Mine Cart

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.

witnesses Recomputed: 13396 tris, four materials (steel 816, iron 5104, timber 208, ballast and ore 1228 faces), UVs in 0..1 with zero overlap, a 2.400 × 1.500 × 1.152 m envelope, LOD1 0.5000 and LOD2 0.2125–0.2199, a 1570-tri compound collider, a FINISHED normal bake and a 1074 kB Unity glTF, hygiene all zero with no coplanar cross-shell faces, and the cart actually on its track: every wheel's tread 0.50 mm into its railhead, every flange 20.5 mm below the rail top and 6.00 mm clear of the railhead's inner face, both axles 0.0000° off square, a 0.600 m wheelbase on 0.600 m gauge, 79 mm rail and 0.360 m wheels. --skip-decimate exits 9 on LOD1; --stray-vert exits 15 on hygiene; --lift-z exits 16 on grounded zmin; --float-wheel exits 18 with one tread 5.50 mm over the rail; --skew-axle exits 19 at 1.500°; --wide-gauge exits 20 with the flanges 6.00 mm inside the railheads.

category Village

tags mesh export showcase

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.

What it composes#

Shipped contentUsed for
skills/mesh-editing-and-bmeshlathed 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-propertiesface 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-shadersred-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-lowCycles tangent-space normal bake, the 48-segment wheels onto the 24-segment low
skills/engine-export-presetsUnity glTF (export_yup=True)
skills/depsgraph-and-evaluated-dataevaluated triangle counts for the LOD ratios
snippets/decimate_to_budget.pyLOD1 / LOD2 COLLAPSE chain
snippets/convex_hull_collider.pya hull per wheel, rail and sleeper, plus the ballast, tub and frame, merged into a compound
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)

The budget that matters#

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:

Budgets#

Declared in the script as named constants, recomputed from the generated mesh.

AxisDeclaredMeasured (4.5.11 / 5.1.2 / 5.2.1)
Base triangles12600–1420013396 / 13396 / 13396
LOD1 ratio0.32–0.620.5000 / 0.5000 / 0.5000
LOD2 ratio0.10–0.350.2199 / 0.2199 / 0.2125
Material slotsexactly 4, distinct4 / 4 / 4
Steel / iron / timber / ballast faces≥ 700 / 4400 / 180 / 1150816 / 5104 / 208 / 1228 on all three
UV boundsinside 0..1(0.0005, 0.0005)–(0.9995, 0.9995)
UV AABB overlap≤ 1e-50.000000
Outer AABB2.400 × 1.500 × 1.152 m ± 0.0202.4000 × 1.5000 × 1.1516 on all three
Collider triangles≤ 17001570 (13 hulls) on all three
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty1073556 bytes on all three

Hygiene#

AxisDeclaredMeasured (4.5.11 / 5.1.2 / 5.2.1)
Loose verts / edges0 / 00 / 0
Non-manifold edges00
Zero-area faces00
Doubles (1e-5 m)00
N-gons00
Coplanar cross-shell pairs00
Grounded zmin\zmin\≤ 1e-40.00000

Joint fit / seat#

AxisDeclaredMeasured (4.5.11 / 5.1.2 / 5.2.1)
Parts4 wheels, 2 rails, 2 axlesas 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 mm20.50 mm
Flange clearance to the railhead3–10 mm, every wheel6.00 mm, every wheel

Form#

AxisDeclaredMeasured (4.5.11 / 5.1.2 / 5.2.1)
Axles square to the rails≤ 0.10°0.0000°
Wheelbase0.600 ± 0.003 m0.60000
Track gauge0.600 ± 0.001 m0.60000
Rail height0.079 ± 0.001 m0.07900
Wheel tread diameter0.360 ± 0.004 m0.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.

Construction#

Findings the budgets forced#

Conventions walked#

ConventionAppliesHow
Deterministic, budgets declared, assertions recomputeyesno RNG (the ballast jitter is a fixed hash); every value above is read off the mesh
Falsifier fails the budget it targetsyestable below, proven on 4.5.11, 5.1.2 and 5.2.1
Hygiene incl. cross-shell coplanaryesexit 15
Plumb and real-world sizeyesaxle squareness, wheelbase, gauge, rail height, wheel size; exit 19
A member is tenoned into its seatyesrails 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)yesevery wheel's tread on its railhead (--float-wheel)
Mirrored assembliesyeswheel sets measured pairwise: squareness and clearance per wheel
Material face floorsyessteel 700, iron 4400, timber 180, ballast 1150
One substance, one slotyespainted steel, iron, timber, ballast
Shading is part of the modelyeswheels, axles, rivets, grab bars and rings smooth, every edge over 35° hard; boxes faceted
Edge treatmentyessleepers, plates, spike heads, sills, beams, boxes, ribs chamfered; the right-angle edge fraction is 0.077
Sort bmesh operator inputsyesthe bevel's edge list is sorted by index
The bake cage is narrower than the nearest neighbouryesCAGE_EXTRUSION 0.01 m
Level on the stage; stage 60 myesturned about Z only; 60 m floor and wall
Keep a falsifier's envelope stillyesno falsifier moves the AABB

Falsifiers#

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.

FlagTarget budgetBreaksExit
--skip-decimateLOD1 ratiodrops the DECIMATE modifiers, LOD1 ratio goes to 1.00009
--stray-vertmesh hygieneadds one loose vertex inside the tub15
--lift-zgrounded zminlifts the whole mesh 50 mm16
--float-wheelwheel seatlifts one wheel 6 mm; its tread is 5.50 mm over the rail top18
--skew-axleaxle squarenessyaws one axle and its wheels 1.5°; measured 1.500°19
--wide-gaugeflange clearancesets every wheel 12 mm outboard; the flanges sit 6.00 mm inside the railheads20

Exit codes#

File-local and sequential. 9 is a valid check code. 1 is the FATAL wrapper — a crash, never a named check.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, has no UV layer, or a part count is wrong
4Base triangle count outside band
5Material slots, or a material's face floor
6UVs outside 0..1
7UV AABB overlap above tolerance
8Outer AABB off declared size
9LOD1 or LOD2 ratio outside band (--skip-decimate)
10Framing gate (examples/gallery_framing.py, render path only)
11Collider triangles above ceiling
12Normal bake failed or produced no image data
13glTF export missing or empty
14--output produced no file
15Mesh hygiene (--stray-vert)
16Grounded zmin (--lift-z)
18Wheel seat or flange depth (--float-wheel)
19Axle squareness, wheelbase, gauge, rail height or wheel size (--skew-axle)
20Flange clearance to the railhead (--wide-gauge)
21Asset-quality floors (examples/gallery_asset_quality.py, render path only; its 11 is this piece's collider code)

Run it#

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

Cross-version measurements#

Value4.5.115.1.25.2.1
Base triangles123341233412334
LOD1 / LOD2 tris6166 / 27126166 / 27126166 / 2612
Face counts (steel / iron / timber / ballast)816 / 5104 / 208 / 622samesame
Outer AABB2.4000 × 1.5000 × 1.0481samesame
Collider tris153215321532
Wheel seat / clearance−0.50 / 6.00 mmsamesame
glTF bytes990544990544990544

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.

Source

showcase/mine-cart/mine_cart.py View the script on GitHub →
A rust-streaked red mine cart heaped with dark ore, its riveted steel tub on oak sills and four flanged iron wheels on two polished rails spiked to sleepers in grey ballast.