EDGE RTS USAGE - MAIN PAGE RTS: Radius Trigger Script Usage

Reformatted by Marc A. Pullen [Fanatic]

Each trigger must be defined with a start and end, referred to as blocks. This includes basically two types of blocks: a block for a map with triggers in that block, and a trigger block, which defines the start and end of an individual trigger.


start_map [mapid]

[mapid] = map name
Specifies the beginning of this map's trigger(s), everything after this will be allocated to that map. This is the start of a map block.

For DOOM use map names like E1M1, DOOM 2 use MAP01 formats for the [mapid].


end_map
Specifies the end of this map's trigger(s).

You must use each to properly define a map's set of trigger(s), with the radius triggers within. This is the end of a map block.


radiustrigger [x] [y] [radius]

[x] - x position on the map
[y] - y position on the map
[radius] - any # greater than zero
Specifies the beginning of a radius trigger, it's position on the map, and it's radius. This is the start of a trigger block.

You can also have a more complex radius trigger. The one above is considered a 2D trigger, because it has no height specified (it can be triggered from the sectors ceiling to the floor it resides in).

Next is a 3D radius trigger:
radiustrigger [x] [y] [radius] [z low] [z high]

[x] - x position on the map
[y] - y position on the map
[radius] - any # greater than zero
[z low] - bottom z height in the map
[z high] - top z height in the map
You can use the 3D radius trigger to define something that is only triggered from a certain height. For example, if using a 3D bridge, you only want this trigger accessible from above the bridge and not below, you can make it spawn at [z low] height of the top of the bridge, and specify the [z high] height by adding 64. This way, you can walk below the bridge and not trigger anything.

In both the 2D and 3D radius trigger, the [radius] is the distance out from the center point of the trigger, being the [x][y] coordinates.


end_radiustrigger
Specifies the end of this radius trigger.

You must use each to properly define a single radius trigger.

Trigger tags: these are entries you can use within a trigger block.


tagged_repeatable [# times] [delay]

[# times] - 0=infinite, or any # greater than zero
[delay] - 0=instant, or any # greater than zero
This causes a trigger to be repeatable, or to loop. If you do not use "tagged_repeatable", the trigger will only occur once.

The delay value is the number of seconds to wait until the trigger begins the next occurrance. But if the value has a trailing `T', then the value is in Tics instead of seconds (in Doom 35 game tics = 1 second).

Examples of the delay:
No delay: 0
1/16 Second: 2T
1/8 Second: 4T
1/4 Second: 0.25 or 9T
1/2 Second: 0.5 or 18T
3/4 Second: 0.75 or 26T
1 Second: 1 or 35T
2 Seconds: 2 or 70T
3 Seconds: 3 or 105T
.
.
5.5 Seconds: 5.5 or 193T
and so on....
So if you have a trigger you want to repeat a total of 5 times at one second intervals:
tagged_repeatable 5 1

tagged_immediate
Forces the trigger to activate immediately. Useful if you want something to happen when the map starts, like an onscreen tip message, or spawning monsters right away.
tagged_independent
Once the trigger is activated it will continue running until all required functions have been completed.


tagged_use
Forces a trigger to only be activated by the player pressing the use key (spacebar) while standing within the radius of the trigger.

Functions & Definitions :
#define [identifier] [value]

[identifier] - CHAR[80]

[value] - thing number from THINGS.DDF
Allows you to define aliases, like in Quake and Quake 2 bindings and advanced config files (like zooms and rocket jumps).

The [identifier] is a text name limited to 80 characters. An example is "CYBERDEMON".

The [value] is a numerical value. In this example, it would be "16" -the thing number in THINGS.DDF.

This way, if you want to spawn a CYBERDEMON, you can use the [identifier] instead of the literal thing number. It reads easier when scripts get big, because it's English and doesn't require referencing to THINGS.DDF for every monster in every trigger.


Basic spawn function:
spawnthing [thingid] [angle]

[thingid] - thing number from THINGS.DDF
[angle] - angle to face on the map
Spawns a thing on the radius triggers center point, and faces it according to the [angle]. Note that spawnthing_ambush can also be used in an identical fashion to spawn a deaf monster. It is also possible to use spawnthing_flash to spawn things using a respawn flash (for a grander entrance).

Advanced spawn function:
spawnthing [thingid] [x] [y] [angle]

[thingid] - thing number from THINGS.DDF
[x] - x position on the map
[y] - y position on the map
[angle] - angle to face on the map
Spawns a thing at the specified [x][y] coordinates, and faces it according to the [angle]. Use the advanced one to spawn something remote of the actual trigger.

Super advanced spawn function:
spawnthing [thingid] [x] [y] [angle] [z] [mlook]

[thingid] - thing number from THINGS.DDF
[x] - x position on the map
[y] - y position on the map
[angle] - angle to face on the map
[z] - z height on the map
[mlook] - mlook angle to spawn the thing at -used for cameras too!
The [mlook] angle used for cameras: "0" is straight forward, "-45" is all the way down, and "45" is all the way up. Use numbers between 45 and -45 to set the angle you want, positive numbers are up, negative numbers are down.

The [mlook] angle used for non-cameras: "0" is straight forward, "-89" is almost straight down, and "89" is almost straight up. Use numbers between 89 and -89 to set the angle you want, positive numbers are up, negative numbers are down. For example, you can set an attack to spawn at the ceiling, like QDOOM's spike or laser shooters, set the [mlook angle] to -35, and it will shoot from the ceiling to the floor at an angle of -35.

NOTE: use the spawnthing function and the [z] spawn height to spawn a thing on an extrafloor. There is no way to set which floor to spawn a monster in a map editor -you must use a spawnthing trigger function for this purpose. The [z] spawn height can be equal to the top of an extrafloor, or just above (if the thing spawned can fall, it will fall on the extrafloor, like Quake does).

Angle examples (from birds eye view) are:
East: 0
NorthEast: 45
North: 90
NorthWest: 135
West: 180 ; W
SouthWest: 225
South: 270
SouthEast: 315

healplayer [amount] [limit]

[amount] - any number greater than zero
[limit] - any number greater than zero and less than MAXHEALTH
When this trigger is active, it gives the player health at [amount], but no more than the [limit].
So if you want to give the player 100 health, but not allow them to get more than 120 (like assuming they just got through a massive fight and have nearly no health), use:
healplayer 100 120
If the player is at 100 health already, they won't receive another 120, but will cap at 120 max health. If you leave out [limit], the parser will default to MAXHEALTH (which is 200).


givearmor [value] [limit]

[value] - any number greater than zero
[limit] - any number greater than zero and less than MAXARMOR
When this trigger is active, it gives the player armor at [amount], but no more than the [limit].

So if you want to give the player 100 ammo, but not allow them to get more than 120 (like assuming they just got through a massive fight and have nearly no armor), use:
givearmor 100 120
If the player is at 100 armor already, they won't receive another 120, but will cap at 120 max armor. If you leave out [limit], the parser will default to MAXARMOR (which is 200).


damageplayer [value]

[value] - any number greater than zero
When this trigger is active, it damages all players that are inside the trigger radius (decreasing health and armour).


exitlevel
When this trigger is activated, it causes the level to end.


gotomap [mapid]

[mapid] = map name
Causes the end of the map screen (a normal end of map trigger), and then calls the next map specified in [mapid]. Useful if you want different exits, like a secret level exit.

For DOOM use map names like E1M1, DOOM 2 use MAP01 formats for the [mapid].

You can use this to return to a map, like you can in HeXen or Quake 2, but the monsters reset (no map states saving).


ondeath [thingid] [threshold]

[thingid] thing number or name from THINGS.DDF.
[threshold] any positive number (optional)
This trigger will not activate until all things of [thingid] are killed/no longer exist on the map. This can be used for special events like a door opening when certain monsters are killed, or spawning a monster when a weapon is picked up.

The threshold value means that the trigger will only be activated when a certain number of the things exist. For example, 2 means that the trigger doesn't activate until all but 2 of the monsters have been killed. The threshold can be omitted, it defaults to 0 which means all the things must be killed or removed from the map.


playsound [sound] {[x] [y]}

[sound] - sound name from SOUNDS.DDF (DS is omitted!)

Optional:
[x] - x position on the map
[y] - y position on the map
Spawns a sound remotely at the optional [x][y] coordinates (if specified), otherwise, spawns the sound at the [x][y] of the radius trigger. Combine with "tagged_repeatable" for a looping sound.


tip "[text]" [displaytime] [sound]

[text] - text to display
[displaytime] - any number greater than zero (optional. defaults to 3)
[sound] - (True/False) (optional, defaults to false)
Displays text on the screen. Use "\n" for a line break, and "\n \n" for an empty line. You are limited to about 80 characters across and 8 lines total (I'm pretty sure). All text is currently centered, but there are plans for allowing alignment.

If the [sound] is set to "true", a sound is played (TINK). You can set it to "FALSE" and use "playsound [sound]" (see previous entry above) to use an alternate (I do :).


skill [num] [respawnmonsters] [fastmonsters]

[num] - 1 through 5
[respawnmonsters] - true/false
[fastmonsters] - true/false
Changes the skill level while in mid-game.
I'm too young to die - 1
Hey, not too rough - 2
Hurt me plenty - 3
Ultra-violence - 4
Nightmare - 5 (should set [respawnmonsters] and [fastmonsters] to "true" for this skill)

sectorv [sector num] [height] [type]

[sector num] - literal sector number in any map editor
[height] - how far the sector is to move
[type] - floor/ceiling
Raises or lowers the referenced sectors floor or ceiling.

Use any map editor to find the sector number that you want to reference.

The height is how far you want the sector to move. Positive numbers move the floor/ceiling up, negative numbers make them move down.

HINT: To get a floor/ceiling to move smoothly, use tagged_repeatable and a low movement value.

For example:
radiustrigger 1480 3400 1000
	// X=1480 
	// Y=3400 
	// RADIUS=1000 -yes it's big
	// START OF THIS RADIUS TRIGGER
tagged_repeatable 64 1 
	// "64" IS 64 REPEATS (TOTAL OF 64 UNIT MOVEMENT UP -SEE "sectorv" SECTION!)
	// "1 1" IS 1/32nd SECOND DELAY BEFORE REPEATING
sectorv 295 1 floor
	// "295" IS THE MAPS SECTOR # I WANT TO ACTIVATE
	// "1" IS THE DISTANCE TO MOVE IT *PER REPEAT* (POSITIVE = UP)
	// "floor" MEANS THE FLOOR IS THE PART THAT WILL MOVE 
end_radiustrigger  
	// END OF THIS RADIUS TRIGGER
When this trigger is activated, sector #295's floor will move up by 1 unit, and since it's "tagged_repeatable", it keeps moving up one unit every second 64 times.


sectorl [sector num] [light change]

[sector num] - literal sector number in any map editor
[light change] - light level to change to (255 max, -255 min)
Changes the light intensity in the specified sector.

For [light change], use positive numbers for brighter, negative numbers for darker.

-255 is the max dark, and 255 is max bright. Zero has no change.


when_appear [1:2:3:4:5:sp:coop:dm]

[1:2:3:4:5:sp:coop:dm] - omit the ones you don't want this trigger to exist on
For example:
when_appear 1:2:sp -only active on skills 1 and 2 in single player only
when_appear 4:5:sp:coop -only active on skills 4 and 5 in single player and coop only
when_appear 1:2:3:4:5:dm -active in death match only, all skill levels

when_appear 1:2:3:4:5:sp:dm:coop -active in all skills, all modes
If you want a trigger to be active in different skills, use two triggers, like if you want a trigger to only be active in skills 1 and 2 single player and skills 4 and 5 in coop, use one trigger for the single player and another for the coop settings, but make the triggers coordinates and other contents identical.


name [name]

[name] - the name of the radius trigger
Names a radius trigger, useful to label a trigger to be turned on or off by another trigger, or for paths. Each trigger in a level should have unique names (when used), but the same name can be re-used in different levels.


enable_script [name]

[name] - the name of the radius trigger to enable
First name a radius trigger, then use another with "enable_script" and put the name of the first script there. When the second trigger is activated, the first will activate as well.


disable_script [name]

[name] - the name of the radius trigger to disable
First ame a radius trigger, then use another with "disable_script" and put the name of the first script there. When the second trigger is activated, the first will deactivate (i.e. immediately stop if it was running).


tagged_disabled

This makes a radius trigger disabled until triggered.
If a trigger is "tagged_disabled", it won't be active intil it's activated. Use "enable_script" and "name" functions for this.


tagged_path [name]

[name] - the name of the radius trigger to target as a path
Specifies that this trigger is actually a node in a path.

Us the above "name [name]" function to name your radius triggers, then use the "tagged_path [next name]" function to create a path to follow. Use the "spawnthing" function in the first trigger, the monster will go to this trigger first, then follow the path based on the "tagged_path" names. Loop them by referencing the last trigger to the first, like this:
start_map MAP01 

radiustrigger -64 800 0 128 128
tagged_immediate
name walk_01
tagged_path walk_02
spawnthing IMP -96 1000 0 0
end_radiustrigger  

radiustrigger 300 800 0 128 128
name walk_02
tagged_path walk_03
end_radiustrigger  

radiustrigger 300 200 0 128 128
name walk_03
tagged_path walk_01
end_radiustrigger  

end_map 
To make them non-looping, omit the last radius trigger's "tagged_path" entry, and the monster will stop there.

NOTE: you must have the PATH_FOLLOW action in the monsters states (e.g. IDLE states) in order for the monster to walk in THINGS.DDF!



onheight [low Z] [high Z] [sector num]
This trigger will only activate when the floor of a sector is between two heights. If no sector number is included, the sector containing the trigger is used.



wait [time]
Makes the trigger pause for the set amount of time before proceeding with the remaining actions in a particular radiustrigger. Can be used to slowly change floors / ceilings or lighting. The time value is either seconds (e.g. 5) or tics (e.g. 70T).



damage_monsters [monster name or ANY] [value]
[monster name or "any"] use a monster name from THINGS.DDF, or "any" (meaning any monster within the active trigger's radius)

[value] any number greater than zero

When this trigger is active, it damages a specific monster from THINGS.DDF, or if "any" is used, it damages any monster within the active trigger. The value controls the amount of damage dished out. NOTE: it will only damage things that have COUNT_AS_KILL or MONSTER in the things special. So you can't damage scenery.



label [name]
[name] text string that can be referenced by the jump function

This is used to label and then jump between parts of a RTS script



jump [label name] [chance to jump]
[label name] name of label to jump to

[chance to jump] optional percentage from 0% (never jump) to 100% (always jump). When omitted, it always jumps.

This specifies the chance that the script will jump to a specified label



sleep
This is like a pause, similar to a wait statement, but lasts until something else wakes it up again. Use it anywhere in your script.



tag [tag number]
[tag number] any positive number

Used to link RTS with a trigger in a map. You must create a special line type in LINES.DDF that uses RADIUS_TRIGGER= ENABLE_TAGGED/DISABLE_TAGGED; (you can either enable or disable with this line type setup).

You then use your map editor to assign the new line type in LINES.DDF to a line in your map, and the tag number in the map will be the [tag number] in your radius script. When the tagged line in your map is triggered, it will activate the radius trigger it's targeting (or deactivate it, when DISABLE_TAGGED is used).



activate_linetype [line type] [tag]
[line type] the line type defined in lines.ddf

[tag] the tag give to your line type in a map editor

Activates a particular line type as if the player had activated it using walk, push or shoot.


Error Codes:

The parser will produce message like this when an error occurs in the script:

Radius Triggers v1.1........

Error: END_MAP with no START_MAP, at line 194.
END_MAP

-= or =-

Radius Triggers v1.1.

Error: Unknown Function, at line 33.
RADIUSTRIGGERED -672 -32 64
In version 1.0 and up, the parser will actually tell you what line it's having a problem with and the code it's choked on -super easy to find your mistake (much easier than DDF :).

Error List:
Unknown Error -will never happen, so don't worry about ever seeing this one.
START_MAP, block not terminated - parser was unable to find the "end_map" command to terminate the current map block.
END_MAP with no START_MAP - pretty obvious, the parser came across a "end_map" but there was no "start_map" previously defined.
RADIUS_TRIGGER, block not terminated - parser found "radiustrigger" or "end_map" instead of "end_radiustrigger".
END_RADIUSTRIGGER with no RADIUS_TRIGGER - parser came across an "end_radiustrigger" but there was no "radiustrigger" to mark the beginning of the trigger block.
Unknown Function - cannot locate the function name.
Parameter is not of integer type - the input is not an integer.
Wrong number of parameters - either too little or too many parameters were passed through to the function.
Invalid number of quotes - either no starting or closing quotes (or neither).
Variable Unknown - has tried to look up a #define declared in one the functions in the defines namespace but was unsuccessful. Will only occur when redefining boolean types.
Function cannot be redefined - an attempt has been made to reuse a function which is allowed only once in a trigger block.
Integer not within range specified - a number was passed to a function which was out of the parameters given range.