chore: add CT content-tooling track and vision plan tooling epic
- Add docs/decomposition/tooling/internal_authoring.md and CT.M1–M3 module stubs - Register CT modules and cross-cutting section in decomposition README - Add internal-content-authoring execution plan - Extend neon_sprawl_vision.plan.md with Tooling epic (CT) in Core Epic Map and modulespull/16/head
parent
2b0a050645
commit
107eda77d8
|
|
@ -8,18 +8,19 @@ This workspace contains detailed planning artifacts derived from the finalized m
|
|||
|
||||
## Folder Layout
|
||||
|
||||
- `epics/` - One file per epic with implementation slices.
|
||||
- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (all epic modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes.
|
||||
- `epics/` - One file per **player-facing** epic (E1–E9) with implementation slices.
|
||||
- `tooling/` - Cross-cutting **operator** tracks (e.g. content authoring) that are **not** numbered with the nine core epics; same slice style, separate **CT.\*** module IDs.
|
||||
- `modules/` - [Contract definitions](modules/contracts.md), [client vs server authority](modules/client_server_authority.md), [PvP × combat engine](modules/pvp_combat_integration.md), [quest scope × party](modules/quest_scope_and_party.md), [data reload × telemetry ops](modules/data_and_ops_policy.md), [docs vs implementation](modules/documentation_and_implementation_alignment.md), [full module dependency register](modules/module_dependency_register.md) (E1–E9 and CT modules), [per-module docs](modules/module_dependency_register.md#per-module-documentation), and interface notes.
|
||||
- `milestones/` - Phase-gated implementation tracks and pass/fail checklists.
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Do not rewrite baseline vision in these files; link back to the master plan.
|
||||
2. Keep slices backlog-ready (clear owner, dependencies, acceptance criteria).
|
||||
3. Use stable IDs (E1, E1.M1, P1.M1, etc.) to preserve traceability.
|
||||
3. Use stable IDs (`E1`, `E1.M1`, etc.) for core game epics; use **`CT.M1`**-style IDs for [content tooling](tooling/internal_authoring.md) so tooling stays out of the E1–E9 sequence.
|
||||
4. Every new slice must reference telemetry and validation where applicable.
|
||||
|
||||
## Epic Files
|
||||
## Epic files (E1–E9, master plan)
|
||||
|
||||
| Epic | Document |
|
||||
|------|----------|
|
||||
|
|
@ -35,6 +36,12 @@ This workspace contains detailed planning artifacts derived from the finalized m
|
|||
|
||||
Template for new epics or major revisions: [epics/_epic_template.md](epics/_epic_template.md)
|
||||
|
||||
## Cross-cutting tooling (not E1–E9)
|
||||
|
||||
| Track | Document | Modules (register) |
|
||||
|-------|----------|-------------------|
|
||||
| Internal authoring & content pipeline | [tooling/internal_authoring.md](tooling/internal_authoring.md) | **CT.M1–M3** |
|
||||
|
||||
## Next Actions
|
||||
|
||||
1. Expand slices into engineering tickets; keep module IDs aligned with the master plan.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
# CT.M1 — ContentValidationPipeline
|
||||
|
||||
## Summary
|
||||
|
||||
| Field | Value |
|
||||
|--------|--------|
|
||||
| **Module ID** | CT.M1 |
|
||||
| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) |
|
||||
| **Stage target** | Prototype |
|
||||
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |
|
||||
|
||||
## Purpose
|
||||
|
||||
Own **content schema artifacts**, **automated validation** in CI and locally, and (when wired) **server-side smoke loading** so file-backed catalogs cannot drift from enforced contracts.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Publish and version **JSON Schema** (or agreed equivalent) for catalogs consumed by **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1**.
|
||||
- Run **structural** and **cross-reference** validation before merge; expose the same rules to **CT.M2**.
|
||||
- Optional: **C#** deserialize test or boot check aligned with `ContentCatalogRegistry` (or successor).
|
||||
|
||||
## Key contracts
|
||||
|
||||
| Contract | Role |
|
||||
|----------|------|
|
||||
| Content schema files | `$id` + versioning per [contracts.md](contracts.md) |
|
||||
| Validation CLI | Stable exit codes and machine-readable errors for CI and studio |
|
||||
|
||||
## Module dependencies
|
||||
|
||||
- **Soft:** Gameplay modules above must define or stabilize the **shapes** being validated; pipeline can ship **minimal** schemas first.
|
||||
|
||||
## Dependents (by design)
|
||||
|
||||
- **CT.M2** — AuthoringStudioApplication
|
||||
- **CT.M3** — ContentReferenceAndBundleWorkflows
|
||||
|
||||
## Related implementation slices
|
||||
|
||||
Content tooling **Slice 1** — schemas + CI; **Slice 4** — server parity hardening.
|
||||
|
||||
## Source anchors
|
||||
|
||||
- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md)
|
||||
- [Module dependency register](module_dependency_register.md)
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# CT.M2 — AuthoringStudioApplication
|
||||
|
||||
## Summary
|
||||
|
||||
| Field | Value |
|
||||
|--------|--------|
|
||||
| **Module ID** | CT.M2 |
|
||||
| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) |
|
||||
| **Stage target** | Prototype |
|
||||
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |
|
||||
|
||||
## Purpose
|
||||
|
||||
Internal **authoring UI** (TypeScript-first per [tech stack](../../architecture/tech_stack.md)) for editing **`content/**`** with **validation parity** with CI and a practical **zone graph** authoring experience.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Browse and edit catalog files; **forms** and **pickers** for IDs (items, zones, quests) as catalogs exist.
|
||||
- **Topology:** Visual **graph** for **ZoneDef** / **ZoneEdge** / **TravelRule** aligned with **E4.M1**.
|
||||
- **Security:** Internal-only deployment; filesystem or local API access must not become part of the public game surface.
|
||||
|
||||
## Key contracts
|
||||
|
||||
| Contract | Role |
|
||||
|----------|------|
|
||||
| Studio ↔ repo | Read/write JSON (or YAML) under agreed roots; no separate authoring DB as source of truth |
|
||||
| Validator integration | Invokes **CT.M1** rules for inline feedback |
|
||||
|
||||
## Module dependencies
|
||||
|
||||
- **CT.M1** — ContentValidationPipeline
|
||||
|
||||
## Dependents (by design)
|
||||
|
||||
- **CT.M3** — optional integrated UX for reference index and bundles
|
||||
|
||||
## Related implementation slices
|
||||
|
||||
Content tooling **Slice 2** — studio core + topology editor.
|
||||
|
||||
## Source anchors
|
||||
|
||||
- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md)
|
||||
- [E4.M1 — ZoneGraphAndTravelRules](E4_M1_ZoneGraphAndTravelRules.md)
|
||||
- [Module dependency register](module_dependency_register.md)
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# CT.M3 — ContentReferenceAndBundleWorkflows
|
||||
|
||||
## Summary
|
||||
|
||||
| Field | Value |
|
||||
|--------|--------|
|
||||
| **Module ID** | CT.M3 |
|
||||
| **Track** | [Content tooling — internal authoring](../tooling/internal_authoring.md) (cross-cutting; not E1–E9) |
|
||||
| **Stage target** | Pre-production |
|
||||
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |
|
||||
|
||||
## Purpose
|
||||
|
||||
**Workflow depth** after the MVP studio: project-wide **reference graph**, safer **renames**, **schema version** warnings across files, and optional **content bundle** manifests to reduce client/server drift.
|
||||
|
||||
## Responsibilities
|
||||
|
||||
- Build an index of IDs and references across `content/**` for find-usages and rename planning.
|
||||
- Emit optional **hash/version manifest** for CI and deploy pipelines (aligns with tech stack bundle note).
|
||||
- Document operational practices (PR review for content, bundle promotion).
|
||||
|
||||
## Key contracts
|
||||
|
||||
| Contract | Role |
|
||||
|----------|------|
|
||||
| `ContentBundleManifest` (optional) | Lists files, schema versions, content hashes |
|
||||
| Reference report | Machine-readable graph for CI or review tools |
|
||||
|
||||
## Module dependencies
|
||||
|
||||
- **CT.M1** — ContentValidationPipeline
|
||||
- **CT.M2** — AuthoringStudioApplication (recommended for integrated UX)
|
||||
|
||||
## Dependents (by design)
|
||||
|
||||
- None within the CT track; ops/deploy may consume manifests.
|
||||
|
||||
## Related implementation slices
|
||||
|
||||
Content tooling **Slice 3** — reference index and optional bundles.
|
||||
|
||||
## Source anchors
|
||||
|
||||
- Plan: [`internal-content-authoring.md`](../../plans/internal-content-authoring.md)
|
||||
- [Module dependency register](module_dependency_register.md)
|
||||
|
|
@ -104,6 +104,18 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl
|
|||
| E9.M3 | LiveBalanceControlPlane | E9.M2, E5.M1, E2.M4, E3.M5 | BalancePatch, ConfigVersion, RolloutState | Production | Planned |
|
||||
| E9.M4 | IntegrityAndAbuseResponse | E9.M1 | IntegritySignal, IncidentTicket, EnforcementAction | Pre-production | Planned |
|
||||
|
||||
### Cross-cutting — Content tooling (not E1–E9)
|
||||
|
||||
Operator-facing authoring infrastructure; module IDs use the **CT** prefix. Program doc: [`tooling/internal_authoring.md`](../tooling/internal_authoring.md).
|
||||
|
||||
| Module ID | Module Name | Depends On | Contract Needed | Phase Required | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| CT.M1 | ContentValidationPipeline | Soft: E2.M1, E3.M2–M3, E4.M1, E7.M1 (shape alignment) | JSON Schema bundle, validation CLI, error schema | Prototype | Planned |
|
||||
| CT.M2 | AuthoringStudioApplication | CT.M1 | Studio project layout, optional local content API | Prototype | Planned |
|
||||
| CT.M3 | ContentReferenceAndBundleWorkflows | CT.M1; CT.M2 (recommended) | ContentBundleManifest (optional), reference graph | Pre-production | Planned |
|
||||
|
||||
**CT.\*** modules consume **gameplay content** contracts from E1–E9; they do not replace **E7** runtime quest semantics or **E4** server travel evaluation.
|
||||
|
||||
## Per-module documentation
|
||||
|
||||
| Module ID | Document |
|
||||
|
|
@ -145,6 +157,9 @@ Gameplay **content and curves** default to **boot load** with optional **dev-onl
|
|||
| E9.M2 | [E9_M2_KpiDashboardsAndAlerting.md](E9_M2_KpiDashboardsAndAlerting.md) |
|
||||
| E9.M3 | [E9_M3_LiveBalanceControlPlane.md](E9_M3_LiveBalanceControlPlane.md) |
|
||||
| E9.M4 | [E9_M4_IntegrityAndAbuseResponse.md](E9_M4_IntegrityAndAbuseResponse.md) |
|
||||
| CT.M1 | [CT_M1_ContentValidationPipeline.md](CT_M1_ContentValidationPipeline.md) |
|
||||
| CT.M2 | [CT_M2_AuthoringStudioApplication.md](CT_M2_AuthoringStudioApplication.md) |
|
||||
| CT.M3 | [CT_M3_ContentReferenceAndBundleWorkflows.md](CT_M3_ContentReferenceAndBundleWorkflows.md) |
|
||||
|
||||
## Status Legend
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,99 @@
|
|||
# Internal authoring and content tooling (cross-cutting)
|
||||
|
||||
This document is the **program epic** for operator-facing authoring infrastructure. It sits **alongside** the [nine player-facing epics](../README.md) from the master plan (E1–E9): same decomposition style (modules, slices, acceptance criteria), but **not** a tenth numbered player epic. It is captured in the vision plan as the **Tooling epic — Internal authoring and content pipeline (CT)** ([`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map and **Content tooling modules (CT)**).
|
||||
|
||||
**Module IDs** use the **CT** prefix (**C**ontent **T**ooling): **CT.M1–M3**. That keeps E1.M1-style IDs reserved for the core game epics.
|
||||
|
||||
## Source anchors
|
||||
|
||||
- **Execution plan (phasing detail):** [`docs/plans/internal-content-authoring.md`](../../plans/internal-content-authoring.md)
|
||||
- Master plan — **tooling epic + CT modules:** [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) (Core Epic Map; System Modules — Content tooling **CT**)
|
||||
- Master plan — product/content assumptions: data-driven catalogs; TS/JS for tooling per [tech stack](../../architecture/tech_stack.md)
|
||||
- **Contracts:** [`docs/decomposition/modules/contracts.md`](../modules/contracts.md)
|
||||
- Related modules: **CT.M1**, **CT.M2**, **CT.M3**. **Consumes** gameplay content contract *shapes* from **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1** (schemas and loaders must stay aligned as those modules evolve).
|
||||
|
||||
## Ownership and success (Level 1)
|
||||
|
||||
- **Ownership focus:** Content Engineering + Tools + Build/CI
|
||||
- **Success criteria:** Solo or small team can author **zones**, **items**, **recipes**, and **quests** quickly, with **CI and local validation** preventing broken references before merge; **no** shadow databases as source of truth.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver an **internal authoring stack**—schemas, validators, optional authoring UI, and workflow helpers—so bulk game data stays **file-backed**, **versioned**, and **consistent** with the authoritative server and with decomposition contracts. This track complements **Epic 3–4–7** (data *consumption* in the live game) by owning the **pipeline** that produces and checks that data.
|
||||
|
||||
## Module breakdown
|
||||
|
||||
### CT.M1 - ContentValidationPipeline
|
||||
|
||||
- **Responsibility:** Canonical JSON (or YAML) Schemas for content catalogs; **CI** and **local** validation (syntax + cross-table rules); optional **server boot** or **test** smoke load that deserializes catalogs.
|
||||
- **Key contracts:** Schema documents (`$id` + version folders per [`contracts.md`](../modules/contracts.md)); validation CLI; error format consumed by studio.
|
||||
- **Dependencies:** Stable enough shapes from **E2/E3/E4/E7** content contracts (can start minimal and extend).
|
||||
- **Stage target:** Prototype
|
||||
|
||||
### CT.M2 - AuthoringStudioApplication
|
||||
|
||||
- **Responsibility:** Internal **TypeScript** application (e.g. Vite + React) for browsing `content/`, editing catalogs with **forms** and **ID pickers**, and running the same validation as CI; **zone graph** visualization and editing for **E4.M1**-shaped payloads.
|
||||
- **Key contracts:** Read/write paths to repo `content/**`; optional tiny local HTTP API for filesystem access in browser dev mode.
|
||||
- **Dependencies:** **CT.M1** (validator behavior and schema versions).
|
||||
- **Stage target:** Prototype
|
||||
|
||||
### CT.M3 - ContentReferenceAndBundleWorkflows
|
||||
|
||||
- **Responsibility:** Project-wide **reference index** (find references, safer **rename** suggestions); warnings for **mixed schema versions** in one bundle; optional **content bundle manifest** + hash for client/server drift control (aligns with tech stack “bundles” note).
|
||||
- **Key contracts:** `ContentBundleManifest` (optional); reference graph export for CI or review.
|
||||
- **Dependencies:** **CT.M1**; **CT.M2** recommended for UX.
|
||||
- **Stage target:** Pre-production
|
||||
|
||||
## Implementation slices (backlog-ready)
|
||||
|
||||
### Slice 1 - Schemas and CI validation (MVP pipeline)
|
||||
|
||||
- **Scope:** **CT.M1** — publish schemas for skills, items, recipes, quests, and zone graph; wire **PR CI** so invalid content cannot merge; document validate commands in [`content/README.md`](../../../content/README.md) or tooling README.
|
||||
- **Dependencies:** Agreement on canonical schema path (`contracts/schemas/content/` vs co-located); see [`internal-content-authoring.md`](../../plans/internal-content-authoring.md).
|
||||
- **Acceptance criteria:**
|
||||
- Every `content/**/*.json` (or agreed glob) is validated on PR.
|
||||
- Cross-table rules catch at least: missing **item** IDs on recipes, missing **zone** IDs on edges, missing **quest** IDs on travel rules where applicable.
|
||||
- **Telemetry / signals:** CI job success/failure; optional `content_validation_failed` counter in ingest (internal) — **not** required for player telemetry.
|
||||
|
||||
### Slice 2 - Authoring studio core + topology editor
|
||||
|
||||
- **Scope:** **CT.M2** — file tree, JSON editing with validation feedback, **zone graph** editor (nodes/edges/`TravelRule` forms), save back to repo files.
|
||||
- **Dependencies:** **CT.M1** stable for catalog types in use.
|
||||
- **Acceptance criteria:**
|
||||
- Author can add a **zone**, **edge**, and **recipe** in one session without hand-editing invalid JSON (validator passes on save or shows blocking errors).
|
||||
- Internal runbook documents **localhost/VPN** usage; no exposure on public game API.
|
||||
- **Telemetry / signals:** None required; optional anonymous local usage metrics off by default.
|
||||
|
||||
### Slice 3 - Reference index and optional bundles
|
||||
|
||||
- **Scope:** **CT.M3** — find references / rename helpers; optional bundle manifest for staging/prod artifact parity.
|
||||
- **Dependencies:** **CT.M1**, **CT.M2** (for integrated UX).
|
||||
- **Acceptance criteria:**
|
||||
- Renaming an **item** ID surfaces all JSON references before apply.
|
||||
- If bundles are in scope: manifest lists file hashes and schema versions; documented in ops runbook.
|
||||
- **Telemetry / signals:** CI validates manifest integrity on build.
|
||||
|
||||
### Slice 4 - Server/content parity hardening (optional gate)
|
||||
|
||||
- **Scope:** **CT.M1** extension — `dotnet test` or startup path proves **ContentCatalogRegistry** (or equivalent) loads all files the server expects; fails CI when C# models drift from schema.
|
||||
- **Dependencies:** Server project owns loader types; coordinate with **E3.M3 / E7.M1** implementation timing.
|
||||
- **Acceptance criteria:**
|
||||
- One **test** or **host build step** fails if any catalog file is rejected by the server deserializer.
|
||||
- **Telemetry / signals:** CI only.
|
||||
|
||||
**Scope note (Epic 7):** Epic 7 already lists “Tools” under ownership for narrative/quest work; this **CT** track owns **shared** authoring infrastructure (schemas, CI, studio shell). Quest-specific UX can land in **CT.M2** slices while **E7.M1** owns runtime `QuestDef` semantics.
|
||||
|
||||
## Risks and mitigations
|
||||
|
||||
- **Risk:** Tooling drifts from server deserialization.
|
||||
- **Mitigation:** Slice 4 parity test; single schema source of truth; align with [`contracts.md`](../modules/contracts.md).
|
||||
- **Risk:** Authors bypass validation locally and break `main`.
|
||||
- **Mitigation:** Required CI on `content/**`; pre-commit hook optional.
|
||||
- **Risk:** Internal studio exposed publicly.
|
||||
- **Mitigation:** Separate host/port, auth per [tech stack — security](../../architecture/tech_stack.md); VPN/local default.
|
||||
|
||||
## Definition of done
|
||||
|
||||
- **Prototype:** **CT.M1** + **CT.M2** slices 1–2 complete; designers can author core catalogs and zone graphs with CI enforcement.
|
||||
- **Pre-production:** **CT.M3** reference workflows; optional bundles documented.
|
||||
- Player-facing epics **3 / 4 / 7** remain the authority for **what** data means at runtime; this track is done when **changing** that data is safe, fast, and traceable in git.
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
# Internal world and content authoring (plan)
|
||||
|
||||
**Status:** Planning only — not an implementation backlog ticket. Use this doc to decide scope, phasing, and ownership before building tooling.
|
||||
|
||||
**Vision plan:** **Tooling epic — Internal authoring and content pipeline (CT)** in [`neon_sprawl_vision.plan.md](../../neon_sprawl_vision.plan.md) (Core Epic Map + **Content tooling modules (CT)** under System Modules).
|
||||
|
||||
**Decomposition:** [Internal authoring (cross-cutting)](../decomposition/tooling/internal_authoring.md) — modules **CT.M1–M3** (not numbered with core epics E1–E9).
|
||||
|
||||
**Related:** [Tech stack — content pipeline](../architecture/tech_stack.md), [Contract kinds — Content](../decomposition/modules/contracts.md), [content/README.md](../../content/README.md).
|
||||
|
||||
---
|
||||
|
||||
## Why this exists
|
||||
|
||||
Neon Sprawl is **data-driven** for skills, items, recipes, quests, and (eventually) world topology. An **internal authoring stack** reduces friction for world designers and content authors: valid IDs, consistent JSON, and a fast loop from edit → CI → server/client consumption — without giving the game client authority over definitions.
|
||||
|
||||
---
|
||||
|
||||
## Context in the repo (today)
|
||||
|
||||
- **Content:** [`content/`](../../content/) holds catalogs; skills exist today with a co-located schema under `content/schemas/`. Items, recipes, quests, and zone graphs will follow the same pattern as those modules land.
|
||||
- **Decomposition:** Shapes are named in epics and modules — e.g. `ItemDef` / `RecipeDef` ([Epic 3 — Crafting](../decomposition/epics/epic_03_crafting_economy.md)), `ZoneDef` / `ZoneEdge` / `TravelRule` ([Epic 4 — World topology](../decomposition/epics/epic_04_world_topology.md)), `QuestDef` ([Epic 7 — Quest / Faction](../decomposition/epics/epic_07_quest_faction.md)), with detail in [E4.M1](../decomposition/modules/E4_M1_ZoneGraphAndTravelRules.md) and [E7.M1](../decomposition/modules/E7_M1_QuestStateMachine.md).
|
||||
- **Stack:** The [tech stack](../architecture/tech_stack.md) locks **authoritative** simulation to **C#** and allows **TypeScript/JavaScript** for **content tooling** (validators, internal UIs, one-off scripts).
|
||||
|
||||
---
|
||||
|
||||
## Goals (v1 of the tooling program)
|
||||
|
||||
1. **Single source of truth:** Definitions live in **versioned files** in git (JSON/YAML), not a private database, unless a later phase adds an explicit export from a temp store.
|
||||
2. **Fast iteration:** Authors get **inline validation**, **ID pickers** (items, zones, quests), and clear errors before merge.
|
||||
3. **Topology:** Support **zone graph** authoring (nodes, edges, travel rules) aligned with **E4.M1**; treat seamless region handoff ([E4.M3](../decomposition/modules/E4_M3_SeamlessHandoffAndRegionState.md)) as a later editor concern once the sim consumes it.
|
||||
4. **Safety:** Internal-only use; any HTTP surface for the tool stays **separate** from the public game API and uses **proportionate auth** per phase ([tech stack — security](../architecture/tech_stack.md)).
|
||||
|
||||
---
|
||||
|
||||
## Non-goals (first release)
|
||||
|
||||
- Replacing Godot (or a DCC) for **full 3D world sculpting** — optional **import/preview** later.
|
||||
- **Client-authoritative** definitions — the tool **authors data**; the **server** remains authoritative at runtime.
|
||||
|
||||
---
|
||||
|
||||
## Target architecture (high level)
|
||||
|
||||
| Piece | Role |
|
||||
|--------|------|
|
||||
| **Content files + JSON Schema** | Canonical definitions; validate in **CI** and locally ([contracts — Content kind](../decomposition/modules/contracts.md)). |
|
||||
| **Validator** | Same rules in CI and in the editor: schema compliance + **cross-table checks** (e.g. recipe inputs reference real `ItemDef` IDs). |
|
||||
| **Authoring UI** | Small **TypeScript** app (e.g. Vite + React) or desktop shell (Tauri/Electron) for filesystem-backed projects — decision at kickoff. |
|
||||
| **Server** | Loads the same files at boot (and optional **smoke tests** that deserialize all catalogs). |
|
||||
| **Godot (optional)** | Read-only debug preview of district/zone data — not required for MVP. |
|
||||
|
||||
---
|
||||
|
||||
## Phased roadmap (suggested)
|
||||
|
||||
### Phase 0 — Contracts and validation spine
|
||||
|
||||
- Publish minimal **JSON Schemas** for `ItemDef`, `RecipeDef`, `QuestDef`, and zone graph payloads; align **one** canonical schema location with [contracts.md](../decomposition/modules/contracts.md) (`contracts/schemas/content/` vs co-located — pick once).
|
||||
- Wire **CI** so `content/**/*.json` cannot merge invalid (Node `ajv` / CLI or `dotnet` validator).
|
||||
- Optional: **dotnet** test that **loads** all content (catches deserialization drift).
|
||||
|
||||
### Phase 1 — “Content Studio” MVP
|
||||
|
||||
- **File-backed** project: browse `content/`, edit with **forms** guided by schema (hand-built or generated).
|
||||
- **Topology:** Visual **graph** for zones + edges + `TravelRule` forms; export to the agreed JSON shape.
|
||||
- **Economy / quests:** Tables or forms for items, recipes, quest steps with **pickers** for IDs.
|
||||
- **Ergonomics:** `npm run validate`, optional watch mode, pre-commit hook if desired.
|
||||
|
||||
### Phase 2 — Workflow polish
|
||||
|
||||
- **Reference index** for find-references and safer renames across files.
|
||||
- **Schema versioning** policy per contracts doc; warn on mixed versions in one bundle.
|
||||
- **Optional bundles:** Hash-versioned content blobs for client/server drift control ([tech stack](../architecture/tech_stack.md)).
|
||||
|
||||
### Phase 3 — Depth (when simulation supports it)
|
||||
|
||||
- Spawn / ecology authoring ([E4.M2](../decomposition/modules/E4_M2_SpawnEcologyController.md)).
|
||||
- Spatial helpers (Godot marker export, CSV import, 2D overlays if `ZoneDef` gains coordinates).
|
||||
- Documented flows for applying bulk content updates to **staging** DBs while **git** remains truth.
|
||||
|
||||
---
|
||||
|
||||
## Open decisions (before implementation)
|
||||
|
||||
- **UI shell:** Browser + local API vs Tauri/Electron for native “open folder.”
|
||||
- **Authoring format default:** JSON vs YAML for hand editing.
|
||||
- **Zone graph storage:** One graph file per district vs split `zones` / `edges` files — trade merge conflicts vs navigation.
|
||||
|
||||
---
|
||||
|
||||
## Success metrics (when you implement)
|
||||
|
||||
- Adding **item + recipe + quest** that ties them together takes **minutes**, with **zero** validation surprises on `main`.
|
||||
- Zone graph edits do not introduce **illegal transitions** in playtests relative to server **TravelRule** evaluation.
|
||||
|
||||
---
|
||||
|
||||
## Security and operations
|
||||
|
||||
- Run the tool on **VPN/localhost** until hardening is explicit.
|
||||
- **Audit trail:** prefer **git history**; use PR review for `content/` if the team grows.
|
||||
|
|
@ -346,6 +346,14 @@ Transform the validated prototype into a scalable production-ready development m
|
|||
- **Scope:** Metrics pipeline, tuning controls, event tooling, anti-cheat/anti-bot workflows, incident runbooks.
|
||||
- **Success criteria:** Team can operate, balance, and protect the game continuously post-launch with fast feedback loops.
|
||||
|
||||
### Tooling epic — Internal authoring and content pipeline (CT)
|
||||
|
||||
**Type:** Operator- and build-focused **tooling epic**, parallel to the numbered **E1–E9** player/product epics above. It does **not** extend the sequence to “Epic 10”; modules use the **`CT.M#`** prefix. Full program doc (slices, risks, DoD): [`docs/decomposition/tooling/internal_authoring.md`](docs/decomposition/tooling/internal_authoring.md).
|
||||
|
||||
- **Ownership focus:** Content Engineering + Tools + Build/CI
|
||||
- **Scope:** JSON (or YAML) schemas for catalogs, **CI and local validation** (including cross-table reference checks), optional **internal authoring UI** (TypeScript-friendly per tech stack), reference/rename workflows, optional content bundles; consumes contract *shapes* from **E2 / E3 / E4 / E7** as those stabilize.
|
||||
- **Success criteria:** Zones, items, recipes, and quests can be authored as **file-backed, versioned** data with merge gates that prevent broken references; no separate authoring database as source of truth.
|
||||
|
||||
## System Modules by Epic (Level 2)
|
||||
|
||||
Module template:
|
||||
|
|
@ -566,6 +574,26 @@ Module template:
|
|||
- Dependencies: E9.M1.
|
||||
- Stage target: Pre-production.
|
||||
|
||||
### Content tooling modules (CT) — Internal authoring
|
||||
|
||||
**Tooling track** (not E1–E9). Depends **softly** on catalog shapes from **E2.M1**, **E3.M2–M3**, **E4.M1**, **E7.M1**; see [`docs/decomposition/tooling/internal_authoring.md`](docs/decomposition/tooling/internal_authoring.md).
|
||||
|
||||
- **CT.M1 ContentValidationPipeline**
|
||||
- Responsibility: Canonical schemas for content files; CI and local validation; optional server/test smoke load of catalogs.
|
||||
- Key contracts: JSON Schema bundle, validation CLI, stable error format for editors.
|
||||
- Dependencies: Soft alignment with E2/E3/E4/E7 content contracts; can start with minimal schemas.
|
||||
- Stage target: Prototype.
|
||||
- **CT.M2 AuthoringStudioApplication**
|
||||
- Responsibility: Internal authoring app (e.g. Vite + React) for `content/**`, forms and ID pickers, zone graph editing aligned with **E4.M1** payloads.
|
||||
- Key contracts: Repo read/write paths; optional local API for dev browser; invokes **CT.M1** rules.
|
||||
- Dependencies: CT.M1.
|
||||
- Stage target: Prototype.
|
||||
- **CT.M3 ContentReferenceAndBundleWorkflows**
|
||||
- Responsibility: Project-wide reference index, safer renames, schema-version warnings; optional bundle manifest for client/server parity.
|
||||
- Key contracts: `ContentBundleManifest` (optional), reference graph for CI/review.
|
||||
- Dependencies: CT.M1; CT.M2 recommended for integrated UX.
|
||||
- Stage target: Pre-production.
|
||||
|
||||
## Module Dependency Flow (Level 2)
|
||||
|
||||
```mermaid
|
||||
|
|
|
|||
Loading…
Reference in New Issue