REACTOR Framework for Vulkan

REACTOR is an experimental game engine written in Rust on top of Vulkan. Its goal is to deliver Vulkan's explicit control and performance through a simpler, safer, and more measurable API for building scenes, worlds, and video games.

Status: active development. The architecture is being consolidated and reviewed subsystem by subsystem. It should not yet be considered a stable API or a production-ready engine.

What is REACTOR

REACTOR is a reusable game framework, not a single game. A game built on REACTOR implements an application trait (ReactorApp), while the engine owns the window, the runtime, and the GPU resources. The game focuses on gameplay; the engine focuses on Vulkan.

Game (your code: implements ReactorApp)
    │
    ▼
REACTOR public API (context, scene, assets, systems)
    │
    ▼
REACTOR runtime (world, assets, input, audio, physics)
    │
    ▼
Renderer (decides how to produce each frame)
    │
    ▼
GPU / Vulkan (resources, pipelines, commands, synchronization)
    │
    ▼
Driver and hardware

Vulkan provides the potential. REACTOR organizes it to build worlds.

Why does REACTOR exist

The Vulkan problem

Vulkan is an extremely explicit API. It gives you full control over the GPU, but at a cost: to draw a single triangle you must manage instances, surfaces, devices, queues, swapchains, memory, command pools, command buffers, fences, semaphores, descriptors, pipelines, render passes, and synchronization. That is a lot of infrastructure to recreate for every new project — and it is easy to get wrong (lifetime issues, race conditions, lost resources, validation errors).

The REACTOR answer

REACTOR exists to solve a simple problem: most games do not need to build Vulkan infrastructure; they need a world. The engine centralizes every repetitive Vulkan concern so that a game can:

Open a window and start the main loop in a few lines.
Load a model, a texture, or a whole scene without touching a staging buffer.
Move a camera while the engine manages swapchains, memory, and synchronization.
Measure performance, memory, and validation errors while it runs.

REACTOR does not pretend Vulkan away behind a "universal" abstraction that hides its power. It keeps the GPU in charge of the hardware — memory, buffers, pipelines, command execution — and exposes comfortable engine-level concepts (scene, material, camera, light) above it. Easy on top, explicit on the bottom.

Built to learn and to last

REACTOR was created to learn, experiment, and prove that a single developer can build a GPU-driven, Vulkan-based engine in Rust — without C, C++, or external FFI — while producing something that others can use to build their own games without reimplementing all of Vulkan from scratch.

REACTOR also has a second goal: being a testbed for ideas. The engine is designed so that sub-systems can be isolated, measured, and swapped: what works stays; what does not is reworked.

Inspiration, not imitation

REACTOR looks up to the way Unreal Engine 5 structures its runtime, with influence in these areas:

Separating the engine from the game.
Organizing scenes, assets, and systems coherently.
Keeping the renderer independent of the game logic.
Building diagnostic and profiling tools into the engine.
Exposing a high-level API on top of a complex graphics backend.

But the goal is not to copy Unreal, nor to build a full editor tomorrow. Blender acts as an intermediate creation tool while REACTOR focuses on a solid runtime and renderer. The frame philosophy is deliberately raster-first: Ray Tracing / RTX is not part of the product or the plan.

Goals

REACTOR aims to:

Provide a small, documented, stable public API for building a game without touching Vulkan handles.
Centralize memory, synchronization, pipelines, and presentation reliability.
Support scenes with cameras, lights, materials, meshes, and transforms.
Offer solid asset loading: glTF, textures, materials, and hot reload.
Keep observability built in: profiler hooks, per-pass timings, VRAM budget, and validation.
Be measured before it is optimized.
Compile and run cleanly on each subsystem as it lands.

Non-goals

No ray tracing / RTX.
No C or FFI in user code; the whole stack is Rust.
No permanent legacy tree — the migration replaces instead of duplicates.
No parent of parallel implementations: one ownership per responsibility.
No editor-only UI (unless it proves worth the cost).

Principles

Single source of truth. The active engine code lives in base_nueva/.
Bottom-up construction. First Vulkan, then the renderer, then the world and the gameplay.
Each layer has one responsibility. An upper layer may use a lower one, never the other way around.
Every change must compile. The workspace stays green.
One problem, one commit. Commits are small, explainable, and reversible.
RAII for Vulkan. Every resource frees its memory on drop and has a single owner with a documented destruction order.
Clear errors. Use Result; avoid panic!, unwrap(), and silent failures in recoverable paths.
Measure before you optimize. Profiler, per-pass timings, memory, and validation before adding complexity.
Easy API on top, explicit control underneath. Games use engine concepts; the GPU keeps the control it needs.
Hardware compatibility. Prefer standard Vulkan features when a vendor-only alternative is avoidable.

Architecture

Target crate layout (design goal)

The engine is migrating toward a dependency-hierarchy of crates. Dependencies can only point downward:

reactor (public facade: App, Context, run())
    ▼
reactor-engine (runtime, scene, assets, input, audio)
    ▼
reactor-render (frame graph, passes, meshes, materials)
    ▼
reactor-gpu (Vulkan, memory, commands, synchronization) — the only crate allowed to use `unsafe`
    ▼
reactor-core (errors, IDs, config, shared types) — no Vulkan, no window

Rules derived from this layout:

Only reactor-gpu may contain raw unsafe Vulkan calls.
Any recoverable public API returns Result; no panic! / unwrap().
Every GPU handle has one owner and documented RAII destruction.
No parallel implementations are kept after reaching parity.
Shaders are generated in the build directory; the build never modifies source files.
A broken shader stops the build.

Engine layers (the content)

1 — Core. Errors, configuration, logging, jobs, safe handles, truly shared math and platform utilities. Core must not know about scenes, materials, or gameplay.

2 — GPU / Vulkan. The reusable base of the engine: instance + validation layers + debug messenger, GPU/capability selection, device and queues, surface and swapchain, allocator and VRAM budget, buffers/images/samplers/staging, descriptors and bindless, command pools/buffers, fences/semaphores, render passes / dynamic rendering, pipelines, and pipeline/shader caches. This layer must not know about enemies, gameplay cameras, or specific games.

3 — Renderer. Uses the GPU layer to produce images: frame begin/end, G-Buffer or forward, depth + MSAA, lighting and shadows, materials and textures, culling + meshlets, post-processing (TAA, Hi-Z, bloom, fog, exposure), IBL and reflections, debug rendering. The renderer receives a description of the visible world; it does not control the game.

4 — Resources / assets. Turns files into usable resources: asset IDs and handles, the asset database, model/texture/material/font/audio loading, async GPU upload, hot reload, asset cooking/caching, explicit Loading / Ready / Failed states. Gameplay requests an asset by name and never manages staging.

5 — World and scene. Represents what exists in the game: entities, transforms, cameras, lights, meshes and materials, sectors/portals, and the list of visible objects delivered to the renderer.

6 — Systems and runtime. Runs the game in an organized loop: application lifecycle, time and fixed update, input + gamepad, physics, animation, audio, particles, events, world streaming, pause/system states.

7 — Public API. The surface a game actually uses: ReactorApp, ReactorContext, fluent builders, small and stable. Internal Vulkan structures should not leak without a reason.

// Dream public API (gameplay that never touches Vulkan)
struct MyGame;

impl ReactorApp for MyGame {
    fn init(&mut self, ctx: &mut ReactorContext) {
        ctx.world.spawn_model("assets/world.glb");
        ctx.world.add_light(Light::sun());
    }

    fn update(&mut self, ctx: &mut ReactorContext) {
        // Gameplay without touching Vulkan directly.
    }
}

Repository layout

The current engine code lives in base_nueva/:

base_nueva/
├── core/          # Errors, context, RAII handles, frame graph, allocators, jobs, profiler
├── gpu/           # Vulkan resources, pipelines, bindless, shader compiler, post-processing
├── renderer/      # Render orchestration (forward / bindless forward)
├── resources/     # Assets, glTF loader, textures, mesh/material, asset database
├── scene/         # Camera, transforms, ECS
├── systems/       # Scene, physics, audio, console, particles, input, gamepad
├── platform/      # Window, input, gamepad, time
├── app/           # ReactorContext, ReactorApp trait, runner, config, pause
├── app_helpers/   # Fluent helpers: App, mesh builder, camera, lighting
├── base_shader/   # Embedded cookbook shaders (forward, texture, etc.)
├── compute/       # Compute pipelines
├── reactor/       # Core draw/init implementation
├── render/        # New render passes (GI, lighting, post, scene)
├── runtime/       # Runtime utilities
├── utils/         # Shared utilities
├── bin/           # `reactor` CLI binary
└── lib.rs         # Public API + macros (game!)

Other important areas:

shaders/                   # GLSL sources compiled to SPIR-V by build.rs (OUT_DIR only)
examples/                  # Small, runnable usage examples
reactor-blender-bridge/    # Standalone Blender integration (Python + Rust)
docs/                      # Architecture and design documentation
ideas.md                   # Build direction and the ordered road map
REFACTOR_PLAN.md           # Recovery/architecture plan

During the reorganization there may be experimental modules or skeletons not yet exposed by the public API.

What is implemented today

The repository contains implementations or work-in-progress baselines for:

Vulkan initialization and context (instance, device, queues, surfaces).
GPU selection and capability detection (Vulkan 1.3, VRS, memory budget).
Swapchain with retrieval and fallback of presentation modes.
Buffers, images, samplers, and GPU memory (gpu-allocator).
Graphics and compute pipelines, mesh shader support, pipeline/shader caches.
Bindless resources (big descriptor pool, variable descriptor counts, update-after-bind).
Frame graph with full barrier generation (read→write, write→write, undefined transitions).
Shaders compiled from GLSL at build time, plus a runtime compiler/reflection via naga and hot reload.
Meshes, textures, materials, and glTF loading (sync + async).
Camera, transforms, ECS, and the scene system used by examples.
Lighting, shadows (cascaded / shadow maps), IBL, GI (SSGI + Hi-Z), Hi-Z pyramid.
Post-processing: TAA, bloom, auto-exposure, GTAO, fog, volumetric clouds, lens flare, decals, depth resolve.
MSAA, depth, dynamic rendering, compute particles.
A new renderer/ forward + bindless forward path (in construction).
Input, gamepad, audio, physics, events.
Asset database (hashed content, dependency invalidation, cache).
Experimental asset hot-reload pipeline and asset cooking CLI.
Experimental Blender integration (textures, live link, import/export).

The presence of a module does not mean it is finished. Each subsystem is audited for ownership, resource release, error correctness, dependencies, Vulkan validation, and real-world behavior.

Development roadmap

The engine is being built bottom-up, phase by phase. Each phase ends with the workspace compiling.

Phase 0 — Reproducible baseline: unify under base_nueva/; keep cargo check --all-targets green; define which modules are active vs. skeletons; document the permitted layer dependencies.
Phase 1 — Core: audit core/ file by file; separate generic utilities from Vulkan objects; unify errors; verify ownership/drop safety; add tests that need no GPU.
Phase 2 — GPU/Vulkan minimum: instance with optional validation, device selection, device + queues + surface, stable swapchain (accept and recreate), allocator + buffers + images, in-flight frame synchronization, and a draw + present loop without validation errors.
Phase 3 — Resources and pipelines: descriptors + bindless, pipeline cache, transfer-queue uploads, GPU mesh/material/texture, VRAM metrics and debug names.
Phase 4 — Renderer: one documented main path (forward, deferred, or hybrid), camera/depth/G-buffer/lighting, shadows and IBL, Hi-Z + frustum/occlusion culling, basic post-processing, obviously defined pass sequence (frame graph).
Phase 5 — World and assets: entities + transforms, scenes + cameras, explicit asset-manager states, glTF as the initial world/model format, async loading and hot reload, and a clean separation between the world representation and the data prepared for the renderer.
Phase 6 — Game engine: input, time, fixed update, physics/audio/animation, events and app states, particles and decals, sector streaming, small documented public examples and example plugins.
Phase 7 — Blender Bridge: a stable protocol, syncing transforms/cameras/lights/audio, connection and error handling, a validated Blender→REACTOR export pipeline, then full live sync on a stable API.
Phase 8 — Advanced optimization (only after a correct, measurable base): GPU-driven rendering, indirect draws, meshlets, async compute, Variable Rate Shading, dirty-tile/delta rendering, persistent VRAM caches, temporal GI, vendor-agnostic upscaling, targeted ray queries.

Each stage must:

Have clear responsibilities and one owner.
Compile before moving forward.
Avoid circular dependencies.
Release Vulkan resources correctly (RAII + documented order).
Report errors with context.
Include a reproducible test or example.
Produce no Vulkan Validation Layer errors.
End in a small, focused commit.

The extended work plan lives in ideas.md and the architecture rationale in docs/architecture.md.

Advanced ideas

These are the roadmap goals after the base, pass-by-pass, resource, renderer, and world are verified. They are not the foundation.

Persistent deep VRAM

A stable dataset (geometry, materials, probes, shadows, caches) stays resident with explicit budgets and clear eviction policies:

compute → store → validate → reuse

Rendering by visual importance

Prioritize what the camera sees.
Use Hi-Z, sectors, and portals to reject work up front.
Update expensive systems against dispatches time-budget.
Reuse history frames only when depth, normal, material, and motion remain valid.

Delta rendering

Classify tiles as stable or modified.
Reproject and validate the previous frame.
Recompute only invalid regions when it is safe to do so.
Always measure for ghosting, invalidations, and compositing costs.

First playable milestone

The first complete demo of the new baseline is deliberately small:

Open a window.
Initialize Vulkan without validation errors.
Load a glTF room.
Create a camera, a light, and materials.
Let the player move with keyboard and gamepad.
Render shadows and basic post-processing.
Show frame time, VRAM usage, and draw calls.
Shut down releasing all resources correctly.

If this room works cleanly, REACTOR already has the foundation to build a larger world on top of it.

Requirements

Rust 1.88 or the toolchain pinned in rust-toolchain.toml.
A GPU and driver with Vulkan support (Vulkan 1.3 recommended).
Vulkan SDK recommended for validation layers and diagnostic tools.
glslc available so build.rs can compile the GLSL shaders to SPIR-V.

On Windows, make sure the Vulkan SDK and glslc are on PATH.

Build

Clone, then check all targets:

git clone https://github.com/AndreeSalazar/REACTOR-Framework-for-Vulkan-.git
cd REACTOR-Framework-for-Vulkan-
cargo check --all-targets

Normal build:

cargo build

Optimized build:

cargo build --release

Examples

Start with the smallest example:

cargo run --example cube

Other registered examples:

cargo run --example textured_cube
cargo run --example physics_camera
cargo run --example obj_loader_demo
cargo run --example generate_audio
cargo run --example blender_live

Some examples need compatible hardware, external assets, audio, or a running Blender instance. They live alongside the API and will change with it during this stage.

Asset CLI

REACTOR ships an experimental CLI for cooking assets:

cargo run --bin reactor -- cook --input assets --output cooked_assets

Get help with:

cargo run --bin reactor -- --help

Blender Bridge

reactor-blender-bridge/ uses Blender as the authoring tool while the engine concentrates on the runtime and the renderer.

Blender
  ├── models
  ├── materials
  ├── lights
  ├── cameras
  └── animations
        ↓ export / sync
REACTOR
    │
    ▼
Game running on Vulkan

The bridge is a standalone integration, currently in development. The priority is a reproducible exported pipeline; full live sync arrives once the public API is stable enough.

Contributing

REACTOR is at an early stage. Bug reports, testing on different hardware, documentation, and focused proposals are all welcome.

Before contributing:

Open an issue or describe the problem clearly.
Keep the change small and aligned with one subsystem.
Run cargo fmt and the available checks (cargo clippy --all-targets).
State the GPU, driver, and operating system you used for any graphics-specific change.

Commit style. One problem, one commit. Always include the module prefix and the intent:

core: clarify error ownership
gpu: stabilize swapchain recreation
render: define frame lifecycle
assets: make loading states explicit
scene: separate world and render data
bridge: sync the whole scene state

License

REACTOR is distributed under the MIT license.

The reason is simple: the project wants to make it easy for anyone to learn, experiment, create, and distribute games with REACTOR — including commercial projects — while keeping the copyright notice and without imposing royalties.

The REACTOR name and visual identity remain the property of their author; the MIT license applies to the code covered by this repository.

REACTOR turns the explicit control of Vulkan into a simpler, safer, and more predictable way to build worlds and video games.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
base_nueva		base_nueva
docs		docs
examples		examples
reactor-blender-bridge		reactor-blender-bridge
shaders		shaders
.gitignore		.gitignore
.rustfmt.toml		.rustfmt.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
REFACTOR_PLAN.md		REFACTOR_PLAN.md
build.rs		build.rs
clippy.toml		clippy.toml
ideas.md		ideas.md
image.svg		image.svg
reactor_live_config.json		reactor_live_config.json
rust-toolchain.toml		rust-toolchain.toml

Navigation Menu

Repository files navigation

REACTOR Framework for Vulkan

Table of contents

What is REACTOR

Why does REACTOR exist

The Vulkan problem

The REACTOR answer

Built to learn and to last

Inspiration, not imitation

Goals

Non-goals

Principles

Architecture

Target crate layout (design goal)

Engine layers (the content)

Repository layout

What is implemented today

Development roadmap

Advanced ideas

Persistent deep VRAM

Rendering by visual importance

Delta rendering

First playable milestone

Requirements

Build

Examples

Asset CLI

Blender Bridge

Contributing

License

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

REACTOR Framework for Vulkan

Table of contents

What is REACTOR

Why does REACTOR exist

The Vulkan problem

The REACTOR answer

Built to learn and to last

Inspiration, not imitation

Goals

Non-goals

Principles

Architecture

Target crate layout (design goal)

Engine layers (the content)

Repository layout

What is implemented today

Development roadmap

Advanced ideas

Persistent deep VRAM

Rendering by visual importance

Delta rendering

First playable milestone

Requirements

Build

Examples

Asset CLI

Blender Bridge

Contributing

License

About

Resources

Stars

Watchers

Forks

Contributors

Languages