Caldera Island Tile

showcase/caldera-island-tile/

A procedural strategy-game map tile of a volcanic island — a disc 2.40 m across where a concave stratocone, furrowed by barrancos and ash rills, has collapsed into a caldera: a crater lake held by a rim that closes all the way round, the inner walls showing the cone's stacked lava and tuff beds; a wooded cinder cone standing in the lake, built to Porter's ratios with its crater on its axis and its flanks at the angle of repose; a channelled aa lava flow running down from a breached spatter cone between its levees, still glowing near the vent, out over its delta and under the sea beside a black-sand beach; forest, conifers, heath and bare ash zoned by height; the sea out to the rim — 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: 112874 tris, nine materials with 57624 ground, 2438 lava, 16834 sea, 2101 foam, 8523 lake, 3132 basalt, 1050 bark, 8622 foliage and 8518 plinth faces, UVs in 0..1 with zero AABB overlap, outer AABB 2.400×2.400×0.549 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, the rim on the circle at the canonical edge height (624 vertices, 0.0000 m off), the caldera's lowest pass 0.0733 m over the lake on 180 bearings (min 0.040) and the lake flat at 0.370 m, the cinder cone's crater 0.00067 m off its base's axis (max 0.004) and its flanks 30.9–31.8° on 36 bearings (band 29–34), the lava falling every one of 111 rows with each levee crest at least 0.0028 m over the channel and its toe 0.054 m under the sea, the sea at 0.1500 m with a 0.0024 m ripple, every sea and lake rim at least 0.009 m under the ground and the flow's foot 0.0038 m, the foam within 0.0058 m of the waterline with its land edge 0.0035 m under the shore, all 29 crags, bombs and boulders sealed in every sector and none overlapping, all 66 trunks 0.009–0.016 m in the ground, LOD ratios in band, seven-hull collider 344 tris, non-empty glTF. --skip-decimate exits 9; --stray-vert 15; --lift-z 16; --warp-edge 17; --breach-rim 18; --tilt-lake 19; --skew-crater 20; --steep-cone 21; --uphill-flow 22; --breach-levee 23; --short-flow 24; --flat-sea 25; --short-sea 26; --lift-foam 27; --perch-rock 28; --pile-rocks 29; --float-trees 30.

category Terrain

tags mesh export showcase

blender --background --python showcase/caldera-island-tile/caldera_island_tile.py --

A showcase piece, not an example, in the terrain category. It builds a procedural strategy-game map tile at hero-diorama density (about 113k triangles at LOD0; the gated LOD2, about 25k, is the in-game asset): a disc 2.40 m across with a volcanic island in the middle and the sea out to its rim on every side. The island is a stratovolcano whose summit has collapsed into a caldera, with a crater lake in it and a young cinder cone standing in the lake as an island.

Every seeded draw comes from random.Random(SEED) in plan_scene(), before anything is built: where each tree and rock stands and its size, tone and turn, the ripple and the foam's phases. The ground is closed-form in plan position. No flag draws from the stream, so a falsifier changes only what it names.

The volcano rises out of the shore's plateau rather than on top of it, so the coast is where the shore's rise starts from the sea's level and the ground meets the water exactly there. The caldera is the smooth minimum of the cone's flank and an inner wall that steepens from the floor's edge to the rim; the cinder cone is the smooth minimum of its straight flank and its crater's bowl. The flow is a nine-lane ribbon, levee crests over a channel, its top edges dropping to a foot 1.4 half-widths out sunk in the ground beside it; the ground under its top is held under its surface. The lake is a flat slab over the caldera's lattice triangles that hold water; the sea one slab over the tile's, running in under the lava where it enters until the bed carved under the flow closes its rim. The foam rises to a crest at the waterline over every ripple by more than a face tilts across the coplanarity range, and its land edge leans inland, so no face of it can lie in the sea's plane or stand parallel to the sea's walls. Rocks and trees landing in another shell's plane turn 3° about their lowest point and sink half a millimetre (two trees on one contour carry level caps a turn leaves level), one shell of a pair at a time.

Ground is smooth-shaded with a 55° crease, the lava with 40°. Nine materials: volcanic ground (sand and black sand, forest, meadow, heath, ash, scoria, the caldera's beds, sulphur), basalt flow, sea water, foam, crater lake, basalt (the crags, bombs and boulders), bark, foliage (conifer and broadleaf), tile plinth (the slate rim and the skirt's section).

It asserts budget conformance of the generated result. It does not witness an API contract. "It rendered without error" is not a check.

Composes skills mesh-editing-and-bmesh, bake-high-to-low, depsgraph-and-evaluated-data, engine-export-presets, and snippets bake_normal_high_to_low.py, setup_bake_target_image.py, lod_chain.py / decimate_to_budget.py, convex_hull_collider.py, export_preset_unity.py (helpers copied inline, not imported).

The collider is seven convex hulls joined in one mesh, built from points only: the plinth up to the water, and the island in six sectors round its centre, from the shore to the ground over it; neighbouring sectors share their edge rays, so the hulls close round the island. Ships sail the sea; units walk the land.

Budgets#

Every budget is declared as a named constant. Every gate recomputes its value from the mesh, materials, UVs, evaluated LOD, collider, or export file.

AxisDeclaredMeasured (5.2.1)
Base triangles111500–114000112874
LOD1 ratio0.32–0.62 of base0.5000
LOD2 ratio0.10–0.35 of base0.2200
Materialsexactly 9 distinct; face floors ground ≥51800, lava ≥1500, sea ≥15100, foam ≥1890, lake ≥7200, basalt ≥2810, bark ≥940, foliage ≥7750, plinth ≥76609 slots; 57624 / 2438 / 16834 / 2101 / 8523 / 3132 / 1050 / 8622 / 8518
UVsin 0..1, AABB overlap ≤ 1e-5in range, overlap 0
Outer AABB(2.4000, 2.4000, 0.5500) m ± 0.01(2.4000, 2.4000, 0.5491), zmin 0
Collider tris (seven hulls)≤ 360344
Exportwritten, size > 0, removed after measuring11629048 bytes

DECIMATE COLLAPSE triangle counts are not identical across Blender series, so the LOD gate is a ratio band, not an exact count. Bake pixels are stochastic, so the bake gate is has_data plus operator FINISHED, not byte-identity. The plan is seeded and nothing else is random; two default runs print identical measurements. The triangle band is wide enough for the falsifiers that change geometry (--short-flow 112082, --breach-rim 113046, --steep-cone 112758) to reach their own checks, and the lava's floor sits under --short-flow's 1646 faces for the same reason.

Hygiene#

Recomputed from the generated mesh, not asserted about the script.

AxisDeclaredMeasured
Non-manifold edges00
Loose verts / edges0 / 00 / 0
Doubles merged at 1e-500
Zero-area faces00
N-gons00
Coplanar cross-shell face pairs (KD range 0.05 m, plane ε 1e-4)00
Grounded: zminwithin 1e-4 of 00.0000

The tile's flat base is the only geometry at Z = 0.

Terrain invariants#

A map tile has no joinery. What makes this read as a volcano and as a map tile is that its edge is one profile all round, that the caldera holds its lake, that the cinder cone is a cinder cone, that the lava ran downhill between its levees into the sea, that the sea lies level and is held by the shore and the rim with its foam at the waterline, and that the rocks and trees stand in the ground. Each face carries Part, Ident and Cap tags, each vertex Ring, Lane and FoamX, so the rim, a flow row and lane, and a trunk's foot can be named; every measurement is then made on the shipped geometry.

AxisDeclaredMeasured
Edge: every vertex on the skirt's top, its distance off the tile's circle and its height against the canonical edge height≤ 0.0005 m each0.0000 / 0.0000 (624 vertices)
Caldera holds its lake: on each of 180 bearings out from the caldera's centre, the highest ground on the shipped tile; the lowest of those crests (the pass the lake would spill through) against the lake's top≥ 0.040 m0.0733 m (at 106°)
Lake flat: its top's spread, and its median against the declared level≤ 0.0005 m; 0.370 ± 0.0015 m0.00000; 0.37000
Cinder cone coaxial: on 36 bearings off the shipped ground, the crater's crest (highest point) and the base (where the flank meets the lake); the distance between the two rings' centres≤ 0.004 m0.00067
Cinder cone at repose: on each bearing, the flank's slope from a quarter to seven eighths of the way from the crest to the baseevery bearing 29–34°30.87–31.78°
Lava drains: along its centre lane, the largest rise from one row to the next≤ 1e-6 m−0.00025 (111 rows, 0.303 m fall)
Lava in its levees: per row, the lower levee crest over the channel's centre≥ 0.002 m0.0028
Lava into the sea: its toe against the sea's level≤ −0.010 m−0.0538
Sea level: the top's median height and largest excursion from itlevel 0.150 ± 0.0015 m; ripple 0.001–0.006 m0.15000; 0.00238
Water contained, lava seated: the ground over every rim vertex and rim-edge midpoint of the sea's and the lake's top; the ground over every corner of the flow's footsea and lake ≥ 0.005 m; lava ≥ 0.003 m; 1804 pointssea 0.0090, lake 0.0095, lava 0.0038
Foam seated: every foam vertex off the water's level; its land edge's top under the shore≤ 0.007 m; ≥ 0.003 m0.0058; 0.0035
Rocks sealed: per crag, bomb and boulder, in each sector holding a vertex, its most-buried vertex under the ground≥ 0.003 m, 29 rocksworst 0.0050
Rocks apart: pairs of rocks whose BVH trees overlap00
Trees rooted: every trunk's foot (its bottom cap) under the ground straight above each corner0.004–0.050 m, 66 trunks0.0089–0.0158

The caldera and the cinder cone are measured off the shipped tile by rays straight down, not read back from the closed form that built them, so the lattice's sampling of the wall and the cone is what the gates see.

Falsifiers#

Each falsifier violates one named budget. Every one was run on 5.2.1 and exited its declared code. The envelope was unchanged in every run but --warp-edge (y 2.3960) and --perch-rock (z 0.5502), both inside the tolerance; the triangle count changed only where the flag changes geometry (above).

FlagBudget violatedExit
--skip-decimateLOD1 ratio band (measured 1.0000)9
--stray-vertloose vertex count is 0 (measured 1)15
--lift-zbounding box zmin is 0 (measured 0.05000)16
--warp-edgeedge (an arc of the rim pulled 4 mm in and lifted 4 mm: 0.0040 m off the circle and the canonical height)17
--breach-rimcaldera holds its lake (a notch 0.24 m deep cut through the back rim: lowest pass −0.0097 m)18
--tilt-lakelake flat (the lake's top sloped 0.03 m per metre: spread 0.0197 m)19
--skew-cratercinder cone coaxial (its crater moved 30 mm off the base's axis: 0.0093 m)20
--steep-conecinder cone at repose (the cone raised 1.45 times: 40.9–41.6°)21
--uphill-flowlava drains (a 30 mm hump mid-course, steeper than the flow falls: rises 0.00480 m between rows)22
--breach-leveelava in its levees (one crest dropped under the channel over a stretch: −0.0027 m)23
--short-flowlava into the sea (the flow stopped 60 mm short of the coast: toe +0.0173 m)24
--flat-seasea level and ripple (the sheet laid flat at its level: ripple 0.00000 m)25
--short-seawater contained (the sheet's shoreward rim drawn 60 mm out to sea: −0.0424 m)26
--lift-foamfoam seated (the foam raised 20 mm: 0.0258 m off the water, land edge −0.0165 m)27
--perch-rockrocks sealed (each rock seated against the ground at its centre alone: −0.0214 m)28
--pile-rocksrocks apart (two crags dropped against the first: 2 pairs overlap)29
--float-treestrees rooted (the lowland broadleaves raised 40 mm: feet −0.0292 m)30

--float-trees lifts only the lowland broadleaves, whose tops stay under the island's top, so the envelope does not steal the exit. --uphill-flow's hump is 20 mm wide: the flow falls about 0.78 m per metre on the flank, and a gentler swell would be swallowed by that fall.

Run#

blender --background --python caldera_island_tile.py --
blender --background --python caldera_island_tile.py -- --skip-decimate
blender --background --python caldera_island_tile.py -- --stray-vert
blender --background --python caldera_island_tile.py -- --lift-z
blender --background --python caldera_island_tile.py -- --warp-edge
blender --background --python caldera_island_tile.py -- --breach-rim
blender --background --python caldera_island_tile.py -- --tilt-lake
blender --background --python caldera_island_tile.py -- --skew-crater
blender --background --python caldera_island_tile.py -- --steep-cone
blender --background --python caldera_island_tile.py -- --uphill-flow
blender --background --python caldera_island_tile.py -- --breach-levee
blender --background --python caldera_island_tile.py -- --short-flow
blender --background --python caldera_island_tile.py -- --flat-sea
blender --background --python caldera_island_tile.py -- --short-sea
blender --background --python caldera_island_tile.py -- --lift-foam
blender --background --python caldera_island_tile.py -- --perch-rock
blender --background --python caldera_island_tile.py -- --pile-rocks
blender --background --python caldera_island_tile.py -- --float-trees
blender --background --python caldera_island_tile.py -- --output caldera.png

Smoke passes no flags.

The hero does not turn the piece (HERO_YAW_DEG 0) and looks down on the tile from the front, 12° to the left and 32° over it, the way a map tile is seen on a game board: the caldera and its lake open behind the cone's front flank, the lava runs down the right toward the camera and the key from the left throws the barrancos into relief. Seen from this high, the floor behind the tile is the backdrop, so the warm wedge drops its pool on the floor off to the left, where it reaches no water to glare off, rather than on the back wall. Framing measures fill x 0.709, y 0.800, margins left 0.138, right 0.153, bottom 0.117, top 0.083; the asset-quality floors pass.

Exit codes#

File-local. 9 is a valid check code. 10 is reserved for gallery_framing.check_framing and 11 for gallery_asset_quality.check_asset_quality, both on the --output path. 15–16 are the hygiene and grounded family; 17–31 are file-local.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, no UV layer, or not one tile, sea, lake, lava flow and foam line
4Base triangle count outside range
5Material count ≠ 9 distinct slots, or a face-count floor missed
6UVs outside 0..1
7UV AABB overlap above tolerance
8World AABB off declared outer size
9LOD ratio band (--skip-decimate lands here)
10Framing gate (render path only)
11Asset-quality floor (render path only)
12Bake did not finish or image has no data
13Export file missing or empty
14--output produced no file
15Mesh hygiene: loose, non-manifold, zero-area, doubles, n-gons, coplanar cross-shell pairs
16Not grounded: bounding box zmin off 0
17Edge: the rim off the circle or off the canonical edge height (--warp-edge)
18Caldera: its rim's lowest pass under the declared freeboard over the lake (--breach-rim)
19Lake: its top not flat or off its level (--tilt-lake)
20Cinder cone: its crater's crest off its base's axis (--skew-crater)
21Cinder cone: a flank outside the repose band (--steep-cone)
22Lava: its surface rising anywhere along it (--uphill-flow)
23Lava: a levee crest not over the channel by the declared margin (--breach-levee)
24Lava: its toe not under the sea (--short-flow)
25Sea: off its level or its ripple outside the band (--flat-sea)
26Water contained, lava seated: a sheet's rim not under the ground, or the flow's foot not under it (--short-sea)
27Foam: off the waterline, or its land edge not under the shore (--lift-foam)
28Rocks: a sector of a crag, bomb or boulder not bedded in the ground (--perch-rock)
29Rocks: two overlap (--pile-rocks)
30Trees: a trunk's foot out of its band under the ground (--float-trees)
31Collider triangle count above ceiling

Source

showcase/caldera-island-tile/caldera_island_tile.py View the script on GitHub →
A round volcanic island map tile seen from above: a caldera holding a blue crater lake with a wooded cinder cone island, forested flanks, and a dark lava flow running down to a black beach.