MutableShape

MutableShape extends Object, adding functions and properties to it.

A MutableShape is an Object that carries and displays a set of Blocks. The difference with Shape is that MutableShape Blocks can be modified.

Constructors

MutableShape ( Item item )

Creates a MutableShape with imported Item.

local s = MutableShape(R.username.itemName)

Functions

Block AddBlock ( Block block )
Block AddBlock ( number paletteIndex, number X, number Y, number Z )

Adds a Block to the MutableShape.

Returns created Block (or nil if it fails).

local block = Block(1, 10, 10, 10)
someMutableShape:AddBlock(block)

-- AddBlock can also be called using
-- block's palette index and coordinates:
someMutableShape:AddBlock(1, 10, 10, 10)

-- created block is returned:
local newBlock = someMutableShape:AddBlock(1, 10, 10, 10)
if newBlock ~= nil then
  -- block successfully created!
end

-- ⚠️
local block = Block(1, 10, 10, 10)
local newBlock = someMutableShape:AddBlock(block)
-- Here `newBlock` is not the same as `block`
-- they both have the same palette index and coordinates
-- but `newBlock` has a parent shape while `block` doesn't.
nil AddChild ( Object child )

Adds given Object as a child.

Object extensions like Shape or MutableShape are naturally accepted too.

local o = Object()
local myShape = Shape(Items.someuser.someitem)
o:AddChild(myShape)

Gets a Block from the MutableShape.
Returns nil if there is no Block at the given coordinates (i. e. if it's "air").

nil GetChild ( number index )

Get child Object at index.

if o.ChildrenCount > 0 then
  print(o:GetChild(1)) -- prints first child
end

Converts a local position to world coordinate system.

local p = Number3(1, 2, 3)
local pInWorldCoords = myObject:PositionLocalToWorld(p)

Converts a world position to local coordinate system.

local p = Number3(1, 2, 3)
local pInLocalCoords = myObject:PositionWorldToLocal(p)

Unsets parent/child relationship with child parameter. The child ends up being deleted if it has no other references.

o:RemoveChild(someChildObject)

Unsets parent/child relationship with all children. Individual children end up being deleted if they have no other references.

o:RemoveChildren()

Removes the MutableShape from its parent. Doesn't do anything if the MutableShape has no parent.

o:RemoveFromParent()

Converts a local rotation to world coordinate system.

Converts a world rotation to local coordinate system.

nil SetParent ( Object parent )

Sets parent/child relationship with parent parameter. nil can be used to remove the Object from its parent.

local o = Object()
o:SetParent(Map) -- o is now a child of the map
-- (Map is an extension of Object)

Properties

MutableShape's continuous acceleration.

Default value: {0,0,0}.

⚠️ Acceleration is nil and can't be set if MutableShape.Physics is false.

-- Acceleration can be used to compensate gravity: 
myObject.Acceleration = -Config.ConstantAcceleration
-- myObject's acceleration is now the invert of 
-- Config.ConstantAcceleration, cancelling it.

Anchor is a point that you set as a way to specify what part of the MutableShape will be used when setting its Position.

-- Anchor at the center of the shape:
myShape.Anchor = {0.5,0.5,0.5}

Backward is a unit vector (vector with a length of 1). It determines which direction is "backward" for the MutableShape.

Setting it is a way to rotate the MutableShape.

number ChildrenCount read-only

Returns number of child Objects.

number Depth read-only

Returns MutableShape's depth, measured in cubes.

Down is a unit vector (vector with a length of 1). It determines which direction is "down" for the MutableShape.

Setting it is a way to rotate the MutableShape.

Forward is a unit vector (vector with a length of 1). It determines which direction is "forward" for the MutableShape.

Setting it is a way to rotate the MutableShape.

number Height read-only

Returns MutableShape's height, measured in cubes.

Left is a unit vector (vector with a length of 1). It determines which direction is "left" for the MutableShape.

Setting it is a way to rotate the MutableShape.

Position of the MutableShape in its parent.
In other words, LocalPosition refers to the position of the MutableShape relative to the {0,0,0} position of its parent.

Rotation of the MutableShape in its parent.

Nested Object local rotations are combined to obtain the "world rotation" (Object.Rotation), the Object's final on-screen rotation.

Scale of the Object, in its parent.

Nested Object local scales are combined to obtain the "world scale" (Object.Scale), the Object's final on-screen scale.

myObject.LocalScale = 2 -- the Object is now 2 times bigger
topLevelObject.LocalScale = 2
local o = Object()
o.LocalScale = 0.5
topLevelObject:AddChild(o) -- o becomes a child of topLevelObject
-- o ends up being displayed with a scale of 1

Be aware, this Motion property is a hack regarding laws of physics. (sorry Isaac)

But it's very practical to move objects without worrying about forces at play.

This is what's being used by default when you're moving around with your avatar (see Client.DirectionalPad). It's the reason why you can stop moving horizontally while in the air.

Basically, Motion is a constant velocity that's added to MutableShape.Velocity each frame to obtain the final movement. (MutableShape.Velocity value is not impacted)

Motion is expressed in world coordinates.

⚠️ Motion is nil and can't be set if MutableShape.Physics is false.

local speed = 10
myObject.Motion = Camera.Forward * speed
-- myObject will move in the same direction the camera is currently facing.
-- If the Camera rotates after this, it won't change where myObject is heading.

Turns physic simulation on/off when set.

⚠️ When turned on, MutableShape.Velocity & MutableShape.Motion are set to {0,0,0}.

Position of the MutableShape in the world.

local o = Object()
-- places the object where the local player is
o.Position = Player.Position

Right is a unit vector (vector with a length of 1). It determines which direction is "right" for the MutableShape.

Setting it is a way to rotate the MutableShape.

Rotation of the MutableShape in the world (as seen on screen).

While it usually works for simple operations (like Rotation.X = Rotation.X + someAngle), we advise you to use Number3.Rotate to rotate an object around X, Y & Z axis.

You can also set unit vectors like MutableShape.Up, MutableShape.Right or MutableShape.Forward to orient your object.

local o = Object()
o.Rotation:Rotate({0, 2, 0})
-- o rotated 2 radians arount Y axis

-- another way to rotate the object:
o.Forward = {0, 0, 1}
o.Forward = Camera.Forward

Up is a unit vector (vector with a length of 1). It determines which direction is "up" for the MutableShape.

Setting it is a way to rotate the MutableShape.

Velocity of the MutableShape in world coordinates.

⚠️ Velocity is nil and can't be set if MutableShape.Physics is false.

-- makes myObject jump:
myObject.Velocity.Y = 100
number Width read-only

Returns MutableShape's width, measured in cubes.