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/tooling/internal_authoring.md

7.5 KiB
Raw Blame History

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 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 — Core Epic Map and Content tooling modules (CT)).

Module IDs use the CT prefix (Content Tooling): CT.M1–M3. That keeps E1.M1-style IDs reserved for the core game epics.

Source anchors

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); 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 or tooling README.
  • Dependencies: Agreement on canonical schema path (contracts/schemas/content/ vs co-located); see 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.
  • Risk: Authors bypass validation locally and break main.
    • Mitigation: Required CI on content/**; pre-commit hook optional.
  • Risk: Internal studio exposed publicly.

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.