Map

Map is the runtime API for baked map content.

Maps are content bundles, not individual objects. A loaded map may contain:

• baked static world nodes
• baked collision/query data
• spawn points and markers
• environment defaults

Status

Partially implemented.

Implemented now on the server:

• Map.GetAvailable
• Map.Load
• Map.Unload
• Map.GetLoaded
• Map.GetInfo
• Map.BakeSmoke (experimental, editor/dev workflow)

Implemented now on shared/client:

• Map.GetAvailable
• Map.GetLoaded
• Map.GetInfo

Shared/client queries read from a built-in mirrored authoritative cache of baked map metadata and active-map lifecycle.

Scope

• runtime baked map lifecycle
• loaded map metadata
• integration with existing Environment and Node

Not in scope:

• map editor authoring operations
• raw authored JSON editing
• family-specific gameplay element authoring contracts for markers, checkpoints, and race pickups

For planned gameplay-element APIs, see:

• map_markers_plan.mdx
• map_checkpoints_plan.mdx
• map_race_pickups_plan.mdx

Function List

Function	Description	Scope
Map.GetAvailable	List discovered baked runtime maps known to this runtime.	S
Map.Load	Load a baked map into the runtime world.	S
Map.Unload	Unload a baked map from the runtime world.	S
Map.GetLoaded	List currently loaded maps.	S
Map.GetInfo	Read map metadata.	S
Map.BakeSmoke	Generate a minimal baked map package from primitive descriptors (dev/editor smoke path).	S

Events

Current script-facing lifecycle events:

• map:loaded
• map:unloaded

Map.Load

S Server Only

local ok, err = Map.Load(mapId)

Parameters:

• mapId (string)

Behavior:

• loads baked static world data
• instantiates baked map-owned nodes
• applies baked environment defaults through the environment system

Notes:

• Map.Load(mapId) operates on the baked runtime payload for a discovered map package
• if a resourceType = "map" package also ships client/server scripts, the recommended lifecycle owner is a Lua maploader resource:
  • Resource.Start(mapResourceName)
  • Map.Load(mapId)
  • later Map.Unload(mapId)
  • Resource.Stop(mapResourceName)
• that keeps map package scripts/assets scoped to the active map lifecycle

Returns:

• ok (boolean | nil)
• err (nil | string)

Map.Unload

S Server Only

local ok, err = Map.Unload(mapId)

Parameters:

• mapId (string)

Returns:

• ok (boolean | nil)
• err (nil | string)

Map.GetLoaded

S Shared

local maps, err = Map.GetLoaded()

Returns:

• maps (table | nil)
• err (nil | string)

Current returned map record includes at least:

• mapId
• name
• version
• resource
• loaded

Map.GetAvailable

S Shared

local maps, err = Map.GetAvailable()

Returns:

• maps (table | nil)
• err (nil | string)

Current returned map record includes at least:

• mapId
• name
• version
• resource
• loaded

Server notes:

• returns all discovered baked runtime maps from the authoritative map registry

Client/shared notes:

• returns baked maps currently known to the local mirrored map store
• this depends on resource transfer and local registry state, so it may be a subset of the server list until relevant map resources are present locally

Map.GetInfo

S Shared

local info, err = Map.GetInfo(mapId)

Returns:

• info (table | nil)
• err (nil | string)

Server-side current fields include:

• mapId
• name
• version
• author
• description
• environment
• resource

Client/shared current fields include:

• mapId
• name
• version
• resource
• assetPath
• headerFormatVersion
• loaded

Map.BakeSmoke

S Server Only (Experimental)

local ok, err = Map.BakeSmoke("editor_smoke_01", {
  name = "Editor Smoke 01",
  version = "0.1.0",
  primitives = {
    { kind = "cube", x = 0, y = -2, z = 0, sx = 64, sy = 2, sz = 64 },
    { kind = "sphere", x = 10, y = 2, z = 0, radius = 2 }
  }
})

Behavior:

• writes/updates a generated resourceType = "map" package under server resources
• regenerates map/map_collision.bin, map/map_render.json, and map/map.json preview/source data
• refreshes runtime resource/map registries for immediate Map.Load(...)

Notes:

• intended for editor/dev smoke loops, not final production bake tooling
• sphere primitives are approximated as box colliders in this smoke path

Relationship To Other APIs

• Environment remains the API for runtime environment overrides
• Node represents baked/static world objects and markers after load
• Vehicle represents dynamic deterministic vehicle entities

Packaging Direction

Runtime-playable maps should ship as resourceType = "map" resources.

A map resource may contain:

• baked runtime map payloads
• optional editable source payloads
• client scripts
• server scripts
• music and preview assets

Recommended split:

• baked runtime payload remains what Map.Load(...) operates on
• package lifecycle remains what Resource.Start(...) / Resource.Stop(...) operate on
• a Lua maploader resource can orchestrate both without moving map-specific policy into engine core

Recommended runtime-facing manifest fields for resourceType = "map" packages:

• name
• resourceType = "map"
• author
• version
• description