SM Docs
Docs›Game›Userdata›Shape

Shape

Availability
Server + Client
Serializable
Yes
Associated namespace
sm.shape

A userdata object representing a shape in the game.

Values:

  • at [ Vec3 ]

    • Get: Returns the direction of a shape's front side.
      Result: The shape's at-axis.

      The direction is affected by the shape's rotation in the world.

  • body [ Body ]

    • Get: Returns the Body a shape is part of.

  • buildable [ boolean ]

    • Get: Check if a shape is buildable

  • buoyancy [ number ]

    • Get: Returns the buoyancy multiplier of a shape.

  • color [ Color ]

    • Get: Returns the color of a shape.
    • Set: (Server-Only) Sets the color of a shape. This is similar to coloring with the Paint Tool.

  • connectable [ boolean ]

    • Get: Check if a shape is connectable

  • convertableToDynamic [ boolean ]

    • Get: Check if a shape is convertible to dynamic form

  • destructable [ boolean ]

    • Get: Check if a shape is destructable.

  • erasable [ boolean ]

    • Get: Check if a shape is erasable.

  • id [ integer ]

    • Get: Returns the id of a shape.

  • interactable [ Interactable ]

    • Get: Returns the Interactable of a shape, if one exists. Otherwise the function will return nil.

  • isBlock [ boolean ]

    • Get: Return true if a shape is a basicmaterial

  • isWedge [ boolean ]

    • Get: Return true if a shape is a wedge

  • liftable [ boolean ]

    • Get: Check if a shape is liftable

  • localPosition [ Vec3 ]

    • Get: Returns the local grid position of a shape.

  • localRotation [ Quat ]

    • Get: Returns the local rotation of a shape.

  • mass [ number ]

    • Get: Returns the mass of a shape.

  • material [ string ]

    • Get: Returns the material of a shape.

  • materialId [ integer ]

    • Get: Returns the material id of a shape.

  • paintable [ boolean ]

    • Get: Check if a shape is paintable

  • right [ Vec3 ]

    • Get: Returns the direction of a shape's right side.
      Result: The shape's right-axis.

      The direction is affected by the shape's rotation in the world.

  • shapeUuid [ Uuid ]

    • Get: Returns the uuid unique to a shape/block type.

  • stackedAmount [ integer ]

    • Get: Return the amount that is stacked in the shape
    • Set: (Server-Only) Set the amount that is stacked in the shape

  • stackedItem [ Uuid ]

    • Get: Return the item Uuid that is stacked in the shape
    • Set: (Server-Only) Set the item Uuid that is stacked in the shape

  • up [ Vec3 ]

    • Get: Returns the direction of a shape's top side.
      Result: The shape's up-axis.

      The direction is affected by the shape's rotation in the world.

  • usable [ boolean ]

    • Get: Check if a shape is interactable

  • uuid [ Uuid ]

    • Get: Returns the uuid unique to a shape/block type.

  • velocity [ Vec3 ]

    • Get: Returns the linear velocity of a shape.

  • worldPosition [ Vec3 ]

    • Get: Returns the world position of a shape.

  • worldRotation [ Quat ]

    • Get: Returns the world rotation of a shape.

  • xAxis [ Vec3 ]

    • Get: Returns the local x-axis vector of a shape.

  • yAxis [ Vec3 ]

    • Get: Returns the local y-axis vector of a shape.

  • zAxis [ Vec3 ]

    • Get: Returns the local z-axis vector of a shape.

Operations:

Operation Returns Description
Shape == Shape boolean Checks if two instances of Shape refer to the same Shape.

Server + Client

getAt

shape:getAt(  )

Returns the direction of a shape's front side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's at-axis.

getBody

shape:getBody(  )

Returns the Body a shape is part of.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Body The body which the shape is part of.

getBoundingBox

shape:getBoundingBox(  )

Returns the bounding box of a shape – the dimensions that a shape occupies when building.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The size of the shape's bounding box.

getBuoyancy

shape:getBuoyancy(  )

Returns the buoyancy multiplier of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
number The buoyancy multiplier.

getBurning

shape:getBurning(  )

Check if a shape is burning.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean Return true if the shape is burning.

getClosestBlockLocalPosition

shape:getClosestBlockLocalPosition( position )

Transform a world position to the closest block's local position in a shape.

Parameters:

Name Type Description
shape Shape The block shape.
position Vec3 The world position.

Returns:

Type Description
Vec3 The closest position.

getColor

shape:getColor(  )

Returns the color of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Color The shape's color.

getCompromised

shape:getCompromised(  )

Check if a shape is compromised.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean Return true if the shape is compromised.

getId

shape:getId(  )

Returns the id of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
integer The shape's id.

getInteractable

shape:getInteractable(  )

Returns the Interactable of a shape, if one exists. Otherwise the function will return nil.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Interactable The interactable belonging to the shape.

getInterpolatedAt

shape:getInterpolatedAt(  )

Returns the interpolated direction of a shape's front side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's interpolated at-axis.

getInterpolatedRight

shape:getInterpolatedRight(  )

Returns the interpolated direction of a shape's right side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's interpolated right-axis.

getInterpolatedUp

shape:getInterpolatedUp(  )

Returns the interpolated direction of a shape's top side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's interpolated up-axis.

getInterpolatedWorldPosition

shape:getInterpolatedWorldPosition(  )

Returns the interpolated world position of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's interpolated world position.

getIsHarvest

shape:getIsHarvest(  )

Return whether the shape belongs to a harvest shape

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean True if the shape is harvestable.

getIsStackable

shape:getIsStackable(  )

Return whether the shape belongs to a stackable shape

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean True if the shape is stackable.

getJoints

shape:getJoints( onlyChildJoints )

Returns a table of all joints that are attached to the shape.

Will return all attached joints when onlyChildJoints is set to false.

Parameters:

Name Type Description
shape Shape The shape.
onlyChildJoints (optional) boolean Filters what joints to return. Defaults to true (Optional)

Returns:

Type Description
table The table of joints attached to the shape. {Joint, ..}

getLocalAabb

shape:getLocalAabb(  )

Get the local aabb of the shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3
Vec3		 Returns the aabb min and max.

getLocalPosition

shape:getLocalPosition(  )

Returns the local grid position of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's local position.

getLocalRotation

shape:getLocalRotation(  )

Returns the local rotation of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Quat The shape's local rotation.

getMass

shape:getMass(  )

Returns the mass of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
number The shape's mass.

getMaterial

shape:getMaterial(  )

Returns the material of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
string The shape's material.

getMaterialId

shape:getMaterialId(  )

Returns the material id of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
integer The shape's material id.

getMultiShapeJoints

shape:getMultiShapeJoints(  )

Parameters:

Name Type Description
shape Shape A shape that is a multishape

Returns:

Type Description
table A table of joints contained in the multishape (returns nil if shape wasn't a multishape)

getMultiShapeShapes

shape:getMultiShapeShapes(  )

Parameters:

Name Type Description
shape Shape A shape that is a multishape

Returns:

Type Description
table A table of shapes contained in the multishape (returns nil if shape wasn't a multishape)

getPipeOffsets

shape:getPipeOffsets( direction )

Returns a table offsets for the pipe connections of the shape. Can specify direction using sm.pipeGraph.direction.

Parameters:

Name Type Description
shape Shape The shape.
direction (optional) integer The direction to fetch in. Defaults to sm.pipeGraph.direction.any (Optional)

Returns:

Type Description
table table of local offset positions. {Vec3, ..}

getRight

shape:getRight(  )

Returns the direction of a shape's right side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's right-axis.

getShapeOutputContainerIndex

shape:getShapeOutputContainerIndex(  )

Returns the shapes output container index listed in the shapeset for pipe graph affecting shapes.

Parameters:

Name Type Description
shape Shape —

getShapeUuid

shape:getShapeUuid(  )

Returns the uuid unique to a shape/block type.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Uuid The shape's uuid.

getSticky

shape:getSticky(  )

Returns the sticky directions of the shape for positive xyz and negative xyz.

A value of 1 means that the direction is sticky and a value of 0 means that the direction is not sticky.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
{Vec3,Vec3} The negative xyz sticky and the positive xyz sticky.

getUp

shape:getUp(  )

Returns the direction of a shape's top side.

The direction is affected by the shape's rotation in the world.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's up-axis.

getVelocity

shape:getVelocity(  )

Returns the linear velocity of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's linear velocity.

getWorldPosition

shape:getWorldPosition(  )

Returns the world position of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's world position.

getWorldRotation

shape:getWorldRotation(  )

Returns the world rotation of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Quat The shape's world rotation.

getXAxis

shape:getXAxis(  )

Returns the local x-axis vector of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's x-axis.

getYAxis

shape:getYAxis(  )

Returns the local y-axis vector of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's y-axis.

getZAxis

shape:getZAxis(  )

Returns the local z-axis vector of a shape.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
Vec3 The shape's z-axis.

isPipe

shape:isPipe(  )

Returns whether the shape is a pipe or not.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean Whether the shape was a pipe or not.

setCollisionSoundEnabled

shape:setCollisionSoundEnabled( enabled )

Sets if the shape should generate sound on collisions.

Parameters:

Name Type Description
shape Shape The shape.
enabled boolean Whether the sound should be enabled or not.

setPhysicsMaterial

shape:setPhysicsMaterial( material )

Sets the physics material of the shape.

Parameters:

Name Type Description
shape Shape The shape.
material integer The new physics material for the shape.

shapeExists

shape:shapeExists(  )

Deprecated: use sm.exists

Return true if a shape exists.

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
boolean Whether the shape exists.

transformDirection

shape:transformDirection( vector )

Transform a world direction to the local shape transform.

Parameters:

Name Type Description
shape Shape The shape.
vector Vec3 The untransformed direction.

Returns:

Type Description
Vec3 The transformed direction.

transformLocalDirection

shape:transformLocalDirection( vector )

Transform a local direction to world space.

Parameters:

Name Type Description
shape Shape The shape.
vector Vec3 The local direction.

Returns:

Type Description
Vec3 The world direction.

transformLocalPoint

shape:transformLocalPoint( vector )

Transform a local point to world space.

local worldPos = self.shape:transformLocalPoint( localPos )

Parameters:

Name Type Description
shape Shape The shape.
vector Vec3 The local point.

Returns:

Type Description
Vec3 The world point.

transformPoint

shape:transformPoint( vector )

Transform a world point to the local shape transform.

local localPos = self.shape:transformPoint( worldPos )

Parameters:

Name Type Description
shape Shape The shape.
vector Vec3 The world point.

Returns:

Type Description
Vec3 The local point.

transformRotation

shape:transformRotation( quat )

Transform a world rotation to the local shape transform.

local worldUp = sm.vec3.new( 0, 0, 1 )
local worldRot = sm.vec3.getRotation( worldUp, worldDir )
local localRot = self.shape:transformRotation( worldRot )

Parameters:

Name Type Description
shape Shape The shape.
quat Quat The untransformed quaternion.

Returns:

Type Description
Quat The transformed quaternion.

Server-only

createJoint

shape:createJoint( uuid, position, direction )

Create a new joint

Parameters:

Name Type Description
shape Shape The host shape.
uuid Uuid The uuid of the joint.
position Vec3 The joint's grid position.
direction Vec3 The joint's normal direction.

Returns:

Type Description
Joint The created joint.

destroyBlock

shape:destroyBlock(
    position,
    size,
    attackLevel,
    destructionType,
    destructionPosition,
    destructionNormal
)

Destroy a block.

Parameters:

Name Type Description
shape Shape The block shape.
position Vec3 The local position of the removal box corner.
size (optional) Vec3 The size of the removal box. Defaults to 1x1x1 (Optional)
attackLevel (optional) integer Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.
destructionType (optional) integer The type of destruction (Optional). (See sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
destructionPosition (optional) Vec3 The position of the destruction would hit the block (Optional)
destructionNormal (optional) Vec3 The normal direction of where the destruction would hit the block (Optional)

destroyPart

shape:destroyPart(
    attackLevel,
    destructionType,
    destructionPosition,
    destructionNormal
)

Deprecated: use Shape.destroyShape

Destroy a part

Parameters:

Name Type Description
shape Shape The part.
attackLevel integer Determines which quality level of parts the attack can destroy. Setting it to 0 (default) will destroy any part.
destructionType (optional) integer The type of destruction (Optional). (See sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
destructionPosition (optional) Vec3 The position of the destruction would hit the part (Optional)
destructionNormal (optional) Vec3 The normal direction of where the destruction would hit the part (Optional)

destroyShape

shape:destroyShape(
    attackLevel,
    destructionType,
    destructionPosition,
    destructionNormal
)

Destroy a shape

Parameters:

Name Type Description
shape Shape The shape.
attackLevel integer Determines which quality level of shape the attack can destroy. Setting it to 0 (default) will destroy any shape.
destructionType (optional) integer The type of destruction (Optional). (See sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
destructionPosition (optional) Vec3 The position of the destruction would hit the shape (Optional)
destructionNormal (optional) Vec3 The normal direction of where the destruction would hit the shape (Optional)

getNeighbours

shape:getNeighbours(  )

Returns a table of shapes which are neighbours to the shape

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
table table of shapes. {Shape, ..}

getPipedNeighbours

shape:getPipedNeighbours(  )

Returns a table of shapes which are neighbours connected with pipes to the shape

Parameters:

Name Type Description
shape Shape The shape.

Returns:

Type Description
table table of shapes. {Shape, ..}

removeColor

shape:removeColor(  )

Restores the color of a shape to its base color. This is similar to coloring with the Paint Tool

Parameters:

Name Type Description
shape Shape The shape

replaceShape

shape:replaceShape( uuid )

Creates a new Shape from Uuid to replace the given Shape.

Parameters:

Name Type Description
shape Shape The shape.
uuid Uuid The uuid of the new shape.

setBurning

shape:setBurning( state )

Set the state that determines if a shape is burning.

True to set burning and false to set not burning.

Parameters:

Name Type Description
shape Shape The shape.
state boolean The state.

setColor

shape:setColor( color )

Sets the color of a shape. This is similar to coloring with the Paint Tool.

Parameters:

Name Type Description
shape Shape The shape.
color Color The color.

setCompromised

shape:setCompromised( state )

Set the state that determines if a shape is compromised.

True to set compromised and false to set not compromised.

Parameters:

Name Type Description
shape Shape The shape.
state boolean The state.

Client-only

applyShakeImpulse

shape:applyShakeImpulse( shake )

Applies a shake impulse to the shape

Parameters:

Name Type Description
shape Shape The shape.
shake number The shake impulse value.