HyperCraft

HyperCraft is an experimental four-dimensional voxel sandbox. The player observes an oriented 3D slice of a 4D world and rotates that slice through the XW, YW, and ZW planes.

Run

nix develop
cargo run

The application uses egui with its wgpu renderer. Hover the viewport and use the mouse wheel to rotate the active slice plane. In the default Orbit camera, right-drag orbits, middle-drag or Shift-right-drag pans, and Ctrl-mouse-wheel zooms; left-click removes a block and Shift-left-click places one. Select Explore in the Slice inspector and click the viewport for first-person mouse look; use WASD to move within the current 3D slice, Space to jump, Ctrl to sprint, and Escape to release the mouse. Gravity, jumping, and collision are resolved in the current slice. The player's X/Y/Z/W position is authoritative four-dimensional state; movement is transformed through the current slice orientation, while rotating the slice changes the observed 3D plane around the same player position. A slice rotation that would put solid geometry inside the player is rejected. In Explore, left-click removes the targeted block and right-click places the selected material on the hit face. Every solid voxel whose 4D hypercube intersects the slice hyperplane is clipped on the CPU: its 32 hypercube edges are intersected, the resulting points are convex-hulled, triangulated, and rendered as the exact 3D cross-section into an off-screen color/depth target.

World edits keep a bounded 256-change history. Use Ctrl-Z to undo and Ctrl-Y or Ctrl-Shift-Z to redo (Command on macOS), or use the buttons in the World inspector. The top bar and World inspector indicate when the current state differs from the last successful save or load.

Use the inspector's Save and Load buttons to persist the world as hypercraft.world in the current working directory. Loading validates the complete file before replacing the active world, then rebuilds and uploads the visible slice once.

The inspector is split into Slice, Scene, World, and Stats pages. Each page is designed to fit at the minimum supported window size, so every control is reachable directly without scrolling the inspector.

Layout

• src/app/: application orchestration, viewport interaction, and modular editor UI (panels/chrome, pages, theme, and widgets)
• src/render/: camera state, GPU resources, shader, and egui callback integration
• src/slice/: 4D slice transforms, hypercube intersection, visible-surface cache, and the cache's BVH accelerator (surface/bvh.rs)
• src/world.rs: sparse, chunked 4D voxel storage; world/format.rs owns versioned world-file I/O
• src/app/world_ops.rs: world edits, undo/redo refresh, and save/load session operations
• src/main.rs: window and renderer startup

The rendering surface is intentionally separate from world and slice logic. Before rebuilding a slice, HyperCraft conservatively tests the slice hyperplane against each occupied 4D chunk's axis-aligned bounds, then visits solid voxels only in candidate chunks. Candidate chunks keep reusable mesh caches keyed by their own and their axial neighbors' revisions, so a block edit rebuilds only dependent chunk geometry. Faces shared by solid neighbors are omitted, and a CPU BVH accelerates selection raycasts over the remaining triangles. CPU staging vectors and geometrically growing GPU vertex buffers are reused between rebuilds, and center-screen raycasts are skipped while both the surface and camera remain unchanged. The inspector reports candidate, rebuilt and reused chunks, culled triangles, BVH size, tested blocks, generated geometry, upload size, and the latest CPU rebuild time.

Lighting uses a hybrid raster/ray-tracing pipeline rather than a path tracer. Rasterization writes the visible slice's position, normal, material, and depth buffers. A compute pass then traverses a compact GPU copy of the surface BVH for hard sun shadows, sky visibility, and one-bounce diffuse color bleeding before the selection overlay is rasterized. The ray stage is bounded and non-recursive, so primary visibility remains stable and inexpensive while indirect lighting responds to slice rotation and world edits. Ray-traced lighting is interleaved across alternating pixels and frames, then reconstructed with the edge-aware filter and TAA. The untraced half of the checkerboard no longer repeats G-buffer and analytic lighting work; isolated edge pixels receive a cheap fallback in the denoiser. Static views therefore converge to full-resolution temporal sampling while dynamic frames issue only one third of the previous worst-case BVH ray workload. BVH nodes and triangles use compact GPU-only layouts, and the normal G-buffer uses normalized 8-bit storage to reduce bandwidth without changing geometry precision. Camera and slice motion retain ray-traced hard shadows but temporarily replace short-lived indirect rays with an analytic hemisphere; temporal GI resumes automatically after the view settles. The application requests frames continuously and uses vsync for smooth presentation. A zero-allocation rolling frame-time monitor automatically adjusts only the 3D render target between 100% and 50% resolution when sustained frame time misses the 16.67 ms budget; egui remains at native resolution and the projection is compensated so quality changes do not alter the camera framing. The Stats inspector reports average and 95th-percentile frame time, slow-frame percentage, active render scale, and target resolution.

World files use a little-endian, versioned binary format. Only non-empty chunks and their solid local block entries are stored, so sparse chunks do not serialize their full 8 x 8 x 8 x 8 arrays. Saves are written to a temporary file and atomically renamed into place. The format rejects incompatible versions, chunk sizes, duplicate chunks or block indices, invalid materials, truncated input, and trailing data.

Performance benchmark

The ignored release-mode benchmark compares brute-force solid-voxel slicing with chunk-filtered slicing in a sparse world whose occupied chunks are spread along the W axis:

cargo test --release benchmark_sparse_distant_chunks -- --ignored --nocapture
cargo test --release benchmark_bvh_raycast -- --ignored --nocapture

The benchmarks check that chunk filtering matches brute-force voxel slicing and that BVH raycasts match brute-force triangle tests. Exact timings depend on the machine and build environment.