|
| 1 | +# AI Asset Pipeline Template |
| 2 | + |
| 3 | +A working starter for a headless Blender job that takes a GLB in and |
| 4 | +writes an engine-ready LOD set plus optional collider. Provider-agnostic: |
| 5 | +the input is a file path, not a generation vendor. |
| 6 | + |
| 7 | +## Usage |
| 8 | + |
| 9 | +```powershell |
| 10 | +blender --background --python pipeline.py -- ` |
| 11 | + --input .\source.glb ` |
| 12 | + --outdir .\out ` |
| 13 | + --preset unity ` |
| 14 | + --lod-budgets 1024,256,64 ` |
| 15 | + --collider convex |
| 16 | +``` |
| 17 | + |
| 18 | +Linux / macOS: |
| 19 | + |
| 20 | +```bash |
| 21 | +blender --background --python pipeline.py -- \ |
| 22 | + --input ./source.glb \ |
| 23 | + --outdir ./out \ |
| 24 | + --preset unity \ |
| 25 | + --lod-budgets 1024,256,64 \ |
| 26 | + --collider convex |
| 27 | +``` |
| 28 | + |
| 29 | +The `--` separator is required. Everything before it is consumed by |
| 30 | +Blender (`--background`, `--python`). Everything after it is forwarded |
| 31 | +to `pipeline.py` as `sys.argv`. |
| 32 | + |
| 33 | +Optional `--draco` enables glTF Draco compression on export. |
| 34 | + |
| 35 | +`--preset` is one of `unity` (Y-up glTF), `godot` (Z-up glTF), `unreal` |
| 36 | +(centimeter glTF: 100x bake then `export_yup=True`). FBX for Unreal lives |
| 37 | +in `snippets/export_preset_unreal.py`; this template emits GLB so a CI |
| 38 | +job can check the `glTF` magic bytes the same way for every preset. |
| 39 | + |
| 40 | +## What it does |
| 41 | + |
| 42 | +1. Parses script-side args after `--`. |
| 43 | +2. Imports the GLB into an empty scene. |
| 44 | +3. Checks scene units (metric meters), applies object rotation/scale, |
| 45 | + sits the origin on the lowest Z, recalculates face normals, and |
| 46 | + prints the evaluated triangle count. |
| 47 | +4. Builds an LOD chain from `--lod-budgets`. |
| 48 | +5. Optionally builds a convex hull or AABB box collider. |
| 49 | +6. Exports each LOD (and the collider) under the chosen engine preset. |
| 50 | +7. Returns explicit exit codes so a CI pipeline can detect failures. |
| 51 | + |
| 52 | +Cleanup order follows `ai-mesh-cleanup`. LOD, collider, and export |
| 53 | +helpers are duplicated from the snippets named in `pipeline.py`'s |
| 54 | +header; templates are not a package. |
| 55 | + |
| 56 | +## Exit codes |
| 57 | + |
| 58 | +Same convention as `templates/headless-batch-script-template/` |
| 59 | +(`script.py` / its README: 0 success, 2+ distinct failure modes; |
| 60 | +argparse usage errors also exit 2). Not a repo-wide table; examples such |
| 61 | +as `export-preset-axis` number their own checks independently. |
| 62 | + |
| 63 | +| Code | Meaning | |
| 64 | +| --- | --- | |
| 65 | +| 0 | Success | |
| 66 | +| 2 | Input file missing, or argparse rejected the flags (including an unsupported `--preset`) | |
| 67 | +| 3 | Input is not a readable GLB (bad magic or import failure) | |
| 68 | +| 4 | `--lod-budgets` missing, non-positive, or not strictly decreasing | |
| 69 | +| 5 | Import produced no mesh | |
| 70 | +| 6 | `outdir` is not a directory, or glTF export failed / wrote no file | |
| 71 | + |
| 72 | +## Expected environment |
| 73 | + |
| 74 | +- Blender on the system `PATH` (or invoked by absolute path). |
| 75 | +- `--outdir` already exists. The script does not create it. |
| 76 | +- `--input` is a GLB with at least one mesh. With no meshes the script |
| 77 | + returns exit code 5. |
| 78 | + |
| 79 | +## Common gotchas |
| 80 | + |
| 81 | +- **Forgetting the `--`**. Blender treats the following args as its |
| 82 | + own and complains. The script never sees them. |
| 83 | +- **Output path with spaces on Windows**. Quote the whole path: |
| 84 | + `--outdir ".\out folder"`. |
| 85 | +- **Running without `--background`**. The script still works, but |
| 86 | + Blender opens a UI window and stays open after the script finishes. |
| 87 | + Use `--background` for unattended runs. |
| 88 | +- **Unreal mutates selected meshes** (100x scale bake). Each export |
| 89 | + selects one object. Do not re-export the same object as Unity afterward |
| 90 | + without restoring scale. |
| 91 | +- **Operators that need a 3D Viewport context**. Some operators only |
| 92 | + work when a `VIEW_3D` area exists. In headless mode, none does. |
| 93 | + Either rewrite using `bpy.data.*`, or fabricate a window+area via |
| 94 | + `temp_override` (advanced; see the `headless-batch-scripting` skill). |
| 95 | + |
| 96 | +## Extending the template |
| 97 | + |
| 98 | +This template covers one pipeline (import, clean, LOD, collider, export). |
| 99 | +For more complex workflows, factor each step into its own function and |
| 100 | +return early with distinct exit codes. The `main()` function is the |
| 101 | +orchestration point; everything else should be pure helpers. |
| 102 | + |
| 103 | +## See also |
| 104 | + |
| 105 | +- Skill `ai-mesh-cleanup` for the cleanup order. |
| 106 | +- Skill `engine-export-presets` for Unity / Godot / Unreal axis and units. |
| 107 | +- Skill `headless-batch-scripting` for the full pattern catalog. |
| 108 | +- Rule `prefer-temp-override-over-context-copy` for why we avoid |
| 109 | + `bpy.context.copy()`. |
| 110 | +- Snippet `lod_chain.py`, `convex_hull_collider.py`, `export_preset_unity.py`. |
0 commit comments