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/plans/internal-content-authoring.md

6.7 KiB
Raw Blame History

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 (Core Epic Map + Content tooling modules (CT) under System Modules).

Decomposition: Internal authoring (cross-cutting) — modules CT.M1–M3 (not numbered with core epics E1–E9).

Related: Tech stack — content pipeline, Contract kinds — Content, 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/ 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), ZoneDef / ZoneEdge / TravelRule (Epic 4 — World topology), QuestDef (Epic 7 — Quest / Faction), with detail in E4.M1 and E7.M1.
  • Stack: The tech stack 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) 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).

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).
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 (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/requirements-content.txt; see CT.M1 — ContentValidationPipeline.
  • 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).

Phase 3 — Depth (when simulation supports it)

  • Spawn / ecology authoring (E4.M2).
  • 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.