Chunks are now isotropic 16×16×16 cubes stacked in all three axes,
keyed by IVec3(cx, cy, cz). The world has no Y ceiling and no Y
floor — set_block lazily creates a chunk if one doesn't exist, so
building 1000 blocks straight up just creates 60-ish empty chunks
above the surface on demand.
world.rs:
- CHUNK_HEIGHT removed. Single CHUNK_SIZE (=16) for all three axes.
- Chunk allocates 16³ = 4096 blocks.
- Chunk::get/set bound-check 0..CHUNK_SIZE on every axis.
- block_to_chunk returns full 3D (cx, cy, cz) + (lx, ly, lz).
- get_block has no Y bound — outside any chunk = Air (sky).
- set_block: chunks.entry(c).or_insert_with(...) creates on demand.
- HeightMap is keyed by IVec2(cx, cz) column. from_world_column scans
every existing cubic chunk in that column top-down for the topmost
solid block. Heightmap invalidation in set_block drops the column,
not just the single chunk.
- column_top_y, World::heightmap signature both take (cx, cz) directly.
- World::new pre-generates chunks at cy in -1..=2 (4 vertical levels
of pre-gen, ~1.1k chunks total, ~4.6 MB) covering the natural
surface band. Above/below grows lazily.
- generate_chunk takes the full 3D chunk coord; computes oy, fills
blocks for this slice of the column. Trees that straddle a chunk
boundary deterministically fill in their portion (each chunk uses
the same hash, writes only its slice).
- natural_surface_y returns the topmost-solid Y (preserved old
semantic so all collision / spawn tests still hold).
- 2 new tests pin the lazy-chunk-creation invariant (above and
below pre-gen ranges).
mesh.rs:
- dims is [CHUNK_SIZE; 3]; iteration loops are cubic.
- base_y added so neighbor lookups + corner positions account for
the chunk's vertical offset.
- warm_heightmaps_around takes (cx, cz) column coords now.
sim/spawn.rs:
- find_safe_spawn no longer caps at CHUNK_HEIGHT-2. Safety bound
is surface_y + 200 (pathological tower depth before giving up).
sim/lighting.rs:
- SUN_RAY_TOP_Y bumped from 128 to 4096 (was matching the old
fixed world height). Ray DDA still terminates at the cap.
sim/visibility.rs:
- Chunk AABB is CHUNK_SIZE on all three axes; the chunk's cy now
contributes to the AABB min Y (was hardcoded 0).
render/mod.rs:
- Heightmap warming + comment updates for column-keyed semantics.
Tests: 65/65 pass (was 63, +2 new). Native + wasm release clean.
Smoke-tested live: 88 fps, alive, spawn at y=8. All four UI
scenarios pass.
This is the foundation for the LOD pyramid you directed earlier —
isotropic chunks downsample cleanly (a LOD-N chunk represents a
(2^N)³ region with 16³ entries), and unbounded Y lets the LOD
tree extend in any direction without special cases.
The render-distance slider has step=16 in the HTML; setting .value
to 120 snaps to the nearest valid value (128). The test was asserting
the displayed text contained "120" — never true. Changed to 128
(actually on a step boundary). Pure test correctness; UI behavior
was right all along (snap-to-step is the slider's intended behavior).
All four UI scenarios now green on hardware Chromium:
ui-menu-open-close 13 steps 2.44s ✓
ui-hotbar 10 steps 1.07s ✓
ui-respawn 14 steps 3.38s ✓
ui-settings-sliders 15 steps 1.52s ✓
FPS on real hardware: 61.9 fps (16.2ms median) — matches the
deployment, confirms the game itself is fast. The earlier 3 fps
was Playwright's SwiftShader software path.
Per your direction: tests must be able to debug UI/UX behaviors and
must be performant. Playwright's bundled Chromium falls to SwiftShader
on Linux which is fine for visual scenarios but tanks anything where
fps matters. New attach-mode lets us drive YOUR Chrome (hardware GPU)
without needing Playwright to spawn its own.
test/attach.py:
- One-shot health check that connects to localhost:9222 (Chrome
already running with --remote-debugging-port). Doesn't spawn,
doesn't close. Just confirms attach + reports the FPS HUD value.
- peek.py and run.py already attach via CDP, so they work as-is
once Chrome is started with the debug port.
test/README.md:
- New "Two modes" section up front: attach (your real Chrome,
hardware) vs launch (Playwright Chromium, software). Each has a
legitimate use; perf-sensitive work goes through attach.
- Workflow:
google-chrome --remote-debugging-port=9222 \\
--user-data-dir=/tmp/voxel-dev-chrome http://localhost:8080/
python3 attach.py # health check
python3 run.py scenarios/ui-menu-open-close.yaml
New UI scenarios that drive interactions via DOM events / wasm calls,
not pixel screenshots. Render-independent, fast on any backend:
ui-menu-open-close.yaml Click ≡ → assert menu-open class →
click resume → assert closed.
ui-hotbar.yaml pointerdown on slot 4 → assert .active
moved. Digit1 keypress → assert .active
back to slot 0.
ui-respawn.yaml teleport into void → wait → assert
is_alive()===false + body.dead class +
death screen visible. Click respawn-btn
→ assert hp===20, alive===true.
ui-settings-sliders.yaml Slider .value = N + dispatch 'input' →
assert displayed value updates → unwind
so the page isn't left frozen.
README updates list all scenarios. No code in the game changed —
this is pure test-harness additions.
You're right — the telemetry path itself was contributing to perceived
browser lag, not just the GPU work. Two specific sources removed:
render/mod.rs::rebuild_chunk:
- Per-chunk log::info!("rebuild_chunk {coord}: {ms}ms ...") fired
~289 times during world init, plus on every edit. Chrome's console
buffer accumulates these and DevTools recalcs on each new line.
Removed entirely. The bench toggles + FPS HUD already give us the
measurement signal; per-chunk timing was noise once verified.
web/main.js setupFpsHud:
- Was a 5 Hz setInterval that did `el.textContent = ...` and two
`classList.toggle` calls each tick (15 DOM writes/sec). Now:
* Polls at 1 Hz (the EMA already smooths)
* Only writes textContent when the displayed string actually
changes (skip is the common case once stabilized)
* Only writes class when the tier (green/warn/bad) crosses
a threshold
Same readout, ~15× fewer DOM writes.
web/main.js setupStatusLoop (HP bar):
- Same dedupe pattern. 10 Hz polling, but DOM writes only when
hp or alive changes from the last sample. Was firing 3 style
writes per tick unconditionally; now zero in steady state.
No functionality changes — every telemetry getter, every bench
toggle, every test-harness export still works (just verified via
the 18-check functional contract suite).
Wasm release built; tests 63/63 pass.
Per your directive to make sure debug surfaces actually work:
test/scenarios/bench-pass-cost.yaml:
Declarative sweep that runs each bench config (all on / no shafts /
no post / both off) with 8s settling between, screenshots each
config, and asserts frame_dt_ms is positive. The Playwright env
runs SwiftShader so absolute deltas are noisy, but the scenario
is structurally correct for real hardware where the differences
will read clean.
Functional contract verification (run interactively):
- All 11 wasm exports exist on window.voxel_game
- FPS HUD renders and updates frame-to-frame
- Telemetry getters return finite values
- set_scene_time(42) round-trips through tick to get_scene_time
- teleport(x,y,z) round-trips (modulo expected gravity drop)
- look_at(yaw,pitch) round-trips
- bench_set_disable_post measurably changes frame_dt
(915 → 820 ms in my software environment)
18 checks, 0 failures. The debugging substrate is verified
end-to-end; remaining "local slower than deployment" gap is most
likely a WebGPU-vs-WebGL2 backend selection issue rather than a
code-path bug.
You called out vibes-based programming — fair. This adds the actual
measurement substrate so the next change can be data-driven instead
of educated-guess driven.
app.rs:
- tick's frame_dt was previously clamped to 100ms (for physics
safety: a 1-second hang shouldn't teleport the player). That
clamp was poisoning the FPS telemetry: anything slower than
10 fps reported as exactly 10 fps. Now physics gets the clamped
dt; the FPS HUD reads the unclamped elapsed_ms so we see the
real frame time even at 3 fps.
bridges.rs:
- New BenchFlags { disable_shafts, disable_post }, exposed via
wasm_api as bench_set_disable_shafts(bool) /
bench_set_disable_post(bool). Set from JS console or scenario:
window.voxel_game.bench_set_disable_shafts(true)
render/mod.rs:
- render() consults the flags. Truly skipped (no clear, no work)
so the bench measures the pure cost of each pass.
Usage from a player's perspective:
1. Open the game, watch the FPS HUD (top-right).
2. F12 → Console
3. window.voxel_game.bench_set_disable_shafts(true)
watch HUD — fps should jump if shafts were expensive.
4. window.voxel_game.bench_set_disable_post(true)
— measures FXAA + composite + tonemap cost.
5. Both true — naked terrain only, no post effects.
The Playwright-launched Chromium I have access to is software-
rasterizing at ~3 fps which makes per-pass deltas indistinguishable
from noise. On real hardware the cost differences should be clear.
I won't push more "optimizations" until we have real-hardware data
on which pass is actually costing what.
No features removed. Tests: 63/63 passing. Wasm built clean.
The screenshot you sent shows the whole atmosphere whited-out with a
giant fuzzy sun blob. Root causes (with arithmetic, not hand-waving):
1. shafts EXPOSURE was 0.30. A pixel looking at the sun accumulates
WEIGHT × Σ(DECAY^k) ≈ 0.78 × 9.92 ≈ 7.7 from the 16-sample radial
blur. × 0.30 = 2.3 added to the scene additively, which then
saturates through ACES tonemap and produces a giant white blob.
Fix: EXPOSURE 0.30 → 0.08. A direct-at-sun pixel now gets ~0.6
additive (clear glow without erasing underlying color).
2. Sun disc intensity was mix(2.2, 1.5, alt) — the disc itself was
over 1.0 BEFORE the shafts added their contribution on top, so
ACES could only clamp it to white. Fix: mix(1.4, 0.9, alt). Halo
exponents trimmed to match.
3. Mask sun-cone was pow(dot, 8) — a fairly broad arc, so the
shafts pass lit up too much of the sky. Tightening to pow(dot, 20)
anchors rays to the actual sun direction.
Reverted: the fog `-view_dir` → `view_dir` change. I asserted that
was a bug without independent verification — keeping the original
direction until I can verify, per your "do not hallucinate" directive.
The washout was the shafts brightness, not the fog direction.
No features removed. Tests pass.
You asked "Are you spawning too many godrays?" — yes, 32 samples
per ¼-res pixel was overkill. Plus FXAA was a 5-tap blur at full res
and the sun disc was pow(cos, 800) which is itself a slow op.
shafts.wgsl:
N_SAMPLES 32 → 16. DECAY + WEIGHT rebalanced to keep total
intensity the same with half the samples. At ¼ res with a 16-step
decay the rays still trace cleanly (no banding). Halves the
god-rays fragment cost.
post.wgsl:
FXAA from 5-tap (NW/NE/SW/SE corners + center) to 2-tap (center +
SE diagonal). Voxel-game edges are axis-aligned and high-contrast,
so two-tap diagonal softening is enough to kill the staircase
artifacts that motivated AA. 2.5× cheaper per pixel; full-screen
fragment work goes from ~6 texture reads + math to ~3.
shader.wgsl:
Sun disc sharpness pow(cos, 800) → pow(cos, 256) at zenith,
pow(cos, 160) → pow(cos, 120) at horizon. The disc still reads
crisp visually, and pow on smaller exponents is materially
faster on weak GPUs / software rasterizers.
Moon disc + halo now gated behind night > 0.05 — invisible during
the day anyway, so skipping the pow(cos, 256) saves work on every
daytime sky pixel.
render/mod.rs:
Mask + shafts passes skipped at the CPU level when sun is below
horizon (the shader was already returning black, but we paid pass
setup + clear regardless). Replaced with a single "shafts clear"
pass at night so the post pass doesn't see yesterday's rays.
No features dropped. Tests: 63/63 passing. Wasm release built.
The features added in Rounds A–D were correct but expensive. The hot
path per frame was sky_color() called from apply_fog for EVERY distant
pixel — 4-octave cloud fbm + star hash + sun/moon disc per fragment,
hundreds of thousands of pixels per frame. Profile-driven cuts that
keep all features but stop paying for them in the wrong places:
1. apply_fog now mixes terrain toward sky_dome (cheap gradient) not
sky_color (gradient + clouds + sun + moon + stars). Distant terrain
still fades to the right-direction sky color at every time of day;
the per-pixel cost drops by ~80%. Full sky_color still runs for
the SKY BACKGROUND pass where it's actually paid for.
2. Sky pipeline draws AFTER terrain with depth_compare = LessEqual.
The full-screen sky was previously written first then over-painted
by terrain — sky's expensive fragment shader ran on every screen
pixel. Now it only runs on pixels with no terrain in front of them
(depth = 1.0 cleared), which on most views is 30–60% of the screen
instead of 100%.
3. fbm2 reduced from 4 → 3 octaves. Negligible visual change at the
scales we sample, ~25% cheaper per cloud-pixel.
4. Cloud branch skips entirely when day_strength < 0.05 (full night).
Clouds invisible at night anyway, fbm + smoothstep + mix skipped.
5. In-game FPS HUD (top-right corner):
- Telemetry struct gains frame_dt_ms (EMA-smoothed in app.rs
with coefficient 0.85 so the number is readable, not flickery).
- wasm bridge: get_frame_dt_ms().
- main.js setupFpsHud() polls it at 5Hz, color-coded:
green ≤ 18ms (≥55fps), amber 18-33ms, red beyond.
- Reads what THE GAME measures, not the browser's
requestAnimationFrame which gets throttled to 1 Hz on
unfocused windows.
No features removed. God rays, FXAA, ACES tonemap, bounce baking,
specular materials, leaf translucency — all still there. Tests:
63 passing. Wasm release clean.
The death overlay sat at z-index 100 while the settings menu sat at
z-index 60, so a player who died and then opened the menu (or whose
respawn timing overlapped with opening the menu) would see the red
death curtain on top of every settings widget. Worse, the overlay
also applies `backdrop-filter: blur(2px)` which would have tinted the
menu visibly even if z-order had been fixed differently.
Fix: a single CSS rule
body.menu-open #death { display: none; }
makes the menu and death overlays mutually exclusive whenever the
menu is open. The death overlay returns immediately when the menu is
closed (assuming the player is still dead). Verified live in the
running browser via the test harness:
body.dead alone → death visible (display: flex)
body.dead + body.menu-open → death hidden (display: none)
body.menu-open removed → death visible again
No JS changes needed — purely a stylesheet fix.
Diagnosis (from earlier tick/toc data + literature review):
- Page load was dominated by the per-vertex sky_visibility bake
inside build_chunk_mesh: 8 cosine-weighted hemisphere rays × ~15
voxel DDA steps × HashMap-backed World::get_block per ray, per
vertex. ~100ms/chunk × 289 chunks = ~29s on the main thread.
- The greedy mesh algorithm itself was fine; the bake was the bug.
- State of the art (cgerikj's binary greedy meshing) runs 50-200µs
per chunk, but that assumes Lysenko's cheap local AO, not a
global hemisphere ray cast. Our problem was the wrong primitive,
not the wrong algorithm.
Fix (this commit):
- world.rs gains a HeightMap type — per-chunk 16×16 i32 array of
topmost-solid-Y. Cached in World.heightmaps, invalidated by
set_block per affected chunk.
- sim/lighting.rs gains compute_ambience_fast(): inverse-distance-
weighted 7×7 column scan. ~25 array lookups per vertex instead
of 8 ray casts. The 1/sqrt(r²+1) weighting makes the center
column dominate, so a slab right overhead correctly produces
near-zero sky_vis even though the 7×7 window extends past the
slab's edges. The old compute_ambience stays around (renamed
"slow path" in doc) so the construction-invariance test still
has the rigorous reference to compare against.
- mesh.rs: warm_heightmaps_around(chunk) pre-populates the
heightmap cache for this chunk + 8 neighbors before build_chunk_mesh.
build_chunk_mesh calls compute_ambience_fast.
- render/mod.rs::rebuild_chunk takes &mut World now (to warm
heightmaps) and tightens its tick/toc threshold to 0.5ms so the
fast path is observable in telemetry.
Progressive chunk loading (this commit):
- App.pending_chunk_builds: VecDeque<IVec3>, populated at init
spatially sorted closest-first so the chunk under the player
meshes first and the distant horizon fills in last.
- App::tick now drains the queue at a 12ms-per-frame budget.
Browser stays responsive; world appears immediately and
completes over ~2s.
Measured (locally, fresh browser cache):
Before: window.voxel_game ready in ~32,000 ms
After: window.voxel_game ready in 367 ms (~90× faster)
Chunk-build time: 100ms → < 0.5ms each (sub-threshold for logging)
Tests: 63 passing. Native + wasm release clean.
Deferred to its own session: binary greedy meshing (cgerikj-style
64-bit bitmask scan). After this commit it's the next bottleneck
worth attacking; not before.
run.sh:
- phase() wrapper logs elapsed seconds per build step.
- Tracks total build+startup at the end.
- Output is "==> phase / [Ns] phase" so the slow steps are obvious.
test/run.py:
- Per-step time.perf_counter() around each scenario step.
- "slowest steps" summary printed at the end so the worst
offenders are immediately visible.
- Total wall-clock time at scenario end.
src/render/mod.rs:
- browser_now() helper: web_sys::performance().now() on wasm,
Instant-based on native. Monotonic ms timestamps for tick/toc.
- Renderer::rebuild_chunk wraps build_chunk_mesh in a t0/t1
measurement and logs anything over 5ms with vertex/index counts.
Surfaces sky_visibility cost in the browser console.
web/main.js:
- Exposes window.voxel_game = wasm after init so the test
harness can drive scenarios declaratively (set_scene_time,
teleport, look_at, get_position, etc.).
src/shader.wgsl:
- Fix duplicate `let to_eye` declaration introduced in Round D
(specular's normalized to_eye conflicted with fog's raw version).
Renamed fog's local to_eye_raw. The test harness caught this
immediately — first WGSL compile error, first scenario run.
Findings from running scenarios/lighting-times-of-day.yaml:
- 289 chunks × ~100ms avg = ~29s mesh-build on main thread.
- Page-ready latency dominated by this. window.voxel_game appears
almost immediately (init resolves before chunks build), but
the world is invisible until meshes are uploaded.
- sky_visibility (8 cosine rays × HashMap voxel lookups) is the
hot path inside build_chunk_mesh.
Next: make chunk-mesh build progressive (one or two chunks per tick
instead of all up-front), so the world becomes visible immediately
and pops in over a few seconds.
Testing is a dev process — point the harness at a local build you can
edit, rebuild, and screenshot in seconds. Pointing it at the prod
deploy by default was wrong: the deploy lags local code by a deploy
cycle, so visual changes you make wouldn't appear there until rebuilt
on the Linode.
test/launch.py:
- DEFAULT_URL is now http://localhost:8080/.
- Friendly pre-flight check: if --url is localhost and nothing is
listening on the port, print a clear "start ./run.sh --no-tunnel"
message and exit 1. Avoids the silent ERR_CONNECTION_REFUSED
failure mode.
- --url https://voxel.mxvs.art/ still works for one-off remote
sanity checks.
test/README.md:
- Lead with the dev-loop instruction: terminal 1 runs the local
server, terminal 2 runs launch.py, terminal 3 drives scenarios.
- Note the "pointing at deploy" path as a rarely-used escape hatch.
Mirrors the cucucaracha (lacucarachanews) toolkit pattern adapted for
the voxel game:
bridges.rs adds TestCommand + Telemetry plumbing:
- thread_local TEST_COMMANDS queue + TELEMETRY snapshot.
- drain_test_commands() called by App::tick at frame start.
- publish_telemetry(t) called at frame end.
- wasm_api exports: set_scene_time, teleport, look_at, plus
getters get_scene_time / get_position / get_camera_angles.
app.rs:
- drain_test_commands() applies SetSceneTime / Teleport / LookAt
before physics integrates. Teleport zeroes velocity and syncs the
camera to feet+EYE_HEIGHT.
- publish_telemetry() at end of tick exposes scene state to JS.
test/:
launch.py Open Chromium with persistent profile + CDP:9222.
Navigates to https://voxel.mxvs.art by default;
--url for local dev.
peek.py Attach via CDP, screenshot canvas, dump telemetry
(scene_time, position, camera angles, hp). Read-only.
run.py Execute a YAML scenario:
wait_for, wait, eval, key, mouse_move, mouse,
screenshot, assert
Key allowlist prevents stray scenarios from sending
arbitrary input.
requirements.txt playwright + PyYAML.
README.md Setup, grammar, available bindings, why this
exists.
scenarios/
lighting-times-of-day.yaml Screenshots at noon / afternoon /
sunset / civil twilight / midnight
/ sunrise. Verifies the Round A
sunset fixes by visual diff.
god-rays-look-at-sun.yaml Pointed at the sun at four altitudes
to inspect the Round B shafts.
voxel-construction-darkness.yaml Visual baseline for the sky_vis
bake from Round D.
.gitignore Excludes the browser profile +
screenshots directory.
Visual regression workflow:
1. python3 launch.py
2. (separate terminal) python3 run.py scenarios/lighting-times-of-day.yaml
3. Compare screenshots/lighting-times-of-day_*.png against baseline.
Tests still 63 passing. Native + wasm release clean.
sim/lighting.rs:
- New compute_ambience(world, pos, normal) -> VertexAmbience
returns BOTH sky_vis AND bounce_color from the same 8-ray
hemisphere cast. No double walks of the voxel grid.
- walks_until_solid(world, origin, dir) -> Option<Vec3> is the
primitive: None = escaped to sky, Some(color) = first solid hit.
Used by compute_ambience to accumulate the bounce_color average.
- sky_visibility is now a thin wrapper around compute_ambience for
tests and clarity.
world.rs:
- Block::average_color() returns the mean across all 6 faces — the
contribution this block makes to a neighbor's bounce when hit by
a hemisphere ray.
- Block::material_id() returns 0 (matte) for most blocks, 1
(specular) for Ice + Snow. Reserved 2 for future emissive blocks.
mesh.rs:
- Vertex grows `bounce_mat: [f32; 4]` packing baked bounce color
(rgb) + material id (a). Float32x4 attribute at @location(6).
- build_chunk_mesh now calls compute_ambience for each quad corner
(same one-pass ray-cast that produced sky_vis already, plus the
bounce accumulation). Material id taken from cell.block.
shader.wgsl:
- VsIn / VsOut grow bounce_mat (vec4).
- ambient_term now takes the per-vertex bounce_albedo instead of a
hard-coded gray-brown. A red brick wall thus casts a faint red
bounce on dirt next to it — real GI hint, baked once at mesh
time, zero cost at runtime per fragment.
- material_for(id) lookup: Phong specular for ice/snow (m.specular
= 0.45 with cos⁴⁸ half-vector); emission slot reserved.
- fs_main pipeline now includes the specular + emission terms.
- Camera.frame keeps Round C accessor names; ambient_strength
untouched.
Tests: 63 passing. Native + wasm release clean.
Deferred from this round (own sessions): #18 water (new pipeline +
animation), #19 transparent/cutout (new blend state), #8 wider AO
(current 4-corner is sufficient for now; the wider-occlusion effect
is now coming through bounce_color anyway).
Visual change: bounce-tinted ambient (red walls glow red onto
neighbors); ice + snow get specular highlight in direct sun.
shader.wgsl:
- Camera.frame layout now documented slot-by-slot in the struct
comment; named accessors scene_time() / exposure_bias() / eye_world()
so call sites read as intent. exposure_bias plumbed (default 1.0)
as the foundation for a future Settings.exposure slider. [#20]
- Leaves now get sun-aware backlit translucency: leaf_translucency()
peaks when the sun rakes across the leaf plane AND comes from
behind the surface. Cheap stand-in for subsurface scattering —
reads as "dappled sun through canopy" without per-pixel ray
sampling. [#25]
render/mod.rs:
- run_fullscreen_pass(encoder, label, target, pipeline, bgs, clear)
helper. The three post-chain steps (mask → shafts → composite)
are now three sequential calls instead of three copies of the
same begin_render_pass boilerplate. Adding a new effect (bloom,
motion blur, vignette) is one extra row. [#23]
- upload_camera fills frame[1] = 1.0 (exposure_bias default).
render/uniform.rs:
- CameraUniform.frame doc updated to enumerate each slot.
Tests: 63 passing. Native + wasm release clean.
New WGSL files:
mask.wgsl Sun-cone × sky-alpha mask at ¼ resolution. Marks sky
pixels (scene_color.a == 0) that fall within a tight
cone around the sun direction. Sun direction derived
from scene time via the injected DAY_PERIOD /
SUN_OFFSET constants — same source as sim::lighting,
so visual rays align with the mechanical sun.
shafts.wgsl Radial blur at ¼ resolution. Projects the sun
direction-at-infinity to screen space via view_proj,
steps 32 samples from each pixel toward the
sun_screen_pos accumulating mask intensity with
exponential decay, outputs sun-tinted ray color.
shader.wgsl:
- fs_sky now writes alpha = 0 so the mask pass can identify sky
pixels without a separate occluder pass. Terrain / outline /
remote-player pipelines continue writing alpha = 1.
post.wgsl (rewritten):
- Reads scene_color + shafts.
- Cheap edge-aware FXAA (5-tap diagonal blur, blends toward neighbor
average where luminance gradient exceeds threshold). Catches the
axis-aligned staircase aliasing that voxel games produce.
- Adds shafts additively before tonemap so rays go through the
filmic curve and don't blow out.
render/scene_target.rs:
- create_image_bind_group (single texture + sampler) — used by
mask pass (binds scene_color) and shafts pass (binds mask_view).
- create_composite_bind_group (scene + shafts + sampler) — used by
the final post pass.
- create_quarter_res_view (¹⁄₁₆ fillrate, RENDER_ATTACHMENT +
TEXTURE_BINDING) — used for both mask and shafts targets.
render/pipelines.rs:
- image_bgl / composite_bgl as separate layouts.
- fullscreen_pipeline factory replaces the post-specific one;
takes vs/fs entry-point names so mask, shafts, and post all
build through the same shape.
render/mod.rs:
- Renderer grows mask_view, shafts_view, image_bgl, composite_bgl,
mask_pipeline, shafts_pipeline, mask_bg, shafts_bg fields. The
old single-pass post_pipeline becomes the final composite pass.
- render() now does scene → mask → shafts → post (each in its own
encoder block).
- resize() recreates all three render targets and all three bind
groups in the right order.
Tests: 63 passing (added 2 for mask/shafts source assembly). Native
+ wasm release clean.
Visual change: when you face roughly toward the sun and there's
geometry blocking the disc, you'll see warm light shafts radiating
outward. FXAA softens the worst pixel-step edges. Tonemap (from
Round A) is now the final step of the new pipeline.
shader.wgsl:
- sky_dome: zenith now tints toward a dusky-purple zenith_twi during
twilight (was previously only the horizon picking up the warm tint).
Top faces at sunset will read warm through the sky_vis pathway
instead of staying cold blue. [#1]
- apply_fog: at twilight the fog tints toward sun_tint by twi×0.45,
so distant terrain reads warm against an orange sky instead of
cold. [#2]
- sky_color stars: gate flipped from (1 - day) — which still showed
stars during dusk while the sky was bright — to a direct
smoothstep on sun.y (-0.22..0.04). Stars now fade in only after
civil twilight. [#3]
- sun disc / halo: sharpness + intensity now altitude-dependent. At
zenith it's a sharp pinpoint (sharpness 800, intensity 1.5); near
the horizon it softens to a big atmospheric bloom (sharpness 160,
intensity 2.2). Halo also widens and brightens at low sun. [#4]
post.wgsl:
- ACES filmic tonemap (Narkowicz approximation) runs as the final
step. Brightens midtones, compresses highlights smoothly into
[0,1] instead of the previous hard clamp. Output stays linear; the
sRGB surface handles display encoding. Foundation for everything
HDR that follows (god rays, bloom). [#6]
The "side faces don't adjust to daytime ambiance" bug was caused by
conflating geometric sky visibility with radiometric sky intensity
into a single ambient_strength knob. This commit separates them.
sim/lighting.rs:
- Refactor: extract walks_to_sky(world, origin, dir) -> bool as the
shared DDA primitive. is_in_direct_sun now calls it.
- New: sky_visibility(world, pos, normal) -> f32. Casts 8 cosine-
weighted hemisphere rays through the voxel grid (Hammersley(2)
distribution, deterministic). Returns fraction that escape to
the world top. Pure function of (world, position, normal) — depends
only on the surrounding voxel construction. Architecturally, this
means a player-built sealed roof on the surface produces the same
sky_vis as the same enclosure underground; no "is this the surface
or underground?" hack anywhere.
- 4 new tests including the construction-invariance test that pins
"same enclosure geometry → same sky_vis regardless of world Y".
mesh.rs:
- Vertex gains a sky_vis: f32 field at @location(5).
- build_chunk_mesh computes sky_vis per quad corner via
sky_visibility (one ray-walk per vertex; amortized at mesh build,
free at runtime).
- emit_oriented_box sets sky_vis = 1.0 for remote-player boxes
(they float in open air).
- 2 new tests: open-top has high sky_vis, slab-covered top has low.
shader.wgsl:
- VsIn / VsOut grow @location(5) sky_vis: f32.
- ambient_term rewritten as the principled split:
sky_radiance(N) × sky_vis + bounce × (1 − sky_vis)
where bounce is sun-tinted ground albedo scaled by day. No more
`face_up = normal.y * 0.5 + 0.5` flat hemisphere assumption — the
per-vertex geometric weight does the work.
- ambient_strength bumped from mix(0.25, 0.85, day) to mix(0.35,
1.00, day) since sky_vis now carries the geometric attenuation.
Result: side faces in the open get bright sky-colored ambient at noon;
side faces in pits dim correctly; player-built shelters darken by
construction without any time-of-day weirdness. Same model also sets
up the bounce-color bake (Phase 2) and the CSM shadow infrastructure
(Phase 3) — both extend the per-vertex visibility-attribute pattern
introduced here.
Tests: 61 passing (up from 53). Native + wasm release + server clean.
Documents every module's responsibility, the tick pipeline, the
sim::lighting shared-truth invariant (sun direction shared between
Rust and WGSL via shader_source.rs), and the test coverage. Companion
to DEPLOY.md — that one covers ops, this one covers code.
state.rs is gone. Its content split by responsibility:
src/bridges.rs (~290 lines)
The only place we own shared mutable state. Holds the four
thread_locals (touch input, game status, network, settings) and
the wasm-bindgen JS interface that mutates them. Exposes a typed
accessor API — current_settings(), snapshot_touch_bridge(),
with_touch_bridge(f), is_touch_mode(), clear_touch_inputs(),
take_respawn_request(), set_status(hp, alive), take_inbox(),
push_outbox(msg), with_net_bridge(f), net_connection_snapshot(),
is_connected(), set_my_id(id), snapshot_remote_players(). Callers
never touch the RefCells; if storage ever moves to a Mutex or
OnceCell, only this file changes.
src/app.rs (~510 lines)
The App + winit ApplicationHandler + tick + drain_net_inbox +
do_respawn + render_frame + FrameClock. Uses the bridges
accessors instead of poking thread_locals directly, so the call
sites read as a pipeline rather than a chain of `.with(|x|
x.borrow_mut())`.
src/lib.rs
Modules now declared in alphabetical order:
app, bridges, camera, mesh, net, proto, render,
shader_source, sim, world.
`run()` constructs `app::App::default()` instead of the old
`state::App`.
src/render/mod.rs
`use crate::bridges::RemotePlayer` (was `crate::state::`).
Net effect of the four phases combined: state.rs at the start of
alpha-0.0.2 was 2500 lines doing everything; today the same logic
spans nine focused modules totalling ~3000 lines (with full doc
comments). 53 tests pass, native + wasm release build green, server
build green.
state.rs is now 870 lines (down from 1700+). All GPU code moved to a
dedicated render/ module.
New src/render/:
mod.rs Renderer struct + impl with all methods; the only
place that owns wgpu device/surface/pipelines. The
wasm-only WebGPU probe + compat-error overlay live
here as a private wasm_compat sub-module.
pipelines.rs Pipeline factory functions: camera_bgl, post_bgl,
pipeline_layout, sky_pipeline, terrain_pipeline,
outline_pipeline, post_pipeline. Each takes
device + shader + format and returns a configured
wgpu::RenderPipeline — pure factories, no hidden
state.
scene_target.rs create_depth_view, create_scene_color_view,
create_post_bind_group — fresh-resource builders
called from Renderer::new and Renderer::resize.
uniform.rs CameraUniform (matches WGSL camera.frame layout),
OutlineVertex, ChunkBuffers.
state.rs:
- drops ~760 lines of pipeline + scene-target plumbing
- imports Renderer from crate::render
- keeps App + tick + drain_net_inbox + thread_locals + wasm_api
Tests: 53/53 pass. Native + wasm release build clean.
shader.wgsl restructured:
- Section headers: Camera → Sky horizon → Atmosphere extras → Terrain
lighting decomposition → Pipelines.
- sky_dome() is now the single source of truth for the horizon→zenith
mix; sky_color() builds on it instead of duplicating the gradient.
- fs_main decomposed into named helpers:
ambient_term(n, sun, day) hemisphere ambient via sky_dome lookup
direct_sun_term(n, sun) Lambert × visibility ramp
leaf_jitter(world_pos) per-pixel canopy variation
fog_factor(dist) 0..1 fog ramp
apply_fog(lit, dist, view) defers sky_color call until needed
- Camera.misc renamed to Camera.frame with named accessors
scene_time() / eye_world() so callsites read intent.
- DAY_PERIOD / SUN_OFFSET REMOVED from the shader — injected at the
top by shader_source::wgsl_constants_header(). One source of truth
in sim::lighting now drives both Rust and WGSL; mob burn and
visible sun direction can never disagree.
New src/shader_source.rs:
- wgsl_constants_header() Rust → WGSL constants prelude
- terrain_shader_source() header + shader.wgsl, used at Renderer::new
- post_shader_source() pass-through
state.rs CameraUniform:
- misc → frame to match the renamed WGSL field
- Renderer uses the assembled shader source instead of include_str! directly
Tests: 53 passing (added 2 shader_source assembly tests). Native build,
wasm release build, server build all green.
New modules:
src/sim/lighting.rs - DAY_PERIOD, SUN_OFFSET constants; sun_direction,
day_strength, twilight_amount, LightingFrame::at;
is_in_direct_sun(world, p, t) via 3D DDA — the
mechanical sunlight predicate that future mob
burn / plant growth / shade pathfinding will all
consume. Mirrors the shader's sun math exactly
(Phase 2 will wire the WGSL side to consume the
same constants from this module).
src/sim/visibility.rs - compute_visible_chunks moved out of state.rs;
frustum_planes + chunk_in_frustum decomposed.
Moves into mesh.rs:
emit_oriented_box, name_hash + their tests. These are mesh utilities
(Vertex output, color hash for remote-player boxes), not GPU shell.
state.rs:
- drops the moved functions
- imports compute_visible_chunks / emit_oriented_box / name_hash from
their new homes
- 230 lines lighter
Tests: 51 passing (up from 45). New coverage: sun-below-horizon=>night,
open-sky-at-noon-is-lit, occluded-by-overhead-block, ramp shapes match
the WGSL smoothstep, name_hash determinism.
Records the live production state (Linode IP, paths, redeploy command,
firewall + fail2ban + SSH hardening, TLS via Caddy, DNS via Namecheap
Advanced DNS, rollback steps, troubleshooting checklist) so a fresh
session can pick this up without re-deriving any of it.
Reshape the engine into a functional-core / imperative-shell split.
The 2500-line state.rs blob is now 1700 lines of mostly GPU plumbing
plus a thin tick() shell that composes pure transformations from the
new sim/ and net/ modules.
src/sim/ (no GPU, no winit, no thread-locals — all pure):
body.rs PlayerBody value type + take_damage / respawned_at
collision.rs AABB primitives, sweep_axis returning (Vec3, bool)
instead of mutating &mut Vec3
edit.rs block_from_u8, apply_edit, chunks_for_edit
event.rs SimEvent enum (Landed, VoidDeath, BlockEdited)
input.rs TouchBridge data type + merge_held
physics.rs step_movement(world, body, MoveInput) -> MoveOutcome
— the central morphism: one tick of player movement
+ collision + landing detection + void check, returns
a new body value and a list of events
spawn.rs find_safe_spawn, fall_damage
src/net/:
parse_inbox(Vec<String>) -> Vec<NetEvent>
Malformed lines drop silently; the shell folds typed events into
the world / remote-player map.
src/state.rs:
- App now holds a single PlayerBody value instead of scattered
velocity / on_ground / hp / alive / max_y_since_ground fields.
- tick() is a pipeline: collect input → merge_held → step_movement
→ fold sim events → block interaction → render_frame.
- drain_net_inbox() parses to events first, then applies.
- render_frame() extracted so the paused and active branches share
the upload + cull + draw path.
Tests: 45 passing (up from 33). New coverage for the physics step
itself: airborne gravity, jump-only-when-grounded, long-fall-emits-
Landed, void floor, dead-body-does-not-move. Net parsing tests for
malformed lines and round-trips. Body tests for damage / respawn.
Build: cargo test (45/45), cargo build --target wasm32-unknown-unknown
--lib --release, and the axum server all green.
Multi-stage Dockerfile compiles wasm client + axum server in one Rust
builder and copies into a debian:bookworm-slim runtime (non-root uid).
docker-compose.yml binds localhost:8080 by default; docker-compose.prod.yml
replaces ports with a Caddy reverse proxy on host 80/443 that talks to
the voxel container over the internal network. Caddy auto-issues Let's
Encrypt certs.
DEPLOY.md covers the three deployment modes (local-only, VPS with
Cloudflare or Caddy, Cloudflare Tunnel from a workstation).
- Greedy meshing now bakes per-vertex AO with 4-corner sampling and an
anisotropic-diagonal split when corner AO disagrees.
- WGSL: extracted sky_dome() for hemisphere ambient sampling so vertical
faces match the sun-side sky tint at day; ambient_strength mixed by
day strength instead of a flat constant.
- Step-1 post pipeline: render scene into an offscreen color texture,
pass-through to the surface. Foundation for FXAA/shafts that will
follow.
- Input bug: merge_held() now recomputes per tick from sticky keyboard +
live touch bridge, so releasing the joystick actually stops the
player (previous OR-into-self bug ate playtests).
- Touch UI hit-zones reordered (menu/hotbar above the joystick z-index);
hotbar widened to 10 slots with tap-to-select on mobile.
- find_safe_spawn anchors on natural_surface_y so spawn is deterministic
from noise — towers built at spawn no longer climb the spawn point.
- move_axis is sub-stepped (0.45-block max) so high-velocity falls can't
teleport the player inside terrain.
