Symptom first. Each entry gives the likely cause and the fix.
Note for publishing: 📷 blocks are screenshot placeholders — replace each with the image when publishing to Notion. Full list in
Screenshot_Capture_List.md.Troubleshooting benefits more from images than any other document here: a user arrives having seen something wrong, and matches pictures far faster than prose. Prioritise these captures if capture time is short.
Run Bake Doctor. It runs the same checks as the hard pre-bake gate, reports offender counts, and lets you click straight to the elements at fault. Most of what follows is faster to diagnose there than by eye.
📷 TRB-04 — Bake Doctor as a first step The window mid-diagnosis on a failing asset, with
Select in Sceneabout to be used and the offending elements highlighted in the viewport behind. Why: the whole document reduces to “run this first”; showing the click-to- element flow makes that concrete.
Read the bake report. Every bake writes a JSON report under
Assets/EQPivotPainterLab_Generated/Reports. It records element counts, level
distribution, triangle coverage, warnings and which solver path ran.
The gate refuses rather than writing data that would produce broken motion. Each refusal names the offending elements.
| Message | Cause | Fix |
|---|---|---|
| Triangles owned by more than one element | Detection assigned the same triangle twice | Re-detect; if it persists, change detection mode |
| Coverage below 98% | Some triangles belong to no element | Re-detect, or use Split By Island on the leftovers |
| Hierarchy cycle | An element is its own ancestor, usually after manual re-parenting | Select the named elements and Clear Overrides, then re-solve |
| Self-parenting | An element was parented to itself | Same as above |
| Chain deeper than the shader replays | Manual re-parenting built a chain longer than 3 hops | Re-parent the named element closer to the root |
| More than 30,000 elements | The mesh partitioned into too many pieces | Use a coarser detection mode, or raise the minimum element size |
This is deliberate. A refused bake is the tool declining to produce a subtly broken result. Do not work around it by relaxing settings until it passes — fix what it named.
Detection produced a single element. Check the element list — if it shows 1, detection did not split anything. Try a different detection mode; for a dense one-mesh tree use Skeleton First (RGS-PA).
Most elements landed on the same hierarchy level, so they all share one wind tier. Check the level distribution in the report. On dense disconnected foliage the spatial scaffold should produce a spread across levels — if nearly everything is on the deepest level, re-detect with Skeleton First.
📷 TRB-02 — Reading the level distribution The Report panel with the level counts visible, on a healthy solve and on one where nearly everything landed on the deepest level. Highlight the numbers that matter. Why: teaches users to diagnose this from the report rather than by staring at motion, which is the faster and more reliable route.