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