FANDOM


IntroductionEdit

Server side Game Scripts (GS) handle the functionality of objects and clients in game. They are saved with the file extenstion ".gs" in the subfolder "standard\objects\scripts". GS are also saved in Map files, when Triggers are used.


Script formatEdit

Blank lines are ignored, any other line must start with a special character:

 # - Comment
 @ - Entry point
 ! - Instruction

When the script is parsed, instructions are appended to the end of one of several linked lists. The last entry point directive determines which list the current instruction is being added to. When something in game triggers an entry point of an object, the game will step through the isntructions in that list and execute them.

 #[comment text] ...
   Ignored, just like a blank line
 @<entry point name> [frequency] | [min_frequency max_frequency]
   See GS Entry Points below for valid entry points.  
   Not all entry points require a frequency (Ignored when unnecessary).
 !<instruction name> <object> [param] ...
   See GS Instruction Dictionary & GS Object Names below for valid commands and parameters. 
   Valid Parameter Types include: 
     * Text: !setstate self idle
     * Integer: !damageradius target 150 500
     * Cvar: !push found #kickX# #kickY# #kickZ#
     * Statement: !if [mycvar>1] @then0


GS Entry PointsEdit

Important Notes: Map trigger scripts can ONLY use the entry @activate.

 Entries relating to Objects state (applies only to Items)
   @activate - Object has been activated (also: Map trigger was actived)
   @active - Object is in activated mode (executed for each frame)
   @idle - Object has been ordered to idle
   @idling - Object is in idle mode (executed for each frame)
   @sleep - Object has been ordered to sleep
   @sleeping - Object is in sleep mode (executed for each frame)
 Entries relating to Objects management (applies only to Items)
   @pickup - Object was picked up on Terrain 
   @given - Object was added to inventory by command !give
   @drop - Object was removed from inventory by command !drop
   @toss - Object was removed from inventory by command !toss
   @attach - Object was attached to Parent by command !attach
   @spawn - Owner of object has spawned or was resurrected
 Entries relating to Usage, Weapons and Damage
   @use - Parent Player used item, or powerup was applied to player
   @fuse - Object fusetime period has expired (fusetime > 0)
   @backfire - Object back-fired (startFuseAtCharge 1)
   @fizzle - Tech Weapon fizzled because Parent has state "lockdownTech 1"
   @impact - Weapon or Projectile has hit something
   @wounded - Object took damage
   @die - Object took fatal damage
   @fire - (not working yet)
   @block - Object has blocked (client-only)
   @blocking - Object is blocking (client-only)
   @levelup - Object advanced a level (client-only)
 Entries relating to AI Objects management
   @walking - Object is walking towards a fixed point
   @chasing - Object is following another object
 Entries relating to GameScript logics
   @then0 .. @then9 - Executed by commands !if and !ifnot


GS Object NamesEdit

  • "self" - Object that is acting
  • "target" - Object that initiated the action
  • "enemy" - Object's current enemy
  • "owner" - Object's owner, if any
  • "link" - Object's link, if any
  • "found" - Object found by last !search
  • "null" - No target (for entries like !exec)


GS Instruction DictionaryEdit

Important Note:

  • Parameters shown between the symbols < > are REQUIRED.
  • Parameters shown between the symbols [ ] are optional.
  • The symbols ( ) mean these parameters are required only if another parameter has been specified.
  • The parameter <target> can take any of the values described in the section above.


Healing/DamageEdit

 !heal <object> <amount>
   Heal object by specified amount.
     If amount < 1.0, the value represents a percentage of full health.
     If amount >= 1.0, the value represents a fixed amount of health.
 !damage <object> <amount> [ignoreArmor]
   Damage object by specified amount.
     If amount < 1.0, the value represents a percentage of full health.
     If amount >= 1.0, the value represents a fixed amount of health.
     If ignoreArmor = 1 (optional), the damage is not shielded by armor.
 !damageradius <object> <radius> <amount> [targetFlag1] [targetFlag2] ...
   If NO flags: Damage everything in radius around object (including object itself).
   If flags: Damage everything flagged in radius around object (excluding object itself).
   Damage is inversely proportional to distance between the object and victim.
   List of valid flags:
     enemy neutral ally unit player npc item building
 !die <object>
   Kill object.
 !revive <object> <healthPercent>
   Resurrect object with specified health percentage (0-1).

Slots/Ammo/Stamina/Gold/Experience/StatesEdit

 !inventory <object> [slot]
   Checks content of player's specified inventory slot.
     If [slot] is not specified, the currently selected slot is used instead.
     Information is returned in Cvars: gs_inventory_name & gs_inventory_count
   Note1: script will error out if <object> is not a player unit.
   Note2: slots are indexed from 0, so slot 1 in-game is slot 0 in-script.
   Example:
     !inventory owner 3
     !exec null "chat Item in slot 3: #gs_inventory_name#"
 !give <object> <objectType> [ammo] [slot]
   Give specified object to player. (ex: human_potion)
     If [ammo] is not specified, value is 1.
     If [slot] is not specified, object is assigned to currently selected slot.
   Also causes the immediate execution of entry @given for that object.
   Note: slots are indexed from 0, so slot 1 in-game is slot 0 in-script.
 !remove <object> [slot]
   Remove the item in specified [slot] of target player's inventory.
     If [slot] is not specified, the currently selected slot is used instead.
   Note1: slots are indexed from 0, so slot 1 in-game is slot 0 in-script.
   Note2: Does not trigger any entry points!
 !giveammo <object> <multiplier> <amount|group|start|full>
   Give ammo for player's ranged weapons.
   The total amount is calculated depending on the last parameter:
     <amount> : Total = current + (multiplier * amount)
     <group>  : Total = current + (multiplier * ammoGroup)
     <start>  : Total = (multiplier * ammoStart)
     <full>   : Total = (multiplier * ammoMax)
   NOTE: While <group>, <start> and <full> are to be written out exactly, 
   "amount" is actually a number specificed instead.
 !givemana <object> <amount>
   Give object the specified amount of mana.
     <amount> always represents a fixed amount.
 !givestamina <object> <amount>
   Give object the specified amount of stamina.
     <amount> always represents a fixed amount.
 !givegold <object> <amount>
   Give object the specified amount of gold.
     <amount> always represents a fixed amount.
 !givegoldradius <object> <radius> <amount> <ally/enemy>
   If flags(for now): Grant gold to allies/enemies in radius around object (excluding
   object itself) and only to clients.
     <amount> always represents a fixed amount.
     <ally/enemy> Relative to the <object> given.
 !giveexp <object> <amount>
   Give object the specified amount of experience.
     <amount> always represents a fixed amount.
   WARNING: The server setting "sv_xp_max_gain" directly affects how high the value 
   of exp gain will be, limiting it to the set % of the next level.
 !giveexpradius <object> <radius> <amount> <ally/enemy>
   If flags(for now): Grant experience to allies/enemies in radius around object 
   (excluding object itself) and only to clients.
     <amount> always represents a fixed amount.
     <ally/enemy> Relative to the <object> given.
   WARNING: The server setting "sv_xp_max_gain" directly affects how high the value of 
   exp gain will be.
 !regenradius <object> <radius> <healamount> <staminaamount> <ammoamount> <targetFlag1> [targetFlag2] ...
   Scan radius around object looking for anything that matches the specified flags.
   The first object detected gets regenarated by the specified amounts.
     If amount < 1.0, the value represents a percentage of maximum stat value.
     If amount >= 1.0, the value represents a fixed amount of the stat value.
   Note: Flags 1st .. 4th correspond to distance from specified object
   List of valid flags:
     enemy neutral ally unit player npc item building 1st 2nd 3rd 4th
 !givestate <object> <stateName> <minDuration> [maxDuration]
   Give specified state to object. (ex: adrenaline)
     If [maxDuration] in msec is not specified, duration is equal to <minDuration>.
     Otherwise, duration is random value in the range (minDuration:maxDuration).
 !givestateradius <object> <radius> <stateName> <minDuration> [maxDuration]
   Give specified state to all valid targets around <object>. (ex: adrenaline)
     If [maxDuration] in msec is not specified, duration is equal to <minDuration>.
     Otherwise, duration is random value in the range (minDuration:maxDuration).
     WARNING: <object> does not receive the state. "Valid" target refers to the target
     flags specified within the ".state" file of that state.
 !hasstate <object> <stateName>
   Check whether the object has the specified state.
   If the object does NOT have the state, the execution of the script breaks at this point. 
 !stateslot <object> <slot>
   Checks content of player's specified state slot.
     Information is returned in Cvar: gs_state_name.
   Example:
     !stateslot owner 15
     !exec null "chat State in slot 15: #gs_state_name#"

See XR State Reference for a list of state attributes.

Players BehaviourEdit

 !goal <object> <player|team|all|#num|$name> <move|object> <x> <y>
   Assign target group a certain goal (move, attack...)
     <player> : only the object is assigned the goal.
     <team>   : object's team is assigned the goal.
     <team0>  : specified team is assigned the goal.
       ...                    ...
     <team4>  : specified team is assigned the goal.
     <all>    : everyone in every team is assigned the goal.
     <#num>   : only object #num is assigned the goal (num can be 0-1024).
     <##cvar#>: same as above, but with object num retrieved from cvar.
     <$name>  : only client with matching name is assigned the goal.
   The nature of the goal depends on the following parameter:
     <move>   : move to location <x> <y>
     <object> : act on nearest object to location <x> <y>
                that object's type & team determines the goal (attack, build...)
 !push <object> <vectX> <vectY> <vectZ>
   Pushes object along specified direction vector (strength is length of vector).
   This force is added on top of the current velocity of that object.
 !pull <object> <speedMult>
   Pulls given object towards acting object (self).
   This force is added on top of the current velocity of that object.
 !physics <object> <gravity|friction|aircontrol|maxvel> <newValue>
   Alters the physics of object.
 !teleport <object> <home|here|link|coords> (<x> <y>)
   Teleport object to a new location defined by the second parameter:
     <home>   : teleport object to team's command centre.
     <here>   : teleport object to location of acting object (aka self).
     <link>   : if object has a linked object in inventory, teleport to that location.
     <coords> : teleport object to location <x> <y>.
 !stun <object> <duration>
   Stun object for a set period of time.
     <duration> represents stun time in msec.
 !stunradius <object> <radius> <duration> <targetFlag1> |targetFlag2| |targetFlag3|
   Stun units in radius around object corresponding to given targetFlags (excluding object itself).
     <duration> represents stun time in msec.
   List of valid flags:
     enemy neutral ally

Items BehaviourEdit

 !drop <object> <angle> <radius>
   Drop object from inventory to precise location on the ground.
   <angle> & <radius> are relative to the player's current position and angle.
   The object remains "linked" to the player who dropped it (ex: see teleport).
   Also causes the immediate execution of entry @drop.
 !toss <object> <velocity> <gravity>
   Toss object from inventory to the ground.
   The object remains "linked" to the player who tossed it (ex: see teleport).
   Also causes the immediate execution of entry @toss.
 !attach <object>
   Allocate model, and attach it to specified object (ex: sacrifice).
   Also causes the immediate execution of entry @attach.
 !destabilize <object> <radius> <targetFlag1> [targetFlag2] ...
   Kills all "volatile" objects matching the flags within specified radius of object. 
   Volatile objects have the field isvolatile=1 in their ".object" definition.
   List of valid flags:
     enemy neutral ally unit item building
 !scan <object> <radius> <triggerState> <targetFlag1> [targetFlag2] ...
   Scan radius around object looking for anything that matches the specified flags.
   When an object is detected, <object> switches to the state <triggerState>.
   Note: Flags 1st .. 4th correspond to distance from specified object.
   List of valid flags:
     enemy neutral ally unit player npc item building 1st 2nd 3rd 4th
   List of valid states:
     sleep idle activate
 !search <object> <radius> <targetFlag1> [targetFlag2] ...
   Scan radius around object looking for anything that matches the specified flags.
   When an object is detected, the GS Target "found" is updated to point to it.
   Note: Flags 1st .. 4th correspond to distance from specified object
   List of valid flags:
     enemy neutral ally unit player npc item building 1st 2nd 3rd 4th
   Example:
     !search self 70 unit ally neutral enemy 1st
     !exec found "set kickX [300*gs_object_dirx]"
     !exec found "set kickY [300*gs_object_diry]"
     !exec found "set kickZ [100]"
     !push found #kickX# #kickY# #kickZ#
     !notify found player "^rU've been Kicked in the Ass!"

EventsEdit

 !exec <object> [client] "command"
   Executes the console command specified between brackets on server.
   The optional use of "client" allows the execution to happen on client instead.
   Note: Script files (*.cfg) can be executed with the command: "exec script.cfg"
 !notify <object> <player|team|all> "message"
   Send notification in chat window to selected group of clients.
     <player> : only the object receives the message.
     <team>   : object's team receives the message.
     <all>    : everyone in every team receives the message.
 !spawnobject <object> <objectType> <objectTeam> <hostile|neutral> <nearby|coords> (<x><y>)
   Spawns a new object at the specified location.
   If object is an item, its ".object" file must have "set canPickup 1".
     <objectType> : type of object to be created (ex: npc_chiprel).
     <objectTeam> : team this object will belong to (0 to 4).
     <hostile|neutral> : behaviour towards <object> (only valid if new object is npc).
     <nearby> : spawn new object within melee range of <object>.
     <coords> : spawn new object at location <x> <y>.
   WARNING: Do NOT under any circumstance spawn a SH/Lair (command center)! Never!
 !playsoundradius <object> <radius> <sound>
   Plays a sound for all clients in radius around target.
     <sound> is the path+filename relative to the "game" folder.
       Example: /sound/human/buildings/construction.ogg
 !changeunit <object> <unitType>
   Transform target object (client-only) into given unit. (ex: npc_chiprel)
   Also causes the immediate execution of entry @spawn for that object.

Note: The !exec function is very powerful, it allows:

  • The execution of console commands.
  • The modification of any cvar value.
  • The execution of custom scripts with the command: !exec null "exec script.cfg"

For the full list of console commands see: Server Commands

LogicsEdit

 !if <object> <condition> <entry>
   Test whether the object meets the specified condition.
   If the condition IS met, the specified entry is executed.
   Note: Conditions such as ally/ennemy are relative to the acting object (aka self).
   List of valid conditions:
     enemy neutral ally character siege npc building item corpse
     condition can also be a statement, such as: [myCvar1>=myCvar2]
   List of valid entries:
     @then0 ... @then9
   Example:
     !if null [bot_index==0] @then0
 !ifnot <object> <condition> <entry>
   Test whether the object meets the specified condition.
   If the condition IS NOT met, the specified entry is executed.
   Note: Conditions such as ally/ennemy are relative to the acting object (aka self).
   List of valid conditions:
     enemy neutral ally character siege npc building item corpse
     condition can also be a statement, such as: [_myCvar1>=_myCvar2]
   List of valid entries:
     @then0 ... @then9
   Example:
     !if null [_bot_index==0] @then0
 !test <object> <condition>
   Test whether the object meets the specified condition.
   If the condition IS NOT met, the execution of the script breaks at this point.
   Note: Conditions such as ally/ennemy are relative to the acting object (aka self).
   List of valid conditions:
     enemy neutral ally character siege npc corpse building item
 !testnot <object> <condition> [param] [...]
   Test whether the object meets the specified condition.
   If the condition IS met, the execution of the script breaks at this point.
   Note: Conditions such as ally/ennemy are relative to the acting object (aka self).
   List of valid conditions:
     enemy neutral ally character siege npc corpse building item
 !setstate <object> <state> [<duration> <nextState>]
   Switch object to specified <state>.
   If optional <duration> in msec is specified, switch to <nextState> afterwards.
   List of valid states:
     sleep idle activate
 !delay <object> <duration>
   Allows a delay in msec before switching to the first state specified in "setstate".
   The "delay" command must be written AFTER the "setstate" command in the script.


GS Internal CvarsEdit

Whenever a GS is executed, the engine automatically updates the content of these Cvars.
These can be used as parameters to any instruction (ex: #gs_object_mana#).

 Object Info: Information about the specified object.
   * gs_object_id: Index of object (between 1 and 128 if object is a player)
   * gs_object_nick: Nickname of object (only valid if object is a player)
   * gs_object_name: Name of object (ex: human_nomad, beast_lair...)
   * gs_object_type: Type of object (client, npc, item, building)
   * gs_object_team: Team the object belongs to (0, 1, 2, 3 or 4)
   * gs_object_posx, gs_object_posy, gs_object_posz: Location of object
   * gs_object_dirx, gs_object_diry, gs_object_dirz: Orientation vector of object
   * gs_object_scale: Scale of object
   * gs_object_mana, gs_object_manapercent, gs_object_manamax: Object's mana
   * gs_object_health, gs_object_healthpercent, gs_object_healthmax: Object's health
 Parent Info: Only valid for Triggers. Information about Trigger's Parent Object.
   * gs_parent_id: Index of object (between 1 and 128 if object is a player)
   * gs_parent_posx, gs_parent_posy, gs_parent_posz: Location of object
   * gs_parent_dirx, gs_parent_diry, gs_parent_dirz: Orientation vector of object
   * gs_parent_scale: Scale of object
 Game Info: General Information about Game.
   * gs_game_time.
   * gs_game_status.
   * gs_game_status_end.
   * gs_team1_resource1 .. gs_team4_resource5.
 Transmitted Info: These variables can be modified by GS instructions.
 The value is then automatically transmitted to Clients.
   * gs_transmit1 .. gs_transmit9.
 For example, these variables can be used to refresh custom GUI Information.


Example of UseEdit

In this example, a "psphere" Map Trigger is looking for buildings being constructed inside the sphere.
When a Team completes the construction of a building, we want the Trigger to execute a GS that increments a variable telling us how many buildings that team has placed within the sphere.

The following script would do the job:

 @activate
 !exec target "inc _buildings_team#gs_object_team# 1"

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.