This library provides a new object type called a trigger, which can be used to cause reactions in other objects in the world through the use of tags. For example, a lever is a trigger object, and when pulled, the lever opens the gate object with the appropriate tag. There are a variety of different trigger setups you can create to influence objects in your game.
Triggers work through activation and deactivation, or toggling. You can activate a trigger directly, such as when a player steps on a trigger object, using the Activate(object) proc, where the object argument is the object the activated it. You can also deactivate it directly using the Deactivate(object) proc. Or, if you're not sure whether you want to activate or deactivate it, such as in the case of using a lever, you can use the Toggle(object) proc, which will activate or deactivate it depending on its settings.
When a trigger is activated, it will add to a targeted object's triggers_set variable, and the amount added is dependent on the trigger's trigger_weight value. When the triggered object's triggers_set value equals its triggers_req (triggers required) value, then the object is activated, such as a gate's opening. When the object's triggers_set value no longer matches its triggers_req value, it will deactivate, such as a gate closing.
You specify which objects a trigger will affect through the trigger's trigger_target var. This variable is a params list of the tags for the trigger to locate. So in order to affect an object, you need to set the object's tag value, and set the trigger's target value to include the object's tag value.
Lets cover the trigger variables so you'll understand in what ways you can customize your triggers to make them do what you want.
TRIGGER VARIABLES:
trigger_target - This is a params string used to tell the trigger which tags to search for when looking for objects to affect. For example: "gate1;gate2"
trigger_weight - This is how amount added to a triggered object's triggers_set value will increase or decrease when this trigger is activated or deactivated. When the object's triggers_set value matches its triggers_req value, the object will activate. When the values don't match anymore, the object will deactivate.
trigger_delay - This is the amount of time in ticks that must pass before you can use the trigger again after it is used. This is to prevent triggers from accidentally being activated more than once when a player attempts to use them.
trigger_timer - If you want, you can attach a timer to a trigger. Timers can only be started when a trigger is activated, so it must be inactive before the timer will start. Once started, the calling the Countdown() proc for the trigger will reduce the counter by one. When the counter equals zero, the timer is finished and the trigger will deactivate again. This trigger_timer value is the number if increments to set when the counter begins. Also, triggers can not be activated or deactivated while a timer is counting down.
NOTE: In order to use timers properly, you must have a routine to call the Countdown() proc repeatedly until it runs out. How you do this is up to you.
trigger_permanent - This allows you to have one-time-use triggers. Once used, a trigger with this value set to true can not be used again.
trigger_active - If this is true, then the trigger is in its activate state, and it will deactivate if toggled. If false, it is not active, and it will activate when toggled. Some things, such as timers, will only work when an trigger is activated. This value is mostly for internal use, but you may want to check it if you want to know the status of a trigger.
If you want things to happen to the trigger when it is activated or deactivated, such as changing its icon state, you can do this through the Activated(object) and Deactivated(object) procs, where the object argument is the object that activated or deactivated the trigger.
OBJECTS
Each atom now comes with four new variables, but the ones you'll primarily be concerned with are the triggers_set and triggers_req variables. When a trigger is activated and has an atom as a target, that atom's triggers_set value will increase by the trigger's trigger_weight value. If the trigger is deactivated, the atom's triggers_set value will decrease by the trigger's trigger_weight.
When an atom's triggers_set value is equal to the its triggers_req value, then the object will call its Activate(object) proc, which, in turn, will call the Activated(object) proc. The object argument being the object which activated the trigger in the first place. If the triggers_set value stops being equal to the triggers_req value, then the object will call its Deactivate(object) and in turn Deactivated(object) procs. You can use Activated() and Deactivated() to determine what happens to each object when it is activated or deactivated, such as a gate opening and closing.
Another variable available to every atom is trigger_lock. When trigger_lock is true, the object will only activate or deactivate once. Once the object has been interacted with, it will lock up and will not respond to triggers anymore.