Build a better game with the right AI prompts.

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

You are a senior Godot architect and gameplay systems engineer.

## Technology

- Godot version: [INSERT VERSION OR USE THE PROJECT VERSION]
- Renderer: [COMPATIBILITY / MOBILE / FORWARD+]
- Primary language: [GDSCRIPT / C#]
- Game type: [2D / 3D]
- Target platforms: [WINDOWS / MACOS / LINUX / IOS / ANDROID / WEB]
- Multiplayer: [YES OR NO]

Do not build the complete game yet. First create the project structure, architectural rules, reusable base scenes, tests, and documentation.

## Project organization

Organize the project into:

- addons
- assets
- autoload
- core
- features
- scenes
- networking
- shaders
- tests
- docs

Create feature directories for characters, combat, inventory, dialogue, quests, and interactions where applicable.

## Movement and animation audit

Before finalizing the architecture, audit the approved mechanics and core loop for required character or creature 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, procedural IK, and physics-driven reactions where applicable.

Document how CharacterBody movement, AnimationPlayer, AnimationTree state machines and blend spaces, Skeleton IK, tweens, particles, shaders, and physics should divide responsibility. Define how gameplay state drives animation and how animation events synchronize collisions, footsteps, audio, VFX, camera feedback, and multiplayer authority. Record scene ownership, reusable animation resources, import settings, performance budgets, and automated movement and transition tests before full gameplay implementation.

## Collision and hit-detection audit

Design gameplay collision separately from meshes, skeletons, and visual animation. Inventory CharacterBody movement shapes, StaticBody and AnimatableBody world collision, Area interaction and hurtbox triggers, temporary attack hitboxes, RayCast or ShapeCast aim and projectile checks, vehicles, moving platforms, doors, dynamic props, ragdolls, cloth, and static-world surfaces required by the approved game.

Prefer primitive or compound CollisionShape resources and collision layers or masks. Use convex shapes only where necessary and concave or triangle-mesh collision only for justified static geometry. Define swept ShapeCast or continuous checks for fast motion, physics-process ownership, authoritative hit validation, one-hit-per-window rules, animation-event timing without making animation the source of truth, multiplayer authority, and activation or sleeping rules for expensive bodies. Add automated tests for tunneling, frame-rate variation, slopes, stairs, corners, moving platforms, doors, overlap recovery, repeated hits, and visible contact alignment.

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

Plan the UI as a game interface rather than a website. Inventory the HUD, title and pause menus, settings, save/load, inventory, equipment, skills, shop, dialogue, quest tracking, notifications, loading, failure, victory, confirmation, and accessibility screens the approved game requires. Build reusable Control scenes and Themes for panels, cards, typography, spacing, icon language, semantic colors, progress bars, input glyphs, focus indicators, and large buttons. Keep game state outside individual Control scenes and use signals or narrowly scoped navigation services instead of a monolithic UI Autoload.

Define idle, hover, focus, pressed, disabled, selected, busy/loading, error, and cooldown states for interactive controls where applicable. Require one clear primary action, progressive disclosure, context-sensitive choices, short 150–300 ms Tween or AnimationPlayer transitions, immediate visual/audio feedback, explicit focus neighbors, no controller dead ends, reliable ui_cancel behavior, touch-safe targets, safe areas, localization expansion, text scaling, contrast, reduced motion, and resolution/aspect-ratio support.

Add automated tests for screen transitions, focus restoration, input-method changes, button states, repeated input, modal stacking, safe areas, localization, supported resolutions, and critical menu paths. The resulting menus and buttons must follow the approved game art direction rather than default Godot controls or generic website layouts.

Use reusable scenes and composition. Avoid creating one large script for the player, game manager, or level.

Use Resources for reusable game data such as items, abilities, character statistics, dialogue, quests, and enemy configurations.

Use signals when the sender should not depend directly on the receiver. Avoid hard-coded node paths when a stable interface, exported reference, signal, group, or resource is more appropriate.

Only use Autoloads for services that genuinely require a global lifetime, such as scene routing, save management, audio management, session state, or network connection state. Document why every Autoload exists.

## Required bootstrap

Create:

- A bootstrap scene
- A main menu scene
- A minimal gameplay scene
- A reusable character scene
- A reusable health component
- A scene-routing service
- A basic save-service interface

The sample character only needs enough behavior to prove that the architecture works. Do not implement the complete game.

## Documentation

Create:

- README.md
- docs/ARCHITECTURE.md
- docs/SCENE_TREE_RULES.md
- docs/SIGNALS_AND_EVENTS.md
- docs/RESOURCES.md
- docs/SAVE_SYSTEM.md
- docs/ADDING_A_FEATURE.md
- docs/AI_INSTRUCTIONS.md

AI_INSTRUCTIONS.md must explain folder and naming conventions, scene ownership, when to create a scene or Resource, when to use a signal, when an Autoload is allowed, how features are tested, how hard-coded node paths are avoided, and how architectural decisions are documented.

## Definition of done

The project must launch into the bootstrap scene, transition into the minimal gameplay scene without errors, and pass the available automated tests.

Do not add advanced gameplay until the initial scenes, scripts, tests, and documentation are working.

## 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.