PlayerClass

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

A player represent a user controlling a Character.

The player script handles actions made by the user.

Can receive events sent with sm.event.sendToPlayer.

Fields

Name	Type	Description
`player`	Player	The Player game object belonging to this class instance.
`network`	Network	A Network object that can be used to send messages between client and server.
`storage`	Storage	(Server side only.) A Storage object that can be used to store data for the next time loading this object after being unloaded.

Server + Client

onCreate

PlayerClass:server_onCreate(  )
PlayerClass:client_onCreate(  )

Called when the scripted object is created. This occurs when a new object is built, spawned, or loaded from the save file.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onDestroy

PlayerClass:server_onDestroy(  )
PlayerClass:client_onDestroy(  )

Called when the scripted object is destroyed.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onRefresh

PlayerClass:server_onRefresh(  )
PlayerClass:client_onRefresh(  )

Called if the Lua script attached to the object is modified while the game is running.

Note: This event requires Scrap Mechanic to be running with the '-dev' flag. This will allow scripts to automatically refresh upon changes.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onFixedUpdate

PlayerClass:server_onFixedUpdate( timeStep )
PlayerClass:client_onFixedUpdate( timeStep )

Called every game tick – 40 ticks a second. If the frame rate is lower than 40 fps, this event may be called twice.

During a fixed update, physics and logic between interactables are updated.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`timeStep`	number	The time period of a tick. (Is always 0.025, a 1/40th of a second.)

Server-only

onReceiveUpdate

PlayerClass:server_onReceiveUpdate(  )

Called occasionally to indicate that some time has passed.

For performance reasons; it recommended to use this instead of server_onFixedUpdate for updates that do not need to happen frequently.

Use sm.game.getCurrentTick to calculate the time.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onProjectile

PlayerClass:server_onProjectile(
    position,
    airTime,
    velocity,
    projectileName,
    shooter,
    damage,
    customData,
    normal,
    uuid,
    mass
)

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

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

Parameters:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the projectile hit the Player's 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`	integer	The damage value of the projectile.
`customData`	any	A Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or an other custom version.
`normal`	Vec3	The normal at the point of impact.
`uuid`	Uuid	The uuid of the projectile.
`mass`	number	The mass of the projectile.

onExplosion

PlayerClass:server_onExplosion( center, destructionLevel, damage )

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

Parameters:

Name	Type	Description
`self`	table	The class instance.
`center`	Vec3	The center of the explosion.
`destructionLevel`	integer	The level of destruction done by this explosion. Corresponds to the 'durability' rating of a Shape.
`damage`	integer	The damage value of the explosion.

onMelee

PlayerClass:server_onMelee(
    position,
    attacker,
    damage,
    power,
    direction,
    normal
)

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

Note: If the attacker is destroyed before the projectile hits, the attacker value will be nil.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the Player's Character was hit.
`attacker`	Player/Unit/nil	The attacker. Can be a Player, Unit or nil if unknown.
`damage`	integer	The damage value of the melee hit.
`power`	number	The physical impact impact of the hit.
`direction`	Vec3	The direction that the melee attack was made.
`normal`	Vec3	The normal at the point of impact.

onCollision

PlayerClass:server_onCollision(
    other,
    position,
    selfPointVelocity,
    otherPointVelocity,
    normal
)

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

Parameters:

Name	Type	Description
`self`	table	The class instance.
`other`	Shape/Character/Harvestable/Lift/nil	The other object. Nil if terrain.
`position`	Vec3	The position in world space where the collision occurred.
`selfPointVelocity`	Vec3	The velocity that that the Player's Character had at the point of collision.
`otherPointVelocity`	Vec3	The velocity that that the other object had at the point of collision.
`normal`	Vec3	The collision normal between the Player's Character and the other other object.

onCollisionCrush

PlayerClass:server_onCollisionCrush(  )

Called when the Player's Character is crushed.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onShapeRemoved

PlayerClass:server_onShapeRemoved( items )

Called when the Player removed a Shape from the World.

Will receive a table of tables listing the items removed by this action.

Element format:

Type	Name	Description
Uuid	uuid	The item uuid.
integer	amount	The amount of items with this uuid.
string	type	Type of shape removed. Can be "part", "block" or "joint".

Parameters:

Name	Type	Description
`self`	table	The class instance.
`items`	table	A table listing the removed items. {{uuid=Uuid, amount=integer, type=string}, ..}

onInventoryChanges

PlayerClass:server_onInventoryChanges( inventory, changes )

Called when the Player has changes in the inventory Container.

Will receive a table listing the changes.

Element format:

Type	Name	Description
Uuid	uuid	The item uuid
integer	difference	The change in amount. Positive numbers mean item gain, negative item loss.
Tool	tool	(Optional) If the item is a Tool, this is the tool. Otherwise nil.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`inventory`	Container	The player's inventory Container.
`changes`	table	A table listing the changes. {{uuid=Uuid, difference=integer, tool=Tool}, ..}

Client-only

onUpdate

PlayerClass:client_onUpdate( deltaTime )

Called every frame.

During a frame update, graphics, animations and effects are updated.

Warning: Because of how frequent this event is called, the game's frame rate is greatly affected by the amount of code executed here. For any non-graphics related code, consider using client_onFixedUpdate instead. If the event is not in use, consider removing it from the script. (Event callbacks that are not implemented will not be called.)

Parameters:

Name	Type	Description
`self`	table	The class instance.
`deltaTime`	number	Delta time since the last frame.

onClientDataUpdate

PlayerClass:client_onClientDataUpdate( data, channel )

Called when the client receives new client data updates from the server set with Network.setClientData.

Data set in this way is persistent and the latest data will automatically be sent to new clients.

The data will arrive after client_onCreate during the same tick.

Channel 1 will be received before channel 2 if both are updated.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`data`	any	Any lua object set with Network.setClientData
`channel`	integer	Client data channel, 1 or 2. (default: 1)

onLocalPlayerChangedWorld

PlayerClass:client_onLocalPlayerChangedWorld( world )

Called when the client player changes world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`world`	World	The entered world.

onInteract

PlayerClass:client_onInteract( character, state )

Called when the player presses or releases the 'Use' key (default 'E').

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Player's Character'. Same as self.player.character.
`state`	boolean	The interaction state. (true if pressed, false if released)

onCancel

PlayerClass:client_onCancel(  )

Called when the player presses the 'Cancel' key (default 'Esc').

Parameters:

Name	Type	Description
`self`	table	The class instance.

onSkipDialog

PlayerClass:client_onSkipDialog(  )

Called when the player presses the 'Cancel' key (default 'Esc') if a dialogue is active and no other gui has focus.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onReload

PlayerClass:client_onReload(  )

Called when the player presses the 'Reload' key (default 'R').

Parameters:

Name	Type	Description
`self`	table	The class instance.