Skip to main content

Map Checkpoints Plan

Status: planned only.

This document defines the intended external API contract for checkpoints. It is not a shipped public Lua runtime contract yet.

Why Checkpoints Are Separate​

Checkpoints are not just marker visuals.

They carry authoritative gameplay semantics such as:

  • progression order
  • next checkpoint routing
  • goal/finish state
  • later lap/track logic

Because of that, checkpoints should stay a separate family from generic markers.

Authority Split​

Server-authoritative:

  • checkpoint progression
  • validation of the expected next checkpoint
  • finish/goal detection
  • future lap progression logic

Client-only:

  • checkpoint visual presentation
  • arrows/rings/coronas used to render checkpoints
  • UI feedback after authoritative progression events

Planned Authored API​

Planned authored shape:

{
  "id": "cp_01",
  "kind": "checkpoint",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "scale": { "x": 6.0, "y": 6.0, "z": 6.0 },
  "nextCheckpointId": "cp_02",
  "isGoal": false,
  "visible": true,
  "collision": true,
  "render": true,
  "visual": {
    "visualType": "arrow",
    "color": { "r": 1.0, "g": 0.4, "b": 0.1, "a": 0.9 },
    "opacity": 1.0,
    "emission": 1.0,
    "pulse": true,
    "spinSpeed": 0.0
  }
}

Planned authored field meanings:

  • id: stable checkpoint id
  • kind: always checkpoint
  • position: authored local position
  • scale: authored trigger/visual scale
  • nextCheckpointId: checkpoint routing target; omitted or null for the final checkpoint
  • isGoal: explicit finish marker
  • visible: editor/runtime visibility intent
  • collision: whether it participates in authoritative baked checkpoint/query data
  • render: whether a baked render descriptor should be emitted
  • visual: presentation-only visual choice and parameters

Planned Baked Authoritative API​

Planned baked descriptor:

{
  "checkpointId": "cp_01",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "size": { "x": 6.0, "y": 6.0, "z": 6.0 },
  "nextCheckpointId": "cp_02",
  "isGoal": false,
  "enabled": true
}

Planned rules:

  • authoritative checkpoint order/progression should be driven by these descriptors, not by client-local presentation state
  • checkpoint progression logic should validate the expected next checkpoint before advancing race state
  • baked checkpoint data belongs in authoritative baked runtime payloads alongside other trigger/query content

Planned Baked Render API​

Planned render descriptor:

{
  "checkpointId": "cp_01",
  "visualType": "arrow",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "scale": { "x": 6.0, "y": 6.0, "z": 6.0 },
  "color": { "r": 1.0, "g": 0.4, "b": 0.1, "a": 0.9 },
  "opacity": 1.0,
  "emission": 1.0,
  "pulse": true,
  "spinSpeed": 0.0
}

Planned render rules:

  • checkpoints may reuse marker-style visuals internally
  • that does not collapse checkpoints into the marker authored API
  • render data remains client presentation only

Planned Runtime Events​

Event direction after runtime checkpoint behavior is implemented:

  • map:checkpoint_hit
  • map:checkpoint_advanced
  • map:checkpoint_goal

These events should come from authoritative progression logic.

Not Shipped Yet​

Not implemented as stable public API yet:

  • checkpoint authoring/runtime implementation
  • progression validation contract
  • final event payloads
  • lap logic
  • map_gameplay_plan.mdx