Build a better game with the right AI prompts.

# Task: Analyze the existing game's audio and video delivery system

You are a senior game audio programmer, media pipeline engineer, and performance engineer.

Do not immediately start changing files.

First inspect the entire existing project and determine:

1. Which game engine or framework is being used.
2. Which platforms are currently supported: web browsers, iOS, Android, Windows, macOS, Linux, and consoles where applicable.
3. How audio and video are currently loaded and played.
4. Where audio and video assets are stored.
5. Whether the project already has an audio manager, sound manager, media manager, asset loader, resource manager, streaming system, cache, or pooling system.
6. Whether media uses synchronous loading, asynchronous loading, streaming, preloading, lazy loading, or a combination.
7. Which assets are compressed and which are uncompressed.
8. Which audio files are mono versus stereo.
9. Which assets are short sound effects versus long-form audio.
10. Which assets are music, dialogue, ambience, UI sounds, combat sounds, environmental sounds, cinematics, or other categories.
11. Whether audio sources or voices are pooled or created dynamically.
12. Whether there is a maximum simultaneous voice or channel limit.
13. Whether duplicate sounds can play unnecessarily.
14. Whether the game performs distance culling, priority management, occlusion, virtualization, or audio LOD.
15. How CDN, server, and static-asset delivery work.
16. Whether HTTP caching is configured.
17. Whether assets are versioned or content-hashed.
18. Whether the game has an existing loading screen or asset-loading pipeline.
19. Whether fallback behavior exists when a media format cannot be decoded.
20. What profiling, automated tests, and platform validation already exist.

## Map the sound effects the game needs

Read the approved game design, mechanics, core loop, movement and animation audit, onboarding plan, environments, UI flows, progression, combat, interactions, vehicles, and accessibility requirements. Do not limit the audit to sound files that already exist.

Create a proposed sound-effects map for the complete approved game. Include only relevant categories, such as:

- Player locomotion: footsteps by surface, starts, stops, jumps, landings, slides, climbs, swimming, impacts, clothing, equipment, and exertion.
- Character, creature, combat, and ability actions: anticipation, attacks, blocks, parries, hits, misses, damage, healing, death, status changes, powers, weapons, projectiles, and recoil.
- Interaction and object sounds: pickups, doors, levers, containers, crafting, inventory, equipment, machines, mechanical parts, destruction, and physics contacts.
- Vehicles and movement systems: engines, thrusters, acceleration, braking, turning, suspension, landing gear, collisions, wind, and travel-state transitions.
- Environment and world: weather, ambience, hazards, wildlife, crowds, machinery, room tone, location identity, and reactive environmental layers.
- UI and onboarding: focus, hover, select, confirm, cancel, errors, rewards, objectives, tutorials, accessibility cues, menus, notifications, and progress feedback.
- Narrative, progression, and economy: dialogue support, quest updates, discoveries, unlocks, level-ups, purchases, currencies, achievements, victory, failure, and save or checkpoint feedback.

For every proposed sound or reusable sound family, record:

Sound or family | Gameplay event and trigger | Player information conveyed | 2D or 3D | Surface/state variants | Variation and anti-repetition plan | Priority | Concurrency limit | Distance/occlusion/virtualization | Sync with animation/VFX/camera/haptics | Source or creation method | Loading strategy | Owning system | Required, optional, or deferred

Identify missing sounds, redundant sounds, opportunities to reuse a designed family safely, and places where silence is the stronger choice. Separate verified existing assets from recommended new assets and do not claim a sound has been created when it has only been proposed.

## Map the music loops the game needs

Create a proposed music map from the approved fantasy, core loop, session structure, locations, narrative beats, progression, difficulty, onboarding, and expected session length. Include only relevant uses, such as title and menu music, onboarding, exploration, safe areas, tension, combat intensity tiers, bosses, puzzles, building or planning, dialogue, discoveries, rewards, victory, failure, credits, and location or faction themes.

For every proposed cue, loop, or adaptive music family, record:

Music cue or family | Player state or scene | Emotional and gameplay purpose | Approximate loop length | Intro and outro needs | Loop point | Layers, stems, or intensity tiers | Horizontal or vertical transitions | Trigger and exit rules | Beat/bar synchronization needs | Stinger or transition cues | Ducking and dialogue behavior | Variation and repetition plan | Loading or streaming strategy | Platform fallback | Required, optional, or deferred

Explain which moments need a seamless loop, a one-shot cue, an adaptive layered score, a location theme, a short stinger, ambience instead of music, or deliberate silence. Flag loops that would become repetitive during the expected session length, and propose variation, rest periods, alternate arrangements, or state-driven layering. Separate verified existing music from recommended new composition and do not claim a track exists when it has only been proposed.

Do not replace an existing architecture simply because you would design it differently. Work with the current architecture unless there is a clear technical reason to change it.

## Required report

Create or update a persistent AUDIO_VIDEO_OPTIMIZATION.md document containing:

- Current architecture
- Current problems
- Audio asset inventory
- Proposed sound-effects map derived from the approved game design
- Missing, redundant, reusable, optional, and deferred sound families
- Proposed music-loop and adaptive-score map derived from the approved game and session structure
- Missing cues, loop families, stems, transitions, stingers, variation needs, and intentional-silence decisions
- Video asset inventory
- Current formats
- Recommended formats
- Recommended compression
- Recommended loading behavior
- Recommended caching behavior
- Recommended memory strategy
- Recommended simultaneous voice limits
- Recommended audio pooling strategy
- Recommended platform-specific differences
- Recommended fallback formats
- Expected download-size improvements
- Expected memory improvements
- Potential CPU and decode costs
- Potential compatibility problems
- Baseline measurements and how to reproduce them

Then propose the smallest set of code and asset-pipeline changes necessary to implement the recommendations.

Do not make implementation changes until the analysis and report are complete.

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