Shape

Associated namespace: sm.shape

A userdata object representing a shape in the game.

Values:

Functions:

Operations:

OperationReturn typeDescription
Shape == ShapebooleanChecks if two instances of Shape refer to the same Shape.

at Vec3

Get:

Returns the direction of a shape's front side.

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.

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.

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.


applyShakeImpulse(shape, shake)

Client only

Applies a shake impulse to the shape

Parameters:

TypeNameDescription
ShapeshapeThe shape.
numbershakeThe shake impulse value.

createJoint(shape, uuid, position, direction)

Server only

Create a new joint

Parameters:

TypeNameDescription
ShapeshapeThe host shape.
UuiduuidThe uuid of the joint.
Vec3positionThe joint's grid position.
Vec3directionThe joint's normal direction.

Returns:

TypeDescription
Joint The created joint.

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

Server only

Destroy a block.

Parameters:

TypeNameDescription
ShapeshapeThe block shape.
Vec3positionThe local position of the removal box corner.
Vec3size?The size of the removal box. Defaults to 1x1x1 (Optional)
integerattackLevel?Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.
integerdestructionType?The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
Vec3destructionPosition?The position of the destruction would hit the block (Optional)
Vec3destructionNormal?The normal direction of where the destruction would hit the block (Optional)

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

Deprecated:

use Shape.destroyShape

Server only

Destroy a part

Parameters:

TypeNameDescription
ShapeshapeThe part.
integerattackLevelDetermines which quality level of parts the attack can destroy. Setting it to 0 (default) will destroy any part.
integerdestructionType?The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
Vec3destructionPosition?The position of the destruction would hit the part (Optional)
Vec3destructionNormal?The normal direction of where the destruction would hit the part (Optional)

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

Server only

Destroy a shape

Parameters:

TypeNameDescription
ShapeshapeThe shape.
integerattackLevelDetermines which quality level of shape the attack can destroy. Setting it to 0 (default) will destroy any shape.
integerdestructionType?The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none)
Vec3destructionPosition?The position of the destruction would hit the shape (Optional)
Vec3destructionNormal?The normal direction of where the destruction would hit the shape (Optional)

getAt(shape)

Returns the direction of a shape's front side.

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's at-axis.

getBody(shape)

Returns the Body a shape is part of.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
BodyThe body which the shape is part of.

getBoundingBox(shape)

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The size of the shape's bounding box.

getBuoyancy(shape)

Returns the buoyancy multiplier of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
numberThe buoyancy multiplier.

getBurning(shape)

Check if a shape is burning.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanReturn true if the shape is burning.

getClosestBlockLocalPosition(shape, position)

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

Parameters:

TypeNameDescription
ShapeshapeThe block shape.
Vec3positionThe world position.

Returns:

TypeDescription
Vec3The closest position.

getColor(shape)

Returns the color of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
ColorThe shape's color.

getCompromised(shape)

Check if a shape is compromised.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanReturn true if the shape is compromised.

getId(shape)

Returns the id of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
integerThe shape's id.

getInteractable(shape)

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
InteractableThe interactable belonging to the shape.

getInterpolatedAt(shape)

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

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's interpolated at-axis.

getInterpolatedRight(shape)

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

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's interpolated right-axis.

getInterpolatedUp(shape)

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

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's interpolated up-axis.

getInterpolatedWorldPosition(shape)

Returns the interpolated world position of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's interpolated world position.

getIsHarvest(shape)

Return whether the shape belongs to a harvest shape

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanTrue if the shape is harvestable.

getIsStackable(shape)

Return whether the shape belongs to a stackable shape

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanTrue if the shape is stackable.

getJoints(shape, 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:

TypeNameDescription
ShapeshapeThe shape.
booleanonlyChildJoints?Filters what joints to return. Defaults to true (Optional)

Returns:

TypeDescription
tableThe table of joints attached to the shape. {Joint, ..}

getLocalAabb(shape)

Get the local aabb of the shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3,Vec3Returns the aabb min and max.

getLocalPosition(shape)

Returns the local grid position of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's local position.

getLocalRotation(shape)

Returns the local rotation of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
QuatThe shape's local rotation.

getMass(shape)

Returns the mass of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
numberThe shape's mass.

getMaterial(shape)

Returns the material of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
stringThe shape's material.

getMaterialId(shape)

Returns the material id of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
integerThe shape's material id.

getMultiShapeJoints(shape)

Parameters:

TypeNameDescription
ShapeshapeA shape that is a multishape

Returns:

TypeDescription
tableA table of joints contained in the multishape (returns nil if shape wasn't a multishape)

getMultiShapeShapes(shape)

Parameters:

TypeNameDescription
ShapeshapeA shape that is a multishape

Returns:

TypeDescription
tableA table of shapes contained in the multishape (returns nil if shape wasn't a multishape)

getNeighbours(shape)

Server only

Returns a table of shapes which are neighbours to the shape

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
tabletable of shapes. {Shape, ..}

getPipeOffsets(shape, direction?)

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.
integerdirection?The direction to fetch in. Defaults to sm.pipeGraph.direction.any (Optional)

Returns:

TypeDescription
tabletable of local offset positions. {Vec3, ..}

getPipedNeighbours(shape)

Server only

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
tabletable of shapes. {Shape, ..}

getRight(shape)

Returns the direction of a shape's right side.

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's right-axis.

getShapeOutputContainerIndex(shape)

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

Parameters:

TypeNameDescription
Shapeshape

getShapeUuid(shape)

Returns the uuid unique to a shape/block type.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
UuidThe shape's uuid.

getSticky(shape)

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:

TypeNameDescription
ShapeshapeThe shape.

Returns:

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

getUp(shape)

Returns the direction of a shape's top side.

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's up-axis.

getVelocity(shape)

Returns the linear velocity of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's linear velocity.

getWorldPosition(shape)

Returns the world position of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's world position.

getWorldRotation(shape)

Returns the world rotation of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
QuatThe shape's world rotation.

getXAxis(shape)

Returns the local x-axis vector of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's x-axis.

getYAxis(shape)

Returns the local y-axis vector of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's y-axis.

getZAxis(shape)

Returns the local z-axis vector of a shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
Vec3The shape's z-axis.

isPipe(shape)

Returns whether the shape is a pipe or not.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanWhether the shape was a pipe or not.

removeColor(shape)

Server only

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

Parameters:

TypeNameDescription
ShapeshapeThe shape

replaceShape(shape, uuid)

Server only

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.
UuiduuidThe uuid of the new shape.

setBurning(shape, state)

Server only

Set the state that determines if a shape is burning.

True to set burning and false to set not burning.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
booleanstateThe state.

setCollisionSoundEnabled(shape, enabled)

Sets if the shape should generate sound on collisions.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
booleanenabledWhether the sound should be enabled or not.

setColor(shape, color)

Server only

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

Parameters:

TypeNameDescription
ShapeshapeThe shape.
ColorcolorThe color.

setCompromised(shape, state)

Server only

Set the state that determines if a shape is compromised.

True to set compromised and false to set not compromised.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
booleanstateThe state.

setPhysicsMaterial(shape, material)

Sets the physics material of the shape.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
integermaterialThe new physics material for the shape.

shapeExists(shape)

Deprecated:

use sm.exists

Return true if a shape exists.

Parameters:

TypeNameDescription
ShapeshapeThe shape.

Returns:

TypeDescription
booleanWhether the shape exists.

transformDirection(shape, vector)

Transform a world direction to the local shape transform.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
Vec3vectorThe untransformed direction.

Returns:

TypeDescription
Vec3The transformed direction.

transformLocalDirection(shape, vector)

Transform a local direction to world space.

Parameters:

TypeNameDescription
ShapeshapeThe shape.
Vec3vectorThe local direction.

Returns:

TypeDescription
Vec3The world direction.

transformLocalPoint(shape, vector)

Transform a local point to world space.

local worldPos = self.shape:transformLocalPoint( localPos )

Parameters:

TypeNameDescription
ShapeshapeThe shape.
Vec3vectorThe local point.

Returns:

TypeDescription
Vec3The world point.

transformPoint(shape, vector)

Transform a world point to the local shape transform.

local localPos = self.shape:transformPoint( worldPos )

Parameters:

TypeNameDescription
ShapeshapeThe shape.
Vec3vectorThe world point.

Returns:

TypeDescription
Vec3The local point.

transformRotation(shape, 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:

TypeNameDescription
ShapeshapeThe shape.
QuatquatThe untransformed quaternion.

Returns:

TypeDescription
QuatThe transformed quaternion.