unity-3d-to-sprite-baker: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Codex, Cursor, GitHub Copilot, Claude Code, Windsurf, Aider, Zed, and others) working in this repository or wiring this tool into another project. Humans: this is a fast, accurate map. Deeper docs are linked at the bottom.

What this project is

A drop-in runtime sprite-atlas baker for Unity 6 + URP. It takes any 3D animated character prefab and, at game start, captures every requested clip × frame into a single packed Texture2D atlas via an offscreen orthographic camera + async GPU readback — then plays the atlas back as a flat textured quad that shares one material across every instance. The runtime is six C# files under Assets/SpriteBaker/Runtime/. Namespace: SpriteBaker. License: MIT. Battle-tested in Leap of Legends, whose lowest mobile quality preset bakes every character to a sprite at start (a 60-bone skinned mesh → one flat quad).

Golden rules (do not violate)

1. Baking is a runtime, async, coroutine-driven process — not editor-only and not synchronous. SpriteAtlasBaker.Instance.Enqueue(request) captures one frame per Unity frame; the atlas is NOT ready the same frame you enqueue. Read results with SpriteAtlasCache.TryGet(key, out var atlas); poll SpriteAtlasCache.IsReady(key) / SpriteAtlasBaker.Instance.IsPending(key), or just call AnimatedSpriteRenderer.Bind(key) early — it hides its mesh and re-checks every Update until the bake lands. To re-bake, SpriteAtlasCache.Evict(key) first (a duplicate Enqueue on a ready/pending key is silently dropped).
2. The playback material is URP/Unlit driven from Resources/SpriteBakerAtlasUnlitTemplate.mat, NOT the AtlasCutout.shader. The custom SpriteBaker/AtlasCutout shader ships as a fallback, but the runtime does new Material(template) because a custom URP shader compiled via new Material(shader) renders solid black on WebGL2, and the _ALPHATEST_ON variant is stripped from the build unless a serialized .mat carries the keyword. Do not "simplify" this to new Material(Shader.Find("SpriteBaker/AtlasCutout")) — that reintroduces the WebGL black-quad bug. Copy the whole Assets/SpriteBaker/ folder (including Editor/ and the .mat), not just Runtime/.
3. Render via URP's SingleCameraRequest, not Camera.Render(). Camera.Render() happens to work on D3D11 in the editor but is a no-op on WebGL2 URP, producing an empty/black atlas. The baker uses RenderPipeline.SubmitRenderRequest(cam, new UniversalRenderPipeline.SingleCameraRequest { destination = rt }).
4. Every bake needs a capture-stage light rig. The prefab is instantiated at ~(2000, 2000, 0), far from any scene light; a URP/Lit character there renders solid black without the key + fill + ambient rig the baker spawns (each light needs UniversalAdditionalLightData, or WebGL's URP silently drops it). Use CaptureLighting.Default, or set DisableDefaultRig and stage your own in PreCaptureCallback.
5. CaptureRotation composes onto the prefab's authored rotation (it is not a replacement). Quaternion.identity means "natural orientation." Kenney AC2 rigs need Quaternion.Euler(0, 180, 0); Mixamo uses identity. For rigs whose animation curves bind relative to a child transform, set SampleAnimationTargetPath (e.g. "Root" for Kenney AC2, "Armature" / "Hips" for Mixamo) or the loose-clip bake captures bind pose.
6. The per-frame yield return null in the bake loop is load-bearing. It lets Unity's skinning (LateUpdate) re-pose the mesh between captures; remove it and every captured frame shows the identical pose — a silent bug (the atlas "looks almost right"). Do not "optimize" it away.
7. No using LeapOfLegends.* or other product-specific imports. New runtime code lives in the SpriteBaker namespace only; demo-only code lives under SpriteBaker.Demo.