Skip to main content

Map Race Pickups Plan

Status: planned only.

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

Why Pickups Are Separate​

Race pickups are not markers and not checkpoints.

They carry authoritative gameplay effects such as:

  • giving nitro
  • repairing the vehicle
  • changing the vehicle

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

Planned Pickup Types​

  • nitro
  • repair
  • vehicle_change

Additional gameplay pickup types can extend this family later.

Authority Split​

Server-authoritative:

  • pickup hit validation
  • vehicle/player eligibility
  • effect application
  • future respawn/cooldown behavior

Client-only:

  • pickup visual presentation
  • pulse/spin/billboard presentation
  • feedback after the authoritative effect has been applied

Planned Authored API​

Planned authored shape:

{
  "id": "pickup_01",
  "kind": "race_pickup",
  "pickupType": "nitro",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "scale": { "x": 3.0, "y": 3.0, "z": 3.0 },
  "visible": true,
  "collision": true,
  "render": true,
  "effect": {
    "amount": 1.0,
    "vehicleId": null
  },
  "visual": {
    "visualType": "corona",
    "color": { "r": 0.2, "g": 0.8, "b": 1.0, "a": 0.9 },
    "opacity": 1.0,
    "emission": 1.0,
    "pulse": true,
    "spinSpeed": 0.0
  }
}

Planned authored field meanings:

  • id: stable pickup id
  • kind: always race_pickup
  • pickupType: gameplay effect family
  • position: authored local position
  • scale: authored trigger/visual scale
  • visible: editor/runtime visibility intent
  • collision: whether the pickup participates in authoritative baked pickup/query data
  • render: whether a baked render descriptor should be emitted
  • effect: type-specific authoritative parameters
  • visual: presentation-only visual choice and parameters

Planned Baked Authoritative API​

Planned baked descriptor:

{
  "pickupId": "pickup_01",
  "pickupType": "nitro",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "size": { "x": 3.0, "y": 3.0, "z": 3.0 },
  "effect": {
    "amount": 1.0,
    "vehicleId": null
  },
  "enabled": true
}

Planned rules:

  • only authoritative baked descriptors drive effect application
  • client render state must not decide whether a pickup effect is granted
  • type-specific effect payloads should stay validated and minimal

Planned Baked Render API​

Planned render descriptor:

{
  "pickupId": "pickup_01",
  "visualType": "corona",
  "position": { "x": 0.0, "y": 2.0, "z": 0.0 },
  "scale": { "x": 3.0, "y": 3.0, "z": 3.0 },
  "color": { "r": 0.2, "g": 0.8, "b": 1.0, "a": 0.9 },
  "opacity": 1.0,
  "emission": 1.0,
  "pulse": true,
  "spinSpeed": 0.0
}

Planned Runtime Events​

Event direction after runtime pickup behavior is implemented:

  • map:race_pickup_hit
  • map:race_pickup_consumed
  • map:race_pickup_respawned

These events should come from authoritative gameplay logic.

Not Shipped Yet​

Not implemented as stable public API yet:

  • pickup authoring/runtime implementation
  • effect application contract
  • respawn/cooldown behavior
  • final event payloads
  • map_gameplay_plan.mdx