Introduction[]
Map Triggers are a powerful tool for designing "scenario" and "events" based maps.
They allow the creation of space/time events, triggered by player / commander / npc actions, and causing the execution of custom Game Scripts (GS).
The Logics behind triggers work as follow:
- The Trigger performs a certain test, either continuously or intermitently.
- When this test becomes true, the trigger executes a Game Script.
- If the Trigger was designed to run once, it is removed, otherwise it carries on testing as before.
Examples of Maps using Triggers:
- The map's objective is to build gars/subs on both hills north of the map.
- The command centers cannot be damaged, and mines never deplete.
The map also features:
- A central hill with bushes that contain "surprises". (players can get on this hill using the jumppad or teleporter facing their base).
- A platform between the hills north of the map, with "ejectors" on its sides (and a "surprise" in the bush at the bottom)
- A redstone mine south of the map, standing on an "icerink".
Triggers Interface[]
The Triggers interface comprises 2 main panels:
- Scripts Panel: Used to add/modify custom Game Scripts
- Triggers Panel: Used to add/modify Map Triggers.
Scripts Panel[]
Use the Scripts Panel to add your own Game Scripts (GS) to the Map. The editor features a library of templates, to help you getting started with GS. A comprehensive description of GS scripting is available on the wiki: Script_Triggers
GS can be used for a wide variety of actions:
- Give something (object, mana, ammo, health...) to the object that activated the Trigger.
- Deal damage to or around this object.
- Temporarily alter the physics of a client (jumppads/ejectors/teleporters).
- Create/Modify server cvars. Example -> !exec null "set sv_minesUnlimited 1" <-makes mines unlimited on that map.
- Run server side commands. Example -> !exec null "endgame 1" <- ends the game with team 1 victorious (see Server_Commands).
- Run client side commands, like "special" visual/sound effects.
Important Notes:
- The first line of a Map GS should always be: @activate
- Do not attempt to add other entries (@ symbol), as they will not be taken into account.
- The <target> parameter should be either "target" (the object that activated the Trigger) or "null". Other values will not work.
Triggers Panel[]
Once you have added your Game Scripts, you can now create the Triggers that will cause their execution.
A Trigger performs a certain Test, either continuously or intermitently. When this test becomes valid, the Trigger tells the server to execute the Game Script that is linked to it. If the trigger was designed to be run once it is deleted, otherwise it carries on performing the test again.
There are 5 different types of Triggers:
- aabox: Axis-Aligned Box (space)
- aaplane: Axis-Aligned Plane (space)
- psphere: Perfect Sphere (space)
- interval: Triggers at regular intervals (time)
- condition: Triggers when all the specified conditions are true (logic)
Each Trigger has a series of flags that can be assigned to it. These flags determine what type of objects can trigger it, whether the trigger should be triggered only once...
aabox Trigger[]
Box aligned to the (X,Y,Z) axis of the editor:
- Xpos, Ypos, Zpos define the position of the box.
- Length, Width, Height define the dimensions of the box.
Flag Options:
- once: Use this flag to activate the Trigger only once.
- obj_client, obj_npc, obj_item, obj_building: Type of objects that can activate the Trigger. Several types can be specified in a single Trigger.
- onEnter: Trigger activates when a compatible object enters inside the volume of the box.
- onInside: Trigger is activated as long as a compatible object is inside the box. WARNING: This causes the script to be executed for each server frame!
- onLeave: Trigger activates when a compatible object leaves the volume of the box.
Other Parameters:
- Restrict: Can be used to limit the trigger to very specific objects. Example of list: human_nomad,beast_scavenger (Note: do not use white spaces between object names, only commas)
- Script: Specify the Game Script to be excecuted when the Trigger activates.
aaplane Trigger[]
Plane aligned with 2 of the (X,Y,Z) axis of the editor:
- Axis: X, Y or Z, axis with which the plane is NOT aligned.
- Offset: Position of plane from zero position along the axis defined above.
- Invert: Decides whether activation happens when objects are either above or underneath the plane (value is 0 or 1).
Flag Options:
- once: Use this flag to activate the Trigger only once.
- obj_client, obj_npc, obj_item, obj_building: Type of objects that can activate the Trigger. Several types can be specified in a single Trigger.
- onEnter: Trigger activates when a compatible object enters inside the plane.
- onInside: Trigger is activated as long as a compatible object is inside the plane. WARNING: This causes the script to be executed for each server frame!
- onLeave: Trigger activates when a compatible object leaves the plane.
Other Parameters:
- Restrict: Can be used to limit the trigger to very specific objects. Example of list: human_nomad,beast_scavenger (Note: do not use white spaces between object names, only commas)
- Script: Specify the Game Script to be excecuted when the Trigger activates.
psphere Trigger[]
Perfect Sphere Trigger:
- Xpos, Ypos, Zpos define the position of the sphere.
- Radius defines the dimension of the sphere.
Flag Options:
- once: Use this flag to activate the Trigger only once.
- obj_client, obj_npc, obj_item, obj_building: Type of objects that can activate the Trigger. Several types can be specified in a single Trigger.
- onEnter: Trigger activates when a compatible object enters inside the volume of the sphere.
- onInside: Trigger is activated as long as a compatible object is inside the sphere. WARNING: This causes the script to be executed for each server frame!
- onLeave: Trigger activates when a compatible object leaves the volume of the sphere.
Other Parameters:
- Restrict: Can be used to limit the trigger to very specific objects. Example of list: human_nomad,beast_scavenger (Note: do not use white spaces between object names, only commas)
- Script: Specify the Game Script to be excecuted when the Trigger activates.
interval Trigger[]
Interval Triggers are automatically activated at regular intervals:
- If an "obj_***" flag is used, the trigger will run the specified script for every existing object of that type.
- If the "event" flag is used instead, the trigger will run only one instance of the specified script, and then wait for the next activation time.
Interval parameters:
- Min: Time between activations of the Trigger (in msec).
- Max: If specified, the time between activations will randomly vary in the range [Min:Max].
Flag Options:
- once: Use this flag to activate the Trigger only once.
- event: Only runs one instance of the script, with no particular target.
- obj_client, obj_npc, obj_item, obj_building: Objects affected by the activation. Several types can be specified in a single Trigger.
Other Parameters:
- Restrict: Can be used to limit the trigger to very specific objects. Example of list: human_nomad,beast_scavenger (Note: do not use white spaces between object names, only commas)
- Script: Specify the Game Script to be excecuted when the Trigger activates.
condition Trigger[]
Condition Triggers are automatically activated when ALL the specified conditions are TRUE.
- If an "obj_***" flag is used, the trigger will run the specified script for every existing object of that type.
- If the "event" flag is used instead, the trigger will run only one instance of the specified script.
Condition parameters: Each condition must be a comparison of 2 values, inside the symbols []. Important: Do not use Whitespaces. Examples:
- [_myCvar==1]
- [_myCvar1>_myCvar2]
Flag Options:
- once: Use this flag to activate the Trigger only once.
- event: Only runs one instance of the script, with no particular target.
- obj_client, obj_npc, obj_item, obj_building: Objects affected by the activation. Several types can be specified in a single Trigger.
Other Parameters:
- Restrict: Can be used to limit the trigger to very specific objects. Example of list: human_nomad,beast_scavenger (Note: do not use white spaces between object names, only commas)
- Script: Specify the Game Script to be excecuted when the Trigger activates.
Tutorials[]
Here are some example of the things you can do with Triggers.
All these examples are taken from the map xr_triggers.
Physics Tricks[]
Jumppad[]
- Paint a Tile on the terrain with a different texture.
- Create a script called jumppad.gs, and enter the text shown.
- Place an aabox Trigger over the Tile, and enter the flags shown.
NOTE: The flag "onInside" means the negative gravity effect is applied for each frame that the unit is within the box, producing a progressive acceleration effect!
Teleporter[]
- Paint a Tile on the terrain with a different texture.
- Create a script called teleport.gs, and enter the text shown (You can replace 1500 1500 with any other X Y coordinate on the map).
- Place an aabox Trigger over the Tile, and enter the flags shown.
NOTE: Always use the flag "onEnter" or "onLeave" with teleporters. "onInside" will produce undesired effects.
Ejector[]
- Create a script called eject.gs, and enter the text shown (The X Y Z values define the direction and stength of the push).
- Place an aabox Trigger near a ledge or cliff, and enter the flags shown.
NOTE: The flag "onEnter" means the ejection will happen in a single frame, producing the effect of being slapped!
Ice Rink[]
- Create a flat area on the map, then either paint it white or use the "iceplane" object.
- Create a script called ice.gs, and enter the text shown.
- Place an aabox Trigger that covers the flat area, and enter the flags shown.
NOTE: Creating a thin box means that players can stop squidding when they jump. If you want to prevent this, you can make the box as high as the height of a jump.
Bush Tricks[]
Goodies Bush[]
- Place a bush on the map.
- Create a script, and enter the text shown.
- Place a pshere Trigger around the bush, and enter the flags shown.
NOTE: Examples of scripts for your Goodies Bush: !heal !damage !die !give !giveammo !givemana !givestamina !givestate. In some cases (like heal or damage) it is better to use the flag "onInside" to produce a constant effect while object is in the bush.
Ambush Bush: Hidden NPCs![]
- Place a large bush on the map.
- Create a script, and enter the text shown.
- Place an aabox Trigger around the bush, and enter the flags shown.
NOTE: It is possible to make the npcs hostile or neutral to the object that activated the trigger. As shown in this example, it is also possible to automatically give the goal of attacking a npc that was spawned. To automatically spawn the npcs near the bush use "near" instead of "coords".
Chat Notifications[]
Game Start Message
- Create a script, and enter the text shown.
- Create an interval Trigger, and enter the parameters & flags shown.
NOTE: The 5000ms delay allows enough time for all clients to reload the map and start the game. Using a lower value could mean that some clients will not receive the message. REMEMBER to add the flag "once", otherwise your start message will become a spam message!
Chat Spam Message
- Create a script, and enter the text shown.
- Create an interval Trigger, and enter the parameters & flags shown.
NOTE: Enter an interval sufficiently large to avoid annoying players! Spam message can be useful to remind players of the map's objectives.
Special Events[]
Adrenaline Boost Event
- Create a script called adrenaline.gs, and enter the text shown.
- Create an interval Trigger, and enter the parameters & flags shown.
NOTE: You can randomize the interval between instances of the event by entering different Min and Max values (in msec)! Any of the following script functions are suitable for special events: !heal !damage !give !giveammo !givemana !givestamina !givestate.
Map Objectives[]
Adding Map Ojectives takes a little thinking and planning before you add the Triggers.
It is advised that you first draw a logic tree on a piece of paper, and make sure that your logics have no loop holes or exploits.
This Tutorial shows how to create a Map with the following Objective:
- First Team to construct garrisons or sublairs on the 2 hills north of the map wins.
Logics Tree[]
2 psphere Triggers will be placed on each Hill:
- One checking for gars/subs being constructed (flag "onEnter").
- The other checking for gars/subs being destroyed (flag "onLeave").
They will execute scripts that increment/decrement the values of 4 Cvars:
- _hill1_team1
- _hill1_team2
- _hill2_team1
- _hill2_team2
This means we also need a "startup" trigger that creates the Cvars and makes them equal to 0.
Finally, 2 condition Triggers will be in charge of monitoring the Cvars:
- Trigger 1: if [_hill1_team1>0] and [_hill2_team1>0] then execute "Victory Team 1" Script.
- Trigger 2: if [_hill1_team2>0] and [_hill2_team2>0] then execute "Victory Team 2" Script.
Logics Check[]
- Make sure that command centers cannot take damage (startup script: set sv_baseDamage 0).
- Once several buildings have been built & destroyed, redstone will run out and commanders may not have enough to build the final gar/sub. So make sure that mines never run out (startup script: set sv_mineDepletion 0).
Triggers Implementation[]
Startup Trigger:
Initialises our custom Cvars when the game starts, and sets some important server settings.
- Create a script called startup.gs, and enter the text shown.
- Create an interval Trigger, and enter the parameters & flags shown.
NOTE: Min value 1 ensures that the Trigger will activate during the first server frame, but do not enter 0.
REMEMBER: Use the "once" flag, otherwise the Cvars will be zeroed for every server frame!
Construction Triggers:
- Create 1 script for each hill, and enter the text shown (use hill1 and hill2).
- Place a psphere Trigger on top of each hill, and enter the flags shown. Enter the following text in Restrict: "human_garrison,beast_sublair" (no whitespaces). Finally, link to the correct script.
NOTE: The Cvar gs_object_team tells us which Team the building that activated the trigger belongs to (see GS Internal Cvars for more info).
Destruction Triggers:
- Create 1 script for each hill, and enter the text shown (use hill1 and hill2).
- Place a psphere Trigger on top of each hill, and enter the flags shown. Enter the following text in Restrict: "human_garrison,beast_sublair" (no whitespaces). Finally, link to the correct script.
NOTE: The Cvar gs_object_team tells us which Team the building that activated the trigger belongs to (see GS Internal Cvars for more info).
Victory Triggers:
Condition Triggers that monitor the values of the hills Cvars, until one Team wins.
- Create 1 victory Script for each team, and enter the text shown (use 1 and 2).
- Create 1 condition Trigger for each team, and enter the flags shown. The conditions should be: [_hill1_team1>0] and [_hill2_team1>0] for the first Trigger, and [_hill1_team2>0] and [_hill2_team2>0] for the second Trigger. Finally, link to the correct script.