Build a better game with the right AI prompts.

# Task: Create the initial architecture for a scalable Unreal Engine game

You are a senior Unreal Engine architect, C++ gameplay engineer, and technical designer.

## Technology

- Unreal Engine version: [INSERT VERSION]
- Primary code: C++
- Visual scripting: Blueprints
- Target platforms: [INSERT PLATFORMS]
- Multiplayer: [YES OR NO]
- Gameplay Ability System: [YES OR NO]
- World Partition: [YES OR NO]

Do not build the complete game yet. First create the module structure, base classes, content organization, testing strategy, and documentation.

## Project organization

Create C++ areas for:

- Core
- Characters
- Player
- AI
- Combat
- Abilities
- Inventory
- Interaction
- Quests
- UI
- Audio
- Save
- Networking
- Developer tools

Create corresponding Content directories where appropriate. Organize content around game features instead of putting every Blueprint or asset type into one global folder.

Use C++ for stable systems, reusable foundations, networking rules, and performance-sensitive logic. Use Blueprints for content assembly, configuration, animation integration, visual behavior, and rapid iteration.

Do not create large Blueprint graphs or one all-purpose player character, GameMode, GameInstance, or Subsystem.

Use Actor Components for reusable behavior such as health, interaction, inventory, equipment, and combat state.

Use Data Assets or Data Tables for items, weapons, abilities, enemies, quests, and character classes. Use Gameplay Tags instead of unrelated strings or large collections of booleans when representing gameplay state.

## Movement and animation audit

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

Document the intended Character Movement, Animation Blueprint, state-machine, Blend Space, Montage, Control Rig, IK Rig, Motion Warping, Motion Matching, root-motion, physics, and VFX responsibilities. Define how gameplay state and Gameplay Tags drive animation; how notifies synchronize hits, footsteps, audio, Niagara, camera feedback, and controller vibration; and how movement and animation replicate without allowing presentation to become trusted game state. Record asset, retargeting, performance-budget, and automation-test requirements before content expansion.

## Collision and hit-detection audit

Design gameplay collision separately from skeletal meshes and visual animation. Inventory CapsuleComponent character movement, world blockers, interaction overlaps, hurtboxes, temporary melee or ability hitboxes, line or shape traces for aiming and projectiles, vehicles, moving platforms, doors, dynamic props, Chaos ragdolls or destruction, cloth, and static-world collision required by the approved game.

Define Collision Channels, Object Types, Profiles, response rules, broad-phase-friendly primitive or compound shapes, simple-versus-complex collision policy, and when convex or static triangle geometry is justified. Use sweeps, traces, or continuous collision detection for fast movement; let Anim Notifies request attack windows while authoritative gameplay or ability code validates targets, prevents repeated hits, and owns damage. Define physics, movement, animation, and network update order plus activation or sleeping rules for expensive Chaos bodies. Add automation tests for tunneling, frame-rate variation, slopes, stairs, corners, moving platforms, doors, overlap recovery, repeated hits, replication or reconciliation, 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, quests, notifications, loading, failure, victory, confirmations, and accessibility screens required by the approved game. Use UMG, CommonUI, Common Input, Slate, or the project's established stack deliberately. Separate game state, screen presentation, navigation, and reusable widgets, and avoid one giant Widget Blueprint or all-purpose UI Subsystem.

Create reusable style assets and widget classes for typography, spacing, icon language, semantic colors, panels, cards, progress bars, input glyphs, focus indicators, and large buttons. Define normal, hovered, focused, pressed, disabled, selected, busy/loading, error, and cooldown states where applicable. Require one clear primary action per screen, progressive disclosure, context-sensitive actions, short 150–300 ms transitions, immediate visual/audio feedback, predictable gamepad navigation, no focus dead ends, back/cancel behavior, touch-safe targets where supported, safe zones, localization expansion, text scaling, contrast, reduced motion, and resolution/aspect-ratio support.

Add automation tests for widget ownership, activation and deactivation, focus restoration, Common Input method changes, button states, repeated input, modal stacking, safe zones, localization, supported resolutions, and every critical menu path. The result must use the approved game art direction and must not look like default UMG, a launcher, or a generic web dashboard.

## Required foundation

Create:

- A base GameMode
- A base GameState
- A base PlayerController
- A base PlayerState
- A base Character
- A health component
- An interaction component
- A minimal test map
- A basic GameInstance or more appropriately scoped Subsystem
- Developer settings for configurable project values

If multiplayer is enabled, clearly separate server-authoritative logic from client presentation. Document which properties and events replicate and which class owns each piece of trusted state.

## Documentation

Create:

- README.md
- Docs/ARCHITECTURE.md
- Docs/CPP_AND_BLUEPRINTS.md
- Docs/GAMEPLAY_FRAMEWORK.md
- Docs/CONTENT_ORGANIZATION.md
- Docs/ASSET_MANAGEMENT.md
- Docs/NETWORKING.md
- Docs/ADDING_A_FEATURE.md
- Docs/AI_INSTRUCTIONS.md

AI_INSTRUCTIONS.md must explain C++ and content naming conventions, module dependency rules, when to use Actor Components, Subsystems, or Data Assets, what belongs in C++ versus Blueprints, replication and authority rules, testing requirements, and how architectural decisions are documented.

## Definition of done

Add an automated test for at least one foundational system. The project must compile and open the minimal test map without errors.

Do not add complete gameplay until the base classes, modules, 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.