Animation-LuaScripting

Call-outs

The new callouts are defined in the Spring.UnitScript table.

Types for arguments are only shown where they're ambiguous. For a number of (common) arguments, the types are:

• unitID: number
• piece: number
• axis: number (1 = x axis, 2 = y axis, 3 = z axis)
• destination: number (world coors or radians)
• speed: number (world coors or radians per second)
• accel/decel: number (radians per second per frame)

Animation

Spring.UnitScript.SetPieceVisibility ( unitID, piece, boolean visible ) -> nil
Spring.UnitScript.Show ( unitID, piece ) -> nil
Spring.UnitScript.Hide ( unitID, piece ) -> nil

These may be used to show/hide pieces of the unit's model.

Spring.UnitScript.Move ( unitID, piece, axis, destination[, speed] ) -> nil

Move piece along axis to the destination position. If speed is given, the piece isn't moved immediately, but will move there at the desired speed. The X axis is mirrored compared to BOS/COB scripts, to match the direction of the X axis in Spring world space.

Spring.UnitScript.Turn ( unitID, piece, axis, destination[, speed] ) -> nil

Turn piece around axis to the destination angle. If speed is given, the piece isn't rotated immediately, but will turn at the desired angular velocity. Angles are in radians.

Spring.UnitScript.Spin ( unitID, piece, axis, speed[, accel] ) -> nil

Makes piece spin around axis at the desired angular velocity. If accel is given, the piece does not start at this velocity at once, but will accelerate to it. Both negative and positive angular velocities are supported. Accel should always be positive, even if speed is negative.

Spring.UnitScript.StopSpin ( unitID, piece, axis[, decel] ) -> nil

Stops a piece from spinning around the given axis. If decel is given, the piece does not stop at once, but will decelerate to it. Decel should always be positive. This function is similar to Spin(unitID, piece, axis, 0, decel), however, StopSpin also frees up the animation record.

Spring.UnitScript.IsMoving ( unitID, piece, axis ) -> boolean
Spring.UnitScript.IsTurning ( unitID, piece, axis ) -> boolean
Spring.UnitScript.IsSpinning ( unitID, piece, axis ) -> boolean

Returns true iff the piece is moving along the axis, or turning/spinning around the axis.

Spring.UnitScript.WaitForMove ( unitID, piece, axis ) -> nil
Spring.UnitScript.WaitForTurn ( unitID, piece, axis ) -> nil

Waits until the piece has stopped moving along / turning around the axis. If the piece is not animating, this functions return at once. You can not wait for a spin, because a spin does never finish.

Spring.UnitScript.Sleep ( unitID, milliseconds ) -> nil

Waits a number of milliseconds before returning.

Spring.UnitScript.StartThread ( unitID, function fun, ... ) -> nil

Starts a new (animation) thread, which will execute the function 'fun'. All arguments after the function are passed as-is as arguments to 'fun'. A thread is just a Lua thread, ie. a coroutine, so please refer to the Lua documentation about coroutines for exact semantics.

Effects

Spring.UnitScript.EmitSfx ( unitID, piece, id ) -> nil

Emits a particle from the given piece. The id may be one of: TODO

Spring.UnitScript.Explode ( unitID, piece, flags ) -> nil

Explodes a piece, optionally creating a particle which flies off. Typically used inside Killed. Explode does not hide the piece by itself; if using it outside Killed you may want to Hide the piece immediately after. The flags may be a combination of: TODO

Other

Spring.UnitScript.AttachUnit ( unitID, piece, passengerID ) -> nil
Spring.UnitScript.DetachUnit ( unitID, passengerID ) -> nil

Attaches or detaches another unit (a passenger, as this is designed for transports) to this unit. For AttachUnit, piece specifies the attachment point.

Spring.UnitScript.GetUnitValue ( ... ) -> number | number, number
Spring.UnitScript.SetUnitValue ( ... ) -> nil

This may be used instead of COB's get and set codes. It is recommended however, to use dedicated Lua functions (e.g. Spring.GetUnitHealth(unitID) instead of GetUnitValue(unitID, 4)): these functions should be considered a relic of the past.

Note that these are identical to Spring.GetUnitCOBValue and Spring.SetUnitCOBValue (see also Lua_SyncedCtrl#Lua_to_COB for the signature of those functions.)

Spring.UnitScript.SetSignalMask ( unitID, mask ) -> nil
Spring.UnitScript.Signal ( unitID, signal ) -> nil

These two support functions offer a powerful way to kill running threads. SetSignalMask assigns a mask to the currently running thread (any new threads started by this one will inherit the signal mask). Signal immediately stops all threads of this unit for which the bitwise and of mask and signal is not zero.

Call-ins

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular “event” happens.

For Lua unit scripts, a new callin mechanism has been implemented, which is faster than the regular callin mechanism which is used for widgets and gadgets.

Generic

Create ( unitID ) -> nil

This is called just after the unit script has been created.

StartMoving ( unitID ) -> nil
StopMoving ( unitID ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation.

Killed ( unitID, recentDamage, maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth. Typically, this function would play a death animation for the unit, and finally return a corpse type.

QueryNanopiece ( unitID ) -> number piece

Called for factories and builders each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

Weapons

QueryWeapon1 ( unitID ) -> number piece
AimFromWeapon1 ( unitID ) -> number piece
AimWeapon1 ( unitID, heading, pitch ) -> boolean
FireWeapon1 ( unitID ) -> nil

Weapon support. The suffix "1" should be replaced with the actual weapon number. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired, in which case FireWeapon will be called, to inform the script about this. FireWeapon may play a recoil animation or emit some smoke using EmitSfx, for example.

TODO: better explanation (?), note about AimWeapon being called very often etc.

RockUnit ( unitID, x, z ) -> nil

A bit like the weapon-specific FireWeapon function, this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to “rock” the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truely realistic rock direction it needs to be rotated according to the unit's current heading.