106 lines
6.7 KiB
Markdown
106 lines
6.7 KiB
Markdown
# 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)
|
||
|
||
<a id="phase-0-contracts-validation"></a>
|
||
|
||
### 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).
|
||
- **Done (partial):** `SkillDef` + `content/skills/*.json` — validated in **PR gate** via [`scripts/validate_content.py`](../../scripts/validate_content.py) + [`scripts/requirements-content.txt`](../../scripts/requirements-content.txt); see [CT.M1 — ContentValidationPipeline](../decomposition/modules/CT_M1_ContentValidationPipeline.md#ci-prototype).
|
||
- 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.
|