Introduction

View the Gallery - Live demos of Nightshade's features running in your browser.

Nightshade is a 3D game engine written in Rust. It handles rendering, physics, audio, animation, input, and windowing, and exposes them through a single trait the game implements. The engine is the kernel that runs every frame. The game is the data and the per-frame logic that runs alongside it.

The runtime is built from four libraries. wgpu handles cross-platform GPU access, targeting Vulkan, Metal, DirectX 12, and WebGPU from a single API. Rapier3D runs the physics at a fixed timestep with interpolation for smooth rendering. Kira drives audio playback and spatial sound. glTF is the model format, with skeletal animation, materials, and scene hierarchy loaded out of the box. The rest of the engine is the glue that ties those pieces to an entity component system and a frame schedule.

How a Nightshade application is shaped

A game implements the State trait. Three methods carry most of the load. initialize runs once at startup and sets up the scene, the camera, the lights, and any entities the game needs. run_systems runs every frame and is where game logic lives. Input handlers like on_keyboard_input fire when events arrive.

The engine owns the World. The World holds every entity, every component, and a Resources struct of singletons grouped by domain (physics, input, assets, text, loading, transform_state, cleanup, entities, commands, schedules). Game code reads and writes the World to drive what happens on screen.

┌─────────────────────────────────────────────────────────────┐
│                      Your Game (State)                       │
├─────────────────────────────────────────────────────────────┤
│  initialize()  │  run_systems()  │  ui()  │  input handlers │
└────────────────┴─────────────────┴────────┴─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                          World                               │
├──────────────────┬──────────────────┬───────────────────────┤
│     Entities     │    Components    │      Resources        │
│  (unique IDs)    │  (data arrays)   │  (global singletons)  │
└──────────────────┴──────────────────┴───────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│   Renderer    │    │    Physics    │    │     Audio     │
│    (wgpu)     │    │   (Rapier)    │    │    (Kira)     │
└───────────────┘    └───────────────┘    └───────────────┘

The frame loop

Each frame proceeds in a fixed order. The engine processes window and input events from winit. It calls run_systems on the game state. The frame schedule runs the engine systems (physics step, animation sampling, transform propagation, text sync, cleanup). The render graph executes its passes against the resulting ECS state and submits the command buffer. The swapchain presents.

The game owns the contents of run_systems. Everything else happens automatically. The schedule itself is data, stored at world.resources.schedules.frame, so a game can insert, remove, or reorder engine systems from initialize when it needs to.

What the engine ships with

Rendering is PBR with a metallic-roughness workflow. Directional, point, and spot lights with shadow maps. Post-processing covers SSAO, SSGI, SSR, bloom, depth of field, and tonemapping. Skeletal animation samples bone transforms straight into the ECS, where the renderer reads them. There is a particle system, a procedural terrain pass, and a grass pass that draws thousands of blades.

Physics covers rigid bodies, character controllers, and the usual collider shapes (box, sphere, capsule, cylinder, convex hull, trimesh, heightfield). Joints cover fixed, revolute, prismatic, spherical, rope, and spring. Raycasting is the primary query.

Audio plays WAV, OGG, MP3, and FLAC, with 3D positioned sources and distance attenuation. Input covers keyboard, mouse, and gamepad (analog sticks, triggers, rumble), with cursor locking for first-person games. Pathfinding goes through a Recast navigation mesh. Debug rendering, HUD text, screenshot capture, and an in-game developer console are part of the standard kit. Steam integration sits behind a feature flag.

The same code runs on Windows, macOS, Linux, and WebAssembly. The graphics backend is picked at runtime.

What this book covers

The next chapters walk through installation, the first application, the project layout, and the architecture in detail. The runnable demo at the end of this section is a single-file Rust program that builds for the browser through WebAssembly and renders the same scene you see in the gallery.

The reference for engine code lives at docs/USAGE.md inside the repository. The API docs are at docs.rs/nightshade. The source is at github.com/matthewjberger/nightshade.

Interactive Demo

The demo below is a Nightshade application built for WebGPU and embedded in this page. It is the same engine binary that runs natively, compiled to WebAssembly.

Controls

• Mouse drag: orbit the camera around the scene.
• Scroll wheel: zoom in and out.

What is in the scene

Three primitives, a cube, a sphere, and a torus, sit on a procedural nebula background. The cube and the torus carry emissive material parameters, which the bloom post-process spreads into a glow around the bright pixels. The sphere is a polished chrome metal that reflects the image-based lighting captured from the procedural sky. An infinite grid sits at y = 0 for reference. A pan-orbit camera tracks the scene origin. Each object rotates and bobs every frame with smooth sinusoidal interpolation.

Browser requirements

The demo needs WebGPU.

• Chrome and Edge: 113 or newer (enabled by default).
• Firefox: 141 or newer (enabled by default).
• Safari: 18 or newer (Technology Preview).

A blank frame means the browser does not yet expose WebGPU.

Source code

The whole demo is two files. The Cargo.toml declares the dependency on Nightshade and adds the wasm-bindgen plumbing for the web build. The src/main.rs is the entire game.

Cargo.toml

[package]
name = "hello-nightshade"
version = "0.1.0"
edition = "2024"

[dependencies]
nightshade = { git = "https://github.com/matthewjberger/nightshade" }

[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = "0.2"
wasm-bindgen-futures = "0.4"

[profile.release]
opt-level = "z"
lto = true

src/main.rs

use nightshade::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    launch(HelloNightshade::default())
}

#[derive(Default)]
struct HelloNightshade {
    cube: Option<Entity>,
    sphere: Option<Entity>,
    torus: Option<Entity>,
    time: f32,
}

impl State for HelloNightshade {
    fn initialize(&mut self, world: &mut World) {
        world.resources.window.title = "Hello Nightshade".to_string();
        world.resources.user_interface.enabled = false;
        world.resources.graphics.atmosphere = Atmosphere::Nebula;
        capture_procedural_atmosphere_ibl(world, Atmosphere::Nebula, 0.0);
        world.resources.graphics.bloom_enabled = true;
        world.resources.graphics.bloom_intensity = 0.15;
        world.resources.graphics.show_grid = true;

        let camera = spawn_pan_orbit_camera(
            world,
            Vec3::new(0.0, 0.0, 0.0),
            8.0,
            0.5,
            0.3,
            "Camera".to_string(),
        );
        world.resources.active_camera = Some(camera);

        spawn_sun(world);

        let cube = spawn_mesh_at(
            world,
            "Cube",
            Vec3::new(-3.0, 0.0, 0.0),
            Vec3::new(1.0, 1.0, 1.0),
        );
        spawn_material(
            world,
            cube,
            "CubeMaterial".to_string(),
            Material {
                base_color: [0.2, 0.6, 1.0, 1.0],
                metallic: 0.8,
                roughness: 0.2,
                emissive_factor: [0.1, 0.3, 0.5],
                emissive_strength: 2.0,
                ..Default::default()
            },
        );
        self.cube = Some(cube);

        let sphere = spawn_mesh_at(
            world,
            "Sphere",
            Vec3::new(0.0, 0.0, 0.0),
            Vec3::new(1.2, 1.2, 1.2),
        );
        spawn_material(
            world,
            sphere,
            "SphereMaterial".to_string(),
            Material {
                base_color: [1.0, 1.0, 1.0, 1.0],
                metallic: 1.0,
                roughness: 0.0,
                ..Default::default()
            },
        );
        self.sphere = Some(sphere);

        let torus = spawn_mesh_at(
            world,
            "Torus",
            Vec3::new(3.0, 0.0, 0.0),
            Vec3::new(0.8, 0.8, 0.8),
        );
        spawn_material(
            world,
            torus,
            "TorusMaterial".to_string(),
            Material {
                base_color: [0.3, 1.0, 0.4, 1.0],
                metallic: 0.7,
                roughness: 0.3,
                emissive_factor: [0.15, 0.5, 0.2],
                emissive_strength: 2.0,
                ..Default::default()
            },
        );
        self.torus = Some(torus);
    }

    fn run_systems(&mut self, world: &mut World) {
        pan_orbit_camera_system(world);

        let dt = world.resources.window.timing.delta_time;
        self.time += dt;

        if let Some(entity) = self.cube {
            if let Some(transform) = world.core.get_local_transform_mut(entity) {
                transform.rotation = nalgebra_glm::quat_angle_axis(self.time * 0.8, &Vec3::y())
                    * nalgebra_glm::quat_angle_axis(self.time * 0.5, &Vec3::x());
                transform.translation.y = (self.time * 1.5).sin() * 0.5;
            }
            mark_local_transform_dirty(world, entity);
        }

        if let Some(entity) = self.sphere {
            if let Some(transform) = world.core.get_local_transform_mut(entity) {
                transform.rotation = nalgebra_glm::quat_angle_axis(self.time * 0.3, &Vec3::y());
                let pulse = 1.0 + (self.time * 2.0).sin() * 0.1;
                transform.scale = Vec3::new(1.2 * pulse, 1.2 * pulse, 1.2 * pulse);
            }
            mark_local_transform_dirty(world, entity);
        }

        if let Some(entity) = self.torus {
            if let Some(transform) = world.core.get_local_transform_mut(entity) {
                transform.rotation = nalgebra_glm::quat_angle_axis(self.time * 1.2, &Vec3::z())
                    * nalgebra_glm::quat_angle_axis(self.time * 0.7, &Vec3::x());
                transform.translation.y = (self.time * 1.2 + 2.0).sin() * 0.5;
            }
            mark_local_transform_dirty(world, entity);
        }
    }
}

The initialize method sets up the window, the atmosphere, IBL capture, bloom, the grid, the camera, the sun, and three meshes with their materials. The run_systems method drives the camera controller and advances per-entity rotation and bobbing. Every transform mutation is followed by a mark_local_transform_dirty call so the frame schedule's transform propagation pass picks up the change.

Installation

Nightshade requires Rust 1.90 or newer with the 2024 edition, and a graphics driver supporting Vulkan 1.2, Metal, or DirectX 12.

Starting from the template

The fastest path is the template repository. It is a working project with the build scripts, CI, and WASM configuration already in place.

git clone https://github.com/matthewjberger/nightshade-template my-game
cd my-game
just run

The window opens onto a 3D scene with a nebula skybox, a ground grid, and a pan-orbit camera. That is the starting point. Edit src/main.rs to make it your game.

What the template contains

The template ships with the following files:

• src/main.rs is a minimal State implementation with a camera and a sun.
• Cargo.toml has the Nightshade dependency with default features enabled.
• justfile defines run, lint, test, and deployment commands for native, WASM, and Steam Deck.
• index.html and Trunk.toml configure the WASM web build.
• .github/workflows/ runs clippy, tests, and the WASM build on CI, and deploys to GitHub Pages.
• rust-toolchain pins the Rust version and adds the WASM target.

The starter src/main.rs looks like this:

use nightshade::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    launch(Template)?;
    Ok(())
}

#[derive(Default)]
struct Template;

impl State for Template {
    fn initialize(&mut self, world: &mut World) {
        world.resources.window.title = "Template".to_string();
        world.resources.user_interface.enabled = true;
        world.resources.graphics.show_grid = true;
        world.resources.graphics.atmosphere = Atmosphere::Nebula;
        spawn_sun(world);
        let camera_entity = spawn_pan_orbit_camera(
            world,
            Vec3::new(0.0, 0.0, 0.0),
            15.0,
            0.0,
            std::f32::consts::FRAC_PI_4,
            "Main Camera".to_string(),
        );
        world.resources.active_camera = Some(camera_entity);
    }

    fn run_systems(&mut self, world: &mut World) {
        pan_orbit_camera_system(world);
    }

    fn on_keyboard_input(
        &mut self,
        world: &mut World,
        key_code: KeyCode,
        key_state: ElementState,
    ) {
        if matches!((key_code, key_state), (KeyCode::KeyQ, ElementState::Pressed)) {
            world.resources.window.should_exit = true;
        }
    }
}

Justfile commands

Use just run rather than cargo run directly. The justfile carries the flags the build needs.

Feature flags

Subsystems are opt-in through Cargo features. Add them in Cargo.toml:

[dependencies]
nightshade = { version = "0.13", features = ["physics", "audio"] }

The full list is in the Feature Flags appendix.

Platform notes

On Windows, DirectX 12 is the default backend. Update the graphics drivers if shaders fail to compile.

On macOS, Metal is selected automatically. Nothing else is required.

On Linux, Vulkan is required. Install the runtime and headers through the system package manager:

# Ubuntu/Debian
sudo apt install vulkan-tools libvulkan-dev

# Fedora
sudo dnf install vulkan-tools vulkan-loader-devel

# Arch
sudo pacman -S vulkan-tools vulkan-icd-loader

On the web, WebGPU support is required. Chrome 113+, Edge 113+, and Firefox 121+ work out of the box. The template's just run-wasm uses Trunk to compile and serve the page.

Your First Application

A Nightshade application is a struct that implements the State trait. The engine calls initialize once at startup and run_systems every frame. The rest of the methods on the trait are input handlers and lifecycle hooks. That is the whole interface.

The minimum viable application

use nightshade::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    nightshade::launch(MyGame::default())
}

#[derive(Default)]
struct MyGame;

impl State for MyGame {
    fn initialize(&mut self, world: &mut World) {
        world.resources.window.title = "My First Game".to_string();
    }

    fn run_systems(&mut self, world: &mut World) {
    }
}

This compiles and runs. It opens a window and renders nothing useful. There is no camera, no light, no geometry. The rest of this chapter fills in those pieces, one at a time, before assembling them into a single example.

A camera

The camera determines what gets drawn. Spawn one and mark it active.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    let camera = spawn_camera(
        world,
        Vec3::new(0.0, 5.0, 10.0),
        "Main Camera".to_string(),
    );
    world.resources.active_camera = Some(camera);
}
}

spawn_camera returns an Entity handle. The renderer reads from whichever entity is stored in world.resources.active_camera. A scene with no active camera renders the clear color and nothing else.

A light

A directional light models the sun. Without one, every PBR surface in the scene is black.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    spawn_sun(world);
}
}

spawn_sun creates a directional light entity with sensible defaults and parents it to the world root. Replace it with spawn_point_light or spawn_spot_light for those flavors.

The grid and the sky

The grid is a development aid. The atmosphere fills the background and feeds image-based lighting.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.graphics.show_grid = true;
    world.resources.graphics.atmosphere = Atmosphere::Sky;
}
}

Both fields live on world.resources.graphics. Toggling show_grid adds an infinite ground grid drawn at y = 0. The Atmosphere enum selects the procedural skybox (sky, nebula, or one of the other variants).

Geometry

spawn_cube_at is the simplest way to put something in the scene. It places a unit cube at the given position with default material properties.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    spawn_cube_at(world, Vec3::new(0.0, 1.0, 0.0));
}
}

The prelude exposes equivalent helpers for spheres and other primitives. For real geometry, load a glTF file.

Camera controls

The fly camera reads mouse and keyboard input and moves the active camera each frame. Add it to run_systems.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    fly_camera_system(world);
    escape_key_exit_system(world);
}
}

escape_key_exit_system sets world.resources.window.should_exit = true when the escape key is pressed. The engine reads that flag at the top of each frame and shuts the window down cleanly.

The whole example

use nightshade::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    nightshade::launch(MyGame::default())
}

#[derive(Default)]
struct MyGame;

impl State for MyGame {
    fn initialize(&mut self, world: &mut World) {
        world.resources.window.title = "My First Game".to_string();
        world.resources.graphics.show_grid = true;
        world.resources.graphics.atmosphere = Atmosphere::Sky;

        let camera = spawn_camera(
            world,
            Vec3::new(0.0, 5.0, 10.0),
            "Main Camera".to_string(),
        );
        world.resources.active_camera = Some(camera);

        spawn_sun(world);

        spawn_cube_at(world, Vec3::new(0.0, 1.0, 0.0));
        spawn_cube_at(world, Vec3::new(3.0, 0.5, 0.0));
        spawn_cube_at(world, Vec3::new(-2.0, 1.5, 2.0));
    }

    fn run_systems(&mut self, world: &mut World) {
        fly_camera_system(world);
        escape_key_exit_system(world);
    }
}

Controls

The fly camera binds the following inputs.

Next steps

The next chapters cover loading real meshes from glTF, customizing materials, and adding physics simulation.

• Meshes & Models
• Materials
• Physics

Project Structure

A Nightshade project is a regular Cargo binary crate. The engine is a single dependency, and the project layout is whatever shape the game needs. The recommendations below are the conventions Nightshade's own apps follow.

Recommended layout

my_game/
├── Cargo.toml
├── src/
│   ├── main.rs           # Entry point
│   ├── game.rs           # Game state
│   └── systems/          # Game systems
│       ├── player.rs
│       ├── camera.rs
│       └── ...
├── assets/
│   ├── models/           # glTF/GLB files
│   ├── textures/         # PNG, JPG, HDR
│   └── sounds/           # Audio files
└── README.md

main.rs stays tiny. The State implementation lives in game.rs. Per-frame logic gets split into systems/<name>.rs files, one per concern. Game logic belongs in the systems directory, not lumped into state.rs.

Cargo.toml

[package]
name = "my_game"
version = "0.1.0"
edition = "2024"

[dependencies]
nightshade = { git = "https://github.com/matthewjberger/nightshade.git", features = ["engine", "wgpu"] }

The engine and wgpu features are the minimum. Add physics, audio, and other features as the game needs them. Each one pulls in its dependency tree, so omit anything unused.

Entry point

main.rs does two things. It declares the game module and calls nightshade::launch with the game state.

mod game;

use nightshade::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    nightshade::launch(game::MyGame::default())
}

That is the whole entry point. Anything more belongs in game.rs or a system module.

Game state

The State implementation owns whatever game data outlives a single frame. Entity handles for the player, score counters, level identifiers, and similar bookkeeping go on the struct.

#![allow(unused)]
fn main() {
use nightshade::prelude::*;

#[derive(Default)]
pub struct MyGame {
    player: Option<Entity>,
    score: u32,
}

impl State for MyGame {
    fn initialize(&mut self, world: &mut World) {
        world.resources.window.title = "My Game".to_string();
    }

    fn run_systems(&mut self, world: &mut World) {
    }
}
}

State stored on the MyGame struct is per-game data. State stored in world.resources is per-engine data. The split is intentional. The engine never touches the game struct, and the game does not need to extend the engine's resource list to track its own bookkeeping.

Embedding assets

For distribution as a single binary, embed assets at compile time with include_bytes!.

#![allow(unused)]
fn main() {
const MODEL_BYTES: &[u8] = include_bytes!("../assets/models/character.glb");
const SKY_HDR: &[u8] = include_bytes!("../assets/textures/sky.hdr");
}

The bytes live in the binary and load synchronously. For larger games, leave the assets on disk and stream them at runtime through the asset cache.

A second ECS for game data

For non-trivial games, define a second freecs::ecs! world alongside the engine's World. The engine world handles rendering, physics, and transforms. The game world handles game-specific components like inventories, AI states, and stats. This is the dual-world pattern that apps/game/ and the example games in nightshade-examples use.

#![allow(unused)]
fn main() {
use freecs::ecs;

ecs! {
    GameWorld {
        components {
            player_state: PlayerState,
            inventory: Inventory,
            health: Health,
        },
        resources {
            game_time: GameTime,
            score: u32,
        }
    }
}

pub struct MyGame {
    game: GameWorld,
}
}

The two worlds are linked through the engine's EngineEntity(Entity) component (at nightshade::ecs::sync::EngineEntity). Game-side entities store the engine-side entity they correspond to, and a render-sync pass copies positions or transforms from the game world to the engine world each frame. The helpers sync_engine_translation, sync_engine_transform, and despawn_linked cover the common cases. The pattern is documented in detail in the ECS chapters.

Splitting systems into modules

Once run_systems grows past a screen of code, break it apart by concern.

#![allow(unused)]
fn main() {
// src/systems/mod.rs
pub mod camera;
pub mod player;
pub mod enemies;
pub mod ui;

// src/game.rs
mod systems;

impl State for MyGame {
    fn run_systems(&mut self, world: &mut World) {
        systems::player::update(&mut self.game, world);
        systems::camera::follow(&self.game, world);
        systems::enemies::ai(&mut self.game, world);
        systems::ui::update(&self.game, world);
    }
}
}

Each system file is a flat set of free functions over (&mut GameWorld, &mut World) or whichever subset it needs. No traits, no inheritance, no manager objects. The naming follows the engine's own convention. Behavior lives in systems/<name>.rs, not in state.rs.

Architecture Overview

Nightshade is a layered dependency graph. Each layer builds on the one below it, and no layer references anything above it. This chapter walks the layers from the bottom up.

Feature Layer:     Terrain, Particles, NavMesh, Grass
                            |
Application Layer: State Trait, Main Loop, Event Bus
                            |
Rendering Layer:   Render Graph -> Passes -> Materials -> Textures -> Shaders
                            |
Simulation Layer:  Physics (Rapier), Animation, Audio (Kira)
                            |
Core Layer:        World, Transform Hierarchy, Input, Time, Windowing
                            |
Foundation Layer:  ECS (freecs), Math (nalgebra_glm), GPU (wgpu)

Foundation layer

The bottom of the graph is three independent systems that everything else depends on.

freecs is the ECS. Its ecs! macro generates a World struct, the per-component storage in struct-of-arrays layout, the query methods, and the entity allocator. The whole thing compiles down to typed accessors over packed Vecs with no virtual dispatch and no unsafe. The result is the kind of cache-coherent access that a hand-rolled archetype storage gives.

nalgebra_glm is the math library. Vectors (Vec2, Vec3, Vec4), matrices (Mat4), quaternions (Quat), and the linear algebra operations that go with them. Nightshade uses nalgebra_glm exclusively. There is no glam anywhere in the codebase.

wgpu is the GPU API. One Rust surface targets Vulkan, Metal, DirectX 12, and WebGPU. Every rendering pass in Nightshade is built against wgpu directly.

Core layer

Built on the foundation, the core layer manages per-frame state and the entity hierarchy.

World is the central data container generated by the freecs::ecs! macro. It holds all entity storage and a Resources struct of global singletons grouped by domain (timing, input, graphics settings, caches, physics world, audio engine, and the rest).

The transform hierarchy propagates LocalTransform through parent-child relationships to compute GlobalTransform matrices each frame. A dirty-flag system ensures only modified subtrees recompute. Manually setting a transform requires a mark_local_transform_dirty(world, entity) call so the next propagation pass picks up the change.

Input aggregates keyboard, mouse, and gamepad state each frame into world.resources.input. Both polling (is_key_pressed) and event-driven (on_keyboard_input) access patterns are available.

Time lives at world.resources.window.timing. The fields are delta_time, frames_per_second, uptime_milliseconds, frame_counter, and raw vs. speed-adjusted variants.

Windowing wraps winit. Window creation, event handling, and surface management all flow through it. On native platforms, secondary windows are supported through world.resources.secondary_windows.

Simulation layer

Systems that update world state every frame, independent of rendering.

Rapier3D runs the physics at a fixed 60 Hz timestep, with interpolation so rendering stays smooth between physics ticks. Rigid bodies, colliders, character controllers, joints, and raycasting are exposed through the physics feature flag.

Animation samples skeletal animations loaded from glTF files. Blending, crossfading, speed control, and looping are all part of the runtime. Bone transforms are written directly into the ECS each frame so the renderer reads them the same way it reads any other transform.

Kira drives audio. Sound playback, spatial positioning, and distance attenuation sit behind the audio feature flag.

Rendering layer

The rendering layer turns ECS state into pixels.

The render graph is a dependency-driven frame graph built on petgraph. Passes declare which resources they read and write through named slots. The graph builds the dependency edges, topologically sorts the passes, computes resource lifetimes, aliases transient GPU memory between non-overlapping passes, and picks the load and store operations that fit.

Passes implement the PassNode trait. Each pass owns its GPU pipelines and bind group layouts. The built-in passes cover shadow mapping, PBR mesh rendering, skeletal animation, grass, particles, text, UI, and post-processing (SSAO, SSGI, SSR, bloom, depth of field, tonemapping, and effects).

Materials use a PBR metallic-roughness workflow stored in a MaterialRegistry. Materials reference textures by name and attach to entities via MaterialRef.

Textures live in a TextureCache that handles GPU upload and format conversion. The way to load a texture is to push a WorldCommand::LoadTexture onto the command queue.

Shaders are written in WGSL and embedded into the binary at compile time via include_str!.

Application layer

The interface between the engine and game code.

The State trait is what the game struct implements. Its methods (initialize, run_systems, configure_render_graph, the input handlers) are called by the engine at fixed points in the frame lifecycle.

The main loop drives the lifecycle. It processes events, updates input, calls run_systems, dispatches events, runs the frame schedule, renders, and presents.

The frame schedule is a data-driven ordered list of engine system functions stored at world.resources.schedules.frame. It dispatches audio, camera, physics, animation, transform propagation, and cleanup systems each frame. A game can insert, remove, or reorder systems from initialize.

The event bus at world.resources.event_bus provides decoupled communication between systems. Typed app events and input messages flow through it.

Feature layer

High-level gameplay systems built on everything below.

Data flow per frame

A frame's data flow runs the layers top to bottom and then renders.

Input Events (winit)
    |
    v
Input State (world.resources.input)
    |
    v
Game Logic (State::run_systems)
    |
    v
ECS Mutations (spawn, despawn, set components)
    |
    v
FrameSchedule Dispatch:
    |-- Audio initialization and update
    |-- Camera aspect ratios
    |-- Physics Step (Rapier simulation, sync back to ECS)
    |-- Animation (bone transforms written to ECS)
    |-- Transform Propagation (LocalTransform -> GlobalTransform)
    |-- Instanced mesh caches, text sync
    |-- Input reset, deferred commands, cleanup
    |
    v
Render Graph Execution
    |-- Shadow Depth Pass (reads GlobalTransform, Light)
    |-- Geometry Passes (reads GlobalTransform, RenderMesh, MaterialRef)
    |-- Post-Processing (reads scene_color, depth, normals)
    |-- UI Pass (reads retained UI state)
    |-- Blit Pass (writes to swapchain)
    |
    v
Present (wgpu surface present)

The game touches the top of this graph (input state, game logic, ECS mutations). The engine handles the rest.

Feature flags

Most subsystems are opt-in through Cargo features.

Entity Component System

Nightshade's ECS is freecs. The whole World struct, every per-component accessor, the archetype tables, the query plumbing, and the resource layout are stamped out by one declarative macro at compile time. No proc macros, no trait objects, no unsafe.

An ECS separates the data from the work. An entity is a small handle, a generational id with no fields and no methods. A component is a plain struct attached to that handle, like LocalTransform or Light. A system is a function that reads or writes components on the entities matching a query, like "every entity with RENDER_MESH and LOCAL_TRANSFORM." The data lives in components, the work happens in systems, and entities are the keys that line them up.

The point of doing it this way instead of with object-oriented game objects is layout. An OOP game object packs position, velocity, health, and mesh into a single class instance, with the fields of each instance scattered across the heap. A loop that wants to advance physics has to touch every instance's position and velocity, paying a cache miss for each one. The fix is to flip the storage. Group entities by which components they have, lay out each component type as its own dense Vec, and the physics loop becomes a stride-1 walk through packed memory.

Archetype storage

Entities with the same set of components live in the same archetype table. Inside each table, every component type gets its own contiguous Vec in slot-aligned order. The position at index 7 and the velocity at index 7 belong to the same entity.

Table A  (mask: LOCAL_TRANSFORM | GLOBAL_TRANSFORM)
  local_transforms:  [t0, t1, t2]
  global_transforms: [g0, g1, g2]

Table B  (mask: LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH)
  local_transforms:  [t3, t4]
  global_transforms: [g3, g4]
  render_meshes:     [m3, m4]

A query for LOCAL_TRANSFORM | GLOBAL_TRANSFORM checks each table's mask with a single table.mask & query_mask == query_mask. Both tables match. A query for RENDER_MESH only matches Table B. Tables whose masks miss any requested bit are skipped without looking at a single entity inside them.

This is "structure of arrays" instead of "array of structures." Iteration through the inner loop is a stride-1 read on dense arrays the CPU prefetcher can predict. There are no per-entity hash lookups and no v-table dispatch. The cost is paid once at structural-change time when an entity has to migrate between archetypes, not on every access.

Component flags

Each component is assigned a bit position at compile time. An entity's archetype is identified by a ComponentFlags integer where bit N is set if the entity has component N.

LOCAL_TRANSFORM    = 1 << 0
GLOBAL_TRANSFORM   = 1 << 1
RENDER_MESH        = 1 << 2
MATERIAL_REF       = 1 << 3

Combine flags with | to describe a set of components. A query for LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF is one integer that names the archetypes the renderer cares about.

#![allow(unused)]
fn main() {
const RENDERABLE: ComponentFlags =
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF;

let entity = world.spawn_entities(RENDERABLE, 1)[0];
}

The full list of built-in flags is in the Components chapter.

Quick tour

#![allow(unused)]
fn main() {
use nightshade::prelude::*;

let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF,
    1,
)[0];

world.core.set_local_transform(entity, LocalTransform {
    translation: Vec3::new(0.0, 5.0, 0.0),
    rotation: Quat::identity(),
    scale: Vec3::new(1.0, 1.0, 1.0),
});
world.core.set_render_mesh(entity, RenderMesh {
    name: "cube".to_string(),
    id: None,
});
world.core.set_material_ref(entity, MaterialRef::new("Default"));

for entity in world.core.query_entities(RENDER_MESH | LOCAL_TRANSFORM) {
    let transform = world.core.get_local_transform(entity).unwrap();
    let mesh = world.core.get_render_mesh(entity).unwrap();
}
}

Spawn returns a Vec<Entity> of length count. The set methods write a component value into the slot. The query returns an iterator over every entity whose archetype has at least the requested bits.

A second ECS for game logic

The engine World holds rendering, physics, transforms, and the rest of the engine state. Game logic that does not belong in the engine, things like player state, inventory, AI, and score, lives in a second freecs::ecs! block the game defines on its own.

#![allow(unused)]
fn main() {
use freecs::ecs;

ecs! {
    GameWorld {
        player_state: PlayerState => PLAYER_STATE,
        inventory: Inventory => INVENTORY,
        health: Health => HEALTH,
        enemy_ai: EnemyAI => ENEMY_AI,
    }
    Resources {
        game_time: GameTime,
        score: u32,
        level: u32,
    }
}
}

The game holds both worlds and runs systems against each.

#![allow(unused)]
fn main() {
pub struct MyGame {
    game: GameWorld,
}

impl State for MyGame {
    fn run_systems(&mut self, world: &mut World) {
        update_player(&mut self.game);
        sync_positions(&self.game, world);
    }
}
}

The dual-world pattern is covered in detail in apps/game/src/systems/props.rs. The link from a game entity to its engine-side render entity is an EngineEntity(Entity) component that the engine ships.

Chapter guide

• The freecs Macro. Macro syntax and what gets generated.
• Entities. Spawning, despawning, and the entity handle.
• Components. The 45 built-in core components.
• Queries and Iteration. Querying and walking entities.
• Resources. Global singleton state.
• Tags, Events, and Commands. Cross-system messaging and deferred operations.

The freecs Macro

freecs::ecs! is one declarative macro that takes a list of components, tags, events, and resources and emits the entire World. The struct, the per-component fields on each archetype table, the typed accessors, the spawn and despawn code, the query iterator, the archetype graph, the query cache, the change-detection tick stamps, and the Resources block all come out of a single invocation.

Macro syntax

#![allow(unused)]
fn main() {
freecs::ecs! {
    World {
        Core {
            local_transform: LocalTransform => LOCAL_TRANSFORM,
            global_transform: GlobalTransform => GLOBAL_TRANSFORM,
            render_mesh: RenderMesh => RENDER_MESH,
            material_ref: MaterialRef => MATERIAL_REF,
            camera: Camera => CAMERA,
            light: Light => LIGHT,
        }
        Ui {
            ui_layout_root: UiLayoutRoot => UI_LAYOUT_ROOT,
            ui_layout_node: UiLayoutNode => UI_LAYOUT_NODE,
        }
    }
    Resources {
        window: Window,
        input: Input,
        graphics: Graphics,
        active_camera: Option<Entity>,
    }
}
}

Nightshade splits its components across two sub-worlds. Core holds the 3D engine components. Ui holds the retained UI components. Accessors are scoped to their sub-world. The light getter is world.core.get_light(entity). The UI node getter is world.ui.get_ui_layout_node(entity).

Each line in a component block has three parts.

1. The field name (snake_case). Used to generate the accessor methods.
2. The component type. The Rust struct stored in the archetype tables.
3. The flag constant (UPPER_SNAKE_CASE). The bit position used in queries.

What the macro generates

The World struct

#![allow(unused)]
fn main() {
pub struct World {
    entities: EntityStorage,
    pub resources: Resources,
}
}

EntityStorage holds the archetype tables, the entity location map, the allocator, and the caches. The resources field holds whatever was declared in the Resources block.

Per-component accessors

For every foo: Foo => FOO, the macro stamps out the three accessors a system needs.

#![allow(unused)]
fn main() {
world.core.get_foo(entity) -> Option<&Foo>
world.core.get_foo_mut(entity) -> Option<&mut Foo>
world.core.set_foo(entity, value: Foo)
}

get_foo and get_foo_mut return None for a stale or invalid handle, and for a live entity whose archetype does not contain Foo. set_foo writes the value if the slot exists. The setter does not add the component to entities that did not have it at spawn time. To add a component to a live entity, see add_components below.

Entity management

#![allow(unused)]
fn main() {
world.spawn_entities(flags: ComponentFlags, count: usize) -> Vec<Entity>
world.despawn_entities(entities: &[Entity])
world.core.entity_has_components(entity: Entity, flags: ComponentFlags) -> bool
world.core.add_components(entity: Entity, flags: ComponentFlags)
}

spawn_entities allocates count entities into the archetype identified by flags and returns their handles. despawn_entities removes a batch of entities and recycles their ids with a bumped generation. add_components migrates an entity to the archetype current_mask | flags, leaving its existing components in place.

Query methods

#![allow(unused)]
fn main() {
world.core.query_entities(flags: ComponentFlags) -> impl Iterator<Item = Entity>
}

Yields every entity whose archetype is a superset of flags. See Queries and Iteration for the closure-form and structural-change patterns.

Component flag constants

#![allow(unused)]
fn main() {
pub const LOCAL_TRANSFORM: ComponentFlags = 1 << 0;
pub const GLOBAL_TRANSFORM: ComponentFlags = 1 << 1;
pub const RENDER_MESH: ComponentFlags = 1 << 2;
// one constant per component, ascending bit positions
}

ComponentFlags is a u64, so a world holds at most 64 component types per sub-world. Nightshade declares 45 in Core and 10 in Ui, well under the ceiling.

The Resources struct

#![allow(unused)]
fn main() {
pub struct Resources {
    pub window: Window,
    pub input: Input,
    pub graphics: Graphics,
    pub active_camera: Option<Entity>,
}
}

Every resource is a public field with Default initialization. Systems read and write directly. world.resources.graphics.bloom_enabled = true is the API.

Nightshade's declaration

The engine declares 45 core components and 10 UI components across the two sub-worlds, plus 30-odd resources. The core component table follows.

Components

Resources

Feature-gated resources are wrapped in #[cfg(feature = "...")] inside the macro invocation. They simply do not exist on the Resources struct when the feature is off.

Entities

An entity is a handle. It owns nothing. It is a generational id the storage uses to locate the components that belong to it.

#![allow(unused)]
fn main() {
pub use freecs::Entity;
}

Entity is a Copy struct holding an index and a generation counter. The index points at a slot in the entity location map. The generation is bumped every time that slot is recycled, which is how stale handles get rejected. If you despawn entity 42 and the allocator hands 42 back out for a new entity, the old handle still has the old generation and will fail to resolve. Stale lookups return None instead of silently pointing at the wrong entity.

Spawning

spawn_entities takes a component flag mask and a count, and returns a Vec<Entity> of newly-created entities sitting in the archetype defined by that mask. Components start at Default::default().

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF,
    1,
)[0];
}

Set the component values after spawn.

#![allow(unused)]
fn main() {
world.core.set_local_transform(entity, LocalTransform {
    translation: Vec3::new(0.0, 1.0, 0.0),
    rotation: Quat::identity(),
    scale: Vec3::new(1.0, 1.0, 1.0),
});

world.core.set_render_mesh(entity, RenderMesh {
    name: "cube".to_string(),
    id: None,
});

world.core.set_material_ref(entity, MaterialRef::new("Default"));
}

Batch spawning

The count parameter is the speed-versus-individual-handling trade-off. Spawning a hundred entities in one call writes the archetype table once and grows each component vec once, instead of a hundred separate spawns each doing the same work.

#![allow(unused)]
fn main() {
let entities = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 100);

for (index, entity) in entities.iter().enumerate() {
    world.core.set_local_transform(*entity, LocalTransform {
        translation: Vec3::new(index as f32 * 2.0, 0.0, 0.0),
        ..Default::default()
    });
}
}

Helper functions

Common entity shapes have spawn helpers in the prelude. The helpers pick the right component mask, spawn the entity, and write sensible defaults.

#![allow(unused)]
fn main() {
spawn_cube_at(world, Vec3::new(0.0, 1.0, 0.0));
spawn_sphere_at(world, Vec3::new(2.0, 1.0, 0.0));
spawn_plane_at(world, Vec3::zeros());
spawn_cylinder_at(world, Vec3::new(4.0, 1.0, 0.0));
spawn_cone_at(world, Vec3::new(6.0, 1.0, 0.0));
spawn_torus_at(world, Vec3::new(8.0, 1.0, 0.0));

let camera = spawn_camera(world, Vec3::new(0.0, 5.0, 10.0), "Main Camera".to_string());
world.resources.active_camera = Some(camera);

let sun = spawn_sun(world);

let (player_entity, camera_entity) = spawn_first_person_player(world, Vec3::new(0.0, 2.0, 0.0));
}

Loading models

Models from glTF and GLB files come through the prefab pipeline. The importer extracts textures, meshes, and prefab definitions, and the game inserts each piece into the right cache before spawning instances.

#![allow(unused)]
fn main() {
use nightshade::ecs::prefab::*;

let model_bytes = include_bytes!("../assets/character.glb");
let result = import_gltf_from_bytes(model_bytes)?;

for (name, (rgba_data, width, height)) in result.textures {
    world.queue_command(WorldCommand::LoadTexture {
        name,
        rgba_data,
        width,
        height,
    });
}

for (name, mesh) in result.meshes {
    mesh_cache_insert(&mut world.resources.mesh_cache, name, mesh);
}

for prefab in result.prefabs {
    spawn_prefab_with_animations(
        world,
        &prefab,
        &result.animations,
        Vec3::new(0.0, 0.0, 0.0),
    );
}
}

Textures go through the command queue rather than the cache directly because texture uploads require GPU access and have to wait for the render phase. See Tags, Events, and Commands for the rest of the deferred-operation API.

Despawning

#![allow(unused)]
fn main() {
world.despawn_entities(&[entity]);

despawn_recursive_immediate(world, entity);

world.queue_command(WorldCommand::DespawnRecursive { entity });
}

The three calls do different things. despawn_entities removes a single entity and recycles its handle. despawn_recursive_immediate walks the entity's transform hierarchy and despawns every descendant alongside it, immediately. The queued DespawnRecursive command does the same recursive walk but waits until the next command-processing point, which is the safe choice when the iteration borrowing the world cannot yet release it.

Adding components after spawn

add_components migrates an entity to a new archetype that includes the requested bits. The existing components are moved across, the newly-added components start at Default::default(), and the entity's location is updated.

#![allow(unused)]
fn main() {
world.core.add_components(entity, AUDIO_SOURCE);
world.core.set_audio_source(entity, AudioSource::new("music").playing());

world.core.add_components(camera, AUDIO_LISTENER);
world.core.set_audio_listener(camera, AudioListener);
}

The cost of add_components is one archetype migration. Every existing component on the entity gets moved between tables. For markers that flip every frame, that cost is wasted and a tag is the better fit. For one-time additions like "give this camera an audio listener," it is fine.

Checking components

#![allow(unused)]
fn main() {
if world.core.entity_has_components(entity, RENDER_MESH) {
    // entity has a mesh
}

if world.core.entity_has_components(entity, ANIMATION_PLAYER | SKIN) {
    // entity is an animated skinned model
}
}

The check is a single bitwise AND against the archetype mask. It does not touch the entity's component data.

Parent-child relationships

Children are entities with a Parent component pointing at the parent's handle. The parent does not need to know about its children up front. The transform system walks the dirty-flag chain to propagate matrices, and the children cache (world.resources.children_cache) is rebuilt incrementally from the parent links.

#![allow(unused)]
fn main() {
let parent = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];
let child = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM | PARENT, 1)[0];

world.core.set_parent(child, Parent(Some(parent)));
world.core.set_local_transform(child, LocalTransform {
    translation: Vec3::new(0.0, 1.0, 0.0),
    ..Default::default()
});
}

Full coverage of hierarchical transforms is in Transform Hierarchy.

Spawning Entities

Every entity in Nightshade comes out of spawn_entities. The call takes a component flag mask and a count, and returns a Vec<Entity> of newly-created entities living in the archetype defined by that mask.

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF,
    1
)[0];
}

Components start at their Default values. Write the actual values with the per-component setters.

#![allow(unused)]
fn main() {
world.core.set_local_transform(entity, LocalTransform {
    translation: Vec3::new(0.0, 1.0, 0.0),
    rotation: Quat::identity(),
    scale: Vec3::new(1.0, 1.0, 1.0),
});

world.core.set_render_mesh(entity, RenderMesh {
    name: "cube".to_string(),
    id: None,
});

world.core.set_material_ref(entity, MaterialRef::new("Default"));
}

Spawning many at once

count > 1 batches the work. The archetype table is located once, every component vec grows once, and the entity allocator hands back a packed range of handles.

#![allow(unused)]
fn main() {
let entities = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 100);

for (index, entity) in entities.iter().enumerate() {
    world.core.set_local_transform(*entity, LocalTransform {
        translation: Vec3::new(index as f32 * 2.0, 0.0, 0.0),
        ..Default::default()
    });
}
}

For thousands of entities the batch form is meaningfully faster than a loop of individual spawns.

Helper functions

Common entity shapes have spawn helpers in the prelude. Each helper picks the right component mask, spawns the entity, and writes sensible defaults so the caller does not have to know which components a given object actually needs.

Cameras

#![allow(unused)]
fn main() {
let camera = spawn_camera(world, Vec3::new(0.0, 5.0, 10.0), "Main Camera".to_string());
world.resources.active_camera = Some(camera);

let orbit_camera = spawn_pan_orbit_camera(
    world,
    Vec3::zeros(),
    10.0,
    0.5,
    0.4,
    "Orbit Camera".to_string(),
);
}

spawn_camera makes a perspective camera at the given position. spawn_pan_orbit_camera adds the PAN_ORBIT_CAMERA component so the pan-orbit controller can drive it. The active-camera resource holds the entity the renderer pulls from each frame.

Lights

#![allow(unused)]
fn main() {
let sun = spawn_sun(world);
}

spawn_sun creates a directional light with reasonable defaults. Point and spot lights are spawned by hand because the Light struct carries the type-discriminating fields.

#![allow(unused)]
fn main() {
let light = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LIGHT,
    1,
)[0];

world.core.set_local_transform(light, LocalTransform {
    translation: Vec3::new(0.0, 3.0, 0.0),
    ..Default::default()
});

world.core.set_light(light, Light {
    light_type: LightType::Point,
    color: Vec3::new(1.0, 0.8, 0.6),
    intensity: 5.0,
    range: 10.0,
    cast_shadows: true,
    shadow_bias: 0.005,
    inner_cone_angle: 0.0,
    outer_cone_angle: 0.0,
});
}

Primitives

#![allow(unused)]
fn main() {
spawn_cube_at(world, Vec3::new(0.0, 1.0, 0.0));
spawn_sphere_at(world, Vec3::new(2.0, 1.0, 0.0));
spawn_plane_at(world, Vec3::zeros());
spawn_cylinder_at(world, Vec3::new(4.0, 1.0, 0.0));
spawn_cone_at(world, Vec3::new(6.0, 1.0, 0.0));
spawn_torus_at(world, Vec3::new(8.0, 1.0, 0.0));
}

Each primitive helper picks up the matching mesh from the built-in mesh cache and applies the default material.

Physics objects

Physics spawn helpers live in nightshade::ecs::physics::commands rather than the prelude, because they are only available with the physics feature on.

#![allow(unused)]
fn main() {
use nightshade::ecs::physics::commands::*;

let dynamic_cube = spawn_dynamic_physics_cube_with_material(
    world,
    Vec3::new(0.0, 5.0, 0.0),
    Vec3::new(1.0, 1.0, 1.0),
    1.0,
    Material {
        base_color: [0.8, 0.2, 0.2, 1.0],
        ..Default::default()
    },
);

let floor = spawn_static_physics_cube_with_material(
    world,
    Vec3::new(0.0, -0.5, 0.0),
    Vec3::new(50.0, 1.0, 50.0),
    Material::default(),
);
}

The full set is spawn_static_physics_cube_with_material, spawn_dynamic_physics_cube_with_material, spawn_dynamic_physics_sphere_with_material, and spawn_dynamic_physics_cylinder_with_material.

To roll a physics entity by hand, combine the rendering flags with RIGID_BODY and COLLIDER directly.

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY
    | RENDER_MESH | MATERIAL_REF | RIGID_BODY | COLLIDER,
    1,
)[0];

world.core.set_local_transform(entity, LocalTransform {
    translation: Vec3::new(0.0, 5.0, 0.0),
    ..Default::default()
});

world.core.set_render_mesh(entity, RenderMesh {
    name: "cube".to_string(),
    id: None,
});

world.core.set_material_ref(entity, MaterialRef::new("Default"));

world.core.set_rigid_body(entity, RigidBodyComponent {
    body_type: RigidBodyType::Dynamic,
    ..Default::default()
});
}

Character controllers

#![allow(unused)]
fn main() {
let (player_entity, camera_entity) = spawn_first_person_player(world, Vec3::new(0.0, 2.0, 0.0));
}

spawn_first_person_player returns the player entity and the camera entity attached to it. The player owns the character controller. The camera is a child entity at eye height.

Loading models

#![allow(unused)]
fn main() {
use nightshade::ecs::prefab::*;

let model_bytes = include_bytes!("../assets/character.glb");
let result = import_gltf_from_bytes(model_bytes)?;

for (name, (rgba_data, width, height)) in result.textures {
    world.queue_command(WorldCommand::LoadTexture {
        name,
        rgba_data,
        width,
        height,
    });
}

for (name, mesh) in result.meshes {
    mesh_cache_insert(&mut world.resources.mesh_cache, name, mesh);
}

for prefab in result.prefabs {
    let entity = spawn_prefab_with_animations(
        world,
        &prefab,
        &result.animations,
        Vec3::new(0.0, 0.0, 0.0),
    );
}
}

Textures are queued as LoadTexture commands because GPU uploads cannot run inline. Meshes go straight into the mesh cache because they are CPU-side data. spawn_prefab_with_animations walks the prefab tree, spawns one entity per node, wires up the Parent links, and attaches the animations to the root.

Adding components after spawn

#![allow(unused)]
fn main() {
world.core.add_components(entity, AUDIO_SOURCE);
world.core.set_audio_source(entity, AudioSource::new("music").playing());
}

add_components migrates the entity to the archetype current_mask | AUDIO_SOURCE. The existing components ride along. The audio source starts at Default::default() and the next line writes the real value.

Despawning

#![allow(unused)]
fn main() {
world.despawn_entities(&[entity]);

despawn_recursive_immediate(world, entity);
}

The first removes a single entity. The second removes the entity and every descendant in its transform hierarchy. For a deferred variant that waits until the next command-processing point, queue WorldCommand::DespawnRecursive instead.

Spawning a child

A child is an entity with a Parent component pointing at the parent's handle. The transform system handles the matrix propagation.

#![allow(unused)]
fn main() {
let parent = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];
let child = world.spawn_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM | PARENT, 1)[0];

world.core.set_parent(child, Parent(Some(parent)));
world.core.set_local_transform(child, LocalTransform {
    translation: Vec3::new(0.0, 1.0, 0.0),
    ..Default::default()
});
}

Components

Nightshade ships 55 built-in components. 45 live in the Core sub-world and cover the 3D engine. The remaining 10 live in Ui and are documented in Retained UI. This chapter catalogues the core set by category.

Transform components

The transform components hold each entity's position in the scene graph, both relative to its parent and in world space.

#![allow(unused)]
fn main() {
pub struct LocalTransform {
    pub translation: Vec3,
    pub rotation: Quat,
    pub scale: Vec3,
}

pub struct GlobalTransform(pub Mat4);

pub struct Parent(pub Option<Entity>);
}

The dirty-marker pattern is the speed trick. Instead of rebuilding every global matrix every frame, the transform system only touches entities that carry LOCAL_TRANSFORM_DIRTY, plus their descendants. After a manual write to a LocalTransform, call mark_local_transform_dirty(world, entity) so the propagation system picks it up.

Rendering components

These are the components the renderer reads when it iterates renderable archetypes.

#![allow(unused)]
fn main() {
pub struct RenderMesh {
    pub name: String,
    pub id: Option<MeshId>,
}

pub struct MaterialRef {
    pub name: String,
    pub id: Option<MaterialId>,
}
}

MaterialRef::new(name) takes impl Into<String>, so the call is the natural one.

#![allow(unused)]
fn main() {
MaterialRef::new("Default")
}

The id fields are resolved lazily. The first access hashes the name to a cache id and caches the result on the component.

Camera components

There is a single CAMERA flag. The projection mode (perspective or orthographic) is decided by the Projection enum inside the Camera struct, not by a separate component.

#![allow(unused)]
fn main() {
pub struct Camera {
    pub projection: Projection,
    pub smoothing: Option<Smoothing>,
}

pub enum Projection {
    Perspective(PerspectiveCamera),
    Orthographic(OrthographicCamera),
}

pub struct PerspectiveCamera {
    pub aspect_ratio: Option<f32>,
    pub y_fov_rad: f32,
    pub z_far: Option<f32>,
    pub z_near: f32,
}

pub struct OrthographicCamera {
    pub x_mag: f32,
    pub y_mag: f32,
    pub z_far: f32,
    pub z_near: f32,
}
}

aspect_ratio: None means "follow the window aspect." z_far: None means "no far plane," which is what reverse-Z infinite projection wants.

Lighting

#![allow(unused)]
fn main() {
pub struct Light {
    pub light_type: LightType,
    pub color: Vec3,
    pub intensity: f32,
    pub range: f32,
    pub cast_shadows: bool,
    pub shadow_bias: f32,
    pub inner_cone_angle: f32,
    pub outer_cone_angle: f32,
}

pub enum LightType {
    Directional,
    Point,
    Spot,
}
}

Like cameras, one flag covers all three light types. inner_cone_angle and outer_cone_angle are zero for non-spot lights.

Physics components

Physics is feature-gated. These components only exist with the physics feature enabled.

#![allow(unused)]
fn main() {
pub struct RigidBodyComponent {
    pub handle: Option<RigidBodyHandle>,
    pub body_type: RigidBodyType,
    pub translation: [f32; 3],
    pub rotation: [f32; 4],
    pub linvel: [f32; 3],
    pub angvel: [f32; 3],
    pub mass: f32,
    pub locked_axes: LockedAxes,
}

pub enum RigidBodyType {
    Dynamic,
    Fixed,
    KinematicPositionBased,
    KinematicVelocityBased,
}
}

Constructors cover the common cases.

• RigidBodyComponent::new_dynamic()
• RigidBodyComponent::new_static() builds a Fixed body
• RigidBodyComponent::new_kinematic() builds a KinematicPositionBased body

The flag is RIGID_BODY, not RIGID_BODY_COMPONENT. The Component suffix is on the type only.

Animation components

#![allow(unused)]
fn main() {
pub struct AnimationPlayer {
    pub clips: Vec<AnimationClip>,
    pub current_clip: Option<usize>,
    pub blend_from_clip: Option<usize>,
    pub blend_factor: f32,
    pub playing: bool,
    pub speed: f32,
    pub time: f32,
    pub looping: bool,
}
}

blend_from_clip and blend_factor drive crossfades between two clips. When blend_from_clip is Some, the player produces the weighted blend of both clips at the same time index.

Audio components

Text components

The per-character color components are optional sidecars. Without them, every character uses the Text struct's main color.

Geometry

#![allow(unused)]
fn main() {
pub struct Lines {
    pub lines: Vec<Line>,
}

pub struct Line {
    pub start: Vec3,
    pub end: Vec3,
    pub color: Vec4,
}
}

Lines is rebuilt per frame by gizmo code. It is the cheap way to draw rays, bounding boxes, and navmesh edges without authoring a mesh.

Advanced components

Queries and Iteration

A query is "give me every entity that has at least this set of components." Because component presence is a bit in the archetype mask, the per-table check is a single table.mask & query_mask == query_mask. Tables that fail the check are skipped without looking at a single entity inside them.

Basic queries

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM) {
    if let Some(transform) = world.core.get_local_transform(entity) {
        let position = transform.translation;
    }
}
}

The query yields every entity whose archetype mask is a superset of the requested mask. An entity with LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH matches a query for LOCAL_TRANSFORM | GLOBAL_TRANSFORM.

The cost of this form is one location-map lookup per get_local_transform call. For read-only loops it is the most ergonomic API. For tight inner loops there are closure-form alternatives that hand the closure raw access to the archetype table, no per-entity lookup. See Querying Entities for that pattern.

Common patterns

Renderable entities

The renderer iterates one combined mask each frame.

#![allow(unused)]
fn main() {
const RENDERABLE: ComponentFlags =
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF;

for entity in world.core.query_entities(RENDERABLE) {
    let transform = world.core.get_global_transform(entity).unwrap();
    let mesh = world.core.get_render_mesh(entity).unwrap();
}
}

Physics entities

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(RIGID_BODY | LOCAL_TRANSFORM) {
    if let Some(rb) = world.core.get_rigid_body(entity) {
        if rb.body_type == RigidBodyType::Dynamic {
            // process dynamic bodies
        }
    }
}
}

Animated entities

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(ANIMATION_PLAYER) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.speed = 1.0;
    }
}
}

First match

For singleton-like entities (the player, the active camera, the world origin), pull the first match off the iterator.

#![allow(unused)]
fn main() {
let player = world.core.query_entities(CHARACTER_CONTROLLER).next();

if let Some(player_entity) = player {
    let controller = world.core.get_character_controller(player_entity);
}
}

Filtering

query_entities filters at the table level. A finer per-entity filter is just a normal if inside the loop body.

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(LIGHT) {
    let light = world.core.get_light(entity).unwrap();
    if light.light_type == LightType::Point {
        // point lights only
    }
}
}

The cost of this shape is that the iterator visits every entity with the requested bits, then filters in Rust. If the secondary filter is hot and selective, splitting the data into two archetypes (a separate flag per variant) is the faster shape.

Entity counts

#![allow(unused)]
fn main() {
let renderable_count = world.core.query_entities(RENDER_MESH).count();
let light_count = world.core.query_entities(LIGHT).count();
}

count consumes the iterator and walks every matching table's entities.len(). It is O(number of matching tables), not O(number of matching entities).

Looking entities up by name

If entities carry the Name component, the engine keeps a HashMap<String, Entity> in world.resources.entity_names. A direct hash lookup is the fast path.

#![allow(unused)]
fn main() {
let player = world.resources.entity_names.get("Player").copied();
}

A scan-based fallback is also available if you do not trust the cache or you are doing case-insensitive matching.

#![allow(unused)]
fn main() {
fn find_by_name(world: &World, name: &str) -> Option<Entity> {
    for entity in world.core.query_entities(NAME) {
        if let Some(entity_name) = world.core.get_name(entity) {
            if entity_name.0 == name {
                return Some(entity);
            }
        }
    }
    None
}

let player = find_by_name(world, "Player");
}

Walking children

Parent-to-child links are not stored on the parent. The engine maintains a HashMap<Entity, Vec<Entity>> cache so the children of a given entity can be found without scanning every PARENT component.

#![allow(unused)]
fn main() {
if let Some(children) = world.resources.children_cache.get(&parent_entity) {
    for child in children {
        if let Some(transform) = world.core.get_local_transform(*child) {
            // process child
        }
    }
}
}

Collecting for deferred work

Mutating the world during iteration invalidates the iterator. The fix is to collect the matching entity handles first, release the borrow, then operate.

#![allow(unused)]
fn main() {
let enemies: Vec<Entity> = world.core.query_entities(ENEMY_TAG | HEALTH).collect();

for enemy in &enemies {
    apply_damage(world, *enemy, 10.0);
}
}

The cost is one allocation per collected query. For structural mutations during iteration that should happen at a defined point in the frame, the better fit is the command queue described in Tags, Events, and Commands.

Iteration with index

#![allow(unused)]
fn main() {
for (index, entity) in world.core.query_entities(RENDER_MESH).enumerate() {
    // index is the position within the iteration, not the entity id
}
}

enumerate gives the iteration position, not the entity's internal id. For the id itself, read entity.id directly.

Querying Entities

query_entities(mask) is the basic shape. It returns an iterator over every entity whose archetype is a superset of mask.

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(LOCAL_TRANSFORM | GLOBAL_TRANSFORM) {
    if let Some(transform) = world.core.get_local_transform(entity) {
        let position = transform.translation;
    }
}
}

Each get_local_transform(entity) inside the loop is a location-map lookup followed by an archetype-mask check. That overhead is fine for read-only outer loops. For inner loops the closure-form world.core.query() / world.core.query_mut() API in the prelude hands the closure raw table access, see the engine's query docs for that pattern.

Common patterns

Renderable entities

#![allow(unused)]
fn main() {
const RENDERABLE: ComponentFlags = LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF;

for entity in world.core.query_entities(RENDERABLE) {
    let transform = world.core.get_global_transform(entity).unwrap();
    let mesh = world.core.get_render_mesh(entity).unwrap();
}
}

Physics entities

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(RIGID_BODY | LOCAL_TRANSFORM) {
    if let Some(rb) = world.core.get_rigid_body(entity) {
        if rb.body_type == RigidBodyType::Dynamic {
        }
    }
}
}

Animated entities

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(ANIMATION_PLAYER) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.speed = 1.0;
    }
}
}

Filtering inside the loop

query_entities filters at the table level. A finer per-entity check goes in a normal if inside the loop body.

#![allow(unused)]
fn main() {
for entity in world.core.query_entities(LIGHT) {
    let light = world.core.get_light(entity).unwrap();

    if light.light_type == LightType::Point {
    }
}
}

If the secondary filter is hot and selective, splitting the data into two archetypes is faster than filtering in Rust.

Checking components

#![allow(unused)]
fn main() {
if world.core.entity_has_components(entity, RENDER_MESH) {
}

if world.core.entity_has_components(entity, ANIMATION_PLAYER | SKIN) {
}
}

The check is one bitwise AND against the archetype mask. It does not read the component data.

First match

For singleton entities, next() pulls the first off the iterator.

#![allow(unused)]
fn main() {
let player = world.core.query_entities(CHARACTER_CONTROLLER).next();

if let Some(player_entity) = player {
    let controller = world.core.get_character_controller(player_entity);
}
}

Counts

#![allow(unused)]
fn main() {
let renderable_count = world.core.query_entities(RENDER_MESH).count();
let light_count = world.core.query_entities(LIGHT).count();
}

count is O(number of matching tables), not O(number of matching entities). The iterator stride is the per-table entities.len().

Named lookup

world.resources.entity_names is a HashMap<String, Entity> populated for every entity carrying the Name component. Direct hash lookup is the fast path.

#![allow(unused)]
fn main() {
let player = world.resources.entity_names.get("Player").copied();
}

The scan fallback is also fine.

#![allow(unused)]
fn main() {
fn find_by_name(world: &World, name: &str) -> Option<Entity> {
    for entity in world.core.query_entities(NAME) {
        if let Some(entity_name) = world.core.get_name(entity) {
            if entity_name.0 == name {
                return Some(entity);
            }
        }
    }
    None
}

let player = find_by_name(world, "Player");
}

Children of a parent

The engine keeps a HashMap<Entity, Vec<Entity>> of parent-to-children in world.resources.children_cache.

#![allow(unused)]
fn main() {
if let Some(children) = world.resources.children_cache.get(&parent_entity) {
    for child in children {
        if let Some(transform) = world.core.get_local_transform(*child) {
        }
    }
}
}

Iteration with index

#![allow(unused)]
fn main() {
for (index, entity) in world.core.query_entities(RENDER_MESH).enumerate() {
}
}

enumerate gives the iteration position. For the entity's internal id, read entity.id directly.

Collecting

Mutating the world during iteration invalidates the iterator. Collect the matching handles first, release the borrow, then operate.

#![allow(unused)]
fn main() {
let enemies: Vec<Entity> = world.core.query_entities(ENEMY_TAG | HEALTH).collect();

for enemy in &enemies {
    apply_damage(world, *enemy, 10.0);
}
}

The cost is one allocation per collected query. For deferred structural mutations that should happen at a defined point in the frame, the command queue in Tags, Events, and Commands is the right tool.

Resources

A resource is global state attached to the world, not to any entity. Delta time. The input snapshot for this frame. The list of loaded materials. The active camera. Each resource type exists exactly once in the world and lives on world.resources.

Systems read and write resources directly. There are no accessor functions, no per-resource fan-out. The freecs macro generates the Resources struct from the declaration block and gives every field public access.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;

    if world.resources.input.keyboard.is_key_pressed(KeyCode::Space) {
        self.jump();
    }

    world.resources.graphics.bloom_enabled = true;
}
}

Resource catalogue

Time and window

Input

Graphics

Caches

Scene

Simulation

Communication

Platform

Feature-gated resources

Resources whose subsystems are optional only exist when the relevant feature flag is on. Guard access with cfg.

#![allow(unused)]
fn main() {
#[cfg(feature = "physics")]
{
    world.resources.physics.gravity = Vec3::new(0.0, -9.81, 0.0);
}

#[cfg(feature = "audio")]
{
    world.resources.audio.master_volume = 0.8;
}
}

World commands

Operations that need GPU access, or that have to happen at a defined point in the frame, go through world.queue_command. The command queue is a Vec<WorldCommand> that the renderer drains at frame setup.

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::LoadTexture {
    name: "my_texture".to_string(),
    rgba_data: texture_bytes,
    width: 256,
    height: 256,
});

world.queue_command(WorldCommand::DespawnRecursive { entity });
world.queue_command(WorldCommand::LoadHdrSkybox { hdr_data });
world.queue_command(WorldCommand::CaptureScreenshot { path: None });
}

The render-time commands are GPU uploads and screenshot captures. The ECS-time commands (DespawnRecursive, ReloadMaterial) are drained by the process_commands_system in the frame schedule. The full breakdown of immediate-versus-deferred operations is in Tags, Events, and Commands.

Tags, Events, and Commands

The three patterns in this chapter all solve the same problem from different angles. One system needs to tell another system something, or one system needs to make a structural change that cannot happen while the iteration that prompted it still holds the world.

The event bus is for cross-system messages. World commands are for deferred mutations that need GPU access or have to wait for a specific point in the frame. Tags are not a separate subsystem in Nightshade today, they are markers expressed as zero-size components and queried through the normal flag-mask machinery.

The event bus

world.resources.event_bus is a VecDeque<Message> that systems push into and the game pops out of. The message variants cover input events and arbitrary app-defined payloads.

#![allow(unused)]
fn main() {
pub struct EventBus {
    pub messages: VecDeque<Message>,
}

pub enum Message {
    Input { event: InputEvent },
    App {
        type_name: &'static str,
        payload: Box<dyn Any + Send + Sync>,
    },
}
}

The trade-off is the boxed Any. Each app event allocates and pays a downcast at the consumer. The win is that the bus does not need to know about the app's event types at compile time. For games where event volume is low and latency is high (death notifications, door opens, inventory pickups), this cost is irrelevant. For high-frequency telemetry, the better fit is a dedicated typed queue inside Resources.

Publishing

Define a plain struct for each event type. Send it through publish_app_event.

#![allow(unused)]
fn main() {
pub struct EnemyDied {
    pub entity: Entity,
    pub position: Vec3,
}

pub struct ItemPickedUp {
    pub item_type: ItemType,
    pub quantity: u32,
}

fn combat_system(world: &mut World) {
    for enemy in world.core.query_entities(ENEMY | HEALTH) {
        let health = world.core.get_health(enemy).unwrap();
        if health.current <= 0.0 {
            let position = world.core.get_global_transform(enemy)
                .map(|t| t.0.column(3).xyz())
                .unwrap_or(Vec3::zeros());

            publish_app_event(world, EnemyDied {
                entity: enemy,
                position,
            });

            world.despawn_entities(&[enemy]);
        }
    }
}
}

Consuming

The game drains the bus during its frame loop and dispatches each message by type.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    while let Some(msg) = world.resources.event_bus.messages.pop_front() {
        match msg {
            Message::App { payload, .. } => {
                if let Some(died) = payload.downcast_ref::<EnemyDied>() {
                    self.handle_enemy_death(world, died);
                }
                if let Some(pickup) = payload.downcast_ref::<ItemPickedUp>() {
                    self.update_inventory(pickup);
                }
            }
            Message::Input { event } => {
                self.handle_input_event(event);
            }
        }
    }
}
}

The downcast pattern means several handlers can react to the same event without coupling. One system reads a DoorOpened to trigger a cutscene, another reads it to play a sound, neither knows the other exists.

#![allow(unused)]
fn main() {
publish_app_event(world, DoorOpened { door_id: 42 });

if let Some(door) = payload.downcast_ref::<DoorOpened>() {
    trigger_cutscene(world, door.door_id);
}

if let Some(door) = payload.downcast_ref::<DoorOpened>() {
    play_door_sound(world, door.door_id);
}
}

World commands

Commands are deferred operations. They go into world.resources.command_queue and are drained by the right subsystem at the right point in the frame. The two main reasons to defer are GPU access (texture uploads, HDR skybox loads, screenshot capture) and iteration safety (despawning entities mid-loop).

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::LoadTexture {
    name: "brick".to_string(),
    rgba_data: texture_bytes,
    width: 512,
    height: 512,
});

world.queue_command(WorldCommand::DespawnRecursive { entity });
world.queue_command(WorldCommand::LoadHdrSkybox { hdr_data });
world.queue_command(WorldCommand::CaptureScreenshot { path: None });
}

Available commands

Immediate vs deferred

Not every structural change needs to be deferred. Operations that do not touch the GPU and are not running inside a borrowing iteration can run inline.

#![allow(unused)]
fn main() {
// inline, happens immediately
world.despawn_entities(&[entity]);
despawn_recursive_immediate(world, entity);

// deferred, happens at the next command drain point
world.queue_command(WorldCommand::DespawnRecursive { entity });
}

The rule is the simple one. If the call would invalidate an iteration the current code is inside, queue it. If it would touch the GPU from a non-render system, queue it. Otherwise call directly.

The State trait event hook

The State trait has a dedicated handle_event method called once per message after run_systems. It is the cleanest place to handle events that drive state transitions.

#![allow(unused)]
fn main() {
fn handle_event(&mut self, world: &mut World, message: &Message) {
    match message {
        Message::App { payload, .. } => {
            if let Some(event) = payload.downcast_ref::<MyEvent>() {
                self.process_event(world, event);
            }
        }
        _ => {}
    }
}
}

The engine dispatches each message exactly once, in order, then drains the bus.

Input events

Input events travel on the same bus.

#![allow(unused)]
fn main() {
pub enum InputEvent {
    KeyboardInput { key_code: u32, state: KeyState },
    GamepadConnected { gamepad_id: usize },
    GamepadDisconnected { gamepad_id: usize },
}

pub enum KeyState {
    Pressed,
    Released,
}
}

For polling-style input (held keys, mouse position) the snapshot in world.resources.input is the right shape. The event variants are for transitions that matter exactly once. Gamepad connect and disconnect, key repeat, IME input.

Practical notes

• Keep event payloads small. The Box<dyn Any> allocation cost is per-message.
• Drain the bus every frame. The queue is unbounded and will accumulate stale messages otherwise.
• Avoid circular events. System A reacting to event B by emitting event B will not terminate.
• Prefer immediate calls for pure ECS work that does not need to be deferred. The command queue exists for GPU access and iteration safety, not as the default.

Math & Coordinates

Nightshade uses nalgebra_glm for every piece of linear algebra. There is no in-house math library. Vectors, matrices, and quaternions all come from nalgebra_glm, and the prelude re-exports the core types.

Core Types

#![allow(unused)]
fn main() {
use nightshade::prelude::*;

let position = Vec3::new(1.0, 2.0, 3.0);
let direction = Vec3::y();
let identity = Mat4::identity();
let rotation = Quat::identity();
}

Coordinate System

The coordinate system is right-handed Y-up. Positive X is right, positive Y is up, positive Z points out of the screen toward the camera, and negative Z points into the scene.

    +Y (up)
     |
     |
     +--- +X (right)
    /
   /
  +Z (forward, toward camera)

This matches the glTF convention and nalgebra_glm's default handedness, which is why no flips or swaps are needed when loading glTF assets.

Vector Operations

Construction

#![allow(unused)]
fn main() {
let a = Vec3::new(1.0, 2.0, 3.0);
let zero = Vec3::zeros();
let one = Vec3::new(1.0, 1.0, 1.0);
let up = Vec3::y();
let right = Vec3::x();
let forward = -Vec3::z();
}

Arithmetic

+, -, and scalar * work as expected. The catch is element-wise multiplication, where * between two vectors does scalar multiplication, not per-component. For element-wise, use component_mul.

#![allow(unused)]
fn main() {
let sum = a + b;
let difference = a - b;
let scaled = a * 2.0;

let element_wise = a.component_mul(&b);
}

This trips up newcomers from glsl, where vec3 * vec3 means per-component multiplication. In nalgebra_glm, * follows linear-algebra conventions, and component_mul is the explicit form.

Common Operations

#![allow(unused)]
fn main() {
let length = nalgebra_glm::length(&v);
let normalized = nalgebra_glm::normalize(&v);
let dot = nalgebra_glm::dot(&a, &b);
let cross = nalgebra_glm::cross(&a, &b);
let distance = nalgebra_glm::distance(&a, &b);
let lerped = nalgebra_glm::lerp(&a, &b, 0.5);
}

Quaternions

Rotations are always quaternions. They avoid gimbal lock, compose cleanly, and interpolate smoothly with slerp. Euler angles are converted to quaternions when needed.

#![allow(unused)]
fn main() {
let rotation = nalgebra_glm::quat_angle_axis(
    std::f32::consts::FRAC_PI_4,
    &Vec3::y(),
);

let forward = nalgebra_glm::normalize(&(target - position));
let rotation = nalgebra_glm::quat_look_at(&forward, &Vec3::y());

let blended = rotation_a.slerp(&rotation_b, 0.5);

let rotated = nalgebra_glm::quat_rotate_vec3(&rotation, &direction);
}

quat_angle_axis builds a rotation of a given angle around a given axis. quat_look_at builds a rotation that orients the local forward toward a target direction with a specified up vector. slerp is spherical linear interpolation, the right way to blend two rotations. quat_rotate_vec3 applies a quaternion to a vector.

Transform Matrices

GlobalTransform stores a single 4x4 matrix. LocalTransform stores the decomposed translation, rotation, and scale.

#![allow(unused)]
fn main() {
pub struct LocalTransform {
    pub translation: Vec3,
    pub rotation: Quat,
    pub scale: Vec3,
}

pub struct GlobalTransform(pub Mat4);
}

The split is deliberate. Local transforms are easy to edit because translation, rotation, and scale are separate fields. Global transforms are easy to use because they bake the entire parent chain into one matrix multiplied through clip space by the renderer.

Building Matrices

#![allow(unused)]
fn main() {
let translation = nalgebra_glm::translation(&Vec3::new(1.0, 2.0, 3.0));
let rotation = nalgebra_glm::quat_to_mat4(&some_quat);
let scale = nalgebra_glm::scaling(&Vec3::new(2.0, 2.0, 2.0));
let combined = translation * rotation * scale;
}

Order matters. translation * rotation * scale is the standard TRS order, applied to a vector right-to-left. The scale is applied first, then the rotation, then the translation.

Extracting Position

The translation column of a 4x4 transform matrix is the fourth column. xyz() extracts the first three components.

#![allow(unused)]
fn main() {
let global = world.core.get_global_transform(entity).unwrap();
let position = global.0.column(3).xyz();
}

Angles

nalgebra_glm works in radians. Convert to and from degrees explicitly.

#![allow(unused)]
fn main() {
let radians = nalgebra_glm::radians(&nalgebra_glm::vec1(45.0)).x;
let degrees = nalgebra_glm::degrees(&nalgebra_glm::vec1(std::f32::consts::FRAC_PI_4)).x;
}

Depth Range and Reversed-Z

wgpu's depth range is [0, 1], not OpenGL's [-1, 1]. Nightshade goes one step further. The depth buffer is reversed-Z, where 0.0 is the far plane and 1.0 is the near plane, the opposite of the traditional convention.

The reason is floating-point precision. Floats have more precision near zero and less precision near one because of how the exponent and mantissa are distributed. In a standard depth buffer, the near plane maps to zero (high precision) and the far plane maps to one (low precision). Perspective projection is nonlinear, and most of the [0, 1] range is already consumed by geometry near the near plane. Combine the two distortions and there is almost no precision left for distant objects, which is what produces z-fighting in the middle distance of large scenes.

Reversed-Z flips the mapping. The far plane goes to zero (where float precision is highest) and the near plane goes to one. The perspective nonlinearity and the floating-point precision curve partially cancel, and the result is nearly uniform depth precision across the entire view range. The difference is dramatic for large outdoor scenes, where z-fighting at the horizon vanishes.

The practical consequences are three. The depth clear value is 0.0, since that is the far plane. The depth comparison function is Greater or GreaterEqual, since closer objects have larger depth values. Projection matrices are constructed with reversed_infinite_perspective_rh_zo rather than the standard perspective_rh_zo.

Time

Timing values are on world.resources.window.timing. There is no separate Time resource. Putting timing on the window struct matches the way the engine treats it, since timing is updated by the same code that updates the window each frame.

WindowTiming

#![allow(unused)]
fn main() {
pub struct WindowTiming {
    pub frames_per_second: f32,
    pub delta_time: f32,
    pub raw_delta_time: f32,
    pub time_speed: f32,
    pub last_frame_start_instant: Option<web_time::Instant>,
    pub current_frame_start_instant: Option<web_time::Instant>,
    pub initial_frame_start_instant: Option<web_time::Instant>,
    pub frame_counter: u32,
    pub uptime_milliseconds: u64,
}
}

delta_time is the scaled time in seconds since the previous frame. raw_delta_time is the unscaled value, before time_speed is applied. frames_per_second is the running rate. frame_counter is the count of frames since startup. uptime_milliseconds is wall-clock time since startup. The three Instant fields are the underlying timestamps used to compute the others.

Reading Time

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;
    let fps = world.resources.window.timing.frames_per_second;
    let elapsed = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;
    let frame = world.resources.window.timing.frame_counter;
}
}

Delta Time

delta_time is the value to multiply by when computing per-frame change. Movement, rotation, animation, anything that should happen at a consistent rate regardless of frame rate.

#![allow(unused)]
fn main() {
fn move_entity(world: &mut World, entity: Entity, velocity: Vec3) {
    let dt = world.resources.window.timing.delta_time;
    if let Some(transform) = world.core.get_local_transform_mut(entity) {
        transform.translation += velocity * dt;
    }
}
}

raw_delta_time ignores time_speed. Use it for things that should not respect time scaling. UI animations should keep going during a slow-motion gameplay moment, so the UI uses raw_delta_time. Gameplay physics that should slow down uses delta_time.

Time Speed

time_speed scales delta_time. The relation is delta_time = raw_delta_time * time_speed, so setting time_speed to zero freezes all delta_time-driven logic without stopping the render loop.

#![allow(unused)]
fn main() {
world.resources.window.timing.time_speed = 0.5;
world.resources.window.timing.time_speed = 2.0;
world.resources.window.timing.time_speed = 0.0;
}

The render loop keeps running at full rate. The frame counter still advances. Animations or UI driven by raw_delta_time still play. Only the values keyed off delta_time freeze.

Periodic Actions

For an action that fires every N seconds, accumulate delta_time into an f32 and reset when the accumulator crosses the threshold.

#![allow(unused)]
fn main() {
struct MyGame {
    spawn_timer: f32,
}

fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;
    self.spawn_timer += dt;
    if self.spawn_timer >= 2.0 {
        spawn_enemy(world);
        self.spawn_timer = 0.0;
    }
}
}

For very long intervals, the simpler approach is to check frame_counter or uptime_milliseconds directly.

Uptime

uptime_milliseconds is total wall-clock time since the application started. The standard use is driving shader animations that should loop continuously.

#![allow(unused)]
fn main() {
let time = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;
let wave = (time * 2.0).sin();
}

uptime_milliseconds is wall-clock and ignores time_speed, so a slow-motion effect does not affect a uniform shader wave.

Web Compatibility

The Instant fields use web_time::Instant, not std::time::Instant. std::time::Instant does not compile to wasm32 because the underlying system call is not available in the browser. web_time::Instant is a drop-in replacement that uses performance.now() on the web and falls back to std::time::Instant on native, so the same code runs on both targets without conditional compilation.

The State Trait

State is the interface between a game and the engine. A game is a type that implements State, and the engine drives it. The trait has five methods, all with defaults, so a minimal game implements none of them and gets a blank window.

Trait Definition

#![allow(unused)]
fn main() {
pub trait State {
    fn initialize(&mut self, _world: &mut World) {}
    fn configure_render_graph(
        &mut self,
        graph: &mut RenderGraph<World>,
        device: &wgpu::Device,
        surface_format: wgpu::TextureFormat,
        resources: RenderResources,
    ) { /* default: bloom + post-processing + swapchain blit */ }
    fn run_systems(&mut self, _world: &mut World) {}
    fn pre_render(&mut self, _renderer: &mut WgpuRenderer, _world: &mut World) {}
    fn update_render_graph(&mut self, _graph: &mut RenderGraph<World>, _world: &World) {}
}
}

Window state (title, icon, log config, next state) lives on the world.resources.window resource. Input, file-drop, gamepad, and lifecycle events arrive on world.resources.input.events as AppEvent values, and the application drains them in run_systems.

Window Configuration

Title

The window title is a String on the Window resource. Set it in initialize and a sync system propagates the value to the OS window each frame, so writes at runtime also take effect.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.window.title = "My Awesome Game".to_string();
}
}

Icon

The icon is Option<&'static [u8]> of PNG bytes. The default is the built-in Nightshade icon. Override it with include_bytes!, or set it to None to remove the icon entirely.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.window.icon_bytes = Some(include_bytes!("../assets/icon.png"));
}
}

The sync runs on desktop only and requires the assets feature.

Logging

File-based logging is configured through log_config: LogConfig on the Window resource. Logging is initialized before initialize runs, so the customization happens when building the initial Window, not inside the trait method.

#![allow(unused)]
fn main() {
let mut window = Window::default();
window.log_config = LogConfig {
    directory: "logs".to_string(),
    rotation: LogRotation::Daily,
    default_filter: "info".to_string(),
    timestamp_format: "%Y-%m-%d_%H-%M-%S".to_string(),
};
}

LogRotation is one of PerSession (new file each launch), Daily, or Never (append to a single file). Desktop only, requires the tracing feature.

initialize

Called once at startup. This is where the initial scene, the active camera, and the application's own state get built.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.graphics.atmosphere = Atmosphere::Sky;

    let camera = spawn_camera(world, Vec3::new(0.0, 5.0, 10.0), "Camera".to_string());
    world.resources.active_camera = Some(camera);

    self.player = Some(spawn_player(world));
}
}

run_systems

Called every frame, after the engine has updated input and timing but before the frame schedule runs. Game logic goes here.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    player_movement_system(world);
    enemy_ai_system(world);
    collision_response_system(world);
}
}

Input and Lifecycle Events

The engine pushes input, file-drop, gamepad, and lifecycle events onto world.resources.input.events as AppEvent values. Drain the queue in run_systems. Events not drained on the frame they arrive are lost, since the engine clears the queue after run_systems returns.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let events = std::mem::take(&mut world.resources.input.events);
    for event in events {
        match event {
            AppEvent::Keyboard { key, state } if state == KeyState::Pressed => match key {
                KeyCode::Escape => self.paused = !self.paused,
                KeyCode::F11 => toggle_fullscreen(world),
                _ => {}
            },
            AppEvent::Mouse { button, state } if state == ElementState::Pressed => match button {
                MouseButton::Left => self.shoot(world),
                MouseButton::Right => self.aim(world),
                _ => {}
            },
            AppEvent::Gamepad(gp_event) => {
                if let gilrs::EventType::ButtonPressed(button, _) = gp_event.event {
                    match button {
                        gilrs::Button::Start => self.paused = !self.paused,
                        gilrs::Button::South => self.player_jump(),
                        _ => {}
                    }
                }
            }
            AppEvent::FileDropped(file) => self.process_dropped_data(world, &file.name, &file.data),
            AppEvent::FileDroppedPath(path) => self.load_model(world, &path),
            AppEvent::FileHovered(_) => self.show_drop_indicator = true,
            AppEvent::FileHoverCancelled => self.show_drop_indicator = false,
            AppEvent::Suspended | AppEvent::Resumed => {}
        }
    }
}
}

configure_render_graph

Called once during initialization to build the render graph. The default configures bloom, post-processing, and a swapchain blit. Override it to add custom passes or replace the pipeline.

#![allow(unused)]
fn main() {
fn configure_render_graph(
    &mut self,
    graph: &mut RenderGraph<World>,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    resources: RenderResources,
) {
    let bloom_pass = passes::BloomPass::new(device, 1920, 1080);
    graph.add_pass(
        Box::new(bloom_pass),
        &[("input", resources.scene_color), ("output", resources.bloom)],
    );
}
}

update_render_graph

Called every frame. Use it to toggle passes or update graph state in response to runtime changes.

#![allow(unused)]
fn main() {
fn update_render_graph(&mut self, graph: &mut RenderGraph<World>, world: &World) {
    if self.bloom_changed {
        graph.set_enabled("bloom_pass", self.bloom_enabled);
        self.bloom_changed = false;
    }
}
}

pre_render

Called before render graph execution each frame. The hook into the renderer is for custom GPU uploads and direct renderer state changes that need to happen before the passes run.

#![allow(unused)]
fn main() {
fn pre_render(&mut self, renderer: &mut WgpuRenderer, world: &mut World) {
    renderer.update_custom_buffer(world, &self.custom_data);
}
}

State Transitions

Setting world.resources.window.next_state inside run_systems switches the game to a new state at the end of the frame. The field holds a builder closure that receives &mut World, so the next state can be constructed against the live engine resources.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    if self.transition_to_gameplay {
        world.resources.window.next_state =
            Some(Box::new(|world| Box::new(GameplayState::from_world(world))));
    }
}
}

Event Bus Messages

Custom EventBus messages live on world.resources.event_bus.messages. Drain that VecDeque in run_systems to process them. See the event system chapter for details.

Launching the Game

nightshade::launch runs the game. It takes a value of any type that implements State.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    nightshade::launch(MyGame::default())
}

A common pattern is to set up the initial scene inside initialize, including HDR skybox loads.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    load_hdr_skybox(world, include_bytes!("../assets/sky.hdr").to_vec());
}
}

Main Loop

The frame is the unit of work in Nightshade. Every frame runs the same sequence of steps in the same order, and almost all engine behavior is one of those steps. Understanding the order matters because anything you write either fits between two steps or replaces one.

Frame Execution Order

Each frame runs the following steps, in order:

1. Process window/input events (winit)
2. Update input state from events
3. Calculate delta time
4. Call State::run_systems(), which runs game logic
5. Dispatch EventBus messages
6. Run FrameSchedule, dispatching engine systems in order:
   a. Initialize and update audio (if audio feature)
   b. Update camera aspect ratios
   c. Step physics simulation (if physics feature)
   d. Update tweens
   e. Update animation players
   f. Apply animations to transforms
   g. Propagate transform hierarchy
   h. Update instanced mesh caches
   i. Run retained UI systems (input sync, picking, layout, rendering)
   j. Reset mouse, keyboard, and touch input state
   k. Process deferred commands
   l. Cleanup unused resources
7. Execute render graph passes
8. Present to swapchain

run_systems runs before the frame schedule. That means game logic sees the freshly updated input state, but it sees physics, animation, and transforms from the previous frame. Reads from the active camera's global transform inside run_systems will see last frame's value, and writes to local transforms will be propagated by step 6g of this frame.

Customizing the Schedule

The frame schedule is a resource at world.resources.frame_schedule. It can be edited from State::initialize to insert custom systems between engine systems, remove systems that the game does not need, or reorder dispatch.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.frame_schedule.insert_after(
        system_names::RUN_PHYSICS,
        "my_gameplay_system",
        my_gameplay_system,
    );

    world.resources.frame_schedule.remove(system_names::UI_LAYOUT_COMPUTE);
}
}

The full list of engine system name constants is in system_names in the prelude.

Timing

All timing information lives on world.resources.window.timing:

#![allow(unused)]
fn main() {
pub struct WindowTiming {
    pub frames_per_second: f32,
    pub delta_time: f32,
    pub raw_delta_time: f32,
    pub time_speed: f32,
    pub last_frame_start_instant: Option<web_time::Instant>,
    pub current_frame_start_instant: Option<web_time::Instant>,
    pub initial_frame_start_instant: Option<web_time::Instant>,
    pub frame_counter: u32,
    pub uptime_milliseconds: u64,
}

fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;
    let elapsed = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;
    let frame = world.resources.window.timing.frame_counter;
}
}

delta_time is the scaled, time-speed-aware seconds since the previous frame. raw_delta_time is the same value before time_speed is applied. The two are different only when something has changed time_speed away from 1.0.

Fixed Timestep Physics

Variable frame rates produce jittery physics. The fix is to step physics at a fixed timestep regardless of the render frame rate, accumulating leftover time and stepping again on later frames if more than one step has elapsed.

#![allow(unused)]
fn main() {
const PHYSICS_TIMESTEP: f32 = 1.0 / 60.0;

fn update_physics(world: &mut World, dt: f32) {
    world.resources.physics_accumulator += dt;

    while world.resources.physics_accumulator >= PHYSICS_TIMESTEP {
        store_physics_state(world);
        world.resources.physics.step(PHYSICS_TIMESTEP);
        world.resources.physics_accumulator -= PHYSICS_TIMESTEP;
    }

    let alpha = world.resources.physics_accumulator / PHYSICS_TIMESTEP;
    interpolate_physics_transforms(world, alpha);
}
}

The render is then drawn at the interpolated point between the previous and current physics states. The cost is one frame of input lag on collisions. The benefit is that a 240 Hz render and a 60 Hz render see the same physics behavior.

Physics Interpolation

Each physics body that needs smooth rendering carries a PhysicsInterpolation component holding the previous and current transforms, and the renderer lerps between them by alpha.

#![allow(unused)]
fn main() {
pub struct PhysicsInterpolation {
    pub previous_translation: Vec3,
    pub previous_rotation: Quat,
    pub current_translation: Vec3,
    pub current_rotation: Quat,
}

fn interpolate_physics_transforms(world: &mut World, alpha: f32) {
    for entity in world.core.query_entities(PHYSICS_INTERPOLATION) {
        let interp = world.core.get_physics_interpolation(entity).unwrap();
        let translation = interp.previous_translation.lerp(&interp.current_translation, alpha);
        let rotation = interp.previous_rotation.slerp(&interp.current_rotation, alpha);
    }
}
}

System Ordering Within run_systems

Within run_systems, the order in which the application calls its own systems is the order they run. Input handling and movement code go before any system that depends on their results.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    handle_input(world);

    player_movement_system(world);

    ai_decision_system(world);
}
}

Reading physics contacts happens in run_systems of the next frame, since the physics step ran in step 6c of the previous frame.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let contacts = get_all_contacts(world);
    for contact in contacts {
        handle_collision(world, contact);
    }
}
}

Delta Time

Movement, animation, and any value that changes over time must be scaled by delta_time. Otherwise the speed of the change is tied to the frame rate, and the game runs faster on a 240 Hz monitor than on a 60 Hz one.

#![allow(unused)]
fn main() {
fn move_entity(world: &mut World, entity: Entity, velocity: Vec3) {
    let dt = world.resources.window.timing.delta_time;

    if let Some(transform) = world.core.get_local_transform_mut(entity) {
        transform.translation += velocity * dt;
    }
}
}

For periodic events, accumulate delta time into a per-game f32 and fire when the accumulator crosses a threshold.

#![allow(unused)]
fn main() {
struct MyGame {
    spawn_timer: f32,
}

fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;

    self.spawn_timer += dt;
    if self.spawn_timer >= 2.0 {
        spawn_enemy(world);
        self.spawn_timer = 0.0;
    }
}
}

Entry Points

The desktop entry point is nightshade::launch called from fn main.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    nightshade::launch(MyGame::default())
}

The WASM entry point is the same call, awaited inside an async function exported with #[wasm_bindgen(start)].

#![allow(unused)]
fn main() {
#[wasm_bindgen(start)]
pub async fn start() {
    nightshade::launch(MyGame::default()).await;
}
}

Diagnosing Frame Issues

A frame spike shows up as a single large delta_time. Logging the spike inside run_systems gives a coarse signal that something blocked the main thread.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;
    if dt > 0.1 {
        tracing::warn!("Long frame: {:.3}s", dt);
    }
}
}

For consistent slowdowns, wrap individual systems in Instant::now to see which one is eating the budget. The 16 ms target for 60 Hz divides across every system in run_systems plus the engine schedule plus the render graph, so finding which slice owns the time is the first step before optimizing anything.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let start = std::time::Instant::now();

    expensive_system(world);

    let elapsed = start.elapsed();
    if elapsed.as_millis() > 5 {
        tracing::info!("expensive_system took {:?}", elapsed);
    }
}
}

World & Resources

The World is the single value that holds every piece of state in a Nightshade game. It contains the ECS storage (entities and components) and the resources (global singletons). Almost every function in the engine takes &mut World or &World as its first argument.

World Structure

The World is generated by the freecs::ecs! macro and reduces to two fields.

#![allow(unused)]
fn main() {
pub struct World {
    pub entities: EntityStorage,
    pub resources: Resources,
}
}

entities is the archetype-based component storage. resources is a flat struct of singleton values shared across every system.

Resources

Resources are the global state of the engine. Each field is a domain. Window state, input state, the physics world, the asset caches, the active camera, the deferred command queue, and so on.

#![allow(unused)]
fn main() {
pub struct Resources {
    pub world_id: u64,
    pub is_runtime: bool,
    pub window: Window,
    pub secondary_windows: SecondaryWindows,
    pub user_interface: UserInterface,
    pub graphics: Graphics,
    pub input: Input,
    #[cfg(feature = "audio")]
    pub audio: AudioEngine,
    #[cfg(feature = "physics")]
    pub physics: PhysicsWorld,
    pub navmesh: NavMeshWorld,
    pub text_cache: TextCache,
    pub mesh_cache: MeshCache,
    pub animation_cache: AnimationCache,
    pub prefab_cache: PrefabCache,
    pub material_registry: MaterialRegistry,
    pub texture_cache: TextureCache,
    pub pending_font_loads: Vec<PendingFontLoad>,
    pub active_camera: Option<Entity>,
    pub event_bus: EventBus,
    pub command_queue: Vec<WorldCommand>,
    pub transform_dirty_entities: Vec<Entity>,
    pub children_cache: HashMap<Entity, Vec<Entity>>,
    pub children_cache_valid: bool,
    pub cleanup_frame_counter: u64,
    pub dropped_files: Vec<DroppedFile>,
    pub skinning_offsets: HashMap<Entity, usize>,
    pub total_skinning_joints: u32,
    #[cfg(all(feature = "steam", not(target_arch = "wasm32")))]
    pub steam: SteamResources,
    #[cfg(feature = "physics")]
    pub picking_world: PickingWorld,
    pub gpu_picking: GpuPicking,
    pub mesh_render_state: MeshRenderState,
    #[cfg(feature = "scene_graph")]
    pub asset_registry: AssetRegistry,
    pub entity_names: HashMap<String, Entity>,
    pub entity_tags: HashMap<Entity, Vec<String>>,
    pub entity_blueprints: HashMap<Entity, Vec<EntityBlueprint>>,
    pub pending_particle_textures: Vec<ParticleTextureUpload>,
    pub ibl_views: IblViews,
    pub retained_ui: RetainedUiState,
    pub frame_schedule: FrameSchedule,
}
}

There is no separate Time resource. Timing values live on world.resources.window.timing alongside the rest of the window state.

Accessing Resources

Resources are reached through world.resources.<field>. The shape is consistent across the engine, and the borrow rules are the standard Rust ones. Two systems cannot mutably borrow the same resource at the same time.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let dt = world.resources.window.timing.delta_time;

    if world.resources.input.keyboard.is_key_pressed(KeyCode::Space) {
        self.jump();
    }

    world.resources.graphics.bloom_enabled = true;
    world.resources.graphics.bloom_intensity = 0.5;
}
}

Common Resources

Timing

world.resources.window.timing is a WindowTiming struct. The relevant fields for game logic are delta_time, frames_per_second, frame_counter, and uptime_milliseconds.

#![allow(unused)]
fn main() {
let dt = world.resources.window.timing.delta_time;
let fps = world.resources.window.timing.frames_per_second;
let elapsed = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;
}

#![allow(unused)]
fn main() {
pub struct WindowTiming {
    pub frames_per_second: f32,
    pub delta_time: f32,
    pub raw_delta_time: f32,
    pub time_speed: f32,
    pub last_frame_start_instant: Option<web_time::Instant>,
    pub current_frame_start_instant: Option<web_time::Instant>,
    pub initial_frame_start_instant: Option<web_time::Instant>,
    pub frame_counter: u32,
    pub uptime_milliseconds: u64,
}
}

Input

The input resource holds keyboard, mouse, gamepad, and touch state. Polling-style queries read flags. Event-style queries drain the events vec.

#![allow(unused)]
fn main() {
if world.resources.input.keyboard.is_key_pressed(KeyCode::KeyW) {
    move_forward();
}

let mouse_pos = world.resources.input.mouse.position;

if world.resources.input.mouse.state.contains(MouseState::LEFT_JUST_PRESSED) {
    shoot();
}
}

Graphics

world.resources.graphics controls the global rendering toggles. Atmosphere, bloom, SSAO, tonemapping, debug grid.

#![allow(unused)]
fn main() {
world.resources.graphics.show_grid = true;
world.resources.graphics.atmosphere = Atmosphere::Sky;
world.resources.graphics.bloom_enabled = true;
world.resources.graphics.ssao_enabled = true;

world.resources.graphics.color_grading.tonemap_algorithm = TonemapAlgorithm::Aces;
}

Active Camera

world.resources.active_camera: Option<Entity> is the camera that drives the main viewport. Setting it changes what the renderer draws. Reading from it after rendering tells you which entity was used.

#![allow(unused)]
fn main() {
world.resources.active_camera = Some(camera_entity);

if let Some(camera) = world.resources.active_camera {
    let transform = world.core.get_global_transform(camera);
}
}

World Commands

Some operations cannot run synchronously from inside a system. GPU resource creation, texture uploads, recursive despawns, and screenshot capture all need to be deferred to a safe point in the frame. These go through world.queue_command, which pushes a WorldCommand onto world.resources.command_queue.

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::LoadTexture {
    name: "my_texture".to_string(),
    rgba_data: texture_bytes,
    width: 256,
    height: 256,
});

world.queue_command(WorldCommand::DespawnRecursive { entity });
world.queue_command(WorldCommand::LoadHdrSkybox { hdr_data });
world.queue_command(WorldCommand::CaptureScreenshot { path: None });
}

The queue is drained during the render phase. Commands run in submission order.

For a recursive despawn that has to happen immediately rather than at the end of the frame, call the helper directly:

#![allow(unused)]
fn main() {
despawn_recursive_immediate(world, entity);
}

The cost of despawn_recursive_immediate is that the change is visible to every system that runs after it in the current frame, including the engine schedule. Use it when the deferred version would let invalid data leak through to physics or rendering.

Scene Hierarchy

A scene hierarchy is a parent-child tree of entities where each child's transform is interpreted relative to its parent. Moving the parent moves every descendant with it. This is how a robot arm holds together as one piece, how a sword stays in a character's hand during an animation, and how an entire scene can be translated by editing a single root entity.

Parent-Child Relationships

Setting a Parent

Setting the parent attaches a child to its parent and marks the local transform dirty so the next propagation pass picks up the change.

#![allow(unused)]
fn main() {
world.core.set_parent(child_entity, Parent(Some(parent_entity)));
world.core.set_local_transform_dirty(child_entity, LocalTransformDirty);
}

After the attach, the child's LocalTransform.translation, rotation, and scale are measured relative to the parent. A child at translation (0, 1, 0) with a parent at translation (5, 0, 0) renders at world-space (5, 1, 0).

Getting Children

The children_cache resource maps each parent entity to a Vec<Entity> of its direct children. The cache is rebuilt lazily when stale, so the lookup is a constant-time HashMap query.

#![allow(unused)]
fn main() {
if let Some(children) = world.resources.children_cache.get(&parent_entity) {
    for child in children {
    }
}
}

Detaching

Setting the parent to None detaches the child. Its local transform is then measured in world space.

#![allow(unused)]
fn main() {
world.core.set_parent(child_entity, Parent(None));
}

Transform Propagation

The engine runs propagate_transforms once per frame as part of the frame schedule. The pass walks every dirty entity, recomputes its global transform, and clears the dirty flag. Doing this manually is unnecessary, the schedule handles it.

#![allow(unused)]
fn main() {
propagate_transforms(world);
}

The propagation pass does five things in order. First, it gathers every entity marked LocalTransformDirty. Second, it walks descendants of each dirty entity and marks them dirty too, because a parent change invalidates the children's world positions. Third, it sorts the dirty set so parents are processed before children. Fourth, it computes each entity's global transform as either parent.GlobalTransform * LocalTransform if the entity has a parent, or LocalTransform.to_matrix() if it does not. Fifth, it clears the dirty flag.

Local vs Global Transform

#![allow(unused)]
fn main() {
pub struct LocalTransform {
    pub translation: Vec3,
    pub rotation: Quat,
    pub scale: Vec3,
}

pub struct GlobalTransform(pub Mat4);
}

LocalTransform is the editable form. Position, rotation, scale, all relative to the parent or to the world if there is no parent. Writing to a LocalTransform requires marking the entity dirty so the next propagation pass picks it up.

GlobalTransform is the read-only output. A single 4x4 matrix that bakes in the entire chain of parents. The renderer reads from GlobalTransform. Physics reads from GlobalTransform. Game logic that needs world-space coordinates reads from GlobalTransform.

Scene Serialization

Scenes can be saved to disk and reloaded. This is the format used by the level editor and the runtime loader.

Scene Structure

#![allow(unused)]
fn main() {
pub struct Scene {
    pub name: String,
    pub entities: Vec<SerializedEntity>,
    pub hierarchy: Vec<HierarchyNode>,
    pub assets: SceneAssets,
}

pub struct SerializedEntity {
    pub id: u64,
    pub name: Option<String>,
    pub components: SerializedComponents,
}

pub struct SceneAssets {
    pub textures: Vec<TextureReference>,
    pub materials: Vec<MaterialReference>,
    pub meshes: Vec<MeshReference>,
}
}

Saving

world_to_scene walks the world and serializes every entity and the hierarchy that connects them. The result is a Scene value that can be written to disk.

#![allow(unused)]
fn main() {
let scene = world_to_scene(world);
save_scene(&scene, "level1.scene")?;
}

Loading

#![allow(unused)]
fn main() {
let scene = load_scene("level1.scene")?;
spawn_scene(world, &scene);
}

spawn_scene allocates fresh entity ids and rebuilds the hierarchy. The ids in the saved file are not preserved across loads, since they have to coexist with whatever entities the live world already contains.

Binary Format

For larger scenes, the binary form is faster to load and smaller on disk.

#![allow(unused)]
fn main() {
let bytes = serialize_scene_binary(&scene)?;
let scene = deserialize_scene_binary(&bytes)?;
}

Recursive Operations

Despawning with Children

A parent and all its descendants can be despawned in a single call. Use the deferred command queue when calling from inside a system, or the immediate helper when the entity must be gone before the next system runs.

#![allow(unused)]
fn main() {
despawn_recursive_immediate(world, parent_entity);
}

Cloning Hierarchy

clone_entity_recursive produces a deep copy of an entity and every descendant. The clones get fresh ids and a fresh hierarchy that mirrors the original.

#![allow(unused)]
fn main() {
let clone = clone_entity_recursive(world, original_entity);
}

Example: A Robot Arm

The robot arm illustrates the hierarchy pattern. Four entities chained by parent pointers. Rotating the lower arm rotates everything above it.

#![allow(unused)]
fn main() {
fn spawn_robot_arm(world: &mut World) -> Entity {
    let base = spawn_cube_at(world, Vec3::zeros());
    world.core.set_name(base, Name("Base".to_string()));

    let lower_arm = spawn_cube_at(world, Vec3::new(0.0, 1.5, 0.0));
    world.core.set_name(lower_arm, Name("Lower Arm".to_string()));
    world.core.set_parent(lower_arm, Parent(Some(base)));

    let upper_arm = spawn_cube_at(world, Vec3::new(0.0, 2.0, 0.0));
    world.core.set_name(upper_arm, Name("Upper Arm".to_string()));
    world.core.set_parent(upper_arm, Parent(Some(lower_arm)));

    let hand = spawn_cube_at(world, Vec3::new(0.0, 1.5, 0.0));
    world.core.set_name(hand, Name("Hand".to_string()));
    world.core.set_parent(hand, Parent(Some(upper_arm)));

    base
}

fn rotate_arm(world: &mut World, lower_arm: Entity, angle: f32) {
    if let Some(transform) = world.core.get_local_transform_mut(lower_arm) {
        transform.rotation = nalgebra_glm::quat_angle_axis(
            angle,
            &Vec3::z(),
        );
    }
    world.core.set_local_transform_dirty(lower_arm, LocalTransformDirty);
}
}

The lower arm's translation (0, 1.5, 0) is relative to the base. The upper arm's translation (0, 2.0, 0) is relative to the lower arm. The hand's translation (0, 1.5, 0) is relative to the upper arm. Rotating the lower arm by setting its local rotation propagates through the chain on the next frame, and the upper arm and hand swing with it.

Input System

Input state is aggregated each frame into world.resources.input. Keyboard, mouse, gamepad, and touch all funnel into the same resource. There are two ways to read it. Polling, where a system checks "is this key currently held," and event-driven, where the system drains an event queue of state transitions.

Polling Input

Polling reads the current state. It tells you what is true right now, without history. Polling is the right choice for continuous controls like WASD movement, mouse look, or holding a fire button.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    if world.resources.input.keyboard.is_key_pressed(KeyCode::KeyW) {
        move_forward(world);
    }

    let mouse_pos = world.resources.input.mouse.position;

    if world.resources.input.mouse.state.contains(MouseState::LEFT_JUST_PRESSED) {
        shoot(world);
    }
}
}

The JUST_PRESSED and JUST_RELEASED flags fire on the single frame that the transition happens. They are how polling-style code detects edges without keeping its own history.

Event-Driven Input

Events are state transitions. The engine pushes them onto world.resources.input.events as AppEvent values, and the application drains the queue inside run_systems. Use events for discrete actions like toggling a menu, selecting a weapon slot, or any input where the transition matters more than the held state.

#![allow(unused)]
fn main() {
fn on_keyboard_input(&mut self, world: &mut World, key_code: KeyCode, key_state: ElementState) {
    if key_state == ElementState::Pressed {
        match key_code {
            KeyCode::Escape => self.paused = !self.paused,
            KeyCode::F11 => toggle_fullscreen(world),
            _ => {}
        }
    }
}

fn on_mouse_input(&mut self, world: &mut World, state: ElementState, button: MouseButton) {
    if state == ElementState::Pressed && button == MouseButton::Left {
        self.shoot(world);
    }
}
}

Built-in Systems

Three input-driven systems ship with the engine. None of them run automatically. Call them from run_systems when the game wants the behavior.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    fly_camera_system(world);

    escape_key_exit_system(world);

    pan_orbit_camera_system(world);
}
}

fly_camera_system reads WASD plus mouse look and writes to the active camera's transform. escape_key_exit_system exits the application when Escape is pressed. pan_orbit_camera_system reads middle-mouse drag and scroll wheel to orbit and zoom the active camera. The fly camera and pan-orbit camera are mutually exclusive on the same entity, and fly_camera_system skips entities that also have the PAN_ORBIT_CAMERA marker.

Chapters

• Keyboard & Mouse. Key detection, mouse tracking, cursor control.
• Gamepad Support. Controller input, analog sticks, button mapping.

Keyboard & Mouse

Keyboard and mouse state live on world.resources.input.keyboard and world.resources.input.mouse. Both can be polled directly inside run_systems or consumed as events through the AppEvent queue.

Keyboard

Polling

is_key_pressed returns whether a key is currently held. It is the right call for continuous actions like movement or sprint.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let keyboard = &world.resources.input.keyboard;

    if keyboard.is_key_pressed(KeyCode::KeyW) {
        move_forward();
    }

    if keyboard.is_key_pressed(KeyCode::Space) {
        jump();
    }

    if keyboard.is_key_pressed(KeyCode::ShiftLeft) {
        sprint();
    }
}
}

Common Key Codes

Event Handling

For discrete actions where the press is more important than the held state, match on the keyboard AppEvent. The example below pauses on Escape, toggles fullscreen on F11, and selects a weapon slot on the digit keys.

#![allow(unused)]
fn main() {
fn on_keyboard_input(&mut self, world: &mut World, key: KeyCode, state: ElementState) {
    if state == ElementState::Pressed {
        match key {
            KeyCode::Escape => self.paused = !self.paused,
            KeyCode::F11 => toggle_fullscreen(world),
            KeyCode::Digit1 => self.select_weapon(0),
            KeyCode::Digit2 => self.select_weapon(1),
            _ => {}
        }
    }
}
}

Mouse

Position

position is the cursor location in screen coordinates. Origin is the top-left of the window.

#![allow(unused)]
fn main() {
let mouse = &world.resources.input.mouse;
let position = mouse.position;
}

Movement Delta

position_delta is the per-frame change in cursor position, the right value for mouse-look or anything that wants relative motion rather than absolute coordinates.

#![allow(unused)]
fn main() {
let delta = world.resources.input.mouse.position_delta;
camera_yaw += delta.x * sensitivity;
camera_pitch += delta.y * sensitivity;
}

Buttons

Mouse buttons expose three states each. CLICKED is held, JUST_PRESSED fires on the transition into pressed, JUST_RELEASED fires on the transition out. The JUST_* variants only see one frame of true.

#![allow(unused)]
fn main() {
let mouse = &world.resources.input.mouse;

if mouse.state.contains(MouseState::LEFT_CLICKED) {
    fire_weapon();
}

if mouse.state.contains(MouseState::LEFT_JUST_PRESSED) {
    start_drag();
}

if mouse.state.contains(MouseState::LEFT_JUST_RELEASED) {
    end_drag();
}

if mouse.state.contains(MouseState::RIGHT_CLICKED) {
    aim_down_sights();
}

if mouse.state.contains(MouseState::MIDDLE_CLICKED) {
    pan_camera();
}
}

Scroll Wheel

wheel_delta is the scroll delta since the previous frame. y is vertical scroll, x is horizontal scroll on mice that support it.

#![allow(unused)]
fn main() {
let scroll = world.resources.input.mouse.wheel_delta;
if scroll.y != 0.0 {
    zoom_camera(scroll.y);
}
}

Event Handling

Match on the mouse AppEvent when the press and release transitions both matter, such as aim-down-sights that holds while the button is down.

#![allow(unused)]
fn main() {
fn on_mouse_input(&mut self, world: &mut World, state: ElementState, button: MouseButton) {
    match (button, state) {
        (MouseButton::Left, ElementState::Pressed) => self.shoot(),
        (MouseButton::Right, ElementState::Pressed) => self.aim(),
        (MouseButton::Right, ElementState::Released) => self.stop_aim(),
        _ => {}
    }
}
}

WASD Movement

The standard WASD pattern. Each direction key sets a component of a movement vector, then the vector is normalized so diagonals are not 1.41x faster than cardinals.

#![allow(unused)]
fn main() {
fn get_movement_input(world: &World) -> Vec3 {
    let keyboard = &world.resources.input.keyboard;
    let mut direction = Vec3::zeros();

    if keyboard.is_key_pressed(KeyCode::KeyW) {
        direction.z -= 1.0;
    }
    if keyboard.is_key_pressed(KeyCode::KeyS) {
        direction.z += 1.0;
    }
    if keyboard.is_key_pressed(KeyCode::KeyA) {
        direction.x -= 1.0;
    }
    if keyboard.is_key_pressed(KeyCode::KeyD) {
        direction.x += 1.0;
    }

    if direction.magnitude() > 0.0 {
        direction.normalize_mut();
    }

    direction
}
}

Mouse Look

First-person camera control. Mouse delta drives yaw on the world Y axis and pitch on the local X axis. Composing them as yaw * rotation * pitch keeps yaw global and pitch relative to the camera's current orientation, which is the convention that produces the expected behavior. A real implementation also clamps pitch so the camera does not flip over.

#![allow(unused)]
fn main() {
fn mouse_look_system(world: &mut World, sensitivity: f32) {
    let delta = world.resources.input.mouse.position_delta;

    if let Some(camera) = world.resources.active_camera {
        if let Some(transform) = world.core.get_local_transform_mut(camera) {
            let yaw = nalgebra_glm::quat_angle_axis(
                -delta.x * sensitivity,
                &Vec3::y(),
            );

            let pitch = nalgebra_glm::quat_angle_axis(
                -delta.y * sensitivity,
                &Vec3::x(),
            );

            transform.rotation = yaw * transform.rotation * pitch;
        }
    }
}
}

Cursor Visibility

For first-person games, lock the cursor to the window and hide it so the system pointer does not interfere with mouse-look.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.set_cursor_locked(true);
    world.set_cursor_visible(false);
}
}

Rebindable Controls

A KeyBindings struct decouples action names from physical keys. The struct holds one KeyCode per action and the input system reads from those fields rather than from hard-coded constants. The user can then write to the struct to remap.

#![allow(unused)]
fn main() {
struct KeyBindings {
    move_forward: KeyCode,
    move_back: KeyCode,
    move_left: KeyCode,
    move_right: KeyCode,
    jump: KeyCode,
    sprint: KeyCode,
}

impl Default for KeyBindings {
    fn default() -> Self {
        Self {
            move_forward: KeyCode::KeyW,
            move_back: KeyCode::KeyS,
            move_left: KeyCode::KeyA,
            move_right: KeyCode::KeyD,
            jump: KeyCode::Space,
            sprint: KeyCode::ShiftLeft,
        }
    }
}
}

Input Buffering

An input buffer accepts an input slightly before the action becomes available and replays it when the action becomes valid. The most common use is jump. A player who presses jump a few frames before landing still gets the jump, which feels more responsive than rejecting the press outright. The buffer is a countdown timer that decays each frame and is refreshed on press.

#![allow(unused)]
fn main() {
struct InputBuffer {
    jump_buffer: f32,
}

fn update_input_buffer(buffer: &mut InputBuffer, world: &World, dt: f32) {
    buffer.jump_buffer = (buffer.jump_buffer - dt).max(0.0);

    if world.resources.input.keyboard.is_key_pressed(KeyCode::Space) {
        buffer.jump_buffer = 0.15;
    }
}

fn try_jump(buffer: &mut InputBuffer, grounded: bool) -> bool {
    if grounded && buffer.jump_buffer > 0.0 {
        buffer.jump_buffer = 0.0;
        return true;
    }
    false
}
}

Gamepad Support

Gamepad input is provided by the gilrs crate. gilrs handles the platform differences across Windows, macOS, Linux, and the web, and Nightshade wraps the live state on world.resources.input.gamepad.

Enabling Gamepad

Gamepad is gated behind the gamepad cargo feature. Add it to the engine dependency.

[dependencies]
nightshade = { git = "...", features = ["engine", "gamepad"] }

Gamepad Resource

The resource wraps the gilrs library and tracks which gamepad is currently active.

#![allow(unused)]
fn main() {
pub struct Gamepad {
    pub gilrs: Option<gilrs::Gilrs>,
    pub gamepad: Option<gilrs::GamepadId>,
    pub events: Vec<gilrs::Event>,
}
}

The engine initializes gilrs at startup and updates the active gamepad as controllers are connected or disconnected.

Polling the Active Gamepad

query_active_gamepad returns a gilrs::Gamepad handle for the currently active controller. The handle exposes value for axes and triggers and is_pressed for buttons.

#![allow(unused)]
fn main() {
use nightshade::ecs::input::queries::query_active_gamepad;

fn run_systems(&mut self, world: &mut World) {
    if let Some(gamepad) = query_active_gamepad(world) {
        let left_x = gamepad.value(gilrs::Axis::LeftStickX);
        let left_y = gamepad.value(gilrs::Axis::LeftStickY);

        if gamepad.is_pressed(gilrs::Button::South) {
            self.jump();
        }
    }
}
}

Buttons

#![allow(unused)]
fn main() {
use nightshade::ecs::input::queries::query_active_gamepad;

fn run_systems(&mut self, world: &mut World) {
    if let Some(gamepad) = query_active_gamepad(world) {
        if gamepad.is_pressed(gilrs::Button::South) {
            jump();
        }

        if gamepad.is_pressed(gilrs::Button::West) {
            attack();
        }
    }
}
}

Button Mapping

gilrs uses position names (South, East, West, North) so the same code works across controller layouts. The face buttons map to different labels on each platform's controller, summarized below.

Analog Sticks

Axis values are f32 in the range [-1.0, 1.0]. Center is zero. LeftStickX is positive right, LeftStickY is positive up.

#![allow(unused)]
fn main() {
if let Some(gamepad) = query_active_gamepad(world) {
    let move_x = gamepad.value(gilrs::Axis::LeftStickX);
    let move_y = gamepad.value(gilrs::Axis::LeftStickY);

    let look_x = gamepad.value(gilrs::Axis::RightStickX);
    let look_y = gamepad.value(gilrs::Axis::RightStickY);
}
}

A deadzone of 0.15 to 0.20 is standard. Below that, treat the stick as centered. Cheap controllers drift, and reading raw values means the camera slowly rotates while the player is not touching the stick.

Triggers

Triggers are axes, not buttons. They report [0.0, 1.0] for how far pulled. LeftZ and RightZ are the analog values. The LeftTrigger and RightTrigger buttons in the table above are the digital shoulder buttons on most controllers, not the analog triggers.

#![allow(unused)]
fn main() {
if let Some(gamepad) = query_active_gamepad(world) {
    let left = gamepad.value(gilrs::Axis::LeftZ);
    let right = gamepad.value(gilrs::Axis::RightZ);

    let acceleration = right * max_acceleration;
}
}

Event Handling

Gamepad events arrive as gilrs::Event values in the AppEvent queue. Match on the event type for transition-based logic.

#![allow(unused)]
fn main() {
fn on_gamepad_event(&mut self, world: &mut World, event: gilrs::Event) {
    if let gilrs::EventType::ButtonPressed(button, _) = event.event {
        match button {
            gilrs::Button::Start => self.paused = !self.paused,
            gilrs::Button::South => self.player_jump(),
            _ => {}
        }
    }
}
}

Combining Keyboard and Gamepad

Player input often comes from whichever device is being held. The pattern is to read both, prefer the gamepad when its sticks are out of the deadzone, and fall back to the keyboard otherwise. Action buttons OR across devices so either input fires the action.

#![allow(unused)]
fn main() {
use nightshade::ecs::input::queries::query_active_gamepad;

struct PlayerInput {
    movement: Vec2,
    jump: bool,
    attack: bool,
}

fn gather_input(world: &mut World) -> PlayerInput {
    let mut input = PlayerInput {
        movement: Vec2::zeros(),
        jump: false,
        attack: false,
    };

    let keyboard = &world.resources.input.keyboard;
    if keyboard.is_key_pressed(KeyCode::KeyW) { input.movement.y -= 1.0; }
    if keyboard.is_key_pressed(KeyCode::KeyS) { input.movement.y += 1.0; }
    if keyboard.is_key_pressed(KeyCode::KeyA) { input.movement.x -= 1.0; }
    if keyboard.is_key_pressed(KeyCode::KeyD) { input.movement.x += 1.0; }
    input.jump |= keyboard.is_key_pressed(KeyCode::Space);

    if let Some(gamepad) = query_active_gamepad(world) {
        let stick_x = gamepad.value(gilrs::Axis::LeftStickX);
        let stick_y = gamepad.value(gilrs::Axis::LeftStickY);

        if stick_x.abs() > 0.15 || stick_y.abs() > 0.15 {
            input.movement = Vec2::new(stick_x, stick_y);
        }

        input.jump |= gamepad.is_pressed(gilrs::Button::South);
        input.attack |= gamepad.is_pressed(gilrs::Button::West);
    }

    input
}
}

Event System

The event bus is a FIFO queue of messages shared across systems. One system publishes, another consumes, and neither has to know about the other. Events are the alternative to direct function calls when the producer and consumer should not be coupled, when one event should trigger several handlers, or when the action needs to be deferred to a later point in the frame.

EventBus

The bus lives on world.resources.event_bus. It is a VecDeque<Message> plus the Message enum, which has two variants. Input is reserved for engine-generated input messages. App is a type-erased payload for application events.

#![allow(unused)]
fn main() {
pub struct EventBus {
    pub messages: VecDeque<Message>,
}

pub enum Message {
    Input(InputMessage),
    App(Box<dyn Any + Send + Sync>),
}
}

Defining Events

An event is any struct that implements Send + Sync. There is no trait to derive and no registration step. The struct holds the data the consumer will need.

#![allow(unused)]
fn main() {
pub struct EnemyDied {
    pub entity: Entity,
    pub position: Vec3,
    pub killer: Option<Entity>,
}

pub struct PlayerLeveledUp {
    pub new_level: u32,
    pub skills_unlocked: Vec<String>,
}

pub struct ItemPickedUp {
    pub item_type: ItemType,
    pub quantity: u32,
}
}

Publishing

publish_app_event boxes the event and pushes it onto the queue. The example below detects death in a combat system, publishes EnemyDied with the relevant context, then despawns the entity.

#![allow(unused)]
fn main() {
fn combat_system(world: &mut World, game: &mut GameState) {
    for enemy in world.core.query_entities(ENEMY | HEALTH) {
        let health = world.core.get_health(enemy).unwrap();
        if health.current <= 0 {
            let position = world.core.get_global_transform(enemy)
                .map(|t| t.matrix.column(3).xyz())
                .unwrap_or(Vec3::zeros());

            publish_app_event(world, EnemyDied {
                entity: enemy,
                position,
                killer: game.last_attacker,
            });

            world.despawn_entities(&[enemy]);
        }
    }
}
}

Consuming

Consumers pop messages off the queue and match on the variant. For Message::App, downcast against each event type that the consumer cares about. The order is FIFO. The first event published is the first one popped.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    while let Some(msg) = world.resources.event_bus.messages.pop_front() {
        match msg {
            Message::App(event) => {
                if let Some(died) = event.downcast_ref::<EnemyDied>() {
                    self.handle_enemy_death(world, died);
                }
                if let Some(levelup) = event.downcast_ref::<PlayerLeveledUp>() {
                    self.show_levelup_ui(levelup);
                }
                if let Some(pickup) = event.downcast_ref::<ItemPickedUp>() {
                    self.update_inventory(pickup);
                }
            }
            Message::Input(input_msg) => {
                self.handle_input_message(input_msg);
            }
        }
    }
}

fn handle_enemy_death(&mut self, world: &mut World, event: &EnemyDied) {
    spawn_explosion_effect(world, event.position);
    self.score += 100;
    self.enemies_killed += 1;
}
}

Patterns

One Publisher, Many Consumers

A single published event can be matched against by any number of consumers, each on its own pass through the queue. The publisher does not know how many listeners exist.

#![allow(unused)]
fn main() {
publish_app_event(world, DoorOpened { door_id: 42 });
}

#![allow(unused)]
fn main() {
if let Some(door) = event.downcast_ref::<DoorOpened>() {
    trigger_cutscene(world, door.door_id);
}

if let Some(door) = event.downcast_ref::<DoorOpened>() {
    play_door_sound(world, door.door_id);
}

if let Some(door) = event.downcast_ref::<DoorOpened>() {
    update_minimap(world, door.door_id);
}
}

The downside is that the queue is drained once per frame, so consumers that share a drain loop see each event exactly once. For one-to-many fan-out, the consumers need to live inside the same drain or the event has to be republished.

Deferred Actions

Events delay work to a later frame. The struct stores its own countdown, and the system retains pending events until the countdown reaches zero, at which point it spawns the actual thing.

#![allow(unused)]
fn main() {
pub struct SpawnEnemy {
    pub enemy_type: EnemyType,
    pub position: Vec3,
    pub delay_frames: u32,
}

fn wave_spawner_system(world: &mut World, pending: &mut Vec<SpawnEnemy>) {
    pending.retain_mut(|spawn| {
        if spawn.delay_frames == 0 {
            spawn_enemy(world, spawn.enemy_type, spawn.position);
            false
        } else {
            spawn.delay_frames -= 1;
            true
        }
    });
}
}

Request-Response

The event bus is fire-and-forget. For request-response, where the caller needs the result of the work, use a pair of structs and pass them through a shared buffer rather than the event bus.

#![allow(unused)]
fn main() {
pub struct DamageRequest {
    pub target: Entity,
    pub amount: f32,
    pub damage_type: DamageType,
}

pub struct DamageResult {
    pub target: Entity,
    pub actual_damage: f32,
    pub killed: bool,
}

fn damage_system(world: &mut World, requests: &[DamageRequest]) -> Vec<DamageResult> {
    requests.iter().map(|req| {
        let actual = apply_damage(world, req.target, req.amount, req.damage_type);
        let killed = is_dead(world, req.target);
        DamageResult {
            target: req.target,
            actual_damage: actual,
            killed,
        }
    }).collect()
}
}

Input Messages

The bus also carries engine-generated input messages. These are the same input transitions exposed through the polling API, available as events for code that prefers the event style.

#![allow(unused)]
fn main() {
pub enum InputMessage {
    KeyPressed(KeyCode),
    KeyReleased(KeyCode),
    MouseMoved { x: f32, y: f32 },
    MouseButton { button: MouseButton, pressed: bool },
    GamepadButton { button: GamepadButton, pressed: bool },
}
}

Constraints

Keep events small. The payload is boxed and downcast, so a large struct costs more to publish and more to read. Process events every frame, since the queue grows unbounded if drained slowly. Watch for cycles. An event A whose handler publishes event B whose handler publishes event A is an infinite loop that fills memory and stalls the frame.

Rendering Architecture

This chapter is about how ECS state becomes pixels. The renderer is built on wgpu and the GPU work is orchestrated by a dependency-driven render graph. Game code writes to components, the renderer reads those components every frame, packs the data into GPU buffers, and submits a graph of passes that ends with a swapchain present.

High-Level Flow

ECS World State
    |
    v
Renderer (WgpuRenderer)
    |-- Sync data: upload transforms, materials, lights to GPU buffers
    |-- Prepare passes: each pass updates its bind groups and uniforms
    |-- Execute render graph: run passes in dependency order
    |-- Submit command buffers to GPU queue
    |-- Present swapchain surface
    |
    v
Pixels on Screen

The Render Trait

The Render trait is the abstraction over the GPU backend. Game code never touches wgpu directly. It calls trait methods on whatever renderer the platform layer constructed.

#![allow(unused)]
fn main() {
pub trait Render {
    fn render_frame(&mut self, world: &mut World, state: &mut dyn State);
    fn resize(&mut self, width: u32, height: u32, world: &mut World);
    // ... additional methods for texture upload, screenshot, etc.
}
}

WgpuRenderer is the concrete implementation. It owns the wgpu device, queue, surface, and the render graph.

WgpuRenderer

WgpuRenderer is the bag of GPU state the engine carries across frames. The fields are:

• Instance, Adapter, Device, Queue are the wgpu initialization chain.
• Surface is the window's swapchain.
• RenderGraph is the dependency-driven frame graph with every pass.
• Resource IDs are handles to transient and external textures.
• Texture Cache is the set of uploaded GPU textures keyed by handle.
• Font Atlas is the glyph texture for text rendering.
• Camera Viewports are render-to-texture targets for editor viewports.

None of this is exposed to game code. Game code mutates the ECS, the renderer reads it.

Initialization

The startup chain is the standard wgpu bring-up plus some graph construction at the end.

1. The instance is created with wgpu::Instance. The backend is Vulkan on Linux and Windows, Metal on macOS, DX12 on Windows, WebGPU on WASM. The instance is the entry point to the GPU API.
2. The instance enumerates available GPUs and picks one. The chosen adapter exposes the GPU's supported texture formats, limits, and features.
3. The adapter opens a logical device and a command queue. The device creates GPU resources. The queue is where command buffers go to execute. All GPU work flows through the queue.
4. The window surface is configured with the GPU's preferred format (usually Bgra8UnormSrgb) and a present mode (Fifo for vsync, Mailbox for low latency).
5. Every built-in pass is constructed. Each pass owns its shader modules, pipeline layouts, render pipelines, bind group layouts, and any persistent GPU buffers. None of this is rebuilt per frame.
6. A RenderGraph<World> is constructed with the transient textures and passes registered.
7. The game's State::configure_render_graph() runs. The game can add custom passes, declare custom textures, or replace the default post-process chain.
8. The graph compiles. Compilation builds dependency edges, topologically sorts the passes, computes resource lifetimes, decides which transients can alias, and works out per-attachment load and store operations.

Transient Textures

The renderer declares every intermediate texture at initialization time. The list is fixed, the sizes track the window, and the graph decides which ones can share memory.

External textures are provided fresh each frame. swapchain is the window surface texture. viewport_output is the editor viewport render target.

Per-Frame Rendering

render_frame() does seven things, in order.

1. Sync data. Transform matrices, material uniforms, light data, and animation bone matrices are uploaded to GPU buffers.
2. Process commands. Queued WorldCommand values run (texture loads, screenshots, anything else queued during the frame).
3. Set the swapchain texture. The next swapchain image is acquired and bound as the external swapchain resource.
4. Call State::update_render_graph() so the game can flip per-frame graph state (enabling or disabling passes, updating parameters).
5. Execute the graph. Every enabled, non-culled pass runs in topological order. Each pass writes one command buffer.
6. Submit. The command buffers go to the GPU queue.
7. Present. The frame appears on the window.

Resize Handling

When the window resizes, the surface is reconfigured with the new dimensions, every transient texture is resized to match, the graph recomputes aliasing, and any pass that cached bind groups invalidates them. SSGI textures resize to half the new dimensions because they run at half resolution.

Custom Rendering

Two State methods let the game change the pipeline. configure_render_graph() runs once at startup. The game adds custom passes, declares custom textures, and changes the pipeline shape. update_render_graph() runs each frame. The game enables or disables passes and updates per-pass parameters.

For the details on the graph itself, see The Render Graph. For end-to-end custom-pass examples, see Custom Passes.

The Render Graph

Live Demos: Custom Pass | Custom Multipass | Render Layers

The render graph is the system that schedules GPU work. Passes declare what they read and what they write, and the graph figures out the ordering, the memory layout, and the load and store operations. The motivation is that hand-ordering a real renderer does not scale.

The Problem: Manual Pass Ordering

A real renderer has dozens of passes. Shadow maps, geometry, SSAO, SSR, bloom, tonemapping, UI. Each one reads from and writes to intermediate textures. Doing this without automation means four kinds of pain.

The first is ordering. Shadow maps before geometry, geometry before SSAO, SSAO before compositing. Adding one pass means figuring out where it fits in the chain, and reordering one pass means re-checking three others.

The second is texture lifecycle. Allocate intermediate textures, track which ones are alive when, decide when to clear versus load and when to store versus discard. Getting this wrong shows up as black screens or stale data from a previous frame.

The third is memory. SSAO's intermediate texture and SSR's intermediate texture might never be alive at the same time. Without aliasing, both live in VRAM whether they need to or not.

The fourth is dynamic passes. Disabling bloom should not require rewriting the compositing pass's inputs. With hardcoded ordering, every conditional pass becomes an if statement threaded through the entire pipeline.

The render graph (also called a frame graph, after the Frostbite GDC 2017 talk "FrameGraph: Extensible Rendering Architecture in Frostbite") replaces all four with declared dependencies. Passes describe what they need. The graph handles ordering, memory, and lifecycle.

How It Works

The frame is modeled as a directed acyclic graph. Nodes are passes. Edges are resource dependencies. An edge from pass A to pass B means A produces data that B consumes.

This is the same abstraction as a build system (Make, Bazel) or a task scheduler. Given the edges, a topological sort produces a valid execution order. Once the order exists, the graph can analyze resource lifetimes, alias memory, compute load and store operations, and cull passes that do not contribute to any external output.

The key property is that dependencies are declarative, not imperative. A pass says "I read scene_color, I write bloom," not "run me after MeshPass and before PostProcessPass." Adding a new pass means declaring its slots, not editing every other pass that touches the same resources.

What This Buys

Five things fall out of the graph automatically.

Pass ordering is topologically sorted from read and write dependencies. Transient textures with non-overlapping lifetimes share GPU memory. The graph picks LoadOp::Clear, LoadOp::Load, StoreOp::Store, and StoreOp::Discard per attachment based on who reads what. Passes that do not contribute to any external output are culled. Passes can be enabled and disabled at runtime without recompiling the graph.

The RenderGraph Struct

#![allow(unused)]
fn main() {
pub struct RenderGraph<C = ()> {
    graph: DiGraph<GraphNode<C>, ResourceId>,  // petgraph directed graph
    pass_nodes: HashMap<String, NodeIndex>,     // pass name -> graph node
    resources: RenderGraphResources,            // texture/buffer descriptors and handles
    execution_order: Vec<NodeIndex>,            // topologically sorted pass order
    store_ops: HashMap<ResourceId, StoreOp>,    // per-resource store operations
    clear_ops: HashSet<(NodeIndex, ResourceId)>,// which passes clear which resources
    aliasing_info: Option<ResourceAliasingInfo>,// memory sharing between transients
    culled_passes: HashSet<NodeIndex>,          // passes removed by dead-pass culling
    // ...
}
}

The generic parameter C is the "configs" type passed to passes during execution. Nightshade uses RenderGraph<World> so passes can read ECS state directly.

Lifecycle

1. Setup Phase (once at startup)

#![allow(unused)]
fn main() {
let mut graph = RenderGraph::new();

// Declare textures
let depth = graph.add_depth_texture("depth")
    .size(1920, 1080)
    .clear_depth(0.0)
    .transient();

let scene_color = graph.add_color_texture("scene_color")
    .format(wgpu::TextureFormat::Rgba16Float)
    .size(1920, 1080)
    .clear_color(wgpu::Color::BLACK)
    .transient();

let swapchain = graph.add_color_texture("swapchain")
    .format(surface_format)
    .external();

// Add passes with slot bindings
graph.add_pass(
    Box::new(clear_pass),
    &[("color", scene_color), ("depth", depth)],
)?;

graph.add_pass(
    Box::new(mesh_pass),
    &[("color", scene_color), ("depth", depth)],
)?;

graph.add_pass(
    Box::new(blit_pass),
    &[("input", scene_color), ("output", swapchain)],
)?;

// Compile: build edges, sort, compute aliasing
graph.compile()?;
}

2. Per-Frame Execution

#![allow(unused)]
fn main() {
// Provide the swapchain texture for this frame
graph.set_external_texture(swapchain_id, swapchain_view, width, height);

// Execute all passes, get command buffers
let command_buffers = graph.execute(&device, &queue, &world)?;

// Submit to GPU
queue.submit(command_buffers);
}

Key Methods

Compilation Steps

compile() runs seven steps in sequence.

1. Build dependency edges. For each resource, an edge is created from the writer to every reader.
2. Topological sort. The passes are ordered so every pass executes after its dependencies.
3. Compute store ops. Each resource write is marked Store or Discard based on whether any later pass reads it.
4. Compute clear ops. The first pass that writes a resource with a clear value gets Clear. The rest get Load.
5. Compute resource lifetimes. Each transient gets a first_use and last_use pass index.
6. Compute resource aliasing. Transient resources with non-overlapping lifetimes are assigned to the same pool slot.
7. Dead pass culling. Passes that do not contribute to any external output are marked for skipping.

Sub-Chapters

• Resources & Textures covers resource types, builders, and the difference between external and transient.
• Passes & the PassNode Trait covers how to implement a custom pass.
• Dependency Resolution & Scheduling covers how the order is computed.
• Resource Aliasing & Memory covers how transients share memory.
• Custom Passes walks through end-to-end examples.

Resources & Textures

Render graph resources are the GPU textures and buffers that passes read from and write to. Every resource is referenced through a ResourceId handle. The graph hands you the handle when you declare the resource, and you pass that handle to add_pass() to wire it into slot bindings.

ResourceId

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ResourceId(pub u32);
}

ResourceId is an opaque integer handle. It survives across frames and across graph recompilations. The actual GPU texture or buffer the handle points to can change (aliasing, resize), but the handle does not.

Resource Types

There are six variants. The split is along two axes: color versus depth versus buffer, and external versus transient.

External vs Transient

External resources are owned by the caller. The graph never creates or destroys them. Every frame, the application provides them via set_external_texture(). The swapchain texture is the canonical example.

Transient resources are owned by the graph. The graph creates the underlying GPU texture or buffer, tracks its lifetime across the frame, and can alias it with other transients to reduce VRAM. A transient with first_use at pass 1 and last_use at pass 3 has no GPU object outside that window, so its memory can be reused by another transient whose lifetime falls outside the same range.

Creating Color Textures

The fluent builder is the entry point.

#![allow(unused)]
fn main() {
// Transient - graph manages lifetime and may alias memory
let hdr = graph.add_color_texture("scene_color")
    .format(wgpu::TextureFormat::Rgba16Float)
    .size(1920, 1080)
    .clear_color(wgpu::Color::BLACK)
    .transient();

// External - you provide the texture each frame
let swapchain = graph.add_color_texture("swapchain")
    .format(wgpu::TextureFormat::Bgra8UnormSrgb)
    .external();
}

Builder Methods

Creating Depth Textures

#![allow(unused)]
fn main() {
let depth = graph.add_depth_texture("depth")
    .size(1920, 1080)
    .format(wgpu::TextureFormat::Depth32Float)
    .clear_depth(0.0)
    .transient();
}

Depth Builder Methods

Creating Buffers

#![allow(unused)]
fn main() {
let data_buffer = graph.add_buffer("compute_data")
    .size(1024 * 1024)
    .usage(wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST)
    .transient();
}

Resource Templates

A template captures the shared shape of a set of textures. Useful when you need a bunch of textures with the same format, size, and usage and only the name differs.

#![allow(unused)]
fn main() {
let template = ResourceTemplate::new(
    wgpu::TextureFormat::Rgba16Float,
    1920,
    1080,
).usage(wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING);

let texture_a = graph.transient_color_from_template("blur_a", &template);
let texture_b = graph.transient_color_from_template("blur_b", &template);
}

Template Methods

Resource Pools

A pool batches the allocation of several transients from one template.

#![allow(unused)]
fn main() {
let mut pool = graph.resource_pool(&template);
let [blur_a, blur_b, blur_c] = [
    pool.transient("blur_a"),
    pool.transient("blur_b"),
    pool.transient("blur_c"),
];
}

Setting External Textures Per-Frame

External textures must be provided before execute() runs.

#![allow(unused)]
fn main() {
// Each frame, provide the swapchain texture
let surface_texture = surface.get_current_texture()?;
let view = surface_texture.texture.create_view(&Default::default());
graph.set_external_texture(swapchain_id, view, width, height);
}

Resizing Transient Textures

When the window resizes, every transient that tracks the window size needs to be told.

#![allow(unused)]
fn main() {
graph.resize_transient_resource(&device, depth_id, new_width, new_height)?;
graph.resize_transient_resource(&device, scene_color_id, new_width, new_height)?;
}

Resizing invalidates the aliasing info. Reallocation happens on the next execution.

Passes & the PassNode Trait

A pass is a PassNode. The trait declares the pass's resource dependencies, gives the graph a chance to upload per-pass uniforms during the prepare phase, and records GPU commands during execute.

The PassNode Trait

#![allow(unused)]
fn main() {
pub trait PassNode<C = ()>: Send + Sync + Any {
    fn name(&self) -> &str;
    fn reads(&self) -> Vec<&str>;
    fn writes(&self) -> Vec<&str>;
    fn reads_writes(&self) -> Vec<&str> { Vec::new() }
    fn optional_reads(&self) -> Vec<&str> { Vec::new() }
    fn prepare(&mut self, _device: &Device, _queue: &wgpu::Queue, _configs: &C) {}
    fn invalidate_bind_groups(&mut self) {}
    fn execute<'r, 'e>(
        &mut self,
        context: PassExecutionContext<'r, 'e, C>,
    ) -> Result<Vec<SubGraphRunCommand<'r>>>;
}
}

On WASM the Send + Sync bounds are removed because the WebGPU types are not Send.

Slot-Based Resource Binding

Passes declare slot names. Slot names are strings that match the keys in the add_pass() bindings. The names are local to the pass.

#![allow(unused)]
fn main() {
impl PassNode<World> for MyPass {
    fn name(&self) -> &str { "my_pass" }

    // Slots this pass reads from (input textures)
    fn reads(&self) -> Vec<&str> { vec!["input"] }

    // Slots this pass writes to (output attachments)
    fn writes(&self) -> Vec<&str> { vec!["output"] }

    // Slots that are both read and written (read-modify-write)
    fn reads_writes(&self) -> Vec<&str> { vec![] }

    // Slots that are read if available, but don't create dependencies if absent
    fn optional_reads(&self) -> Vec<&str> { vec![] }
    // ...
}
}

The slot-to-resource binding happens at add_pass().

#![allow(unused)]
fn main() {
graph.add_pass(
    Box::new(my_pass),
    &[("input", scene_color_id), ("output", swapchain_id)],
)?;
}

The pass's shader code refers to bind groups, not to slot names. The slot names are only the graph's vocabulary. Inside the pass, you ask the execution context for the view bound to a slot.

PassExecutionContext

The context is what the pass uses to look up resources, get attachment descriptors, and record commands.

#![allow(unused)]
fn main() {
pub struct PassExecutionContext<'r, 'e, C = ()> {
    pub encoder: &'e mut CommandEncoder,
    pub resources: &'r RenderGraphResources,
    pub device: &'r Device,
    pub queue: &'r wgpu::Queue,
    pub configs: &'r C,  // For Nightshade, this is &World
    // ... internal fields
}
}

Context Methods

Automatic Load/Store Operations

The graph picks the right load and store op for each attachment based on who else touches the resource.

• LoadOp::Clear is used when this pass is the first writer and the resource has a clear value.
• LoadOp::Load is used when a previous pass already wrote to this resource.
• StoreOp::Store is used when any later pass reads this resource.
• StoreOp::Discard is used when no subsequent pass reads this resource.

You do not choose these. get_color_attachment() and get_depth_attachment() return the right ones.

Prepare Phase

prepare() runs before execution for every non-culled pass. The right work for prepare is anything that uploads uniforms or per-frame data.

#![allow(unused)]
fn main() {
fn prepare(&mut self, device: &Device, queue: &wgpu::Queue, configs: &World) {
    let camera_data = extract_camera_uniforms(configs);
    queue.write_buffer(&self.uniform_buffer, 0, bytemuck::bytes_of(&camera_data));
}
}

Bind Group Invalidation

When the graph reallocates a resource (resize, aliasing change), invalidate_bind_groups() is called on every pass that references that resource. The pass clears its cached bind groups so they get rebuilt against the new GPU texture.

#![allow(unused)]
fn main() {
fn invalidate_bind_groups(&mut self) {
    self.bind_group = None;
}
}

The graph tracks a version per resource. Only passes that actually reference a changed resource get invalidated.

Full Example

#![allow(unused)]
fn main() {
pub struct BlurPass {
    pipeline: wgpu::RenderPipeline,
    bind_group_layout: wgpu::BindGroupLayout,
    bind_group: Option<wgpu::BindGroup>,
    sampler: wgpu::Sampler,
}

impl PassNode<World> for BlurPass {
    fn name(&self) -> &str { "blur_pass" }
    fn reads(&self) -> Vec<&str> { vec!["input"] }
    fn writes(&self) -> Vec<&str> { vec!["output"] }

    fn invalidate_bind_groups(&mut self) {
        self.bind_group = None;
    }

    fn execute<'r, 'e>(
        &mut self,
        ctx: PassExecutionContext<'r, 'e, World>,
    ) -> Result<Vec<SubGraphRunCommand<'r>>> {
        if !ctx.is_pass_enabled() {
            return Ok(vec![]);
        }

        let input_view = ctx.get_texture_view("input")?;
        let (output_view, load_op, store_op) = ctx.get_color_attachment("output")?;

        if self.bind_group.is_none() {
            self.bind_group = Some(ctx.device.create_bind_group(&wgpu::BindGroupDescriptor {
                layout: &self.bind_group_layout,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: 0,
                        resource: wgpu::BindingResource::TextureView(input_view),
                    },
                    wgpu::BindGroupEntry {
                        binding: 1,
                        resource: wgpu::BindingResource::Sampler(&self.sampler),
                    },
                ],
                label: Some("blur_bind_group"),
            }));
        }

        let mut pass = ctx.encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("blur_pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: output_view,
                resolve_target: None,
                ops: wgpu::Operations { load: load_op, store: store_op },
            })],
            depth_stencil_attachment: None,
            ..Default::default()
        });

        pass.set_pipeline(&self.pipeline);
        pass.set_bind_group(0, self.bind_group.as_ref().unwrap(), &[]);
        pass.draw(0..3, 0..1);  // Fullscreen triangle

        Ok(vec![])
    }
}
}

The pattern is the same for every pass. Pull the views out of the context, build a bind group if the cached one was invalidated, begin a render pass with the load and store ops the graph computed, set the pipeline, draw.

Sub-Graph Execution

A pass can trigger a sub-graph for multi-pass effects like a bloom mip chain.

#![allow(unused)]
fn main() {
fn execute<'r, 'e>(
    &mut self,
    mut ctx: PassExecutionContext<'r, 'e, World>,
) -> Result<Vec<SubGraphRunCommand<'r>>> {
    ctx.run_sub_graph("bloom_mip_chain".to_string(), vec![
        SlotValue::TextureView {
            view: ctx.get_texture_view("hdr")?,
            width: self.width,
            height: self.height,
        },
    ]);

    Ok(ctx.into_sub_graph_commands())
}
}

The sub-graph is a separate RenderGraph registered against a name. The parent pass passes in slot values and the sub-graph executes with those as its external inputs.

Dependency Resolution & Scheduling

Pass ordering falls out of the resource dependencies. This chapter is about how that calculation works, where it can fail, and how runtime toggling fits in.

Dependency Edge Construction

compile() builds edges by walking the passes and the resources they touch.

1. Iterate every pass.
2. For each resource a pass reads, find the pass that last wrote it.
3. Add a directed edge from the writer to the reader.

Pass A writes texture T
Pass B reads texture T
  => Edge: A -> B (B depends on A)

For reads_writes resources the pass counts as both reader and writer, so it sits between the previous writer and the next reader. Optional reads create edges only when a writer exists. If no pass writes the slot, the optional reader simply does not get the edge and the pass is free to schedule wherever else its other dependencies allow.

Topological Sort

The graph performs a topological sort using petgraph. A topological sort of a DAG produces a linear ordering where every edge A -> B puts A before B. That ordering guarantees every pass runs after the passes that produce its inputs.

The cost is O(V + E) where V is the number of passes and E is the number of dependency edges. Kahn's algorithm (iteratively remove nodes with no incoming edges) and depth-first search both produce the same result. petgraph picks one implementation.

A cycle in the graph means compilation fails with RenderGraphError::CyclicDependency. Two passes that each depend on the other's output have no valid ordering. The fix is in the graph definition: one of the passes is over-declared and should not actually depend on the other's resource.

Dead Pass Culling

Not every pass contributes to the final image. The graph uses backward reachability from external resources to keep only the passes that matter.

1. Start with every external resource marked "required."
2. Walk the execution order backward.
3. A pass is required if it writes a required resource, or if it has no writes and no reads_writes (which the graph treats as a side-effecting pass).
4. If a pass is required, every resource it reads is also required.
5. Any pass not marked required is culled.

Pass A writes T1
Pass B reads T1, writes T2     <- T2 is not read by anyone
Pass C reads T1, writes output  <- output is external

Result: A and C execute, B is culled

The culling is what lets update_render_graph() toggle effects on and off without leaving dead passes in the pipeline. A disabled pass whose output nothing else reads is invisible to the rest of the graph.

Runtime Pass Toggling

A pass can be turned on or off without recompiling.

#![allow(unused)]
fn main() {
graph.set_pass_enabled("bloom_pass", false)?;
}

Disabling does not remove the pass from the graph. execute() is still called, but is_pass_enabled() returns false. The pass's execute() checks the flag and skips its GPU work.

#![allow(unused)]
fn main() {
fn execute<'r, 'e>(
    &mut self,
    ctx: PassExecutionContext<'r, 'e, World>,
) -> Result<Vec<SubGraphRunCommand<'r>>> {
    if !ctx.is_pass_enabled() {
        return Ok(vec![]);
    }
    // ... normal execution
}
}

The trade-off is that the pass's outputs still exist as dependencies in the graph. Disabling a pass that downstream passes depend on (and that does not have an optional_reads declaration covering it) leaves the downstream passes reading whatever was last in the attachment, which is usually the clear value.

Recompilation

The graph tracks a needs_recompile flag. Adding or removing a pass sets it. On the next execute(), the graph drops every existing edge, rebuilds the dependency edges, re-sorts topologically, and recomputes store ops, clear ops, lifetimes, and aliasing. The call site does not have to call compile() again.

Store and Clear Operations

Store Operations

On tile-based GPU architectures (mobile, Apple Silicon), render pass attachments live in fast on-chip tile memory during the pass. At the end of the pass, the driver decides whether to write that tile memory back out to main VRAM. The write-back is the store operation, and it costs real bandwidth.

The graph picks the store op per resource write.

• Store is used when any later pass reads the resource, or when the resource is external and has force_store set. The data has to survive.
• Discard is used when no later pass reads the resource. The GPU skips the write-back entirely. On tile-based architectures this is a significant win.

Clear Operations

The other end of the pass has a parallel decision. The GPU decides what to do with the existing attachment contents.

• Clear writes a known value (black, zero depth) into the attachment. This is cheap because tile memory can be initialized without reading from VRAM.
• Load reads the existing contents from VRAM into tile memory. This is required when a previous pass wrote data that this pass needs to preserve.

The first pass that writes a resource with a clear value (clear_color or clear_depth) gets LoadOp::Clear. Every subsequent writer gets LoadOp::Load.

The cost of getting these wrong is real. Picking Clear when Load was correct erases the previous pass's work. Picking Load when Clear was correct wastes bandwidth loading garbage data. The graph computes both automatically, and get_color_attachment() and get_depth_attachment() return the chosen ops.

Resource Aliasing & Memory

Transient resources with non-overlapping lifetimes share GPU memory. The render graph works this out automatically. The point is to keep the VRAM footprint bounded as the pipeline grows.

The VRAM Problem

A real pipeline uses fifteen-plus intermediate textures: shadow maps, SSAO buffers, bloom mip chains, SSR buffers, selection masks, and so on. A single Rgba16Float texture at 1080p is about 16 MB. At 4K it is 64 MB. Without aliasing, every one of those textures sits in VRAM whether it is in use or not.

Resource aliasing is the GPU equivalent of stack allocation. The same memory region gets reused by different variables (textures) whose lifetimes do not overlap. The graph's execution order gives a total ordering of passes, which is exactly what is needed to compute precise lifetimes and find aliasing opportunities.

The technique comes from the Frostbite frame graph (GDC 2017) and is standard practice in production engines. The savings run 30 to 50 percent of transient VRAM depending on the pipeline.

How It Works

After the topological sort, the graph knows the execution order. For every transient it computes two pass indices.

• first_use is the pass where the resource is first written.
• last_use is the pass where the resource is last read.

If resource A's last_use is before resource B's first_use, and they have compatible descriptors, they can share the same GPU texture.

Pass 0: writes A
Pass 1: reads A, writes B
Pass 2: reads B, writes C    <- A's memory can be reused for C
Pass 3: reads C, writes output

A's lifetime is [0, 1]. C's lifetime is [2, 3]. They do not overlap. If the descriptors match, the graph assigns them to the same pool slot.

Compatibility Requirements

Two textures alias when every one of the following matches.

• Format
• Width and height
• Sample count
• Mip level count
• The reuser's usage flags are a subset of the pool's usage flags

Two buffers alias when the pool's size is at least the reuser's size and the usage flags match exactly.

If a reuser needs usage flags the pool texture does not have, the pool texture is recreated with the combined flags. The reuser still gets to share the slot.

Pool-Based Allocation

The allocator is a pool keyed by a BinaryHeap ordered by lifetime_end. The heap gives constant-time access to the slot that frees up earliest.

1. Sort transient resources by first_use.
2. For each resource, check whether any pool slot has a lifetime_end strictly before this resource's first_use. If a compatible slot is found, reuse it. Otherwise allocate a new slot.
3. Each pool slot holds at most one GPU texture or buffer at any moment.

Min-heap on lifetime_end means the earliest-expiring slot is the one checked first, which is the right order for greedy reuse.

Bind Group Invalidation

When a transient gets a new GPU texture (the pool slot was reallocated), every pass that references that resource needs to rebuild its bind groups.

The graph keeps a version number per resource. When a resource's version changes between frames:

1. Find every pass that reads, writes, or reads_writes the resource.
2. Call invalidate_bind_groups() on those passes.
3. Update the stored version.

This is what keeps passes from accidentally binding the old GPU handle after an aliasing change or a window resize.

Memory Savings

A scene with fifteen-plus transient textures can shrink dramatically once aliasing is applied. Some concrete examples:

• ssao_raw and ssgi_raw are usually never live at the same time.
• Shadow depth maps are only live during shadow passes. After that, their memory is free.
• Intermediate blur textures from bloom can share memory with SSR blur textures.

The exact savings depend on the pass ordering and the resource sizes.

External Resources

External resources are never aliased. They are owned outside the graph and provided fresh each frame. The swapchain texture is the obvious case. Editor viewport outputs are the other.

Custom Passes

Custom rendering hooks into the graph through two State methods. One runs at startup. The other runs every frame.

configure_render_graph()

This is the setup hook. It runs once when the renderer is constructed. The game adds passes, declares textures, and changes the pipeline shape.

#![allow(unused)]
fn main() {
fn configure_render_graph(
    &mut self,
    graph: &mut RenderGraph<World>,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    resources: RenderResources,
) {
    // Add custom textures
    let my_texture = graph.add_color_texture("my_effect")
        .format(wgpu::TextureFormat::Rgba16Float)
        .size(1920, 1080)
        .clear_color(wgpu::Color::BLACK)
        .transient();

    // Add custom passes
    let my_pass = MyCustomPass::new(device);
    graph.add_pass(
        Box::new(my_pass),
        &[("input", resources.scene_color), ("output", my_texture)],
    );
}
}

RenderResources

RenderResources is the bundle of ResourceIds the engine already declared. Anything custom usually reads from scene_color and writes to compute_output or swapchain.

update_render_graph()

The per-frame hook. Use it for runtime state flips, not for adding passes (use the setup hook for that).

#![allow(unused)]
fn main() {
fn update_render_graph(&mut self, graph: &mut RenderGraph<World>, world: &World) {
    if self.bloom_changed {
        let _ = graph.set_pass_enabled("bloom_pass", self.bloom_enabled);
        self.bloom_changed = false;
    }
}
}

Adding Built-in Passes

The built-in pass types are reusable. A custom graph can pick and choose which built-ins to include.

#![allow(unused)]
fn main() {
use nightshade::render::passes;

fn configure_render_graph(
    &mut self,
    graph: &mut RenderGraph<World>,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    resources: RenderResources,
) {
    let bloom_texture = graph.add_color_texture("bloom")
        .format(wgpu::TextureFormat::Rgba16Float)
        .size(960, 540)
        .clear_color(wgpu::Color::BLACK)
        .transient();

    // Bloom
    let bloom_pass = passes::BloomPass::new(device, 1920, 1080);
    graph.add_pass(
        Box::new(bloom_pass),
        &[("hdr", resources.scene_color), ("bloom", bloom_texture)],
    );

    // SSAO
    let ssao_pass = passes::SsaoPass::new(device, 1920, 1080);
    graph.add_pass(
        Box::new(ssao_pass),
        &[
            ("depth", resources.depth),
            ("normals", resources.view_normals),
            ("ssao_raw", resources.ssao_raw),
        ],
    );

    let ssao_blur_pass = passes::SsaoBlurPass::new(device, 1920, 1080);
    graph.add_pass(
        Box::new(ssao_blur_pass),
        &[("ssao_raw", resources.ssao_raw), ("ssao", resources.ssao)],
    );

    // Final compositing
    let postprocess_pass = passes::PostProcessPass::new(device, surface_format, 0.3);
    graph.add_pass(
        Box::new(postprocess_pass),
        &[
            ("hdr", resources.scene_color),
            ("bloom", bloom_texture),
            ("ssao", resources.ssao),
            ("output", resources.compute_output),
        ],
    );

    // Blit to swapchain
    let blit_pass = passes::BlitPass::new(device, surface_format);
    graph.add_pass(
        Box::new(blit_pass),
        &[("input", resources.compute_output), ("output", resources.swapchain)],
    );
}
}

PassBuilder Fluent API

pass() is an alternative to add_pass() that reads more like an expression. The builder adds the pass to the graph when it goes out of scope.

#![allow(unused)]
fn main() {
graph.pass(Box::new(bloom_pass))
    .read("hdr", resources.scene_color)
    .write("bloom", bloom_texture);

graph.pass(Box::new(postprocess_pass))
    .read("hdr", resources.scene_color)
    .read("bloom", bloom_texture)
    .read("ssao", resources.ssao)
    .write("output", resources.swapchain);
}

Conditional Passes

There are two ways to make a pass conditional. The first is to leave it out of the graph entirely at setup time.

#![allow(unused)]
fn main() {
fn configure_render_graph(
    &mut self,
    graph: &mut RenderGraph<World>,
    device: &wgpu::Device,
    surface_format: wgpu::TextureFormat,
    resources: RenderResources,
) {
    if self.ssao_enabled {
        let ssao_pass = passes::SsaoPass::new(device, 1920, 1080);
        graph.add_pass(
            Box::new(ssao_pass),
            &[
                ("depth", resources.depth),
                ("normals", resources.view_normals),
                ("ssao_raw", resources.ssao_raw),
            ],
        );
    }
}
}

The second is to add the pass unconditionally and toggle it at runtime.

#![allow(unused)]
fn main() {
fn update_render_graph(&mut self, graph: &mut RenderGraph<World>, _world: &World) {
    let _ = graph.set_pass_enabled("ssao_pass", self.ssao_enabled);
}
}

The toggle path is the right choice when the setting changes during play. The conditional-construction path is the right choice when the decision is fixed at startup, because it skips the per-frame check entirely.

Default Pipeline

If the game does not override configure_render_graph(), the default implementation adds three passes:

1. BloomPass runs HDR bloom at half resolution.
2. PostProcessPass does tonemapping and compositing.
3. BlitPass copies to the swapchain.

The engine always adds the core passes (clear, sky, shadow, mesh, skinned mesh, grass, grid, lines, selection) regardless of what the custom configuration does. Overriding configure_render_graph() only changes the post-process tail.

The Default Pipeline

The default render graph is what the engine constructs when the game does not override configure_render_graph(). This chapter is the inventory: the pass list, the order they end up in after topological sort, and the data flow between them.

Pass Execution Order

The graph sorts these passes from their declared read and write dependencies. The order below is the one that comes out the other side for a typical configuration.

1.  ClearPass           - Clear scene_color and depth
2.  ShadowDepthPass     - Render cascaded shadow maps + spotlight shadows
3.  SkyPass             - Render procedural atmosphere to scene_color
4.  ScenePass           - Render scene objects (simple path) to scene_color
5.  MeshPass            - Render PBR meshes with shadows and lighting
6.  SkinnedMeshPass     - Render animated skeletal meshes
7.  GrassPass           - Render GPU-instanced grass
8.  GridPass            - Render infinite ground grid
9.  LinesPass           - Render debug lines
10. SelectionMaskPass   - Generate selection mask for editor
11. OutlinePass         - Render selection outline

    --- User passes (from configure_render_graph) ---

12. BloomPass           - HDR bloom (default)
13. PostProcessPass     - Tonemapping and compositing (default)
14. BlitPass            - Copy to swapchain (default)

Data Flow Diagram

                    shadow_depth
ShadowDepthPass --> spotlight_shadow_atlas
                        |
                        v
SkyPass ----------> scene_color <-- ClearPass
                        |
MeshPass ----------> scene_color, depth, entity_id, view_normals
                        |
SkinnedMeshPass --> scene_color, depth
                        |
GrassPass --------> scene_color, depth
GridPass ---------> scene_color, depth
LinesPass --------> scene_color, depth
                        |
                        v
BloomPass --------> bloom (half-res)
                        |
PostProcessPass --> compute_output
    reads: scene_color, bloom, ssao
                        |
BlitPass ---------> swapchain

Core Passes (Always Present)

These passes are added by the engine during renderer initialization. They cannot be removed. They can be disabled at runtime.

ClearPass

Clears scene_color to black and depth to 0.0. Reversed-Z is the convention everywhere in the renderer, so 0.0 is the far plane.

SkyPass

Renders the procedural atmosphere or a solid background. Controlled by world.resources.graphics.atmosphere.

ScenePass

A simpler scene path for basic objects, kept around alongside the PBR mesh pass.

ShadowDepthPass

Renders the shadow map. The depth target is shadow_depth (cascaded sun shadows) plus spotlight_shadow_atlas (per-spotlight shadows packed into one atlas). See Shadow Mapping.

MeshPass

The main PBR mesh pass. Multi-target output: scene_color for HDR shaded color, depth for depth, entity_id for GPU picking, and view_normals for SSAO and SSR. One fragment invocation writes to all four. See Geometry Passes.

SkinnedMeshPass

The same idea as MeshPass but with GPU skinning for animated skeletal meshes.

Selection Passes

SelectionMaskPass writes a mask of selected entities into selection_mask. OutlinePass reads the mask and renders the outline.

User-Configurable Passes (Default)

These three are what the default configure_render_graph() adds. Override the method to replace them.

BloomPass

Reads scene_color, writes a half-resolution bloom texture.

PostProcessPass

Reads scene_color, bloom, and ssao. Performs tonemapping and compositing. Writes to compute_output.

BlitPass

Copies compute_output to swapchain for presentation.

Adding SSAO/SSGI/SSR

The default pipeline only ships bloom and tonemapping. SSAO, SSGI, and SSR are not in the default graph because they cost real GPU time and not every game wants them. To enable any of them, override configure_render_graph() and add the relevant passes. See Post-Processing for the full list of available post-process passes, and Custom Passes for the wiring.

Shadow Mapping

Live Demos: Shadows | Spotlight Shadows

Nightshade uses cascaded shadow mapping for directional lights and a single shadow atlas for every spotlight in the scene.

How shadow mapping works

Shadow mapping is two passes. The first pass renders the scene from the light's point of view into a depth-only texture, the shadow map. The second pass is the regular geometry pass. Every fragment projects itself into the light's coordinate space and compares its depth against the value stored in the shadow map. If the fragment is farther from the light than the shadow map records, something closer to the light is blocking it, and the fragment is in shadow.

The shadow map records "closest surface to the light" at every texel. Anything behind that closest surface must be occluded. The cost of the lookup is one texture sample per fragment per light.

The resolution problem

A single shadow map has a fixed resolution. A directional light like the sun illuminates the entire scene, so the shadow map has to cover all of it. Objects near the camera want high-resolution shadows because the eye can see the edges clearly. Distant objects can tolerate much lower resolution because they cover a few pixels of screen space anyway. One global shadow map wastes resolution on geometry that is far away and starves the geometry that is close.

Cascaded shadow maps (CSM)

The fix is to split the camera's view frustum into depth ranges and give each range its own shadow map. Near cascades cover a small area at high texel density. Far cascades cover a large area at lower density. The total memory cost is fixed, but the texels go where they are seen.

The ShadowDepthPass renders four shadow cascades (NUM_SHADOW_CASCADES = 4) into a single large depth texture, one per quadrant.

• Cascade 0 is the near range, highest detail, covering roughly 0 to 10 percent of the view distance.
• Cascade 1 is the mid-near range, covering roughly 10 to 30 percent.
• Cascade 2 is the mid-far range, covering roughly 30 to 60 percent.
• Cascade 3 is the far range, lowest detail, covering roughly 60 to 100 percent.

Shadow map resolution

Each cascade takes one quadrant of the texture, so each cascade gets an effective 4096 x 4096 on native and 2048 x 2048 on the web.

How cascades work

Every frame the engine does four things.

The first is frustum computation. The camera's view frustum is the truncated pyramid defined by the near plane, the far plane, and the field of view. The engine pulls the eight corners of that pyramid out of the camera matrices.

The second is frustum splitting. The frustum gets sliced into four depth ranges using a logarithmic-linear blend. Logarithmic splitting gives more resolution to near cascades. Linear splitting distributes resolution evenly. A blend of 0.5 to 0.8 toward logarithmic produces good results across most scenes.

The third is tight projection fitting. For each cascade, the engine takes the eight corners of that frustum slice, transforms them into light space, and builds an orthographic projection matrix that just encloses those points. The matrix is as tight as the slice allows, which keeps texels from being wasted on empty space outside the cascade's actual coverage.

The fourth is shadow rendering. Every shadow-casting mesh is drawn from the directional light's perspective into each cascade's viewport region of the shadow texture.

During the mesh pass, each fragment decides which cascade to sample based on its distance from the camera. The shader picks the highest-resolution cascade that still contains the fragment, projects into that cascade's light-space coordinates, and does the depth comparison.

Cascade selection and blending

At cascade boundaries, shadows can show visible seams because the resolution changes abruptly across the boundary. The fragment shader compares the fragment's view-space depth against the cascade split distances to pick a cascade. Implementations that need smoother transitions blend between adjacent cascades in a small band around the boundary.

Spotlight shadow atlas

Spotlights share one atlas instead of getting their own textures.

Every spotlight with cast_shadows: true gets a slot in the atlas. The atlas is subdivided to fit multiple spotlights at the cost of per-light resolution.

Enabling shadows

Directional light shadows

spawn_sun() creates a directional light with shadows enabled by default.

#![allow(unused)]
fn main() {
let sun = spawn_sun(world);
}

To configure manually:

#![allow(unused)]
fn main() {
world.core.set_light(entity, Light {
    light_type: LightType::Directional,
    cast_shadows: true,
    shadow_bias: 0.005,
    ..Default::default()
});
}

Spotlight shadows

#![allow(unused)]
fn main() {
world.core.set_light(entity, Light {
    light_type: LightType::Spot,
    cast_shadows: true,
    shadow_bias: 0.002,
    inner_cone_angle: 0.2,
    outer_cone_angle: 0.5,
    ..Default::default()
});
}

Per-mesh shadow casting

Control which meshes cast shadows.

#![allow(unused)]
fn main() {
world.core.add_components(entity, CASTS_SHADOW);
world.core.set_casts_shadow(entity, CastsShadow);

// Disable:
world.core.remove_components(entity, CASTS_SHADOW);
}

Shadow quality

Shadow bias

Shadow acne comes from the shadow map's finite resolution. A surface that should be lit samples the shadow map at a slightly different position than where it was rendered, and floating-point imprecision lets the surface report itself as in shadow. The result is a moire-like pattern of alternating lit and shadowed stripes on flat surfaces.

The fix is shadow bias. A small depth offset is added during the comparison, pushing the comparison point slightly toward the light so a surface cannot self-shadow. The tradeoff is peter-panning. Too much bias detaches the shadow from the base of the object because the comparison point gets pushed past the surface entirely.

shadow_bias controls the offset.

#![allow(unused)]
fn main() {
light.shadow_bias = 0.005;  // Good default for directional lights
light.shadow_bias = 0.002;  // Good default for spotlights
}

Spotlights need less bias because their shadow maps cover a smaller area at higher effective resolution, so the acne is less severe to begin with.

Cascade settings

Shadow cascades are configured at the renderer level. The engine uses 4 cascades (NUM_SHADOW_CASCADES = 4) with the shadow map resolution set at initialization (8192 native, 4096 WASM). These are not runtime-configurable through Graphics resources.

Geometry Passes

Geometry passes render scene objects into the HDR color buffer and the depth buffer. Each pass handles a different category of geometry and writes a subset of the available render targets.

ClearPass

The ClearPass clears scene_color to black and depth to 0.0, which is the reversed-Z far plane. It always runs first so every other pass sees a known starting state.

Writes: scene_color, depth

SkyPass

The SkyPass renders the sky or atmosphere background. The mode is selected by world.resources.graphics.atmosphere.

• Atmosphere::None is a solid background color and is the default.
• Atmosphere::Sky is a procedural clear-sky gradient.
• Atmosphere::CloudySky is a procedural sky with volumetric clouds.
• Atmosphere::Space is a procedural starfield.
• Atmosphere::Nebula is a procedural nebula with stars.
• Atmosphere::Sunset is a procedural sunset gradient.
• Atmosphere::DayNight is a procedural day-night cycle driven by an hour parameter.
• Atmosphere::Hdr is an HDR environment cubemap.

Writes: scene_color

ScenePass

The ScenePass is a basic scene rendering pass for simple objects that do not need the full PBR pipeline.

Reads/Writes: scene_color, depth

MeshPass

The MeshPass is the main PBR mesh rendering pass. It renders all entities with RENDER_MESH | MATERIAL_REF | GLOBAL_TRANSFORM. The fragment shader does PBR shading with the metallic-roughness workflow, samples the shadow depth texture for cascaded shadow maps, samples the spotlight shadow atlas, applies normal mapping from a per-material normal texture, and supports opaque, mask, and blend alpha modes. The same shader output also writes entity IDs for GPU picking and view-space normals for SSAO and SSGI, all in a single fragment invocation.

Reads: shadow_depth, spotlight_shadow_atlas Writes: scene_color, depth, entity_id, view_normals

SkinnedMeshPass

The SkinnedMeshPass renders animated skeletal meshes. It reads bone matrices from the skinning buffer and transforms vertices on the GPU.

Reads: shadow_depth, spotlight_shadow_atlas Writes: scene_color, depth

GrassPass

The GrassPass is GPU-instanced grass rendering. It renders thousands of grass blades using instance data from GrassRegion components, with wind animation and interactive bending driven by GrassInteractor components.

Reads/Writes: scene_color, depth

DecalPass

The DecalPass renders projected decals onto scene geometry. Each decal samples the depth buffer to project its texture onto whatever surface is behind it.

Reads/Writes: scene_color, depth

ParticlePass

The ParticlePass is GPU billboard particle rendering. It reads ParticleEmitter component data and renders camera-facing quads, one per particle.

Reads/Writes: scene_color, depth

TextPass

The TextPass renders 3D world-space text using the font atlas.

Reads/Writes: scene_color, depth

HudPass

The HudPass renders screen-space HUD text. Unlike the TextPass, HUD text is positioned in screen coordinates with configurable anchoring rather than placed in the world.

Reads/Writes: scene_color, depth

LinesPass

The LinesPass renders debug lines from Lines components. The pass is the workhorse for visualization, bounding boxes, and any other debug geometry.

Reads/Writes: scene_color, depth

GridPass

The GridPass renders an infinite ground grid. It is gated on world.resources.graphics.show_grid.

Reads/Writes: scene_color, depth

UiRectPass

The UiRectPass renders UI rectangles for the immediate-mode UI system.

SelectionMaskPass

The SelectionMaskPass generates a selection mask texture for selected entities. The editor uses it to drive selection outlines.

Reads: depth Writes: selection_mask

OutlinePass

The OutlinePass reads the selection mask and renders outlines around selected entities by detecting edges in the mask.

Reads: selection_mask Writes: scene_color

ProjectionPass / HiZPass

The ProjectionPass and HiZPass build a hierarchical-Z buffer for occlusion culling.

Post-Processing

Live Demos: Bloom | SSAO | Depth of Field

Post-processing passes read the HDR scene color, the depth buffer, and the view-space normals and produce the final image. They are added to the graph in configure_render_graph().

Available passes

Enabling effects

Post-processing is controlled through world.resources.graphics.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    world.resources.graphics.bloom_enabled = true;
    world.resources.graphics.bloom_intensity = 0.3;

    world.resources.graphics.ssao_enabled = true;
    world.resources.graphics.ssao_radius = 0.5;
    world.resources.graphics.ssao_intensity = 1.0;

    world.resources.graphics.color_grading.tonemap_algorithm = TonemapAlgorithm::Aces;
}
}

SSAO (Screen-Space Ambient Occlusion)

Corners, crevices, and enclosed spaces receive less ambient light in the real world because surrounding geometry occludes incoming light from many directions. SSAO approximates that effect in screen space by reading the depth buffer.

How SSAO works

For each pixel, the shader reconstructs the 3D position from the depth buffer, then samples several random points in a hemisphere oriented along the surface normal. Each sample point is projected back into screen space and checked against the depth buffer. If the stored depth is closer than the sample point's depth, that direction is considered occluded. The ratio of occluded samples to total samples is the occlusion factor.

The three inputs are the depth buffer for the 3D position of each pixel, the view-space normals for the hemisphere orientation, and a random noise texture that rotates the sample kernel per-pixel to avoid banding patterns.

The raw output is noisy because the sample count is small. Typical SSAO uses 16 to 64 samples per pixel. A bilateral blur pass smooths the result while preserving edges, which means it avoids blurring across depth discontinuities. Without the bilateral guard the blur would produce halos around silhouettes.

#![allow(unused)]
fn main() {
world.resources.graphics.ssao_enabled = true;
world.resources.graphics.ssao_radius = 0.5;
world.resources.graphics.ssao_intensity = 1.0;
world.resources.graphics.ssao_bias = 0.025;
}

ssao_radius is the hemisphere radius in world units. Larger values detect occlusion from farther geometry but can over-darken broad regions. ssao_bias is a small depth offset that prevents self-occlusion artifacts on flat surfaces. ssao_intensity is the multiplier on the final occlusion factor.

SSGI (Screen-Space Global Illumination)

Light bounces between surfaces in the real world. A red wall next to a white floor tints the floor red. Traditional rasterization computes direct lighting only, which is light source to surface to camera. Global illumination adds the indirect bounces.

SSGI approximates one bounce of indirect light using only screen-space data. For each pixel, the shader traces short rays through the depth buffer to find nearby surfaces, then reads the color at those hit points as incoming indirect light. It is conceptually the same trick as SSAO, except it samples color instead of just occlusion.

The pass runs at half resolution. The indirect illumination is low-frequency, the bilateral blur cleans up the noise, and the upsample reintroduces full resolution at the composite step.

SSR (Screen-Space Reflections)

SSR adds dynamic reflections by ray-marching through the depth buffer. For each reflective pixel, the shader computes the reflection vector from the camera direction and the surface normal, then steps along that vector in screen space, checking the depth buffer at each step. When the ray's depth exceeds the depth buffer value, the ray has hit a surface. The color at that screen position is used as the reflection.

The technique works well for reflections of on-screen geometry. The limits are inherent. Off-screen objects cannot be reflected because there is no data for them. Reflections at grazing angles stretch across large screen areas. The blur pass hides the worst of the artifacts, and a fallback to environment maps or IBL fills in where SSR has no data at all.

Bloom

Bloom simulates the light scattering that happens in real cameras and in the human eye when bright light sources bleed into surrounding pixels. In HDR rendering, pixels can hold values above 1.0, which is the displayable range. Bloom extracts those bright pixels and spreads their light outward.

How bloom works

The bloom pipeline uses a progressive downsample-then-upsample chain, the same approach described in the Call of Duty Advanced Warfare presentation.

The first step thresholds the HDR scene color, keeping only pixels above a configurable cutoff. The second step is the downsample chain. Resolution is progressively halved through multiple mip levels, for example 1920x1080 to 960x540 to 480x270 and so on, with a blur applied at each step. Blurring at low mip levels is far cheaper than blurring at full resolution because each level has a quarter of the pixels of the level above. The third step is the upsample chain. The renderer walks back up the mip chain, additively blending each level with the one above it. The result is a smooth, wide blur that spans many pixels of the final image without ever using a large blur kernel directly. The fourth step is the composite. The bloom result is added to the scene color during the final post-process pass.

The mip-chain approach produces natural-looking bloom because tight glow comes out of the high-resolution mips while wide glow comes out of the low-resolution mips, both at once.

#![allow(unused)]
fn main() {
world.resources.graphics.bloom_enabled = true;
world.resources.graphics.bloom_intensity = 0.5;
}

Materials with high emissive values produce the strongest bloom.

#![allow(unused)]
fn main() {
let glowing = Material {
    base_color: [0.2, 0.8, 1.0, 1.0],
    emissive_factor: [2.0, 8.0, 10.0],
    ..Default::default()
};
}

Depth of field

Depth of field simulates the optical behavior of a physical camera lens. A real lens can only focus at one distance, and objects nearer or farther than the focal plane appear blurred. The amount of blur is called the circle of confusion (CoC), and it grows with distance from the focal plane. Aperture size sets the maximum.

How DoF works

The first step is CoC computation. For each pixel, the shader pulls the depth value out of the depth buffer, combines it with the focus distance and aperture, and produces a CoC diameter in pixels.

The second step is the blur. A variable-radius blur is applied where the kernel size scales with the CoC. Pixels far from focus get heavy blur. Pixels near the focal plane stay sharp.

The third step is the bokeh accent. Bright out-of-focus highlights form the characteristic disc or hexagon shapes called bokeh. The shader emphasizes bright pixels during the blur to reproduce the optical effect.

#![allow(unused)]
fn main() {
world.resources.graphics.depth_of_field.enabled = true;
world.resources.graphics.depth_of_field.focus_distance = 10.0;
world.resources.graphics.depth_of_field.focus_range = 5.0;
world.resources.graphics.depth_of_field.max_blur_radius = 10.0;
world.resources.graphics.depth_of_field.bokeh_threshold = 1.0;
world.resources.graphics.depth_of_field.bokeh_intensity = 1.0;
}

Tonemapping

HDR rendering computes lighting in a physically linear color space where values can range from 0 to thousands. Displays can only show values between 0 and 1. Tonemapping compresses the HDR range into the displayable LDR range while preserving the perception of brightness differences and color relationships.

Different curves make different tradeoffs. Reinhard is the simple color / (color + 1) mapping. It preserves highlights but tends to look washed out. ACES is the film industry curve. It produces good contrast and a slight warm tint and is what most games ship with. AgX is a more recent curve designed to handle highly saturated colors better than ACES, which can produce hue shifts in bright saturated regions. Neutral does minimal color manipulation and is useful when color grading is handled externally.

The PostProcessPass does the HDR-to-LDR conversion.

#![allow(unused)]
fn main() {
pub enum TonemapAlgorithm {
    Reinhard,
    Aces,
    ReinhardExtended,
    Uncharted2,
    AgX,
    Neutral,
    None,
}

world.resources.graphics.color_grading.tonemap_algorithm = TonemapAlgorithm::Aces;
}

Color grading

#![allow(unused)]
fn main() {
world.resources.graphics.color_grading.saturation = 1.0;
world.resources.graphics.color_grading.contrast = 1.0;
world.resources.graphics.color_grading.brightness = 0.0;
}

Effects pass

The EffectsPass runs custom WGSL shader effects for specialized visual treatments. The standard set includes color grading presets, chromatic aberration, film grain, and any custom shader the application wants to inject.

See Effects Pass for details.

Custom post-processing

Custom passes are added through the render graph. See Custom Passes for the implementation pattern.

Performance

Disable expensive effects for lower-end hardware.

#![allow(unused)]
fn main() {
fn set_quality_low(world: &mut World) {
    world.resources.graphics.ssao_enabled = false;
    world.resources.graphics.bloom_enabled = false;
}

fn set_quality_high(world: &mut World) {
    world.resources.graphics.ssao_enabled = true;
    world.resources.graphics.bloom_enabled = true;
}
}

Cameras

Live Demo: Skybox

A camera defines the viewpoint and projection used to render the scene. Nightshade uses reversed-Z depth buffers for both perspective and orthographic projections, supports infinite far planes, frame-rate-independent input smoothing, and an arc-ball orbit controller for editor-style navigation.

Camera component

A camera entity needs a transform and the CAMERA component.

#![allow(unused)]
fn main() {
let camera = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | CAMERA,
    1
)[0];
}

#![allow(unused)]
fn main() {
pub struct Camera {
    pub projection: Projection,
    pub smoothing: Option<Smoothing>,
}

pub enum Projection {
    Perspective(PerspectiveCamera),
    Orthographic(OrthographicCamera),
}
}

The default Camera is perspective with a 45 degree FOV, an infinite far plane, a 0.01 near plane, and smoothing on.

Spawning cameras

Basic camera

#![allow(unused)]
fn main() {
let camera = spawn_camera(
    world,
    Vec3::new(0.0, 5.0, 10.0),
    "Main Camera".to_string(),
);
world.resources.active_camera = Some(camera);
}

Pan-orbit camera

For editor-style arc-ball controls.

#![allow(unused)]
fn main() {
use nightshade::ecs::camera::commands::spawn_pan_orbit_camera;

let camera = spawn_pan_orbit_camera(
    world,
    Vec3::new(0.0, 2.0, 0.0),  // focus point
    10.0,                       // radius (distance)
    0.5,                        // yaw (horizontal angle)
    0.4,                        // pitch (vertical angle)
    "Orbit Camera".to_string(),
);
}

Perspective projection

#![allow(unused)]
fn main() {
pub struct PerspectiveCamera {
    pub aspect_ratio: Option<f32>,
    pub y_fov_rad: f32,
    pub z_far: Option<f32>,
    pub z_near: f32,
}
}

Reversed-Z projection

Nightshade uses reversed-Z depth buffers. The near plane maps to depth 1.0 and the far plane maps to 0.0. The reason is precision. Floating-point depth has its highest precision near 0.0, and reversing the mapping puts that precision where the eye notices it most, on distant objects. Z-fighting at long range drops dramatically without changing anything else about the pipeline.

With an infinite far plane (z_far: None), the projection matrix is:

f = 1 / tan(fov / 2)

| f/aspect  0     0      0     |
| 0         f     0      0     |
| 0         0     0      z_near|
| 0         0    -1      0     |

With a finite far plane the matrix maps [z_near, z_far] to [1.0, 0.0]:

| f/aspect  0     0                          0                           |
| 0         f     0                          0                           |
| 0         0     z_near/(z_far - z_near)    z_near*z_far/(z_far-z_near) |
| 0         0    -1                          0                           |

#![allow(unused)]
fn main() {
world.core.set_camera(camera, Camera {
    projection: Projection::Perspective(PerspectiveCamera {
        y_fov_rad: 1.0,
        aspect_ratio: None,
        z_near: 0.1,
        z_far: Some(1000.0),
    }),
    smoothing: None,
});
}

Orthographic projection

#![allow(unused)]
fn main() {
pub struct OrthographicCamera {
    pub x_mag: f32,
    pub y_mag: f32,
    pub z_far: f32,
    pub z_near: f32,
}
}

The orthographic projection uses reversed-Z too, mapping [z_near, z_far] to [1.0, 0.0].

#![allow(unused)]
fn main() {
world.core.set_camera(camera, Camera {
    projection: Projection::Orthographic(OrthographicCamera {
        x_mag: 10.0,
        y_mag: 10.0,
        z_near: 0.1,
        z_far: 100.0,
    }),
    smoothing: None,
});
}

Camera systems

Fly camera

A free-flying FPS-style camera with WASD movement.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    fly_camera_system(world);
}
}

Pan-orbit camera

The arc-ball camera that orbits around a focus point.

#![allow(unused)]
fn main() {
use nightshade::ecs::camera::systems::pan_orbit_camera_system;

fn run_systems(&mut self, world: &mut World) {
    pan_orbit_camera_system(world);
}
}

Orthographic camera

For 2D or isometric views.

#![allow(unused)]
fn main() {
use nightshade::ecs::camera::systems::ortho_camera_system;

fn run_systems(&mut self, world: &mut World) {
    ortho_camera_system(world);
}
}

Input smoothing

The Smoothing component applies frame-rate-independent exponential smoothing to camera input. The smoothing factor is computed as:

smoothing_factor = 1.0 - smoothness^7 ^ delta_time

smoothness is the per-device smoothness parameter. A smoothness of 0 gives instant response. Values approaching 1 make the input progressively more sluggish. The powi(7) exponent is there to make the parameter feel linear when you adjust it in an inspector.

#![allow(unused)]
fn main() {
pub struct Smoothing {
    pub mouse_sensitivity: f32,
    pub mouse_smoothness: f32,
    pub mouse_dpi_scale: f32,
    pub keyboard_smoothness: f32,
    pub gamepad_sensitivity: f32,
    pub gamepad_smoothness: f32,
    pub gamepad_deadzone: f32,
}
}

#![allow(unused)]
fn main() {
world.core.set_camera(camera, Camera {
    projection: Projection::Perspective(PerspectiveCamera::default()),
    smoothing: Some(Smoothing {
        mouse_sensitivity: 0.5,
        mouse_smoothness: 0.05,
        keyboard_smoothness: 0.08,
        ..Smoothing::default()
    }),
});
}

Pan-orbit camera configuration

The PanOrbitCamera component is a fully configurable arc-ball camera with Blender-style controls by default.

#![allow(unused)]
fn main() {
pub struct PanOrbitCamera {
    pub focus: Vec3,
    pub radius: f32,
    pub yaw: f32,
    pub pitch: f32,
    pub target_focus: Vec3,
    pub target_radius: f32,
    pub target_yaw: f32,
    pub target_pitch: f32,
    pub enabled: bool,
    // ... configuration fields
}
}

Default controls

Builder API

#![allow(unused)]
fn main() {
let pan_orbit = PanOrbitCamera::new(focus, 10.0)
    .with_yaw_pitch(0.5, 0.4)
    .with_zoom_limits(1.0, Some(100.0))
    .with_pitch_limits(-1.5, 1.5)
    .with_smoothness(0.1, 0.02, 0.1)
    .with_buttons(PanOrbitButton::Middle, PanOrbitButton::Middle)
    .with_modifiers(None, Some(PanOrbitModifier::Shift))
    .with_upside_down(false);
}

Sensitivity and smoothness

Each action has independent sensitivity and smoothness parameters.

Target values (target_yaw, target_pitch, target_focus, target_radius) are set by user input. The current values interpolate toward the targets every frame using the smoothing formula. The system snaps to the target when the difference falls below 0.001 to avoid an infinite tail.

Zoom and pitch limits

#![allow(unused)]
fn main() {
if let Some(pan_orbit) = world.core.get_pan_orbit_camera_mut(camera) {
    pan_orbit.zoom_lower_limit = 1.0;
    pan_orbit.zoom_upper_limit = Some(50.0);
    pan_orbit.pitch_upper_limit = std::f32::consts::FRAC_PI_2 - 0.01;
    pan_orbit.pitch_lower_limit = -(std::f32::consts::FRAC_PI_2 - 0.01);
}
}

Upside-down handling

When allow_upside_down is true, the pitch can exceed plus or minus 90 degrees. When the camera goes upside down, the yaw direction is automatically reversed so mouse control still feels right.

Runtime control

#![allow(unused)]
fn main() {
if let Some(pan_orbit) = world.core.get_pan_orbit_camera_mut(camera) {
    pan_orbit.target_focus = Vec3::new(0.0, 2.0, 0.0);
    pan_orbit.target_radius = 5.0;
    pan_orbit.target_yaw += 0.1;
    pan_orbit.target_pitch += 0.05;
}
}

Computing camera transform

The pan-orbit camera position is computed from yaw, pitch, and radius.

#![allow(unused)]
fn main() {
let (position, rotation) = pan_orbit.compute_camera_transform();
}

The camera sits at focus + rotate(yaw, pitch) * (0, 0, radius). The rotation is composed as yaw around Y first and then pitch around X.

Screen-to-world conversion

Convert screen coordinates to a world-space ray.

#![allow(unused)]
fn main() {
use nightshade::ecs::picking::PickingRay;

let screen_pos = world.resources.input.mouse.position;
if let Some(ray) = PickingRay::from_screen_position(world, screen_pos) {
    let origin = ray.origin;
    let direction = ray.direction;
}
}

For perspective cameras, the ray origin is the camera position and the direction is computed by unprojecting through the inverse view-projection matrix. For orthographic cameras, the origin is the unprojected near-plane point and the direction is the camera's forward vector.

Multiple cameras

Switching between cameras is a single field write.

#![allow(unused)]
fn main() {
fn on_keyboard_input(&mut self, world: &mut World, key: KeyCode, state: ElementState) {
    if state == ElementState::Pressed && key == KeyCode::Tab {
        let current = world.resources.active_camera;
        world.resources.active_camera = if current == Some(self.main_camera) {
            Some(self.debug_camera)
        } else {
            Some(self.main_camera)
        };
    }
}
}

Materials

Live Demos: Textures | Alpha Blending

A material defines the visual appearance of a mesh using physically based rendering. Nightshade follows the glTF 2.0 metallic-roughness workflow and supports several glTF extensions on top of it: KHR_materials_transmission, KHR_materials_volume, KHR_materials_specular, and KHR_materials_emissive_strength.

Material structure

#![allow(unused)]
fn main() {
pub struct Material {
    // Core PBR
    pub base_color: [f32; 4],
    pub roughness: f32,
    pub metallic: f32,
    pub emissive_factor: [f32; 3],
    pub emissive_strength: f32,
    pub alpha_mode: AlphaMode,
    pub alpha_cutoff: f32,
    pub unlit: bool,
    pub double_sided: bool,
    pub uv_scale: [f32; 2],

    // Textures
    pub base_texture: Option<String>,
    pub base_texture_uv_set: u32,
    pub emissive_texture: Option<String>,
    pub emissive_texture_uv_set: u32,
    pub normal_texture: Option<String>,
    pub normal_texture_uv_set: u32,
    pub normal_scale: f32,
    pub normal_map_flip_y: bool,
    pub normal_map_two_component: bool,
    pub metallic_roughness_texture: Option<String>,
    pub metallic_roughness_texture_uv_set: u32,
    pub occlusion_texture: Option<String>,
    pub occlusion_texture_uv_set: u32,
    pub occlusion_strength: f32,

    // Transmission (KHR_materials_transmission)
    pub transmission_factor: f32,
    pub transmission_texture: Option<String>,
    pub transmission_texture_uv_set: u32,

    // Volume (KHR_materials_volume)
    pub thickness: f32,
    pub thickness_texture: Option<String>,
    pub thickness_texture_uv_set: u32,
    pub attenuation_color: [f32; 3],
    pub attenuation_distance: f32,
    pub ior: f32,

    // Specular (KHR_materials_specular)
    pub specular_factor: f32,
    pub specular_color_factor: [f32; 3],
    pub specular_texture: Option<String>,
    pub specular_texture_uv_set: u32,
    pub specular_color_texture: Option<String>,
    pub specular_color_texture_uv_set: u32,
}
}

Core PBR fields

Normal map options

Transmission and volume

The transmission and volume fields implement light transmission through surfaces, which covers glass, water, and thin-shell materials.

Specular

The specular fields override the default Fresnel reflectance for dielectric materials.

Alpha modes

#![allow(unused)]
fn main() {
pub enum AlphaMode {
    Opaque,  // Fully opaque, alpha ignored
    Mask,    // Binary transparency using alpha_cutoff
    Blend,   // Full alpha blending
}
}

Creating materials

Basic colored material

#![allow(unused)]
fn main() {
let red_material = Material {
    base_color: [1.0, 0.0, 0.0, 1.0],
    roughness: 0.5,
    metallic: 0.0,
    ..Default::default()
};

material_registry_insert(
    &mut world.resources.material_registry,
    "red".to_string(),
    red_material,
);
}

Metallic material

#![allow(unused)]
fn main() {
let gold = Material {
    base_color: [1.0, 0.84, 0.0, 1.0],
    roughness: 0.3,
    metallic: 1.0,
    ..Default::default()
};
}

Emissive material

The final emissive output is emissive_factor * emissive_strength * emissive_texture.

#![allow(unused)]
fn main() {
let neon = Material {
    base_color: [0.2, 0.8, 1.0, 1.0],
    emissive_factor: [0.2, 0.8, 1.0],
    emissive_strength: 10.0,
    roughness: 0.8,
    ..Default::default()
};
}

Glass / transmissive material

#![allow(unused)]
fn main() {
let glass = Material {
    base_color: [0.95, 0.95, 1.0, 1.0],
    roughness: 0.05,
    metallic: 0.0,
    transmission_factor: 0.95,
    ior: 1.5,
    ..Default::default()
};
}

Colored glass with volume absorption

#![allow(unused)]
fn main() {
let stained_glass = Material {
    base_color: [0.8, 0.2, 0.2, 1.0],
    roughness: 0.05,
    transmission_factor: 0.9,
    thickness: 0.02,
    attenuation_color: [0.8, 0.1, 0.1],
    attenuation_distance: 0.05,
    ior: 1.52,
    ..Default::default()
};
}

Transparent (alpha blended) material

#![allow(unused)]
fn main() {
let ghost = Material {
    base_color: [0.9, 0.95, 1.0, 0.3],
    alpha_mode: AlphaMode::Blend,
    roughness: 0.1,
    ..Default::default()
};
}

Foliage (alpha mask)

#![allow(unused)]
fn main() {
let foliage = Material {
    base_texture: Some("leaf_color".to_string()),
    alpha_mode: AlphaMode::Mask,
    alpha_cutoff: 0.5,
    double_sided: true,
    ..Default::default()
};
}

Textured materials

Loading textures

#![allow(unused)]
fn main() {
let texture_bytes = include_bytes!("../assets/wood.png");
let image = image::load_from_memory(texture_bytes).unwrap().to_rgba8();

world.queue_command(WorldCommand::LoadTexture {
    name: "wood".to_string(),
    rgba_data: image.to_vec(),
    width: image.width(),
    height: image.height(),
});
}

Full PBR texture set

#![allow(unused)]
fn main() {
let brick = Material {
    base_texture: Some("brick_color".to_string()),
    normal_texture: Some("brick_normal".to_string()),
    normal_scale: 1.0,
    metallic_roughness_texture: Some("brick_metallic_roughness".to_string()),
    occlusion_texture: Some("brick_ao".to_string()),
    roughness: 1.0,
    metallic: 1.0,
    ..Default::default()
};
}

When a metallic_roughness_texture is present, the scalar roughness and metallic values are multiplied with the texture's green and blue channels respectively. The scalars become per-material multipliers on top of the per-texel data.

UV scaling

Tile a texture by scaling UV coordinates.

#![allow(unused)]
fn main() {
let tiled = Material {
    base_texture: Some("tile".to_string()),
    uv_scale: [4.0, 4.0],
    ..Default::default()
};
}

DirectX normal maps

Some normal maps, including most output from Substance or older authoring tools, use a flipped Y channel.

#![allow(unused)]
fn main() {
let material = Material {
    normal_texture: Some("dx_normal".to_string()),
    normal_map_flip_y: true,
    ..Default::default()
};
}

For two-component normal maps (RG only, B reconstructed from RG):

#![allow(unused)]
fn main() {
let material = Material {
    normal_texture: Some("bc5_normal".to_string()),
    normal_map_two_component: true,
    ..Default::default()
};
}

Assigning materials to entities

#![allow(unused)]
fn main() {
material_registry_insert(
    &mut world.resources.material_registry,
    "my_material".to_string(),
    my_material,
);

if let Some(&index) = world.resources.material_registry.registry.name_to_index.get("my_material") {
    world.resources.material_registry.registry.add_reference(index);
}

world.core.set_material_ref(entity, MaterialRef::new("my_material"));
}

Procedural textures

Procedural textures are generated at runtime and uploaded the same way as any other texture.

#![allow(unused)]
fn main() {
fn create_checkerboard(size: usize) -> Vec<u8> {
    let mut data = vec![0u8; size * size * 4];

    for y in 0..size {
        for x in 0..size {
            let index = (y * size + x) * 4;
            let checker = ((x / 32) + (y / 32)) % 2 == 0;
            let value = if checker { 255 } else { 64 };
            data[index] = value;
            data[index + 1] = value;
            data[index + 2] = value;
            data[index + 3] = 255;
        }
    }

    data
}

let checkerboard = create_checkerboard(256);
world.queue_command(WorldCommand::LoadTexture {
    name: "checkerboard".to_string(),
    rgba_data: checkerboard,
    width: 256,
    height: 256,
});
}

Meshes & Models

Live Demo: Prefabs

Built-in primitives

The engine ships with a small set of basic geometric primitives.

#![allow(unused)]
fn main() {
use nightshade::prelude::*;

spawn_cube_at(world, Vec3::new(0.0, 1.0, 0.0));
spawn_sphere_at(world, Vec3::new(2.0, 1.0, 0.0));
spawn_plane_at(world, Vec3::zeros());
spawn_cylinder_at(world, Vec3::new(-2.0, 1.0, 0.0));
}

Loading glTF/GLB models

Basic loading

#![allow(unused)]
fn main() {
use nightshade::ecs::prefab::*;

const MODEL_BYTES: &[u8] = include_bytes!("../assets/character.glb");

fn load_model(world: &mut World) -> Option<Entity> {
    let result = import_gltf_from_bytes(MODEL_BYTES).ok()?;

    // Register textures
    for (name, (rgba_data, width, height)) in result.textures {
        world.queue_command(WorldCommand::LoadTexture {
            name,
            rgba_data,
            width,
            height,
        });
    }

    // Register meshes
    for (name, mesh) in result.meshes {
        mesh_cache_insert(&mut world.resources.mesh_cache, name, mesh);
    }

    // Spawn first prefab
    result.prefabs.first().map(|prefab| {
        spawn_prefab_with_skins(
            world,
            prefab,
            &result.animations,
            &result.skins,
            Vec3::zeros(),
        )
    })
}
}

With custom position/transform

#![allow(unused)]
fn main() {
fn spawn_model_at(world: &mut World, prefab: &Prefab, position: Vec3, scale: f32) -> Entity {
    let entity = spawn_prefab(world, prefab, position);

    if let Some(transform) = world.core.get_local_transform_mut(entity) {
        transform.scale = Vec3::new(scale, scale, scale);
    }

    entity
}
}

Filtered animation channels

A common preprocessing step is to remove root motion from animations so the gameplay code can drive the root transform itself.

#![allow(unused)]
fn main() {
let root_bone_indices: HashSet<usize> = [0, 1, 2, 3].into();

let filtered_animations: Vec<AnimationClip> = result
    .animations
    .iter()
    .map(|clip| AnimationClip {
        name: clip.name.clone(),
        duration: clip.duration,
        channels: clip
            .channels
            .iter()
            .filter(|channel| {
                // Skip translation on all bones
                if channel.target_property == AnimationProperty::Translation {
                    return false;
                }
                // Skip rotation on root bones
                if root_bone_indices.contains(&channel.target_node)
                    && channel.target_property == AnimationProperty::Rotation
                {
                    return false;
                }
                true
            })
            .cloned()
            .collect(),
    })
    .collect();
}

Manual mesh creation

Meshes can be built programmatically. The vertex format is fixed across the engine.

#![allow(unused)]
fn main() {
use nightshade::ecs::mesh::*;

let vertices = vec![
    Vertex {
        position: [0.0, 0.0, 0.0],
        normal: [0.0, 1.0, 0.0],
        tex_coords: [0.0, 0.0],
        ..Default::default()
    },
    Vertex {
        position: [1.0, 0.0, 0.0],
        normal: [0.0, 1.0, 0.0],
        tex_coords: [1.0, 0.0],
        ..Default::default()
    },
    Vertex {
        position: [0.5, 0.0, 1.0],
        normal: [0.0, 1.0, 0.0],
        tex_coords: [0.5, 1.0],
        ..Default::default()
    },
];

let indices = vec![0, 1, 2];

let mesh = Mesh {
    vertices,
    indices,
    ..Default::default()
};

mesh_cache_insert(&mut world.resources.mesh_cache, "triangle".to_string(), mesh);
}

Mesh component

Assigning a mesh to an entity is two writes plus the component mask.

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF,
    1
)[0];

world.core.set_render_mesh(entity, RenderMesh {
    name: "triangle".to_string(),
    id: None,
});

world.core.set_material_ref(entity, MaterialRef::new("default"));
}

Instanced meshes

For rendering many copies of the same mesh, the instanced path is one draw call instead of N.

#![allow(unused)]
fn main() {
world.core.set_instanced_mesh(entity, InstancedMesh {
    mesh_name: "tree".to_string(),
    instance_count: 1000,
    instance_data: instance_transforms,
});
}

Mesh cache

The cache is keyed by name and shared across the whole world.

#![allow(unused)]
fn main() {
// Check if mesh exists
if world.resources.mesh_cache.contains("cube") {
    // Mesh is available
}

// Get mesh data (for physics, etc.)
if let Some(mesh) = world.resources.mesh_cache.get("terrain") {
    let vertices: Vec<Vec3> = mesh.vertices.iter()
        .map(|v| Vec3::new(v.position[0], v.position[1], v.position[2]))
        .collect();
}
}

Skinned meshes

For animated characters with a skeleton, spawn through the skin-aware path.

#![allow(unused)]
fn main() {
let entity = spawn_prefab_with_skins(
    world,
    &prefab,
    &animations,
    &skins,
    position,
);

// The entity will have Skin and AnimationPlayer components
if let Some(player) = world.core.get_animation_player_mut(entity) {
    player.playing = true;
    player.looping = true;
}
}

Shadow casting

Whether a mesh casts shadows is controlled by the CASTS_SHADOW component.

#![allow(unused)]
fn main() {
// Enable shadow casting
world.core.add_components(entity, CASTS_SHADOW);
world.core.set_casts_shadow(entity, CastsShadow);

// Disable shadow casting (for UI elements, etc.)
world.core.remove_components(entity, CASTS_SHADOW);
}

Lighting

Live Demos: Lights | Shadows | Spotlight Shadows

Nightshade supports three types of lights: directional, point, and spot.

Light types

Directional light (sun)

A directional light illuminates the entire scene from a single direction. It is the standard way to model distant light sources like the sun, where the rays are effectively parallel.

#![allow(unused)]
fn main() {
use nightshade::prelude::*;

let sun = spawn_sun(world);
}

spawn_sun returns the Entity for the directional light. The light can be reconfigured at any time.

#![allow(unused)]
fn main() {
if let Some(light) = world.core.get_light_mut(sun) {
    light.color = Vec3::new(1.0, 0.98, 0.95);
    light.intensity = 2.0;
}
}

Point light

A point light emits in all directions from a single position.

#![allow(unused)]
fn main() {
fn create_point_light(world: &mut World, position: Vec3, color: Vec3, intensity: f32) -> Entity {
    let entity = world.spawn_entities(
        LIGHT | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
        1
    )[0];

    world.core.set_light(entity, Light {
        light_type: LightType::Point,
        color,
        intensity,
        range: 10.0,
        cast_shadows: false,
        ..Default::default()
    });

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        ..Default::default()
    });

    entity
}
}

Spot light

A spot light is a cone-shaped emitter. Flashlights, stage lighting, and headlights all fit this model.

#![allow(unused)]
fn main() {
fn create_spotlight(world: &mut World, position: Vec3, direction: Vec3) -> Entity {
    let entity = world.spawn_entities(
        LIGHT | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
        1
    )[0];

    world.core.set_light(entity, Light {
        light_type: LightType::Spot,
        color: Vec3::new(1.0, 0.95, 0.9),
        intensity: 15.0,
        range: 20.0,
        inner_cone_angle: 0.2,  // Full intensity cone
        outer_cone_angle: 0.5,  // Falloff cone
        cast_shadows: true,
        shadow_bias: 0.002,
    });

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        rotation: nalgebra_glm::quat_look_at(&direction.normalize(), &Vec3::y()),
        ..Default::default()
    });

    entity
}
}

Light properties

Dynamic lighting

Flickering light

A flickering fire or torch effect is three out-of-phase sine waves summed onto a base intensity.

#![allow(unused)]
fn main() {
fn update_flickering_light(world: &mut World, light_entity: Entity) {
    let time = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;

    if let Some(light) = world.core.get_light_mut(light_entity) {
        let flicker1 = (time * 8.0).sin() * 0.15;
        let flicker2 = (time * 12.5).sin() * 0.1;
        let flicker3 = (time * 23.0).sin() * 0.08;

        let base_intensity = 3.5;
        light.intensity = base_intensity + flicker1 + flicker2 + flicker3;
    }
}
}

Color cycling

Three phase-offset sines on the RGB channels cycle through the color wheel.

#![allow(unused)]
fn main() {
fn update_disco_light(world: &mut World, light_entity: Entity) {
    let time = world.resources.window.timing.uptime_milliseconds as f32 / 1000.0;

    if let Some(light) = world.core.get_light_mut(light_entity) {
        light.color = Vec3::new(
            (time * 2.0).sin() * 0.5 + 0.5,
            (time * 2.0 + 2.094).sin() * 0.5 + 0.5,
            (time * 2.0 + 4.188).sin() * 0.5 + 0.5,
        );
    }
}
}

Flashlight (camera-attached spotlight)

A flashlight is a spotlight whose transform tracks the active camera every frame.

#![allow(unused)]
fn main() {
fn update_flashlight(world: &mut World, flashlight: Entity) {
    let Some(camera) = world.resources.active_camera else { return };
    let Some(camera_transform) = world.core.get_global_transform(camera) else { return };

    let position = camera_transform.translation();
    let forward = camera_transform.forward_vector();

    if let Some(transform) = world.core.get_local_transform_mut(flashlight) {
        transform.translation = position;
        transform.rotation = nalgebra_glm::quat_look_at(&forward, &Vec3::y());
    }
    mark_local_transform_dirty(world, flashlight);
}
}

How lighting works

Nightshade uses a clustered forward rendering pipeline. The view frustum is divided into a 16x9x24 grid of clusters. A compute shader assigns each light to the clusters it overlaps, producing a per-cluster light list with a cap of 256 lights per cluster. During the mesh pass, each fragment looks up its cluster and only evaluates the lights assigned to it. The cost is bounded by the lights that actually reach the pixel rather than the total light count in the scene.

PBR lighting model

All lights are evaluated using the Cook-Torrance microfacet BRDF. The model has three parts.

The Normal Distribution Function (D) is Trowbridge-Reitz GGX. It models the statistical distribution of microfacet orientations. The squared roughness parameter (a = roughness * roughness) controls how concentrated the specular highlight is.

The Geometry Function (G) is the Schlick-Beckmann approximation combined with Smith's method. It accounts for self-shadowing between microfacets. Two terms get combined, one for the view direction and one for the light direction.

The Fresnel term (F) is Schlick's approximation. It computes how reflectivity changes with viewing angle. For dielectrics, F0 is derived from the index of refraction. For metals, F0 equals the base color.

The final light contribution per light is:

(kD * albedo / PI + specular) * radiance * NdotL

where kD = (1 - F) * (1 - metallic) ensures metals have no diffuse component.

Image-based lighting

Ambient lighting comes from two pre-computed cubemaps. The irradiance map is a pre-convolved diffuse environment, sampled in the surface normal direction. The prefiltered environment map is five mip levels of increasingly blurred specular reflections, sampled in the reflection direction at a mip level chosen by roughness.

A 2D BRDF lookup texture (the split-sum approximation) combines with the prefiltered map to produce the final specular IBL contribution.

Atmosphere

Set the sky rendering mode.

#![allow(unused)]
fn main() {
world.resources.graphics.atmosphere = Atmosphere::Sky;
}

Multiple lights

Nightshade supports many lights in a scene. Combine the spawn helpers above to build out an environment.

#![allow(unused)]
fn main() {
fn setup_lighting(world: &mut World) {
    spawn_sun(world);

    create_point_light(world, Vec3::new(5.0, 3.0, 5.0), Vec3::new(0.8, 0.9, 1.0), 2.0);
    create_point_light(world, Vec3::new(-5.0, 3.0, -5.0), Vec3::new(1.0, 0.8, 0.7), 1.5);

    create_spotlight(world, Vec3::new(0.0, 5.0, 0.0), Vec3::new(0.0, -1.0, 0.0));
}
}

Textures & the Texture Cache

Nightshade manages GPU textures through a centralized TextureCache with generational indexing and reference counting. Textures can be loaded synchronously from bytes, asynchronously from disk or HTTP, or generated procedurally at runtime.

Texture cache

The TextureCache stores every loaded texture as a TextureEntry (a wgpu texture plus its view plus its sampler) in a GenerationalRegistry. Each texture is identified by a TextureId containing an index and a generation counter. Stale references are detected because the generation increments when a slot is recycled, so an old TextureId will not match the slot's current contents.

Loading textures

The most common way to load a texture is through WorldCommand::LoadTexture.

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::LoadTexture {
    name: "my_texture".to_string(),
    rgba_data: image_bytes,
    width: 512,
    height: 512,
});
}

The renderer drains the command queue, uploads the RGBA data to the GPU, and stores the texture in the cache under the given name.

Procedural textures

The engine provides three built-in procedural textures loaded at startup via load_procedural_textures().

#![allow(unused)]
fn main() {
load_procedural_textures(world);
}

Looking up textures

Find a loaded texture by name.

#![allow(unused)]
fn main() {
let texture_id = texture_cache_lookup_id(&cache, "my_texture");
}

Reference counting

Textures use reference counting for lifecycle management. The cache will not free a texture until every holder has released it.

#![allow(unused)]
fn main() {
texture_cache_add_reference(&mut cache, "my_texture");
texture_cache_remove_reference(&mut cache, "my_texture");
texture_cache_remove_unused(&mut cache);
}

When a texture's reference count reaches zero, texture_cache_remove_unused() frees it.

Dummy textures

If a texture is missing, texture_cache_ensure_dummy() creates a 64x64 purple-and-black checkerboard placeholder. The fallback keeps the renderer from erroring out and makes missing assets obvious in the viewport.

Async texture loading

For loading textures without blocking the main thread, use the TextureLoadQueue system.

Setup

#![allow(unused)]
fn main() {
use nightshade::ecs::texture_loader::*;

struct MyState {
    queue: SharedTextureQueue,
    loading_state: AssetLoadingState,
}

fn initialize(&mut self, world: &mut World) {
    self.queue = create_shared_queue();

    queue_texture_from_path(&self.queue, "assets/textures/albedo.png");
    queue_texture_from_path(&self.queue, "assets/textures/normal.png");

    self.loading_state = AssetLoadingState::new(2);
}
}

Processing each frame

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    let status = process_and_load_textures(
        &self.queue,
        world,
        &mut self.loading_state,
        4,
    );

    if status == AssetLoadingStatus::Complete {
        // All textures loaded
    }
}
}

Loading progress

Track progress for a loading screen.

#![allow(unused)]
fn main() {
let progress = self.loading_state.progress(); // 0.0 to 1.0
let is_done = self.loading_state.is_complete();
let loaded = self.loading_state.loaded_textures;
let failed = self.loading_state.failed_textures;
}

Platform behavior

Asset search paths

Configure the directories where texture files are searched.

#![allow(unused)]
fn main() {
set_asset_search_paths(vec![
    "assets/".to_string(),
    "content/textures/".to_string(),
]);

queue_texture_from_path(&queue, "player.png");
// Searches: assets/player.png, content/textures/player.png
}

Material textures

PBR materials reference textures by name through MaterialRef.

#![allow(unused)]
fn main() {
let material = Material {
    base_texture: Some("albedo".to_string()),
    normal_texture: Some("normal_map".to_string()),
    metallic_roughness_texture: Some("metallic_roughness".to_string()),
    ..Default::default()
};
}

See Materials for the full PBR material workflow.

Decals

Live Demo: Decals

A decal is a texture projected onto scene geometry using the depth buffer. Decals cover bullet holes, blood splatters, footprints, scorch marks, and environmental details without modifying the underlying mesh. The geometry stays static and the decal layer is purely cosmetic.

How decal rendering works

Each decal is drawn as a unit cube positioned and oriented in world space. The fragment shader reconstructs the world position of the scene geometry behind the cube by sampling the depth buffer, then transforms that position into the decal's local space using the inverse model matrix. If the reconstructed point falls inside the decal's projection volume (plus or minus 1 in XY, 0 to depth in Z), the decal texture is sampled at those local XY coordinates and blended onto the scene.

The normal threshold test compares the scene surface normal (computed from depth buffer gradients) against the decal's forward direction. Surfaces angled past the threshold are rejected. The result is that decals stop projecting around sharp edges instead of wrapping over them like a sticker.

Distance fade is a smoothstep between fade_start and fade_end based on the camera-to-decal distance. Far decals fade out cheaply and stay culled rather than producing aliased projections at long range.

Decal component

#![allow(unused)]
fn main() {
pub struct Decal {
    pub texture: Option<String>,
    pub emissive_texture: Option<String>,
    pub emissive_strength: f32,
    pub color: [f32; 4],
    pub size: Vec2,
    pub depth: f32,
    pub normal_threshold: f32,
    pub fade_start: f32,
    pub fade_end: f32,
}
}

Spawning decals

#![allow(unused)]
fn main() {
fn spawn_bullet_hole(world: &mut World, position: Vec3, normal: Vec3) -> Entity {
    let entity = world.spawn_entities(
        LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | DECAL,
        1
    )[0];

    let rotation = nalgebra_glm::quat_look_at(&normal, &Vec3::y());

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        rotation,
        ..Default::default()
    });

    world.core.set_decal(entity, Decal::new("bullet_hole")
        .with_size(0.2, 0.2)
        .with_depth(0.1)
        .with_normal_threshold(0.5)
        .with_fade(20.0, 30.0));

    entity
}
}

Builder API

The Decal struct supports a builder pattern for chained configuration.

#![allow(unused)]
fn main() {
let decal = Decal::new("texture_name")
    .with_size(0.5, 0.5)
    .with_depth(0.2)
    .with_color([1.0, 0.0, 0.0, 1.0])
    .with_normal_threshold(0.3)
    .with_fade(30.0, 50.0)
    .with_emissive("rune_glow", 3.0);
}

Common use cases

Blood splatter

#![allow(unused)]
fn main() {
fn spawn_blood(world: &mut World, position: Vec3, normal: Vec3) -> Entity {
    let entity = world.spawn_entities(
        LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | DECAL,
        1
    )[0];

    let rotation = nalgebra_glm::quat_look_at(&normal, &Vec3::y());
    let random_angle = rand::random::<f32>() * std::f32::consts::TAU;
    let rotation = rotation * nalgebra_glm::quat_angle_axis(random_angle, &Vec3::z());

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        rotation,
        ..Default::default()
    });

    world.core.set_decal(entity, Decal::new("blood")
        .with_size(0.8, 0.8)
        .with_depth(0.1)
        .with_normal_threshold(0.3)
        .with_fade(30.0, 50.0));

    entity
}
}

Emissive rune

#![allow(unused)]
fn main() {
fn spawn_magic_rune(world: &mut World, position: Vec3) -> Entity {
    let entity = world.spawn_entities(
        LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | DECAL,
        1
    )[0];

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        rotation: nalgebra_glm::quat_angle_axis(
            -std::f32::consts::FRAC_PI_2,
            &Vec3::x(),
        ),
        ..Default::default()
    });

    world.core.set_decal(entity, Decal::new("rune")
        .with_size(2.0, 2.0)
        .with_depth(0.5)
        .with_normal_threshold(0.7)
        .with_fade(50.0, 80.0)
        .with_emissive("rune_glow", 3.0));

    entity
}
}

Footprints

#![allow(unused)]
fn main() {
fn spawn_footprint(world: &mut World, position: Vec3, direction: Vec3, left: bool) -> Entity {
    let entity = world.spawn_entities(
        LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | DECAL,
        1
    )[0];

    let rotation = nalgebra_glm::quat_look_at(&Vec3::y(), &direction);
    let flip = if left { 1.0 } else { -1.0 };

    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        rotation,
        scale: Vec3::new(flip, 1.0, 1.0),
    });

    world.core.set_decal(entity, Decal::new("footprint")
        .with_size(0.15, 0.3)
        .with_depth(0.05)
        .with_normal_threshold(0.8)
        .with_fade(15.0, 25.0));

    entity
}
}

Physics Overview

Live Demo: Physics

Physics in nightshade is Rapier3D wrapped in ECS components. The engine owns the RigidBodySet, ColliderSet, and ImpulseJointSet on a single PhysicsResources struct, and runs the simulation at a fixed timestep on the frame schedule. Components on entities (RigidBodyComponent, ColliderComponent, CharacterControllerComponent) hold the parameters and the Rapier handles. Transforms sync into Rapier before the step and back out after.

Enabling Physics

The physics feature flag pulls in Rapier3D and the components that drive it.

[dependencies]
nightshade = { git = "...", features = ["engine", "physics"] }

Physics World

The physics world is a resource on world.resources.physics. Configuration sits on the same struct.

#![allow(unused)]
fn main() {
let physics = &mut world.resources.physics;

physics.gravity = Vec3::new(0.0, -9.81, 0.0);
physics.fixed_timestep = 1.0 / 60.0;
}

Gravity is a vector, not a magnitude, so a top-down game can set it to zero and a side-scroller can rotate it. The fixed timestep is the rate the simulation actually steps at. 60 Hz is the default and what most demos assume.

Core Concepts

Rigid Bodies

A rigid body is the dynamic state Rapier integrates each step. There are three kinds.

• Dynamic. Mass and inertia tensor, integrated under gravity and applied forces.
• Kinematic. Position is set by code each frame, dynamic bodies see it as an immovable wall that happens to move.
• Fixed. Infinite mass, never moves. Floors, walls, terrain.

Colliders

A collider is the shape Rapier uses for contact and intersection tests. Shapes available are Ball, Cuboid, Capsule, Cylinder, Cone, TriMesh, HeightField, and compound combinations.

Character Controllers

A character controller is a kinematic body with a small state machine on top that resolves contacts itself instead of letting the constraint solver do it. The result is movement that respects walls but does not get pushed around by stacked boxes.

Quick Start

#![allow(unused)]
fn main() {
use nightshade::ecs::physics::*;

fn initialize(&mut self, world: &mut World) {
    spawn_cube_at(world, Vec3::new(0.0, -0.5, 0.0));

    for index in 0..10 {
        spawn_cube_at(world, Vec3::new(0.0, 2.0 + index as f32 * 1.5, 0.0));
    }
}
}

The floor is one fixed cube. The stack is ten dynamic cubes spawned at increasing height. The physics schedule does the rest.

Physics Synchronization

The simulation runs at the fixed timestep, the renderer runs at the display rate, and the two are not the same. Each frame works like this:

1. Game logic mutates entity transforms.
2. The physics step runs zero or more times depending on how much real time has passed since the last step.
3. Rapier writes the new positions and orientations back into the entity transforms.
4. Interpolation between the previous and current physics positions smooths the visual.

The interpolation step is what hides the discrete simulation rate from the eye. Without it, fast-moving bodies appear to stutter at 60 Hz regardless of the frame rate.

Querying Physics

Picking (Raycasting)

Picking casts a ray from the cursor pixel into the world and returns the closest hit.

#![allow(unused)]
fn main() {
let (width, height) = world.resources.window.cached_viewport_size.unwrap_or((800, 600));
let screen_center = Vec2::new(width as f32 / 2.0, height as f32 / 2.0);

if let Some(hit) = pick_closest_entity(world, screen_center) {
    let hit_entity = hit.entity;
    let hit_distance = hit.distance;
    let hit_position = hit.world_position;
}
}

pick_closest_entity hits the bounding volume of each candidate. That is fast enough to run every frame for hover and selection, and inaccurate enough that the hit point can be off the actual surface by the radius of the bounding sphere.

For per-triangle accuracy, use the trimesh variant.

#![allow(unused)]
fn main() {
if let Some(hit) = pick_closest_entity_trimesh(world, screen_center) {
    let hit_entity = hit.entity;
    let hit_position = hit.world_position;
}
}

The trimesh path is slower per pick but lands on the actual mesh. Use it when the hit point matters, like for decal placement or precise interaction.

Physics Materials

Friction, restitution, and density live directly on ColliderComponent. There is no separate material asset.

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.5)
    .with_restitution(0.3)
    .with_density(1.0));
}

Friction controls sliding resistance, restitution controls bounciness, density combines with shape volume to give the body its mass.

Debug Visualization

The debug draw flag dumps collider shapes, contact points, and collision normals as line geometry.

#![allow(unused)]
fn main() {
world.resources.physics.debug_draw = true;

physics_debug_draw_system(world);
}

Useful while building levels to see where collision actually is versus where the visual mesh sits. The two diverge more than you would expect.

Performance Tips

Five things move the needle, roughly in this order.

1. Use primitive shapes (boxes, spheres, capsules) wherever possible. Trimesh collision is an order of magnitude slower per pair.
2. Filter collision groups so unrelated objects do not even broadphase against each other.
3. Combine shapes into compound colliders on one body instead of parenting many small bodies.
4. Let idle bodies sleep. Rapier does this automatically when linear and angular velocity stay below a threshold for long enough.
5. Keep the fixed timestep at 60 Hz unless something specifically needs more.

Joints

Joints constrain the relative motion of two bodies. Doors are revolute joints, drawers are prismatic, ropes are rope joints, chains are spherical. See Physics Joints for the full set.

Rigid Bodies

A rigid body is the chunk of state Rapier integrates each step. Position, orientation, linear and angular velocity, mass, the inertia tensor. The body type controls how it responds to forces. The collider attached to it controls what it collides with.

Body Types

Dynamic Bodies

Dynamic bodies are fully simulated. Gravity, applied forces, impulses, contacts all push them around.

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RIGID_BODY | COLLIDER,
    1
)[0];

world.core.set_rigid_body(entity, RigidBodyComponent::new_dynamic());

world.core.set_collider(entity, ColliderComponent::new_ball(0.5));
}

Use dynamic for physics props, ragdolls, anything that should react to the world.

Kinematic Bodies

Kinematic bodies move by code, not by the integrator. Other dynamic bodies treat them as immovable walls, but the kinematic body itself ignores collision response.

#![allow(unused)]
fn main() {
world.core.set_rigid_body(entity, RigidBodyComponent::new_kinematic());
}

Drive a kinematic body by writing its transform directly each frame.

#![allow(unused)]
fn main() {
if let Some(transform) = world.core.get_local_transform_mut(kinematic_entity) {
    transform.translation.x += velocity.x * dt;
}
mark_local_transform_dirty(world, kinematic_entity);
}

The mark_local_transform_dirty call is required. Without it the transform sync system does not know the transform changed and the body will not move in Rapier.

Static Bodies

Static bodies never move. Floors, walls, environment geometry. Infinite mass, no integration cost.

#![allow(unused)]
fn main() {
world.core.set_rigid_body(entity, RigidBodyComponent::new_static());
}

Helper Functions

The physics module ships two helpers for the common case of spawning a dynamic primitive with a matching collider.

Spawning Physics Cubes

#![allow(unused)]
fn main() {
use nightshade::ecs::physics::*;

let cube = spawn_cube_at(world, Vec3::new(0.0, 5.0, 0.0));
}

Spawning Physics Spheres

#![allow(unused)]
fn main() {
let sphere = spawn_sphere_at(world, Vec3::new(0.0, 10.0, 0.0));
}

Both spawn a dynamic body with a unit-sized collider. Use the longer form when you need a custom size or material.

Applying Forces

Forces and impulses are not exposed through the component directly. Reach into Rapier through the handle on RigidBodyComponent.

#![allow(unused)]
fn main() {
fn apply_force(world: &mut World, entity: Entity, force: Vec3) {
    let Some(rb_component) = world.core.get_rigid_body(entity) else { return };
    let Some(handle) = rb_component.handle else { return };

    if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
        rigid_body.add_force(
            rapier3d::prelude::Vector::new(force.x, force.y, force.z),
            true,
        );
    }
}
}

The boolean is the wake flag. Sleeping bodies ignore forces unless explicitly woken, which is almost always what you want when applying force.

Applying Impulses

An impulse is an instantaneous change in velocity. Use it for explosions, jumps, hit reactions, anything that should not integrate over time.

#![allow(unused)]
fn main() {
fn apply_impulse(world: &mut World, entity: Entity, impulse: Vec3) {
    let Some(rb_component) = world.core.get_rigid_body(entity) else { return };
    let Some(handle) = rb_component.handle else { return };

    if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
        rigid_body.apply_impulse(
            rapier3d::prelude::Vector::new(impulse.x, impulse.y, impulse.z),
            true,
        );
    }
}
}

The difference from a force is units. Force is mass times acceleration, applied over the timestep. Impulse is mass times velocity, applied all at once.

Setting Velocity

#![allow(unused)]
fn main() {
fn set_velocity(world: &mut World, entity: Entity, velocity: Vec3) {
    let Some(rb_component) = world.core.get_rigid_body(entity) else { return };
    let Some(handle) = rb_component.handle else { return };

    if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
        rigid_body.set_linvel(
            rapier3d::prelude::Vector::new(velocity.x, velocity.y, velocity.z),
            true,
        );
    }
}
}

Setting velocity directly stomps whatever Rapier had. Useful for snapping a character to a target speed. Forces and impulses are better when you want the body to ease into motion.

Getting Velocity

#![allow(unused)]
fn main() {
fn get_velocity(world: &World, entity: Entity) -> Option<Vec3> {
    let rb_component = world.core.get_rigid_body(entity)?;
    let handle = rb_component.handle?;
    let rigid_body = world.resources.physics.rigid_body_set.get(handle.into())?;

    let vel = rigid_body.linvel();
    Some(Vec3::new(vel.x, vel.y, vel.z))
}
}

Mass Properties

#![allow(unused)]
fn main() {
fn set_mass(world: &mut World, entity: Entity, mass: f32) {
    let Some(rb_component) = world.core.get_rigid_body(entity) else { return };
    let Some(handle) = rb_component.handle else { return };

    if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
        rigid_body.set_additional_mass(mass, true);
    }
}
}

set_additional_mass adds to the mass Rapier computed from the collider's density and volume. Use density on the collider for typical materials. Use this for things like a hat that should not change the wearer's inertia.

Locking Axes

Some bodies should not be free to rotate or translate on every axis. A first-person character should not tip over. A 2.5D platformer body should not drift on Z.

#![allow(unused)]
fn main() {
if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
    rigid_body.lock_rotations(true, true);

    // rigid_body.lock_translations(true, true);
}
}

Damping

Damping is the air-drag-style velocity decay applied each step.

#![allow(unused)]
fn main() {
if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
    rigid_body.set_linear_damping(0.5);
    rigid_body.set_angular_damping(0.5);
}
}

Linear damping bleeds off translation, angular damping bleeds off spin. Values around 0.5 to 2.0 give a noticeable "thick air" feel. Zero is vacuum.

Sleeping

Rapier puts bodies to sleep when their velocity stays under a threshold for long enough. Sleeping bodies skip integration entirely. Wake them when you want them to react to something that does not generate a contact, like a teleport or a manual velocity change.

#![allow(unused)]
fn main() {
if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
    rigid_body.wake_up(true);
}
}

Colliders

A collider is the shape Rapier uses for contact detection. It is separate from the visual mesh, and the two should usually disagree. Visual meshes have thousands of triangles. Colliders are the simplest shape that approximates the visual closely enough.

Collider Shapes

Ball (Sphere)

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_ball(0.5));
}

Cheapest shape. A single radius and a position. Use it for projectiles, simple props, and anything that can roll without looking wrong.

Cuboid (Box)

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_cuboid(1.0, 0.5, 1.0));
}

The three arguments are half-extents, not full widths. The cuboid above is 2 by 1 by 2 meters.

Capsule

A capsule is a cylinder with hemispheres on both ends. The hemispheres prevent the character from snagging on small steps and crease lines, which a flat-bottomed cylinder is prone to do.

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_capsule(1.0, 0.3));
}

Cylinder

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent {
    shape: ColliderShape::Cylinder {
        half_height: 1.0,
        radius: 0.5,
    },
    ..Default::default()
});
}

Cylinders make good barrels and pillars. They are more expensive than boxes at contact time.

Cone

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent {
    shape: ColliderShape::Cone {
        half_height: 1.0,
        radius: 0.5,
    },
    ..Default::default()
});
}

Triangle Mesh

Triangle mesh is the escape hatch for static geometry that does not fit a primitive shape.

#![allow(unused)]
fn main() {
let vertices: Vec<[f32; 3]> = mesh.vertices.iter()
    .map(|v| v.position)
    .collect();

let indices: Vec<[u32; 3]> = mesh.indices
    .chunks(3)
    .map(|c| [c[0], c[1], c[2]])
    .collect();

world.core.set_collider(entity, ColliderComponent {
    shape: ColliderShape::TriMesh { vertices, indices },
    ..Default::default()
});
}

Rapier builds a BVH over the triangles on insert, so the construction cost is real but one-time. Use trimesh on static bodies only. Dynamic bodies with trimesh colliders run into the limitation that Rapier cannot compute mass properties from a non-closed mesh, and contact resolution between two trimesh dynamic bodies is not well-defined.

Heightfield

A heightfield is a grid of height samples. It is the right shape for terrain.

#![allow(unused)]
fn main() {
let heights: Vec<f32> = generate_height_grid(64, 64);

world.core.set_collider(entity, ColliderComponent {
    shape: ColliderShape::HeightField {
        nrows: 64,
        ncols: 64,
        heights,
        scale: [100.0, 50.0, 100.0],
    },
    ..Default::default()
});
}

The scale vector is [x, height, z]. The grid above covers a 100 by 100 meter area with vertical scale 50.

Compound

Compound colliders are multiple shapes attached to one body. Cheaper than parenting multiple bodies and keeps the mass properties coherent.

#![allow(unused)]
fn main() {
let body_collider = ColliderComponent::new_cuboid(0.5, 0.1, 0.5);
let head_collider = ColliderComponent::new_ball(0.3);
}

Physics Materials

Friction, restitution, and density are fields on ColliderComponent itself.

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.5)
    .with_restitution(0.3)
    .with_density(1.0));
}

Friction is the sliding-resistance coefficient. 0 is frictionless, 1 is sticky. Restitution is the bounce coefficient. 0 absorbs impact, 1 returns it perfectly. Density is mass per unit volume. Rapier computes the body's mass from collider density and shape volume at insertion.

Material Examples

#![allow(unused)]
fn main() {
let ice = ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.05)
    .with_restitution(0.1)
    .with_density(0.9);

let rubber = ColliderComponent::new_ball(0.5)
    .with_friction(0.9)
    .with_restitution(0.8)
    .with_density(1.1);

let metal = ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.4)
    .with_restitution(0.2)
    .with_density(7.8);
}

Density 7.8 for metal is realistic (steel). Density 1.0 is water. These values matter for the mass ratio between bodies in contact, which controls how much each one moves on collision.

Collision Groups

Collision groups filter which pairs of colliders are even considered for contact testing. A player should not collide with the projectiles it fired. Enemy AI should not interpenetrate.

#![allow(unused)]
fn main() {
use rapier3d::prelude::*;

const GROUP_PLAYER: Group = Group::GROUP_1;
const GROUP_ENEMY: Group = Group::GROUP_2;
const GROUP_PROJECTILE: Group = Group::GROUP_3;
const GROUP_WORLD: Group = Group::GROUP_4;

let player_filter = CollisionGroups::new(
    GROUP_PLAYER,
    GROUP_ENEMY | GROUP_WORLD,
);
}

The first arg is the group this collider belongs to. The second is the bitmask of groups it collides with. A pair collides only if each side's membership intersects the other side's filter.

Sensor Colliders

A sensor reports overlap without applying contact response. Trigger volumes, damage zones, pickup proximity.

#![allow(unused)]
fn main() {
if let Some(collider) = world.resources.physics.collider_set.get_mut(handle.into()) {
    collider.set_sensor(true);
}
}

Sensor pairs come through the collision event stream alongside regular contacts, distinguished by the is_sensor flag.

Collision Events

Rapier queues collision events each step. The engine surfaces them on world.resources.physics.collision_events(), returning a &[CollisionEvent] slice.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    for event in world.resources.physics.collision_events() {
        match event.kind {
            CollisionEventKind::Started => {
                handle_collision_start(event.entity_a, event.entity_b);
            }
            CollisionEventKind::Stopped => {
                handle_collision_end(event.entity_a, event.entity_b);
            }
        }
    }
}
}

Each event carries the two entities, the kind (Started or Stopped), and the sensor flag.

#![allow(unused)]
fn main() {
pub struct CollisionEvent {
    pub entity_a: Entity,
    pub entity_b: Entity,
    pub kind: CollisionEventKind,
    pub is_sensor: bool,
}
}

Convex Decomposition

For dynamic bodies that need to approximate a concave shape, convex decomposition breaks the mesh into a set of convex pieces and attaches them as a compound collider.

#![allow(unused)]
fn main() {
use rapier3d::prelude::*;

let decomposed = SharedShape::convex_decomposition(&vertices, &indices);
}

The result is more expensive than a single primitive but works as a dynamic collider, which a trimesh cannot.

Performance Tips

Primitives are always cheaper than meshes. Trimesh is for static collision only. Compound on one body beats many small entities connected by joints. The collision mesh almost always wants to be simpler than the visual mesh.

Character Controllers

A character controller is a kinematic body with a custom contact resolver on top. The constraint solver is what makes a stack of boxes stable, and it is also what makes a player character feel mushy when standing on those boxes. Character controllers bypass it. Movement happens in code, contacts are resolved by sweeping and sliding the capsule against the world, and the result is movement that snaps to walls without bouncing off them.

First-Person Player

The fastest way to get a working player is spawn_first_person_player. It creates the controller entity, a child camera at eye height, and wires up input.

#![allow(unused)]
fn main() {
use nightshade::ecs::physics::commands::spawn_first_person_player;
use nightshade::ecs::physics::character_controller::character_controller_input_system;

fn initialize(&mut self, world: &mut World) {
    let (player_entity, camera_entity) = spawn_first_person_player(
        world,
        Vec3::new(0.0, 2.0, 0.0),
    );

    self.player = Some(player_entity);

    if let Some(controller) = world.core.get_character_controller_mut(player_entity) {
        controller.max_speed = 5.0;
        controller.is_sprinting = false;
        controller.jump_impulse = 6.0;
    }
}
}

max_speed is in meters per second. jump_impulse is the instantaneous upward velocity applied when the jump input fires.

Custom Character Controller

For third-person, NPCs, or anything that needs custom dimensions, build the entity by hand.

#![allow(unused)]
fn main() {
fn spawn_character(world: &mut World, position: Vec3) -> Entity {
    let entity = world.spawn_entities(
        NAME | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | CHARACTER_CONTROLLER,
        1,
    )[0];

    world.core.set_name(entity, Name("Player".to_string()));
    world.core.set_local_transform(entity, LocalTransform {
        translation: position,
        ..Default::default()
    });

    if let Some(controller) = world.core.get_character_controller_mut(entity) {
        *controller = CharacterControllerComponent::new_capsule(0.5, 0.3);
        controller.max_speed = 3.0;
        controller.acceleration = 15.0;
        controller.jump_impulse = 4.0;
        controller.is_sprinting = false;
        controller.is_crouching = false;
    }

    entity
}
}

new_capsule(0.5, 0.3) is half-height 0.5 and radius 0.3. The full character is 1 meter tall and 0.6 meters wide, roughly humanoid proportions.

Controller Properties

Movement Input

The built-in character_controller_input_system(world) reads WASD, space, shift, and control, and writes the resulting motion into the controller each frame. Call it from run_systems.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    character_controller_input_system(world);
}
}

Skip this call and the controller will only move when something else writes to it. That is the right choice when input comes from a network packet or an AI script.

Ground Detection

The controller flags whether the capsule is currently in contact with a surface below it.

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller(player) {
    if controller.grounded {
        // On ground - can jump
    } else {
        // In air
    }
}
}

Use this for jump gating, footstep timing, and switching between ground and air movement.

Slope Handling

The controller has two slope angles. Anything below max_slope_climb_angle is walkable. Anything above min_slope_slide_angle will slide the character down. Values are radians.

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller_mut(player) {
    controller.config.max_slope_climb_angle = 0.8;
    controller.config.min_slope_slide_angle = 0.5;
}
}

0.8 rad is about 45 degrees. 0.5 rad is about 30 degrees. Tune for the world's geometry.

Camera Integration

First-Person Camera

The camera is a child entity of the player, offset to eye height.

#![allow(unused)]
fn main() {
let camera = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | CAMERA | PARENT,
    1
)[0];

world.core.set_parent(camera, Parent(Some(player)));
world.core.set_local_transform(camera, LocalTransform {
    translation: Vec3::new(0.0, 0.8, 0.0),
    ..Default::default()
});

world.resources.active_camera = Some(camera);
}

Parenting means the transform hierarchy handles position. Mouse look writes to the camera's local rotation, body rotation goes on the player.

Third-Person Camera

Third-person follows the character with an offset and looks at a target point on or near the body.

#![allow(unused)]
fn main() {
fn third_person_camera_system(world: &mut World, player: Entity, camera: Entity) {
    let Some(player_pos) = world.core.get_local_transform(player).map(|t| t.translation) else {
        return;
    };

    let offset = Vec3::new(0.0, 3.0, 8.0);
    let target_pos = player_pos + offset;

    if let Some(pan_orbit) = world.core.get_pan_orbit_camera_mut(camera) {
        pan_orbit.target_focus = player_pos + Vec3::new(0.0, 1.0, 0.0);
    }
}
}

Step Climbing

Automatic step climbing lets the controller walk over small ledges without jumping. The two parameters bound what counts as a step.

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller_mut(player) {
    controller.config.autostep_max_height = Some(0.3);
    controller.config.autostep_min_width = Some(0.2);
}
}

30 cm is roughly a typical stair height. Anything taller than autostep_max_height is treated as a wall.

Interaction Cooldowns

Player actions that fire on a button press need cooldowns so a long key press does not fire the action every frame.

#![allow(unused)]
fn main() {
struct PlayerState {
    interaction_cooldown: f32,
}

fn update_cooldown(state: &mut PlayerState, dt: f32) {
    state.interaction_cooldown = (state.interaction_cooldown - dt).max(0.0);
}

fn can_interact(state: &PlayerState) -> bool {
    state.interaction_cooldown <= 0.0
}

fn set_cooldown(state: &mut PlayerState, duration: f32) {
    state.interaction_cooldown = duration;
}
}

A just_pressed check on the input also works and is simpler. Use cooldowns when the action should repeat at a fixed rate while the key is held, like an auto-fire weapon.

Physics Joints

A joint is a constraint between two rigid bodies. The constraint solver enforces the relationship every step. Different joint types constrain different degrees of freedom. A fixed joint constrains all six (three translation, three rotation). A revolute joint constrains five and leaves one rotation axis free. A prismatic joint constrains five and leaves one translation axis free.

Joint Types

Fixed Joint

A fixed joint welds two bodies into one. They move and rotate together as if they were a single body, but mass and collision stay separate.

#![allow(unused)]
fn main() {
use nightshade::ecs::physics::joints::*;

create_fixed_joint(
    world,
    body_a,
    body_b,
    FixedJoint::new()
        .with_local_anchor1(Vec3::new(0.5, 0.0, 0.0))
        .with_local_anchor2(Vec3::new(-0.5, 0.0, 0.0)),
);
}

The two local anchors are the attachment points in each body's local space. The solver keeps those points coincident.

Spherical Joint (Ball-and-Socket)

A spherical joint locks position but allows all three rotation axes. The two bodies pivot freely around the joint point.

#![allow(unused)]
fn main() {
let anchor = spawn_cube_at(world, Vec3::new(0.0, 5.0, 0.0));
let ball = spawn_sphere_at(world, Vec3::new(0.0, 3.0, 0.0));

create_spherical_joint(
    world,
    anchor,
    ball,
    SphericalJoint::new()
        .with_local_anchor1(Vec3::new(0.0, -0.15, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 1.0, 0.0)),
);
}

The example above is a pendulum. The anchor is fixed, the ball swings.

Revolute Joint (Hinge)

A revolute joint allows rotation around a single axis. Everything else is constrained.

#![allow(unused)]
fn main() {
let door_frame = spawn_cube_at(world, Vec3::zeros());
let door = spawn_cube_at(world, Vec3::new(0.5, 1.0, 0.0));

create_revolute_joint(
    world,
    door_frame,
    door,
    RevoluteJoint::new(JointAxisDirection::Y)
        .with_local_anchor1(Vec3::new(0.0, 0.0, 0.0))
        .with_local_anchor2(Vec3::new(-0.5, 0.0, 0.0))
        .with_limits(JointLimits::new(-1.5, 1.5)),
);
}

The Y-axis revolute joint above is a door hinge. The limits (in radians) prevent it from swinging through the wall behind it.

Adding Motor

A joint motor drives the joint toward a target position or velocity. For a position motor on the door, that turns the hinge into something that can open and close on command.

#![allow(unused)]
fn main() {
RevoluteJoint::new(JointAxisDirection::Y)
    .with_motor(JointMotor::position(0.0, 5.0, 100.0))
}

The three arguments are target position, stiffness, and damping. Stiffness controls how hard the motor pushes toward the target. Damping resists the resulting velocity.

Prismatic Joint (Slider)

A prismatic joint allows translation along a single axis and locks everything else.

#![allow(unused)]
fn main() {
let cabinet = spawn_cube_at(world, Vec3::zeros());
let drawer = spawn_cube_at(world, Vec3::new(0.0, 0.0, 0.5));

create_prismatic_joint(
    world,
    cabinet,
    drawer,
    PrismaticJoint::new(JointAxisDirection::Z)
        .with_local_anchor1(Vec3::new(0.0, 0.0, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 0.0, -0.5))
        .with_limits(JointLimits::new(0.0, 0.8)),
);
}

The limits are in meters. 0 is fully closed, 0.8 is fully open.

Rope Joint

A rope joint enforces a maximum distance between two bodies. Within that distance the bodies move freely. At the limit they stop separating.

#![allow(unused)]
fn main() {
let ceiling = spawn_cube_at(world, Vec3::zeros());
let weight = spawn_sphere_at(world, Vec3::new(0.0, 0.0, 0.0));

create_rope_joint(
    world,
    ceiling,
    weight,
    RopeJoint::new(2.0)
        .with_local_anchor1(Vec3::new(0.0, -0.15, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 0.0, 0.0)),
);
}

Use rope joints in series for a chain. Each link is a small body connected to the next by a rope joint with a short max distance.

Spring Joint

A spring joint applies a Hooke's-law restoring force toward a rest length. The body oscillates around that length and damping bleeds off the oscillation over time.

#![allow(unused)]
fn main() {
let anchor = spawn_cube_at(world, Vec3::zeros());
let bob = spawn_sphere_at(world, Vec3::new(0.0, -2.0, 0.0));

create_spring_joint(
    world,
    anchor,
    bob,
    SpringJoint::new(1.5, 50.0, 2.0)
        .with_local_anchor1(Vec3::new(0.0, -0.15, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 0.2, 0.0)),
);
}

Arguments are rest length, stiffness, damping. Higher stiffness gives a stiffer spring. Higher damping settles the bounce faster.

Joint Limits

Limits clamp the free degree of freedom to a range.

#![allow(unused)]
fn main() {
RevoluteJoint::new(JointAxisDirection::Z)
    .with_limits(JointLimits::new(-1.57, 1.57))

PrismaticJoint::new(JointAxisDirection::X)
    .with_limits(JointLimits::new(-2.0, 2.0))
}

Revolute limits are radians. Prismatic limits are meters. Without limits the joint runs to its full mechanical range, which for a revolute is unbounded rotation and for a prismatic is unbounded translation.

Breaking Joints

Joints can break under excessive force. Set a maximum impulse and Rapier will dissolve the joint when contact forces push past it.

#![allow(unused)]
fn main() {
if let Some(joint) = world.resources.physics.get_joint_mut(joint_handle) {
    joint.set_max_force(1000.0);
}
}

Chain Example

A chain is a string of spherical joints. Each link's bottom anchor is the next link's top anchor.

#![allow(unused)]
fn main() {
fn create_chain(world: &mut World, start: Vec3, links: usize) {
    let mut previous = spawn_cube_at(world, start);

    for index in 0..links {
        let position = start - Vec3::new(0.0, (index + 1) as f32 * 0.5, 0.0);
        let link = spawn_sphere_at(world, position);

        create_spherical_joint(
            world,
            previous,
            link,
            SphericalJoint::new()
                .with_local_anchor1(Vec3::new(0.0, -0.2, 0.0))
                .with_local_anchor2(Vec3::new(0.0, 0.2, 0.0)),
        );

        previous = link;
    }
}
}

The first link anchors to the spawn cube. Each subsequent link anchors below the previous one.

Interactive Door Example

A real door is a revolute joint with locked rotations on every axis except the hinge axis. Locking rotations on the body itself, in addition to the joint constraint, makes the door behave like a door instead of a wobbling flap.

#![allow(unused)]
fn main() {
fn spawn_interactive_door(world: &mut World, position: Vec3) -> Entity {
    let frame = spawn_cube_at(world, position);

    let door = spawn_cube_at(world, position + Vec3::new(0.5, 0.0, 0.0));

    if let Some(rb) = world.core.get_rigid_body(door) {
        if let Some(handle) = rb.handle {
            if let Some(body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
                body.lock_rotations(true, true);
            }
        }
    }

    create_revolute_joint(
        world,
        frame,
        door,
        RevoluteJoint::new(JointAxisDirection::Y)
            .with_local_anchor1(Vec3::new(0.05, 0.0, 0.0))
            .with_local_anchor2(Vec3::new(-0.5, 0.0, 0.0))
            .with_limits(JointLimits::new(-2.0, 2.0)),
    );

    door
}
}

The door body keeps the dynamic mass that gives it momentum when pushed. The joint limits define how far it swings open.

Loading Animated Models

Animated models in nightshade are glTF or GLB files with a skin, a skeleton, and one or more animation clips. The loader pulls all four (mesh, textures, skin, animations) out of the file and the spawner attaches them to entities. Skeleton joints become entities in the hierarchy. Animation clips become channels that target those joint entities by index.

Loading an Animated Model

#![allow(unused)]
fn main() {
use nightshade::ecs::prefab::*;

const CHARACTER_GLB: &[u8] = include_bytes!("../assets/character.glb");

fn load_character(world: &mut World) -> Option<Entity> {
    let result = import_gltf_from_bytes(CHARACTER_GLB).ok()?;

    for (name, (rgba_data, width, height)) in result.textures {
        world.queue_command(WorldCommand::LoadTexture {
            name,
            rgba_data,
            width,
            height,
        });
    }

    for (name, mesh) in result.meshes {
        mesh_cache_insert(&mut world.resources.mesh_cache, name, mesh);
    }

    result.prefabs.first().map(|prefab| {
        spawn_prefab_with_animations(
            world,
            prefab,
            &result.animations,
            Vec3::zeros(),
        )
    })
}
}

The textures go through the command queue because GPU uploads happen at frame setup, not during loading. The meshes go straight into the mesh cache. spawn_prefab_with_animations is the version of the spawner that attaches an AnimationPlayer with the loaded clips.

Animation Data Structure

A loaded animation is a duration and a list of channels. Each channel targets one property on one joint and stores keyframes as flat arrays of times and values.

#![allow(unused)]
fn main() {
pub struct AnimationClip {
    pub name: String,
    pub duration: f32,
    pub channels: Vec<AnimationChannel>,
}

pub struct AnimationChannel {
    pub target_node: usize,
    pub target_property: AnimationProperty,
    pub interpolation: Interpolation,
    pub times: Vec<f32>,
    pub values: Vec<f32>,
}

pub enum AnimationProperty {
    Translation,
    Rotation,
    Scale,
    MorphWeights,
}
}

target_node indexes into the skin's joint array, not into the world entity list. The animation system resolves the index to an entity at sample time.

Filtering Animation Channels

Mocap-derived animations often include translation on the root joint, which moves the character through the scene as the clip plays. That works when the engine drives movement from the animation (root motion) and breaks when game code drives movement and the animation should stay in place.

#![allow(unused)]
fn main() {
fn filter_animations(animations: &[AnimationClip]) -> Vec<AnimationClip> {
    let root_bone_indices: std::collections::HashSet<usize> = [0, 1, 2, 3].into();

    animations
        .iter()
        .map(|clip| AnimationClip {
            name: clip.name.clone(),
            duration: clip.duration,
            channels: clip
                .channels
                .iter()
                .filter(|channel| {
                    if channel.target_property == AnimationProperty::Translation {
                        return false;
                    }
                    if root_bone_indices.contains(&channel.target_node)
                        && channel.target_property == AnimationProperty::Rotation
                    {
                        return false;
                    }
                    true
                })
                .cloned()
                .collect(),
        })
        .collect()
}
}

The filter above drops all translation channels and root-bone rotation. Rotation on the spine and limbs survives, so the character animates in place.

Storing Animation Indices

The animation player holds clips by index, not by name. Resolve names once at load time and store the indices.

#![allow(unused)]
fn main() {
struct AnimationIndices {
    idle: Option<usize>,
    walk: Option<usize>,
    run: Option<usize>,
    jump: Option<usize>,
}

fn find_animation_indices(clips: &[AnimationClip]) -> AnimationIndices {
    let mut indices = AnimationIndices {
        idle: None,
        walk: None,
        run: None,
        jump: None,
    };

    for (index, clip) in clips.iter().enumerate() {
        let name = clip.name.to_lowercase();
        if name.contains("idle") {
            indices.idle = Some(index);
        } else if name.contains("walk") {
            indices.walk = Some(index);
        } else if name.contains("run") {
            indices.run = Some(index);
        } else if name.contains("jump") {
            indices.jump = Some(index);
        }
    }

    indices
}
}

Substring matching is forgiving against clip names like "Armature.Idle" or "idle_loop". A strict equality check fails on the first asset that renames its clips.

Skeleton Structure

A skin is the binding between the mesh and the skeleton. Joints are entities, and the inverse bind matrices are the bind-pose transforms used to skin the mesh.

#![allow(unused)]
fn main() {
pub struct Skin {
    pub joints: Vec<Entity>,
    pub inverse_bind_matrices: Vec<Mat4>,
}
}

The joints array is what animation channels target. Bone index 7 in a channel resolves to skin.joints[7] in the world.

Attaching Objects to Bones

Attaching an item to a bone is the same as parenting any entity. Set the parent to the joint entity, then place the item in local space relative to the bone.

#![allow(unused)]
fn main() {
fn attach_to_bone(world: &mut World, item: Entity, bone: Entity) {
    world.core.set_parent(item, Parent(Some(bone)));

    if let Some(transform) = world.core.get_local_transform_mut(item) {
        transform.translation = Vec3::new(0.0, 0.1, 0.0);
        transform.scale = Vec3::new(1.0, 1.0, 1.0);
    }
}

fn attach_hat(world: &mut World, character: Entity, hat: Entity) {
    if let Some(skin) = world.core.get_skin(character) {
        for joint in &skin.joints {
            if let Some(name) = world.core.get_name(*joint) {
                if name.0.contains("Head") {
                    attach_to_bone(world, hat, *joint);
                    return;
                }
            }
        }
    }
}
}

The transform hierarchy does the rest. As the head bone moves through the animation, the hat moves with it.

Finding Bones by Name

#![allow(unused)]
fn main() {
fn find_bone_by_name(world: &World, character: Entity, bone_name: &str) -> Option<Entity> {
    let skin = world.core.get_skin(character)?;

    for joint in &skin.joints {
        if let Some(name) = world.core.get_name(*joint) {
            if name.0.contains(bone_name) {
                return Some(*joint);
            }
        }
    }
    None
}
}

Bone names come from the source file. They are typically capitalized in glTF (Head, LeftHand, Spine_2) but DCC tool conventions vary, so substring matching survives more files than equality does.

Multiple Animated Characters

Loading the same model file repeatedly is wasted work. Decode once, then spawn from the cached prefab as many times as needed.

#![allow(unused)]
fn main() {
struct CharacterFactory {
    prefab: Prefab,
    animations: Vec<AnimationClip>,
}

impl CharacterFactory {
    fn new(bytes: &[u8]) -> Option<Self> {
        let result = import_gltf_from_bytes(bytes).ok()?;
        Some(Self {
            prefab: result.prefabs.into_iter().next()?,
            animations: result.animations,
        })
    }

    fn spawn(&self, world: &mut World, position: Vec3) -> Entity {
        spawn_prefab_with_animations(
            world,
            &self.prefab,
            &self.animations,
            position,
        )
    }
}
}

The prefab and animations are shared by reference. Each spawn produces an independent set of entities with its own AnimationPlayer, so two characters can play different clips at different times from the same source data.

Animation Playback

Live Demo: Dance

AnimationPlayer is the component that tracks playback state for one animated entity. It holds the loaded clips, the index of the current clip, the playback time within that clip, the speed multiplier, and the flags that control looping and pausing. The animation system on the frame schedule advances the time each frame and writes the sampled pose into the joint entities.

AnimationPlayer Component

#![allow(unused)]
fn main() {
pub struct AnimationPlayer {
    pub clips: Vec<AnimationClip>,
    pub current_clip: Option<usize>,
    pub time: f32,
    pub speed: f32,
    pub looping: bool,
    pub playing: bool,
    pub blend_from_clip: Option<usize>,
    pub blend_factor: f32,
}
}

blend_from_clip and blend_factor are the crossfade state used by blend_to. When blend_from_clip is Some, the system samples both clips and lerps the result by blend_factor. See the blending chapter for details.

Basic Playback

#![allow(unused)]
fn main() {
fn play_animation(world: &mut World, entity: Entity, clip_index: usize) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.play(clip_index);
        player.looping = true;
    }
}
}

play sets current_clip, resets time to zero, and sets playing to true. Setting looping separately controls whether the clip wraps or stops at the end.

Controlling Speed

#![allow(unused)]
fn main() {
fn set_animation_speed(world: &mut World, entity: Entity, speed: f32) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.speed = speed;
    }
}
}

Speed is a multiplier on the time advance. 1.0 is normal, 0.5 is half, 2.0 is double. Negative values play in reverse.

Pausing and Resuming

#![allow(unused)]
fn main() {
fn pause_animation(world: &mut World, entity: Entity) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.pause();
    }
}

fn resume_animation(world: &mut World, entity: Entity) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.resume();
    }
}
}

Pause stops the time from advancing but leaves the current pose frozen. Resume picks up where it left off.

Looping

#![allow(unused)]
fn main() {
fn set_looping(world: &mut World, entity: Entity, looping: bool) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.looping = looping;
    }
}
}

A non-looping clip stops at its duration and stays on the final pose. A looping clip wraps the time modulo duration.

Checking Animation State

For one-shot animations the caller often needs to know when the clip has finished playing.

#![allow(unused)]
fn main() {
fn is_animation_finished(world: &World, entity: Entity) -> bool {
    if let Some(player) = world.core.get_animation_player(entity) {
        if !player.looping {
            if let Some(index) = player.current_clip {
                let clip = &player.clips[index];
                return player.time >= clip.duration;
            }
        }
    }
    false
}

fn get_animation_progress(world: &World, entity: Entity) -> f32 {
    if let Some(player) = world.core.get_animation_player(entity) {
        if let Some(index) = player.current_clip {
            let clip = &player.clips[index];
            return player.time / clip.duration;
        }
    }
    0.0
}
}

get_animation_progress returns a normalized [0, 1] value useful for driving UI like an attack windup bar.

Animation by Name

#![allow(unused)]
fn main() {
fn play_animation_by_name(world: &mut World, entity: Entity, name: &str) -> bool {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        for (index, clip) in player.clips.iter().enumerate() {
            if clip.name.to_lowercase().contains(&name.to_lowercase()) {
                player.play(index);
                return true;
            }
        }
    }
    false
}
}

Name lookup is O(N) over the clips array. For tight loops, resolve indices once at load and store them on a per-character struct.

State-Based Animation

A character typically has an animation state machine driven by gameplay state. The cleanest pattern is to map each state to a clip index and call blend_to whenever the state changes.

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, PartialEq)]
enum MovementState {
    Idle,
    Walking,
    Running,
    Jumping,
}

fn update_character_animation(
    world: &mut World,
    entity: Entity,
    state: MovementState,
    indices: &AnimationIndices,
    current: &mut Option<usize>,
) {
    let target = match state {
        MovementState::Idle => indices.idle,
        MovementState::Walking => indices.walk,
        MovementState::Running => indices.run,
        MovementState::Jumping => indices.jump,
    };

    if target != *current {
        if let Some(index) = target {
            if let Some(player) = world.core.get_animation_player_mut(entity) {
                player.blend_to(index, 0.2);
                *current = Some(index);
            }
        }
    }
}
}

The if target != *current guard is important. Calling blend_to every frame restarts the crossfade and the result is a stuck pose.

Speed Based on Movement

Walk and run clips are authored at a fixed speed. Scaling the playback rate to match the character's actual velocity prevents foot sliding.

#![allow(unused)]
fn main() {
fn sync_animation_to_movement(world: &mut World, entity: Entity, velocity: f32) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        let base_speed = 3.0;
        player.speed = (velocity / base_speed).clamp(0.5, 2.0);
    }
}
}

The clamp keeps the animation from playing absurdly fast or slow. A character creeping at 0.1 m/s should not freeze, and a character sprinting at 30 m/s should not blur.

One-Shot Animations

#![allow(unused)]
fn main() {
fn play_once(world: &mut World, entity: Entity, clip_index: usize) {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.play(clip_index);
        player.looping = false;
    }
}
}

Animation Events

Animation events are gameplay triggers fired at specific times within a clip. Footsteps, weapon swing sounds, hit detection windows. The technique is to compare the current time against an event time and the previous frame's time, and fire when the threshold is crossed.

#![allow(unused)]
fn main() {
fn check_animation_events(world: &World, entity: Entity, event_time: f32) -> bool {
    if let Some(player) = world.core.get_animation_player(entity) {
        let prev_time = player.time - world.resources.window.timing.delta_time * player.speed;
        prev_time < event_time && player.time >= event_time
    } else {
        false
    }
}

fn footstep_system(world: &mut World, character: Entity, footstep_source: Entity) {
    if check_animation_events(world, character, 0.3) || check_animation_events(world, character, 0.8) {
        if let Some(audio) = world.core.get_audio_source_mut(footstep_source) {
            audio.playing = true;
        }
    }
}
}

The cross-the-threshold check fires exactly once per pass. A naive time >= 0.3 check would fire every frame after the threshold and play the footstep on every subsequent frame.

Blending & Transitions

Live Demos: Dance | Morph Targets

A hard cut between two animation clips snaps the skeleton from one pose to another in a single frame and looks broken. Crossfading samples both clips and lerps the joint transforms by a weight that ramps from 0 to 1 over a short window. The result is a continuous motion that takes the skeleton from one clip's pose to the other's without visible discontinuity.

Cross-Fade Transition

blend_to is the entry point. It records the current clip as the blend source, sets the new clip as the active clip, and ramps the blend factor across the requested duration.

#![allow(unused)]
fn main() {
if let Some(player) = world.core.get_animation_player_mut(entity) {
    player.blend_to(new_animation_index, 0.2);
}
}

While the blend is active, the animation system samples both clips at their respective times and interpolates each joint's translation, rotation, and scale by the current weight. When the weight reaches 1, the source clip is dropped and the new clip becomes the sole active animation.

Blend Duration

Different transitions want different durations. A startle reaction needs to snap. A stop-walking transition wants time to settle.

The 0.05s attack blend is short enough to read as instant while still avoiding the visible snap of a hard cut.

Movement State Machine

A state machine is the right abstraction for character animation. The state is the gameplay-level intent (idle, walking, jumping). The animation player tracks which clip is currently playing. A transition is a request to blend from the current clip to the one mapped to the new state.

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, PartialEq, Eq)]
enum CharacterState {
    Idle,
    Walking,
    Running,
    Jumping,
    Falling,
    Landing,
}

struct AnimationController {
    state: CharacterState,
    current_animation: Option<usize>,
    indices: AnimationIndices,
}

impl AnimationController {
    fn update(&mut self, world: &mut World, entity: Entity, new_state: CharacterState) {
        if self.state == new_state {
            return;
        }

        let blend_time = self.get_blend_time(self.state, new_state);
        let target_anim = self.get_animation_for_state(new_state);

        if let Some(index) = target_anim {
            if let Some(player) = world.core.get_animation_player_mut(entity) {
                player.blend_to(index, blend_time);
                self.current_animation = Some(index);
            }
        }

        self.state = new_state;
    }

    fn get_blend_time(&self, from: CharacterState, to: CharacterState) -> f32 {
        match (from, to) {
            (CharacterState::Idle, CharacterState::Walking) => 0.2,
            (CharacterState::Walking, CharacterState::Running) => 0.15,
            (CharacterState::Running, CharacterState::Idle) => 0.3,
            (_, CharacterState::Jumping) => 0.1,
            _ => 0.2,
        }
    }

    fn get_animation_for_state(&self, state: CharacterState) -> Option<usize> {
        match state {
            CharacterState::Idle => self.indices.idle,
            CharacterState::Walking => self.indices.walk,
            CharacterState::Running => self.indices.run,
            CharacterState::Jumping => self.indices.jump,
            CharacterState::Falling => self.indices.jump,
            CharacterState::Landing => self.indices.idle,
        }
    }
}
}

The from, to pair gates the blend time, which is how transitions like "running stop" can use a longer duration than "running to jump."

Speed-Based Blending

Choosing between walk and run by speed threshold is a state-machine approach. A pure crossfade between walk and run blended by speed gives a continuous gait that interpolates smoothly across the threshold. Both work. The threshold version is shown below.

#![allow(unused)]
fn main() {
fn update_locomotion(world: &mut World, entity: Entity, speed: f32, indices: &AnimationIndices) {
    let walk_threshold = 2.0;
    let run_threshold = 5.0;

    let state = if speed < 0.1 {
        MovementState::Idle
    } else if speed < walk_threshold {
        MovementState::Walking
    } else {
        MovementState::Running
    };

    let target_anim = match state {
        MovementState::Idle => indices.idle,
        MovementState::Walking => indices.walk,
        MovementState::Running => indices.run,
    };

    if let Some(index) = target_anim {
        if let Some(player) = world.core.get_animation_player_mut(entity) {
            if player.current_clip != Some(index) {
                player.blend_to(index, 0.2);
            }

            player.speed = match state {
                MovementState::Idle => 1.0,
                MovementState::Walking => speed / walk_threshold,
                MovementState::Running => speed / run_threshold,
            };
        }
    }
}
}

Tying playback speed to actual velocity inside each band keeps the feet from sliding. A character moving at 1.5 m/s plays walk at 0.75 speed, not at the authored 1.0.

Interrupt Handling

Attacks are non-looping clips that interrupt locomotion. They blend in fast, play once, then the state machine has to decide what comes next.

#![allow(unused)]
fn main() {
fn try_attack(world: &mut World, entity: Entity, attack_anim: usize, current_state: &mut CharacterState) -> bool {
    if let Some(player) = world.core.get_animation_player_mut(entity) {
        player.blend_to(attack_anim, 0.05);
        player.looping = false;
        *current_state = CharacterState::Attacking;
        return true;
    }
    false
}

fn check_attack_finished(world: &World, entity: Entity) -> bool {
    if let Some(player) = world.core.get_animation_player(entity) {
        if !player.looping {
            if let Some(index) = player.current_clip {
                let clip = &player.clips[index];
                return player.time >= clip.duration * 0.9;
            }
        }
    }
    false
}
}

duration * 0.9 is the trick that gives the next animation room to blend in. Waiting for the full duration leaves no time for the crossfade and the attack appears to snap back to idle.

Additive Blending

Additive layers stack a delta animation on top of a base. A breathing layer on top of idle. An aim offset on top of walk. The base provides the bulk of the motion, the additive provides per-joint offsets that add to whatever the base produced.

#![allow(unused)]
fn main() {
struct LayeredAnimation {
    base_animation: usize,
    additive_animations: Vec<(usize, f32)>,
}
}

The struct above is the data layout. The sampling math depends on the engine support and is not part of the default AnimationPlayer.

Root Motion

Root motion is the technique of letting the animation drive movement. The character moves through the world by the same amount the root bone moves in the clip. This produces tightly synchronized footplant but ties movement speed to the authored clip and complicates collision response.

#![allow(unused)]
fn main() {
fn apply_root_motion(world: &mut World, entity: Entity) {
    let Some(player) = world.core.get_animation_player(entity) else { return };

    let Some(current_index) = player.current_clip else { return };
    let clip = &player.clips[current_index];
}
}

The alternative is to strip root translation out of every clip (see the filter in the loading chapter) and drive movement from game code. That gives less footplant accuracy but more control. nightshade examples use the strip-and-drive approach.

Transition Rules

Not every state should be reachable from every other state. A jump cannot start from mid-air. An attack should not be interruptible by walking.

#![allow(unused)]
fn main() {
fn can_transition(from: CharacterState, to: CharacterState) -> bool {
    match (from, to) {
        (_, CharacterState::Idle) => true,
        (_, CharacterState::Falling) => true,

        (CharacterState::Attacking, _) => false,

        (CharacterState::Falling, CharacterState::Jumping) => false,
        (CharacterState::Jumping, CharacterState::Jumping) => false,

        _ => true,
    }
}
}

The rule table lives outside the animation system and gates state changes before they ever reach blend_to. Keeping the rules data instead of scattering them through gameplay code makes the state machine easy to audit.

Audio System

Live Demo: Audio

Audio in nightshade is Kira behind an ECS facade. Sounds are decoded once and stored in a name-keyed cache on world.resources.audio. Playback happens through the AudioSource component, which holds a reference to the cached sound by name plus per-source state like volume, looping, and spatial flag. An AudioListener component on the camera (or wherever else) gives spatial sources a reference point.

Enabling Audio

The audio feature pulls in Kira and the audio components.

[dependencies]
nightshade = { git = "...", features = ["engine", "audio"] }

Loading Sounds

Sound loading is two steps. Decode the bytes into a StaticSoundData, then cache that data by name. The cache is shared, so any number of AudioSource components can reference the same sound without duplicating the decoded samples.

#![allow(unused)]
fn main() {
use nightshade::ecs::audio::*;

const EXPLOSION_WAV: &[u8] = include_bytes!("../assets/sounds/explosion.wav");
const MUSIC_OGG: &[u8] = include_bytes!("../assets/sounds/music.ogg");

fn initialize(&mut self, world: &mut World) {
    if let Ok(data) = load_sound_from_bytes(EXPLOSION_WAV) {
        world.resources.audio.load_sound("explosion", data);
    }
    if let Ok(data) = load_sound_from_bytes(MUSIC_OGG) {
        world.resources.audio.load_sound("music", data);
    }
}
}

load_sound_from_bytes is the decoder. It accepts WAV, OGG, MP3, and FLAC and returns the same StaticSoundData regardless of source format.

Playing Sounds

Entity-Based Playback

Playback is driven by AudioSource. The component references a cached sound by name and the audio system polls for active sources each frame.

#![allow(unused)]
fn main() {
let entity = world.spawn_entities(AUDIO_SOURCE | LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];

world.core.set_audio_source(entity, AudioSource::new("explosion").playing());
}

Looping Music

#![allow(unused)]
fn main() {
let music = world.spawn_entities(AUDIO_SOURCE, 1)[0];

world.core.set_audio_source(music, AudioSource::new("music")
    .with_looping(true)
    .playing(),
);
}

Music does not need a transform. The audio system treats a source with no transform as non-spatial and routes it to the master bus directly.

Audio Source Component

#![allow(unused)]
fn main() {
pub struct AudioSource {
    pub audio_ref: Option<String>,
    pub volume: f32,
    pub looping: bool,
    pub playing: bool,
    pub spatial: bool,
    pub reverb: bool,
}
}

audio_ref is the lookup key into the sound cache. volume is a per-source multiplier. looping, playing, spatial, and reverb are flags that gate playback behavior.

Builder methods chain the same fields.

#![allow(unused)]
fn main() {
AudioSource::new("name")
    .with_volume(0.8)
    .with_looping(true)
    .with_spatial(true)
    .with_reverb(true)
    .playing()
}

Audio Listener

A spatial audio source needs to know where the listener is. Mark the listener with the AUDIO_LISTENER component, usually on the active camera.

#![allow(unused)]
fn main() {
world.core.add_components(camera_entity, AUDIO_LISTENER);
world.core.set_audio_listener(camera_entity, AudioListener);
}

The audio system reads the listener's global transform each frame and uses it as the reference point for distance attenuation and panning.

Spatial Audio Sources

A spatial source attenuates by distance and pans by direction relative to the listener. The flag is spatial = true.

#![allow(unused)]
fn main() {
const ENGINE_LOOP: &[u8] = include_bytes!("../assets/sounds/engine_loop.wav");

fn initialize(&mut self, world: &mut World) {
    if let Ok(data) = load_sound_from_bytes(ENGINE_LOOP) {
        world.resources.audio.load_sound("engine_loop", data);
    }

    let entity = world.spawn_entities(
        AUDIO_SOURCE | LOCAL_TRANSFORM | GLOBAL_TRANSFORM,
        1,
    )[0];

    world.core.set_audio_source(entity, AudioSource::new("engine_loop")
        .with_spatial(true)
        .with_looping(true)
        .playing(),
    );
}
}

The source's transform is the position in world space. Move the transform and the sound moves.

Sound Variations

Repeating the same audio sample every time a footstep fires is audibly mechanical. Pick from a small pool of variations to make the result feel less canned.

#![allow(unused)]
fn main() {
const FOOTSTEP_1: &[u8] = include_bytes!("../assets/sounds/footstep_1.wav");
const FOOTSTEP_2: &[u8] = include_bytes!("../assets/sounds/footstep_2.wav");
const FOOTSTEP_3: &[u8] = include_bytes!("../assets/sounds/footstep_3.wav");
const FOOTSTEP_4: &[u8] = include_bytes!("../assets/sounds/footstep_4.wav");

fn initialize(&mut self, world: &mut World) {
    for (name, bytes) in [
        ("footstep_1", FOOTSTEP_1),
        ("footstep_2", FOOTSTEP_2),
        ("footstep_3", FOOTSTEP_3),
        ("footstep_4", FOOTSTEP_4),
    ] {
        if let Ok(data) = load_sound_from_bytes(bytes) {
            world.resources.audio.load_sound(name, data);
        }
    }
}

fn play_footstep(world: &mut World, source_entity: Entity) {
    let sounds = ["footstep_1", "footstep_2", "footstep_3", "footstep_4"];
    let index = rand::random::<usize>() % sounds.len();

    if let Some(audio) = world.core.get_audio_source_mut(source_entity) {
        audio.audio_ref = Some(sounds[index].to_string());
        audio.playing = true;
    }
}
}

Four variations is the practical minimum to break the loop perception. Eight is better.

Triggering Sounds on Events

Physics collision events are a natural source of impact sounds. Read the event queue and flip the appropriate source's playing flag.

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    for event in world.resources.physics.collision_events() {
        if matches!(event.kind, CollisionEventKind::Started) {
            if let Some(audio) = world.core.get_audio_source_mut(self.impact_source) {
                audio.audio_ref = Some("impact".to_string());
                audio.playing = true;
            }
        }
    }
}
}

Stopping Sounds

Two ways to stop a sound. Through the audio resource, or by setting the flag.

#![allow(unused)]
fn main() {
world.resources.audio.stop_sound(entity);
}

#![allow(unused)]
fn main() {
if let Some(audio) = world.core.get_audio_source_mut(entity) {
    audio.playing = false;
}
}

The resource call stops Kira's playback handle immediately. The flag flips on the next frame when the audio system processes sources. Use the flag for game-logic-driven stops and the resource for clean shutdown.

Supported Formats

WAV is the right format for short effects where decode time matters. OGG and MP3 are right for music where file size matters. FLAC sits in between with lossless compression at a moderate decode cost.

Spatial Audio

Spatial audio is positional sound. A source at a location in the world, a listener at another location, and an audio signal that is attenuated by distance and panned by direction. The result is the listener can tell where a sound is coming from without seeing it. Footsteps behind, gunfire to the left, a waterfall in the distance.

Audio Listener

The listener is the entity whose position and orientation define "the ears." Almost always the camera.

#![allow(unused)]
fn main() {
fn initialize(&mut self, world: &mut World) {
    let camera = spawn_camera(world, Vec3::new(0.0, 2.0, 10.0), "Camera".to_string());
    world.resources.active_camera = Some(camera);

    world.core.add_components(camera, AUDIO_LISTENER);
    world.core.set_audio_listener(camera, AudioListener);
}
}

There is one active listener. If two entities both have the component, the audio system picks one and ignores the other.