Doc_Halo1_UnitExtensions

OpenSauce Unit Extensions

The OpenSauce unit extension adds functionality that allows for a variety of vehicle boarding types. For instance, you can:

• Set up boarding that has the player mount a unit, melee a hatch and then plant a grenade
• Set up boarding that has the player play an animation, kill the seated unit and take control.
• Set up an assassination scenario where the player mounts a unit, can melee the mounted unit, but get's kicked off by the mounted unit.
• Set up an assassination scenario where the player mounts a unit from behind and immediately kills it.

To do this OpenSauce adds a number of complementary features:

• Seat access restrictions
• Seat boarding
• Seat damage
• Unit mounted state

Seat Block

The seat block's flags has an extra option to enable melee attacks whilst in the seat, which you will need to scroll down to see.

When seated melee is enabled and weapons are not, the unit must have a melee animation setup for the seats unarmed weapon type in it's animation tag. The melee animation must also be a replacement animation.

Seat Extensions

The seat extensions block contains options that can help in certain scenarios.

Field	Type	Usage
flags	word flags	See below.
target seat	block index	This is the index of the seat to target when boarding/doing seat damage and such.

Seat extension flags:

Flag	Usage
triggers mounted state	When set, if a unit enters the seat, the unit will enter the mounted state as detailed below.
exit on unit death	When set, if the mounted unit dies (such as as biped), the unit in this seat will exit.
exit on target seat empty	When set, if the seat being targeted becomes empty (from the seated unit dying or exiting), the unit in this seat will exit.
prevent death when unit dies	When set, if the mounted unit dies and tries to kill its riders in the process, the unit in this seat will be unharmed.
ignored by seated ai	When set, the AI in other seats will not react to a unit in this seat. If not set, entering an enemy controlled vehicle can cause the AI to exit their seats.
ignored by mounted ai	When set, the AI controlling the unit will not react to being mounted (such as entering a seat on an AI biped). If not set, the AI can enter a panicked state.
can't enter seats when occupied	When set, if this seat is occupied the unit cannot enter another unit's seat.

Seat Access

The seat access feature adds a number of new criteria that you can use to control when a seat can be entered.

Field	Type	Usage
flags	word flags	See below.
unit sight angle	angle	The cone angle in front of the target unit that the mounting unit must not be in.
unit sight marker	string	The marker on the mounting unit to use when determining if they are in the target unit's cone of vision.
mounting unit sight angle	angle	The cone angle in front of the mounting unit that the target unit must be in.
mounting unit sight marker	string	The marker on the target unit to use when determining if they are in the mounting unit's cone of vision.
unit shield threshold	real fraction	The threshold the target unit's shield must be below for the seat to be available.
unit health threshold	real fraction	The threshold the target unit's health must be below for the seat to be available.
permitted ai states	word flags	When restricted by ai state, the states flagged here allow the seat to be available.

Access flags:

Flag	Usage
requires target seat occupied	When set, the seat will not be usable if the target seat is empty.
enemy access only	When set, the seat will only be usable if the vehicle is an enemy.
restrict by unit sight	When set, the seat is only available if the mounting unit is not within a cone of vision in front of the target unit.
restrict by mounting unit sight	When set, the seat is only available if the target unit is within a cone of vision in front of the mounting unit.
restrict by unit shield	When set, the seat is only available if the target unit's shield is below the specified threshold.
restrict by unit health	When set, the seat is only available if the target unit's health is below the specified threshold.
restrict by ai state	When set, the seat is only available if the target unit's actor is in a permitted state.

Seat Boarding

The seat boarding system allows you to set up scenarios where a unit in a seat can enter another seat and take control of a vehicle.

The boarding state is triggered on the unit in the boarding seat when the boarding criteria have been met. If the boarding type is set to immediate then the boarding state will begin as soon as the unit has finished entering the seat. If set to delayed the unit will stay in the seat until the criteria are met. The boarding state plays the "boarding" animation on the seated unit, which is set up in the unit's animation tag.

Field	Type	Usage
boarding type	enum	Controls whether boarding should occur immediately, or wait for certain criteria to be set.
delay until	word flags	See below.
unit vitality source	enum	When delaying on unit health/shield, controls what unit to use as the health/shield source.
unit shield threshold	real fraction	The threshold the source unit's shield must be below for the seat to be available.
unit health threshold	real fraction	The threshold the source unit's health must be below for the seat to be available.
region name	string	The region that must be destroyed before boarding can take place.

Delay flags:

Flag	Usage
empty target seat	When set, the boarding state will start once the target seat is empty.
unit shield threshold	When set, the boarding state will start once the target unit's shield is below the specified threshold.
unit health threshold	When set, the boarding state will start once the target unit's health is below the specified threshold.
region destroyed	When set, boarding will start once the specified region has been destroyed.

Keyframe Actions

The boarding keyframe actions allow you to trigger a number of events during the boarding animation. The primary and secondary keyframe locations are set up in the unit's animation tag and the final keyframe always occurs at the end of the animation.

When target seat unit action is set to eject the unit, the keyframe will cause the targeted unit to enter it's "ejecting" state and play it's "ejecting" animation.

Field	Type	Usage
keyframe	enum	The keyframe to trigger the action on.
flags	word flags	Controls whether this keyframe should make the boarding unit take control of the powered seat.
self seat action	enum	Controls whether the boarding unit should exit it's current seat or enter the target seat.
target seat unit action	enum	Controls whether the unit in the target seat should just exit or be ejected.
unit door action	enum	Controls whether the unit should be opened or closed.
apply damage to	enum	Controls whether the damage effect should be targeted at the seated unit, the mounted unit, or a specifid region on the mounted unit.
region name	string	Specifies the region the damage effect should be applied to.
damage effect	tag reference	The damage effect to apply.
apply effect to	enum	Controls whether to spawn the effect on the seated unit, or the mounted unit.
effect	tag reference	The effect to spawn.
effect marker	string	The marker to spawn the effect at.

Seat Damage

The seat damage feature allows you redirect melee damage to a seated unit, the mounted unit and/or a specific region on the mounted unit.

If a region name is set then melee damage will be targeted at the mounted unit's region until it's destroyed. Once destroyed damage will be applied to the mounted or seated unit as intended.

Field	Type	Usage
flags	word flags	See below.
melee	enum	Controls whether the players melee should be normal or targeted at a seated/mounted unit.
melee damage effect	tag reference	The damage effect to apply.
grenade	enum	Controls whether grenades shoul be disabled, planted on the seated unit or planted on the mounted unit.
disabled grenade types	word_flags	Sets which grenade types should not be available when in the seat.
grenade detonation time	real	The detonation time of planted grenades.
grenade marker	The marker to attach the grenade to on the seated/mounted unit
region flags	word flags	Controls whether grenades should be disabled whislst the speified region is alive.
region name	string	The name of the region to target.
region damage effect	tag reference	The damage effect to apply to the region (overrides the weapon or unarmed damage effects)

Mounted State

OpenSauce adds a new unit state called the mounted state which is triggered when a seat that has the "trigger mounted state" flag checked is entered. The mounted state will play the "mounted" animation which is set up in the units animation tag. The mounted animation should be a looping animation.

Field	Type	Usage
flags	word flags	If the mounted unit is a player, sets whether their camera should go third person.
camera marker name	string	The marker to use for the third person camera.
camera submerged marker name	string	The marker to use for the third person camera when submerged.
pitch autolevel	real	The pitch that the auto leveling will return to.
pitch range	real bounds	The available pitch range for the third person camera.

Camera Tracks

The camera track blocks are identical to those used in a normal seat. Block 0 is loose, block 1 is tight.

Field	Type	Usage
track	tag reference	The camera track to use.

Keyframe Actions

During the mounted animation you can trigger events using keyframe actions.

Field	Type	Usage
keyframe	enum	The keyframe to trigger on.
flags	word flags	Sets whether to eject the mounting units.
target	enum	Controls whether to target all seats or just seats that can trigger the mounted state.
damage effect	tag reference	The damage effect to apply.
effect	tag reference	The effect to spawn.
effect marker	string	The marker to spawn the effect at.