Character
Associated namespace: sm.character
A userdata object representing a character in the game.
Values:
- clientPublicData
- color
- direction
- id
- mass
- movementSpeedFraction
- publicData
- smoothDirection
- velocity
- world
- worldPosition
Functions:
- addRenderable
- applyTumblingImpulse
- bindAnimationCallback
- getActiveAnimations
- getAnimationInfo
- getCanSwim
- getCharacterType
- getClientPublicData
- getColor
- getCurrentMovementNoiseRadius
- getCurrentMovementSpeed
- getDirection
- getGlowMultiplier
- getHeight
- getId
- getImmovable
- getJumpSpeedFraction
- getLockingHarvestable
- getLockingInteractable
- getMass
- getMoveSpeed
- getMovementSpeedFraction
- getPlayer
- getPublicData
- getRadius
- getSmoothViewDirection
- getSprintSpeed
- getSurfaceNormal
- getTpBonePos
- getTpBoneRot
- getTumblingAngularVelocity
- getTumblingExtent
- getTumblingLinearVelocity
- getTumblingWorldPosition
- getTumblingWorldRotation
- getUnit
- getVelocity
- getWorld
- getWorldPosition
- hasActiveOverrideAnimation
- hasGraphics
- isAiming
- isClimbing
- isCrouching
- isDefaultColor
- isDiving
- isDowned
- isFlying
- isHovering
- isLadderClimbing
- isMoving
- isOnGround
- isPlayer
- isSeated
- isSprinting
- isSwimming
- isTumbling
- isVisible
- overrideRenderableList
- removeAnimationCallbacks
- removeRenderable
- setAllowTumbleAnimations
- setClientPublicData
- setClimbing
- setColor
- setDiving
- setDowned
- setFlying
- setGlowMultiplier
- setHovering
- setImmovable
- setJumpSpeedFraction
- setLockingHarvestable
- setLockingInteractable
- setMovementEffects
- setMovementSpeedFraction
- setMovementWeights
- setNameTag
- setPublicData
- setSwimming
- setTumbling
- setUpDirection
- setVisible
- setWorldPosition
- updateAnimation
Operations:
| Operation | Return type | Description |
|---|---|---|
| Character == Character | boolean | Checks if two instances of Character refer to the same Character. |
clientPublicData table
Get:
Client only
Returns client public data from a character.
Set:
Client only
Sets client public data on a character.
color Color
Get:
Returns the base color of a character.
Set:
Server only
Sets the character color.
direction Vec3
Get:
Returns the direction of where a character is viewing or aiming.
id integer
Get:
Returns the id of a character.
mass number
Get:
Returns the mass of a character.
movementSpeedFraction number
Get:
Gets the current fraction multiplier applied on the character's movement speed.
Set:
Sets a fraction multiplier to the character's movement speed.
publicData table
Get:
Server only
Returns (server) public data from a character.
Set:
Server only
Sets (server) public data on a character.
smoothDirection Vec3
Get:
Returns the smooth direction of where a character is viewing or aiming.
velocity Vec3
Get:
Returns the velocity of a character.
world World
Get:
Returns the world a character exists in.
worldPosition Vec3
Get:
Returns the world position of a character.
Set:
Server only
Sets the world position of a character.
addRenderable(character, renderable)
Client only
Adds a renderable (file containing model data) to be used for the character in third person view.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | renderable | The renderable path. |
applyTumblingImpulse(character, impulse, offset?)
Applies impulse to the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Vec3 | impulse | The impulse. |
| Vec3 | offset? | The offset from the center point. (Defaults to no offset) |
bindAnimationCallback(character, animationName, triggerTime, callback)
Binds a character's animation to a callback function.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | animationName | The name of the animation. |
| number | triggerTime | The required time that will have elapsed in the animation when the callback is triggered. |
| string | callback | The name of the Lua function to bind. |
getActiveAnimations(character)
Returns the set of active animations.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| table | The set of active animations { { name = string, weight = number }, ...} |
getAnimationInfo(character, name)
Client only
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | name | The name. |
Returns:
| Type | Description |
|---|---|
| table | The animation info { name = string, duration = number, looping = boolean }. |
getCanSwim(character)
Returns whether the character will float or sink in liquid.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the character will float, false if the character will sink. |
getCharacterType(character)
Returns the uuid of the character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Uuid | The character type. |
getClientPublicData(character)
Client only
Returns client public data from a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| table | The client public data. |
getColor(character)
Returns the base color of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Color | The character color. |
getCurrentMovementNoiseRadius(character)
Returns the radius around the character where it can be heard.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The noise radius of the character. |
getCurrentMovementSpeed(character)
Returns the current movement speed of the character depending on state and multiplier.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The current movement speed. |
getDirection(character)
Returns the direction of where a character is viewing or aiming.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The character's view direction. |
getGlowMultiplier(character)
Client only
Gets the glow multiplier.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The glow multiplier (0.0 - 1.0). |
getHeight(character)
Returns the height of a character
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The character's height. |
getId(character)
Returns the id of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| integer | The character's id. |
getImmovable(character)
Server only
Returns whether a non-player character is immovable,
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The immovable state of the character. |
getJumpSpeedFraction(character)
Gets the current fraction multiplier applied on the character's jump speed.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The jump speed fraction. |
getLockingHarvestable(character)
Get the Harvestable that the Character is locked to.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Harvestable | The harvestable. |
getLockingInteractable(character)
Get the Interactable that the Character is locked to.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Interactable | The interactable. |
getMass(character)
Returns the mass of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The character's mass. |
getMoveSpeed(character)
Returns the move speed of a character
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The character's move speed. |
getMovementSpeedFraction(character)
Gets the current fraction multiplier applied on the character's movement speed.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The movement speed fraction. |
getPlayer(character)
Returns the player controlling the character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Player | The player controlling the character. |
getPublicData(character)
Server only
Returns (server) public data from a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| table | The public data. |
getRadius(character)
Returns the radius of a character
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The character's radius. |
getSmoothViewDirection(character)
Returns the smooth direction of where a character is viewing or aiming.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The character's smooth view direction. |
getSprintSpeed(character)
Returns the sprint speed of a character
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| number | The character's sprint speed. |
getSurfaceNormal(character)
Returns the normal of the character's contact with a surface. Defaults to a zero vector when no contact is found.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The surface normal. |
getTpBonePos(character, jointName)
Returns the world position for a bone in the third person view animation skeleton.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | jointName | The joint name. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The joint position. |
getTpBoneRot(character, jointName)
Returns the world rotation for a bone in the third person view animation skeleton.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | jointName | The joint name. |
Returns:
| Type | Description |
|---|---|
| Quat | The joint rotation. |
getTumblingAngularVelocity(character)
Returns the angular velocity of the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The tumbling shape's angular velocity. |
getTumblingExtent(character)
Returns the extent of the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The tumbling shape's extent. |
getTumblingLinearVelocity(character)
Returns the linear velocity of the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The tumbling shape's linear velocity. |
getTumblingWorldPosition(character)
Returns the world position of the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The tumbling shape's world position. |
getTumblingWorldRotation(character)
Returns the world rotation of the characters tumbling shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Quat | The tumbling shape's world rotation. |
getUnit(character)
Returns the unit controlling the character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Unit | The unit controlling the character. |
getVelocity(character)
Returns the velocity of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The character's velocity. |
getWorld(character)
Returns the world a character exists in.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| World | The world the character exists in. |
getWorldPosition(character)
Returns the world position of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The character's world position. |
hasActiveOverrideAnimation(player)
Client only
Returns whether or not the character has an active animation override on its third person animations.
A third person animation override could be the crowbar animation when picking something up or the hammer when placing something.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | player | The player. |
Returns:
| Type | Description |
|---|---|
| bool | Has active animation override. |
hasGraphics(character)
Client only
Checks if a character has graphics.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character has graphics. |
isAiming(character)
Returns whether a character is currently aiming with a weapon.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is aiming. |
isClimbing(character)
Get the character climbing state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The climbing state. |
isCrouching(character)
Returns whether a character is currently crouching.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is crouching. |
isDefaultColor(character)
Returns true if the current character color is its default color.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the color is the base color. |
isDiving(character)
Get the character diving state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The diving state. |
isDowned(character)
Get the character downed state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The downed state. |
isFlying(character)
Get the character flying state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The flying state. |
isHovering(character)
Get the character hovering state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The hovering state. |
isLadderClimbing(character)
Get whether the character is climbing a ladder.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The ladder climbing state. |
isMoving(character)
Returns whether a character is currently moving.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is moving. |
isOnGround(character)
Returns whether the character is currently standing on the ground.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is on the ground. |
isPlayer(character)
Returns whether a character is owned by a player.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is owned by a player. |
isSeated(character)
Returns whether the character is currently seated.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is seated. |
isSprinting(character)
Returns whether a character is currently sprinting.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is sprinting. |
isSwimming(character)
Get the character swimming state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The swimming state. |
isTumbling(character)
Get the character tumbling state.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | The tumbling state. |
isVisible(character)
Client only
Returns whether a character is visible.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the character is visible. |
overrideRenderableList(character, renderables)
Client only
Overrides a non player character's third person renderable list with a new list of renderables. Will trigger a rebuild of the character's graphics.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| table | renderables | An array of renderable file paths to override with. |
removeAnimationCallbacks(character)
Removes all of a character's animation callbacks.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
removeRenderable(character, renderable)
Client only
Removes a renderable (file containing model data) that was used for the character in third person view.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | renderable | The renderable path. |
setAllowTumbleAnimations(character, allow)
Client only
Enables or disables event animations.
When set to false no animations can play while tumble is active, and when set to true the animations will play while tumbling.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | allow | The state. |
setClientPublicData(character, data)
Client only
Sets client public data on a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| table | data | The client public data. |
setClimbing(character, state)
Server only
Sets whether the character is climbing.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The climbing state. |
setColor(character, color)
Server only
Sets the character color.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Color | color | The character color. |
setDiving(character, state)
Server only
Sets whether the character is diving.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The diving state. |
setDowned(character, state)
Server only
Sets whether the character is downed.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The downed state. |
setFlying(character, state)
Server only
Sets whether the character is flying.
Will not activate flight for player characters.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The flying state. |
setGlowMultiplier(character, value)
Client only
Sets a value to multiply the glow from asg texture with.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| number | value | The glow multiplier (0.0 - 1.0). |
setHovering(character, state)
Server only
Sets whether the character is hovering.
Will not activate hover for player characters.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The hovering state. |
setImmovable(character, enable)
Server only
Sets the immovable state on a non-player character. This prevents the character from updating its physics.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | enable | Set immovable state. |
setJumpSpeedFraction(character, fraction)
Sets a fraction multiplier to the character's jump speed.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| number | fraction | The jump speed fraction. |
setLockingHarvestable(character, harvestable)
Set the Harvestable that the Character is locked to. Set Harvestable to nil to unlock.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Harvestable | harvestable | The harvestable. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the character was successfully locked or unlocked. |
setLockingInteractable(character, interactable)
Set the Interactable that the Character is locked to. Set Interactable to nil to unlock.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Interactable | interactable | The interactable. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the character was successfully locked or unlocked. |
setMovementEffects(character, filepath)
Sets the movement effect set filepath.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | filepath | The effect set filepath. |
setMovementSpeedFraction(character, fraction)
Sets a fraction multiplier to the character's movement speed.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| number | fraction | The movement speed fraction. |
setMovementWeights(character, lower, upper)
Client only
Sets the weights for movement animations on a character's upper and lower body.
For a value of 0 no movement animations will play, and for a value of 1 the movement animations will fully play unless otherwise overridden.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| number | lower | The lower weight. |
| number | upper | The upper weight. |
setNameTag(character, name, color?, requiresLoS?, renderDistance?, fadeDistance?)
Client only
Sets the name tag display value for the character
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | name | The new name tag text value. |
| Color | color? | The color of the name. (defaults to white) |
| boolean | requiresLoS? | Whether broken line of sight will hide the name tag. (Defaults to false) |
| number | renderDistance? | Max distance the name tag will render in. (Defaults to 10000) |
| number | fadeDistance? | Distance where fade out will start. (Defaults to 9500) |
setPublicData(character, data)
Server only
Sets (server) public data on a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| table | data | The public data. |
setSwimming(character, state)
Server only
Sets whether the character is swimming.
Note:
By default the swimming state is controlled by the client as part of the player movement. This value is treated like an override that is synchronized from the server. Buoyancy calculations in the character controller require that the character touches a liquid volume.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The swimming state. |
setTumbling(character, state)
Server only
Sets whether the character is tumbling.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | state | The tumbling state. |
setUpDirection(character, up)
Client only
Sets the upward direction of the character's graphics.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Vec3 | up | The direction. |
setVisible(character, visible)
Client only
Sets the visibility.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| boolean | visible | Whether the character should be visible. |
setWorldPosition(character, position)
Server only
Sets the world position of a character.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| Vec3 | position | The character's new world position. |
updateAnimation(character, name, time, weight?, additive?)
Client only
Updates a character animation.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | character | The character. |
| string | name | The animation name. |
| number | time | The time. |
| number | weight? | The weight. Defaults to -1.0. (Optional) |
| boolean | additive? | Whether the animation will be added to the default animation. Defaults to false. (Optional) |