Maps
Runtime APIs for layered levels, tile and node layers, and spawning map-placed instances.
For collision and overlap on map-spawned instances, see Nodes / Collision.
For a practical guide focused on loadMapEntities, see Loading Map Entities.
For game-level checkpoint flow using snapshots, see Checkpoints & Snapshots.
Map loading helpers
These control which map nodes exist as scripted instances and sync level data for a logical level (mapIndex / levelIndex) or a single layer within that level.
getNumberOfMaps()— How many logical levels exist in the cart (legacy carts: same as the number of raw maps).loadMapEntities(mapIndex)— Unloads all map-spawned entities, resets that level’s entities and tiles to cart data, then spawns scripted instances (full restart-style load).loadMapLayerEntities(mapIndex, layerIndexOrName)— Same reset + spawn behavior, scoped to one layer (by index or name).unloadMapEntities()— Removes all currently loaded map-spawned entities (Lua); script-spawned entities are unchanged.unloadMapLayerEntities(mapIndex, layerIndexOrName)— Unloads only entities belonging to that map + layer scope.
Lower-level reset helpers (resetMapLevelEntities, resetMapLayerEntities, resetMapLevelTiles, resetMapLayerTiles) are listed in the IDE/engine reference; loadMapEntities / loadMapLayerEntities call the appropriate resets before spawning.
Examples
-- Full level load: reset engine entities + tiles to cart, then spawn loadMapEntities(1) -- One layer scope (same reset + spawn, scoped) loadMapLayerEntities(1, "Foreground")
drawMap
Draw a whole level at a world position. Pass the level number (0 is the first level), or the level name from the Level Editor.
- drawMap(levelIndex, x, y) -> void
- drawMap(levelName, x, y) -> void
Parameters
- levelIndex — Which level (0 is the first).
- x — World-space X in pixels.
- y — World-space Y in pixels.
- levelName — Level name as in the editor.
Returns
- void — No return value.
Examples
-- Draw level 0 at the top-left of the world.
drawMap(0, 0, 0)
-- Draw the level named 'Town' at (0, 0).
drawMap("Town", 0, 0)drawMapLayer
Draw one layer of a level at a world position. Pass the layer number (0 is the bottom layer), or the layer name from the Level Editor.
- drawMapLayer(levelIndex, layerIndex, x, y) -> void
- drawMapLayer(levelIndex, layerName, x, y) -> void
Parameters
- levelIndex — Which level (0 is the first).
- layerIndex — Which layer (0 is the bottom layer).
- x — World-space X in pixels.
- y — World-space Y in pixels.
- layerName — Layer name as in the editor.
Returns
- void — No return value.
Examples
-- Draw layer 0 of level 0 at (0, 0). Layer 0 is the bottom layer.
drawMapLayer(0, 0, 0, 0)
-- Draw the layer named 'Background' of level 0 at (0, 0).
drawMapLayer(0, "Background", 0, 0)drawMapLayerRange
Draw a contiguous range of layers (tile + node) for a level, back-to-front.
- drawMapLayerRange(levelIndex, firstLayerIndex, lastLayerIndex, x, y) -> void
Parameters
- levelIndex — Which level (0 is the first).
- firstLayerIndex — First layer in the range to draw.
- lastLayerIndex — Last layer in the range to draw.
- x — World-space X in pixels.
- y — World-space Y in pixels.
Returns
- void — No return value.
Examples
-- Draw layers 0 through 2 of level 0 at (0, 0).
drawMapLayerRange(0, 0, 2, 0, 0)getMapLayerKind
Return "tile" or "node" for one layer. Pass the layer number, or the layer name. An unknown level or layer returns an empty string.
- getMapLayerKind(levelIndex, layerIndex) -> string
- getMapLayerKind(levelIndex, layerName) -> string
Parameters
- levelIndex — Which level (0 is the first).
- layerIndex — Which layer (0 is the bottom layer).
- layerName — Layer name as in the editor.
Returns
- string
Examples
-- "tile" or "node" for layer 0 of level 0.
local kind = getMapLayerKind(0, 0)
-- The same check for the layer named 'Background'.
local backgroundKind = getMapLayerKind(0, "Background")getMapTile
Return the sprite id stored in the tile layer map at the given tile coordinates. Non-tile layers return 0.
- getMapTile(levelIndex, layerIndex, tileX, tileY) -> int
Parameters
- levelIndex — Which level (0 is the first).
- layerIndex — Which layer (0 is the bottom layer).
- tileX — Tile column on the map.
- tileY — Tile row on the map.
Returns
- int
Examples
-- Read the sprite on layer 0 of level 0, at tile column 3, row 4.
local sprite = getMapTile(0, 0, 3, 4)setMapTile
Write a sprite index into the tile layer at the given tile coordinates. spriteIndex is clamped to 0–2048. Returns false if the level, layer, or tile index is invalid, or the layer is not a tile layer.
- setMapTile(levelIndex, layerIndex, tileX, tileY, spriteIndex) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- layerIndex — Which layer (0 is the bottom layer).
- tileX — Tile column on the map.
- tileY — Tile row on the map.
- spriteIndex — Sprite index (1-based). Sheet 0 is 1–256, sheet 1 is 257–512, and so on.
Returns
- bool
Examples
-- Put sprite 12 on layer 0 of level 0, at tile column 3, row 4.
setMapTile(0, 0, 3, 4, 12)setMapNodeEnabled
Updates the map node `enabled` flag in the engine. When `enabled` is false, the node is ignored for updates, `hasCollided*`, and the collider overlay. `visible` only affects drawing. For collision-only off while staying enabled, use `setMapNodeEnableCollisions`. `destroy(instance)` sets this to false for map-spawned instances.
- setMapNodeEnabled(levelIndex, nodeId, enabled) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- nodeId — Id of the map node.
- enabled — If false, the node is turned off (no updates or collisions).
Returns
- bool
Examples
-- Turn off the map node with id 'door', so it stops updating and colliding.
setMapNodeEnabled(0, "door", false)setMapNodeVisible
Updates the map node `visible` flag in the engine (draw visibility only). Invisible nodes still participate in `hasCollided*` when `enabled` and `enableCollisions` are true. `destroy(instance)` sets both enabled and visible to false for map-spawned instances.
- setMapNodeVisible(levelIndex, nodeId, visible) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- nodeId — Id of the map node.
- visible — If false, the node is hidden.
Returns
- bool
Examples
-- Hide the map node with id 'door'. It can still collide.
setMapNodeVisible(0, "door", false)setMapNodeEnableCollisions
When `enableCollisions` is false, the map node is skipped for collision checks (`hasCollided*`) and the collider debug overlay, while `enabled` and `visible` can stay true. Default in map data is true.
- setMapNodeEnableCollisions(levelIndex, nodeId, enableCollisions) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- nodeId — Id of the map node.
- enableCollisions — If false, collisions ignore this node.
Returns
- bool
Examples
-- Leave the node 'door' on the map, but stop it colliding.
setMapNodeEnableCollisions(0, "door", false)loadMapEntities
Unload all map-spawned scripted nodes, reset that level’s map entities and tiles to cart defaults, then spawn instances for types that define a script (including lifecycle methods). Placed nodes without a script are still drawn and can still collide. Always performs a full restart-style load.
- loadMapEntities(mapIndex) -> bool
Parameters
- mapIndex — Which map / level to load from.
Returns
- bool
Examples
-- Restart level 0 and spawn its map nodes.
loadMapEntities(0)loadMapLayerEntities
Unload map entities for one layer scope, reset that layer’s entities and tiles to cart defaults, then spawn instances for that scope—same restart semantics as loadMapEntities but scoped to one layer.
- loadMapLayerEntities(mapIndex, layerIndexOrName) -> bool
Parameters
- mapIndex — Which map / level to load from.
- layerIndexOrName — Layer number or layer name.
Returns
- bool
Examples
-- Restart layer 1 of level 0 and spawn that layer's nodes.
loadMapLayerEntities(0, 1)saveSnapshot
Captures map state for the **current** level (last successful `loadMapEntities` / `loadMapLayerEntities`). Returns a numeric snapshot id; pass the same id as `replaceSnapshotId` to overwrite that checkpoint. Logs approximate snapshot size to the play console. IDs are invalid after reload.
- saveSnapshot([replaceSnapshotId]) -> snapshotId
Parameters
- [replaceSnapshotId] — Optional id of a snapshot to replace.
Returns
- snapshotId
Examples
-- Save the current level and keep the id.
local id = saveSnapshot()
-- Save again into that same snapshot.
saveSnapshot(id)loadSnapshot
Restores map data for the stored level, then respawns map-placed nodes for that level without a full reset (so the snapshot is not discarded). Returns success and, on success, the saved level index as a second return value. Does not restore script globals, inventory, or nodes created with `spawn`.
- loadSnapshot(snapshotId) -> bool [, savedLevelIndex]
Parameters
- snapshotId — Snapshot id from saveSnapshot.
Returns
- bool [, savedLevelIndex]
Examples
-- Save the level, then restore that snapshot. level is the saved level number.
local id = saveSnapshot()
local ok, level = loadSnapshot(id)deleteSnapshot
Frees a snapshot by id in the engine to reclaim memory.
- deleteSnapshot(snapshotId) -> void
Parameters
- snapshotId — Snapshot id from saveSnapshot.
Returns
- void — No return value.
Examples
-- Save the level, then forget that snapshot.
local id = saveSnapshot()
deleteSnapshot(id)resetMapLevelEntities
Reset all node/entity layers in the level back to cart defaults.
- resetMapLevelEntities(levelIndex) -> bool
Parameters
- levelIndex — Which level (0 is the first).
Returns
- bool
Examples
-- Put every node layer in level 0 back to the cart's original layout.
resetMapLevelEntities(0)resetMapLayerEntities
Reset one node/entity layer scope back to cart defaults.
- resetMapLayerEntities(levelIndex, layerIndexOrName) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- layerIndexOrName — Layer number or layer name.
Returns
- bool
Examples
-- Put layer 1 of level 0 back to the cart's original nodes.
resetMapLayerEntities(0, 1)resetMapLevelTiles
Reset tile data for all tile layers in the level back to cart defaults.
- resetMapLevelTiles(levelIndex) -> bool
Parameters
- levelIndex — Which level (0 is the first).
Returns
- bool
Examples
-- Put every tile layer in level 0 back to the cart's original tiles.
resetMapLevelTiles(0)resetMapLayerTiles
Reset tile data for one tile layer scope back to cart defaults.
- resetMapLayerTiles(levelIndex, layerIndexOrName) -> bool
Parameters
- levelIndex — Which level (0 is the first).
- layerIndexOrName — Layer number or layer name.
Returns
- bool
Examples
-- Put the tiles on layer 1 of level 0 back to the cart's original tiles.
resetMapLayerTiles(0, 1)unloadMapEntities
Unload all currently loaded map-spawned entities. Script-spawned entities are not affected.
- unloadMapEntities() -> void
Returns
- void — No return value.
Examples
-- Remove every node that was spawned from the map.
unloadMapEntities()unloadMapLayerEntities
Unload currently loaded map-spawned entities that belong to the target map layer scope only.
- unloadMapLayerEntities(mapIndex, layerIndexOrName) -> void
Parameters
- mapIndex — Which map / level to load from.
- layerIndexOrName — Layer number or layer name.
Returns
- void — No return value.
Examples
-- Remove map nodes that belong to layer 1 of level 0.
unloadMapLayerEntities(0, 1)getNumberOfMaps
Return how many logical levels are available (for legacy carts this matches the number of raw maps).
- getNumberOfMaps() -> int
Returns
- int
Examples
-- How many levels are in this cart.
local count = getNumberOfMaps()