Unity Profile

This profile maps STAGE concepts to common Unity practices. None of the listed packages are required.

Concept Mapping

STAGE concept	Common Unity implementation
Authored intent	ScriptableObjects, prefabs, scenes, UXML, configuration assets
Composition	LifetimeScope, scene root, installers, explicit factories
Runtime state	Plain C# objects, components, ECS components, registries
Runtime systems	Tickable services, MonoBehaviours, ECS systems, custom PlayerLoop
Engine shell	MonoBehaviours, renderers, physics, particles, animation, input
Operation surface	Editor windows, menu commands, inspectors, MCP tools
Evidence surface	EditMode tests, PlayMode tests, deterministic scenes, screenshots, profiler, revision-bound player builds

Unity Requirements

A STAGE-mapped Unity project should document:

• the bootstrap scene and composition root;
• script compilation and domain-reload expectations;
• canonical content and configuration assets;
• scene and prefab ownership;
• generated asset roots and rebuild commands;
• Play Mode entry and smoke workflows;
• supported player-build targets and project-owned build operations;
• editor-settled and console-clean checks;
• target input paths and visual resolutions;
• middleware generation and import steps.

Compilation Workflow

After script changes:

1. focus or signal the Unity Editor;
2. wait for compilation, import, and domain reload to settle;
3. inspect the Unity console;
4. run focused tests;
5. exercise composed Play Mode when runtime wiring changed;
6. inspect appearance changes through the smallest truthful Unity-native surface; export evidence only when a decision-bearing artifact consumer requires it.

Generated IDE project builds are useful supplemental checks. They are not substitutes for Unity's compiler and composed runtime.

Readiness Ladder

Do not collapse Unity readiness into a single installed or compiled state:

1. Source present: package, asset, or project files resolve.
2. Imported: Unity has completed import and package resolution.
3. Compiled: project assemblies compile in the intended editor version.
4. Composed: the real scene and composition root resolve their graph.
5. Activated: scene-dependent surfaces such as UI Toolkit runtime content have entered the lifecycle phase in which consumers can bind them.
6. Interactive: the intended input and gameplay path works in Play Mode.
7. Experiential: a human has accepted readability, feel, and product intent.

Evidence from one rung does not establish later rungs. In particular, UIDocument.rootVisualElement content may not be ready during a composition root's Awake, even when dependency construction succeeds. Bind activation- sensitive views from an appropriate start or scene-ready lifecycle phase.

Architecture Guidance

• Keep local component behavior local when extraction adds no real control or test value.
• Use explicit runtime systems for cross-actor, cross-domain, or ordered behavior.
• Keep ScriptableObjects as authored intent unless shared mutable state is explicitly intended.
• Use assembly definitions when dependency conventions repeatedly fail.
• Add a composed startup smoke test for dependency-injection graphs.
• Treat scene and prefab generation as ownership-sensitive operations.
• Use fixed real-scale seeds for procedural-world review.
• Keep useful runtime diagnostics available after the immediate bug is fixed.
• Name coordinate spaces in APIs that cross simulation and Unity presentation boundaries, such as LocalCellToWorld rather than an ambiguous ToPosition.
• Give runtime-created meshes, materials, textures, GameObjects, and other Unity resources an explicit owner and symmetric release path.
• Infer runtime shader compatibility from the active render pipeline, not from the mere presence of a render-pipeline package.

Scene And UI Authoring

• Treat authored scenes, prefabs, UXML, and USS as canonical source unless a named generator explicitly owns them.
• Prefer small targeted editor operations over a retained command that rebuilds an entire authored scene.
• When an editor operation creates or opens a destination scene, do that before loading native asset references that will be assigned into the scene. Scene transitions can invalidate handles loaded earlier in the operation.
• Preserve user-authored transforms and references. Reopen and inspect the actual serialized result before declaring the operation complete.
• Verify authored UI both structurally and in the Game view. A camera render target does not normally include overlay UI Toolkit content.
• Declare graphics-device for camera or screen capture operations. Do not call Camera.Render under Unity -nographics; use a graphical run or a separate structural assertion operation. Keep world-camera and overlay-UI claims separate unless the evidence surface actually captures both.
• Do not assume WaitForEndOfFrame resumes in a batch PlayMode test. When a deterministic composed artifact is needed, render the world camera and UI Toolkit panel into separate owned targets, assert both layers, alpha-compose them, and label the result as offscreen structural evidence rather than the exact Game-view backbuffer.

Runtime Resource Ownership

For every runtime-generated resource family, record:

• who creates it;
• whether it is shared or instance-owned;
• which scene or scope lifetime owns it;
• how repeated entry avoids duplicate allocation;
• how teardown releases it;
• which PlayMode test proves repeated composition and disposal.

This applies even to small visual helpers. A generated material that renders correctly once can still leak across scene reloads or use a shader unsupported by the active pipeline.

Deterministic Input Rehearsal

• Exercise the real Input System adapter and composed scene rather than invoking gameplay Commands directly.
• Treat virtual-device helper calls as queued input unless the test proves otherwise. Publish the queued state before polling the adapter, then publish release state before the next action.
• Pause and anchor the runtime to a named authored baseline before asserting exact Simulation Ticks. Scene load and activation may advance real-time schedulers before a test gains control.
• Advance exact scheduler Ticks only when the claim is deterministic mechanical reachability. Use a separate real-time rehearsal for cadence and pacing.
• Assert authoritative state and its projected world or UI surfaces together.
• Keep native Unity results authoritative. Produce a stable machine-readable summary only when a named CI, release, analytics, or publishing consumer requires it; byte-identical storage is not a verification goal by itself.
• Keep virtual Gamepad, physical-controller, control-feel, and human-acceptance claims separate.

Player-Build Evidence

• Let the project own build policy: target, enabled scenes, scripting backend, options, output shape, and any product-specific preconditions.
• Let STAGE verify provenance and integrity: clean source revision, effective Unity version, exact scene list, settled build log, raw receipt, and a hash of the complete external artifact tree.
• Keep build output and normalized evidence outside the Unity project. A build verifier must not quietly alter, clean, or stage the inspected repository.
• A successful BuildPipeline result proves that Unity assembled an artifact. It does not prove that the player launches, accepts input, performs well on target hardware, is signed or distributable, or meets human release intent.
• Use capture_unity_player_build_evidence.py to normalize a compatible project-owned receipt without transferring build policy into STAGE.

Player-Launch Evidence

• Let the project own readiness semantics. The game knows which scene, composition root, authoritative state, views, and cameras mean "started."
• Let STAGE own launch controls: exact clean revision and artifact, executable, nonce, timeout, process-group cleanup, receipt and log freshness, failure markers, and before/after artifact-tree identity.
• Keep the project probe opt-in, inert in the Editor and ordinary player runs, bounded by its own timeout, and able to terminate with an unambiguous status.
• Use natural standalone startup for a launch claim. A PlayMode test that waits a chosen number of frames is useful contract coverage but does not prove the built player's wall-clock startup path.
• A passing readiness receipt proves only its named checks. Record real input, rendered-frame correctness, performance, signing, distribution, and human release acceptance separately.
• Use run_unity_player_launch_probe.py to bind a compatible project-owned receipt to the exact built artifact.

Unity MCP

MCP is an operation surface, not an authority source. Use it to inspect scenes, focus compilation, read console state, run tests, enter Play Mode, and capture screenshots. Do not use it to regenerate broad scene state when a targeted serialized edit or manual authoring workflow is safer.

A one-time editor bootstrap may be useful for creating an initial scene, prefab, UI document, or material family. Before that output becomes manually authored, remove or disable the bootstrap, or constrain it to an explicitly generated subtree. A convenient rebuild command is not worth retaining when it can silently replace Inspector, scene, or layout decisions.

Visual Work

Start with Unity's existing asset preview, animation or VFX editor, Prefab Mode, Scene view, Game view, or the project's direct development route. If a named player, author, or recurring developer job justifies a codex, gallery, world previewer, or inspect mode, deliver it as an ordinary project feature and apply the safeguards in Unity Visual Work. Unity owns canonical content resolution, staging, rendering, playback, presentation, readiness, reset, and teardown. Human review remains the visual acceptance authority. Record a persistent route in the ordinary project map and operating docs without claiming that a custom gallery or callable agent operation exists when it does not.

Only when a decision-bearing artifact consumer needs durable or portable artifacts, use the project's own Unity capture, recorder, test, or build workflow. It must drive the same native subjects, scenarios, stage, and presentation state; it is not a second review implementation, and STAGE does not prescribe a universal export package.

Personal Profile Verification

The optional Solo Unity Owner Runbook uses Unity and the project as the verification surfaces. After one authorized dependency change, let Unity resolve or import it, wait for compilation and domain reload, inspect the settled Console, run the dependency's focused checks, exercise one real composed use when relevant, inspect the Git delta, and commit the accepted checkpoint.

Do not create STAGE-specific assessment versions, human-attestation forms, or operational-proof packets for a personal project. Preserve raw test, profiler, build, or diagnostic output only when it helps a current diagnosis or serves a named consumer. Human judgment remains necessary for visuals, feel, editor comfort, and product value, but it happens directly on the owning surface.

Dogfood Evidence

The Lanternworks longitudinal trial demonstrates dependency bootstrap, authored-scene composition, explicit runtime resource ownership, local/world coordinate boundaries, and deterministic world-plus-HUD capture in Unity 6000.3.6f1. Its virtual-Gamepad rehearsal also completes the authored First Light loop through the real input adapter with a repeatable state result. The trial also produces a clean-revision macOS player artifact with a deterministic tree hash while keeping player launch and release acceptance separate. A later standalone probe launches that exact class of artifact, reaches nine project-owned readiness checks, preserves the artifact tree, and exits cleanly. Mechanical startup passed; physical controller behavior, visual correctness, performance, control feel, and human acceptance remain deliberately unclaimed.