Halo 5 Forge Scripting Reference http://docs.google.com/document/d/1bnW0QHucyEcH4kReWQHIV9LJ2kOEiO1DgtX_yIqoD3Q/edit?usp=sharing Community-made Google Doc that lists all the Halo5 scripting Conditions and Actions and also explains some of the specifics or gotchas when using them. Plus general info about scripting. This is for the public domain, so copy and use it however you like. It's set to public and anyone can edit it, so add your knowledge to help out everyone. If anyone has time, copy this to a better place for a community doc like under http://halo.wikia.com/wiki/Forge or somewhere. It would also be great to add a "Recipes" or "Common/Useful Scripts" section. Provide links to tutorials that are out there if that's a good option. Spoiler: Condition Descriptions On Spawn Object specific. Triggers whenever the object spawns, including: 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 spawned May trigger when a Spawn action would spawn a despawned object, but a higher number Despawn action overrides it On Destroyed/Despawn Object specific. Triggers when an object is despawned or destroyed in one of many ways: 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 Does not 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 higher number Spawn action overrides it On Interaction 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 On Health: Below Object specific. Some objects that have health can be given On Health: Below scripts: Health Choose [0.00] to [1.00] in increments of 0.01. Vehicles Explosives Fixed turrets Grenades (not working with player damage) Destructible shields On Message: Received Not object specific. Messages are simple events that you can broadcast from any object that can contain scripts (using the Message: Send action). Any script that has On Message: Received conditions will listen for a message broadcast being sent over the channel it is listening to. Channel Choose [alpha to zulu]. On Power: State Not object specific. Listen for power channel state change events that occur for your chosen power channel. These events occur when the power is switched from Off to On or from On to Off. Channel Choose [alpha to zulu]. State Choose [On/Off]. Choose [On] to trigger when the chosen channel switches from Off to On, or vice versa. On Message/Power: Multi Not object specific. This is the only condition that can sense multiple conditions, up to four, but it is limited to messages and power states. Each condition evaluates to True or False and each one that is True counts as one when compared to the Minimum to Trigger setting (see notes). Minimum to Trigger Choose [1/2/3/4]. This determines how many of the four conditions must be true for the script to trigger and execute its action. 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 Tip: If you set this to a higher number than conditions that are used, it effectively disables the script without losing the settings {Condition 1/2/3/4} Choose [none/On Message/On Power]. These are the four conditions you have the option to use. They default to the value [none], but you may change any of them to other values If you select [On Message], the Channel setting will appear below Selecting [On Power] reveals both the Channel and State settings Tip: If you have several Multi scripts that check the same channels, put the channels in the same number condition slot, even if you leave the lower number conditions set to [none] Channel Choose [alpha to zulu]. State Choose [On/Off/Toggle]. The behavior of Multi power state differs some from On Power: State conditions. [On] evaluates to True when the channel switched from Off to On during the previous cycle, but also if the power state is currently set to On even if that was earlier in the game [Off] evaluates to True when the channel switches from On to Off during the previous cycle, but also if the power state is currently set to Off even if that was earlier in the game is True only if the power state changed during the previous cycle Notes 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. As of April 2016, Multi [On Message] conditions have some odd behavior: They count as two toward the Minimum to Trigger setting when the message is broadcast while same power channel is on They count as one when the power channel is switched On even without the message being sent Not affected by the presence of Multi [On Power] conditions for the same channel Regular On Message: Received conditions don’t exhibit this behavior This effectively means that you can’t use Multi [On Message] conditions for a channel while using that channel’s power state for another independent purpose. You can still use the plain On Message: Received condition for that channel independently. On Timer Not object specific. The game has one timer running during each match (and Forge). Initial Delay Choose [0.00 to 120.00] seconds in intervals of 0.1. Repeat Timer Choose [0.00 to 120.00] seconds in intervals of 0.1. Notes 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 On Match: Start Not object specific. This condition triggers only at the start of the match or Forge session. Players are spawned about 13 seconds after this event. On Round: Start Not object specific. This condition triggers at the start of each round in a match, including the start of any match whether or not the match has multiple rounds, and including the start of a Forge session. For the first round (match start), players are spawned about 13 seconds after this event. For later rounds, players spawn about 8 seconds after this event. Spoiler: Action Descriptions Spawn Object specific. Spawns an object that is currently not in the game. Notes Objects spawn in their original positions, not where they were when destroyed or despawned Objects in a welded group might be repositioned or rotated if the group was still spawned and in another location The Spawn action won't reset a currently spawned object Many objects won't spawn if players are in the way or very close by Some objects, such as the Sparks FX, won't spawn inside other objects even when both objects are set to Phased Physics Despawn Object specific. Removes an object from the game if it currently is in the game and not destroyed. Notes If you despawn an object in Forge when it has no means of respawning (Respawn property or Spawn script action), it might be removed from your map. An object with an (On Spawn) {Despawn} script will probably be impossible to recover Position/Rotation: Reset Object specific. Moves and rotates its object back to its spawn point and orientation. Velocity Reset Choose [Yes/No]. Sets the velocity to zero if set to Yes. If set to No, the object position and rotation will be reset, but it will continue to move in whatever direction it was moving. Time Choose [0.00 to 60.00] seconds in intervals of 0.1. Notes The position and rotation is not reliably reset to their original values. Using Despawn and Spawn actions can be more reliable. Setting the time to 0.0 might be more reliable. A vehicle with a Reset script with Time set to 0.00 will instantly teleport the vehicle and passengers to the vehicles spawn location. Does not seem to work when there's a driver. Tested with a Mongoose. Message: Send Not object specific. Channel Choose [alpha to zulu]. Power: Set Not object specific. Channel Choose [alpha to zulu]. State Choose [On/Off/Toggle]. Change the selected channel's power state to On, Off, or Toggle it from its previous state. Notes The behavior seems like the highest number script that sets a channel's power state is the only one that takes effect. Two Toggle actions won't cancel each other. If an On/Off script attempts to set the state but it is already set to that value, then no events occur and no conditions will trigger during the next cycle Toggle always changes the value, either from Off to On or from On to Off Since it appears that only one script takes effect for a power channel, only either the On or the Off conditions can trigger during each cycle. If the setting doesn't end up changed, no On/Off/Toggle conditions will be triggered by it (but the current state is still true for On/Off Multi conditions). Move: Offset Object specific. Offsets an object's current X/Y/Z position coordinates by a specified amount over a specified period of time. The changes can be relative to either world coordinates (Local Movement set to [Off]) or the object's relative coordinates (Local Movement set to [On]). The units used in Halo 5 are similar to the foot or ⅓ meter. X / Forward Choose [-500.00 to 500.00] in increments of 0.5 Y / Horizontal Choose [-500.00 to 500.00] in increments of 0.5 Z / Vertical Choose [-500.00 to 500.00] in increments of 0.5 Time Choose [0.10 to 60.00] seconds in intervals of 0.1. Local Movement Choose [On/Off]. The direction of the movement will change when the object’s rotation changes if this is turned On. If [Off], the direction will always be relative to the world coordinates. Notes If the relative (Local Movement) offset orientations for an object are not obvious, reset its rotation settings to 0.00. Then the Forward, Horizontal and Vertical directions will match the positive world X, Y and Z directions. Only one Move:Offset or Position/Rotation: Reset script can be active for an object at a time When multiple Move scripts for an object are activated during the same cycle, the lowest number script (first one to execute) is used while the others are ignored A Move script that activates while during another script’s control will take over the object movement. If the newer script finishes and the earlier script is still running, control returns to the earlier script A Move script can’t be activated again while it is running. The length of time it runs can’t be extended in the middle of them by executing it again Continuous motion: It can be activated on the next cycle after the time is completed to provide continuous motion. This does not work with repeating On Timer conditions set to repeat for the same amount of time that the Move script uses because the On Timer condition will Trigger during the last cycle of the Move script, which means that the Move script can’t activate again at that time. One solution is to have the Move script last 0.1 seconds less than the Timer condition, but the object motion will stop for that tenth of a second Since another script can take over while the first script is running, using a second copy of the script (or a script that runs when the first script can’t) will provide continuous motion Object Timers can be used to provide timed continuous motion with a single Move script because the On Spawn and On Despawn events can be scripted to one cycle apart A Move script can run for a Warthog that is being driven and the resulting motion seems to be a combination of the Move script and normal driving motion. Tested with a Forward action script. Other vehicles need to be tested. As of April 2016, Move scripts sometimes result in jerky object motion rather than the expected smooth movement. There doesn't seem to be any definite patterns to this behavior, which may or may not occur at any time. This makes Move actions difficult to use in situations where inconsistent movement is undesirable. Sometimes Move scripts that use short Time settings seem to provide smoother motion. The Velocity action can provide smoother motion, but has limitations. Rotate: Offset Object specific. Yaw Choose [-180.00 to 180.00] degrees in increments of 0.1. Yaw rotates the object around the world Z axis. Roll Choose [-180.00 to 180.00] degrees in increments of 0.1. Roll rotates the object around the world X axis. Pitch Choose [-180.00 to 180.00] degrees in increments of 0.1. Pitch rotates the object around the world Y axis. Time Choose [0.10 to 60.00] seconds in intervals of 0.1. Notes See Move: Offset notes (similar) Welded groups with Rotation scripts result in erratic behavior and usually result in movement along with rotation. Rotation works much better for single objects. A single object with a Rotate script can be used to as a crank to rotate a welded group that is set to Normal Physics. Velocity: Set Object specific. Only available for objects set to Normal Physics. Instantly sets the current velocity for the object. Forward Choose [-500.00 to 500.00] in increments of 0.5 Horizontal Choose [-500.00 to 500.00] in increments of 0.5 Vertical Choose [-500.00 to 500.00] in increments of 0.5 Notes If the relative orientations for an object are not obvious, reset its rotation settings to 0.00. Then the Forward, Horizontal and Vertical directions will match the positive world X, Y and Z directions. This action does not have a time component, so it can be activated every cycle If multiple Velocity scripts are activated during the same cycle for an object, the highest numbered script executes and the others are ignored Gravity, collisions, etc will affect the object’s velocity again immediately on the next cycle Whatever velocity the object has before this action activates is completely replaced by the velocity set by this action Vehicles with a driver don't seem to respond to Velocity scripts. Vehicles with only passengers will execute Velocity scripts and the passenger seems to stay in the vehicle if it floors upside down. Tested in Forge with a Mongoose. As of April 2016, this action provides smoother motion than Move, Rotate, or Reset script actions, but it can be tricky to use Color: Set Object specific. Available for some objects. The number of colors will match the object’s colors. Damage: Ratio Object specific. Only available for objects that have health. Deals damage to to an object. Ratio Choose [0.00] to [1.00] in increments of 0.01. *edit: adding this link so it might show up in search engines: https://docs.google.com/document/d/1bnW0QHucyEcH4kReWQHIV9LJ2kOEiO1DgtX_yIqoD3Q/pub
Thanks, Yekkou. I added the Condition and Action descriptions to the opening post, but had to cut some content. Couldn't fit the general info. Guess that at least gives people some info here and they can click the link for more info or to see if there's updated content. Edit: Here's the General Info: Spoiler: General Info Most of the objects in Forge can be given scripts, up to 8 (previously 7, double check if 8 is now working). Each script contains one condition and one action. The conditions check if certain events occur in the game. Some events are specific to the object, such as spawning or taking damage. Other events are observed by all objects in the game, such as message broadcasts or timer events. When the conditions of a script are met, it executes its action. A couple of actions are universal (sending messages or power changes), but most are object specific and do things like move the object or change its color. Scripts seem to be processed for every game cycle, which is each round of calculations and graphics generation done by the game. In testing, scripts ran 60 times a second (which matches Halo 5's targeted frame rate), though it might vary a little. Conditions Are Checked First During game play, events happen: object spawns, timers occur, objects take damage, players interact with switches, etc. When these happen, the game creates events that the script conditions listen for. In each cycle, the conditions are first checked to see if their events happened. The On Message/Power Multi condition also includes checks for the current States of power channels. If a condition checks for a power channel state to be On or Off, then that condition is true even if the power was set previously. It doesn't have to act like an event that just triggered. Note that at least one of a Multi's conditions needs to be triggered during the previous cycle for the script to activate. Scripts with conditions that check out will have their actions executed after all conditions are checked. Think of it as each script that passes getting put on an execution basket one time. Scripts don't seem to be executed more than one even if their conditions are triggered more than once. Actions Are Executed In Order By Number Seems that each script gets assigned numbers when they are added. It gets assigned the lowest number available and that number doesn't change. That usually means it gets the number than the current highest, which might be one higher than the script count you see on your screen. An exception is when lower numbered scripts are removed. The script numbers are not adjusted and this leaves a lower numbered slot open which gets filled before any higher numbered slots. This is significant when scripts perform opposing actions during the same cycle. The highest number Power Set action wins The lowest number Move or Rotate action wins Damage: Ratio actions accumulate The highest number Spawn or Despawn script wins Message and Power Channels Messages and power channel states are like radio broadcasts that can be heard by all objects in your game, which lets objects in your map communicate with each other. When messages or power status updates are sent, all scripts that contain the On Message: Received, On Power: State, or On Message/Power: Multi conditions will listen and activate their actions when appropriate. You can think of there being a set of channels each for messages and power states, or that the channels can handle both pieces of info separately. These broadcasts are for your customization; the game doesn’t automatically create any broadcasts. There are 26 channels to send these broadcasts over. They are named like the radio message standard for spelling the alphabet: alpha, bravo, charlie… zulu. Both messages and power channel changes behave like events that will be detected by script conditions on the next script cycle check. As of April 2016, there is one behavior where On Message parameters of the Multi conditions seem to be connected to the power state for each channel. See the description of the On Message/Power: Multi condition. Messages Messages are simple events that you can broadcast from any object that can contain scripts. Any script that has On Message: Received conditions will listen for a message broadcast being sent over the channel it is listening to. Power States Each channel has a power state that can be switched On or Off. They have two purposes, listed in the first two items here. They send state change events whenever they switch from Off to On or from On to Off. They maintain and report their On/Off state for On Message/Power: Multi conditions. At the start of a match or Forge session, every channel's power state seems to behave as if it’s Off. Setting it to Off doesn't trigger any scripts. Using the Toggle or On actions turn it On and conditions that listen for On events trigger. Conditions that listen for Off events don't trigger at match start, so the behavior doesn’t seem like the channels are initialized to Off at the start. Various Notes Grouped objects have their own individual scripts. Scripts added to a group are added to each object within. Welding doesn't make any difference. Some objects don't physically spawn so they don't trigger On Spawn/Despawn conditions and Move, Rotate, and Set Velocity actions probably don't work: script brains invisible switches probably more, test objects that can be moved through Scripts generally will work even if the objects they were added to are despawned or never spawned. Decals can be scripted to rotate and Move in Forge, but those scripts don't work in matches. Decals also don't move with other objects when they are part of a welded group in matches. The On Health Below condition doesn't seem to work for some objects: Destructible shields Grenades