Skip to main content

Shape​

Associated namespace: sm.shape

A userdata object representing a shape in the game.

Values:

  • at [ Vec3 ]

    • Get: The direction of the shape's front side.

  • body [ Body ]

    • Get: The body that the shape is part of.

  • buildable [ bool ]

    • Get: Whether the shape is buildable or not.

  • buoyancy [ number ]

    • Get: The buoyancy multiplier of the shape.

  • color [ Color ]

    • Get: The color of the shape.
    • Set: (Server-Only) Sets the color of the shape.

  • connectable [ bool ]

    • Get: Whether the shape is connectable or not.

  • convertableToDynamic [ bool ]

    • Get: Whether the shape is convertable to dynamic or not.

  • destructable [ bool ]

    • Get: Whether the shape is destructable or not.

  • erasable [ bool ]

    • Get: Whether the shape is erasable or not.

  • id [ id ]

    • Get: The shape's id.

  • interactable [ Interactable ]

    • Get: The interactable of the shape, if it exists.

  • isBlock [ bool ]

    • Get: Whether the shape is a block or not.

  • isWedge [ bool ]

    • Get: Whether the shape is a wedge or not.

  • liftable [ bool ]

    • Get: Whether the shape is liftable or not.

  • localPosition [ Vec3 ]

    • Get: The local grid position of the shape.

  • localRotation [ Quat ]

    • Get: The local rotation of the shape.

  • mass [ number ]

    • Get: The shape's mass.

  • material [ string ]

    • Get: The shape's material.

  • materialId [ int ]

    • Get: the shape's material id.

  • paintable [ bool ]

    • Get: Whether the shape is paintable or not.

  • right [ Vec3 ]

    • Get: The direction of the shape's right side.

  • stackedAmount [ int ]

    • Get: The item amount that is stacked in the shape.
    • Set: (Server-Only) Sets the item amount that is stacked in the shape.

  • stackedItem [ Uuid ]

    • Get: The item uuid that is stacked in the shape.
    • Set: (Server-Only) Sets the item uuid that is stacked in the shape.

  • up [ Vec3 ]

    • Get: The direction of the shape's top side.

  • usable [ bool ]

    • Get: Whether the shape is interactable or not.

  • shapeUuid [ Uuid ]

    • Get: The shape's uuid.

  • uuid [ Uuid ]

    • Get: The shape's uuid.

  • velocity [ Vec3 ]

    • Get: The shape's linear velocity.

  • worldPosition [ Vec3 ]

    • Get: The world position of the shape.

  • worldRotation [ Quat ]

    • Get: The world rotation of the shape.

  • xAxis [ Vec3 ]

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

  • yAxis [ Vec3 ]

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

  • zAxis [ Vec3 ]

    • Get: The local z-axis vector of the shape.
Operations:
OperationDescription
Shape == ShapeChecks if two instances of Shape refer to the same Shape.

Functions​

createJoint​

shape:createJoint( uuid, position, direction )
Server-Only

Creates a joint on the shape.

Arguments:
  • shape [ Shape ]: The shape.
  • uuid [ Uuid ]: The joint's uuid.
  • position [ Vec3 ]: The joint's position.
  • direction [ Vec3 ]: The joint's normal direction.
Returns:

destroyBlock​

shape:destroyBlock( position, size, attackLevel )
Server-Only

Destroys a block in the shape.

Arguments:
  • shape [ Shape ]: The shape.
  • position [ Vec3 ]: The local position of the removal box corner.
  • size [ Vec3 ]: The size of the removal box (defaults to 1x1x1).
  • attackLevel [ int ]: Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.

destroyPart​

shape:destroyPart( attackLevel )
Server-Only

Destroys the part.

Arguments:
  • shape [ Shape ]: The shape.
  • attackLevel [ int ]: Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.

destroyShape​

shape:destroyShape( attackLevel )
Server-Only

Destroys the shape.

Arguments:
  • shape [ Shape ]: The shape.
  • attackLevel [ int ]: Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.

getAt​

shape:getAt()

Returns the direction of the shape's front side.

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

Arguments:
Returns:

getBody​

shape:getBody()

Returns the body that the shape is part of.

Arguments:
Returns:

getBoundingBox​

shape:getBoundingBox()

Returns the bounding box of the shape - the dimensions that the shape occupies.

Arguments:
Returns:

getBuoyancy​

shape:getBuoyancy()

Returns the buoyancy multiplier of the shape.

Arguments:
Returns:
  • [ number ]: The buoyancy multiplier.

getClosestBlockLocalPosition​

shape:getClosestBlockLocalPosition( position )

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

Arguments:
  • shape [ Shape ]: The shape.
  • position [ Vec3 ]: The world position.
Returns:
  • [ Vec3 ]: The closest local block position.

getColor​

shape:getColor()

Returns the shape's color.

Arguments:
Returns:

getId​

shape:getId()

Returns the shape's id.

Arguments:
Returns:
  • [ int ]: The id.

getInteractable​

shape:getInteractable()

Returns the Interactable of the shape, if it exists.

Arguments:
Returns:

getInterpolatedAt​

shape:getInterpolatedAt()

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

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

Arguments:
Returns:
  • [ Vec3 ]: The interpolated direction.

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.

Arguments:
Returns:
  • [ Vec3 ]: The interpolated direction.

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.

Arguments:
Returns:
  • [ Vec3 ]: The interpolated direction.

getInterpolatedWorldPosition​

shape:getInterpolatedWorldPosition()

Returns the interpolated world position of a shape.

Arguments:
Returns:
  • [ Vec3 ]: The interpolated position.

getIsHarvest​

shape:getIsHarvest(uuid)

Returns whether the uuid belongs to a harvestable.

Arguments:
Returns:
  • [ bool ]: Whether the uuid belongs to a harvestable or not.

getIsStackable​

shape:getIsStackable( uuid )

Returns whether the uuid belongs to a stackable shape.

Arguments:
Returns:
  • [ bool ]: Whether the uuid belongs to a stackable shape or not.

getJoints​

shape:getJoints( onlyChildJoints, onlySubshapes )

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

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

Will only get the joints which are subshapes to the shape when onlySubshapes is set to true.

Arguments:
  • shape [ Shape ]: The shape.
  • onlyChildJoints [ bool ]: Filters what joints to return (Optional, defaults to true).
  • onlySubshapes [ bool ]: Only get joints which are subshapes to the shape (Optional, defaults to false).
Returns:
  • [ table ]: The table of attached joints.

getLocalPosition​

shape:getLocalPosition()

Returns the local grid position of the shape.

Arguments:
Returns:
  • [ Vec3 ]: The shape's local position.

getLocalRotation​

shape:getLocalRotation()

Returns the local grid rotation of the shape.

Arguments:
Returns:
  • [ Quat ]: The shape's local rotation.

getMass​

shape:getMass()

Returns the shape's mass.

Arguments:
Returns:
  • [ number ]: The shape's mass.

getMaterial​

shape:getMaterial()

Returns the shape's material.

Arguments:
Returns:
  • [ string ]: The material.

getMaterialId​

shape:getMaterialId()

Returns the shape's material id.

Arguments:
Returns:
  • [ int ]: The material id.

getNeighbours​

shape:getNeighbours()
Server-Only

Returns a table of "neighbor" shapes that are attached to the shape.

Arguments:
Returns:
  • [ table ]: The table of attached neighbor shapes.

getPipedNeighbours​

shape:getPipedNeighbours()
Server-Only

Returns a table of piped "neighbor" shapes that are attached to the shape through pipes.

Arguments:
Returns:
  • [ table ]: The table of piped neighbor shapes.

getRight​

shape:getRight()

Returns the direction of the shape's right side.

Arguments:
Returns:

getShapeUuid​

shape:getShapeUuid()

Returns the shape's uuid.

Arguments:
Returns:

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.

Arguments:
Returns:
  • [ Vec3 ]: The negative sticky directions.
  • [ Vec3 ]: The positive sticky directions.

getUp​

shape:getUp()

Returns the direction of the shape's top side.

Arguments:
Returns:

getVelocity​

shape:getVelocity()

Returns the shape's linear velocity.

Arguments:
Returns:

getWorldPosition​

shape:getWorldPosition()

Returns the shape's world position.

Arguments:
Returns:

getWorldRotation​

shape:getWorldRotation()

Returns the shape's world rotation.

Arguments:
Returns:

getXAxis​

shape:getXAxis()

Returns the local x-axis vector of the shape.

Arguments:
Returns:
  • [ Vec3 ]: The x-axis vector.

getYAxis​

shape:getYAxis()

Returns the local y-axis vector of the shape.

Arguments:
Returns:
  • [ Vec3 ]: The y-axis vector.

getZAxis​

shape:getZAxis()

Returns the local z-axis vector of the shape.

Arguments:
Returns:
  • [ Vec3 ]: The z-axis vector.

replaceShape​

shape:replaceShape( uuid )
Server-Only

Replaces a shape with another.

note

The replacement shape must have the exact same size/bounding box as the current shape!

Arguments:
  • shape [ Shape ]: The shape.
  • uuid [ Uuid ]: The uuid of the replacement shape.

setColor​

shape:setColor()
Server-Only

Sets the shape's color.

Arguments:

shapeExists​

shape:shapeExists()
warning

This function is deprecated!
Use sm.exists instead.

Returns true if the shape exists.

Arguments:
Returns:
  • [ bool ]: Whether the shape exists or not.

shapesInSphere​

shape.shapesInSphere( center, radius )
note

Due to a bug in the game, this function needs to be called with . instead of :.

Returns a table of shapes that are inside the sphere.

Arguments:
  • center [ Vec3 ]: The sphere center position.
  • radius [ number ]: The sphere radius.
Returns:
  • [ table ]: The table of shapes in the sphere.

transformDirection​

shape:transformDirection( vector )

Transform a world direction to the local shape transform.

Arguments:
  • shape [ Shape ]: The shape.
  • vector [ Vec3 ]: The untransformed direction.
Returns:
  • [ Vec3 ]: The transformed direction.

transformLocalPoint​

shape:transformLocalPoint( vector )

Transforms a local point to world space.

local worldPos = self.shape:transformLocalPoint( localPos )
Arguments:
Returns:

transformPoint​

shape:transformPoint( vector )

Transforms a world point to the local shape transform.

local localpos = self.shape:transformPoint( worldPos )
Arguments:
Returns:

transformRotation​

shape:transformRotation( quat )

Transforms 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 )
Arguments:
  • shape [ Shape ]: The shape.
  • quat [ Quat ]: The untransformed quaternion.
Returns:
  • [ Quat ]: The transformed quaternion.