119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
---
|
|
id: PLN-0004
|
|
ticket: world-editor-journey-spec
|
|
title: Journey Commit and Validation
|
|
status: review
|
|
created: 2026-06-19
|
|
decisions:
|
|
- DEC-0001
|
|
tags:
|
|
- editor
|
|
- validation
|
|
- journey
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Implement the explicit World Editor commit action that validates `WorldLayoutSO` and publishes only logical Journey data into `JGraphSO`.
|
|
|
|
## Source Decisions
|
|
|
|
- `DEC-0001`: World Editor / Journey V1.
|
|
|
|
## Target
|
|
|
|
Create the publication pipeline from `WorldLayoutSO` to `JGraphSO`:
|
|
|
|
- validation service,
|
|
- error/warning reporting,
|
|
- commit button behavior,
|
|
- deterministic conversion to runtime logical Journey data,
|
|
- publication metadata.
|
|
|
|
## Scope
|
|
|
|
- Editor-only validation and commit code.
|
|
- Conversion from World Editor authoring records to runtime `JGraphSO`.
|
|
- Generate/update `JStage`, `JEndpoint`, and `JConnection` records.
|
|
- Preserve stable ids across repeated commits.
|
|
- Block commit on errors.
|
|
- Allow commit with warnings.
|
|
|
|
## Out Of Scope
|
|
|
|
- Stage scene generation.
|
|
- Stage bake.
|
|
- Loading hints.
|
|
- Concrete requirements.
|
|
- Runtime traversal behavior.
|
|
- Automatic Stage Editor sync.
|
|
- Unified editor shell.
|
|
|
|
## Execution Plan
|
|
|
|
1. Add validation types.
|
|
- Target `Assets/Scripts/Editor/GON/WorldEditor`.
|
|
- Create severity enum: error and warning.
|
|
- Create validation message record with severity, message, and optional authoring object id.
|
|
|
|
2. Add `WorldLayoutValidator`.
|
|
- Validate same-layer tile overlap.
|
|
- Validate connection endpoints exist.
|
|
- Validate connection does not connect an endpoint to itself.
|
|
- Validate endpoint type compatibility.
|
|
- Validate socket cardinality: at most one connection.
|
|
- Validate socket face is a free Stage tile face.
|
|
- Validate sockets connect opposite faces on adjacent tiles when physically connected.
|
|
- Validate anchor/lift cannot coexist on same WorldTile.
|
|
- Validate lift alignment by x/y and differing layer.
|
|
- Validate lift cardinality: exactly one connection when required, at most one connection in all cases.
|
|
- Validate required endpoint without connection as error.
|
|
- Validate optional endpoint without connection as warning.
|
|
|
|
3. Add `JourneyCommitter`.
|
|
- Input: `WorldLayoutSO` and target `JGraphSO`.
|
|
- Run validation before writing.
|
|
- If errors exist, abort without modifying `JGraphSO`.
|
|
- If only warnings exist, allow commit and show warnings.
|
|
- Write `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, and optional deterministic `contentHash`.
|
|
- Write `JStage`, endpoint, and connection records only.
|
|
- Do not create Stage scenes, Stage geometry, Stage objects, or Stage bake artifacts.
|
|
|
|
4. Wire commit into `WorldEditorWindow`.
|
|
- Add or enable commit button.
|
|
- Let the user choose/create a target `JGraphSO`.
|
|
- Display validation messages after commit attempt.
|
|
- Mark changed assets dirty and save through Unity asset APIs.
|
|
|
|
5. Add validation display.
|
|
- Reuse UI Toolkit patterns from the Stage Editor inspector/top bar where practical.
|
|
- Show errors and warnings clearly.
|
|
- Keep visual polish secondary to correctness for V1.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Commit button publishes `JGraphSO` only.
|
|
- Commit button never generates Stage scenes or Stage bake output.
|
|
- Commit aborts when validation errors exist.
|
|
- Commit can proceed with warnings.
|
|
- Required endpoint without connection is an error.
|
|
- Optional endpoint without connection is a warning.
|
|
- `JGraphSO` publication metadata is written on successful commit.
|
|
- Repeated commits preserve stable ids rather than regenerating ids from names or positions.
|
|
|
|
## Validation
|
|
|
|
- Unity compile succeeds.
|
|
- Manually verify commit of a minimal valid layout with two stages and a socket connection.
|
|
- Manually verify commit aborts when two stages overlap on the same WorldLayer tile.
|
|
- Manually verify commit aborts when a required endpoint has no connection.
|
|
- Manually verify commit allows an optional unconnected endpoint and reports a warning.
|
|
- Manually verify no Stage scene, Stage geometry, or Stage bake output is created by commit.
|
|
- No automated tests are required for this phase.
|
|
|
|
## Risks
|
|
|
|
- Id preservation can be broken if conversion derives ids from mutable fields; use stored stable ids from authoring data.
|
|
- Validation and commit can become coupled to UI; keep validation and conversion in separate services.
|
|
- Content hash can become noisy if it includes non-deterministic ordering or timestamps; omit or narrow it if deterministic hashing is not cheap.
|