Skip to content

Items and Buffs Future Integration Plan

Use plain ascii in this document only.

Goal: Define a staged plan for adding item and buff systems to Rally so they can be integrated safely with KNAT driving controls and a future track world model.

Motivation: Rally currently has early item and buff model files, but no runtime world, spawn flow, pickup rules, lifetime processing, or protocol exposure. This plan captures the implementation path before execution starts.

Constraints:

  • Keep deterministic fixed-step simulation behavior.
  • Preserve current JSON over WebSocket protocol style.
  • Do not break existing driving node paths or semantics.
  • Item and buff logic must be optional and disabled by default in early phases.
  • Track assumptions remain forward-looking until track plan phases land.

Non-Goals:

  • Networked multiplayer inventory ownership conflict resolution.
  • Monetization, economy balancing, or progression systems.
  • Full UI inventory management in Godot or Unity.
  • Long term persistence of item state across sessions.

Current State

Audit of existing implementation and context.

Already Done:

  • knat_mvp/item.py defines an immutable Item dataclass.
  • knat_mvp/buffs.py sketches a Buff type and future placement idea.
  • Core simulation loop exists and is deterministic at 60 Hz.
  • KNAT protocol supports describe/subscribe/write/update_batch.
  • Phase I and II driving controls are complete and tested.

Gaps:

  • knat_mvp/buffs.py is not production-ready and needs cleanup/typing fixes.
  • No world registry for spawned items or active buffs.
  • No pickup/contact events linked to track position.
  • No buff duration countdown and expiration in the simulation loop.
  • No KNAT node paths yet for item state, pickup requests, or buff effects.

Proposed Approach

Implement items and buffs in four phases with explicit dependency on track representation. Begin with data contracts and runtime storage, then integrate track contact logic, then expose protocol nodes, then add client bridge hooks.

Track plan dependency:

  • Items and buffs require a stable track coordinate model and contact zones.
  • This plan can start with schema and storage before track execution.
  • Pickup/contact execution starts only after track Phase II baseline is merged.

Phases

I - Item and Buff Domain Model Hardening

Status: Unstarted (planning only)

Problem Current item and buff files are incomplete and not validated in runtime.

Approach Define canonical dataclasses and enums for item kind, buff category, duration, stacking rules, and scope. Keep runtime behavior disabled in this phase.

Deliverables

  • Refined Item and Buff models with clear field contracts.
  • Validation helpers for buff payloads and allowed modifiers.
  • Documentation table for supported buff keys and value ranges.

Tests

  • Unit tests for model creation, validation, and serialization shape.
  • Unit tests for invalid buff definitions and type mismatches.

Done When [ ] Item and Buff models are import-clean and validated. [ ] Invalid modifier payloads are rejected deterministically. [ ] Model tests pass without touching simulation behavior.

I.a

Define supported buff modifier surface for early use:

  • speed_multiplier
  • steering_sensitivity
  • brake_effectiveness
  • traction_assist

I.b

Define stacking policy per buff class:

  • replace
  • additive
  • strongest-wins

II - Runtime Registries and Lifecycle

Status: Unstarted (planning only)

Problem No runtime ownership exists for spawned items or active buff instances.

Approach Add deterministic registries for world items and active buffs in SimulationCore-adjacent state, with tick-based lifetime processing.

Deliverables

  • WorldItemRegistry with spawn/despawn APIs.
  • ActiveBuffRegistry with apply, refresh, expire operations.
  • Tick lifecycle integration for expiration and cleanup.

Tests

  • Unit tests for registry add/remove/query semantics.
  • Tick progression tests for expiration boundaries.
  • Determinism test comparing two runs with identical spawn schedule.

Done When [ ] Spawned items persist across ticks until consumed/expired. [ ] Active buffs expire exactly on scheduled ticks. [ ] Determinism checks are green.

III - Track Contact and Pickup Integration

Status: Unstarted (planning only)

Problem No spatial model links vehicle movement to item pickup opportunities.

Approach Integrate with track coordinate model from track plan. Evaluate contact zones using session distance and lateral offset against item spawn coordinates.

Deliverables

  • Contact evaluator function for item pickup checks.
  • Pickup event creation path with deterministic ordering.
  • Buff activation on pickup with stacking policy enforcement.

Tests

  • Contact tests for in-lane vs out-of-lane pickup boundaries.
  • Multi-item same-tick ordering tests.
  • Buff activation tests from pickup events.

Done When [ ] Vehicle can pick up item by crossing its contact zone. [ ] Pickup activates expected buff instance. [ ] Contact behavior remains deterministic per tick.

IV - Protocol and Client Bridge Exposure

Status: Unstarted (planning only)

Problem Clients cannot observe item state or buff effects via KNAT protocol.

Approach Expose minimal read/subscribe nodes for active buffs and optional write nodes for test spawning in non-production mode.

Deliverables

  • KNAT node paths for active buffs and recent pickup events.
  • Describe metadata for item and buff node schemas.
  • Godot bridge updates for buff_changed and pickup_event signals.

Tests

  • Protocol tests for describe and update_batch node visibility.
  • Integration tests for pickup event round trip.
  • Headless test that confirms a buff node update after pickup.

Done When [ ] Buff and pickup nodes appear in describe output. [ ] update_batch includes expected active buff values. [ ] Godot headless test verifies one pickup-to-buff flow.

Alternatives Considered (optional)

  • Implement pickups before track model: rejected due to fake spatial logic.
  • Add full inventory first: rejected because simulation effect path is primary.
  • Client-only buffs with no server authority: rejected for determinism reasons.

Decision Log

Date Decision Reason
2026-04-01 Plan items and buffs before implementation Align schema and dependencies first
2026-04-01 Defer pickup execution until track baseline exists Avoid unstable spatial contracts

Additional Context

  • Related file: knat_mvp/item.py
  • Related file: knat_mvp/buffs.py
  • Depends on future track coordinate contracts in track plan.

Additional Cross Project Requirements (optional)

Build Alignment

  • Keep pure Python implementation first.
  • Defer knat-abi binding updates until node paths stabilize.

Versioning

  • Use schema_hash change tracking through existing describe flow.

Documentation

  • Add a short items and buffs schema section to KNAT-DRIVER after Phase II.

Effort Summary and Progress

  • Unstarted [ ]
  • In Progress [-]
  • Deferred [+]
  • Complete [x]
=== Phase Effort Notes
[ ] I - Item and Buff Domain Model Hardening low schema and model cleanup
[ ] II - Runtime Registries and Lifecycle medium deterministic tick lifecycle
[ ] III - Track Contact and Pickup Integration medium depends on track baseline
[ ] IV - Protocol and Client Bridge Exposure medium protocol and client surfaces

Technical Debt

  • knat_mvp/buffs.py currently contains draft-only code and unresolved typing.
  • No canonical buff modifier list exists yet.
  • No deterministic pickup ordering policy has been codified.