Lua:info ff script

Introduction

An info_ff_script is a point-based scriptable entity. Unlike most Source entities, which represent one type of object and have predetermined behavior, the scriptability behind this entity makes it extremely flexibile.

info_ff_script entities represent items that can affect, and be affected by players. Such items might be the flags in a CTF map, or the armor, health and ammo packs in a respawn room.

These entities are placed in a map editor, such as Hammer, and must be given a name in order to function correctly. This name will be used to link it into the map's corresponding Lua file. So, whenever you put a named info_ff_script entity in your map, the game attempts to find a correspondingly named function in mapname.lua.

FF includes a number of pre-existing game modes that require very little work to implement in your own maps--that is, assuming your map's gameplay is similar enough to one of these templates. You'll simply need to add the appropriate entities, give them the proper names, and you're all set. More on that can be found by looking at the available map templates.

Example

Let's assume you don't want to use one of FF's pre-existing base items, and you just want to make your own. For the sake of the example let's say we're setting up our own flag as a learning experience. First, put two info_ff_script entities in your map, and give them the names: myfirstflag and mysecondflag. Now, create a new text file, and save the file as yourmapname.lua.

So far, we don't have much of anything. We'll need to let Lua know that these entities are in our map. As you might expect, there's other options you can specify here, but this is our first script so we're going to keep it simple. This is how we'd get it started in our previously created Lua file.

-- This is my first base flag!
baseflag = info_ff_script:new({
       name = "base flag",
       model = "models/flag/flag.mdl",
       modelskin = 1
})

You're probably noticing that nothing in the above bit of Lua has anything directly related to the two named entities you put in your map. We're creating a new info_ff_script object in Lua, and setting some default parameters. For our example, the model won't be changing, but we have two flags and we're going to easily change it's name and skin. This baseflag is our blank that we'll copy and modify to create other team-specific flags that are sitting in our map.

--We're extending our baseflag!
myfirstflag = baseflag:new({
       name = "Flag one",
       modelskin = 2
})

Any functions and variables we define in baseflag will be inherited by those entities which use it as a base. We can redefine functions and variables in the derived entites, to override the basic functionality.

Functions & Events

info_ff_scripts have various functions and events that handle specific behavior of the entity, or provide you information that may be useful elsewhere in your scripting.

Access to events is typically in the following format:

function item:methodname( parameters )
  --What to do when this method is called
  --return anything, if necessary
end

Obviously, different methods will accept different parameters. Some methods may not take any parameters, or may not return any values. All of the passed parameters, returned values and examples of usage can be found for all of the info_ff_script methods in the following links.

"On" Events

These callbacks are available to detect when certain events happen to the info_ff_script.

• ondrop( owner_entity )--The flag is dropped, either intentionally or by death.
• onloseitem( owner_entity )--The item is taken from the player for any reason.
• onreturn()--The flag returns to its origin.
• onownerdie( owner_entity )--A player dies while holding the item.
• onownerforcerespawn( owner_entity )--The player is forced to respawn while holding the item.
• ownercloak( owner_entity )--A spy activates his cloak while holding the item. NOTE: This one doesn't start with "on".

Other Events

• dropitemcmd(owner_entity)--The player holding the item presses the dropitems key.
• touch( player_entity )--The info_ff_script is touched by a player.
• precache()--Called on each info_ff_script when the map is loaded, but before it starts. See Lua:precache.
• materialize()--Called when an item respawns.

Options

• dropatspawn()--Return true to make the object drop to the ground when the map loads. Return false to leave it floating where it was placed in Hammer.
• hasanimation()--Return true if the model used is animated.
• usephysics()--Return true for dropped items to act as physics props. Default behavior is for the item to stop when it hits the ground.

Functions can be sent to an info_ff_script whenever you have a reference to a particular entity.

-- find the flag and cast it to an info_ff_script
local flag = GetInfoScriptByName("redflag")
     -- Make sure flag isn't nil
     if flag then
          -- check if the player is carrying the flag
          if player:HasItem(flag:GetName()) then
		-- return the flag
          	flag:Return()
          end     
     end

Attachment Functions

These functions can be used to change the offset by which an item is attached to a player. These offsets are relative to the player's absolute origin.

• attachoffsetforward
• attachoffsetright
• attachoffsetup

Get Functions

Get functions return some information. Information you can use.

• Info_ff_script:GetAngles()--Returns an orientation array. (p,y,r, I believe)
• Info_ff_script:GetOrigin()--Returns a location array. (x,y,z)
• Info_ff_script:GetName()--Returns a string containing the name of the info_ff_script.

Set Functions

These functions change some property of the info_ff_script.

• SetAngles(angles) Turns the item to a specific angle.
• SetModel(string) Sets the model of the item. Remember to precache.
• SetOrigin(origin) Moves the item to a specific spot on the map.
• SetSkin(int) Changes the skin of the model.
• SetStartAngles(angles) Sets the orientation of the item for when it respawns.
• SetOrigin(origin) Sets the location of the item for when it respawns.

State Checking Functions

These all return true or false. You'll generally use them in a conditional statement.

• IsActive
• IsCarried
• IsDropped
• IsInactive
• IsRemoved
• IsReturned

Misc. Functions

• addnotouch() Defined in base_teamplay. Default behavior is to prevent the player from picking up the flag for 2 seconds after dropping it. Disabling this behavior will prevent players from being able to throw the flag at all--or rather, they will throw it, and pick it up an instant later.
• new({collection}) creates a new type of info_ff_script. See Lua:info_ff_script#Example
• Drop(FLAG_RETURN_TIME, FLAG_THROW_SPEED) Causes the player to throw/drop the flag.
• Pickup(player) Causes the specified player to carry this item.
• Respawn(int) Causes the item to disappear, and reappear after a specified number of seconds.
• Return() Causes the item to return to its starting point.
• EmitSound(String) Causes the item to make a sound.