A 4D rendering engine in Rust. See real-time 3D cross-sections of 4D geometry. Heavily inspired by Engine4D by Code Parade
Alpha Stage - Core rendering and physics are functional, but the API may change.
What works:
- 4D to 3D slicing via compute shaders
- Real-time navigation in 4D space
- Basic 4D physics with gravity and collisions
- Multiple 4D primitives (tesseract, hyperplane)
- FPS-style camera controls with 4D extensions
- Scene serialization and loading (RON format)
- Configuration system (TOML with env var overrides)
- 4D spatial audio with bus routing (Master/Sfx/Music/Ambient)
- Lua 5.4 scripting with lifecycle callbacks and hot-reload
- HUD system with sprites and particles
- Game utilities: EventBus, StateMachine, TweenManager
What's in progress:
- More 4D shapes (hypersphere, 4D prisms)
- Advanced collision detection
Imagine you're a 2D being living on a flat plane. If a 3D sphere passes through your plane, you'd see it as a circle that grows, reaches maximum size, then shrinks and vanishes. You're seeing 2D cross-sections of a 3D object.
Rust4D does the same thing, but one dimension higher.
We take 4D objects (like a tesseract, the 4D analog of a cube) and slice them with a 3D hyperplane. What you see on screen is a 3D cross-section of 4D geometry. Move along the W-axis (the 4th spatial dimension) and watch shapes morph in ways impossible in 3D:
- A tesseract appears as a cube, morphs into complex polyhedra, then back to a cube
- Objects can pass "through" each other by taking different paths in W
- The floor extends infinitely in 4D, but you only see the slice at your W position
This is not just a visualization trick - the engine actually computes 4D geometry and performs true 4D physics.
- True 4D Geometry: tesseract, hypersphere, spherinder, cubinder, duocylinder, and the regular 5-cell/16-cell/24-cell/600-cell — all mathematically defined in 4D space
- GPU-Accelerated Slicing: Compute shaders slice tetrahedra in parallel
- 4D Physics: Gravity, collision detection, and rigid body dynamics in 4D
- FPS-Style Controls: Navigate 4D space with intuitive WASD + Q/E controls
- Modular Architecture: 8 specialized crates for math, core, render, physics, input, audio, scripting, and game logic
- Configuration System: TOML-based configuration with environment variable overrides
- Cross-Platform: Runs on Windows, macOS, and Linux via wgpu
Rust4D is organized as a Cargo workspace with 8 specialized crates:
rust4d/ # Main application
crates/
rust4d_math/ # 4D vector and matrix math
rust4d_core/ # World, entities, transforms, shapes
rust4d_render/ # GPU rendering pipeline, Camera4D, HUD, sprites, particles
rust4d_physics/ # 4D physics simulation
rust4d_input/ # Input handling and camera controller
rust4d_audio/ # 4D spatial audio with kira, bus routing
rust4d_scripting/ # Lua 5.4 scripting with hot-reload
rust4d_game/ # CharacterController4D, EventBus, StateMachine, TweenManager
See ARCHITECTURE.md for detailed diagrams and data flow.
- Rust 1.70 or later
- A GPU with Vulkan, Metal, or DX12 support
# Clone the repository
git clone https://github.com/Lemon9247/Rust4D
cd Rust4D
# Run the main application
cargo run --release
# Or try an example
cargo run --example 01_hello_tesseractOn NixOS (or with Nix installed), use the dev shell — it provides the Rust toolchain, Vulkan wiring, and the imaging tools used for visual verification:
nix develop
cargo test --workspace
# Headless rendering verification: captures protocol frames as PPM images
# plus numeric slice-plane logs, without opening a window
cargo run --example headless_protocol .scratchpad/capturesThe examples are the best way to learn Rust4D. They progress from simple to complex:
# 1. Minimal setup - just a tesseract
cargo run --example 01_hello_tesseract
# 2. Multiple shapes with keyboard movement
cargo run --example 02_multiple_shapes
# 3. Physics simulation with falling objects
cargo run --example 03_physics_demo
# 4. Full camera controls - explore 4D space
cargo run --example 04_camera_explorationSee examples/README.md for detailed descriptions.
Configuration is loaded from TOML files with environment variable overrides:
config/default.toml- Default settings (checked into git)config/user.toml- Your personal overrides (gitignored)- Environment variables with
R4D_prefix
[window]
title = "Rust4D - 4D Rendering Engine"
width = 1280
height = 720
[camera]
start_position = [0.0, 0.0, 5.0, 0.0]
fov = 45.0
[input]
move_speed = 3.0
w_move_speed = 2.0
mouse_sensitivity = 0.002
[physics]
gravity = -20.0
jump_velocity = 8.0# Override window title
R4D_WINDOW__TITLE="My 4D Game" cargo run
# Override physics gravity
R4D_PHYSICS__GRAVITY="-10.0" cargo run| Input | Action |
|---|---|
| WASD | Move in XZ plane |
| Q/E | Move along W-axis (4th dimension) |
| Space/Shift | Move up/down |
| Mouse | Look around |
| Right-click drag | Rotate through W |
| Scroll | Adjust slice offset |
| R | Reset camera |
| F | Fullscreen |
| G | Toggle input smoothing |
| ESC | Release cursor / Quit |
See examples/README.md for the full example index and learning path.
| Example | Description |
|---|---|
| 01_hello_tesseract | Minimal 4D rendering setup |
| 02_multiple_shapes | Multiple objects with transforms |
| 03_physics_demo | Physics with gravity and collision |
| 04_camera_exploration | Full camera controls |
| Guide | Audience |
|---|---|
| Getting Started — installation, first steps, 4D concepts | New users |
| User Guide — full feature reference | All users |
| Developer Guide — architecture, algorithms, testing, contributing | Contributors |
| The Mathematics of Rust4D — rotors, SkipY, slicing, the slice invariant, conventions | Contributors |
| Shape Catalog — built-in 4D primitives, construction math, RON snippets, verification | Users & contributors |
| ARCHITECTURE.md — crate structure and data flow | Contributors |
- 4D Golf - Camera controls based on this
- 4D Toys - 4D physics visualization
- Miegakure - 4D puzzle platformer
- Engine4D - Original inspiration
MIT