Build a better game with the right AI prompts.

# Task: Optimize and verify my game for mobile devices

You are a senior mobile game performance engineer, rendering engineer, stability engineer, usability QA engineer, and release owner.

Audit, optimize, and retest [GAME NAME] for real mobile devices. Use measured evidence, preserve working desktop behavior, and distinguish confirmed causes from hypotheses.

## Test context

- Repositories and immutable build: [PATHS, URL, COMMIT, BUILD ID, AND ASSET VERSION]
- Engine or web runtime: [THREE.JS / UNITY / GODOT / UNREAL / OTHER]
- Expected platforms: [IOS / IPADOS / ANDROID / MOBILE WEB]
- Target device classes: [OLDER CONSTRAINED DEVICE AND NEWER CAPABLE DEVICE]
- Target frame rate: [30 / 60 FPS]
- Mobile memory budget: [BUDGET OR ASK AI TO PROPOSE ONE]
- Required soak duration: [10–30 MINUTES OR LONGER]
- Representative gameplay: [EXPLORATION / COMBAT / DIALOGUE / BUILDING / MULTIPLAYER / OTHER]
- Required orientations: [PORTRAIT / LANDSCAPE / BOTH]
- Required network conditions: [WIFI / CELLULAR-LIKE / HIGH LATENCY / OFFLINE / RECONNECT]

## Device and automation setup

1. Prefer physical phones and tablets. Emulators may support preliminary checks but are not proof of memory pressure, thermals, native GPU behavior, touch handling, safe areas, audio compatibility, or lifecycle recovery.
2. Test at least one constrained or older device and one newer capable device when available.
3. For iOS device testing, document Developer Mode and the approved command-line, device-lab, or MCP connection. For mobile web, document Safari Web Inspector and Remote Automation setup when available.
4. For Android, document the approved developer/debug bridge and device connection.
5. Use the project's remote game automation protocol when it exists. Combine semantic game state, screenshots, events, assertions, and real input instead of relying only on image recognition.
6. Use trusted touch or pointer input for acceptance. Do not accept element.click(), synthetic mouse events, source inspection, a screenshot, a health endpoint, or an idle session as proof that gameplay works.

Do not expose production secrets or weaken device, browser, network, or automation security to make testing easier.

## Establish a baseline before changing code

Record the exact build, device, OS, browser/runtime, viewport, device-pixel ratio, orientation, CPU/GPU signals, memory signals, thermal state, and network condition.

Measure representative cold and warm startup, time to first visible frame, time to interactive gameplay, world synchronization, transferred bytes, request count, main-thread stalls, average and percentile frame time, CPU and GPU time, scripting, draw calls, triangles, textures, geometry, lights, audio residency, peak memory, end-of-soak memory, battery or thermal behavior, and failure recovery.

Audit:

- Device detection and mobile-only gating.
- Adaptive quality, render scale, draw distance, shadows, lights, particles, terrain, entities, postprocessing, and frame-rate caps.
- Startup initialization and whether the complete asset catalog is loaded eagerly.
- Texture, model, animation, audio, video, WebAssembly, JavaScript, and service-worker delivery.
- Resource reuse, pooling, culling, LOD, streaming, disposal, and cache limits.
- Touch press, hold, release, cancellation, multi-touch, joystick, camera, hotbar, menus, dialogue, and authoritative gameplay results.
- Portrait, short landscape, safe areas, notches, browser bars, keyboard behavior, and approximately 44 CSS-pixel essential targets.
- Game-menu and HUD hierarchy, controller or external-keyboard focus, touch targets, button states, input glyphs, text scaling, localization expansion, semantic color and icons, transition timing, immediate feedback, and whether the interface still looks like the approved game instead of a responsive website.
- Background/foreground, lock/unlock, orientation changes, WebGL or graphics-context loss, audio interruption, authentication expiry, network loss, WebSocket reconnect, and low-memory recovery.

## Implement the smallest measured fixes

After the baseline and diagnosis, implement prioritized reversible fixes. Depending on the evidence, this may include:

- A smaller mobile memory budget with bounded caches and a stable working set.
- Capability-based adaptive quality instead of one permanent setting for every phone.
- A mobile render cap such as 30 FPS while keeping input, networking, authoritative simulation, and fixed-rate physics responsive.
- Earlier device-pixel-ratio and render-scale limits.
- Reduced draw distance, shadows, lights, particles, effects, terrain radius, entity counts, or postprocessing.
- On-demand asset streaming instead of eager loading of the complete world or media catalog.
- Mobile-appropriate compressed textures, meshes, models, audio, and video with verified fallbacks.
- Lazy, reusable, and reclaimable animation graphs, audio buffers, renderers, previews, and other heavy resources.
- Pools for frequently created effects and gameplay objects.
- Correct touch ownership, cancellation, safe-area layout, short-landscape rules, and lifecycle cleanup.
- Smaller service-worker catalogs, immutable asset URLs, compression, reliable caching, and reconnect behavior.

Do not reduce quality blindly. Change one meaningful variable at a time, perform controlled before-and-after tests on the same device, build, scene, orientation, network, and thermal state, and preserve the primary game fantasy and readability.

## Protect the desktop experience

Mobile optimization must not reduce or unintentionally change the existing desktop experience. Scope mobile-specific layouts, touch controls, safe areas, asset variants, render caps, quality reductions, memory limits, lifecycle behavior, and network fallbacks through explicit platform capability checks, input-mode rules, responsive breakpoints, or mobile configuration—not global defaults that also affect desktop.

Before each change, record the desktop baseline for supported browsers or native builds, resolution and device-pixel ratio, mouse and keyboard behavior, controller behavior where supported, visual quality, UI layout, asset quality, startup and loading, frame time, memory, audio, networking, and representative gameplay. After each mobile change, rerun the same desktop scenarios on the same build and compare against the baseline.

Reject a mobile improvement if it degrades desktop image quality, field of view, render scale, frame rate, draw distance, effects, input latency, controls, menu density, target sizes, hover/focus behavior, aspect-ratio use, asset loading, audio, networking, save compatibility, or gameplay behavior unless a separately approved desktop change explicitly requires it. Share fixes only when they improve every platform; otherwise keep platform-specific behavior isolated and documented.

## Acceptance scenarios

Run at minimum:

1. Cold start and warm reload into real gameplay.
2. Traversal through representative world regions.
3. A dense scene and effects-heavy or multi-enemy gameplay.
4. Dialogue, inventory, settings, and other major UI flows.
5. Every critical menu and button with touch, controller or keyboard where supported: focus order, no dead ends, back navigation, idle/pressed/disabled/selected/busy states, safe areas, text scaling, localization, and rapid repeated input.
6. Trusted touch controls, including press, hold, release, cancellation, and multi-touch where used.
7. Portrait-to-landscape and landscape-to-portrait rotation on physical hardware.
8. Audio start, stop, repeat, interruption, and transition.
9. Background for at least one minute, then resume.
10. Network interruption and recovery.
11. A continuous physical-device soak for the required duration.
12. Desktop regression coverage after the mobile fixes: cold and warm start, representative gameplay, dense/effects-heavy play, mouse and keyboard, controller where supported, major UI flows, audio, networking, save/load, supported resolutions and aspect ratios, and a performance/visual comparison with the recorded desktop baseline.

Report PASS only when the exact build was tested on required physical devices, gameplay was reached, required performance and memory budgets were met, controls produced real game-state changes, layouts were usable, memory remained bounded, lifecycle/network recovery succeeded, and supported desktop experiences showed no unapproved regression. Report untested criteria as NOT TESTED rather than PASS.

## Required final report

Provide the tested build and device matrix, mobile and desktop baseline/final performance tables, memory and thermal observations, startup and asset findings, touch and layout results, desktop visual/input/UI regression results, lifecycle and network results, ranked findings with evidence, controlled before-and-after comparisons, remaining failed or untested gates, likely regressions, platform-scoping decisions, and an exact retest procedure.

## Three.js geometry, draw-call, and rendering performance

If the project uses Three.js, do not treat a triangle count or WebGPU selection as a universal performance guarantee. Establish per-device and per-quality-tier budgets from measured CPU frame time, GPU frame time, frame pacing, draw calls, visible triangles, shader and material cost, overdraw/fill rate, lights and shadows, post-processing, texture bandwidth, uploads, animation/skinning, physics, memory, loading, and JavaScript allocation behavior.

Use these only as initial planning hypotheses before profiling, never as pass/fail claims:

- Visible scene geometry: roughly 100k–500k triangles for constrained mobile, 500k–2 million for mid-range mobile, 2–5 million for capable mobile, 2–10 million for older desktop hardware, and 10–50 million for capable gaming desktops when the rest of the frame is controlled.
- Asset envelopes: characters around 5k–50k triangles, props around 100–5k, buildings around 1k–20k, terrain around 100k–500k visible, and approximately 1–5 million visible triangles for a broadly compatible complete scene.
- Draw calls: below 500 is a strong initial target, 500–1,000 requires observation, 1,000–2,000 has increasing CPU risk, and more than 2,000 requires explicit evidence on the target hardware and renderer backend.

Replace those hypotheses with project-specific measured budgets as soon as representative content exists. A lower triangle scene can still be slower because of expensive pixels, shaders, state changes, transparency, shadows, post-processing, animation, physics, or JavaScript work.

Prefer the smallest measured combination of InstancedMesh, BatchedMesh, merged static geometry, shared geometry/materials, texture atlases or arrays where appropriate, frustum culling, distance and screen-size LOD, spatial partitioning, bounded object pools, selective updates, compressed KTX2/Basis textures, compressed glTF meshes where justified, asynchronous loading, streaming, and explicit resource disposal. Do not merge objects that need independent culling, animation, selection, collision, or material behavior without measuring the trade-off.

Record renderer.info counters and browser/GPU profiler captures for representative quiet, dense, high-motion, transparent, shadow-heavy, particle-heavy, UI-overlay, and post-processing states. Profile WebGPU and WebGL 2 separately; WebGPU can reduce some CPU submission overhead and enable compute or modern rendering features, but it does not repair excessive allocations, physics, pathfinding, poor scene organization, expensive fragment shading, oversized shadows, or unnecessary post-processing.

For every optimization, capture the same build and gameplay route before and after, verify visual and gameplay parity, and report the actual bottleneck moved—not only the triangle count.

## Three.js multi-device rendering quality and fallback paths

If the project uses Three.js, design and implement capability-based rendering quality paths so the same game remains playable and visually coherent across constrained phones, capable phones and tablets, integrated-GPU laptops, older desktops, and high-end desktops.

Define documented Low, Balanced, High, and Ultra profiles when the supported device range justifies them. Each profile must specify measured budgets and explicit settings for:

- Renderer backend and supported feature path, render scale, device-pixel-ratio cap, target frame rate, antialiasing, output-buffer precision, and post-processing.
- Visible triangle and draw-call budgets, LOD distances or screen-size thresholds, object and vegetation density, terrain detail, decals, particles, transparent effects, reflection quality, and draw distance.
- Texture resolution, KTX2/Basis variants, anisotropy, material and shader complexity, normal/detail maps, environment maps, lighting count, shadow count, shadow-map resolution, cascades, contact shadows, and baked versus dynamic lighting.
- Character and object animation quality: rig and bone budgets, skinned-mesh count, animation sampling/update rate, interpolation, blend layers, facial animation, lip sync, IK, secondary motion, cloth, hair, ragdolls, physics reactions, crowd animation, and update-distance throttling.
- Asset residency, streaming, preload scope, memory ceilings, cache limits, geometry and texture disposal, worker use, and recovery from memory or graphics-device pressure.

Build the quality system from centralized data rather than scattered conditionals. Use measured capabilities and runtime performance—not only user-agent strings—to select a safe default. Let players override the choice when practical, persist the setting, explain costly options simply, and support safe automatic degradation with hysteresis so quality does not rapidly oscillate. Recover upward only after sustained headroom and never during a critical gameplay moment without an approved transition policy.

Create real asset, material, animation, and effect fallback paths instead of only disabling everything globally. Preserve silhouettes, art direction, gameplay readability, telegraphs, interaction feedback, hit timing, collision, input response, UI meaning, localization, accessibility, network authority, saves, and deterministic gameplay across every profile. Ultra may add presentation detail, but it must not reveal gameplay information or mechanics unavailable on Low.

Test cold start, representative gameplay, dense/high-motion scenes, menus, particles, transparency, lighting and shadows, animation-heavy scenes, background/resume, resize, orientation change, device/context loss, and live profile switching on representative devices. Capture comparable screenshots and performance traces for every profile and backend. Report unsupported combinations and fall back to the nearest verified path with a player-readable message rather than a blank canvas, crash, or raw error.

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