Module LuaHandleSynced

Callins, functions called by the Engine (Synced)

See also:

Misc

RecvFromSynced
Receives data sent via SendToUnsynced callout.

Custom Object Rendering

DrawUnit
For custom rendering of units
DrawFeature
For custom rendering of features
DrawShield
For custom rendering of shields.
DrawProjectile
For custom rendering of weapon (& other) projectiles
DrawMaterial
CommandFallback
Called when the unit reaches an unknown command in its queue (i.e.
AllowCommand
Called when the command is given, before the unit's queue is altered.
AllowUnitCreation
Called just before unit is created.
AllowUnitTransfer
Called just before a unit is transferred to a different team.
AllowUnitBuildStep
Called just before a unit progresses its build percentage.
AllowUnitCaptureStep
AllowUnitTransport
AllowUnitTransportLoad
AllowUnitTransportUnload
AllowUnitCloak
AllowUnitCloak
AllowUnitKamikaze
AllowFeatureCreation
Called just before feature is created.
AllowFeatureBuildStep
Called just before a feature changes its build percentage.
AllowResourceLevel
Called when a team sets the sharing level of a resource.
AllowResourceTransfer
Called just before resources are transferred between players.
AllowDirectUnitControl
Determines if this unit can be controlled directly in FPS view.
AllowBuilderHoldFire
Called when a construction unit wants to "use his nano beams".
AllowStartPosition
Whether a start position should be allowed
MoveCtrlNotify
Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.
TerraformComplete
Called when pre-building terrain levelling terraforms are completed (c.f.
UnitPreDamaged
Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.
FeaturePreDamaged
Called before damage is applied to the feature.
ShieldPreDamaged
Called before any engine shield-vs-projectile logic executes.
AllowWeaponTargetCheck
Determines if this weapon can automatically generate targets itself.
AllowWeaponTarget
Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep.
AllowWeaponInterceptTarget
Controls blocking of a specific intercept target from being considered during an interceptor weapon's periodic auto-targeting sweep.

Misc

RecvFromSynced(arg1, arg2, argn)

Receives data sent via `SendToUnsynced` callout.

Parameters:

  1. arg1 any
  2. arg2 any
  3. argn any

Custom Object Rendering

For the following calls drawMode can be one of the following, notDrawing = 0, normalDraw = 1, shadowDraw = 2, reflectionDraw = 3, refractionDraw = 4, and finally gameDeferredDraw = 5 which was added in 102.0.

DrawUnit(unitID, drawMode)

For custom rendering of units

Parameters:

  1. unitID number
  2. drawMode number

Returns:

  1. bool suppressEngineDraw

DrawFeature(featureID, drawMode)

For custom rendering of features

Parameters:

  1. featureID number
  2. drawMode number

Returns:

  1. bool suppressEngineDraw

DrawShield(featureID, weaponID, drawMode)

For custom rendering of shields.

Parameters:

  1. featureID number
  2. weaponID number
  3. drawMode number

Returns:

  1. bool suppressEngineDraw

DrawProjectile(projectileID, drawMode)

For custom rendering of weapon (& other) projectiles

Parameters:

  1. projectileID number
  2. drawMode number

Returns:

  1. bool suppressEngineDraw

DrawMaterial(uuid, drawMode)

Parameters:

  1. uuid number
  2. drawMode number

Returns:

  1. bool suppressEngineDraw

CommandFallback(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag)

Called when the unit reaches an unknown command in its queue (i.e.

one not handled by the engine).

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. cmdID number
  5. cmdParams {number,...}
  6. cmdOptions cmdOptions
  7. cmdTag number

Returns:

  1. boolean whether to remove the command from the queue

AllowCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced, fromLua)

Called when the command is given, before the unit's queue is altered.

The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. cmdID number
  5. cmdParams {number,...}
  6. cmdOptions cmdOptions
  7. cmdTag number
  8. synced bool
  9. fromLua bool

Returns:

  1. bool whether it should be let into the queue.

AllowUnitCreation(unitDefID, builderID, builderTeam, x, y, z, facing)

Called just before unit is created.

Parameters:

  1. unitDefID number
  2. builderID number
  3. builderTeam number
  4. x number
  5. y number
  6. z number
  7. facing number

Returns:

  1. bool allow, bool dropOrder

AllowUnitTransfer(unitID, unitDefID, oldTeam, newTeam, capture)

Called just before a unit is transferred to a different team.

Parameters:

  1. unitID number
  2. unitDefID number
  3. oldTeam number
  4. newTeam number
  5. capture bool

Returns:

  1. bool whether or not the transfer is permitted.

AllowUnitBuildStep(builderID, builderTeam, unitID, unitDefID, part)

Called just before a unit progresses its build percentage.

Parameters:

  1. builderID number
  2. builderTeam number
  3. unitID number
  4. unitDefID number
  5. part number

Returns:

  1. bool whether or not the build makes progress.

AllowUnitCaptureStep(builderID, builderTeam, unitID, unitDefID, part)

Parameters:

  1. builderID number
  2. builderTeam number
  3. unitID number
  4. unitDefID number
  5. part number

Returns:

  1. bool whether or not the capture makes progress.

AllowUnitTransport(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam)

Parameters:

  1. transporterID number
  2. transporterUnitDefID number
  3. transporterTeam number
  4. transporteeID number
  5. transporteeUnitDefID number
  6. transporteeTeam number

Returns:

  1. bool whether or not the transport is allowed

AllowUnitTransportLoad(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam, x, y, z)

Parameters:

  1. transporterID number
  2. transporterUnitDefID number
  3. transporterTeam number
  4. transporteeID number
  5. transporteeUnitDefID number
  6. transporteeTeam number
  7. x number
  8. y number
  9. z number

Returns:

  1. bool whether or not the transport load is allowed

AllowUnitTransportUnload(transporterID, transporterUnitDefID, transporterTeam, transporteeID, transporteeUnitDefID, transporteeTeam, x, y, z)

Parameters:

  1. transporterID number
  2. transporterUnitDefID number
  3. transporterTeam number
  4. transporteeID number
  5. transporteeUnitDefID number
  6. transporteeTeam number
  7. x number
  8. y number
  9. z number

Returns:

  1. bool whether or not the transport unload is allowed

AllowUnitCloak(unitID[, enemyID])

Parameters:

  1. unitID number
  2. enemyID number (optional)

Returns:

  1. bool whether unit is allowed to cloak

AllowUnitCloak(unitID[, objectID[, weaponNum]])

Parameters:

  1. unitID number
  2. objectID number (optional)
  3. weaponNum number (optional)

Returns:

  1. bool whether unit is allowed to decloak

AllowUnitKamikaze(unitID, targetID)

Parameters:

  1. unitID number
  2. targetID number

Returns:

  1. bool whether unit is allowed to selfd

AllowFeatureCreation(featureDefID, teamID, x, y, z)

Called just before feature is created.

Parameters:

  1. featureDefID number
  2. teamID number
  3. x number
  4. y number
  5. z number

Returns:

  1. bool whether or not the creation is permitted

AllowFeatureBuildStep(builderID, builderTeam, featureID, featureDefID, part)

Called just before a feature changes its build percentage.

Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and ressurect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that's a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.

Parameters:

  1. builderID number
  2. builderTeam number
  3. featureID number
  4. featureDefID number
  5. part number

Returns:

  1. bool whether or not the change is permitted

AllowResourceLevel(teamID, res, level)

Called when a team sets the sharing level of a resource.

Parameters:

  1. teamID number
  2. res string
  3. level number

Returns:

  1. bool whether or not the sharing level is permitted

AllowResourceTransfer(oldTeamID, newTeamID, res, amount)

Called just before resources are transferred between players.

Parameters:

  1. oldTeamID number
  2. newTeamID number
  3. res string
  4. amount number

Returns:

  1. bool whether or not the transfer is permitted.

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID)

Determines if this unit can be controlled directly in FPS view.

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. playerID number

Returns:

  1. bool allow

AllowBuilderHoldFire(unitID, unitDefID, action)

Called when a construction unit wants to "use his nano beams".

Parameters:

  1. unitID number
  2. unitDefID number
  3. action number one of following:

    -1 Build CMD.REPAIR Repair CMD.RECLAIM Reclaim CMD.RESTORE Restore CMD.RESURRECT Resurrect CMD.CAPTURE Capture

Returns:

  1. bool actionAllowed

AllowStartPosition(playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ)

Whether a start position should be allowed

clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker. The readyState can be any one of: 0 - player picked a position, 1 - player clicked ready, 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or 3 - the player failed to load. The default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

Parameters:

  1. playerID number
  2. teamID number
  3. readyState number
  4. clampedX number
  5. clampedY number
  6. clampedZ number
  7. rawX number
  8. rawY number
  9. rawZ number

Returns:

  1. bool allow

MoveCtrlNotify(unitID, unitDefID, unitTeam, data)

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in.

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. data number was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground").

Returns:

  1. bool whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true).

TerraformComplete(unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam)

Called when pre-building terrain levelling terraforms are completed (c.f.

levelGround)

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. buildUnitID number
  5. buildUnitDefID number
  6. buildUnitTeam number

Returns:

  1. bool if true the current build order is terminated

UnitPreDamaged(unitID, unitDefID, unitTeam, damage, paralyzer[, weaponDefID[, projectileID[, attackerID[, attackerDefID[, attackerTeam]]]]])

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

Called after every damage modification (even `HitByWeaponId`) but before the damage is applied expects two numbers returned by lua code: 1st is stored under *newDamage if newDamage != NULL 2nd is stored under *impulseMult if impulseMult != NULL

Parameters:

  1. unitID number
  2. unitDefID number
  3. unitTeam number
  4. damage number
  5. paralyzer bool
  6. weaponDefID number Synced Only (optional)
  7. projectileID number Synced Only (optional)
  8. attackerID number Synced Only (optional)
  9. attackerDefID number Synced Only (optional)
  10. attackerTeam number Synced Only (optional)

Returns:

  1. number newDamage, number impulseMult

FeaturePreDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called before damage is applied to the feature.

Allows fine control over how much damage and impulse is applied.

Parameters:

  1. featureID number
  2. featureDefID number
  3. featureTeam number
  4. damage number
  5. weaponDefID number
  6. projectileID number
  7. attackerID number
  8. attackerDefID number
  9. attackerTeam number

Returns:

  1. number newDamage
  2. number impulseMult

ShieldPreDamaged(projectileID, projectileOwnerID, shieldWeaponNum, shieldCarrierID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ)

Called before any engine shield-vs-projectile logic executes.

If the weapon is a hitscan type (BeamLaser or LightningCanon) then proID is nil and beamEmitterWeaponNum and beamEmitterUnitID are populated instead.

Parameters:

  1. projectileID number
  2. projectileOwnerID number
  3. shieldWeaponNum number
  4. shieldCarrierID number
  5. bounceProjectile bool
  6. beamEmitterWeaponNum number
  7. beamEmitterUnitID number
  8. startX number
  9. startY number
  10. startZ number
  11. hitX number
  12. hitY number
  13. hitZ number

Returns:

  1. bool if true the gadget handles the collision event and the engine does not remove the projectile

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)

Determines if this weapon can automatically generate targets itself.

See also commandFire weaponDef tag.

Parameters:

  1. attackerID number
  2. attackerWeaponNum number
  3. attackerWeaponDefID number

Returns:

  1. bool allowCheck
  2. bool ignoreCheck

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)

Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep.

Parameters:

  1. attackerID number
  2. targetID number
  3. attackerWeaponNum number
  4. attackerWeaponDefID number
  5. defPriority number

Returns:

  1. bool allowed
  2. number the new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first.

AllowWeaponInterceptTarget(interceptorUnitID, interceptorWeaponID, targetProjectileID)

Controls blocking of a specific intercept target from being considered during an interceptor weapon's periodic auto-targeting sweep.

Only called for weaponDefIDs registered via Script.SetWatchWeapon.

Parameters:

  1. interceptorUnitID number
  2. interceptorWeaponID number
  3. targetProjectileID number

Returns:

  1. bool allowed