Build a better game with the right AI prompts.

# Task: Design and implement a best-in-class onboarding flow for the approved game

You are a senior game designer, gameplay engineer, UX designer, accessibility specialist, behavioral researcher, and retention analyst.

Use the approved game design and the current playable build. Do not invent a different game, replace the core loop, or create a disconnected tutorial that teaches mechanics the real game does not use.

## Project context

- Current onboarding state: [NOT BUILT / PARTLY BUILT / BUILT BUT NEEDS IMPROVEMENT / INSPECT PROJECT]
- Intended players: [TOTAL NEWCOMERS / GENRE FANS / CHILDREN / MIXED AUDIENCE / INSPECT AND RECOMMEND]
- Target platforms and input devices: [WEB + KEYBOARD / MOBILE + TOUCH / CONSOLE + GAMEPAD / MULTIPLE / INSPECT PROJECT]
- Onboarding entry point: [FIRST LAUNCH / TUTORIAL LEVEL / CHARACTER CREATION / EXISTING GAME FLOW / INSPECT PROJECT]
- Account or store requirement before play: [NONE / SIGN-IN REQUIRED / STORE OR PURCHASE REQUIRED / UNKNOWN]
- Preferred tutorial length: [UNDER 2 MINUTES / 2-5 MINUTES / 5-10 MINUTES / RECOMMEND BASED ON GAME]

## Read and audit first

Before proposing changes:

1. Read the game design, mechanics, core loop, architecture, controls, accessibility, analytics, save, progression, economy, and platform documentation.
2. Play or inspect the first playable build from launch until the core loop repeats. Record the time to first input, first meaningful action, first feedback, first success, first failure risk, and entry into the real game.
3. Inventory every mechanic and movement skill the player truly needs for the first session. Separate required locomotion, camera, traversal, combat, interaction, or vehicle knowledge from systems that can be introduced later.
4. Audit collision along the onboarding path for invisible blockers, snagging corners, incorrect interaction ranges, missed or repeated hits, unsafe spawn overlaps, moving-platform failures, misleading visual contact, or tutorial gates that can be bypassed or become impossible because collision and animation disagree.
5. Inspect the current tutorial, UI, prompts, level flow, checkpoints, account gates, cinematics, permissions, store screens, and failure states.
6. Audit the first-session HUD, menus, prompts, and buttons as game UI. Identify website-like layouts, tiny targets, unclear primary actions, text-heavy explanations, missing focus or pressed states, controller dead ends, inconsistent icons or colors, excessive clicks, modal stacking, weak feedback, and UI that hides the game world unnecessarily.
7. Identify where a new player could become confused, overloaded, blocked, punished before learning, or asked to read instead of play.
8. State assumptions when information is missing. Ask for a decision only when it would materially change the approved game or a business requirement.

## Onboarding principles

- Reach a satisfying player-controlled action within the first 30–60 seconds.
- Teach through doing and level or encounter design before using explanatory text.
- Introduce one concept at a time, allow safe practice, and then combine it with earlier concepts.
- Never punish the player for a mechanic that has not been taught and reinforced.
- Keep prompts contextual, action-oriented, non-blocking, and no longer than two short lines.
- Deliver an early genuine win with clear visual, audio, and game-state feedback.
- Reveal HUD, currencies, menus, progression, social features, and advanced systems only when they become useful.
- Save or checkpoint aggressively during the first session so crashes, exits, and mistakes do not erase early progress.
- Provide a clear skip path and adapt to skill signals such as correct inputs before instruction or unusually fast completion.
- Delay sign-in, permissions, monetization, and store friction until after the player experiences the core fun unless a documented requirement makes that impossible. Call out the trade-off when it cannot be delayed.
- Support keyboard, controller, touch, remapping, localization, reduced motion, color-vision needs, hearing needs, motor needs, and readable cognitive load as required by the target platforms.

## Create or update the onboarding specification

Document:

1. A beat-by-beat first-session flow from launch until the player is participating in the real core loop.
2. A detailed first-60-seconds sequence showing what the player sees, does, learns, and receives as feedback.
3. A first-10-minutes timeline, adjusted when the game's natural session is shorter.
4. A mechanic-teaching table with the mechanic or movement skill, prerequisite, teaching method, animation and feedback cues, safe practice, reinforcement, mastery signal, and fallback hint.
5. The early win, short-term objective, first meaningful choice, first safe failure, and transition out of onboarding.
6. The UI reveal, checkpoint/save, accessibility, skip, replay, and adaptive-assistance rules.
7. The game-menu and button direction for the first session: information hierarchy, icons, input glyphs, primary actions, large targets, focus order, back behavior, all required interaction states, immediate feedback, short transitions, and how the visual treatment matches the approved game rather than a website.
8. Every tutorial message, button prompt, voice line requirement, highlight, and environmental teaching cue.
9. Risk flags for likely confusion, churn, difficulty spikes, control problems, account friction, and platform-specific issues.
10. An analytics funnel covering onboarding start and completion, time to first input/action/success, each teaching beat, hints, retries, deaths, skips, menu abandonment, repeated selections, drop-off points, session length, and return behavior.

## Implement the approved flow

Do not stop after writing the specification.

1. Implement the onboarding inside the real game flow using the project's existing architecture, input, UI, save, analytics, localization, and accessibility systems.
2. Prefer environmental setup, encounter design, readable locomotion and animation, audio, and immediate feedback over modal instructions. Use anticipation, poses, contacts, VFX, camera, and sound to make movement goals and successful inputs understandable.
3. Use the real gameplay collision model in onboarding rather than tutorial-only shortcuts. Keep colliders separate from visual meshes, use forgiving but honest interaction and hit volumes, and ensure animation events cannot independently award hits or progression.
4. Ensure tutorial prompts never stack, unexpectedly steal focus, block needed input, or reappear after completion unless the player requests a replay.
5. Implement first-session menus and buttons with the approved game UI style, recognizable icons, minimal text, one clear primary action, large targets, complete focus/pressed/disabled/selected/busy states, immediate visual/audio feedback, controller navigation without dead ends, touch and mouse parity, reliable back behavior, safe areas, localization, text scaling, contrast, and reduced-motion support.
6. Add progressive disclosure so unavailable or irrelevant systems do not compete for attention.
7. Add safe practice, reinforcement, recovery, checkpoints, skip/replay controls, and adaptive shortening for experienced players.
8. Instrument stable events for every important funnel step without collecting unnecessary personal information.
9. Preserve the approved mechanics, difficulty intent, narrative tone, visual language, and core-loop pacing.

## Verify with real behavior

Test at minimum:

- A completely new player path with no prior knowledge.
- A returning or experienced player who skips or demonstrates mastery early.
- Every required keyboard, controller, and touch path.
- Every first-session menu and button state, including input-method switching, focus restoration, back/cancel, rapid repeated input, modal stacking, supported resolutions, safe areas, localization, and readable couch or mobile distance.
- Required locomotion, camera, traversal, combat, interaction, or vehicle teaching paths, including incorrect or interrupted inputs.
- Collision behavior along the full teaching path, including walls, corners, slopes, stairs, doors, moving platforms, triggers, hitboxes, hurtboxes, projectiles, overlap recovery, frame-rate variation, and repeated-hit prevention where applicable.
- Animation readability, transition timing, foot or contact placement, feedback synchronization, and reduced-motion behavior where applicable.
- Failure, retry, quit, crash/reload, checkpoint, and resume behavior.
- Accessibility settings and readable prompts at supported resolutions and text sizes.
- Slow completion, ignored hints, unexpected inputs, and players who explore out of sequence.
- Analytics events and funnel ordering without duplicate events.
- Time to first fun, time to first success, onboarding completion time, and entry into the repeatable core loop.

## Required final report

Provide the implemented first-session flow, mechanic-teaching table, skip/adapt logic, risk mitigations, analytics funnel, tests and measurements, known limitations, before-and-after timing where available, and the exact next playtest questions. List every code, content, analytics, test, and documentation file changed.

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

## Internationalization and localization implementation

Implement the approved internationalization architecture as part of this work rather than leaving localization for a later rewrite.

- Route every new or changed player-facing string through stable translation keys and locale resources, including HUD, menus, buttons, tutorials, objectives, dialogue, item and ability descriptions, errors, loading/save/reconnect states, accessibility text, subtitles, and notifications.
- Use locale-aware pluralization and formatting. Keep save data, network messages, analytics event names, content IDs, achievements, and gameplay rules language-independent; attach the active locale as metadata only where it is useful and privacy-safe.
- Preserve the selected language across sessions and support safe runtime switching where the platform allows it. Fall back predictably when a translation, font glyph, subtitle, voice line, or localized asset is missing.
- Verify text expansion, wrapping, truncation, responsive layout, safe areas, button and card sizing, controller focus, touch targets, subtitle timing, localized audio fallback, font and atlas memory, CJK text, diacritics, right-to-left mirroring and mixed-direction text, and IME/text entry where applicable.
- Run pseudolocalization and representative real-locale tests across supported resolutions and input methods. Player-facing output must remain natural, readable, visually native to the game, and free of raw translation keys or developer diagnostics.

Update the existing localization documentation and report supported, partially supported, fallback-only, and untested locales honestly.

## Analytics implementation requirement

Use the approved analytics taxonomy and centralized analytics interface while implementing this game work. Before adding or changing a mechanic, screen, onboarding beat, progression step, success/failure state, or recovery path, identify its required events and acceptance evidence in the coverage matrix.

Emit stable language-independent event names with validated properties, build/version and platform context, input method where useful, and privacy-safe locale metadata. Prevent duplicates and preserve event order. Analytics must be asynchronous and failure-safe: blocked consent, offline play, provider failure, or a full queue must not break gameplay, input, saves, networking, loading, or UI.

Add automated tests for the new event paths and verify representative sessions in the development validation view and approved provider tools. Update the coverage matrix and analytics documentation with implemented, deferred, and untested events.

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