Map

Map extends MutableShape, adding functions and properties to it.
Map is not creatable, there's only one instance of it. It can only be accessed through its globally exposed variable.

Map is a global variable that represents the game map.

How to load a map for your game?

Config = {
  Map = "aduermael.rockies"
}
Config.Map = "aduermael.rockies"

(See Config for more details regarding Map & Items loading)

Functions

Inherited from MutableShape

Hide

Adds a Block to the Map. You may provide a Block, a palette index to an existing color in Map's Palette, or any color which will be added automatically to the Map's Palette if needed.

Returns true if a block was successfully added.

local block = Block(Color(200, 0, 200), 10, 10, 10)
someMutableShape:AddBlock(block)

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

-- returns whether the block was added or not:
local added = someMutableShape:AddBlock(1, 10, 10, 10)
if added ~= false then
  -- block successfully created!
end

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

Inherited from Object

Hide

nil AddChild ( Object child, boolean keepWorld optional )

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.

local o = Object()
local myShape = Shape(Items.someuser.someitem)
o:AddChild(myShape)
nil RemoveChild ( Object child, boolean keepWorld optional )

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)
nil RemoveChildren ( boolean keepWorld optional )

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()
nil GetChild ( integer index )

Get child Object at index.

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

Get Map's parent.

print(myObject:GetParent())

Returns true if the two Objects may collide with each other.

Resets to Map's original collision box. For example, Player and Shape objects will revert to fitting their model bounding box.

Inherited from Shape

Hide

Gets a Block from the Shape.
Returned Block is read-only because Shape is immutable, unlike MutableShape.
Returns nil if there is no Block at those coordinates (i. e. if it's "air").

Converts Block coordinates from model space to world space.

Converts Block coordinates from model space to local space.

Converts a point from world space to model space.

Converts a point from local space to model space.

Computes and returns the smallest axis-aligned box that encompasses all of Map's blocks, in local space.

Computes and returns the smallest axis-aligned box that encompasses all of Map's blocks, in world space.

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

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.

Client.OnStart = function()
  Map.Palette[1].Light = true

  -- refresh baked lighting for existing blocks
  Map:ComputeBakedLight(function() print("Map baked lighting done!") end)
end
nil FitToScreen ( Camera camera, number screenRatio optional, boolean spherize optional )

Fits the Map to the given Camera's view'. This function moves the shape back until it fits on the camera view.

Optional parameters:
- screenRatio indicates the percentage of the screen that should be covered by the target.
- spherize switches between box fit (false) and sphere fit (true), spherize can be useful if the function is used every frame on a moving object, for smoother motion, but the fit will be wider.

Properties

Inherited from Object

Hide

Collision groups the Map belongs to.

⚠️ It doesn't mean the Map will collide with other Objects in these groups.

If the Map 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 depening on your needs.

local object1 = Object()
local object2 = Object()
-- It's not mandatory to set Physics to true
-- An object with Physics set to false contributes to the
-- physics simulation as a static item (can't be moved)
object1.Physics = true
object2.Physics = true

-- making sure 2 objects collide with each other
-- NOTE: by default:
-- Map.CollisionGroups == {1},
-- Player.CollisionGroups == {2},
-- Object.CollisionGroups == {3}
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}

-- making an object collides with the Map and Players
local object = Object()
object.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

-- for Player (local player) to collide with other players and the Map
Player.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

Collision groups the Map collides with.

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}

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 when the Map 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

Executed when the Pointer is dragged (moved while down). Receives a PointerEvent parameter, just like Pointer.Drag.

(nil by default)

myObject.OnPointerDrag = function(pointerEvent)
  print("dx:", pointerEvent.DX, "dy:", pointerEvent.DY)
end

Can be set to true for the Map to be hidden recursively, meaning Map and all of its children are hidden.

Nothing else changes, the Map remains in the scene and it keeps being affected by the simulation (collisions, etc.).

Can be set to true for the Map to be hidden individually.

Nothing else changes, the Map remains in the scene and it keeps being affected by the simulation (collisions, etc.).

Size in world units of the shadow cookie projected under the Map, 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.

Tick is a function executed ~30 times per second when set (nil by default). Provides the Map and elapsed time in seconds as parameters.

-- executed ~30 times per second on each user device
myObject.Tick = function(object, dt)
  print("elapsed:", dt, "seconds")
end
number LossyScale read-only

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.

Inherited from Shape

Hide

Palette is an array of BlockProperties, with each entry corresponding to a style of block used by the Map's model.

number Depth read-only

Returns Map's depth, measured in blocks.

number Height read-only

Returns Map's height, measured in blocks.

number Width read-only

Returns Map's width, measured in blocks.

Number3 Size read-only

Returns Map's model bounding box size, measured in blocks. Equivalent to Number3(shape.Width, shape.Height, shape.Depth).

Box BoundingBox read-only

The bounding box represents the bounds of the Map in model space.

It is the smallest axis-aligned box that encompasses all of Map's blocks.

Number3 Min read-only

The minimum point of the Map's BoundingBox.

Number3 Center read-only

The center of the Map's BoundingBox.

Number3 Max read-only

The maximum point of the Map's BoundingBox.

integer BlocksCount read-only

The number of blocks in Map's model.

Whether or not the shape should cast shadows. Light objects set as shadow casters will affect all shapes in matching layers.

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.

Whether or not the Map should ignore scene lighting, false by default.

Whether or not inner faces between blocks of different colors should be drawn for this shape, true by default.

Original item name of this shape. If it was created programmatically, item name is nil.