Ra Engine

A Vulkan 1.4 hardware ray tracing engine with a terminal-first UI philosophy. Theatrical-quality lighting informed by McCandless theory. Built at Flux Studios under Color It Company LLC.

01. Quick Start

Running the Engine

# Standard launch — skip recompile, suppress MangoHUD
./go.sh --skip-compile --no-mango

# Launch with a specific scene
./go.sh --skip-compile --no-mango scenes/launch_up_tutorial1.gltf

# Play mode (locks cursor, enables game input)
./go.sh --skip-compile --no-mango --play scenes/launch_up_tutorial1.gltf

# Full recompile from scratch
./go.sh --clean --no-mango

Compiling Shaders

After any change to .rchit, .rgen, .rmiss, or .rint files, recompile the SPIR-V:

./compile_shaders.sh

The active raygen is raygen.rgen → raygen_rgen.spv. The file raygen_aa.rgen is kept in sync but not compiled into the active pipeline.

Test Scenes

02. Hardware Requirements

Platform: Fedora Linux. Vulkan 1.4 required. VK_LAYER_KHRONOS_validation available via VK_INSTANCE_LAYERS for debug builds.

03. Renderer

Ra Engine uses a full hardware ray tracing pipeline. Every pixel is ray traced — there is no rasterization fallback. The pipeline dispatches from raygen.rgen and traces recursively through closest-hit and miss shaders.

Ray Tracing Pipeline

Recursive ray order per primary ray:

1. Reflections — mirror and glossy bounces, depth-gated at bounce ≤ 1 for shadow rays
2. Refractions — enter/exit pairs tracked via fromRefraction integer in RayPayload; suppresses reflection spawning inside refraction chains
3. GI (Global Illumination) — single bounce, multi-sample. Modes: Off / 1 / 2 / 4 samples. fromGI flag skips shadow rays on GI hits. Correct 2× Monte Carlo scale factor applied.

After all tracing, a post-imageStore pass in raygen.rgen draws the crosshair over the tonemapped image.

Tonemapping & Color

Acceleration Structure

Ra Engine uses a per-object BLAS architecture. Each SceneObject owns a PerObjectBLAS struct. The TLAS holds one instance per BLAS, all with identity transforms.

// DigifluxEngine — per-object BLAS array (parallel to geometry SceneObjects)
struct PerObjectBLAS {
    VkAccelerationStructureKHR as  = VK_NULL_HANDLE;
    VkBuffer                   buf = VK_NULL_HANDLE;
    VkDeviceMemory             mem = VK_NULL_HANDLE;
};
std::vector<PerObjectBLAS> objectBLASes;

Vertex positions are world-space baked. applyAllObjectTransforms() bakes the full transform into vertex data before BLAS build. gl_ObjectToWorldEXT is therefore identity per instance and not referenced in any shader.

Index addressing in closesthit: gl_InstanceCustomIndexEXT stores firstIndex for each TLAS instance, mapping the local gl_PrimitiveID back to the correct slot in the global index buffer:

uint baseIndex = gl_InstanceCustomIndexEXT;
uint i0 = indices[baseIndex + 3 * gl_PrimitiveID + 0];
uint i1 = indices[baseIndex + 3 * gl_PrimitiveID + 1];
uint i2 = indices[baseIndex + 3 * gl_PrimitiveID + 2];

04. Camera UBO — Field Order

The CameraUBO struct must match exactly across all shader files and the C++ host. Order is fixed — do not reorder.

05. Shader System

Shader Files

Light Culling

Per-light culling in closesthit.rchit uses an influence radius computed as:

float influenceRadius = sqrt(light.intensity * 1000.0);

Lights beyond this radius from the hit point are skipped entirely, with no shadow ray cast.

Glass / Zero-Roughness Safety

Alpha is clamped to 1e-4 in GGX BRDF evaluation to prevent NaN from division by zero at perfect mirror roughness:

float alpha = max(roughness * roughness, 1e-4);

06. Lighting

Ra Engine uses physically-based inverse-square attenuation. Intensities must be calibrated carefully — oversaturated values wash all surfaces to white.

Intensity Calibration

Use inverse-square attenuation: illuminance = intensity / (distance²). Start low and increase. A point light at intensity = 10 will fully illuminate geometry within ~3 metres.

GI Performance Flags

• fromGI — set on GI rays. Skips shadow ray casting on GI hits, halving secondary ray count.
• fromRefraction — integer in RayPayload. Suppresses reflection spawning inside refraction chains without breaking enter/exit pairs.
• Shadow ray depth gate — shadow rays only cast at bounce depth ≤ 1.

Adding Lights in the Editor

Press KP* (hold) to open the Add Light submenu:

07. Scene Format — GLTF 2.0

Ra Engine loads scenes via tinygltf. Scenes must conform to GLTF 2.0 with the extensions listed below.

Supported Extensions

Light Nodes — Critical

Material Extras

Ra Engine reads the following custom node extras:

08. Scene Editor

The editor is accessed via F-key menus overlaid as ANSI terminal text. No ImGui is used. All interaction is keyboard-driven.

F-Key Menu System

Hierarchy View (F3)

The HierarchyView constructor signature (in order):

HierarchyView(
  SceneManager*     sceneMgr,
  lights*           lightsPtr,
  bool*             lightsNeedUpdate,
  LightDeleteCB     onLightDelete,
  LightAddCB        onLightAdd,
  ObjectAddCB       onObjectAdd,
  SaveSceneCB       onSaveScene,
  TlasRebuildCB     onTlasRebuild,
  SnapToGroundCB    onSnapToGround,
  MaterialUpdateCB  onMaterialUpdate,
  materials*        materialsPtr,
  float             keyRepeatDelay,
  float             keyRepeatRate
);

Controls Reference

Fly Mode (F4)

Console View (F1)

F1 opens a full-screen scrollable terminal panel that captures all stdout and stderr into a 500-line ring buffer. Output is ANSI-stripped for storage and re-coloured by line type (normal / success / warning / error). The real terminal still receives the original coloured output simultaneously via a tee streambuf.

Object Groups

Objects are assigned to named groups via the ra_group node extra or via the editor. The current scene name is displayed at the bottom-left border of the hierarchy panel — it turns red when there are unsaved changes. Press Enter on a group header to select the whole group; subsequent property edits apply to all members. Alt+G grabs the whole group for movement.

09. Build System

go.sh Flags

Scene file path is the final positional argument — writing it to disk updates .last_scene for the next session. Without a positional argument, go.sh loads the scene from .last_scene, falling back to material_showcase_v2.gltf on first run.

Incremental Builds

The Makefile uses -MMD -MP for dependency tracking. Without --clean, only changed translation units recompile. Shader compilation is always a separate step via compile_shaders.sh — the build system does not auto-detect shader changes.

# Typical dev workflow
./compile_shaders.sh          # after shader edit
./go.sh --skip-compile --no-mango scenes/myscene.gltf

# After C++ changes
./go.sh --no-mango scenes/myscene.gltf

# Debug run with Vulkan validation
./go.sh --no-mango --validate scenes/myscene.gltf

10. Platform Notes

AMD (RADV driver)

Linux / X11 + GLFW

glfwSetCharCallback does not fire when GLFW_CURSOR_DISABLED is active (X11 limitation). Use keyCallback-based keyToChar() translation for all text input that may occur while the cursor is locked.

MangoHUD

MangoHUD causes segfaults during Vulkan teardown when running against Ra Engine. Always pass --no-mango. Do not attempt to use MangoHUD for performance monitoring with this engine — use Vulkan timestamp queries or VK_EXT_debug_utils markers instead.

11. Critical Pitfalls

12. Lua Scripting

Ra Engine drives game logic through Lua scripts. Drop a .lua file in scripts/ and the full engine API is available as the global table engine. No recompile needed — scripts hot-reload live on save.

Script Contract

Every script must define three global functions the engine calls automatically:

Hot-Reload

The engine stat()s the script file every frame. On mtime change it tears down the Lua state, reopens it, and calls init() again. Lua variables do not survive hot-reload — persist anything important with engine.set_var(), which lives in C++ and is unaffected by Lua restarts.

Quick Example

local goal_id = 0
local score   = 0.0

function init()
    goal_id = engine.find_object("goal_pad")
    score   = engine.get_var("game.score", 0.0)
end

function update(dt)
    local _, y, _ = engine.get_camera_position()
    score = y * 100.0
    engine.set_hud_data(score, y)

    if goal_id ~= 0 and engine.player_overlaps_object(goal_id) then
        engine.print_status("★ LEVEL COMPLETE!")
    end
end

function shutdown()
    engine.set_var("game.score", score)
end

13. Built with Ra Engine

Ra Engine is sold at $49.99/seat on Steam through digiflux.one. Games built with Ra Engine are cross-promoted through the digiflux.one pipeline. Launch Up on Steam is built with Ra Engine.