Story 1.1: Launch a Runnable, Testable Windows Shell

Status: done

Story

As Tim, I want a repeatable Windows build that opens the Baseline play space, so that every later slice is testable outside the Editor.

Acceptance Criteria

1. Given composition is still validating, when the single BaselineSandbox scene opens, then a static Loading play space… overlay prevents interaction with incomplete gameplay.
2. Given composition validation fails, when Bootstrap handles the failure, then the incomplete game surface remains unavailable and a fatal overlay shows a stable diagnostic code plus Exit without adding a second scene.
3. Given the repository project is opened in Unity 6000.5.6f1 and package import has completed without Console errors, when the canonical Windows build procedure is followed, then the Windows profile includes only Assets/TestGame/Scenes/BaselineSandbox.unity, targets Intel 64-bit, enables Development Build, and disables Autoconnect Profiler, Deep Profiling, and Script Debugging.
4. Given that profile, when Player Settings are inspected before building, then the product name is TestGame, the default window is 1600×900, display mode is Windowed, Resizable Window is enabled, and Windows is the only accepted desktop target.
5. Given the approved profile and Player Settings, when Build writes Builds/Windows/TestGame.exe and that executable is launched directly, then it opens BaselineSandbox as a fresh session, displays the Development Build marker, and requires no account, network, save, MCP, or Editor dependency.
6. Given the launched executable, when it is resized to 1280×720 and 1600×900, then the startup/fatal UI, persistent-HUD placeholder region, and world-interaction placeholder surface remain visible and usable, and acceptance evidence records the Unity version, build-profile settings, output path, Windows version, hardware, and result. Full Storage, selection, Quest, and job-timer verification remains owned by the stories that create those surfaces and by integrated UX verification.
7. Given the test assemblies, when project tests are invoked, then at least one Edit Mode smoke test and one Play Mode startup/composition test are discovered and pass without gameplay implementation from later stories.

Tasks / Subtasks

• Establish repository and assembly foundations (AC: 3, 7)

  • Add a Unity-appropriate repository-root .gitignore covering at least TestGame/Library/, Temp/, Logs/, UserSettings/, .vs/, generated IDE project files, and Builds/; retain source assets, .meta files, Packages, and ProjectSettings.
  • Audit starter-template assets through Unity reference inspection before deleting them; record which assets are retained, migrated, or removed and why.
  • Remove the unused Unity tutorial/readme payload through the Unity Editor so matching .meta files are removed with it: Assets/TutorialInfo/, Assets/TutorialInfo.meta, Assets/Readme.asset, and Assets/Readme.asset.meta.
  • After BaselineSandbox safely contains any starter camera/light/URP setup worth retaining and is the sole build scene, remove the obsolete Assets/Scenes/SampleScene.unity and its .meta file. Update the template-default-scene reference if Unity does not clear it automatically.
  • Inspect Assets/InputSystem_Actions.inputactions and Assets/Settings/SampleSceneProfile.asset before removal. Delete an asset only if the new scene, EditorBuildSettings, render settings, and serialized objects no longer reference it; otherwise migrate/rename it into the canonical Assets/TestGame/ structure first.
  • Do not delete Assets/Settings wholesale: the current URP renderer, pipeline, global settings, and volume assets may still be required. Do not delete Packages/, ProjectSettings/, source .meta files, or regenerate the Unity project.
  • Create TestGame.Domain, TestGame.Unity, TestGame.Presentation, and TestGame.Bootstrap Assembly Definitions under their prescribed Assets/TestGame/ boundaries.
  • Enforce dependencies: Domain has no UnityEngine; Unity references Domain; Presentation references Domain and only a narrow Unity-facing interface if demonstrably needed; Bootstrap alone composes all runtime boundaries.
  • Create Edit Mode and Play Mode test Assembly Definitions with Unity Test Framework/NUnit test support and explicit references to the assemblies they test.
  • Add one real Edit Mode configuration smoke test and one real Play Mode composition/scene test; empty assemblies do not satisfy discovery.

• Author the single-scene startup shell (AC: 1, 2, 5, 6)

  • Create Assets/TestGame/Scenes/BaselineSandbox.unity; preserve useful starter URP camera/light/volume behavior where appropriate, but do not modify or delete SampleScene merely to create the new scene.
  • Scene-author separate gameplay/world, persistent-HUD placeholder, and startup/fatal overlay roots. The overlay must exist before runtime composition, cover/block incomplete interaction, and remain readable at 1280×720 and 1600×900.
  • Implement a minimal SceneCompositionRoot that validates mandatory serialized references, begins with gameplay disabled/non-raycastable, and exposes no partial session.
  • On successful validation, hide the loading state before enabling the minimal shell. Do not implement later-story gameplay, content definitions, or speculative session systems.
  • On deterministic validation failure, keep the shell unavailable, log detailed development context, and show a concise fatal state with one documented stable diagnostic code and Exit.
  • Route Exit through a narrow injectable quit boundary so Play Mode can verify the request; the production adapter calls Application.Quit, whose call is ignored in the Editor.
  • Dispose any created session/composition-owned resources on scene unload; every scene load and executable launch starts fresh.

• Make startup behavior executable and regression-testable (AC: 1, 2, 7)

  • Play Mode-test the initial loading/input-blocked state, successful transition ordering, and validation-failure exclusivity.
  • Force failure through a controlled validation seam rather than committing a broken scene; assert the stable code, fatal text, Exit availability, and absence of an exposed partial shell/session.
  • Test the quit boundary independently of Application.Quit Editor behavior.
  • Use test names in Method_WhenCondition_ExpectedResult form and ensure tests run without MCP.

• Configure and persist the canonical Windows build contract (AC: 3, 4)

  • Update ProjectSettings/EditorBuildSettings.asset so the only enabled build scene is Assets/TestGame/Scenes/BaselineSandbox.unity; preserve unrelated configuration objects and keep SampleScene out of the build.
  • Update only the required Player Settings: product TestGame, default 1600×900, Windowed, Resizable Window enabled. Verify the serialized result through the Unity UI rather than assuming enum values.
  • Create/save a version-controlled Windows Build Profile under Assets/TestGame/Settings/BuildProfiles/ if Unity supports the required profile there; never use Library/BuildProfiles as source-controlled evidence.
  • Verify Windows Intel 64-bit, Development Build on, and Autoconnect Profiler, Deep Profiling, and Script Debugging off. “Windows only” means the accepted/built target; do not delete installed platform support or add cross-platform abstractions.
  • Reopen/reload the project and confirm the scene list, profile, serialized assets, compiler state, and both tests survive outside transient Library state.

• Produce acceptance evidence from the standalone player (AC: 5, 6)

  • Build to repository-relative Builds/Windows/TestGame.exe; keep build output ignored and outside Assets/.
  • Launch the executable directly outside the Editor, confirm the Development Build marker, and verify it runs without account, network, save, MCP, or Editor dependencies.
  • Close and relaunch to prove a fresh shell/session and absence of cross-launch persistence.
  • Capture results at 1280×720 and 1600×900, including startup/fatal readability, placeholder region visibility, and world-interaction surface availability.
  • Record Unity 6000.5.6f1, profile flags, output path, Windows version, CPU/GPU/RAM, and pass/fail result. Configuration inspection or Editor Play Mode alone is not acceptance evidence.
  • Run both test suites, record discovered/passed counts, confirm no compiler/Console errors, and check git status for generated-file leakage.

Review Findings

• [Review][Patch] Validate all startup-overlay child references before invoking view transitions [TestGame/Assets/TestGame/Bootstrap/Composition/SceneCompositionRoot.cs:31]
• [Review][Patch] Gate the world-interaction root together with the shell during loading and fatal startup [TestGame/Assets/TestGame/Bootstrap/Composition/SceneCompositionRoot.cs:87]
• [Review][Patch] Give the fatal explanation and diagnostic code distinct layout regions [TestGame/Assets/TestGame/Editor/StoryOneProjectSetup.cs:160]
• [Review][Patch] Fail build automation when BuildPipeline.BuildPlayer does not succeed [TestGame/Assets/TestGame/Editor/StoryOneProjectSetup.cs:92]
• [Review][Patch] Clear the deleted SampleScene template-default reference [TestGame/ProjectSettings/ProjectSettings.asset:265]
• [Review][Patch] Handle failed or cancelled TMP Essential Resources imports without hanging batch setup [TestGame/Assets/TestGame/Editor/StoryOneProjectSetup.cs:34]
• [Review][Patch] Anchor the Windows build output path to the Unity project instead of the process working directory [TestGame/Assets/TestGame/Editor/StoryOneProjectSetup.cs:84]

Dev Notes

Scope and sequencing

• This is the first story; there is no previous-story implementation to reuse. It provides the shell and test seam required by all later slices.
• Owned requirements are GFR-070, GNFR-004, and GNFR-005. Here, GFR-070 means fresh launch/no cross-launch persistence; in-session defeat durability is implemented later. GNFR-005 is established through a resize-safe shell, not by prematurely building Storage, selection, Quest, or job UI.
• The three implementation slices must pass independently: (1) build/profile and test discovery, (2) startup/composition failure, and (3) executable launch and resize evidence.
• Do not add a loading/bootstrap scene, title/options/restart flow, save/load, PlayerPrefs gameplay state, networking, accounts, analytics, runtime MCP, controller/mobile support, Addressables, Resources.Load, or gameplay from later stories.

Current repository state

• The initialized Unity project lives at TestGame/ and is pinned to Unity 6000.5.6f1 revision 0e0577a1a2ac. Do not recreate, replace, or upgrade it.
• Only Assets/Scenes/SampleScene.unity exists today; it contains the starter URP camera, directional light, and global volume. There is no Assets/TestGame/ code, scene, Assembly Definition, or test assembly.
• ProjectSettings/EditorBuildSettings.asset currently enables only SampleScene and contains the Input System action mapping. Replace the scene entry and preserve or deliberately migrate the input mapping before deleting its source asset.
• ProjectSettings/ProjectSettings.asset already names the product TestGame and uses the Input System, but currently stores 1024×768 and resizableWindow: 0. Update the required fields without broadly rewriting unrelated settings.
• Known removable tutorial payload is Assets/TutorialInfo/ plus Assets/Readme.asset and their .meta files. SampleScene, the starter input actions, and SampleSceneProfile require reference-safe migration or replacement before deletion; the URP assets under Assets/Settings/ are not blanket cleanup targets.
• The pinned package set already matches the architecture: URP 17.5.0, Input System 1.20.0, AI Navigation 2.0.14, uGUI 2.5.0, and Test Framework 1.7.0. Do not upgrade or add packages. The starter Multiplayer Center package is not authorization to add networking.
• The only commit is the initial README commit, and the working tree contains substantial untracked project/planning content. Preserve all user work and do not use destructive cleanup.

Architecture compliance

• Put every first-party Unity asset under TestGame/Assets/TestGame/. Use one public top-level C# type per matching file and namespaces TestGame.<Boundary>.<Feature>.
• Domain stays pure C#. MonoBehaviours use private [SerializeField] references; explicit Bootstrap composition owns wiring. No gameplay singleton, service locator, DontDestroyOnLoad, Find*, or repeated runtime discovery.
• BaselineSandbox is the sole Baseline scene. The startup overlay is scene-authored and static so it can protect the surface while composition validates.
• A validation failure is startup failure, not a recoverable partially playable state. Keep detailed asset/field context in development diagnostics while the player-facing overlay shows a stable code, concise explanation, and Exit.
• Runtime UI uses uGUI and TextMesh Pro passive views. Essential startup/failure state must not rely on hover, color, audio, Inspector, Console, or development tooling.
• Use Canvas anchors/layout and CanvasScaler so the placeholder safe regions remain visible at both supported test sizes. Do not invent final HUD widgets owned by Story 1.7 or later epics.

File structure requirements

Expected new areas (exact types may vary if responsibilities remain equivalent):

• TestGame/Assets/TestGame/Domain/TestGame.Domain.asmdef
• TestGame/Assets/TestGame/Unity/TestGame.Unity.asmdef
• TestGame/Assets/TestGame/Presentation/TestGame.Presentation.asmdef
• TestGame/Assets/TestGame/Bootstrap/TestGame.Bootstrap.asmdef
• TestGame/Assets/TestGame/Bootstrap/Composition/
• TestGame/Assets/TestGame/Presentation/Diagnostics/ or Presentation/Common/ for passive startup/fatal UI
• TestGame/Assets/TestGame/Scenes/BaselineSandbox.unity
• TestGame/Assets/TestGame/Settings/BuildProfiles/ for the version-controlled profile, if supported by the Editor
• TestGame/Assets/TestGame/Tests/EditMode/TestGame.Tests.EditMode.asmdef and .../Common/
• TestGame/Assets/TestGame/Tests/PlayMode/TestGame.Tests.PlayMode.asmdef and .../Composition/

Expected updates:

• Repository-root .gitignore
• TestGame/ProjectSettings/EditorBuildSettings.asset
• TestGame/ProjectSettings/ProjectSettings.asset

Expected removals after reference-safe migration:

• TestGame/Assets/TutorialInfo/ and TestGame/Assets/TutorialInfo.meta
• TestGame/Assets/Readme.asset and TestGame/Assets/Readme.asset.meta
• TestGame/Assets/Scenes/SampleScene.unity and its .meta file after BaselineSandbox replaces it
• Other starter assets only when Unity reports no remaining serialized, scene, settings, or build references

Preserve Packages/manifest.json, Packages/packages-lock.json, required URP/rendering assets, starter assets not explicitly replaced, and unrelated Project Settings. Perform asset cleanup in the Unity Editor where practical, then verify there are no missing-script, missing-GUID, compiler, or Console errors.

Testing requirements

• Edit Mode tests must be discoverable through a test Assembly Definition and avoid scene loading/frame time. A configuration/assembly-boundary smoke test is sufficient for this story.
• Play Mode tests must cover the actual BaselineSandbox composition path: initial loading block, success transition, controlled failure, fatal state, and testable Exit request.
• Test Assembly Definitions must opt into test assemblies and explicitly reference the runtime assemblies under test. Do not rely on folder names alone.
• Manual standalone evidence is mandatory for build flags, direct launch, Development Build marker, fresh relaunch, and resizing. Automated Editor tests complement but do not replace it.
• After cleanup, reopen BaselineSandbox and run both suites to catch missing GUIDs, scripts, input mappings, materials, volume profiles, or render-pipeline references. git status must show paired asset/.meta removal and no generated-cache additions.

Latest Unity-specific information

• Unity 6 Build Profiles use an ordered Scene List; the profile can override the global list. Verify exactly one enabled scene after saving and reopening the profile.
• Enabling Development Build defines DEVELOPMENT_BUILD; guard development-only diagnostics with UNITY_EDITOR || DEVELOPMENT_BUILD.
• Application.Quit terminates a built player and accepts an optional exit code on Windows, but Unity ignores it in the Editor. Keep the quit request behind a test seam.
• The installed project versions remain authoritative. Do not substitute a newer package merely because newer online documentation exists.

Project Context Rules

• Follow _bmad-output/project-context.md in full. Particularly: no Domain UnityEngine reference; only Bootstrap composes boundaries; no scene-wide searches; no per-frame allocation/logging/UI rebuild; no runtime persistence or MCP dependency; no speculative framework/generalization.
• Optional CoplayDev MCP and Context7 may assist development, but tests and the player must function without them.
• Development diagnostics must compile only under UNITY_EDITOR || DEVELOPMENT_BUILD and cannot count as the player-facing fatal overlay or acceptance surface.

References

• [Source: _bmad-output/planning-artifacts/gdds/gdd-TestGame-2026-08-02/epics.md — Story Contract; Epic 1; E1.S1]
• [Source: _bmad-output/planning-artifacts/gdds/gdd-TestGame-2026-08-02/gdd.md — Canonical Requirement Register: GFR-070, GNFR-004, GNFR-005; Accessibility; Out of Scope]
• [Source: _bmad-output/game-architecture.md — Assembly Boundaries; UI Architecture; Scene Composition; Testing Strategy; Project Structure; Definition-to-Session Boundary; Windows Development Build Procedure]
• [Source: _bmad-output/project-context.md — Technology Stack; Engine-Specific Rules; Code Organization; Testing; Platform & Build; Critical Don’t-Miss Rules]
• [Source: TestGame/ProjectSettings/ProjectVersion.txt; TestGame/ProjectSettings/EditorBuildSettings.asset; TestGame/ProjectSettings/ProjectSettings.asset; TestGame/Packages/manifest.json]
• Unity Manual: Manage scenes in a build
• Unity Manual: Build Profiles window reference
• Unity Scripting API: Application.Quit
• Unity Test Framework: Edit Mode vs. Play Mode tests

Dev Agent Record

Agent Model Used

GPT-5 Codex

Implementation Plan

• Establish strict Domain, Unity, Presentation, and Bootstrap assembly boundaries plus Edit/Play test assemblies.
• Author a scene-first blocked startup surface, validate composition atomically, and expose success/fatal states through a passive TMP/uGUI view.
• Persist the Windows x64 Development Build contract, generate the canonical scene through Unity editor automation, and validate with red-green-refactor tests plus direct standalone launches.

Debug Log References

• TestGame/Logs/editmode-red.log: expected red-phase missing shell contracts.
• TestGame/Logs/editmode.log: final Edit Mode result, 1/1 passed.
• TestGame/Logs/playmode.log: final Play Mode result, 4/4 passed.
• TestGame/Logs/build.log: final Windows build result, Success.
• Standalone TMP failure was reproduced, corrected by importing official TMP Essential Resources, and regression-checked with a clean final player log.

Completion Notes List

• Ultimate context engine analysis completed - comprehensive developer guide created.
• Independent artifact, architecture/repository, and quality-risk reviews reconciled.
• Full integrated HUD verification explicitly deferred to its owning stories while preserving Story 1.1’s resize-shell obligation.
• Starter tutorial/readme and obsolete sample-scene cleanup added with explicit reference-safety checks and URP preservation guards.
• Implemented the single-scene startup shell with scene-authored loading protection, atomic composition validation, stable fatal code TG-BOOT-001, and injected Exit handling.
• Preserved the Input Actions binding, starter URP pipeline assets, and required volume profile while removing only audited obsolete starter payload.
• Persisted the Windows Intel 64-bit Development Build profile and required 1600×900 windowed/resizable Player Settings.
• Added one Edit Mode smoke test and four passing Play Mode startup/composition tests, including loading the actual BaselineSandbox scene.
• Built and directly launched Builds/Windows/TestGame.exe; verified fresh launches and resize-safe placeholders at 1280×720 and 1600×900 with captured evidence.
• Final validation: Edit Mode 1/1, Play Mode 4/4, Windows build Success, clean direct-launch startup log, and no generated cache/build leakage in Git status.

File List

• .gitignore
• TestGame/Assets/TestGame/ (new runtime assemblies, editor setup, canonical scene, tests, build profile, and paired .meta files)
• TestGame/Assets/TextMesh Pro/ (official TMP Essential Resources and paired .meta files)
• TestGame/ProjectSettings/EditorBuildSettings.asset
• TestGame/ProjectSettings/ProjectSettings.asset
• TestGame/Assets/TutorialInfo/ and TestGame/Assets/TutorialInfo.meta (deleted)
• TestGame/Assets/Readme.asset and TestGame/Assets/Readme.asset.meta (deleted)
• TestGame/Assets/Scenes/SampleScene.unity and TestGame/Assets/Scenes/SampleScene.unity.meta (deleted)
• _bmad-output/implementation-artifacts/1-1-windows-shell-acceptance-evidence.md
• _bmad-output/implementation-artifacts/1-1-standalone-1280x720.png
• _bmad-output/implementation-artifacts/1-1-standalone-1600x900.png
• _bmad-output/implementation-artifacts/1-1-launch-a-runnable-testable-windows-shell.md
• _bmad-output/implementation-artifacts/sprint-status.yaml

Change Log

• 2026-08-03: Implemented and validated the runnable, testable Windows shell; added assembly/test foundations, startup/fatal composition, canonical scene/profile/settings, official TMP resources, and standalone acceptance evidence.