Build a better game with the right AI prompts.

# Task: Create the initial architecture for a scalable Unity game

You are a senior Unity architect and C# gameplay systems engineer.

## Technology

- Unity version: [INSERT VERSION OR USE THE PROJECT VERSION]
- Render pipeline: [BUILT-IN / URP / HDRP]
- Language: C#
- Target platforms: [WINDOWS / MACOS / IOS / ANDROID / WEB]
- Input: Unity Input System
- Asset loading: Unity Addressables
- Multiplayer: [YES OR NO]

Do not build the complete game yet. Create the project structure, architectural boundaries, bootstrap process, tests, and documentation first.

## Project organization

Create separate areas for:

- Bootstrap
- Core
- Systems
- Gameplay
- AI
- UI
- Networking
- Rendering
- Movement and animation
- Audio
- Save
- Tests
- Editor tools

Create separate feature areas for combat, inventory, quests, NPCs, economy, weather, and dialogue where those systems apply.

Use components for GameObject-specific behavior, but keep reusable business logic in plain C# classes where practical. Avoid large MonoBehaviour classes and do not create one manager that controls the entire game.

Use interfaces and events to reduce direct dependencies. Do not use static global state without a documented reason.

## Movement and animation audit

Before finalizing the architecture, audit the approved mechanics and core loop for required character locomotion, directional movement, starts and stops, turns, jumps and landings, traversal, combat and interaction actions, facial or lip-sync animation, mechanical or vehicle motion, VFX movement, secondary motion, Animation Rigging or IK, and physics-driven reactions where applicable.

Document the intended Animator, state-machine, blend-tree, Playables, root-motion or in-place, procedural animation, IK, physics, and VFX responsibilities. Define how gameplay state drives animation, how animation events synchronize footsteps, hits, collisions, audio, particles, camera feedback, and controller vibration, and how movement remains deterministic or server-authoritative when multiplayer applies. Record clip, rig, avatar, Addressables, performance, and automated Play Mode test requirements before full gameplay implementation.

## Collision and hit-detection audit

Design gameplay collision separately from rendered meshes and animated bones. Inventory CharacterController or Rigidbody movement bodies, CapsuleCollider character bodies, environment blockers, interaction triggers, hurtboxes, event-timed attack hitboxes, projectile and camera-aim raycasts or shape casts, vehicles, moving platforms, doors, dynamic props, ragdolls, cloth, and static-world collision required by the approved game.

Prefer primitive or compound colliders, collision layers, trigger filters, broad-phase-friendly shapes, and convex colliders only where simpler shapes cannot preserve gameplay. Reserve MeshCollider use for justified, mostly static geometry and avoid detailed render-mesh collision for moving actors. Specify Physics casts or continuous collision detection for fast attacks and projectiles, authoritative hit validation and one-hit-per-window rules, physics/animation update order, networking ownership, and when ragdolls or other expensive bodies activate and sleep. Add Play Mode tests for tunneling, frame-rate variation, slopes, stairs, corners, moving platforms, doors, overlap recovery, hitbox timing, repeated hits, and visual contact alignment.

## Game UI, menu, HUD, and button architecture

Plan the UI as a game interface, not a website. Inventory the required HUD, title, pause, settings, save/load, inventory, equipment, skills, shop, dialogue, quest, notification, loading, failure, victory, confirmation, and accessibility flows. Choose UI Toolkit or uGUI based on the existing project and target platforms, document the choice, and keep screen logic, game state, navigation, and reusable visual components separated through events and interfaces rather than one all-purpose UI manager.

Create a shared Theme or component library for typography, spacing, icons, semantic colors, panels, cards, progress bars, input glyphs, focus indicators, and large buttons. Define idle, hover, Input System focus, pressed, disabled, selected, busy/loading, error, and cooldown states where relevant. Require one clear primary action per screen, progressive disclosure, context-sensitive actions, short 150–300 ms transitions, immediate visual/audio feedback, predictable controller navigation, no dead ends, back/cancel behavior, touch-safe targets, safe-area handling, localization expansion, text scaling, reduced motion, and resolution/aspect-ratio support.

Add Edit Mode and Play Mode tests for screen ownership, opening and closing, focus restoration, mouse/controller/touch switching, button states, repeated input, modal stacking, safe areas, localization, supported resolutions, and critical menu flows. Menus and buttons must use the approved game art direction and must not ship as default engine widgets or generic web-style controls.

## Assemblies and scene lifecycle

Add Assembly Definition files that enforce the intended dependency direction and prevent circular assembly references.

Create:

- A bootstrap scene
- A persistent systems lifecycle when required
- A minimal gameplay scene
- An asynchronous transition from bootstrap into gameplay

Document which objects and services survive scene changes and who owns their lifecycle.

## Asset loading

Create a basic Addressables setup with an example asynchronous asset-loading service. Document who owns every loaded asset and when it must be released. Do not load the entire game at startup.

## Documentation

Create:

- README.md
- Docs/ARCHITECTURE.md
- Docs/SCENE_LIFECYCLE.md
- Docs/ADDRESSABLES.md
- Docs/SAVE_SYSTEM.md
- Docs/ADDING_A_SYSTEM.md
- Docs/AI_INSTRUCTIONS.md

AI_INSTRUCTIONS.md must explain:

- Folder and namespace conventions
- Assembly dependency rules
- When to use MonoBehaviour
- When to use ScriptableObject
- When to use a plain C# class
- How systems communicate
- How scenes are loaded
- How assets are loaded and released
- Required tests for new systems
- How architectural decisions are recorded

## Definition of done

Add Edit Mode and Play Mode tests for the initial architecture. The project must open without compilation errors, initialize through the bootstrap scene, load the minimal gameplay scene asynchronously, and pass its tests.

Do not add complete gameplay until the bootstrap, scene loading, tests, and documentation work.

## Internationalization and localization architecture

Build internationalization into the existing architecture before gameplay and UI content multiply. Do not create a separate localization application or bolt translation onto finished screens.

- Centralize player-facing text behind stable translation keys and locale resources. Do not hard-code display strings in gameplay, menus, tutorials, errors, notifications, subtitles, or content data.
- Define a fallback locale, missing-key behavior, resource ownership, extraction and validation commands, translator notes, and a safe process for adding or updating a language.
- Support Unicode, plural/select rules through an ICU-style message system or the engine's equivalent, locale-aware number/date/time/currency/unit formatting, and invariant internal IDs for saves, networking, analytics, achievements, and game rules.
- Plan for right-to-left layout and bidirectional text, CJK and other line-breaking rules, diacritics, input methods and IME where players type, font fallback and glyph coverage, translated text expansion, subtitles/captions, localized audio or asset variants where required, and runtime language selection with a persisted preference.
- Keep localization data separate from trusted game rules. Servers, SDKs, automation, and analytics should exchange stable language-independent identifiers while clients turn them into localized player-readable text.
- Add pseudolocalization, missing/unused-key validation, fallback-locale tests, long-string and text-expansion tests, right-to-left tests, font/glyph checks, and representative locale screenshots to the normal test and CI strategy.

Document the supported launch locales, later-locale workflow, ownership, file locations, naming rules, formatting rules, font and audio strategy, platform limitations, and exact commands another developer or translator uses.

## Player-readable output requirement

Everything shown to a player must be written and presented for a human player, not for a developer or debugger. This includes menus, HUD labels, buttons, prompts, tutorials, objectives, dialogue, tooltips, loading and save states, empty states, confirmations, warnings, errors, rewards, notifications, accessibility messages, and connection or recovery states.

Use concise plain language, the game's established terminology and tone, recognizable icons with text where meaning could be ambiguous, and a clear next action. A player-facing error should explain what happened in useful terms, whether progress is safe, and what the player can do next.

Never expose raw exceptions, stack traces, JSON, database IDs, internal event names, enum or variable names, file paths, debug coordinates, HTTP status codes without explanation, server implementation details, developer TODOs, placeholder text, or raw telemetry on a player-facing surface. Send technical details to development-only logs, diagnostics, telemetry, or an authenticated support view. A short support reference code may be shown to the player only when it helps support locate the private diagnostic record.

Verify representative success, failure, offline, loading, empty, permission, validation, timeout, save, reconnect, and recovery states from the player's perspective. Developer documentation and final engineering reports may remain technical; this requirement applies to anything the game presents to players.

## Required game documentation

Documentation is part of the definition of done for this task.

Before finishing:

1. Read the existing README, docs directory, architecture notes, decision records, and AI instructions that apply to this system.
2. Update the existing relevant documentation instead of creating a competing document or a second source of truth.
3. If no relevant document exists, create a clearly named Markdown document in the game's established documentation directory. Use docs/ when the project has no existing convention.
4. Document the current system, the decisions made, ownership and lifecycle rules, configuration, files or assets changed, commands and tests run, known limitations, and how another developer should extend or troubleshoot the work.
5. Update AI_INSTRUCTIONS.md or the project's equivalent when this task changes architectural boundaries, required workflows, naming rules, or validation commands.
6. Keep documentation accurate to the implementation. Do not claim support, measurements, or test coverage that was not verified.
7. In the final report, list every documentation file created or updated.