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...

34 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). NEO-44 landed (E5.M1 / combat path): combat defeat grants gig XP via CombatDefeatGigXpGrant + IPlayerGigProgressionStore — not E2.M2 skill XP; GET …/gig-progression (NEO-44, NEO-44 manual QA); server README — Gig progression (NEO-44). Epic 2 Slice 3 integration complete for documented payout paths (gather/craft activity, mission mission_reward, combat → gig XP on E5.M1). See epic_02 — E2.M2 + Slice 3. NEO-37, NEO-38, NEO-39, NEO-40, NEO-41, NEO-42, NEO-43, NEO-44, E2_M2; label E2.M2 on NEO-37–NEO-41, NEO-42–NEO-43
E3.M1 Ready 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). NEO-64 landed: comment-only resource_gathered / gather_node_depleted hook sites in GatherOperations.TryGather (NEO-64, NEO-64 manual QA); Epic 3 Slice 2 backlog E3M1-01–E3M1-08 complete. NEO-73 landed: client gather feedback — skill_progression_client.gd, prototype_interactable_picker.gd (nearest in-range R), GatherFeedbackLabel + SkillProgressionLabel, auto inventory/skill refresh after successful gather (NEO-73, NEO-73 manual QA); client/README.md gather section. NEO-75 landed: capstone gather→refine→make loop in Godot — NEO-75 manual QA, client/README.md end-to-end section; Epic 3 Slice 5 client complete. NEO-41 … NEO-64, NEO-73, NEO-75, E3S5-client-prototype-backlog, E3_M1; server/NeonSprawl.Server/Game/Gathering/, Game/Interaction/, client/scripts/skill_progression_client.gd, client/scripts/prototype_interactable_picker.gd
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-72 landed: client inventory HUD — inventory_client.gd, item_definitions_client.gd, InventoryLabel, boot hydrate + I refresh (NEO-72, NEO-72 manual QA); client/README.md inventory HUD section. NEO-75 landed: prototype_economy_hud_section.gd collapse toggle + capstone manual QA (NEO-75, NEO-75 manual QA); Epic 3 Slice 5 client complete. NEO-50, NEO-51, NEO-52, NEO-53, NEO-54, NEO-55, NEO-56, NEO-72, NEO-75, E3S5-client-prototype-backlog, E3M3-prototype-backlog, E3_M3
E3.M2 Ready NEO-65 landed: frozen prototype eight-recipe catalog in content/recipes/prototype_recipes.json; recipe-def.schema.json + recipe-io-row.schema.json; PR gate + validate_content.py Slice 3 gates (NEO-65). NEO-66 landed: fail-fast server load of content/recipes/*_recipes.json at startup — server/NeonSprawl.Server/Game/Crafting/ (NEO-66); server README — Recipe catalog. NEO-67 landed: injectable IRecipeDefinitionRegistry + lookup tests (NEO-67). NEO-68 landed: GET /game/world/recipe-definitions — RecipeDefinitionsWorldApi + DTOs in Game/Crafting/ (NEO-68, NEO-68 manual QA); server README — Recipe definitions (NEO-68); Bruno bruno/neon-sprawl-server/recipe-definitions/. NEO-69 landed: CraftOperations.TryCraft + CraftResult — pre-flight inputs/outputs, inventory mutation, refine XP (NEO-69); server README — Craft engine (NEO-69). NEO-70 landed: POST /game/players/{id}/craft — PlayerCraftApi + wire CraftResponse; Bruno gather→refine→make spine (NEO-70); Bruno bruno/neon-sprawl-server/craft/. NEO-71 landed: comment-only item_crafted / craft_failed telemetry hook sites in CraftOperations.TryCraft (NEO-71); server README — Craft telemetry hooks (NEO-71). NEO-42 landed (prep): RefineActivitySkillXpGrant / RefineSkillXpConstants — wired from craft engine success path. Epic 3 Slice 3 server backlog E3M2-01–E3M2-07 complete. Upstream: E3.M1 Ready, E3.M3 inventory landed. NEO-74 landed: client craft UI — recipe_definitions_client.gd, craft_client.gd, craft_recipe_panel.gd, CraftFeedbackLabel, refine skill row (NEO-74, NEO-74 manual QA); client/README.md craft section. NEO-75 landed: capstone playable gather→refine→make loop — NEO-75 manual QA, prototype_economy_hud_section.gd; Epic 3 Slice 5 client complete. NEO-42, NEO-65, NEO-66, NEO-67, NEO-68, NEO-69, NEO-70, NEO-71, NEO-74, NEO-75, E3M2-prototype-backlog, E3S5-client-prototype-backlog, E3_M2
E5.M1 Ready NEO-76 landed: frozen prototype four-ability catalog in content/abilities/prototype_abilities.json; ability-def.schema.json; PR gate + validate_content.py E5M1 four-id gate (NEO-76). NEO-77 landed: fail-fast server load of content/abilities/*_abilities.json at startup — server/NeonSprawl.Server/Game/Combat/ (NEO-77); server README — Ability catalog. NEO-79 landed: injectable IAbilityDefinitionRegistry + DI; hotbar/cast use TryNormalizeKnown (NEO-79); Bruno bruno/neon-sprawl-server/hotbar-loadout/ + ability-cast/ unknown-ability deny smokes. NEO-78 landed: GET /game/world/ability-definitions — AbilityDefinitionsWorldApi + DTOs in Game/Combat/ (NEO-78); server README — Ability definitions (NEO-78); Bruno bruno/neon-sprawl-server/ability-definitions/. NEO-80 landed: ICombatEntityHealthStore / InMemoryCombatEntityHealthStore — lazy prototype dummy HP at PrototypeCombatConstants.MaxPrototypeTargetHp (100); DI via AddCombatEntityHealthStore() (NEO-80); server README — Combat entity health (NEO-80). NEO-81 landed: CombatOperations.TryResolve + CombatResult + CombatReasonCodes — defeated pre-check deny, catalog damage (NEO-81); server README — Combat engine (NEO-81). NEO-82 landed: AbilityCastApi → CombatOperations.TryResolve; nested wire combatResolution on accept; per-ability catalog cooldown; target_defeated cast deny (NEO-82); server README — Ability cast (NEO-82); Bruno bruno/neon-sprawl-server/ability-cast/ defeat spine. NEO-83 landed: GET /game/world/combat-targets — CombatTargetsWorldApi + DTOs; authoritative HP snapshot from ICombatEntityHealthStore (NEO-83); server README — Combat targets snapshot (NEO-83); Bruno bruno/neon-sprawl-server/combat-targets/. NEO-44 landed: CombatDefeatGigXpGrant on cast targetDefeated — 25 gig XP to breach via IPlayerGigProgressionStore (V007); GET …/gig-progression (NEO-44, NEO-44 manual QA); server README — Gig progression (NEO-44); Bruno bruno/neon-sprawl-server/gig-progression/. NEO-84 landed: comment-only ability_used / enemy_defeat telemetry hook sites in CombatOperations.TryResolve; reserved encounter_start / player_death (NEO-84); server README — Combat telemetry hooks (NEO-84). NEO-85 landed: client combat HUD — ability_cast_client.gd parses combatResolution; combat_targets_client.gd, CastFeedbackLabel resolution copy, CombatTargetHpLabel; event-driven GET refresh (NEO-85, NEO-85 manual QA); client/README.md combat HUD section. NEO-86 landed: playable combat capstone — gig_progression_client.gd, GigXpLabel, defeat-triggered gig GET refresh; capstone manual QA NEO-86; client/README.md end-to-end combat loop section (NEO-86). Epic 5 Slice 1 client capstone complete. Backlog decomposed: Epic 5 Slice 1 — E5M1-01–E5M1-12 landed. Precursor landed: E1.M4 cast funnel (NEO-28/31/32). E5M1-prototype-backlog.md, E5_M1, NEO-77, NEO-79, NEO-78, NEO-80, NEO-81, NEO-82, NEO-83, NEO-44, NEO-84, NEO-85, NEO-86, E1M4-prototype-backlog.md
E5.M2 In Progress NEO-87 landed: frozen prototype three-behavior catalog in content/npc-behaviors/prototype_npc_behaviors.json; npc-behavior-def.schema.json; PR gate + validate_content.py E5M2 three-id gate (NEO-87). NEO-88 landed: fail-fast server load of content/npc-behaviors/*_npc_behaviors.json at startup — server/NeonSprawl.Server/Game/Npc/ (NEO-88); server README — NPC behavior catalog. NEO-89 landed: injectable INpcBehaviorDefinitionRegistry + DI; PrototypeNpcBehaviorRegistry id constants (NEO-89). NEO-90 landed: GET /game/world/npc-behavior-definitions — NpcBehaviorDefinitionsWorldApi + DTOs in Game/Npc/ (NEO-90); server README — NPC behavior definitions (NEO-90); Bruno bruno/neon-sprawl-server/npc-behavior-definitions/. Backlog decomposed: Epic 5 Slice 2 — E5M2-prototype-backlog.md E5M2-01 NEO-87 → E5M2-12 NEO-98; client capstone NEO-98. Three archetypes (prototype_melee_pressure, prototype_ranged_control, prototype_elite_mini_boss); replaces alpha/beta dummies with prototype_npc_melee / ranged / elite. Owns ThreatState, TelegraphEvent, GET …/npc-runtime-snapshot, session IPlayerCombatHealthStore. Upstream E5.M1 Ready. E5M2-prototype-backlog.md, E5_M2, NEO-87, NEO-88, NEO-89, NEO-90, label E5.M2 on NEO-87–NEO-98

Related docs