Loading Map Entities

What does

loadMapEntities(mapIndex) is a full map-entity reload for one level.

When called, it:

1. removes currently loaded map-spawned Lua instances
2. resets that level's map entities to cart data
3. resets that level's tiles to cart data
4. spawns fresh Lua node instances from that level's Node layers

Use this when you want to treat the level as freshly loaded.

Default behavior on first run

By default, PIXELFALLS calls map spawning for the first level at startup:

• startup flow spawns map nodes from level 0
• this is equivalent to the default first-map load experience
• this behavior can be turned off in Game Settings: Auto-load first map entities on startup

You only need to call loadMapEntities(mapIndex) yourself when you want to switch/reload levels during gameplay.

What happens if you call it a second time

Calling loadMapEntities(...) again repeats the same full reload process.

That means:

• current map-spawned instances are discarded
• current tile edits for that level are reset to cart defaults
• new instances are spawned from the level data again

If you call it with a different mapIndex, it unloads current map-spawned entities and loads the new level's map-spawned entities.

Important behavior notes

• Map-spawned only: loadMapEntities manages entities created from Node layers. Script-spawned entities (spawn(...) from your code) are not part of map data resets.
• Resets map state: Any runtime changes to map tiles/entities in that level are reset to the cart's original data.
• Tracks current level for snapshots: saveSnapshot() / loadSnapshot() use the current level tracked by the map-loading helpers.
• Layer-specific alternative: Use loadMapLayerEntities(mapIndex, layerIndexOrName) when you want the same reset+spawn behavior for one layer only.

Basic usage

Copy
-- Load level 0 map entities (full reset + respawn)
loadMapEntities(0)

-- Later, switch to level 1
loadMapEntities(1)

Typical level-transition pattern

Copy
local currentLevel = 0

function goToLevel(nextLevel)
  if nextLevel == currentLevel then
    -- Force a clean reload of the same level
    loadMapEntities(currentLevel)
    return
  end

  currentLevel = nextLevel
  loadMapEntities(currentLevel)
end

vs snapshots

Use the right tool for the job:

• loadMapEntities(level): reset level map state to original cart data, then respawn map entities.
• loadSnapshot(id): restore a previously saved runtime checkpoint for that level.

If you call loadMapEntities(level) right after loadSnapshot(id), the snapshot restore is overwritten by a fresh reset.

For full snapshot/checkpoint behavior, see Checkpoints & Snapshots.