Vertra

Vertra is a lightweight, cross-platform 3D rendering engine for Rust, built on top of wgpu. It provides a streamlined abstraction for hardware-accelerated graphics with a professional perspective camera, a safe hierarchical scene graph, a built-in static scene editor, a compact binary scene format (VTR), and a WASM/JavaScript binder layer.

Features

Getting Started

Vertra is not yet published to crates.io. Clone the repository and reference it via a path dependency:

[dependencies]

vertra = { path = "../path/to/vertra" }

Quick Example — Solar System

use std::collections::HashSet;
use winit::event::{DeviceEvent, ElementState, Event, WindowEvent};
use winit::keyboard::{KeyCode, PhysicalKey};

use vertra::camera::Camera;
use vertra::window::Window;
use vertra::transform::Transform;
use vertra::geometry::Geometry;
use vertra::objects::Object;

struct AppState {
    pressed_keys: HashSet<KeyCode>,
    sun_id: usize,
    planet_id: usize,
}

fn main() {
    Window::new(AppState { pressed_keys: HashSet::new(), sun_id: 0, planet_id: 0 })
        .with_title("Solar System")
        .with_camera(
            Camera::new()
                .with_position([0.0, 8.0, -12.0])
                .with_rotation(90.0, -30.0),
        )
        .with_event_handler(|state, scene, event, _| {
            match event {
                Event::WindowEvent {
                    event: WindowEvent::KeyboardInput { event: ke, .. }, ..
                } => {
                    if let PhysicalKey::Code(code) = ke.physical_key {
                        match ke.state {
                            ElementState::Pressed  => { state.pressed_keys.insert(code); }
                            ElementState::Released => { state.pressed_keys.remove(&code); }
                        }
                    }
                }
                Event::DeviceEvent {
                    event: DeviceEvent::MouseMotion { delta }, ..
                } => {
                    scene.camera.rotate(delta.0 as f32 * 0.1, delta.1 as f32 * 0.1, false);
                }
                _ => {}
            }
        })
        .on_startup(|state, scene, _| {
            let sun = Object {
                name: "Sun".to_string(),
                geometry: Some(Geometry::Sphere { radius: 2.0, subdivisions: 32 }),
                color: [1.0, 0.9, 0.2, 1.0],
                ..Default::default()
            };
            state.sun_id = scene.spawn(sun, None);

            let planet = Object {
                name: "Planet".to_string(),
                transform: Transform::from_position(6.0, 0.0, 0.0),
                geometry: Some(Geometry::Sphere { radius: 0.8, subdivisions: 24 }),
                color: [0.2, 0.5, 1.0, 1.0],
                ..Default::default()
            };
            state.planet_id = scene.spawn(planet, Some(state.sun_id));

            let moon = Object {
                name: "Moon".to_string(),
                transform: Transform::from_position(1.5, 0.0, 0.0),
                geometry: Some(Geometry::Sphere { radius: 0.3, subdivisions: 16 }),
                color: [0.7, 0.7, 0.7, 1.0],
                ..Default::default()
            };
            scene.spawn(moon, Some(state.planet_id));
        })
        .on_update(|state, scene, ctx| {
            scene.camera.handle_default_input(&state.pressed_keys, 3.0, ctx);

            if let Some(sun) = scene.world.get_mut(state.sun_id) {
                sun.transform.rotation[1] += 30.0 * ctx.dt;
            }
            if let Some(planet) = scene.world.get_mut(state.planet_id) {
                planet.transform.rotation[1] += 100.0 * ctx.dt;
            }
        })
        .create();
}

Architecture Overview

Module Map

Scene Graph

Objects form a tree. Each Object stores its parent's and children's integer IDs. During rendering the engine traverses the tree recursively, combining parent and child Transform matrices so that children automatically inherit position, rotation, and scale.

The World type manages the graph and exposes safe mutation methods:

• spawn_object(object, parent_id) — insert; unknown parent falls back to root.
• delete(id) — remove an object and all its descendants.
• reparent(id, new_parent) — move an object in the hierarchy with cycle detection.
• get_id(str_id) — resolve a stable string handle to an integer ID (call once, cache the result).
• on_scene_graph_modified — optional callback fired after every structural mutation.

Coordinate System

Y-up, left-handed. The default camera looks along +Z. All rotation angles are in degrees (Euler, Y → X → Z order).

Rendering Pipeline

Geometry is baked each frame: the scene tree is walked, all object meshes are assembled into MeshData builders grouped by texture_path, then uploaded to the GPU as a small number of batched draw calls. The editor gizmo overlay is rendered as a separate pass.

Built-in Editor

Enable with scene.enable_editor_mode() in on_startup. While active:

• on_update, on_fixed_update, and on_draw_request are suppressed.
• Orbit (Alt+drag), pan (middle-drag), and zoom (scroll wheel) control the camera.
• T / R / E switch between translate, rotate, and scale gizmos.
• Left-click picks objects; Ctrl+click multi-selects; G selects a subtree.
• F focuses the camera on the selection.
• Escape exits editor mode and returns to play mode.

Use Window::on_editor_event to react to gizmo-mode changes, drag start/end, and selection changes while the editor is active.

VTR Binary Format

.vtr files store the full camera state and scene hierarchy in a compact little-endian binary layout (~84 bytes minimum for an empty scene). Use scene.save_vtr_file / scene.load_vtr_file on native, or vtr::write / vtr::read directly on any Write/Read impl.

License

Copyright 2026 xCirno Labs.

Licensed under the Apache License, Version 2.0.
http://www.apache.org/licenses/LICENSE-2.0

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.