Pond Edge

showcase/pond-edge/

A procedural pond margin on a raised soil disc — a shallow pond whose water is its own mesh at a declared level, rippled in low rings round the reeds and the branch, its rim run on under a sloped mud bank; a clump of cattails with arching strap leaves and five stems, each threaded through a brown seed head with a bare spike above it; soft rush and turf tufts on the bank; five notched lily pads floating on the water with two layered white-and-pink water lilies; wet stones at the waterline, a half-submerged branch, pebbles and fallen leaves — 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: 37602 tris, nine materials with 5824 water, 5614 soil, 8162 reed, 1400 seed-head, 1390 pad, 1440 flower, 2046 stone, 234 wood and 400 litter faces, UVs in 0..1 with zero AABB overlap, outer AABB 3.204×2.634×1.507 m read off the vertices, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, all 39 cattail leaves and stems rooted 0.0397–0.0445 m under the mud (band 0.020–0.070), all five pads floating with 0.00149 m freeboard (band −0.0005–0.0040) and 0.00150 m draft (band 0.0005–0.0040) at ≤ 0.011° tilt (cap 3°), the water's level 0.11500 m (declared 0.115 ± 0.0015) with a 0.00439 m ripple (band 0.0015–0.0090), five seed heads on five distinct stems at most 0.00008 m off their stems' axes (cap 0.002) with 0.093–0.136 m of spike above (floor 0.06), the bank at least 0.01366 m over every point of the water's rim (floor 0.008), all 598 shells joined to the soil, LOD ratios in band, soil collider 96 tris, non-empty glTF. --skip-decimate exits 9; --stray-vert 15; --lift-z 16; --float-reeds 17; --sink-pad 18; --flat-water 19; --slip-heads 20; --short-water 21; --float-cover 22.

category Nature

tags mesh export showcase

blender --background --python showcase/pond-edge/pond_edge.py --

A showcase piece, not an example, and the fourth in the nature category. It builds a procedural, game-ready pond margin on a raised soil disc:

Every draw comes from random.Random(SEED) in plan_pond(), before anything is built. Which scatter candidates are used is decided once against the default build (Layout), which also refuses a layout whose floating parts crowd each other or the shore. No flag draws from the stream or changes the layout, so a falsifier changes only what it names.

Nine materials, one per substance: water, bank mud, reed (cattail leaves and stems, rushes), seed head (with the bare spike), lily pad, lily flower, stone (stones and pebbles), wood (the branch) and leaf litter. Point attributes carry what the shaders need: Depth (water over the mud), Wet (the mud band, the wet part of each stone and of the branch), Turf, Skirt, Along (the run along a leaf, blade, stem or petal) and PadAng / PadR (the pad veins and rim). A Tone face attribute is seeded per part. Everything is smooth-shaded; every material boundary and every fold sharper than 60° is a hard edge.

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

Intended size: a disc 3.20 × 2.63 m with its bank 0.17–0.25 m high, the tallest cattail spike 1.51 m off the floor. The outer AABB is 3.204 × 2.634 × 1.507 m, read off the vertices. The soil sets X and Y, a cattail spike the top; the soil's underside is the ground. The collider is the convex hull of the soil disc alone, coarse: the water is a trigger volume, and players walk through reeds.

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 triangles36900–3830037602
LOD1 ratio0.32–0.62 of base0.5000
LOD2 ratio0.10–0.35 of base0.2200
Materialsexactly 9 distinct; ≥5240 water, ≥5050 soil, ≥7340 reed, ≥1260 seed head, ≥1250 pad, ≥1290 flower, ≥1840 stone, ≥210 wood, ≥360 litter faces9 slots; 5824 / 5614 / 8162 / 1400 / 1390 / 1440 / 2046 / 234 / 400
UVsin 0..1, AABB overlap ≤ 1e-5in range, overlap 0
Outer AABB(3.2040, 2.6342, 1.5071) m ± 0.01(3.2040, 2.6342, 1.5071), zmin 0
Collider tris (soil hull)≤ 12096
Exportwritten, size > 0, removed after measuring3140712 / 3140712 / 3140704 bytes (4.5.11 / 5.1.2 / 5.2.1)

No falsifier changes the triangle count or the envelope: every falsifier run measured 37602 tris and the default's outer AABB to the tenth of a millimetre.

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; the geometry is pure Python math. Two default runs print identical measurements.

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 coplanar budget caught four kinds of fault on the way. Petals and sepals rooted on one point of the flower's axis put planes through that axis, and a mirror-symmetric petal turned about it lands a face on a neighbour's plane: seven pairs. Every petal now roots at its own radius and height, and its two halves differ by a few percent. Two cattail stems built with the same starting ring frame laid facets on shared planes where they ran parallel; each tube now starts its facets at its own angle. Two rush blades rooted at one height had flat root caps on one plane, and a fallen leaf laid along the soil normal lay on the plane of the face under it; blades now leave the ground already leaning their own way, and bank leaves are tipped a few degrees off the ground. A V-section blade pair with opposite yaws and equal lean was parallel by chance; a per-blade roll broke it.

Rooted reeds, floating pads, the water, threaded heads, the enclosed water and the cover#

These are the organic invariants. A pond margin has no joinery. What makes it read as a pond is that its reeds grow out of the mud rather than stand on it, that its pads float on the water rather than sink or hover, that the water lies level with a living surface, that the seed heads grow on their stems, that the bank holds the water on every side, and that nothing on the bank floats.

AxisDeclaredMeasured
Rooted reeds: every cattail leaf and stem, its lowest vertex under the soil straight above it (a ray down onto the soil shell alone)39 of 39, each 0.020–0.070 m39; 0.0397–0.0445 m
Floating pads: for each pad, its mean height over the water surface under its centroid (a ray down onto the water shell alone), how far its lowest vertex draws under that surface, and the tilt of the plane fitted through it5 pads; freeboard −0.0005–0.0040 m, draft 0.0005–0.0040 m, tilt ≤ 3°5; freeboard 0.00149 m, draft 0.00150 m, tilt ≤ 0.011°
Water: the median height of the water's top sheet, and its largest excursion from that medianlevel 0.115 ± 0.0015 m; ripple 0.0015–0.0090 m0.11500 m; 0.00439 m
Threaded heads: each seed head's axis from its own vertices (principal axis); the stem whose vertices inside the head's middle run lie closest to it, and their centroid's distance off the axis; how far that stem runs on above the head5 heads on 5 distinct stems; off-axis ≤ 0.002 m; spike ≥ 0.06 m5 on 5; ≤ 0.00008 m; 0.093–0.136 m
Enclosed water: the bank over every rim vertex and rim-edge midpoint of the water's top sheet (a ray down onto the soil shell alone)≥ 0.008 m everywhere0.01366 m (208 rim edges)
Cover joined: every shell unioned with the soil through BVH overlaps (floating parts through the water)every shell joined598 shells; 0 loose

The shoreline is found per bearing by bisection on the analytic bank, and the water's rim is laid 50 mm past it; the enclosure budget reads the bank back off the shipped soil mesh by raycast, so it sees the soil that was built. Each leaf and stem root is set 40 mm (staggered) under the soil mesh as built. The pads sit a 3 mm slab with its underside 1.5 mm under the water, and the ripples die out round each pad, so a pad rests on calm water.

Falsifiers#

Each falsifier violates one named budget. Every one was run on 5.2.1 and exited its declared code. None moves the envelope: every run measured the same outer AABB and triangle count as the default, and every other piece-specific budget stayed green.

FlagBudget violatedExit
--skip-decimateLOD1 ratio band (measured 1.0000)9
--stray-vertloose vertex count is 0 (measured 1, placed inside the envelope)15
--lift-zbounding box zmin is 0 (measured 0.05000)16
--float-reedsrooted reeds (every leaf and stem base raised 70 mm, fading to 0 at the tip: lowest vertex −0.0303 to −0.0255 m, above the mud)17
--sink-padfloating pads (the first pad pushed 4 mm under, its rim still awash: freeboard −0.00251 m, draft 0.00550 m)18
--flat-waterwater level and ripple band (the sheet laid flat: ripple 0.00000 m)19
--slip-headsthreaded heads (every head slid 8 mm off its stem's axis, still pierced by it: 0.0079–0.0080 m off)20
--short-waterenclosed water (the rim stopped 60 mm short of the shoreline: the bank 0.03736 m below it)21
--float-covercover joined (every rush blade, pebble and bank leaf lifted 30 mm: 108 of 598 shells loose)22

--float-reeds holds each tip where it was, so the envelope, set by a spike tip, does not move; the heads stay threaded (1.0 mm off-axis). The stems and leaves still cross the water, so the cover budget still joins them. --sink-pad pushes the pad 4 mm, not more: pushed 12 mm it drowned whole and came loose from the water, which the cover budget saw too. --slip-heads slides 8 mm for the same reason: at 25 mm the heads left their stems and came loose. --flat-water changes no draw, so the pads float exactly as before. --short-water changes only the water; the ripples, the pads and the cover are unchanged. --stray-vert and --lift-z necessarily move the loose-shell count and the water's absolute level with them; they exit on their own, earlier codes.

Run#

blender --background --python pond_edge.py --
blender --background --python pond_edge.py -- --skip-decimate
blender --background --python pond_edge.py -- --stray-vert
blender --background --python pond_edge.py -- --lift-z
blender --background --python pond_edge.py -- --float-reeds
blender --background --python pond_edge.py -- --sink-pad
blender --background --python pond_edge.py -- --flat-water
blender --background --python pond_edge.py -- --slip-heads
blender --background --python pond_edge.py -- --short-water
blender --background --python pond_edge.py -- --float-cover
blender --background --python pond_edge.py -- --output pond.png

Smoke passes no flags.

The hero keeps the piece unturned (HERO_YAW_DEG 0°) and looks in from the south-south-west, a little above the bank, so the water shows as a dark sheet between the near bank and the far one. EEVEE's traced reflections put the cattails and the back wall into the water. The cattails stand at the back left against the wall, the rushes along the far bank, the branch on the right. The fill is 0.688 × 0.872.

Exit codes#

File-local. 9 is a valid check code. 10 is reserved for gallery_framing.check_framing on the --output path. 15–19 are the hygiene, grounding, rooting, floating and level family. 20–22 are file-local. 23 is the asset-quality floor on the render path: check_asset_quality returns 11, which this piece already spends on the collider ceiling, so the call site remaps it.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, no UV layer, or no soil or water shell
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)
11Collider triangle count above ceiling
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 (--lift-z)
17Rooted reeds: not 39 leaves and stems, or one's lowest vertex outside 0.020–0.070 m under the mud (--float-reeds)
18Floating pads: not 5 pads, or a pad's freeboard outside −0.0005–0.0040 m, its draft outside 0.0005–0.0040 m, or its tilt above 3° (--sink-pad)
19Water: its level more than 0.0015 m off 0.115 m, or its ripple outside 0.0015–0.0090 m (--flat-water)
20Threaded heads: not 5 heads on 5 stems, a head more than 0.002 m off its stem's axis, or a spike under 0.06 m (--slip-heads)
21Enclosed water: the bank less than 0.008 m over the water's rim anywhere (--short-water)
22Cover: a shell not joined to the soil (--float-cover)
23Asset-quality floor (render path only; remapped from 11)

Source

showcase/pond-edge/pond_edge.py View the script on GitHub →
A dark rippled pond on a raised soil disc: cattails with brown seed heads and rush tufts on the far bank, notched lily pads and two pink-white water lilies, wet stones and a branch at the waterline.