101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
---
|
|
id: PLN-0001
|
|
ticket: world-editor-journey-spec
|
|
title: World Editor / Journey V1 Spec
|
|
status: done
|
|
created: 2026-06-19
|
|
decisions:
|
|
- DEC-0001
|
|
tags:
|
|
- spec
|
|
- world-editor
|
|
- journey
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Write the canonical English specification for the World Editor / Journey V1 contract accepted in DEC-0001. This plan produces documentation only. It does not implement Unity code.
|
|
|
|
## Source Decisions
|
|
|
|
- `DEC-0001`: World Editor / Journey V1.
|
|
|
|
## Target
|
|
|
|
Create or update the canonical spec location used by this repository with an English spec covering:
|
|
|
|
- `WorldLayoutSO` as editor authoring data.
|
|
- `JGraphSO` as runtime Journey data.
|
|
- `JStage`, `JEndpoint`, `JEndpointSocket`, `JEndpointAnchor`, `JEndpointLift`, and `JConnection`.
|
|
- World tile/layer defaults and configurability.
|
|
- Commit/publication boundary.
|
|
- Validation error and warning rules.
|
|
- V1 exclusions.
|
|
|
|
## Scope
|
|
|
|
- Inspect the repository for the canonical spec/docs location before editing.
|
|
- Add an English World Editor / Journey V1 spec if none exists.
|
|
- If a relevant spec already exists, update it instead of creating a parallel source of truth.
|
|
- Link the spec back to `DEC-0001`.
|
|
- Document that runtime Journey code lives outside `Assets/Scripts/Editor`.
|
|
- Document that Stage bake remains owned by the Stage Editor.
|
|
|
|
## Out Of Scope
|
|
|
|
- C# implementation.
|
|
- Unity Editor UI implementation.
|
|
- Stage Editor changes.
|
|
- Loading hints, concrete requirements, deep Stage marker sync, and editor unification.
|
|
|
|
## Execution Plan
|
|
|
|
1. Locate canonical docs/specs.
|
|
- Use `rg --files` to find existing `spec`, `docs`, or design contract files.
|
|
- Target the existing canonical location if present.
|
|
- If no canonical spec location exists, create a minimal `specs/` or repository-approved equivalent only after confirming repo convention from nearby files.
|
|
|
|
2. Draft the V1 spec.
|
|
- Add sections for authoring model, runtime model, endpoint model, connection model, commit flow, validation, and exclusions.
|
|
- Use normative language: `MUST`, `MUST NOT`, `SHALL`, `SHOULD`, and `MAY`.
|
|
- Keep the spec in English.
|
|
|
|
3. Define V1 data contracts in prose.
|
|
- `WorldLayoutSO`: default `worldTileSize = 24m`, default `worldLayerHeight = 24m`, stages, occupied tiles, authoring endpoints, and editor metadata.
|
|
- `JGraphSO`: `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, optional `contentHash`, `JStage[]`, `JEndpoint[]`, and `JConnection[]`.
|
|
- `JStage`: logical runtime stage record, not scene generation data.
|
|
|
|
4. Define validation levels.
|
|
- Errors block commit.
|
|
- Warnings do not block commit.
|
|
- Required endpoint without connection is an error.
|
|
- Optional endpoint without connection is a warning.
|
|
|
|
5. Document non-goals.
|
|
- No loading hints in V1.
|
|
- No concrete requirements in V1.
|
|
- No Stage scene generation from World Editor commit.
|
|
- No automatic World Editor to Stage Editor integration in V1.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- The spec is in English.
|
|
- The spec references `DEC-0001`.
|
|
- The spec names `WorldLayoutSO` and `JGraphSO`.
|
|
- The spec states that Journey elements use prefix `J`, and Journey ScriptableObjects use suffix `SO`.
|
|
- The spec states that World Editor commit publishes only logical Journey data.
|
|
- The spec states that runtime MUST consume `JGraphSO`, not `WorldLayoutSO` or `StageDefinition`.
|
|
|
|
## Validation
|
|
|
|
- Review the spec against every invariant in `DEC-0001`.
|
|
- Search the spec for residual Portuguese text before finalizing.
|
|
- Confirm no duplicate contradictory spec was created.
|
|
- No automated tests are required for this plan.
|
|
|
|
## Risks
|
|
|
|
- The repository may not yet have a canonical specs directory.
|
|
- If spec location is unclear, stop before creating a new documentation tree and ask for direction.
|
|
- Over-documenting future features could accidentally make them V1 commitments.
|