Traps and Triggers plus assorted other scripts

[67418ae5b6b9aZygo]

Traps, Triggers and Selected other Scripts

Traps and triggers are how many of the object processes and effects are handled by SS2. They are a subset of scripts, which control how pretty much every object you interact with behaves with respect to you. To properly use triggers and traps it is necessary to know a bit about how the link system works in SS2.

Switchlinks are the mainstay of the system, they send two basic message types with many scripts having alternative functions depending on whether they receive the 'TurnOn' or the 'TurnOff' signal. Most sent signals are TurnOn by default, e.g. from general buttons, certain Rooms, card slots or keypads. If you want a TurnOff signal there are two primary ways to get one. The first is to use an Inverter (in the Traps -> Filters/Routers hierarchy; TrapInvert is the script name) which flips a signal from On to Off (or vice versa if the signal is already TurnOff) then passes the TurnOff along any Switchlinks it has. The second is to use a script object that generates TurnOffs. For example, the 'TwoStateButton' script on a button will make a button's signal type alternate On/Off as it is pushed. Doors also send a TurnOff when closing, and a TurnOn when opening.

Please note the difference between an object being 'destroyed' and being 'slain' for certain traps, an object which is destroyed is simply removed from the level. An object which is slain is killed by the engine. If you destroy an AI or a junction box it will disappear, if you slay it it will die and leave its corpse.

In the list below object names the script are on in the default gamesys are specified in brackets, when the script should be added via S -> Script to an existing concrete object the brackets are left empty. They're in roughly alphabetical order, except for the section on other useful scripts at the end.

TrapDelay (Trigger Delay)
Effect: Relays a signal after a delay. Signal type (on/off) is retained. Set the delay time with the Script -> Delay Time property. Can also be used to send a looping signal by sending a switchlink to itself.

TriggerDestroy ()
Effect: Sends out a TurnOn message when the object it is placed on is destroyed. Note: while this Script has a named object type it should always be placed on the object to be destroyed. Using the TriggerDestroy object is pointless in most cases.Very useful if, for example, you want the game to end when SHODAN dies...

TriggerDamage ()
Effect: As with TriggerDestroy, but triggers links from it if the object is damaged.

TrapDestroyer (Destroy Trap)
Effect: *Destroys* every object that it has a SwitchLink to. If you want to *slay* something rather than destroy it use TrapSlayer instead.

TriggerEcology (Ecology)
Effect: Monitors the quantity of a set of objects in the level, and sends out messages when it detects a deficiency. Every N seconds (set by the “period” field) it counts the number of objects in the world with a Script -> EcoType property value matching the EcoType set on the trap. If that is below the minimum count, the trap will send out a TurnOn message. If the number is below the maximum value, but above the minimum, then there is a 1 in N chance (set by the “random” field) that it will send out a message. If the count is equal to or above the maximum value, it is guaranteed to not send out a message. Note that while this is generally used for controlling the respawn of monsters it can be used for controlling the spawn of any other object as well.

If this trigger is linked up to a camera alert system and receives an “Alarm” message then it goes into alert mode, and if it receives a “Reset” message from a Security Computer it will return to normal. When in alarm mode, the trigger returns to normal mode after N seconds (set by the recovery field), and will send out Reset messages accordingly. The minimum count, maximum count, randomness, and recovery can be set individually for each mode, normal and alerted. All of those values, as well as the checking period, are set in the Script -> Ecology property.

Example: Min set to 1, Max set to 3, Random set to 5 and Period set to 30, and EcoType set to 100. This means that every 30 seconds the ecology queries how many object in the level have the Ecotype 100 property. If there are 0 objects with it the Ecology fires. If there are 1 or 2 objects with it there is a 20% (1/5) chance that it will fire. If there are 3 objects with EcoType 100 then it will definitely not fire.

Usually used in conjunction with MonsterGen traps (TrapSpawn) to control respawning, or spawning via alarm- but does not have to be used that way.

TrapEmail (EmailTrap)
Effect: Add an email to the player’s PDA, and immediately play it, but do not bring up the PDA. Which email is set through the Logs -> Deck properties. Only the email sub-section of the property is used, and only one email can be sent per trap (even though extra flags *can* be set). No effect if the player already has the email.

TrapEXP (Experience Trap)
Effect: Gives the player a number of experience points set by the Gamesys -> Exp property. Frequently used in game to reward the player for performing tasks. NB, you almost certainly want to make sure this trap fires only once to stop XP farming, or use the alternative TrapEXPOnce script.

TrapGravity ()
Effect: Controls gravity on an object. Good for making things fall or be nonphysical. Should usually be used by adding this script to the otherwise normal object in the world. TurnOn signals set gravity to 100% and TurnOff sets it to zero. Only works on Sphere type physics objects as OBBs have controls set.

TrapInverter (Inverter)
Effect: Reverses the type of a TurnOn / TurnOff message. A TurnOn becomes TurnOff, and vice versa.

TrapLog (LogTrap)
This will autoplay a *log* like an email, and is different from the script on the physical Log objects (LogDiscScript). For details see TrapEmail

TrapMedia/ TrapCutscene
Look interesting, but exist in gamesys only, not the osm itself. Defunct.

TrapMessage (Message Trap)
Effect: Sends a message to the status line. The text of the message is controlled by the Script -> Use Message property and Usemsg.str*. Note that this script can be put on a trap that is already doing other stuff, to save yourself an object.

*If you use a string that does not exist in usemsg.str you do not have to add it to usemsg,str, e.g. Use Message -> blah:"This is random gibberish" would work without being added to usemsg.str, but any alterations to existing strings do have to be altered, e.g. closed:"Hello" would still print "Access denied.", not "Hello" unless you altered or removed the relevant 'closed' entry in the usemsg file.

TrapMetapropByList (Metaprop List Trap)
Effect: Adds (TurnOn) or removes (TurnOff) a metaproperty from an object or set of objects, using Script -> Objlist Args to set the objects affected and Script -> Metaprop Type to set the metaprop. The objlist args may be a name or an object number, and may be directed at multiple objects using a comma separator, or an entire archetype using @ (e.g. @rumblers affects all rumblers in a level). The tilde ~ can be used to exclude objects from the effect of an @, so "@hybrids, ~Rumblers" will affect all grunts and monkeys in level, but not any rumblers.

TriggerMulti (Multi Trigger)
Effect: This is a trigger that only goes off when it has received a TurnOn message from every object that is SwitchLinked to it. So if for example you wanted something to happen once four items had been destroyed you could put a TriggerDestroy on the four objects, and switchlink each to a multitrigger. Once all four objects are destroyed and have sent their signals any switchlinks from the multitrigger are fired.

TrapNewTripwire (New Tripwire)
Effect: This is a trap which is activated by objects entering its physical space. Exactly how it operates is controlled by flags set in the Script > Trap Control Flags property.

• Enter: Sends out a TurnOn message when a physics object enters the space of the tripwire.
  
• Exit: Sends out a TurnOff message when a physics object exits the space of the tripwire.
• Mono: Tracking information is sent to the monolog when the tripwire is operating.
• Once: The tripwire will only ever send out one message (TurnOn or TurnOff), destroying itself after sending that one message.
• Invert: Reverses any message coming out of the tripwire, so for example, entering the tripwire will send out a TurnOff instead of a TurnOn.
• Player: Only activates on the presence of the player object. Use if you don't want any wandering AI to trigger the trap. WARNING: If the tripwire is linked to a door, this flag will be ignored.

There are other variants of tripwire script, but this is the most reliable and well documented one. This object is particularly prone to the apparent vs physical scale problem; if you find things wandering through the tripwire without triggering it, check its physics dimensions.

TrapOffFilter (OffFilter)
Effect: Filters out all messages other than TurnOff messages.

TrapOnFilter (OnFilter)
Effect: Filters out all messages other than TurnOn messages.

TrapQuestbit (QB Trigger)
Effect: Checks a specified set of questbits, and sends out a TurnOn message along each if that questbit in non-zero, or a TurnOff if it is zero. This check is made when the level is loaded. Each Questbit link coming off of the trap is checked, and specified which questbit is to be checked in the data of the link.

TrapQuestbitSimple (Simple QB Trigger)
Effect: Checks the questbit specified by QB Name when its value changes and upon level entry. When the QB value is higher than QB Val (or 0 if not specified) it sends TurnOn to all its switchlinks, then destroys itself.

TrapQBFilter (QB Filter)
Effect: Compares the value of a questbit specified by QB Name with QB Val. If the QB is higher than QB Val, the script acts as a router, passing the message through its switchlinks (otherwise the message is blocked). If QB Val is not provided, the QB is compared with 0, e.g. any non-zero value in the QB will allow messages to pass.

Pseudocode: IF QB Name value > QB Val (0 if not provided) THEN pass message

TrapQBFilterOnce ()
Effect: Identical to TrapQBFilter, but will only ever activate once.

TrapQBNegFilter (Anti QB Trigger)
Effect: Compares the value of a questbit specified by QB Name with QB Val. If the QB is less than or equal to QB Val, the script acts as a router, passing the message through its switchlinks (otherwise the message is blocked). If QB Val is not provided, the QB is compared with 0, e.g. any non-zero value in the QB will prevent messages from passing.

Pseudocode: IF QB Name value <= QB Val (0 if not provided) THEN pass message

TrapQBNegFilterOnce
Effect: Identical to TrapQBNegFilter, but will only ever activate once.

TrapQBSet (QB Set)
Effect: On receipt of TurnOn, sets Script -> QB Name to QB Val. On receipt of TurnOff, sets QB Name to 0.

FrobQB ()
Effect: Triggers QBSet and QBVal when the object the script is on is frobbed. An in game example is when you loot the keycard off Mike Grassi's body in medsci, picking it up sets a QB.

TrapRadCleanse (RadCleaner)
Effect: When activated via a TurnOn message, will remove all radiation from the player. Possibly not MP compatible.

TrapRouter (Router)
Effect: Passes along any signal.

OnceRouter ()
Effect: Identical to TrapRouter, but will only ever activate once. Any object serving as OnceRouter MUST be created and kept outside rooms, else it will fire automatically upon level start.

TrapShove (Shove Trap)
Effect: Provides a physics “push” to an object. Should usually be used by adding this script to the otherwise normal object in the world. The magnitude and direction of the push is determined by the Script -> Shove property.

TrapSignal (Signal Trap)
Effect: Sends out a signal that AIs can respond to via a signal response. The type of the signal is set by the Script -> SignalType property. If sent a TurnOff message will send the signaltype message with "off" appended to the end. It's not really necessary to use this script for signalling though, a switchlink to an AI generates the SwitchOn message as a signal.

TrapSlayer (Buffy the Trap Slayer)
Effect: *Slays* all objects that are linked to it via SwitchLinks. If you wish for the object to be *destroyed* instead (no corpse etc) use TrapDestroy

TrapSound (Sound Trap)
Effect: Plays a sound from Sound -> Object Sound. TurnOff will halt any sound being played by the trap (e.g. if it is a looping sound).

TrapSoundAmb ()
Effect: Activates an AmbientHacked sound on the object in response to TurnOn. Cannot turn it off.

TrapAmbientOff ()
Effect: Turns any AmbientHacked sound on the object on or off. Note that the messages are inverted from their usual sense. You send TurnOn to turn sound off, and TurnOff to turn sound on.

TrapSpawn (Spawn)
Effect: Generates an object of a random specified type at a random specified set of locations. The object list is formed using Script -> Spawn, the type is the archetype name, the rarity a weighting of generation chance (e.g. make them add up to 100 and you have a percentage). Any object generated will have a Script -> EcoType property matching the EcoType property on this trap. Any Patrol: Does Patrol property on the selected spawn marker will be copied to the spawned AI. The location of object generation is specified by choosing randomly among any marker objects linked to the trap through a SpawnPoint link. You can set the following flags:

• PopLimit: If the Population Limit flag is set, each spawn marker will be individually limited to one spawned object at a time.
• PlrDist: If the Player Distance flag is set, then the trap will exclude from consideration all markers that are within a certain distance (about 10 meters, so very short) of the player.
• GotoLoc: If the Goto Location flag is set, then the creature will attempt to directly go to the player’s location at the time of the monster’s generation. Useful for alarm systems.
• SelfMarker: If the Self Marker flag is set, the trap itself is also used as the spawn marker.
• Raycast: If set, the trap and all its SpawnPoint linked markers will not spawn from points that are in the player's vision. If the randomly selected spawn marker has line of sight to the player, no attempt will be made to select another marker, so the spawn will fail.
• Farthest: If set, the farthest SpawnPoint linked marker will always spawn a monster once triggered (Raycast will be ignored).

The Supply field can limit the total number of objects that will be spawned. 0 is no limit.

If the object generated is an AI, additional behaviours can be applied. If the trap has the AI -> Ability Settings -> Patrol: Does Patrol property set to TRUE, then the generated monster will also have that property set.

If the trap has a Sound > ObjSound property on it, then it will play the schema named by that property whenever a monster is generated.

TrapSuicide ()
Effect: Causes the object to *slay* *itself* when activated. Useful for scripted killing of monsters.

TrapTeleport (Teleport Trap)
Effect: Teleports all objects that are switchlinked to the trap to the location of the trap. Teleported objects use the teleport trap's rotation properties too, so if an object teleports in on a bad angle you need to change the trap's orientation.

TrapTeleportPlayer ()
Effect: Teleports the player to the location of the trap.

TrapToxinCleanse (ToxCleaner)
Effect: When activated via a TurnOn message, will remove all toxin from the player. May be broken in MP.

TrapTripLevel (Tripwire Level)
Effect: This trap is only activated by the entry of the player moving him to a new level, specified by the MultiLevel -> Dest Level property. The specific location within that level that the player will appear at is determined by the MultiLevel -> Dest Loc property. On the new level, the player appears at the location of a marker whose MultiLevel -> Start Loc property matches the Dest Loc value.

TrapTweq (Tweq Trap)
Effect: Controls the Tweq properties on the trap. May be used as a standalone object to for example emit objects (tweq: emit, used for the scripted explosions for example) or may be added as a script to an existing object. Other tweq control scripts include TweqOnOff and Tweqable

TrapUnlock (Lock Trap)
Effect: Causes objects that it is SwitchLinked to to become locked (TurnOff) or unlocked (TurnOn). This does not change the state of the object this script is on directly!

TrapUnref ()
Effect: Unrefs (equivalent effect to it being put into a container, disappears and loses physics) the object it is on when triggered. TurnOff reverses.

EraseRadiation
TurnOn: Purges the "radiation level" from all objects on the level, excluding the Player. This includes room brushes. Used in Engineering to flush radiation.

DestroyAllByName
Effect: Destroys all objects in the world that descend from the archetype specified in Script -> ConsumeType.

TweqAllByName
Effect: Triggers Tweqs on all objects that descend from the archetype specified in Script -> ConsumeType. Used in enginneering to set the Radboxes to safe once radiation is purged.

TransluceByDamage
Effect: When added to an object the object fades as it is damaged. Used in the final battle.

ChangeInterface
Effect: Enables (TurnOn) or disables (TurnOff) the cyberinterface. Essential for a functional mission!

ObjConsumeButton ()
Effect: Sends signals along switchlinks when an appropriate object from Script -> ConsumeType is dragged onto its world object. The dragged object is destroyed at the time. Used for Sim Comps, power cells in game.

Some custom script modules such as NVScript also exist, and are complementary to the default ones providing additional functionality and control.

[67418ae5b6daaZylonBane]

The documentation for TrapSpawn doesn't describe what the Raycast and Farthest flags do. Anyone know?

[67418ae5b6ecfZygo]

My presumption was that both were for moderating the player seeing spawning behaviour, raycast was for situation where the player could be close to a spawn but for example on the other side of a wall or on a sublevel above/ below and thus unable to see it, while farthest would mean that the markers furthest from the player are used first.

That's conjecture though, I never had to test them.

[67418ae5b6fa5ZylonBane]

Updated first post to add OnceRouter script.

[67418ae5b73d8chuckles n chestnuts]

The documentation for TrapSpawn doesn't describe what the Raycast and Farthest flags do. Anyone know?

Raycast: spawns only when the player cannot see the spawnpoint

Farthest: is presumed to cause the AI's to spawn at the furthest point from the player (to my vague experience it works better when you have the rand/directmonstergen's set to selfmark and also have a spawn point set)...... Looks like I schooled you this time ZylonBane, wheres my cookie 

[67418ae5b74cfZylonBane]

That question was already answered three years ago.

[67418ae5b7702chuckles n chestnuts]

That question was already answered three years ago.

Yeah I was kinda wondering, because its in shockED for dummies posts (one of them, can't exactly remember which).