Shape
A Shape is an Object that carries a voxel model made of Blocks.
It introduces an additional coordinate system called model space i.e. relative to model origin.
Any point can be expressed in model space. If the point is expressed with integers, then it may represent a Block coordinates.
Note that if the Shape.Pivot is set to zero, then model space and local space become equivalent.
Constructors
Creates a Shape which model can be empty, loaded from an imported Item (see Items), or copied from an existing Shape or MutableShape.
The optional table parameter can be used to override default configuration: {recurse = false, bakedLight = false}.
- recurse (false by default) will copy and replicate the full shape hierarchy, including all children objects.
- bakedLight (false by default) determines whether or not the shape should be loaded with baked lighting. If true, it will use the baked lighting information saved with the original item, or compute it from scratch if there was none. Any subsequent changes to the shape's blocks will automatically maintain its baked lighting.
The first step after creating a shape is usually to add it to the world using SetParent or AddChild, then place it by setting its Position.
-- create shape from items declared in the [Items] table local myShape = Shape(Items.someuser.someitem) -- add to the world and place it World:AddChild(myShape) myShape.Position = { 0, 5, 15 }
-- create a full copy of a composite shape, including all children objects local myShape = Shape(myCompositeShape, {includeChildren = true})
Functions
Removes the shape baked lighting and frees up any memory used. It could be an optimization step for scenes pooling a large amount of shapes.
Computes the shape baked lighting. It is a combination of a white ambient light and all blocks that were set as light sources. Other shapes entering inside this shape's bounding box will be affected by its baked lighting.
This is an efficient way of applying lighting to shapes without affecting performance. The baked lighting of a shape is cached to speed up subsequent loads.
Once a shape has baked lighting, it will be automatically maintained when changing its blocks.
However, directly changing the transparency or light properties of shape's Palette entries of _existing_ blocks will not be reflected on the shape immediately, and will require another call to this function.
You may want to call this function only if:
- activating baked lighting on a shape for the first time
- setting light property i.e. shape.Palettei.Light = true/false of _existing_ shape blocks
- setting transparency i.e. shape.Palettei.Color.A = newValue of _existing_ shape blocks
You _do not_ need to call this function if:
- ANY blocks, including light and transparent blocks, are added/removed at runtime
- setting light or transparent property of an unused palette entry first, before adding blocks using that entry
Client.OnStart = function() Map.Palette[1].Light = true -- refresh baked lighting for existing blocks Map:ComputeBakedLight(function() print("Map baked lighting done!") end) end
Computes and returns the smallest axis-aligned box that encompasses all of Shape's blocks, in local space (i.e. expressed from This.Pivot).
Converts given Number3 from local space to model space.
Converts given Number3 from world space to model space.
Inherited from Object
HideLoads the given item asynchronously and calls the callback once done. The parameter itemName follows the usual naming convention user.item.
This is a function of the global Shape, to be called as Object:Load(itemName, callback, config).
The config table options are as follows,
- mutable allows to create the item shapes as MutableShape instead of Shape. Default false.
- bakedLight allows to generate baked lighting for the item shapes. Default false.
Adds given Object as a child. Object extensions like Shape or MutableShape are naturally accepted too.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
It's a good practice to set child/parent relationships before setting positions, if you do not want to use the keepWorld parameter.
Note that there is a cyclic hierarchy protection that will prevent you from creating parenting loops.
local o = Object() local myShape = Shape(Items.someuser.someitem) o:AddChild(myShape)
Unsets parent/child relationship with child parameter. The child ends up being deleted if it has no other references.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
o:RemoveChild(someChildObject)
Unsets parent/child relationship with all children. Individual children end up being deleted if they have no other references.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
o:RemoveChildren()
Iterates over all descendants of Shape and calls the callback function for each.
The callback function is called with the descendant as the only argument.
The config table accepts two boolean options:
- deepFirst: if true, traverses depth-first instead of root-first. Default false.
- includeRoot: if true, includes Shape in the recursion. Default true.
o:Recurse(function(descendant) print(descendant) end, { includeRoot = true })
Returns the first descendant Object for which the search function returns true.
If no descendant is found, returns nil.
The search function is called with the descendant as the only argument.
The config table accepts two boolean options:
- deepFirst: if true, traverses depth-first instead of root-first. Default false.
- includeRoot: if true, includes Shape in the recursion. Default false.
local leaf = oakTree:FindFirst(function(o) return o.Name == "leaf" end) if leaf then print("found a leaf:", leaf) end
Returns all descendants Objects for which the search function returns true.
If no descendant is found, returns an empty table.
The search function is called with the descendant as the only argument.
The config table accepts two boolean options:
- deepFirst: if true, traverses depth-first instead of root-first. Default false.
- includeRoot: if true, includes Shape in the recursion. Default false.
local leaves = oakTree:Find(function(o) return o.Name == "leaf" end) for i, leaf in leaves do print("leaf #" .. i .. ":", leaf) end
Get child Object at index.
if o.ChildrenCount > 0 then print(o:GetChild(1)) -- prints first child end
Sets parent/child relationship with parent parameter. nil can be used to remove the Object from its parent.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
It's a good practice to set child/parent relationships before setting positions, if you do not want to use the keepWorld parameter.
Note that there is a cyclic hierarchy protection that will prevent you from creating parenting loops.
local o = Object() o:SetParent(Map) -- o is now a child of the map -- (Map is an extension of Object)
Removes the Shape from its parent. Doesn't do anything if the Shape has no parent.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
o:RemoveFromParent()
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)
Rotates the Shape in its own coordinates system.
o = Object() -- rotate with provided Euler angle o:RotateLocal({0, 0, math.pi / 2.0}) -- rotate along specified axis o:RotateLocal(o.Forward, math.pi / 2.0)
Converts a rotation from local to world relative to this object.
Converts a rotation from world to local relative to this object.
Returns true if the two Objects may collide with each other.
Iterates over all descendants of Shape and calls the callback function for each.
The callback function is called with the descendant as the only argument.
The config table options are as follows,
- includeRoot whether to include Shape in the iteration. Default true.
- depth the maximum depth of the iteration. Default -1 (unlimited).
- deepFirst whether to iterate in depth-first order. Default false.
If you were to remove an object from its parent while recursing through it, the object removal will be delayed until the full recursion is completed.
o:Recurse(function(descendant) print(descendant.Name) end, { includeRoot = true })
Properties
The number of blocks in Shape's model.
The bounding box represents the bounds of the Shape in model space (the space where blocks are placed).
It is the smallest axis-aligned box that encompasses all of Shape's blocks.
If you are looking for the bounding box in a different space, see Shape.ComputeLocalBoundingBox and Shape.ComputeWorldBoundingBox.
The center of the Shape's bounding box. Shortcut to Shape.BoundingBox.Center.
Returns Shape's depth, expressed in model space (the space where blocks are placed). Shortcut to Shape.BoundingBox.Size.Z.
Enable and configure draw modes using this property. Setting this to nil disables all draw modes.
Currently, one draw mode is supported: { color=
- color as a Color, applied multiplicatively to the whole shape. Alternatively, it can be set to a table of options (see below).
Color options are,
- multiplicative as a Color, applied multiplicatively to the whole shape.
- additive as a Color, applied additively to the whole shape.
The additive and multiplicative colors are a shortcut to modify shape colors as a whole, but it could also be done by adding or multiplying each colors of the shape palette.
All these options can be set at runtime or animated individually.
Returns Shape's height, expressed in model space (the space where blocks are placed). Shortcut to Shape.BoundingBox.Size.Y.
Whether or not inner faces between blocks of different colors should be drawn for this shape, true by default.
Whether or not the shape should ignore scene lighting, false by default. If true, the shape won't be affected by any light and shadows from other objects.
Original item name of this shape. If it was created programmatically, item name is nil.
Integer or table of integers between 1 and 12. Cameras only render shapes corresponding to their layers, and lights only affect shapes in matching layers.
The maximum point of the Shape's bounding box. Shortcut to Shape.BoundingBox.Max.
The minimum point of the Shape's bounding box. Shortcut to Shape.BoundingBox.Min.
Palette is an array of BlockProperties, with each entry corresponding to a style of block used by the Shape's model. Each of the Shape's block use a palette index, indicating which entry to use to draw that block.
If Shape.Palette is set, the shape will start using the new palette in place. Each of its block's palette index will then point to the BlockProperties of that new palette. This can be used to share a single palette between multiple shapes, for example to create effects by changing color on a whole group of shapes at once.
Note that if you would like to keep the original colors of the shape while assigning another palette, you should use the Palette.Merge function instead.
Shape's pivot is a local point that acts as a reference for its transformations:
- translation is applied from its parent's pivot to its own pivot
- rotation is applied around the pivot
It is set by default to Shape's geometric center, which is equal to myShape.BoundingBox.Min + myShape.BoundingBox.Center.
You can override it with any point, even outside of the Shape's bounding box, as a way to modify how transformations are applied.
Note that setting the pivot to zero effectively means you are using the Shape's model origin as reference point for transformations.
-- set it to any arbitrary point myShape.Pivot = { 2.3, 5.0, 1.5 } -- set it to a specific block, it will use block's center myShape.Pivot = myShape:GetBlock(1, 1, 1) -- doing this resets pivot to its default value myShape.Pivot = myShape.BoundingBox.Min + myShape.BoundingBox.Center
Whether or not the shape should cast shadows onto other lit objects. Light objects set as shadow casters will affect all shapes in matching layers (see Light.CastsShadows).
Note that whether or not the shape is affected by lights and shadows from other objects depends on the separate property Shape.IsUnlit.
Returns Shape's model bounding box size, expressed in model space (the space where blocks are placed). Shortcut to Shape.BoundingBox.Size.
Returns Shape's width, expressed in model space (the space where blocks are placed). Shortcut to Shape.BoundingBox.Size.X.
Inherited from Object
HideShape's constant acceleration in world coordinates per second squared.
⚠️ Acceleration only affects Shape when Shape.Physics is PhysicsMode.Dynamic.
-- Acceleration can be used to compensate gravity: myObject.Acceleration = -Config.ConstantAcceleration -- myObject's acceleration is now the invert of -- Config.ConstantAcceleration, cancelling it.
Collision groups the Shape belongs to.
⚠️ It doesn't mean the Shape will collide with other Objects in these groups.
If the Shape belongs to group number 3 for example, it means all Objects that have group number 3 in their Object.CollidesWithGroups property will collide with it.
By default:
- Objects collide with the Map and other Objects
- Players collide with the Map only
That can all be configured differently depending on your needs.
Collision groups are best used as buckets created for gameplay needs, for example,
- a group for "hittable" objects that can be damaged by the player's weapon
- a group for recyclable Objects that are disabled and thrown back into their pool when they reach a certain trigger collider
- a group for static scenery objects that moving objects will bump into
- a group for objects that can get hit by raycasts executed for some specific game mechanic
It may well be the case that one object belongs to several or all of these groups, depending on the gameplay associated with it.
In general, it is bad practice to assign or add all collision groups from one object to another (unless making exact copies), as it isn't future-proof if you later add more groups. Instead, you should assign individual groups depending on what this new object should contribute to in your world.
-- these are the group numbers assigned by default to Map, Player, and all Objects local GROUP_MAP = 1 local GROUP_PLAYER = 2 local GROUP_OBJECT = 3 -- by default, this object will collide with the map and other objects local o = Object() o.Physics = PhysicsMode.Dynamic -- when in doubt, print the groups of your objects print(Map.CollisionGroups, Map.CollidesWithGroups) print(o.CollisionGroups, o.CollidesWithGroups) -- let's say our world needs an extra group for a gameplay mechanic, for example, a group for objects that can be hit by player's weapon (which could perform a raycast in that group) local GROUP_HITTABLE = 4 -- here, the object would collide with anything that cares about GROUP_OBJECT or GROUP_HITTABLE, in addition to itself wanting to collide with GROUP_MAP and GROUP_PLAYER o.CollisionGroups = { GROUP_OBJECT, GROUP_HITTABLE } o.CollidesWithGroups = { GROUP_MAP, GROUP_PLAYER } -- when adding new obstacle/scenery objects to our scene, you can simply re-use the GROUP_MAP as a way to say "this is part of the environment that is collidable" -- here, maybe this object only acts as an obstacle and doesn't contribute to anything else someBigRock.CollisionGroups = GROUP_MAP someBigRock.CollidesWithGroups = nil -- doing this effectively prevents all physics interaction on an object o.CollisionGroups = nil o.CollidesWithGroups = nil -- note that there is redundancy with CollisionGroups and CollidesWithGroups, so you can organize your groups however seems more convenient for you -- for example the following setups will all result in object1 and object2 colliding with each other object1.CollisionGroups = GROUP_OBJECT object1.CollidesWithGroups = nil object2.CollisionGroups = GROUP_OBJECT object2.CollidesWithGroups = GROUP_OBJECT object1.CollisionGroups = GROUP_OBJECT object1.CollidesWithGroups = GROUP_OBJECT object2.CollisionGroups = GROUP_OBJECT object2.CollidesWithGroups = nil object1.CollisionGroups = GROUP_OBJECT object1.CollidesWithGroups = GROUP_OBJECT object2.CollisionGroups = GROUP_OBJECT object2.CollidesWithGroups = GROUP_OBJECT object1.CollisionGroups = GROUP_OBJECT object1.CollidesWithGroups = nil object2.CollisionGroups = nil object2.CollidesWithGroups = GROUP_OBJECT
Collision groups the Shape collides with. See Shape.CollisionGroups.
By default:
- Objects collide with the Map and other Objects
- Players collide with the Map and the Objects
That can all be configured differently depending on your needs.
local object = Object() -- It's not mandatory to change Physics value. -- (default value is PhysicsMode.Static) -- An object with Physics set to PhysicsMode.Static contributes -- to the physics simulation as a static item (can't be moved) object.Physics = PhysicsMode.Dynamic -- making an object collide with the Map and Players object.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups -- for an Object to collide with other objects only -- (won't collide with the map) object.CollidesWithGroups = object.CollisionGroups -- for Player (local player) to collide with other players and the Map Player.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups -- making sure 2 objects collide with each others -- NOTE: by default: -- Map.CollisionGroups == {1}, -- Player.CollisionGroups == {2}, -- Object.CollisionGroups == {3} local object1 = Object() local object2 = Object() object1.CollisionGroups = {5} object2.CollisionGroups = {5} object1.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5 object2.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5 -- would also work this way if you don't -- remember Map's group (which can be changed too by the way) object1.CollidesWithGroups = Map.CollisionGroups + {5}
Sets the simulation mode for this object, it can be one of the following:
- PhysicsMode.Disabled: excluded from all physics features.
- PhysicsMode.Trigger: Shape's collision box is available for casts and collision callbacks, and is passed through by other dynamic objects.
- PhysicsMode.TriggerPerBlock: if Shape is a Shape, its model blocks are available for casts and collision callbacks, and is passed through by other dynamic objects.
- PhysicsMode.Static: Shape's collision box is available for casts, collision callbacks, and acts as an obstacle for other dynamic objects.
- PhysicsMode.StaticPerBlock: if Shape is a Shape, its model blocks are available for casts, collision callbacks, and act as obstacles for other dynamic objects.
- PhysicsMode.Dynamic: Shape's world-aligned collision box is available for casts, collision callbacks, may act as obstacles for other dynamic objects, and is itself fully simulated. When setting this mode, any children that may collide with the object will be automatically set to PhysicsMode.Disabled.
By default, players are PhysicsMode.Dynamic, shapes are PhysicsMode.Static, all other objects are PhysicsMode.Disabled.
You may use Dev.DisplayColliders to visualize each object's collision settings.
⚠️ When set to PhysicsMode.Disabled, Shape.Velocity & Shape.Motion are set to {0,0,0}.
nil by default. Can be set to a function that will be triggered when this object begins a collision with another object.
The function is called with 3 parameters:
- the object the callback was set for,
- the other actor in the collision,
- the world normal of the hit surface.
Note: it's not necessary to use all 3 parameters.
object.OnCollisionBegin = function(self, other, normal) print("collision began between", self, " and ", other, " with world normal ", normal) end
nil by default. Can be set to a function that will be triggered every frame where this object remains in contact with another object.
Like OnCollisionBegin, this function has 3 arguments: self, other, normal.
nil by default. Can be set to a function that will be triggered when the Shape ends colliding with another Object.
The function is called with 2 parameters: the object the callback was set for and the other actor in the collision.
object.OnCollisionEnd = function(self, other) print("collision ended between", self, "and", other) end
Position of the Shape in the world.
local o = Object() -- places the object where the local player is o.Position = Player.Position
Size in world units of the shadow cookie projected under the Shape, default is 0.0 (disabled).
The shadow cookie, also called blob shadow, is a square texture acting as a cheap alternative to projected shadows.
If this value is strictly positive, shadow cookies will be displayed when:
- the scene has no light source,
- the scene has light sources, but they are disabled because the client is using lower quality settings
Shadow cookies can be used as a fallback to your scene shadows for players with low quality settings, of course, you can also use them instead of shadows as a design choice.
Local position of the Shape relative to its parent.
All of Shape's ancestors local transformations are combined to obtain the Shape "world position" (Object.Position), the Object's final position.
Rotation of the Shape 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 Shape.Up, Shape.Right or Shape.Forward to orient your object.
local o = Object() o.Rotation = {0, math.pi, 0} -- o revolved half a turn on Y axis -- another way to rotate the object: o.Forward:Rotate({0, 0, math.pi / 2}) o.Forward = Camera.Forward
Tick is a function executed each frame when set (nil by default). Provides the Shape and elapsed time in seconds as parameters.
For general purposes, you may consider using Client.Tick instead. It is functionally the same, but is executed once for your world per frame, rather than once per frame per object.
The exact number of frames per second may fluctuate and depend on the device. It is typically around 60 frames per second.
myObject.Tick = function(object, dt) print("elapsed:", dt, "seconds since last frame") end
Local rotation of the Shape relative to its parent.
All of Shape's ancestors local transformations are combined to obtain the "world rotation" (Object.Rotation), the Object's final rotation.
Motion is an instantaneous displacement that contributes to moving Shape every frame, without changing Shape.Velocity directly, and without being affected by collision responses and other forces. It is expressed in world coordinates per second.
It's very useful to quickly implement character movement. 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.
⚠️ Motion only affects Shape when Shape.Physics is PhysicsMode.Dynamic.
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.
Scale of the Object, in its parent local space. Can be set to a number for a uniform scale.
Nested Object local scales are combined to obtain the "world scale" (Object.LossyScale), the Object's final scale.
-- make the object twice as big myObject.LocalScale = 2 -- equivalent to myObject.LocalScale = Number3(2, 2, 2) myObject.LocalScale = { 2, 2, 2 }
-- demonstrate how scales are combined in the hierarchy local parentObject = Object() parentObject:SetParent(World) parentObject.LocalScale = 2 local childObject = Object() childObject:SetParent(parentObject) childObject.LocalScale = 0.5 -- here, the scales would cancel each other: 2 x 0.5 = 1 print(childObject.LossyScale) -- returns (1,1,1)
Convenience property that attempts to match the actual world scale as much as it can. Note that Objects that have multiple levels of nested rotations and scales will return a skewed lossy scale.
The mass of the Object determines how much a given force can move it and whether or not another object can be pushed by it. It cannot be zero, a neutral mass is a mass of 1.
The combined friction of 2 Objects in contact represents how much the moving Object will be able to slide along the colliding Object.
It is a rate between 0 (full slide, no friction) and 1 (maximum friction). Values equal to or lower than 0 will keep or increase momentum, like sliding on ice. Values higher than 1 means a faster stop, up to a value of 2 to ensure a full stop on contact regardless of the colliding Object's own friction.
[Object.Friction] can be set per-face by providing a table with any combination of the following keys : right, left, front, back, top, bottom, other.
For example, to set the friction on the bottom face of an object's collider to 0 and 0.2 on every other faces, you could set, object.Friction = { bottom=0, other=0.2 }.
The combined bounciness of 2 Objects in contact represents how much of the moving Object's velocity is produced after being in contact with the colliding Object, it is a rate between 0 (no bounce) and 1 (100% of the velocity bounced). Values higher than 1 are allowed and will create an increasing momentum at each bounce (try at your own risk).
[Object.Bounciness] can be set per-face by providing a table with any combination of the following keys : right, left, front, back, top, bottom, other.
For example, to set the bounciness on the side faces of an object's collider to 0.2 and 0 on top and bottom faces, you could set, object.Bounciness = { top=0, bottom=0, other=0.2 }.
Returns number of child Objects.