Cubey is a native C++20/Vulkan workbench for real-time rendering, GPU simulation, and procedural environments. It is a collection of focused visual projects built on a deliberately small shared foundation: enough engine to make the experiments coherent, without turning the repository into a general game engine or editor.
Projects own their scenes, simulation, configuration, and presentation. Shared modules provide the recurring vocabulary—Vulkan resources, render passes, camera and transform math, asset loading, procedural sky and clouds, terrain, PBR, profiling, and deterministic headless capture.
Build and run · Design · Architecture · Roadmap
Five highlights show the workbench's range. Each highlight is an independent eight-second, 720p/60 FPS project story rather than a segment from a combined reel. All five native players and their poster fallbacks are backed by committed media and reproducible recipes. Terrain Water and glTF also retain their native 1080p masters below.
ocean.mp4
A Windy spectral sea carries afternoon light through golden hour and into night. The slow camera arc keeps the horizon stable while the waves, foam, cloud reflections, and atmosphere change together.
Project · Committed MP4 · Poster
gltf-terrain.mp4
The Damaged Helmet overlooks mountain streams and a lake on generated Terrain Diffusion terrain. A face-on opening eases into a 45° orbit as afternoon becomes sunset and early night, combining imported PBR materials with the shared captured-water landscape renderer. Water levels are a held SynxFlow storm state; camera, lighting and surface cues animate, not hydrology.
Project · 720p MP4 · 1080p master · Poster · Recipe
water-3d.mp4
An APIC dam break collapses through a long tank, then spreads and rebounds into surface foam and secondary whitewater. The clear sky keeps the simulation and screen-space reconstruction legible.
Project · Committed MP4 · Poster
fire-3d.mp4
A warmed-up volumetric plume evolves from daylight into night. The fixed camera lets combustion, turbulence, flame shaping, and smoke structure carry the motion.
Project · Committed MP4 · Poster
fluid-25d.mp4
Rain-fed streams collect into a lake on unmodified Joining valleys terrain. A low, eased orbit reveals the relief as afternoon turns to sunset. This is recorded SynxFlow timelapse rendered in Vulkan: approximately six physical hours, an independent artistic solar clock, and exact water states held between saves—not a live-FPS claim. This is the owner-selected sunset cut.
Project · 8-second gallery MP4 · Poster · 1080p master · Recipe and provenance
The showcase package preserves the exact media, posters, capture recipes, hashes, attachment mapping, and license boundaries. The glTF-derived clip has a separate CC-BY-NC-4.0 media license; Cubey source and the other original showcase media remain MIT licensed.
Cubey's runnable projects are independent products, not scenes in one monolithic application. They reuse foundation code where the contract is genuinely shared and keep domain-specific policy local.
| Project | Focus |
|---|---|
| Atmosphere | Clear-sky scattering, solar time, twilight, stars, moon, Milky Way, and the shared surface-cloud layer. |
| Ocean | Spectral FFT waves, clipmap LOD, persistent whitecaps, curved local horizon, and atmosphere/cloud lighting. |
| Terrain | External-raster far backdrop with cached sector geometry, placement, material detail, and self-shadowing. |
| Terrain Water | Terrain-water integration with live external SynxFlow, recorded fields, and shared terrain/water rendering. |
| glTF Viewer | Staged glTF 2.0 PBR import, animation and deformation, required-use material extensions, procedural or HDR environments, shadows, and optional terrain. |
| Fractal 2D | Interactive Mandelbrot-style fullscreen shader with windowed navigation and headless output. |
Terrain and Ocean deliberately represent different scales: far backdrop and local water surface. Planet rendering is a paused study. Surface-scale planet terrain, shorelines, bathymetry, and shallow-water coupling remain separate work rather than hidden extensions of those products.
The Fluid family guide maps shared solver modules, frontend ownership and focused validation.
| Project | Focus |
|---|---|
| Smoke 2D | GPU dye/velocity field with MacCormack advection, vorticity, and pressure projection. |
| Water 2D | APIC free-surface liquid with PIC/FLIP fallback, obstacles, hose/drain flow, and surface diagnostics. |
| Water 3D | APIC liquid, sorted particle-grid transfers, screen-space surface reconstruction, and whitewater. |
| Fluid 2.5D | Standalone builtin Vulkan shallow-water experiments, virtual-pipes/finite-volume alternatives and numerical diagnostics. |
| Fire 3D | Dense volumetric combustion, projection, vorticity, shadow volume, and raymarching. |
| Explosion 3D | The shared pyro solver presented as repeated impulses with explosion-specific timing and controls. |
The cube-focused programs under examples/ isolate reusable
renderer behavior: transforms and depth, compute-generated textures, render
graph passes, shadow maps, instance-rate input, material handles, particle
compute, and no-window capture. They are small foundation tests rather than
showcase projects.
pbr_furnace is likewise maintained as an internal
white-furnace validation target, not a public demo.
- Planet is a paused orbital-rendering study with an explicit opt-in build; its renderer, design, and review tools are retained.
- Terrain Hydrology is a paused snapshot of the earlier regional terrain and landscape-evolution work.
- Cloud reference study, Terrain Ref, and the Terrain ShaderToy study retain reference evidence without competing with active products.
- Archived terrain attempts summarize the retired terrain workbench, terrain lab, and coastal demo; Git history remains the implementation archive.
- Native Vulkan is the primary backend and desktop is the primary target.
- Layered
cubey::*libraries expose reusable headers underinclude/cubey/; projects consume the aggregatecubey::cubeytarget where appropriate. cubey_hostsupplies GLFW-backed windowing and the deterministic headless host without owning project policy.- Each executable owns a typed Config V2 facade composed from shared host and engine schemas plus only its live project options.
- Headless PNG and optional H.264 MP4 capture are first-class validation and publication paths.
- ImGui provides project controls and diagnostics, but Cubey does not aim to become an editor.
The architecture is deliberately pressure-driven: shared abstractions are promoted from repeated project needs, while Vulkan-specific requirements stay visible when hiding them would make the code less useful.
The normal presets need Clang 16+ with C++20 support, CMake 3.25+, Ninja, Git,
pkg-config, OpenSSL and Vulkan development packages, a working Vulkan driver,
and glslangValidator. Tests also require Python 3.11+. Linux window-backend
packages and distribution examples are listed in the setup guide.
cmake --preset dev
cmake --build --preset dev
ctest --preset devThen launch a project, for example:
./build/dev/projects/ocean/ocean
./build/dev/projects/fluid/water_3d/water_3d
./build/dev/projects/gltf_viewer/gltf_viewer --input path/to/model.glbSee Build and run Cubey for distro packages,
headless PNG/MP4 capture, sample assets, validation, configuration precedence,
and common controls. For remote visual review, the
local report browser
provides an automatically discovered, searchable index of HTML result pages
under outputs/, served by a small Python HTTP server that can run in tmux.
The docs index separates current architecture, project guides, evidence, and archived work. Good starting points:
- Design — purpose, tenets, and repository structure.
- Architecture notes — current engine and rendering contracts.
- Configuration V2 — typed project-owned config, JSON serialization, CLI precedence, and validation.
- Roadmap — current readiness and likely next foundation work.
- Repository tools — current navigation checks, CMake policy fixtures, and the local report browser.
- Showcase plan — shot design, capture contract, and media provenance.
- Changelog — implementation history and release notes.
Active development lives on main. The original OpenGL 4 shader playground is
preserved on the legacy branch.
Cubey source and original project media are licensed under the MIT License. The Damaged Helmet-derived glTF showcase MP4s (gallery and native master) and poster are a media-only CC-BY-NC-4.0 exception with their attribution recorded in the showcase manifest.