ludic/packages/ludic.render3d/README.md

ludic.render3d

A physically based 3D renderer over Vulkan. FEATURES.md lists what is implemented and where.

Painted ground layers

A ground layer is a density painted over the map (R the chance a cell keeps one, G its scale, 2 m texels baked into an LGD2 file, ground_density.ludic) and a GroundFill row of numbers. Everything it grows is a pure function of those two - the same on every machine and in the editor's preview.

• The candidate (ground_cand.ludic): for (layer, chunk, band, cell) ground_candidate answers whether one stands there and its x, z, scale, yaw, seed and wind, into a GroundCand the caller holds. Its steps are pure: gf_along (the jitter, draws 0 and 1), gf_keeps (draw 2 under the chance), gf_scale (G and draw 6), gf_yaw (3), gf_seed (4), gf_wind (5). ground_fill draws exactly these. Numbers are IEEE single precision, Math.lerp is a + (b - a) * t, gf_hash is 32-bit integer arithmetic with a logical >>, and the model shader turns local (x, z) to (c x + s z, -s x + c z) - three.js's rotation about +Y.
• Cover and solid. A cover layer (grass, flowers, pebbles) is filled at its band's step, so a far band is a different, sparser sample. A layer with solid: true (rocks, trees) is filled at step0 with band 0's hashes whatever the band, and a far band draws the subset whose draw 7 falls under (step0 / step_band)^2; its scale ignores band_grow. Nothing solid moves with the camera.
• Solid ids (ground_solid.ludic): ground_solid_id(layer, cx, cz, i, j, cells) = ((layer * 256 + cz + 128) * 256 + cx + 128) * 512 + i * cells + j, a positive 31-bit int, stable while the painting under it is. It holds chunks -128 .. 127 about the stream's corner and at most 22 cells a chunk side (a step of at least 32 / 22 m on 32 m chunks); a cell past that has no id and is not grown. ground_solid_list fills a caller's GroundSolids (made once, ground_solids_new) with a chunk's things for physics, the nav bake or a save; ground_solid_at answers one by id.
• The trample as data (ground_clear.ludic): r3d_ground_clearing(x, z, r_in, r_out, floor) hands over a clearing - floor inside r_in, back to full at r_out on a smoothstep, the shape of the camp's ring and the town's yard. A layer with trample multiplies its chance by the game's callback (r3d_on_ground_trample, kept for now) and then by every clearing. A game should use one or the other.
• Conformance: tests/ground_fill_test.ludic holds the package to tests/ground_fill_golden.json (gf_hash, lerp, yaw, one cover chunk and one solid chunk over a hand-written density), which the studio's own test reads. After a deliberate change, rebuild it from the repository root: bin/ludic run packages/ludic.render3d/tests/gen/ground_fill_golden.ludic --headless, and commit it.