don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/decomposition/modules/documentation_and_implement...

21 KiB
Raw Blame History

Documentation and implementation alignment

The module dependency register Status column and each module’s summary table should not silently disagree with the repo. This doc defines how to keep decomposition docs truthful and where to record partial work.

Roles

Source Role
Register + module markdown Intent, dependencies, contracts, policies (authority, PvP, quests, ops).
Code + tests What actually runs; paths under server/, client/, etc.
Plans docs/plans/ (e.g. NEO-* implementation plans) tie stories to acceptance criteria.
Linear Issues under projects; module grouping = labels on the issue (no duplicate Feature tier). Decomposition README — Linear alignment.
This doc’s tracking table Quick inventory of modules that have started implementation; expand as work lands.

Status column (register)

Status Meaning
Planned No meaningful implementation toward this module yet, or only unrelated spikes.
In Progress At least one tracked story or code path exists toward the module; contracts may be partial.
Ready Exported contracts meet contracts.md “Ready” guidance and dependents may integrate.
Blocked Upstream module or external dependency prevents progress.

Rule: When a story merges that implements part of a module (API, store, schema), move that row from Planned to In Progress (or Ready when appropriate) in the same PR or a follow-up doc PR.

Partial modules stay In Progress until the prototype slice for that module is satisfied or contracts are explicitly frozen for dependents.

Per-module docs

Optional ## Implementation snapshot (or a short bullet under Summary) on a module page: one paragraph + links to docs/plans/…, server paths, and server README sections—avoid duplicating the full tracking table on every page.

The Summary table Status field should match the register row for that module.

Implementation tracking table

Rows appear when work starts; default for unlisted modules is Planned / not started.

Module Register status Snapshot Plans / pointers
E1.M1 Ready Prototype milestone Done (E1.M1). Authoritative PositionState + MoveCommand over HTTP (JSON v1 snap); in-memory store by default, Postgres when configured (NEO-8); shared NpgsqlDataSource disposed on host shutdown (NEO-13); Godot sync + path-follow (NEO-7, NEO-11); InteractionRequest + horizontal range (NEO-9). Follow-on: prediction/reconciliation, Slice 1 telemetry, Protobuf wire per contracts.md. NEO-6, NEO-7, NEO-8, NEO-9, NEO-10, NEO-11, NEO-13; server/NeonSprawl.Server/Game/PositionState/, Game/Interaction/; server README
E1.M2 Ready Slice 2 prototype slice closed: follow + CameraState (NEO-15); zoom bands (NEO-16); occlusion (NEO-17); occluder pick-through (NEO-20); contracts + hardening (NEO-18). Client-local; no server use of camera pose. NEO-15, NEO-16, NEO-17, NEO-18, NEO-20; client/scripts/isometric_follow_camera.gd, camera_state.gd, zoom_band_config.gd, occlusion_policy.gd, ground_pick.gd; E1_M2_IsometricCameraController.md
E1.M3 In Progress NEO-23 landed: JSON v1 targeting read + select (GET/POST …/target, Game/Targeting/, NEO-23) — PlayerTargetStateResponse / soft lock / reasonCode denials; wire name differs from illustrative TargetState in module doc (called out in plan + README). NEO-24 landed: client tab-target + lock HUD synced to server (NEO-24) — TargetSelectionClient (client/scripts/target_selection_client.gd), Tab / Esc bindings, TargetLockLabel HUD, hybrid movement-triggered refresh via new PositionAuthorityClient.authoritative_ack signal (fires on every server-confirmed position, boot + move-stream 200) with a 250 ms cooldown; manual QA in docs/manual-qa/NEO-24.md. NEO-25 landed: versioned GET /game/world/interactables (NEO-25) — InteractablesListResponse / InteractablesWorldApi in server/NeonSprawl.Server/Game/Interaction/; Godot interactables_catalog_client.gd + interactable_world_builder.gd (fetch-driven props + glow); server README — Interactable descriptors (NEO-25). NEO-26 landed: prototype SelectionEvent — TargetSelectionClient.selection_event (NEO-26) when lockedTargetId changes; optional log_selection_events. NEO-27 landed: Slice 3 telemetry hook sites documented — selection_event maps to product target_changed in target_selection_client.gd; server lock transition hook comments in InMemoryPlayerTargetLockStore; reserved ability_cast_requested / ability_cast_denied comments in client/scripts/main.gd (all TODO(E9.M1)); see NEO-27 and docs/manual-qa/NEO-27.md. Follow-on / still open: richer InteractableDescriptor consumers beyond list projection + existing POST …/interact; production telemetry ingest/catalog after E9.M1. Precursor (E1.M1): NEO-9 POST …/interact. Linear NEO-24–NEO-27; E1_M3_InteractionAndTargetingLayer.md; E1M3 prototype backlog; server README — Targeting, Interactable descriptors (NEO-25), Interaction
E1.M4 In Progress NEO-29 landed: prototype HotbarLoadout v1 server contract (GET/POST /game/players/{id}/hotbar-loadout) with stable deny reason codes, per-player scope, and persistence policy matching NEO-8/NS-17 (Postgres when configured, in-memory fallback otherwise). Client boot hydration is wired via hotbar_loadout_client.gd + hotbar_state.gd from main.gd; manual QA checklist created. NEO-31 landed: prototype POST /game/players/{id}/ability-cast, digit-key cast wiring from main.gd, ability_cast_client.gd, and hotbar_cast_slot_resolver.gd (target id from lockedTargetId in cached target state); GdUnit covers resolver + HTTP client; manual QA NEO-31. NEO-28 landed: cast POST validates lock + registry + range (invalid_target, out_of_range); AbilityCastClient.cast_result_received + CastFeedbackLabel HUD line; manual QA NEO-28. NEO-30 landed: Slice 3 cast funnel telemetry hook-site comments in AbilityCastApi.cs (ability_cast_requested on authoritative accept, ability_cast_denied + non-empty reasonCode on each JSON deny branch); client dev hooks unchanged; manual QA NEO-30; plan NEO-30. NEO-32 landed: GET /game/players/{id}/cooldown-snapshot + on_cooldown cast deny + prototype global cooldown commit; cooldown_snapshot_client.gd, cooldown_state.gd, CooldownSlotsLabel in main.gd; manual QA NEO-32; plan NEO-32. NEO-29, NEO-31, NEO-28, NEO-30, NEO-32; E1_M4_AbilityInputScaffold.md; E1M4 prototype backlog; server/NeonSprawl.Server/Game/AbilityInput/; client/scripts/hotbar_loadout_client.gd, client/scripts/hotbar_state.gd, client/scripts/ability_cast_client.gd, client/scripts/hotbar_cast_slot_resolver.gd, client/scripts/cooldown_snapshot_client.gd, client/scripts/cooldown_state.gd; server README — Hotbar loadout, Ability cast (NEO-31), Cooldown snapshot (NEO-32)
E2.M1 In Progress NEO-33 landed: frozen prototype trio salvage / refine / intrusion in content/skills/prototype_skills.json; PR gate + validate_content.py enforce schema, duplicate id, exact trio ids, and category coverage; designer note on allowedXpSourceKinds in E2_M1 + content/README.md. NEO-34 landed: fail-fast server load of content/skills/*.json at startup — server/NeonSprawl.Server/Game/Skills/ (NEO-34); config + discovery in server README — Skill catalog. NEO-35 landed: ISkillDefinitionRegistry / SkillDefinitionRegistry + DI (NEO-35). NEO-36 landed: versioned GET /game/world/skill-definitions (NEO-36) — SkillDefinitionsWorldApi + SkillDefinitionsListDtos in server/NeonSprawl.Server/Game/Skills/; Bruno bruno/neon-sprawl-server/skill-definitions/; manual QA NEO-36. E2.M2 consumer (NEO-38 landed): grant path validates skillId + sourceKind vs catalog allowedXpSourceKinds on POST …/skill-progression (NEO-38); see server README — Skill progression grant and E2_M2. NEO-33, NEO-34, NEO-35, NEO-36; E2_M1; module_dependency_register.md E2.M1 note; server/NeonSprawl.Server/Game/Skills/; docs/manual-qa/NEO-36.md; server README — Skill definitions (NEO-36)
E2.M3 In Progress NEO-45 landed: prototype salvage mastery catalog + CI gates (see NEO-45 plan). NEO-46 landed: fail-fast server load under server/NeonSprawl.Server/Game/Mastery/ — MasteryCatalogLoader, IMasteryCatalogRegistry, cross-check vs ISkillDefinitionRegistry, Slice 4 + tierIndex 1..N gate; see NEO-46 plan. NEO-47 landed: PerkUnlockEngine, IPlayerPerkStateStore + V004, level-up hook in skill XP grants; see NEO-47 plan. NEO-49 landed: comment-only perk_unlock telemetry hook site in PerkUnlockEngine.TryUnlockPerks (NEO-49 plan, NEO-49 manual QA); server README — Perk unlock telemetry (NEO-49). NEO-48 landed: GET/POST /game/players/{id}/perk-state — PerkStateApi + DTOs in Game/Mastery/ (NEO-48, NEO-48 manual QA); server README — Perk state (NEO-48); Bruno bruno/neon-sprawl-server/perk-state/. NEO-45, NEO-46, NEO-47, NEO-48, NEO-49, E2M3-pre-production-backlog, E2_M3
E2.M2 In Progress NEO-37 landed: versioned GET /game/players/{id}/skill-progression (NEO-37) — read model for every registered skill; known-player gate via IPositionStateStore; server README — Skill progression snapshot (NEO-37); manual QA NEO-37. NEO-38 landed: POST same path — grant apply, persistence (IPlayerSkillProgressionStore, V003 migration), structured denies + levelUps (NEO-38); manual QA NEO-38; Bruno bruno/neon-sprawl-server/skill-progression/; server README — Skill progression grant (NEO-38). NEO-39 landed: data-driven LevelCurve content + schema + CI validation (*_level_curve.json) with fail-fast startup schema checks; progression GET/POST level resolution now uses ISkillLevelCurve content-backed thresholds (NEO-39); manual QA NEO-39. NEO-40 landed: comment-only telemetry hook sites in SkillProgressionSnapshotApi.cs on POST …/skill-progression for future xp_grant / level_up (NEO-40, NEO-40 manual QA). NEO-41 landed: gather prototype — POST …/interact with kind: resource_node grants salvage + activity (10 XP) via SkillProgressionGrantOperations (NEO-41, NEO-41 manual QA); server README — Interaction. NEO-42 landed (prep): RefineActivitySkillXpGrant / RefineSkillXpConstants + deny-registry factory + tests — same NEO-38 grant stack; E3.M2 must invoke on craft/refine success (NEO-42, NEO-42 manual QA); server README — Craft / refine hook (NEO-42). NEO-43 landed (prep): MissionRewardSkillXpGrant / MissionRewardSkillXpConstants + deny-registry factory + tests — same NEO-38 grant stack with fixed sourceKind: mission_reward; E7.M2 must invoke from quest hand-in (NEO-43, NEO-43 manual QA); server README — Mission / quest reward (NEO-43). Slice 3 still open: NEO-44. See epic_02 — E2.M2 + Slice 3. NEO-37, NEO-38, NEO-39, NEO-40, NEO-41, NEO-42, NEO-43, E2_M2; label E2.M2 on NEO-37–NEO-41, NEO-42–NEO-44
E3.M1 In Progress NEO-41 landed (prototype, superseded on interact by NEO-63): inline XP on resource_node interact. NEO-57–NEO-61 — content, registry, HTTP defs, depletion store (see prior alignment). NEO-62 landed: GatherOperations + GatherResult. NEO-63 landed: POST …/interact resource_node → gather engine; four PrototypeInteractableRegistry anchors; Bruno gather → inventory + depletion deny (NEO-63, NEO-63 manual QA); server README — Gather via interact (NEO-63). Still planned: telemetry hooks (NEO-64). NEO-41 … NEO-63, E3_M1; server/NeonSprawl.Server/Game/Gathering/, Game/Interaction/
E3.M3 In Progress NEO-50 landed: frozen prototype six-item catalog in content/items/prototype_items.json; item-def.schema.json; PR gate + validate_content.py. NEO-51 landed: fail-fast server load of content/items/*_items.json at startup — server/NeonSprawl.Server/Game/Items/ (NEO-51); server README — Item catalog. NEO-52 landed: injectable IItemDefinitionRegistry + lookup tests (NEO-52). NEO-53 landed: GET /game/world/item-definitions — ItemDefinitionsWorldApi + DTOs in Game/Items/ (NEO-53, NEO-53 manual QA); server README — Item definitions (NEO-53); Bruno bruno/neon-sprawl-server/item-definitions/. NEO-54 landed: IPlayerInventoryStore + PlayerInventoryOperations — 24 bag + 1 equipment slots, stack rules, V005 migration (NEO-54). NEO-55 landed: GET/POST /game/players/{id}/inventory — PlayerInventoryApi + DTOs in Game/Items/ (NEO-55); server README — Player inventory (NEO-54 store, NEO-55 HTTP); Bruno bruno/neon-sprawl-server/inventory/. NEO-56 landed: comment-only item_created / inventory_transfer_denied telemetry hook sites in PlayerInventoryOperations (NEO-56, NEO-56 manual QA); no E9.M1 ingest. NEO-50, NEO-51, NEO-52, NEO-53, NEO-54, NEO-55, NEO-56, E3M3-prototype-backlog, E3_M3

Related docs