Scripting Conditions

Feb 16, 2019 at 6:43 AM
Scripting Conditions




  • Conditions Overview(top)


    During game play things, or events, happen: objects spawn, timers tick away, objects take damage, players interact with switches, etc. When these happen, the game “broadcasts” these triggered events that Script Conditions listen for. In each game tick, each script is processed in a set order and for each one the conditions are first checked to see if the events they watch out for happened.

    Scripts with Conditions that pass their tests will have their Actions executed.


    Spawned(top)


    Object specific. Triggers whenever the object spawns, at the start of cinematics, but before players spawn onto the map. This includes:
    • Start of a Forge session
    • Match start
    • Start of each round
    • Caused by a Spawn script action
    • Caused by an object's Respawn property
    NOTES
    • Doesn’t trigger when a Spawn script action attempts to spawn an object that is already on the map
    • May trigger when a Spawn action would spawn a despawned object, but a higher number Despawn action overrides it
    • All objects are spawned at the beginning of every round, about 13 seconds before players spawn in round one and 5 seconds before in later rounds. The Spawned condition can be used to set up objects before players are on the map (similar to how the On Round condition originally worked).
    • Player presence can delay or cancel spawns, except when using the Spawn action with the Force parameter turned On
    • There is not currently a way to delay objects from spawning at the start of a round. Objects can be excluded from specific gametypes, but they can't be spawned at all if this is done (there might be exceptions). So the Spawned condition will trigger for all objects on the map at the start of every round.

    NOTABLE USES
    • Use Spawned to do something at the earliest scripting time possible for each round, right after the map loads and cinematics begin, but (usually) before players are initially spawned.
    • Set an object's Respawn: Timer property and then add a despawn script to create a timer that can be activated at any time. Use the On Spawn script condition to trigger something when the object respawns. Note: put the object far away from where players will be since player presence can delay respawns.


    Destroyed/Despawned(top)


    WHEN... THIS object is 'Destroyed' or 'Despawned' (result of object cleanup).
    • Objects that have health (vehicles, fixed turrets, explosives, etc) are destroyed when their health reaches zero
    • Any object that that spawns can be despawned with scripting, as long as the object can be given a script
    • Objects with their Despawn property set can despawn automatically
    • Objects that fall out of the map bounds might despawn
    • When usable objects or inventory objects are picked up by a player. Includes power ups and grenades. Weapons will despawn immediately if a player takes all of its ammo.
    NOTES
    • Doesn't trigger when a Despawn script action attempts to despawn an object that is already despawned
    • Triggers when a Despawn action would despawn a spawned object, but a later (higher number) Spawn action overrides it
    • Will not trigger when deleted by a forger
    • May trigger when object is excluded in excluded gametypes
    • Despawned objects may still be represented, i.e. objects with boundary checks will continue checking when despawned

    NOTABLE USES

    • Timer method before the Monitor's Bounty update: Set an object's Despawn: Timer property and then add a spawn script to create a timer that can be activated at any time. Use the Destroyed/Despawned script condition to trigger something when the object despawns. Note: put the object far away from where players will be since player presence can delay despawns.


    Health Below(top)


    WHEN... Object's health falls below the 'Health' value.

    • Health is the % of total health 0-100%
    • Can be set in increments of 1



    Message:Received(top)


    WHEN... A 'Message: Send' Action with the specified Channel is valid. Condition uses 'Message: Send' Transfer object as its ACTIVATOR object.


    • Channel alpha-zulu
    • Uses a separate message channel than Power Check.



    Power Check(top)


    WHEN... A 'Power: Set' Action with the specified Channel and State are valid. Condition uses 'Power: Set' Transfer object as its ACTIVATOR object.

    • Channel alpha-zulu
    • Uses a separate message channel than Messages.



    Timer Check(top)


    WHEN... THIS object's Initial delay time expires and then continuously after the Repeat Timer.

    Initial: 0-720 (increments of .05)

    Repeat: 0-720 (increments of .05)



    Interacted(top)


    WHEN... A player interacts with THIS object (switch or pickup). Uses ACTIVATOR as the player that interacted with the object.

    Object specific. The player sees a prompt and uses the action button to trigger the script when near an object that has an On Interaction script. A few objects have the On Interaction condition:
    • Interactive switch
    • Interactive switch terminal
    • Invisible switch
    NOTES
    • The switches respect their Team property, so only the selected team can use the switch


    Match:Start(top)


    WHEN... A game 'Match' begins (start of map). This Condition triggers when all expected players have joined and gameplay is about to begin.

    Match start occurs approximately 13 seconds after the first intro camera shot starts.



    Round:Event(top)


    WHEN... Each time a 'Round' event triggers. Start when players can move or at the End when the round has concluded.

    Setting toggles to trigger either when a round starts or when a round ends.

    NOTES
    • End can only be used to set info saved between rounds: numbers and power states. Scripts stop working after this so any changes won't be seen and the map will be reset for the next round.


    Message/Power:Multi(top)


    WHEN... Multiple 'Message' and/or 'Power' state Conditions are valid; useful for and/or type logic.

    Triggers when up to four of any combination of Message:Received and Power:Check Conditions are valid. Can set how many of the four conditions must be met for the Script to trigger in Trigger Count.

    Trigger Count - 1-4

    Each of four:
    Condition - Message:Recieved or Power:Check

    Message:Recieved - alpha-zulu​

    Power:Check - Channel or State
    Channel: alpha-zulu
    State: On/Off/Toggle​


    Number:Check(top)


    WHEN... 'Number: Check" meets criteria set by the 'Number: Change' Action. Uses EXTRA to only transfer objects with modified variables that pass the condition.

    VARIABLE
    Scope: Global, Player, Team or Object
    Channel: alpha-zulu
    Offset: (Scope of the variable you want to check) -1000 - 1000​
    Operator: Equal, Not Equal, Greater Than, "Greater Than, Equal To", Less Than, "Less Than, Equal to"
    CHECK
    Scope: Global, Player, Team, Object or Constant​

    NOTES
    • When Number:Check is the condition and Number/Score/Spawn-Order:Change the action, the Object setting becomes available when Source=Number+Scope=Object or when Scope=Game-Value and the options are THIS and ACTIVATOR. ACTIVATOR represents the object whose Number changed. That can include Objects, Players or Teams (need to verify there's a Team object).


    Score:Check(top)


    WHEN... THIS object's Team Score:Check criteria is met. THIS object's 'Team' property should be set to the 'Team' you are checking.

    Score: -5000 - 5000 (increments of 1)
    Periodic: - On/Off

    NOTES
    • Can toggle 'Periodic' in settings, to trigger Condition any time a multiple of chosen Score is reached.


    Round:Time(top)


    WHEN... The active 'Round' time is equal to the desired Time value.

    Time: 0 - 720 (increments of .10)
    Periodic: On/Off


    Boundary:Check(top)


    WHEN... Objects intersect with THIS object's 'Boundary' (trigger volume). Uses ACTIVATOR as object that intersected the boundary; EXTRA as all objects inside the boundary.

    Check: Enter, Exit, Enter/Exit, Continuous
    Filter: Players, Objects, All
    Repeat: 0-720 (increments of .05)

    NOTES
    • Repeat sets the amount of time that passes before Boundary checks for Objects. The smaller the number, the more frequently the check. Repeat = 0.00 means it checks every game tick (60 ticks or second). 0.05 seconds = 3 game ticks. Set to 0 for a one-time trigger.