Shape
Associated namespace: sm.shape
A userdata object representing a shape in the game.
Values:
- at
- body
- buildable
- buoyancy
- color
- connectable
- convertableToDynamic
- destructable
- erasable
- id
- interactable
- isBlock
- isWedge
- liftable
- localPosition
- localRotation
- mass
- material
- materialId
- paintable
- right
- shapeUuid
- stackedAmount
- stackedItem
- up
- usable
- uuid
- velocity
- worldPosition
- worldRotation
- xAxis
- yAxis
- zAxis
Functions:
- applyShakeImpulse
- createJoint
- destroyBlock
- destroyPart
- destroyShape
- getAt
- getBody
- getBoundingBox
- getBuoyancy
- getBurning
- getClosestBlockLocalPosition
- getColor
- getCompromised
- getId
- getInteractable
- getInterpolatedAt
- getInterpolatedRight
- getInterpolatedUp
- getInterpolatedWorldPosition
- getIsHarvest
- getIsStackable
- getJoints
- getLocalAabb
- getLocalPosition
- getLocalRotation
- getMass
- getMaterial
- getMaterialId
- getMultiShapeJoints
- getMultiShapeShapes
- getNeighbours
- getPipeOffsets
- getPipedNeighbours
- getRight
- getShapeOutputContainerIndex
- getShapeUuid
- getSticky
- getUp
- getVelocity
- getWorldPosition
- getWorldRotation
- getXAxis
- getYAxis
- getZAxis
- isPipe
- removeColor
- replaceShape
- setBurning
- setCollisionSoundEnabled
- setColor
- setCompromised
- setPhysicsMaterial
- shapeExists
- transformDirection
- transformLocalDirection
- transformLocalPoint
- transformPoint
- transformRotation
Operations:
| Operation | Return type | Description |
|---|---|---|
| Shape == Shape | boolean | Checks 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| number | shake | The shake impulse value. |
createJoint(shape, uuid, position, direction)
Server only
Create a new joint
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The host shape. |
| Uuid | uuid | The uuid of the joint. |
| Vec3 | position | The joint's grid position. |
| Vec3 | direction | The joint's normal direction. |
Returns:
| Type | Description |
|---|---|
| Joint The created joint. |
destroyBlock(shape, position, size?, attackLevel?, destructionType?, destructionPosition?, destructionNormal?)
Server only
Destroy a block.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The block shape. |
| Vec3 | position | The local position of the removal box corner. |
| Vec3 | size? | The size of the removal box. Defaults to 1x1x1 (Optional) |
| integer | attackLevel? | Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block. |
| integer | destructionType? | The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none) |
| Vec3 | destructionPosition? | The position of the destruction would hit the block (Optional) |
| Vec3 | destructionNormal? | The normal direction of where the destruction would hit the block (Optional) |
destroyPart(shape, attackLevel, destructionType?, destructionPosition?, destructionNormal?)
Deprecated:
Server only
Destroy a part
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The part. |
| integer | attackLevel | Determines which quality level of parts the attack can destroy. Setting it to 0 (default) will destroy any part. |
| integer | destructionType? | The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none) |
| Vec3 | destructionPosition? | The position of the destruction would hit the part (Optional) |
| Vec3 | destructionNormal? | The normal direction of where the destruction would hit the part (Optional) |
destroyShape(shape, attackLevel, destructionType?, destructionPosition?, destructionNormal?)
Server only
Destroy a shape
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| integer | attackLevel | Determines which quality level of shape the attack can destroy. Setting it to 0 (default) will destroy any shape. |
| integer | destructionType? | The type of destruction (Optional). (See[sm.shape.destructionType). (Defaults to sm.shape.destructionType.none) |
| Vec3 | destructionPosition? | The position of the destruction would hit the shape (Optional) |
| Vec3 | destructionNormal? | 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's at-axis. |
getBody(shape)
Returns the Body a shape is part of.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Body | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The size of the shape's bounding box. |
getBuoyancy(shape)
Returns the buoyancy multiplier of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| number | The buoyancy multiplier. |
getBurning(shape)
Check if a shape is burning.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | Return true if the shape is burning. |
getClosestBlockLocalPosition(shape, position)
Transform a world position to the closest block's local position in a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The block shape. |
| Vec3 | position | The world position. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The closest position. |
getColor(shape)
Returns the color of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Color | The shape's color. |
getCompromised(shape)
Check if a shape is compromised.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | Return true if the shape is compromised. |
getId(shape)
Returns the id of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| integer | The shape's id. |
getInteractable(shape)
Returns the Interactable of a shape, if one exists. Otherwise the function will return nil.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Interactable | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's interpolated up-axis. |
getInterpolatedWorldPosition(shape)
Returns the interpolated world position of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's interpolated world position. |
getIsHarvest(shape)
Return whether the shape belongs to a harvest shape
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the shape is harvestable. |
getIsStackable(shape)
Return whether the shape belongs to a stackable shape
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | True 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| boolean | onlyChildJoints? | Filters what joints to return. Defaults to true (Optional) |
Returns:
| Type | Description |
|---|---|
| table | The table of joints attached to the shape. {Joint, ..} |
getLocalAabb(shape)
Get the local aabb of the shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3,Vec3 | Returns the aabb min and max. |
getLocalPosition(shape)
Returns the local grid position of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's local position. |
getLocalRotation(shape)
Returns the local rotation of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Quat | The shape's local rotation. |
getMass(shape)
Returns the mass of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| number | The shape's mass. |
getMaterial(shape)
Returns the material of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| string | The shape's material. |
getMaterialId(shape)
Returns the material id of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| integer | The shape's material id. |
getMultiShapeJoints(shape)
Parameters:
| Type | Name | 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)
Parameters:
| Type | Name | 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) |
getNeighbours(shape)
Server only
Returns a table of shapes which are neighbours to the shape
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| table | table 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| integer | direction? | The direction to fetch in. Defaults to sm.pipeGraph.direction.any (Optional) |
Returns:
| Type | Description |
|---|---|
| table | table of local offset positions. {Vec3, ..} |
getPipedNeighbours(shape)
Server only
Returns a table of shapes which are neighbours connected with pipes to the shape
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| table | table 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's right-axis. |
getShapeOutputContainerIndex(shape)
Returns the shapes output container index listed in the shapeset for pipe graph affecting shapes.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape |
getShapeUuid(shape)
Returns the uuid unique to a shape/block type.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Uuid | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| {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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's up-axis. |
getVelocity(shape)
Returns the linear velocity of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's linear velocity. |
getWorldPosition(shape)
Returns the world position of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's world position. |
getWorldRotation(shape)
Returns the world rotation of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Quat | The shape's world rotation. |
getXAxis(shape)
Returns the local x-axis vector of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's x-axis. |
getYAxis(shape)
Returns the local y-axis vector of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's y-axis. |
getZAxis(shape)
Returns the local z-axis vector of a shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The shape's z-axis. |
isPipe(shape)
Returns whether the shape is a pipe or not.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape |
replaceShape(shape, uuid)
Server only
Creates a new Shape from Uuid to replace the given Shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Uuid | uuid | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| boolean | state | The state. |
setCollisionSoundEnabled(shape, enabled)
Sets if the shape should generate sound on collisions.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| boolean | enabled | Whether 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Color | color | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| boolean | state | The state. |
setPhysicsMaterial(shape, material)
Sets the physics material of the shape.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| integer | material | The new physics material for the shape. |
shapeExists(shape)
Deprecated:
use sm.exists
Return true if a shape exists.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the shape exists. |
transformDirection(shape, vector)
Transform a world direction to the local shape transform.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Vec3 | vector | The untransformed direction. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The transformed direction. |
transformLocalDirection(shape, vector)
Transform a local direction to world space.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Vec3 | vector | The local direction. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The world direction. |
transformLocalPoint(shape, vector)
Transform a local point to world space.
local worldPos = self.shape:transformLocalPoint( localPos )
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Vec3 | vector | The local point. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The world point. |
transformPoint(shape, vector)
Transform a world point to the local shape transform.
local localPos = self.shape:transformPoint( worldPos )
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Vec3 | vector | The world point. |
Returns:
| Type | Description |
|---|---|
| Vec3 | The 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:
| Type | Name | Description |
|---|---|---|
| Shape | shape | The shape. |
| Quat | quat | The untransformed quaternion. |
Returns:
| Type | Description |
|---|---|
| Quat | The transformed quaternion. |