Shipping Crate
A procedural shipping crate through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.
showcase/mine-cart/
A procedural narrow-gauge mine cart on a rail segment — riveted steel tub with a rolled lip heaped with ore, timber frame, four flanged wheels on two axles, two 30 lb rails spiked to sleepers in ballast — through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.
Rendered headless by the showcase piece itself. Select it to enlarge.
category Village
blender --background --python showcase/mine-cart/mine_cart.py --
A narrow-gauge mine cart on a rail segment: a riveted steel tub with a rolled lip, a base strap, ten stiffener ribs and an iron grab bar on each end, heaped with a load of iron ore, carried on two timber sills and two buffer beams with a coupling ring at each end; four flanged wheels on two axles running in four iron axle boxes; and the track it stands on, two 30 lb rails on tie plates, held by dog spikes to four sleepers bedded in ballast. A showcase piece, not an example — it witnesses no API contract. It asserts that generated geometry meets declared asset budgets, recomputed from the finished mesh.
| Shipped content | Used for |
|---|---|
skills/mesh-editing-and-bmesh | lathed wheels and rivets, swept rail sections, rolled lip, base strap, grab bars and coupling rings, chamfered boxes, all in one bmesh, chamfered with bmesh.ops.bevel |
skills/custom-properties | face attributes read back by the audits (Part) and the shaders (WoodTone, Grime, Ore); a per-vertex GrainCo vector that gives each timber member its own grain space |
skills/procedural-materials-and-shaders | red-oxide paint, sun-faded toward the rim, chipped to bare steel at the rim and foot, with run-off rust and shallow dents; mill-scaled iron with crisp rust scabs and the railheads and treads polished where they run; creosoted sleepers and weathered oak whose growth rings, fibre and drying checks follow each member's long axis; two sizes of crushed-stone ballast, and fist-sized ore lumps with hematite-red faces and the odd glint |
skills/bake-high-to-low | Cycles tangent-space normal bake, the 48-segment wheels onto the 24-segment low |
skills/engine-export-presets | Unity glTF (export_yup=True) |
skills/depsgraph-and-evaluated-data | evaluated triangle counts for the LOD ratios |
snippets/decimate_to_budget.py | LOD1 / LOD2 COLLAPSE chain |
snippets/convex_hull_collider.py | a hull per wheel, rail and sleeper, plus the ballast, tub and frame, merged into a compound |
snippets/lod_chain.py | LOD naming and ratio pattern |
examples/mesh-hygiene-audit | hygiene combinatorics (copied, not imported) |
A cart on rails has one job the mesh can fail without looking wrong: it has to run on the track. A wheel hovering a few millimetres over its railhead, an axle yawed a degree and a half, or a wheel set spread so its flanges sit inside the railheads all fit the bounding box and pass every hygiene check. The piece measures, off the finished mesh, per wheel:
atan2; acos of a cosine this close to 1 reads float32 noise as 0.01°). Measured 0.0000°.Declared in the script as named constants, recomputed from the generated mesh.
| Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) |
|---|---|---|
| Base triangles | 12600–14200 | 13396 / 13396 / 13396 |
| LOD1 ratio | 0.32–0.62 | 0.5000 / 0.5000 / 0.5000 |
| LOD2 ratio | 0.10–0.35 | 0.2199 / 0.2199 / 0.2125 |
| Material slots | exactly 4, distinct | 4 / 4 / 4 |
| Steel / iron / timber / ballast faces | ≥ 700 / 4400 / 180 / 1150 | 816 / 5104 / 208 / 1228 on all three |
| UV bounds | inside 0..1 | (0.0005, 0.0005)–(0.9995, 0.9995) |
| UV AABB overlap | ≤ 1e-5 | 0.000000 |
| Outer AABB | 2.400 × 1.500 × 1.152 m ± 0.020 | 2.4000 × 1.5000 × 1.1516 on all three |
| Collider triangles | ≤ 1700 | 1570 (13 hulls) on all three |
| Normal bake | {'FINISHED'} with image data | {'FINISHED'}, has_data=True |
| glTF export | file written, non-empty | 1073556 bytes on all three |
| Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) | ||
|---|---|---|---|---|
| Loose verts / edges | 0 / 0 | 0 / 0 | ||
| Non-manifold edges | 0 | 0 | ||
| Zero-area faces | 0 | 0 | ||
| Doubles (1e-5 m) | 0 | 0 | ||
| N-gons | 0 | 0 | ||
| Coplanar cross-shell pairs | 0 | 0 | ||
| Grounded zmin | \ | zmin\ | ≤ 1e-4 | 0.00000 |
| Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) |
|---|---|---|
| Parts | 4 wheels, 2 rails, 2 axles | as stated |
| Wheel seat (tread low point − rail top) | −1.5..+0.5 mm, every wheel | −0.50 mm, every wheel |
| Flange depth below the rail top | ≥ 12 mm | 20.50 mm |
| Flange clearance to the railhead | 3–10 mm, every wheel | 6.00 mm, every wheel |
| Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) |
|---|---|---|
| Axles square to the rails | ≤ 0.10° | 0.0000° |
| Wheelbase | 0.600 ± 0.003 m | 0.60000 |
| Track gauge | 0.600 ± 0.001 m | 0.60000 |
| Rail height | 0.079 ± 0.001 m | 0.07900 |
| Wheel tread diameter | 0.360 ± 0.004 m | 0.36000 |
Real-world size: a 600 mm (24 in) gauge tub on 30 lb rail, the common narrow-gauge mining track. The tub is 1.30 × 0.85 m at the lip and its top stands 1.05 m above the ground, 0.84 m above the rail (the heaped ore crowns at 1.15 m), inside the range IS 8066 gives for 600 mm gauge mine cars; 0.36 m wheels on a 0.60 m wheelbase.
Ore face attribute.GrainCo, its own (across, across, along) coordinates with the pith set 0.12–0.30 m off the piece, so growth rings show as flat-sawn arches on the long faces and as arcs on the ends, and fibre and drying checks run with the member, never across it. The first pass read the grain in object space, squeezed along Z: horizontal members showed it as a woven crosshatch.acos(d.y / |d|), read 0.0102° on a mesh whose wheel centres were exact: float32 vertex noise near a cosine of 1. It is now atan2 of the off-axis and on-axis components, and reads 0.0000°.--wide-gauge failed the seat (the flange is lower than the tread and had moved over the head) and the wheel size, never reaching the clearance it was built to break. The tread is now the vertices within the tread radius, so the falsifier lands on 20.| Convention | Applies | How |
|---|---|---|
| Deterministic, budgets declared, assertions recompute | yes | no RNG (the ballast jitter is a fixed hash); every value above is read off the mesh |
| Falsifier fails the budget it targets | yes | table below, proven on 4.5.11, 5.1.2 and 5.2.1 |
| Hygiene incl. cross-shell coplanar | yes | exit 15 |
| Plumb and real-world size | yes | axle squareness, wheelbase, gauge, rail height, wheel size; exit 19 |
| A member is tenoned into its seat | yes | rails into plates into sleepers into ballast, spikes into sleepers, boxes into sills, tub into sills, axles into hubs, ribs into walls |
| Seat conformance (a band: minimum so it cannot float) | yes | every wheel's tread on its railhead (--float-wheel) |
| Mirrored assemblies | yes | wheel sets measured pairwise: squareness and clearance per wheel |
| Material face floors | yes | steel 700, iron 4400, timber 180, ballast 1150 |
| One substance, one slot | yes | painted steel, iron, timber, ballast |
| Shading is part of the model | yes | wheels, axles, rivets, grab bars and rings smooth, every edge over 35° hard; boxes faceted |
| Edge treatment | yes | sleepers, plates, spike heads, sills, beams, boxes, ribs chamfered; the right-angle edge fraction is 0.077 |
| Sort bmesh operator inputs | yes | the bevel's edge list is sorted by index |
| The bake cage is narrower than the nearest neighbour | yes | CAGE_EXTRUSION 0.01 m |
| Level on the stage; stage 60 m | yes | turned about Z only; 60 m floor and wall |
| Keep a falsifier's envelope still | yes | no falsifier moves the AABB |
Each breaks one pipeline stage so a named budget fails. All six were run on Blender 4.5.11, 5.1.2 and 5.2.1 and exited the declared code.
| Flag | Target budget | Breaks | Exit |
|---|---|---|---|
--skip-decimate | LOD1 ratio | drops the DECIMATE modifiers, LOD1 ratio goes to 1.0000 | 9 |
--stray-vert | mesh hygiene | adds one loose vertex inside the tub | 15 |
--lift-z | grounded zmin | lifts the whole mesh 50 mm | 16 |
--float-wheel | wheel seat | lifts one wheel 6 mm; its tread is 5.50 mm over the rail top | 18 |
--skew-axle | axle squareness | yaws one axle and its wheels 1.5°; measured 1.500° | 19 |
--wide-gauge | flange clearance | sets every wheel 12 mm outboard; the flanges sit 6.00 mm inside the railheads | 20 |
File-local and sequential. 9 is a valid check code. 1 is the FATAL wrapper — a crash, never a named check.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Uncaught exception (FATAL wrapper) |
| 2 | argparse / usage |
| 3 | Mesh did not build, has no UV layer, or a part count is wrong |
| 4 | Base triangle count outside band |
| 5 | Material slots, or a material's face floor |
| 6 | UVs outside 0..1 |
| 7 | UV AABB overlap above tolerance |
| 8 | Outer AABB off declared size |
| 9 | LOD1 or LOD2 ratio outside band (--skip-decimate) |
| 10 | Framing gate (examples/gallery_framing.py, render path only) |
| 11 | Collider triangles above ceiling |
| 12 | Normal bake failed or produced no image data |
| 13 | glTF export missing or empty |
| 14 | --output produced no file |
| 15 | Mesh hygiene (--stray-vert) |
| 16 | Grounded zmin (--lift-z) |
| 18 | Wheel seat or flange depth (--float-wheel) |
| 19 | Axle squareness, wheelbase, gauge, rail height or wheel size (--skew-axle) |
| 20 | Flange clearance to the railhead (--wide-gauge) |
| 21 | Asset-quality floors (examples/gallery_asset_quality.py, render path only; its 11 is this piece's collider code) |
# Budget check, no render. A few seconds warm.
blender --background --python mine_cart.py --
# Falsifier: one wheel hovers 6 mm over its railhead. Must exit 18.
blender --background --python mine_cart.py -- --float-wheel
# Falsifier: every wheel 12 mm outboard. Must exit 20.
blender --background --python mine_cart.py -- --wide-gauge
# Render the gallery still (EEVEE).
blender --background --python mine_cart.py -- --output mine-cart.webp
Smoke runs the check-only path. It does not pass --output or any falsifier.
| Value | 4.5.11 | 5.1.2 | 5.2.1 |
|---|---|---|---|
| Base triangles | 12334 | 12334 | 12334 |
| LOD1 / LOD2 tris | 6166 / 2712 | 6166 / 2712 | 6166 / 2612 |
| Face counts (steel / iron / timber / ballast) | 816 / 5104 / 208 / 622 | same | same |
| Outer AABB | 2.4000 × 1.5000 × 1.0481 | same | same |
| Collider tris | 1532 | 1532 | 1532 |
| Wheel seat / clearance | −0.50 / 6.00 mm | same | same |
| glTF bytes | 990544 | 990544 | 990544 |
DECIMATE COLLAPSE gives LOD2 2612 triangles on 5.2.1 and 2712 on 4.5.11 and 5.1.2; the ratio band holds both.