ShapeClass

A script class that is instanced for every "scripted" Interactable Shape in the game.

An interactable part is a Shape that is usually built by the player and can be interacted with. For instance a button or an engine.

Can receive events sent with sm.event.sendToInteractable.

Fields

Name	Type	Description
`interactable`	Interactable	The Interactable game object belonging to this class instance. (The same as shape.interactable)
`shape`	Shape	The Shape game object that the Interactable is attached to. (The same as interactable.shape)
`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.
`data`	any	Data from the "data" json element.
`params`	any	Parameter set with Interactable.setParams when created from a script.

Constants

Name	Type	Description
`colorHighlight`	Color	Sets the connection-point highlight color. The connection-point is shown when using the Connect Tool and selecting the interactable. (Defaults to white)
`colorNormal`	Color	Sets the connection-point normal color. The connection-point is shown when using the Connect Tool. (Defaults to gray)
`connectIcon`	string	Sets the connection-point texture name that maps to texture specified in connectIcons.json. The connection-point is shown when using the Connect Tool and selecting the interactable. (Defaults to empty)
`connectIconScale`	integer	Sets the connection-point visualization scale. The connection-point is shown when using the Connect Tool and selecting the interactable. (Defaults to 0.75)
`connectionInput`	integer	Sets the connection input type flags. (See sm.interactable.connectionType) (Defaults to 0, no input)
`connectionOutput`	integer	Sets the connection output type flags. (See sm.interactable.connectionType) (Defaults to 0, no output)
`maxChildCount`	integer	Sets the maximum number of allowed child connections – the number of output connections. (Defaults to 0, no allowed child connections)
`maxParentCount`	integer	Sets the maximum number of allowed parent connections – the number of input connections. (Defaults to 0, no allowed parent connections)
`poseWeightCount`	integer	Sets the number of animation poses the shape's model is able to use.

maxChildCount

Value type: integer

Sets the maximum number of allowed child connections – the number of output connections. (Defaults to 0, no allowed child connections)

Note: Implement client_getAvailableChildConnectionCount to control specific types.

maxParentCount

Value type: integer

Sets the maximum number of allowed parent connections – the number of input connections. (Defaults to 0, no allowed parent connections)

Note: Implement client_getAvailableParentConnectionCount to control specific types.

poseWeightCount

Value type: integer

Sets the number of animation poses the shape's model is able to use.

Value can be are integers 0-3. (Defaults to 0, no poses)

A value greater that 0 indicates that the renderable's "mesh" is set up blend into "pose0", "pose1", "pose2".

This is, for instance, used to move the lever on the engine.

Server + Client

onCreate

ShapeClass:server_onCreate(  )
ShapeClass: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

ShapeClass:server_onDestroy(  )
ShapeClass:client_onDestroy(  )

Called when the scripted object is destroyed.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onRefresh

ShapeClass:server_onRefresh(  )
ShapeClass: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

ShapeClass:server_onFixedUpdate( timeStep )
ShapeClass: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.)

onProjectile

Server

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

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

Client

ShapeClass:client_onProjectile(
    position,
    airTime,
    velocity,
    projectileName,
    shooter,
    damage,
    customData,
    normal,
    uuid,
    mass
)

Called when the Shape 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 Shape.
`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/Shape/Harvestable/nil	The shooter, can be a Player, Shape, Harvestable or nil if unknown. Projectiles shot by a Unit will be nil on the client.
`damage`	number	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.

onMelee

Server

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

Called when the Shape is hit by a melee attack.

Note: If the attacker is destroyed before the hit lands, the attacker value will be nil.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the Shape 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.

Client

ShapeClass:client_onMelee(
    position,
    attacker,
    damage,
    power,
    direction,
    normal
)

Called when the Shape is hit by a melee attack.

Note: If the attacker is destroyed before the hit lands, the attacker value will be nil.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the Shape 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`	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

ShapeClass:server_onCollision(
    other,
    position,
    selfPointVelocity,
    otherPointVelocity,
    normal
)
ShapeClass:client_onCollision(
    other,
    position,
    selfPointVelocity,
    otherPointVelocity,
    normal
)

Called when the Shape 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 Shape 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 Shape and the other other object.

canErase

ShapeClass:server_canErase(  )
ShapeClass:client_canErase(  )

Called to check whether the Shape can be erased at this moment.

Note: Can be used to override restrictions. (See Shape.erasable)

Parameters:

Name	Type	Description
`self`	table	The class instance.

Returns:

Type	Description
boolean	A boolean indicating whether the Shape can be erased or not. (Defaults to true)

Server-only

onReceiveUpdate

ShapeClass: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.

onUnload

ShapeClass:server_onUnload(  )

Called when the Interactable is unloaded from the game because no Player's Character is close enough to it. Also called when exiting the game.

Note: The creation, consisting of one or more bodies, consisting of one or more shapes joined together with joints are always unloaded at the same time.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onSledgehammer

ShapeClass:server_onSledgehammer(  )

Deprecated: Use server_onMelee instead.

onExplosion

ShapeClass:server_onExplosion( center, destructionLevel, damage )

Called when the Shape is hit by an explosion.

For more information about explosions, see sm.physics.explode.

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.

onWorldChanged

ShapeClass:server_onWorldChanged(  )

Called when a shape changes world

Parameters:

Name	Type	Description
`self`	table	The class instance.

Client-only

onUpdate

ShapeClass: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

ShapeClass: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

ShapeClass: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

ShapeClass:client_onInteract( character, state )

Called when a Player is interacting with the Interactable by pressing the 'Use' key (default 'E') or pressing '0–9' if the Interactable is connected to a seat. (See: Interactable.pressSeatInteractable)

Note: If this method is defined, the player will see the interaction text "E Use" when looking at the Shape.

-- Example of interaction
function MySwitch.client_onInteract( self, character, state ) 
    if state == true then
        self.network:sendToServer( 'sv_n_toggle' )
    end
end

function MySwitch.sv_n_toggle( self ) 
    -- Toggle on and off
    self.interactable.active = not self.interactable.active
end

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is interacting with the Interactable.
`state`	boolean	The interaction state. (true if pressed, false if released)

onTinker

ShapeClass:client_onTinker( character, state )

Called when a Player is tinkering with the Interactable by pressing the 'Tinker' key (default 'U').

Note: Tinkering usually means opening the upgrade menu for seats.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is tinkering with the Interactable.
`state`	boolean	The interaction state. (true if pressed, false if released)

onInteractThroughJoint

ShapeClass:client_onInteractThroughJoint( character, state, joint )

Called when a Player is interacting with the Interactable through a connected Joint.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is interacting with the Interactable.
`state`	boolean	The interaction state. Always true. client_onInteractThroughJoint only receives the key down event.
`joint`	Joint	The Joint that the Player interacted through.

onAction

ShapeClass:client_onAction( action, state )

Called when the interactable receives input from a Player with the Character locked to the Interactable.

When a Character is seated in an Interactable Shape with a "seat" component, the Character is also considered locked to the Interactable.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`action`	integer	The action as an integer value. More details in sm.interactable.actions.
`state`	boolean	True on begin action, false on end action.

canInteract

ShapeClass:client_canInteract( character )

Called to check whether the Interactable 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. (Defaults to "E Use")

Note: Can be used to override restrictions. (See Shape.usable)

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is looking at the Shape.

Returns:

Type	Description
boolean	A boolean indicating whether the interactable can be interacted with or not. (Defaults to true if client_onInteract is implemented, otherwise false)

canInteractThroughJoint

ShapeClass:client_canInteractThroughJoint( character, joint )

Called to check whether the Interactable can be interacted with through a child Joint at this moment.

Note: This callback can also be used to change the interaction text shown to the player using sm.gui.setInteractionText. (Defaults to "E Use")

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is looking at the Joint.
`joint`	Joint	The Joint.

Returns:

Type	Description
boolean	A boolean indicating whether the interactable can be interacted with or not. (Defaults to true if client_onInteractThroughJoint is implemented, otherwise false)

canTinker

ShapeClass:client_canTinker( character )

Called to check whether the Interactable can be tinkered with at this moment.

Note: Tinkering usually means opening the upgrade menu for seats.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`character`	Character	The Character of the Player that is looking at the Shape.

Returns:

Type	Description
boolean	A boolean indicating whether the interactable can be tinkered with or not. (Defaults to true if client_onTinker is implemented, otherwise false)

getAvailableParentConnectionCount

ShapeClass:client_getAvailableParentConnectionCount( flags )

Called to check how many more parent (input) connections with the given type flag the Interactable will accept. Return 1 or more to allow a connection of this type.

-- Example of implementation where logic and power shares the same slot but electricity counts as separate
MyIteractable.maxParentCount = 2
MyIteractable.connectionInput = sm.interactable.connectionType.logic + sm.interactable.connectionType.power + sm.interactable.connectionType.electricity

function MyIteractable.client_getAvailableParentConnectionCount( self, flags )
    if bit.band( flags, bit.bor( sm.interactable.connectionType.logic, sm.interactable.connectionType.power ) ) ~= 0 then
        return 1 - self:getParents( bit.bor( sm.interactable.connectionType.logic, sm.interactable.connectionType.power ) )
    end
    if bit.band( flags, sm.interactable.connectionType.electricity ) ~= 0 then
        return 1 - self:getParents( sm.interactable.connectionType.electricity )
    end
    return 0
end

Note: maxParentCount must be 1 or more for this callback to be called.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`flags`	integer	Connection type flags.

Returns:

Type	Description
integer	The number of available connections.

getAvailableChildConnectionCount

ShapeClass:client_getAvailableChildConnectionCount( flags )

Called to check how many more child (output) connections with the given type flag the Interactable will accept. Return 1 or more to allow a connection of this type.

-- Example of implementation that accepts 10 logic connections and 1 power connection
MyInteractable.maxChildCount = 11
MyInteractable.connectionOutput = sm.interactable.connectionType.logic + sm.interactable.connectionType.power

function MyIteractable.client_getAvailableChildConnectionCount( self, flags )
    if bit.band( flags, sm.interactable.connectionType.logic ) ~= 0 then
        return 10 - self:getParents( sm.interactable.connectionType.logic )
    end
    if bit.band( flags, sm.interactable.connectionType.power ) ~= 0 then
        return 1 - self:getParents( sm.interactable.connectionType.power )
    end
    return 0
end

Note: maxChildCount must be 1 or more for this callback to be called.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`flags`	integer	Connection type flags.

Returns:

Type	Description
integer	The number of available connections.

canCarry

ShapeClass:client_canCarry(  )

Called to check if the shape must be carried instead of put in the inventory.

Note: Shapes with the "carryItem" attribute are always carried.

Parameters:

Name	Type	Description
`self`	table	The class instance.

Returns:

Type	Description
boolean	A boolean indicating whether the interacable must be carried or not. (Defaults to false)

onChildJointRemoved

ShapeClass:client_onChildJointRemoved( joint )

Called when a child Joint is removed from the Interactable's connection list.

This can happen when a player explicitly disconnects the Joint or when the Joint is destroyed.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`joint`	Joint	The Joint that was removed.