Skip to main content

UnitClass​

A script class that is instanced for every Unit in the game.

A unit represents an AI controlling a Character.

The unit script runs only on the server.

The class can receive events sent with sm.event.sendToUnit.

The fields below are accessed using self.fieldName in the UnitClass script:

Fields:
TypeNameDescription
UnitunitThe Unit game object belonging to this class instance.
StoragestorageA server-side Storage object that can be used to save and load data to/from the world database.
anydataData from the data entry in the unit character's JSON file entry.
anyparamsParameters passed to sm.unit.createUnit
Constants:

isSaveObject

Callbacks:

Server-only​

onProjectile​

function UnitClass.server_onProjectile( self, position, airTime, velocity, projectileName, shooter, damage, customData, normal, uuid )
end

Called when the Unit's Character is hit by a projectile.

note

If the shooter is destroyed before the projectile hits, the shooter value will be nil.

Arguments:
  • self [ table ]: The class instance.
  • position [ Vec3 ]: The position in world space where the projectile hit the Character.
  • airTime [ number ]: The time, in seconds, that the projectile spent flying before the hit.
  • velocity [ Vec3 ]: The velocity of the projectile at impact.
  • projectileName [ string ]: The name of the projectile. (Legacy, use uuid instead)
  • shooter [ Player / Unit / Shape / Harvestable / nil ]: The shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
  • damage [ int ]: The damage value of the projectile.
  • customData [ any ]: A Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or any other custom version.
  • normal [ Vec3 ]: The normal at the point of impact.
  • uuid [ Uuid ]: The uuid of the projectile.

onExplosion​

function UnitClass.server_onExplosion( self, center, destructionLevel )
end

Called when the Unit's Character is hit by an explosion.

Arguments:
  • self [ table ]: The class instance.
  • center [ Vec3 ]: The center of the explosion.
  • destructionLevel [ int ]: The level of destruction done by this explosion. Corresponds to the durability rating of a Shape.

onMelee​

function UnitClass.server_onMelee( self, position, attacker, damage, power, direction, normal )
end

Called when the Unit's Character is hit by a melee attack.

note

If the attacker is destroyed before the hit lands, the attacker value will be nil.

Arguments:
  • self [ table ]: The class instance.
  • position [ Vec3 ]: The position in world space where the Character was hit.
  • attacker [ Player / nil ]: The attacker. Can be a Player or nil if unknown. Attacks made by a Unit will be nil on the client.
  • damage [ int ]: The damage value of the melee hit.
  • power [ number ]: The physical impact of the hit.
  • direction [ Vec3 ]: The direction of the melee attack.
  • normal [ Vec3 ]: The normal at the point of impact.

onCollision​

function UnitClass.server_onCollision( self, other, position, selfPointVelocity, otherPointVelocity, normal )
end

Called when the Unit's Character collides with another object.

Arguments:
  • self [ table ]: The class instance.
  • other [ Shape / Character / Harvestable / Lift / nil ]: The other object. Nil if terrain.
  • position [ Player / nil ]: The position in world space where the collision occurred.
  • selfPointVelocity [ int ]: The velocity that that the Character had at the point of collision.
  • otherPointVelocity [ number ]: The velocity that that the other object had at the point of collision.
  • normal [ Vec3 ]: The collision normal between the Character and the other object.

onCollisionCrush​

function UnitClass.server_onCollisionCrush( self )
end

Called when the Unit's Character is being crushed.

Arguments:
  • self [ table ]: The class instance.

onUnitUpdate​

function UnitClass.server_onUnitUpdate( self, deltaTime )
end

Called occasionally for units based on how many units are active.

It is recommended to do heavier AI decisions here instead of in server_onFixedUpdate.

Arguments:
  • self [ table ]: The class instance.
  • deltaTime [ number ]: The time, in seconds, since server_onUnitUpdate was last called for this Unit.

onCharacterChangedColor​

function UnitClass.server_onCharacterChangedColor( self, color )
end

Called occasionally for units based on how many units are active. Called when the Unit Character's color is changed. The color can be changed by painting, set using Character:setColor or by modifying Character.color.

Arguments:
  • self [ table ]: The class instance.
  • color [ Color ]: The new Color of the Unit's Character.