Skip to main content

PlayerClass​

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

A player represents a user controlling a Character.

The player script handles actions made by the user.

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

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

Fields:
TypeNameDescription
PlayerplayerThe Player game object belonging to this class instance.
NetworknetworkA Network object that can be used to send data between client and server.
StoragestorageA server-side Storage object that can be used to save and load data to/from the world database.
Callbacks:

Server-only​

onProjectile​

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

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.

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 PlayerClass.server_onExplosion( self, center, destructionLevel )
end

Called when the Player'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 PlayerClass.server_onMelee( self, position, attacker, damage, power, direction, normal )
end

Called when the Player'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 PlayerClass.server_onCollision( self, other, position, selfPointVelocity, otherPointVelocity, normal )
end

Called when the Player'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 PlayerClass.server_onCollisionCrush( self )
end

Called when the Player's Character is being crushed.

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

onShapeRemoved​

function PlayerClass.server_onShapeRemoved( self, items )
	--items = { { uuid = uuid, amount = integer, type = string }, .. }
end

Called when the Player removed a Shape from the World.

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

Arguments:
  • self [ table ]: The class instance.
  • items [ table ]: A table listing the removed items. See the table format below.
Table Format:
  • uuid [ Uuid ]: The item uuid.
  • amount [ int ]: The amount of items with this uuid.
  • type [ string ]: Type of shape removed. Can be part, block or joint.

onInventoryChanges​

function PlayerClass.server_onInventoryChanges( self, inventory, changes )
	--changes = { { uuid = Uuid, difference = integer, tool = Tool }, .. }
end

Called when the Player has changes in the inventory Container.

Will receive a table listing the changes.

Arguments:
  • self [ table ]: The class instance.
  • inventory [ Container ]: The player's inventory Container.
  • changes [ table ]: A table listing the changes. See the table format below.
Table Format:
  • uuid [ Uuid ]: The item uuid.
  • difference [ int ]: The change in amount. Positive numbers mean item gain, negative item loss.
  • tool [ Tool / nil ]: (Optional) If the item is a Tool, this is the tool. Otherwise nil.

Client-only​

onInteract​

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

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

Arguments:
  • self [ table ]: The class instance.
  • character [ Character ]: The player's character. Same as self.player.character.
  • state [ bool ]: The interaction state (true if pressed, false if released).

onCancel​

function PlayerClass.client_onCancel( self )
end

Called when the player presses the Cancel key (default ESC).

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

onReload​

function PlayerClass.client_onReload( self )
end

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

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