Skip to content

Pin Helio's voxel octree, per-voxel materials and material contract - #1395

Draft
Tuafo wants to merge 5 commits into
mainfrom
claude/voxel-ray-guided-residency
Draft

Tuafo wants to merge 5 commits into
mainfrom
claude/voxel-ray-guided-residency

Conversation

@Tuafo

@Tuafo Tuafo commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

This pins Helio to the voxel planet work in Far-Beyond-Pulsar/Helio#353 (draft) and updates Pulsar for it.

What the Helio pin brings

The pin moves from 819dff8f to 1dcc418f, which contains Helio main (90b34047, the pin on Pulsar main).

  • Chunk octree. A 3D chunk octree with ray-guided residency and a footprint pool.
  • Per-voxel materials. Edited cells and dug walls draw their own material instead of their leaf's. PickHit reports the drawn material.
  • Material contract. The generation kernel now evaluates materials as Planet::material does. Picks, dig yields and drawn colours agree, where 40.5% of natural mountain pixels used to differ.
  • Edit index. A brush index replaces the per-chunk scan of every brush.
  • Edits on data. Large brushes are baked into the data, so 10,000 large digs cost about what 100 do. Edited chunks the renderer evicts are kept and come back by copy.
  • Kept chunks in saves. A journal can carry the renderer's chunks for its edits (VoxelKeptChunks, saved as kept), and the pass loads and exports them through its frame.

Pulsar changes

  • voxel_backend.rs: the edit-ray test builds a PickHit, which gained material. It's set to 0, since an edit ray takes the cell.
  • Saves keep the edited chunks (342598aed). A loaded level copies what its edits made, instead of generating it from the terrain and every edit.
    • HelioRenderer owns a VoxelChunkSaves request/answer handle. The planet backend answers it, and the editor gets it through HelioEditorMailbox and keeps it in SceneDomain.voxel_chunk_saves.
    • save_blocking runs keep_voxel_chunks after compacting the journals. It asks only when a terrain has edits but no kept chunks, and waits up to 5 s.
    • The backend has its pass pack the chunks through PlanetFrame.export. It answers for the journal the shown planet was built from, and asks again if the world changed meanwhile.
    • The save deflates the chunks off the render thread. It keeps them only if the journal is unchanged; any later edit drops them.
    • A rebuilt world parses the journal's kept chunks on the world-builder thread and passes them in PlanetFrame.kept. The pass loads them into the new world.
  • Pin exception: .github/submodule-pin-exceptions.txt lists the Helio pin, because Helio#353 isn't on Helio main yet. Once it merges, re-pin to Helio main and delete the line.
  • Docs: 0158ee23c makes the voxel system docs describe the chunk octree.
  • Merge: Pulsar main is merged in. The only conflict was the Helio gitlink, resolved to the new pin.

Merge order

  1. Merge Helio#353 into Helio main.
  2. Re-pin crates/renderer/helio to that main commit and drop the exception line.
  3. Merge this PR.

Tests

  • cargo test -p engine_backend voxel: 28 tests pass against the new pin.
  • New voxel_kept_chunks (engine_backend, headless editor renderer). A save waiting on another thread is answered in 7 frames with 90 chunks (105 KiB). A new renderer given the saved journal loads all 90.
  • New a_level_save_keeps_the_renderers_voxel_chunks (ui_level_editor). It runs the editor's real save while the viewport draws; the written level loads with the same journal and its kept chunks. All 9 ui::save tests pass.
  • scripts/submodule-pins.sh check passes, with the Helio pin listed as an exception.
  • Helio's own suites are in Helio#353. All voxel tests pass; two camera-relative tests in helio-default-graphs fail the same way on Helio main.

🤖 Generated with Claude Code

Tuafo and others added 3 commits October 15, 2026 19:11
Residency is a cut of a 3D chunk octree with ray-guided refinement;
diagnostics report drawn nodes, footprints and ray reports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Helio e6371f37 (Far-Beyond-Pulsar/Helio#353, a draft; listed in the pin
exceptions until it lands on Helio main): the 3D chunk octree with
ray-guided residency, per-voxel materials for edits and dug walls, the
generation kernel's materials matching Planet::material, and Helio main
merged. PickHit gained the drawn material; the edit-ray test sets it to 0
(an edit ray takes the cell).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed-residency

# Conflicts:
#	crates/renderer/helio
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Tuafo Tuafo self-assigned this Oct 16, 2026
@Tuafo Tuafo moved this from Todo to In Progress in Pulsar Tracker Oct 16, 2026
A level save now keeps the voxel planet renderer's chunks of the terrain's
edits with its journal, so a loaded level copies what the edits made
instead of generating it from the terrain and every edit.

- HelioRenderer owns a VoxelChunkSaves (request/answer, condvar), given to
  the planet backend and to the editor through HelioEditorMailbox; the
  level editor keeps it in SceneDomain.voxel_chunk_saves.
- save_blocking, after compacting the journals, asks for the chunks when a
  terrain with edits keeps none (keep_voxel_chunks, waiting up to 5 s);
  the backend has its pass pack them (PlanetFrame.export), answers for the
  journal its shown planet was built from, and the save deflates them off
  the render thread and keeps them only while the journal is unchanged.
- A rebuilt world parses the journal's kept chunks on the world builder
  thread and passes them in PlanetFrame.kept; the pass loads them into
  the new world.

Helio 1dcc418f (Far-Beyond-Pulsar/Helio#353): kept chunks travel with the
journal and the frame, not the edit snapshot.

Tests: voxel_kept_chunks (90 chunks, 105 KiB, answered in 7 frames; a new
renderer loads all 90) and a_level_save_keeps_the_renderers_voxel_chunks
(the editor's save while the viewport draws; the level loads with them).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

1 participant