Scene Validation And Repairs

Purpose

Scene validation repairs are the bridge between scene diagnostics and editor actions. Validators attach typed codes, source jumps, related trigger ids, and repair metadata; the scene tab converts those diagnostics into repair batches that can be previewed or applied through the authoring command bus.

Steps

1. Run scene validation from the editor scene tab or through the shared validation/bake path.
2. Inspect diagnostics with typed SceneValidationCode, SceneRepairAction, source jump targets, and related trigger ids.
3. Preview a repair plan before applying edits.
4. Dry-run the repair through the command bus.
5. Apply the repair batch, save the scene, and rerun validation.

Validation Model

validate_scene_document builds one SceneValidationReport. The report stores errors and warnings as SceneValidationMessage values. A message can carry:

• SceneValidationCode
• SceneRepairAction
• SceneValidationTarget
• source jump target
• doctor report category
• related trigger ids
• optional issue identity for cross-panel dedupe

Typed codes currently cover missing transition pair ids, missing target entry points, and navigation-zone validation cases. Repair actions currently cover filling transition pair ids and creating missing entry points.

Transition Pairs

Transition triggers should have a transition_pair_id unless the trigger is explicitly authored as a one-way route with the intentional_one_way_transition tag. Missing pair ids emit TriggerMissingTransitionPairId and SceneRepairAction::FillTransitionPairIds.

Transition graph validation runs after trigger validation because trigger validation collects transition actions and destination aliases. The transition pass checks duplicate destination aliases, local pair fan-out, missing remote counterparts, disabled counterparts, destination entry coverage, ambiguous overlapping paired triggers, missing return routes, and return routes that target no valid local entry point.

Trigger Actions

Action validation inspects the primary trigger action and every action_pipeline step. Scene-transition actions must use canonical scene paths, non-empty target entry ids, readable and parseable target scenes, and target entry points that exist, use valid layers, and sit inside target-scene bounds.

Transition validation also warns when an arrival entry sits inside another transition trigger, because arrival may immediately retrigger or loop back to the source scene.

Dialogue actions validate NPC and topic ids. Event-style actions are prepared through gameplay semantics and checked through runtime-event validation. Spawn-encounter actions should reference authored scene mob spawners; related catalog validation can also check SpawnEncounter intents against known spawner ids when cross-catalog context is supplied.

Jump Targets And Source Maps

SceneDocumentTokenStream builds a SceneDocumentSourceMap before parse execution. The map stores section spans, record spans, scalar field spans, and embedded JSON field spans, with lookup indexes for section, record kind, record id, field, and JSON path.

Validators should prefer jump_targets.rs helpers such as SceneDocumentRecordRef, scene_record_field_message, and trigger_field_jump_target. Those helpers attach exact .scene field spans when possible. Trigger messages fall back to AuthoringJumpTarget::Trigger with a descriptor-backed inspector section when the source span is unavailable.

Doctor transition helpers attach SceneDoctorReportCategory::BrokenTransition, related trigger ids, and trigger field targets consistently.

Expected Outputs

A successful repair workflow produces a SceneValidationReport with source-aware diagnostics, a previewable repair plan, command-bus dry-run output, and scene edits in buckets such as trigger pair ids, trigger entry points, created entry points, and created return triggers.

Repair Metadata

The shared validation projection maps explicit SceneRepairAction values, and selected fallback SceneValidationCode values, into stable authoring autofix metadata:

• scene.fill_transition_pair_ids
• scene.create_entry_point

The editor scene-tab planner reads diagnostics that request transition repairs, extracts trigger ids from repair actions, targets, or related-trigger ids, and builds a SceneLintRepairPlan.

Concrete repair batches use four edit buckets:

• set_trigger_pair_ids
• set_trigger_entry_points
• create_entry_points
• create_triggers

For a current-scene transition target, repair planning can create the missing entry point at the trigger tile, retarget the trigger to it, and create a one-tile return trigger when the pair id is present. For remote targets, the planner uses transition-target metadata to report when a return route appears unrepairable from the current scene.

scene_lint_repair_preview_report dry-runs the batch through the command bus under source tool scene-repair, so UI previews and apply operations share the same command path.

Common Mistakes

• Matching diagnostics by human-readable text instead of typed codes or repair actions.
• Omitting transition_pair_id on two-way transition triggers.
• Creating a transition to a missing or out-of-bounds target entry point.
• Adding a new validator without source-map jump targets.
• Marking a transition one-way by accident instead of using the intentional one-way tag deliberately.

Recovery Paths

For broken transitions, fill missing pair ids, create the missing target entry point, and create a return trigger when the pair id implies one. For diagnostics that cannot be repaired automatically, jump to the source span and edit the owning scene section directly. After repair, rerun validation and the command-bus dry-run before saving broad scene changes.

Validator Authoring Rules

Add new validation behavior under src/scene/document/validation/* and wire it from validate.rs in the intended diagnostic order.

Use SceneValidationContext indexes instead of rescanning scene vectors when the context already exposes the lookup. Use source-map jump helpers for every diagnostic tied to an authored field. Use typed SceneValidationCode and SceneRepairAction only when editor or command-bus consumers can act on them.

When a diagnostic belongs in the scene doctor experience, use the doctor_report.rs helpers so category, related triggers, and jump metadata remain consistent. Keep repairable transition diagnostics precise: a message should identify the trigger, the field, and the repair action or code that the planner expects.

Add tests for new repairable diagnostics, including source-map jump target coverage, typed code mapping, repair action metadata, and command-bus dry-run behavior.

Related Pages

• Scene Documents
• Mob Encounters And Scene Combat
• Validation And Bake