Skip to main content

CharacterClass

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

A Character is a temporary vessel controlled by a Player or Unit.

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

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

Fields:
TypeNameDescription
CharactercharacterThe Character game object belonging to this class instance.
NetworknetworkA Network object that can be used to send data between client and server.
anydataData from the data entry in the character's JSON file entry.
Callbacks:

Client-only

onProjectile

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

Called when the 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.

onMelee

function CharacterClass.client_onMelee( self, position, attacker, damage, power, direction, normal )
end

Called when the 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 CharacterClass.client_onCollision( self, other, position, selfPointVelocity, otherPointVelocity, normal )
end

Called when the 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.

onGraphicsLoaded

function CharacterClass.client_onGraphicsLoaded( self )
end

Called when graphics are loaded for the Character.

After this, graphics related functions can be called, like accessing animations.

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

onGraphicsUnloaded

function CharacterClass.client_onGraphicsUnloaded( self )
end

Called when graphics are unloaded for the Character.

After this, graphics related functions no longer have any effect or will fail.

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

onInteract

function CharacterClass.client_onInteract( self, character, state )
end

Called when a Player is interacting with the Character by pressing the Use key (default E).

Arguments:
  • self [ table ]: The class instance.
  • character [ Character ]: The Character of the Player that is interacting with this Character.
  • state [ bool ]: The interaction state. Always true. The CharacterClass only receives the key down event.

canInteract

function CharacterClass.client_canInteract( self, character )
return true --true or false, default true if onInteract is implemented
end

Called to check whether the Character can be interacted with at this moment.

note

This callback can also be used to change the interaction text shown to the player using sm.gui.setInteractionText.

Arguments:
  • self [ table ]: The class instance.
  • character [ Character ]: The Character of the Player that is looking at this Character.
Returns:
  • [ bool ]: A boolean indicating whether the character can be interacted with or not. Defaults to true if client_onInteract is implemented, otherwise false.

onEvent

function CharacterClass.client_onEvent( self, event )
end

Called when a Player is interacting with the Character by pressing the Use key (default E).

Called when the Character receives an event from Player:sendCharacterEvent or Unit:sendCharacterEvent.

This is usually for triggering animations on the character.

For more extensive events, see sm.event.sendToCharacter.

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