Build a better game with the right AI prompts.

# Task: Audit and implement an optimized game asset pipeline

You are a senior technical artist, rendering engineer, and build pipeline engineer.

## Project context

- Engine or runtime: [UNITY / UNREAL / GODOT / THREE.JS / OTHER]
- Target platforms: [DESKTOP / WEB / IOS / ANDROID / CONSOLE]
- Source assets: [BLENDER FILES OR LOCATION]
- Current asset format: [BLEND / FBX / GLTF / GLB / OTHER]
- Performance targets: [FPS, MEMORY, DOWNLOAD SIZE, LOAD TIME, DEVICE CLASS]

## Audit before changing anything

1. Inspect the engine, platform targets, rendering setup, build process, and current asset pipeline.
2. Find and follow existing folder structures, naming conventions, import presets, and documentation. Create them only if they do not exist.
3. Profile representative scenes and record a baseline for CPU, GPU, memory, download size, load time, draw calls, triangles, materials, texture memory, shaders, bones, animations, lighting, shadows, and visible object counts.
4. Read the movement, animation, collision, visual-quality, and game-UI audits. Inventory skeletons, avatars, retargeting rules, clips, blend shapes, locomotion sets, facial animation, mechanical animation, secondary motion, IK or procedural layers, physics animation, particles, shader animation, event markers, gameplay colliders, hitbox or hurtbox markers, collision layers, UI icons, panels, cards, button states, input glyphs, fonts, atlases, and platform-specific fallbacks required by the approved game.

## Choose the right technologies

- Determine the correct texture compression per platform. For web or glTF workflows, evaluate KTX2/Basis Universal. For native platforms, use the formats best supported by the target devices.
- Determine whether Meshopt, Draco, engine-native mesh processing, or no additional mesh compression is appropriate.
- If the project uses glTF/GLB, evaluate glTF Transform or the project's existing optimization tools.
- If the project uses FBX, prefer the existing engine importer unless another SDK or processor is genuinely required.
- Use the engine's built-in LOD workflow when available. Otherwise, choose an appropriate simplification process.

Do not install tools simply because they are listed here. Justify every choice based on the current project and target platform.

## Implement and verify

1. Create or update the Blender export process and engine import presets.
2. Export and integrate the approved assets, materials, skeletons, animations, collision metadata, and LODs. Do not automatically reuse detailed render meshes as gameplay collision.
3. Implement the approved collision representation separately from the visual asset: use primitive or compound colliders by default, convex hulls only when needed, and triangle-mesh collision only for justified static world geometry. Preserve sockets, markers, or named attachment points needed for hurtboxes, temporary hitboxes, interaction triggers, projectiles, doors, vehicles, ragdolls, or other gameplay systems without baking trusted rules into the art asset.
4. Implement the approved runtime movement and animation pipeline: import and retarget rigs and clips, configure state machines and blend trees, choose root motion or in-place movement deliberately, add IK or procedural correction where required, and connect facial, mechanical, vehicle, secondary, VFX, shader, and physics animation to the appropriate engine systems.
5. Synchronize animation events with authoritative gameplay collision windows, footsteps, impacts, audio, particles, lighting, camera feedback, controller vibration, and network state. Animation may request a hitbox window, but gameplay code must enable, validate, deduplicate, and close it.
6. Verify locomotion speed, starts, stops, turns, transitions, foot planting, slope and stair behavior, contacts, aiming, recoil, traversal, facial timing, mechanical articulation, and secondary motion that apply to the game. Test collision alignment at gameplay distance and under frame-rate variation without forcing colliders to follow every visible polygon or bone.
7. Optimize more than polygon count: address materials, draw calls, texture sizes, shader complexity, bone counts, animation compression and size, active animators, collider count and complexity, collision layers, broad-phase pair counts, IK and physics cost, particles, lighting, shadows, batching, instancing, memory, downloads, and loading.
8. Build a repeatable UI asset pipeline for icons, input glyphs, panels, cards, nine-slice or scalable frames, progress elements, button-state art, fonts, localization variants, atlases, compression, preloading, and resolution or platform fallbacks. Preserve crisp edges, readable text, consistent semantics, and fast state changes without shipping generic default controls.
9. Preserve visual quality and gameplay readability at real gameplay distance.
10. Profile the same scenes again. Do not claim an optimization worked without measured before-and-after evidence.
11. Test representative desktop, web, and mobile targets that the project actually supports.

## Documentation

Document Blender export settings, asset structure, naming, rigs, retargeting, clip and event conventions, root-motion decisions, state-machine and blend-tree ownership, collision primitives and compound shapes, layers and masks, hitbox or hurtbox markers, static-mesh collision exceptions, UI asset and atlas rules, button-state assets, fonts, input glyphs, scalable panels, IK and procedural layers, facial and secondary-motion rules, VFX and audio synchronization, import presets, optimization tools, compression formats, LOD strategy, platform differences, profiling steps, budgets, and regression checks.

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