Skip to main content

Map Gameplay Plan

Status: planned only.

This document is not a shipped public Lua API contract yet.

Why this is still a plan​

The current public Map API documents:

  • package discovery
  • package lifecycle
  • baked map load/unload

But it does not yet document stable script-facing gameplay element contracts for:

  • markers
  • checkpoints
  • race pickups

Marker semantics are now locked enough to implement against. Checkpoint and race-pickup semantics are still in planning.

Planned runtime direction​

Authoring should distinguish:

  1. authored element kind
  2. visual shape
  3. trigger/query shape
  4. gameplay effect

This avoids overloading one field for both presentation and authoritative trigger logic.

Planned authored gameplay element kinds​

  • marker
  • checkpoint
  • race_pickup
  • spawn_point

These are in addition to static map object content.

Family-specific planning docs​

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

Current status by family:

  • marker
    • authored contract: locked
    • baked authoritative/render contract: locked
    • runtime event semantics: locked
    • implementation still in progress
  • checkpoint
    • still planned
  • race_pickup
    • still planned

Planned authority model​

Server-authoritative:

  • checkpoint progression
  • pickup effects
  • teleport/speed/nitro/repair behavior
  • any trigger that changes vehicle or race state

Client-only:

  • render presentation
  • decorative markers
  • visual response after the authoritative event has happened

Planned bake split​

map/map_collision.bin should contain all authoritative gameplay descriptors, not only static collision.

That includes:

  • trigger descriptors
  • checkpoints
  • race pickups
  • spawn points

map/map_render.json should contain render-only presentation data.

Planned runtime events​

Likely event direction after runtime behavior is implemented:

  • map:marker_hit
  • map:checkpoint_hit
  • map:race_pickup_hit

These should be emitted from authoritative runtime logic, not from purely client-local hit detection.

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