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:

TypeNameDescription
PlayerplayerThe Player game object belonging to this class instance.
NetworknetworkA Network object that can be used to send messages between client and server.
Storagestorage(Server side only.) A Storage object that can be used to store data for the next time loading this object after being unloaded.

Common callbacks:

Callbacks:


server_onCreate(self) serverEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onCreate(self) clientEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onDestroy(self) serverEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onDestroy(self) clientEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onRefresh(self) serverEventCallback

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:

TypeNameDescription
tableselfThe class instance.

client_onRefresh(self) clientEventCallback

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:

TypeNameDescription
tableselfThe class instance.

server_onFixedUpdate(self, timeStep) serverEventCallback

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:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe time period of a tick. (Is always 0.025, a 1/40th of a second.)

client_onFixedUpdate(self, timeStep) clientEventCallback

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:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe time period of a tick. (Is always 0.025, a 1/40th of a second.)

client_onUpdate(self, deltaTime) clientEventCallback

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:

TypeNameDescription
tableselfThe class instance.
numberdeltaTimeDelta time since the last frame.

client_onClientDataUpdate(self, data, channel) clientEventCallback

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:

TypeNameDescription
tableselfThe class instance.
anydataAny lua object set with Network.setClientData
integerchannelClient data channel, 1 or 2. (default: 1)

client_onInteract(self, character, state) clientEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.
CharactercharacterThe Player's Character'. Same as self.player.character.
booleanstateThe interaction state. (true if pressed, false if released)

client_onCancel(self) clientEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onReload(self) clientEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onProjectile(self, position, airTime, velocity, projectileName, shooter, damage, customData, normal, uuid) serverEventCallback

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:

TypeNameDescription
tableselfThe class instance.
Vec3positionThe position in world space where the projectile hit the Player's Character.
numberairTimeThe time, in seconds, that the projectile spent flying before the hit.
Vec3velocityThe velocity of the projectile at impact.
stringprojectileNameThe name of the projectile. (Legacy, use uuid instead)
Player/Unit/Shape/Harvestable/nilshooterThe shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
integerdamageThe damage value of the projectile.
anycustomDataA Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or an other custom version.
Vec3normalThe normal at the point of impact.
UuiduuidThe uuid of the projectile.

server_onExplosion(self, center, destructionLevel) serverEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.
Vec3centerThe center of the explosion.
integerdestructionLevelThe level of destruction done by this explosion. Corresponds to the 'durability' rating of a Shape.

server_onMelee(self, position, attacker, damage, power, direction, normal) serverEventCallback

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:

TypeNameDescription
tableselfThe class instance.
Vec3positionThe position in world space where the Player's Character was hit.
Player/Unit/nilattackerThe attacker. Can be a Player, Unit or nil if unknown.
integerdamageThe damage value of the melee hit.
numberpowerThe physical impact impact of the hit.
Vec3directionThe direction that the melee attack was made.
Vec3normalThe normal at the point of impact.

server_onCollision(self, other, position, selfPointVelocity, otherPointVelocity, normal) serverEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.
Shape/Character/Harvestable/Lift/nilotherThe other object. Nil if terrain.
Vec3positionThe position in world space where the collision occurred.
Vec3selfPointVelocityThe velocity that that the Player's Character had at the point of collision.
Vec3otherPointVelocityThe velocity that that the other object had at the point of collision.
Vec3normalThe collision normal between the Player's Character and the other other object.

server_onCollisionCrush(self) serverEventCallback

Called when the Player's Character is crushed.

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onShapeRemoved(self, items) serverEventCallback

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:

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:

TypeNameDescription
tableselfThe class instance.
tableitemsA table listing the removed items. {{uuid=Uuid, amount=integer, type=string}, ..}

server_onInventoryChanges(self, inventory, changes) serverEventCallback

Called when the Player has changes in the inventory Container.

Will receive a table listing the changes.

Element format:

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:

TypeNameDescription
tableselfThe class instance.
ContainerinventoryThe player's inventory Container.
tablechangesA table listing the changes. {{uuid=Uuid, difference=integer, tool=Tool}, ..}