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.

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.

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

Adds given Object as a child.

Object extensions like Shape or MutableShape are naturally accepted too.

By default, when using AddChild, the child maintains it's LocalPosition. But since the local position remains the same in the new parent, it means the child's world position may change.

The keepWorld optional parameter, false by default, can be used to maintain the child's Position (world position) instead.

It's also a good practice to set child/parent relationships before setting positions.

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.

o:RemoveChild(someChildObject)

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

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.

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 to world coordinate system.

Converts Block coordinates to local coordinate system.

Converts world coordinates to Block coordinate system.

Converts local coordinates to Block coordinate system.

Properties

Returns an array of BlockProperties (Palette)

Note: non-opaque and light emissive block colors can't be changed after game start.

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 only

That can all be configured differently depening on your needs.

local object = 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)
object.Physics = true

-- 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 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(o1, o2)
  -- `o1` is `object` here
  print("collision ended between", o1, "and", o2)
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.
Nothing else changes, the Map remains in the scene and it keeps being affected by the simulation (collisions, etc.).

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 stop on contact) and 1 (full slide, no friction), values higher than 1 are allowed and will create an increasing momentum, like sliding on ice.

The combined bounciness of 2 Objects in contact represents how much of the moving Object's velocity is produced after being in contact with 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).

Returns number of child Objects.

Inherited from Shape

Hide

number Depth read-only

Returns Map's depth, measured in cubes.

number Height read-only

Returns Map's height, measured in cubes.

number Width read-only

Returns Map's width, measured in cubes.

Box BoundingBox read-only

The BoundingBox represents the bounds of the Map. It is the limits of the Shape's blocks.

Number3 Min read-only

The coordinates of the min limit of the Map's BoundingBox.

Number3 Center read-only

The coordinates of the center of the Map's BoundingBox.

Number3 Max read-only

The coordinates of the max limit of the Map's BoundingBox.