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

• For an input/menu claim, exercise the real Input System adapter and composed scene rather than invoking gameplay Commands directly. A typed world-command scenario is appropriate for a simulation claim, but proves no omitted input projection, camera or UI boundary.
• 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.

Iteration, Integration And Performance

Use the shortest existing route containing the claim. Pure rules can run outside Unity when they share production source. A direct-boot scenario can avoid title generation and reuse a session for repeated designer/agent experiments. Neither replaces fresh-scene lifetime tests or normal menu, input and audio coverage. Batch related scenarios or suites in one invocation when the project supports it; preserve per-case diagnostics and wait for a cleanup-complete receipt before another submission. Do not delete distinct contracts simply to lower test count.

Automated repeated playback should not disrupt the owner's devices. Where appropriate, temporarily mute final test output while real sources still play and assertions inspect their behavior. Restore the prior setting after failure, reload and teardown. Do not lower the authored game mix or certify physical speaker quality from a source-state assertion. The same ownership principle applies to synthetic input devices, focus and temporary engine settings.

For a performance claim, establish a target-build baseline before architectural change. Match actual canvas resolution, display preference, population, seed, input route and simulation clock. Run measurements serially; keep invalid runs and rejected candidates with their reasons, then recheck the control when machine load could explain a gain. Separate fixed-work measurements from normal elapsed-time catch-up, cold first-use events from warmed steady state, and rendered player frames from numeric/headless timing. Verify a compiled or job backend really executed rather than merely checking a setting. An engine plus backend upgrade measures the combination unless separately isolated.

These practices follow the Salvageist pilot, where the first data-oriented migration regressed a workload, later target-Web changes improved it, and a warmed benchmark still missed the first-death shader hitch. They are conditional measurement guidance, not a requirement to adopt its Scenario Lab, crowd architecture, Burst, ECS or a new STAGE benchmark framework.

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.

Concurrent Authoring

Use one Unity Editor per worktree. A code-only change opens Unity when its verification needs the engine. Isolated Unity work uses its own worktree and Library; caches are not project authority. Serialize integration of changes that share authored state, then let the integration editor import, compile, and exercise the changed production consumer.

Treat scenes, prefabs, authored assets, project settings, package manifests and locks, input-action assets, Addressables, localization, middleware projects, animation graphs, and generator-owned asset families as exclusive while they are being mutated. Narrow these boundaries only when project conventions and observed safe behavior justify it.

UnityYAMLMerge may resolve syntax in scenes and prefabs, but the integrated asset still needs reference, transform, composition, and consumer checks in Unity. Return ambiguous serialized or binary conflicts to the owner; do not pick one side or regenerate authored state by convenience.

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 make a local checkpoint after relevant mechanical checks pass. Human product acceptance is separate.

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.

CI And Analysis

Unity needs more than a generic C# job. A future project workflow may include:

1. license/entitlement setup through a trusted provider;
2. exact Unity editor version;
3. Library cache only as an optimization, never authority;
4. batch-mode EditMode tests;
5. batch-mode PlayMode tests compatible with the project's rendering needs;
6. a project-owned player build;
7. retained XML, editor logs, player logs, and build receipt; and
8. target launch/performance jobs only where runners can support the claim.

Do not add hosted Unity execution until the project has stable local commands, secrets handling, and enough recurring value to justify maintenance. A clean local rehearsal copy can expose most clean-machine problems earlier.

Use:

• Unity's compiler diagnostics;
• Unity Test Framework;
• assembly definitions for real ownership boundaries;
• focused Roslyn analyzers for important mechanically expressible rules;
• project validators for serialized assets and content; and
• production-consumer PlayMode routes.

IDE inspections are useful local feedback. A rule relied upon for project acceptance needs a reproducible command or engine route, not only one person's IDE state.