Editing Games:Halo 5: Guardians/Forge/Scripting/1. Conditions

''<span style="text-size: 12px"><span style="color: #99ccff">This information was compiled for your use as a reference and learning resource. Please keep in mind that Halo 5 Forge updates over the years, including but not limited to the huge Monitor's Bounty update, means you may find information that is no longer relevant or was modified in an update. ''We're working to get this info up-to-date. ''Feel free to contact staff if you find deprecated information, when they can forward your concern to the appropriate team for correction.</span></span>''



__TOC__


==Conditions Overview==
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 [https://www.forgehub.com/wiki/h5-actions/ https://www.forgehub.com/wiki/h5-actions/] executed.

With the exception of the Message/Power:Multi Condition, each Script contains one Condition. In addition to each Condition's unique settings, each Script has four options to choose from at the bottom of the UI (User Interface) to further narrow the circumstances under which it's Actions will occur: Condition Interrupt, Round Interrupt, Always Runs and Enabled.

[INDENT]'''Condition Interrupt'''
Condition Interrupt causes a script with timed Actions to stop running its current Action and start over with Action 1 whenever the Condition gets triggered again. If there are no timed Actions, Condition Interrupt won't do anything.

Timed Actions run in sequence; the next one once the current one finishes. For example, if you want to have a Move:Offset start at the same time as a Rotate:Offset, you need 2 separate Scripts that trigger at the same time.

'''Round Interrupt'''
Round Interrupt is useful for scripts with long running times that need to restart for each round.

'''Always Runs '''
When Always Runs is unchecked, it stops timed Actions that are running, without completing them or any Actions after, when the object running the Script is destroyed or despawned.

Make sure you put a Spawn Action in a different Script that has Always Runs ON.

You can use the mod filters with the Despawn Action to specify whether or not THIS object is included based on its current Number, Order, Team, Label, etc.

'''Enabled '''
Enabled turns your script on or off.[/INDENT]



==Spawned==
WHEN... THIS object is 'Spawned'.

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES
</span>
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'''


*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 <span style="text-decoration: underline;">Force</span> 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.

'''<span style="text-decoration: underline;">NOTABLE USES</span>'''

*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.

</div>


==Destroyed/Despawned==
WHEN... THIS object is 'Destroyed' or 'Despawned'.

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES
</span>'''

*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
*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.


</div>


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

<div class="spoiler">

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

</div>

<div class="spoiler">
Examples of Objects that have health:

*Vehicles [Gameplay]


*Explosives [Props][Explosives]


*Fixed turrets [Gameplay][Weapons]


*Grenades [Gameplay][Weapons] (not working with player damage)


*Destructible shields [Gameplay] Note, as of April 2016 this does not work for damage done by player attacks, only when the Damage: Ratio script action is used.

</div>



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


<div class="spoiler">

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

</div>



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

<div class="spoiler">

[ATTACH=full]70751[/ATTACH]


<span style="text-decoration: underline;">NOTES</span>

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

</div>



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

<div class="spoiler">
'''<span style="color: #4da6ff">Initial</span>''': 0-720 (increments of .05)

<span style="color: #4da6ff">'''Repeat'''</span>: 0-720 (increments of .05)
</div>

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

*The timer starts running at the start of the match, about 13 seconds before players are spawned.


*This lets us run scripts before the fighting starts and during the intro cinematics.


*A script with a Delay of 0.0 will trigger one cycle after scripts with On Spawn, On Match: Start, and On Round: Start conditions

</div>



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

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES
</span>'''
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


*The switches respect their Team property, so only the selected team can use the switch

</div>



==Match:Start==
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==
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.)

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

*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. A workaround is to set a Script Condition with an Action followed by a Wait action, set to extend into the next round.


*There is a technique of using object respawn (or despawn) timers and power channel states to have scripts trigger when players spawn at the start of each round. See Object Spawn Timers.

</div>



==Message/Power:Multi==
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.)

<div class="spoiler">

[ATTACH=full]70747[/ATTACH]

'''<span style="color: #4da6ff">Trigger Count</span>''' - 1-4 (Minimum number of state Conditions that must be true in order to trigger the Action.)

'''Each of four:
<span style="color: #4da6ff">Condition </span>- Message:Recieved or Power:Check'''
[INDENT]<span style="color: #4da6ff">'''Message:Recieved''' </span>- alpha-zulu[/INDENT]

[INDENT]'''<span style="color: rgb(77, 166, 255)">Power:Check</span>''' - Channel or State
[INDENT]'''Channel:''' alpha-zulu
'''State:''' On/Off/Toggle[/INDENT][/INDENT]
</div>

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

*This is the only condition that can sense multiple Conditions, but it is limited to Messages and Power States.


*When you have more than one Condition, setting this to 1 behaves with OR logic, so any one of the Conditions being true means that the script will trigger.


*If you set this to the number of Conditions you use, it behaves with AND logic and ''all'' the conditions must be true for the script to trigger.


*Setting it to more than 1 but less than the number of Conditions results in complex behavior that would have to be represented with many AND and OR operations.


*If you set this to a higher number than Conditions that are used, it effectively disables the script without losing the settings.

*If you have several Multi scripts that check the same Channels, put the channels in the same number Condition slot, even if some Conditions are set to [none]. That way, you can select multiple objects that have scripts that use these channels and change the channels at the same time.

*A script with Multi: Minimum=1 (On Power: [alpha]: Toggle) {Power: Set: [alpha]: Toggle} will activate every cycle (an infinite loop). The same thing will happen with a script sending a message to itself.

*The Multi condition won’t continuously trigger based only on power states staying On or Off. A message or power state change broadcast that it is listening for must occur to trigger it.

</div>



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

<div class="spoiler">

[ATTACH=full]70748[/ATTACH]

'''<span style="color: #4da6ff">VARIABLE</span>'''
[INDENT]     '''<span style="color: #a64dff">Scope</span>:''' <span style="color: #9999ff">'''Global'''</span>, <span style="color: #9999ff">'''Player'''</span>, <span style="color: #9999ff">'''Team'''</span> or <span style="color: #9999ff">'''Object'''</span>
[INDENT][INDENT]<span style="color: #9999ff">''''''Global''''''</span>
[INDENT]<span style="color: #00b300">Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Player</span>'''
[INDENT]<span style="color: rgb(0, 179, 0)">Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Team</span>'''
[INDENT]<span style="color: #00b300">Team</span>: (Neutral, Team 1-Team 8)
<span style="color: #00b300">Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Object</span>'''[/INDENT]
'''<span style="color: #a64dff">Offset:</span>''' Adds this Offset to the VARIABLE before comparing to CHECK Value (-1000 - 1000)[/INDENT][/INDENT]
'''<span style="color: #4da6ff">Operator:</span>''' (How your VARIABLE and CHECK values are compared to each other.)
Equal, Not Equal, Greater Than, "Greater Than, Equal To", Less Than, "Less Than, Equal to"
'''<span style="color: #4da6ff">CHECK</span>'''
[INDENT]   '''<span style="color: #a64dff">Scope</span>:''' <span style="color: #9999ff">'''Global'''</span>, <span style="color: #9999ff">'''Player'''</span>, '''<span style="color: #9999ff">Team</span>''',''' <span style="color: #9999ff">Object</span>,''' or '''<span style="color: #9999ff">Constant</span>'''
[INDENT][INDENT]<span style="color: #9999ff">'''Global'''</span>
[INDENT]<span style="color: #00b300">Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Player</span>'''
[INDENT]<span style="color: rgb(0, 179, 0)">Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Team</span>'''
[INDENT]<span style="color: #00b300">Team: (Neutral, Team 1-Team 8)
Channel</span>: alpha-zulu[/INDENT]
'''<span style="color: #9999ff">Object
Constant</span>'''
[INDENT]<span style="color: #00b300">Value</span> (The Value that you want the variable to hit before this Condition triggers.)[/INDENT][/INDENT][/INDENT][/INDENT]

</div>

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

*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).
*When Number:Check is set to pull a Number from Team Neutral, it will attempt to pull the Number from the object that holds the Number:Chagne script, and it will look for a team in it's Object Properties. If that object is also set to Team Neutral, Number:Check triggers for all teams.
*Since Conditions can't filter players, when Number:Check is listening for a Number change on one of the Player Channels (alpha-zulu), it does not differentiate between different Players and treats all on that Channel as Player.
*Number Checks for a player number equal to itself will trigger every time that player number is dirtied, but "Less Than" and "More Than" simply won't fire.

</div>



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

<div class="spoiler">

[ATTACH=full]70749[/ATTACH]

'''<span style="color: #4da6ff">Score:</span>''' -5000 - 5000 (increments of 1)
'''<span style="color: #4da6ff">Periodic: </span>'''- On/Off (If On, Condition will trigger any time a multiple of the target Score is hit.)
</div>

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

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

</div>



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

<div class="spoiler">

[ATTACH=full]70750[/ATTACH]

'''<span style="color: #4da6ff">Time</span>''': 0 - 720 (increments of .10)
'''<span style="color: #4da6ff">Periodic</span>''': On/Off (If On, Condition will trigger any time a multiple of the target Score is hit.)
</div>



==Boundary:Check==
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.

<div class="spoiler">

[ATTACH=full]70746[/ATTACH]

'''<span style="color: #4da6ff">Check:</span>''' Enter, Exit, Enter/Exit, Continuous
'''<span style="color: #4da6ff">Filter:</span>''' Players, Objects, All
'''<span style="color: #4da6ff">Repeat:</span>''' 0-720 (increments of .05) (How often the Condition will check for objects within the 'Boundary'.)
</div>

<div class="spoiler">
'''<span style="text-decoration: underline;">NOTES</span>'''

*When Boundary:Check is set to detect Objects, that object's "origin" must cross the barrier for Boundary:Check to trigger. In grouped objects, the parent object's origin triggers Boundary:Check.
*Repeat sets the amount of time that passes between Boundary checks. The smaller the number, the more frequently the check. Unlike Timer Check, for Boundary Check the Repeat = 0.00 means it checks every game tick (60 ticks per second). 0.05 seconds = 3 game ticks.

'''<span style="text-decoration: underline;">GOTCHAS!</span>'''

*When set to Objects, some objects, such as Wall Trim, will not trigger Boundary:Check with their origin.
*Teleporters teleport players before Boundary:Check can detect them
*If using Boundary Check to change a number to equal player alpha, and no player is in boundary, the number will change to 0

</div>