Introduction

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

Nightshade is a modern game engine written in Rust, designed for creating 3D games and interactive applications. It provides a complete toolkit for game development including rendering, physics, audio, animation, and more.

What is Nightshade?

Nightshade is a batteries-included game engine that handles the complexity of modern 3D graphics while remaining approachable for developers of all skill levels. Whether you're building a simple visualizer, a physics playground, or a complete 3D game, Nightshade provides the foundation you need.

The engine is built on top of industry-standard libraries:

• wgpu for cross-platform GPU access (Vulkan, Metal, DirectX 12, WebGPU)
• Rapier3D for physics simulation
• Kira for audio playback and spatial sound
• egui for immediate-mode UI
• glTF for 3D model loading

Key Features

Rendering

• Physically Based Rendering (PBR) - Metallic-roughness workflow with support for all standard texture maps
• Dynamic Lighting - Directional, point, and spot lights with real-time shadows
• Post-Processing - Bloom, SSAO, depth of field, tonemapping, and custom effects
• Skeletal Animation - Smooth blending and crossfading between animations
• Particle Systems - GPU-accelerated particles with configurable emitters
• Terrain - Procedural generation with tessellation and LOD
• Grass - Thousands of interactive grass blades with wind simulation

Physics

• Rigid Body Dynamics - Dynamic, kinematic, and static bodies
• Collision Shapes - Box, sphere, capsule, cylinder, convex hull, trimesh, heightfield
• Character Controllers - Built-in player movement with slopes, steps, and jumping
• Physics Joints - Fixed, revolute, prismatic, spherical, rope, and spring joints
• Raycasting - Query the physics world for line-of-sight and hit detection

Audio

• Sound Playback - WAV, OGG, MP3, FLAC support
• Spatial Audio - 3D positioned sound sources with distance attenuation
• FFT Analysis - Real-time spectral analysis for music visualizers

Input

• Keyboard & Mouse - Full key detection with press/release states
• Gamepad - Controller support with analog sticks, triggers, and rumble
• Cursor Control - Lock and hide cursor for FPS-style games

Tools

• Navigation Mesh - AI pathfinding with Recast integration
• Debug Rendering - Lines, boxes, spheres for visualization
• HUD Text - Screen-space text rendering with anchoring
• Screenshot Capture - Save frames to PNG
• Developer Console - In-game command console with custom commands

Platform

• OpenXR VR - Virtual reality with head/hand tracking and locomotion
• Steam - Achievements, stats, multiplayer, and friends integration
• Webview - Host web frontends (Leptos, Yew) with bidirectional IPC
• Mosaic - Multi-pane desktop application framework with dockable widgets
• WASM Plugins - Extend the engine with WebAssembly plugins

Architecture Overview

Nightshade follows a simple architecture centered around the State trait and the World container:

┌─────────────────────────────────────────────────────────────┐
│                      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 Game Loop

Each frame, Nightshade:

1. Processes window and input events
2. Calls your run_systems() method
3. Updates physics simulation
4. Propagates transform hierarchies
5. Renders the scene
6. Presents to the screen

You control game logic in run_systems(), and the engine handles everything else.

Design Philosophy

Nightshade follows these core principles:

Simplicity

The API surface is minimal and consistent. Common tasks like spawning entities, loading models, and handling input should be intuitive. If something feels overly complex, it's probably a bug.

Performance

The engine uses data-oriented design throughout. The ECS stores components in contiguous arrays for cache-friendly access. The renderer batches draw calls and uses GPU instancing where possible.

Flexibility

Feature flags let you include only what you need. Building a simple visualizer? Just use engine. Need physics? Add physics. Everything is opt-in.

Cross-Platform

Write once, run everywhere. The same code runs on Windows, macOS, Linux, and WebAssembly. The engine automatically selects the appropriate graphics backend.

When to Use Nightshade

Nightshade is well-suited for:

• 3D Games - Action games, platformers, simulations
• Visualizers - Music-reactive graphics, data visualization
• Prototypes - Quickly test game ideas
• Learning - Understanding game engine concepts

Nightshade may not be ideal for:

• 2D-only games - Consider a dedicated 2D engine (though Nightshade does support sprites)
• Mobile - Not yet optimized for mobile platforms

Version

This documentation covers Nightshade using Rust 2024 Edition.

Getting Help

• GitHub Repository - Source code and issue tracker
• API Documentation - Generated API docs

Let's get started!

Interactive Demo

Experience Nightshade running directly in your browser via WebGPU.

Controls

• Mouse Drag: Orbit the camera around the scene
• Scroll Wheel: Zoom in and out

What You're Seeing

This demo showcases several Nightshade features:

• Primitives: A cube, sphere, and torus rendered with PBR materials
• Emissive Materials: Each object has emissive properties that create a glowing effect
• Bloom Post-Processing: The glow spreads beyond object boundaries
• Infinite Grid: A reference grid at ground level
• Nebula Skybox: A procedural space background
• Pan-Orbit Camera: Interactive camera controls
• Animation: Objects rotate and bob with smooth interpolation

Requirements

This demo requires a browser with WebGPU support:

• Chrome/Edge: Version 113+ (enabled by default)
• Firefox: Version 141+ (enabled by default)
• Safari: Version 18+ (Technology Preview)

If you see a blank frame, your browser may not support WebGPU yet.

Source Code

Cargo.toml

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

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

[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 title(&self) -> &str {
        "Hello Nightshade"
    }

    fn initialize(&mut self, world: &mut World) {
        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);
        }
    }
}

Installation

Prerequisites

• Rust 1.90+ with the 2024 edition
• A graphics driver supporting Vulkan 1.2, Metal, or DirectX 12

Quick Start

Clone the template repository:

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

Run it:

just run

You should see a 3D scene with a nebula skybox, a grid, and a pan-orbit camera.

What's in the Template

The template gives you a working project with:

• src/main.rs - A minimal Nightshade application with a camera, sun, and egui UI
• Cargo.toml - Nightshade dependency with egui feature enabled
• justfile - Build, run, lint, and deploy commands for native, WASM, VR, and Steam Deck
• index.html + Trunk.toml - WASM web build configuration
• .github/workflows/ - CI (clippy, tests, WASM build) and GitHub Pages deployment
• rust-toolchain - Pinned Rust version with WASM target

Starter Code

The template's src/main.rs:

use nightshade::prelude::*;

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

#[derive(Default)]
struct Template;

impl State for Template {
    fn title(&self) -> &str { "Template" }

    fn initialize(&mut self, world: &mut World) {
        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 ui(&mut self, _world: &mut World, ui_context: &egui::Context) {
        egui::Window::new("Template").show(ui_context, |_ui| {});
    }

    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

Feature Flags

The template enables egui by default. Add more features in Cargo.toml:

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

See the Feature Flags appendix for the complete list.

Platform-Specific Notes

Windows

DirectX 12 is the default backend. Ensure your graphics drivers are up to date.

macOS

Metal is used automatically. No additional setup required.

Linux

Vulkan is required. Install Vulkan drivers for your GPU:

# 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

WebAssembly

WebGPU support requires a compatible browser (Chrome 113+, Firefox 121+). The template includes just run-wasm which uses Trunk to build and serve.

Your First Application

Let's create a simple application that displays a 3D scene with a camera, lighting, and some cubes.

Basic Structure

Every Nightshade application implements the State trait:

use nightshade::prelude::*;

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

#[derive(Default)]
struct MyGame;

impl State for MyGame {
    fn title(&self) -> &str {
        "My First Game"
    }

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

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

Adding a Camera

The camera determines what the player sees:

#![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);
}
}

Adding Lighting

Without lights, everything is dark. Add a directional light (sun):

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

Enabling the Grid

For development, a ground grid is helpful:

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

Adding Geometry

Spawn a cube using the built-in primitive (available from the prelude):

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

Camera Controls

Add a fly camera system so you can navigate the scene:

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

Complete 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 title(&self) -> &str {
        "My First Game"
    }

    fn initialize(&mut self, world: &mut World) {
        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

With the fly camera system enabled:

Next Steps

Now that you have a basic scene, explore:

• Meshes & Models - Load 3D models
• Materials - Customize appearance
• Physics - Add physics simulation

Project Structure

Recommended Layout

A typical Nightshade project follows this structure:

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

Cargo.toml

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

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

Entry Point (main.rs)

Keep main.rs minimal:

mod game;

use nightshade::prelude::*;

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

Game State (game.rs)

Implement your game logic:

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

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

impl State for MyGame {
    fn title(&self) -> &str {
        "My Game"
    }

    fn initialize(&mut self, world: &mut World) {
        // Setup code
    }

    fn run_systems(&mut self, world: &mut World) {
        // Per-frame logic
    }
}
}

Embedding Assets

For distribution, embed assets directly in the binary:

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

Custom ECS

For complex games, create a separate game ECS alongside the engine's World:

#![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,
}
}

This keeps game-specific data separate from engine data while allowing both to coexist.

Module Organization

For larger projects, organize systems into modules:

#![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);
    }
}
}

Architecture Overview

Nightshade is organized as a layered dependency graph (DAG). Each layer builds on the one below it, and no layer references anything above it. This chapter shows how the pieces fit together.

Feature Layer:     Terrain, Particles, NavMesh, Grass, SDF, Lattice, Scripting
                            |
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 lowest layer contains three independent systems that everything else depends on.

ECS (freecs) provides compile-time code-generated entity storage with struct-of-arrays layout. The ecs! macro generates the World struct, component accessors, query methods, and entity management. Zero unsafe code, all statically dispatched.

Math (nalgebra_glm) provides vectors (Vec2, Vec3, Vec4), matrices (Mat4), quaternions (Quat), and all standard linear algebra operations. Nightshade uses nalgebra_glm exclusively for all math.

GPU (wgpu) provides cross-platform GPU access. wgpu targets Vulkan, Metal, DirectX 12, and WebGPU from a single API surface.

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 containing global singletons (timing, input, graphics settings, caches, physics world, audio engine, etc.).

Transform Hierarchy propagates LocalTransform through parent-child relationships to compute GlobalTransform matrices each frame. Dirty-flag tracking ensures only modified subtrees are recomputed.

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

Time is accessed through world.resources.window.timing and provides delta_time, frames_per_second, uptime_milliseconds, frame_counter, and raw/speed-adjusted variants.

Windowing wraps winit for window creation, event handling, and surface management. On native platforms, secondary windows are supported via SecondaryWindows.

Simulation Layer

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

Physics (Rapier3D) runs at a fixed 60Hz timestep with interpolation for smooth rendering. Provides rigid bodies, colliders, character controllers, joints, and raycasting. Gated behind the physics feature flag.

Animation plays back skeletal animations loaded from glTF files. Supports blending, crossfading, speed control, and looping. Bone transforms are written directly into the ECS each frame.

Audio (Kira) handles sound playback with spatial positioning, distance attenuation, and FFT analysis. Gated behind the audio feature flag.

Rendering Layer

Transforms ECS data into pixels on screen.

Render Graph is a dependency-driven frame graph built on petgraph. Passes declare which resources they read and write via named slots. The graph automatically builds dependency edges, topologically sorts passes, computes resource lifetimes, aliases transient GPU memory, and determines optimal load/store operations.

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

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

Textures are managed by a TextureCache that handles GPU upload, format conversion, and atlas packing (for sprites). Textures are loaded via WorldCommand::LoadTexture.

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

Application Layer

The interface between engine and game code.

State Trait is implemented by your game struct. Its methods (initialize, run_systems, ui, configure_render_graph, etc.) are called by the engine at specific points in the frame lifecycle.

Main Loop drives the frame lifecycle: process events, update input, call run_systems, dispatch events, run the frame schedule (engine systems), render, present.

Frame Schedule is a data-driven ordered list of engine system functions stored as a resource (world.resources.frame_schedule). It dispatches audio, camera, physics, scripting, animation, transform propagation, and cleanup systems each frame. Users can insert, remove, or reorder systems in State::initialize().

Event Bus provides decoupled communication via world.resources.event_bus. Supports typed app events and input messages.

Feature Layer

High-level gameplay systems built on everything below.

Data Flow

A typical frame flows data through the layers like this:

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)
    |-- Script execution
    |-- 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 egui UI state)
    |-- Blit Pass (writes to swapchain)
    |
    v
Present (wgpu surface present)

Feature Flags

Most subsystems are opt-in via Cargo feature flags:

Entity Component System

Nightshade uses freecs, a compile-time code-generated ECS with struct-of-arrays (SoA) storage. freecs generates all entity management, component storage, and query methods at compile time via the ecs! macro, with zero unsafe code.

What is an ECS?

An Entity Component System separates data from behavior:

• Entities are unique identifiers (IDs). They have no data of their own.
• Components are plain data structs attached to entities. Each component type is stored in its own contiguous array.
• Systems are functions that query entities by their component masks and process matching entities.

This is fundamentally different from object-oriented game architectures where a GameObject class owns its data and behavior through inheritance. The OOP approach leads to deep inheritance hierarchies (the "diamond problem"), poor cache locality (objects scattered across the heap), and rigid coupling between data and logic. ECS inverts this: data is organized by type, not by object, and logic operates on slices of data rather than individual objects.

How Archetype Storage Works

freecs uses archetype-based SoA (struct-of-arrays) storage. To understand why this matters, consider how data layouts affect performance.

Array of Structs vs Struct of Arrays

In a traditional OOP game, entities are stored as an array of structs (AoS):

Memory: [Entity0{pos,vel,hp,mesh}] [Entity1{pos,vel,hp,mesh}] [Entity2{pos,vel,hp,mesh}]

When a system iterates over all positions, it loads entire entity structs into cache lines even though it only needs the pos field. The rest is wasted bandwidth.

In SoA storage, each component type gets its own contiguous array:

Positions:  [pos0] [pos1] [pos2] [pos3] ...
Velocities: [vel0] [vel1] [vel2] [vel3] ...
Health:     [hp0]  [hp1]  [hp2]  [hp3]  ...

Now a system iterating over positions reads a dense, contiguous block of memory. Every byte loaded into a cache line is useful. This can be 5-10x faster for large entity counts due to CPU cache prefetching.

Archetype Tables

Not every entity has the same components. An entity with Position | Velocity is different from one with Position | Velocity | Health. freecs groups entities by their component mask (the exact set of components they have) into archetype tables.

Each table stores only entities with identical component masks. Within a table, components are stored in SoA layout:

Table A (mask: Position | Velocity):
  positions:  [p0, p1, p2]
  velocities: [v0, v1, v2]

Table B (mask: Position | Velocity | Health):
  positions:  [p3, p4]
  velocities: [v3, v4]
  healths:    [h3, h4]

When querying for Position | Velocity, the ECS checks each table's mask with a single bitwise AND. Table A matches, Table B also matches (it has a superset of the requested components). Tables whose masks don't include all requested components are skipped entirely without examining any entities.

Component Masks as Bitflags

Each component is assigned a bit position at compile time. An entity's component mask is a single integer where bit N is set if the entity has component N:

LOCAL_TRANSFORM    = 0b0001
GLOBAL_TRANSFORM   = 0b0010
RENDER_MESH        = 0b0100
MATERIAL_REF       = 0b1000

Querying query_entities(RENDER_MESH | LOCAL_TRANSFORM) becomes table_mask & query_mask == query_mask, which is two CPU instructions (AND + CMP). This is why ECS queries scale to millions of entities.

Why freecs?

freecs generates all ECS infrastructure at compile time from a single macro invocation. This means:

• No runtime overhead for component lookups - everything is statically dispatched, no vtables, no hash lookups
• SoA storage - components of the same type are stored in contiguous arrays, optimal for CPU cache utilization
• Archetype tables - entities with the same component mask share a table, so queries skip irrelevant entities entirely
• Zero unsafe - the generated code uses only safe Rust
• Bitflag queries - component presence is checked with bitmask operations, which is a single CPU instruction
• Compile-time monomorphization - accessor methods like get_local_transform() compile down to a direct array index with no indirection

Quick Overview

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

// Spawn an entity with transform and mesh components
let entity = world.spawn_entities(
    LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH | MATERIAL_REF,
    1,
)[0];

// Set component values
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"));

// Query all entities with a specific set of components
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();
}
}

Component Flags

Each component has a corresponding bitflag constant. Combine flags with | to describe which components an entity has:

#![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 component flags is in the Components chapter.

Custom Game ECS

For complex games, define a separate ECS for game-specific data:

#![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,
    }
}
}

Then use both worlds together in your State:

#![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);
    }
}
}

Chapter Guide

• The freecs Macro - Full macro syntax and what gets generated
• Entities - Spawning, despawning, and entity IDs
• Components - All 48 built-in components
• Queries & Iteration - Querying and iterating over entities
• Resources - Global singleton data
• Tags, Events & Commands - Events, command buffers, and deferred operations

The freecs Macro

The freecs::ecs! macro generates the entire World struct, component storage, accessors, query methods, and entity management from a declarative definition.

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,
        }
        Sprite2d {
            sprite: Sprite => SPRITE,
            sprite_animator: SpriteAnimator => SPRITE_ANIMATOR,
        }
    }
    Resources {
        window: Window,
        input: Input,
        graphics: Graphics,
        active_camera: Option<Entity>,
    }
}
}

Nightshade uses three subsystems: Core (3D engine components), Ui (retained UI), and Sprite2d (2D sprites). Component accessors are scoped to their subsystem: world.core.get_light(entity), world.ui.get_ui_layout_node(entity), world.sprite2d.get_sprite(entity).

Each line in the component block declares:

1. A field name (snake_case) - used to generate accessor methods
2. A type - the Rust struct stored for this component
3. A flag constant (UPPER_SNAKE_CASE) - the bitflag for queries

What Gets Generated

From the macro invocation, freecs generates:

The World Struct

#![allow(unused)]
fn main() {
pub struct World {
    // Internal entity storage (archetype tables, free lists, etc.)
    entities: EntityStorage,
    // All global resources
    pub resources: Resources,
}
}

Per-Component Accessors

For each component foo: Foo => FOO, the macro generates:

#![allow(unused)]
fn main() {
// Immutable access
world.core.get_foo(entity) -> Option<&Foo>

// Mutable access
world.core.get_foo_mut(entity) -> Option<&mut Foo>

// Set value
world.core.set_foo(entity, value: Foo)
}

Entity Management

#![allow(unused)]
fn main() {
// Spawn entities with a component mask
world.spawn_entities(flags: ComponentFlags, count: usize) -> Vec<Entity>

// Despawn entities
world.despawn_entities(entities: &[Entity])

// Check if entity has components
world.core.entity_has_components(entity: Entity, flags: ComponentFlags) -> bool
}

Query Methods

#![allow(unused)]
fn main() {
// Query entities matching a component mask
world.core.query_entities(flags: ComponentFlags) -> impl Iterator<Item = Entity>
}

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 per component, powers of 2
}

The Resources Struct

#![allow(unused)]
fn main() {
pub struct Resources {
    pub window: Window,
    pub input: Input,
    pub graphics: Graphics,
    pub active_camera: Option<Entity>,
    // ... all declared resources with Default initialization
}
}

Nightshade's World Definition

Nightshade declares 45 core components, 10 UI components, and 4 sprite components across three subsystems (Core, Ui, Sprite2d), plus 30+ resources. Here is the Core component declaration (simplified paths for readability):

Components

Resources

The Resources block includes:

Conditional resources are included only when their feature flag is enabled, using #[cfg(feature = "...")] attributes in the macro.

Entities

Entities are unique identifiers that group components together. An entity is just an ID - it has no data of its own.

Entity Type

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

Entity is a lightweight handle containing a generation and an index. Generations prevent dangling references - if an entity is despawned and its slot reused, the old Entity handle will no longer match.

Spawning Entities

Basic Spawning

Spawn entities with spawn_entities, specifying component flags and count:

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

Then set component values:

#![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

Spawn multiple entities at once:

#![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

Nightshade provides convenience functions for common entities:

#![allow(unused)]
fn main() {
// Primitives
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));

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

// Sun light
let sun = spawn_sun(world);

// First-person player with character controller
let (player_entity, camera_entity) = spawn_first_person_player(world, Vec3::new(0.0, 2.0, 0.0));
}

Loading Models

Load glTF/GLB 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 {
    spawn_prefab_with_animations(
        world,
        &prefab,
        &result.animations,
        Vec3::new(0.0, 0.0, 0.0),
    );
}
}

Despawning Entities

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

// Despawn entity and all children recursively
despawn_recursive_immediate(world, entity);

// Deferred despawn via command queue
world.queue_command(WorldCommand::DespawnRecursive { entity });
}

Adding Components After Spawn

Add component flags to an existing entity with add_components:

#![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);
}

This is useful when you need to augment entities created by helper functions (like spawn_cube_at) with additional components.

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
}
}

Parent-Child Relationships

Spawn an entity as a child of another:

#![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()
});
}

See Transform Hierarchy for details on parent-child transforms.

Spawning Entities

Basic Entity Spawning

Spawn entities with spawn_entities, specifying component flags:

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

Then set component values:

#![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 Multiple Entities

Spawn multiple entities at once:

#![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

Nightshade provides convenience functions for common entities. Primitive spawn helpers and fly_camera_system / escape_key_exit_system are available from the prelude.

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(),
);
}

Lights

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

To create a point light, manually spawn an entity with the LIGHT flag and set the Light component with LightType::Point:

#![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

All primitive spawn helpers are available from the prelude:

#![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));
}

Physics Objects

Physics spawn convenience functions are available in nightshade::ecs::physics::commands (not in the prelude):

#![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(),
);
}

Available helpers: spawn_static_physics_cube_with_material, spawn_dynamic_physics_cube_with_material, spawn_dynamic_physics_sphere_with_material, spawn_dynamic_physics_cylinder_with_material.

You can also create physics entities manually by combining the appropriate component flags:

#![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 takes the world and position, and returns a tuple of (Entity, Entity) for the player entity and camera entity.

Loading Models

Load glTF/GLB 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),
    );
}
}

Adding Components After Spawn

Add component flags to an existing entity:

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

Despawning Entities

Remove entities from the world:

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

despawn_recursive_immediate(world, entity);
}

Entity with Parent

Spawn an entity as a child:

#![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 provides 59 built-in components across several categories. Core components (45) are listed below. UI components (10) are covered in Retained UI and Sprite2D components (4) in Sprites.

Transform Components

#![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>);
}

Rendering Components

#![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 you can pass &str directly:

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

Camera Components

There is a single CAMERA component flag. The projection type is determined by the Projection enum inside the Camera struct:

#![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,
}
}

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,
}
}

Physics Components

#![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,
}
}

Constructor methods:

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

The component flag for rigid bodies is RIGID_BODY (not RIGID_BODY_COMPONENT).

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,
}
}

Audio Components

Text Components

Geometry Components

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

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

Advanced Components

Queries & Iteration

Queries find entities by their component masks. Since component presence is tracked as bitflags, queries are extremely fast - a single bitmask comparison per archetype table.

Basic Queries

Query entities with specific components using component flags:

#![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 returns all entities that have at least the specified components. An entity with LOCAL_TRANSFORM | GLOBAL_TRANSFORM | RENDER_MESH will match a query for LOCAL_TRANSFORM | GLOBAL_TRANSFORM.

Common Query 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 {
            // 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, use iterator methods:

#![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

Combine queries with additional runtime checks:

#![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 {
        // Process point lights only
    }
}
}

Entity Count

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

Named Entity Lookup

If entities have the Name component:

#![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");
}

The engine also maintains world.resources.entity_names as a HashMap<String, Entity> for fast name-based lookups.

Children Queries

Query children of a specific parent:

#![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 Results

Collect query results for later processing (useful when you need to mutate during iteration):

#![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);
}
}

Iteration with Index

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

Querying Entities

Basic Queries

Query entities with specific components using component flags:

#![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;
    }
}
}

Common Query 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 Results

Filter query results with additional checks:

#![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 {
    }
}
}

Checking Components

Check if an entity has specific components:

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

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

Getting Single Entities

For singleton-like entities, query and take the first:

#![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);
}
}

Entity Count

Count entities matching a query:

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

Named Entity Lookup

If entities have the Name component:

#![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 Queries

Query children of a specific parent:

#![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

When you need the iteration index:

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

Collecting Entities

Collect query results for later processing:

#![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);
}
}

Resources

Resources are global singletons stored in world.resources. Unlike components (which are per-entity), each resource type exists exactly once in the world.

Accessing Resources

All resources are accessed through world.resources:

#![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 Catalog

Time & Window

Input

Graphics

Caches

Scene

Simulation

Communication

Platform

Conditional Resources

Some resources are only available when their feature flag is enabled:

#![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 require GPU access or must be deferred are queued as commands:

#![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 });
}

Commands are processed during the render phase when GPU access is available.

Tags, Events & Commands

This chapter covers the communication and deferred-operation patterns in Nightshade's ECS.

Event Bus

The event bus provides decoupled communication between systems via world.resources.event_bus:

#![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>,
    },
}
}

Publishing Events

Define event structs and publish them:

#![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 Events

Process events in your game loop:

#![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);
            }
        }
    }
}
}

Event Patterns

Events enable one-to-many communication without coupling:

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

// Multiple handlers respond independently
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 that require GPU access or must happen at a specific point in the frame. They are queued during run_systems and processed later during the render phase.

#![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

For operations that don't need GPU access, use immediate functions:

#![allow(unused)]
fn main() {
// Immediate - happens right now
world.despawn_entities(&[entity]);
despawn_recursive_immediate(world, entity);

// Deferred - happens during render phase
world.queue_command(WorldCommand::DespawnRecursive { entity });
}

State Trait Event Handling

The State trait provides a dedicated handle_event method for processing event bus messages:

#![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);
            }
        }
        _ => {}
    }
}
}

This is called by the engine after run_systems during the event dispatch phase of the frame lifecycle.

Input Events

The event bus also carries input events:

#![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,
}
}

Best Practices

1. Keep events small - only include necessary data
2. Process events each frame - don't let the queue grow unbounded
3. Avoid circular events - A handling B which triggers A causes infinite loops
4. Use commands for GPU operations, immediate functions for pure ECS operations

Math & Coordinates

Nightshade uses nalgebra_glm exclusively for all linear algebra. This chapter covers the types, conventions, and common operations you'll use throughout the engine.

Core Types

All types are re-exported through the prelude:

#![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

Nightshade uses a right-handed Y-up coordinate system:

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

• +X points right
• +Y points up
• +Z points toward the camera (out of the screen)
• -Z points into the screen (forward into the scene)

This matches the glTF convention and nalgebra_glm's default handedness.

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

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

// Element-wise multiplication requires component_mul
let element_wise = a.component_mul(&b);
}

The * operator on Vec2/Vec3 performs scalar multiplication, not element-wise. Use component_mul() when you need per-component multiplication.

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);
}

Quaternion Rotations

Nightshade uses quaternions for all rotations. They avoid gimbal lock and interpolate smoothly.

#![allow(unused)]
fn main() {
// Rotation around an axis
let rotation = nalgebra_glm::quat_angle_axis(
    std::f32::consts::FRAC_PI_4,  // 45 degrees
    &Vec3::y(),                     // around Y axis
);

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

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

// Apply rotation to a vector
let rotated = nalgebra_glm::quat_rotate_vec3(&rotation, &direction);
}

Transform Matrices

GlobalTransform stores a 4x4 matrix. LocalTransform stores decomposed translation/rotation/scale:

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

pub struct GlobalTransform(pub Mat4);
}

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;
}

Extracting from Matrices

#![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 from degrees when needed:

#![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 uses a [0, 1] depth range (not [-1, 1] like OpenGL).

Nightshade uses reversed-Z depth, where 0.0 is the far plane and 1.0 is the near plane. This is the opposite of the traditional convention where 0 is near and 1 is far.

Why Reversed-Z?

Floating-point numbers 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 0 and the far plane maps to 1. But perspective projection is highly nonlinear: most of the [0, 1] range is consumed by geometry close to the near plane, leaving very little precision for distant objects. This causes z-fighting (flickering surfaces) at medium to far distances.

Reversed-Z exploits the floating-point distribution by mapping the far plane to 0 (where float precision is highest) and the near plane to 1. The perspective nonlinearity and the floating-point precision curve partially cancel each other out, resulting in nearly uniform depth precision across the entire view range. This is especially important for large outdoor scenes.

Practically, this means:

• Depth clear value is 0.0 (far plane)
• Depth comparison function is Greater or GreaterEqual (closer objects have larger depth values)
• Projection matrices are constructed with reversed_infinite_perspective_rh_zo

Time

All timing information lives in world.resources.window.timing. There is no separate Time resource.

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,
}
}

Accessing 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 time in seconds since the last frame, adjusted by time_speed. Use it for all frame-rate-independent movement:

#![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 is the unscaled delta time before time_speed is applied. Use raw_delta_time for UI animations or anything that should ignore time scaling.

Time Speed

Control the speed of time:

#![allow(unused)]
fn main() {
world.resources.window.timing.time_speed = 0.5;  // Half speed (slow motion)
world.resources.window.timing.time_speed = 2.0;  // Double speed
world.resources.window.timing.time_speed = 0.0;  // Paused
}

delta_time = raw_delta_time * time_speed, so setting time_speed to zero pauses all time-dependent movement without stopping the render loop.

Periodic Actions

Use an accumulator for timed events:

#![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;
    }
}
}

Uptime

uptime_milliseconds counts wall-clock time since the application started. Useful for shader animations and effects:

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

Web Compatibility

Timing uses web_time::Instant instead of std::time::Instant for cross-platform compatibility between native and WASM targets.

The State Trait

The State trait is the primary interface between your game and the Nightshade engine. Every game implements this trait to define its behavior.

Trait Definition

#![allow(unused)]
fn main() {
pub trait State {
    fn title(&self) -> &str { "Nightshade" }
    fn log_config(&self) -> LogConfig { LogConfig::default() }
    fn icon_bytes(&self) -> Option<&'static [u8]> { /* default: built-in icon */ }
    fn initialize(&mut self, _world: &mut World) {}
    fn next_state(&mut self, _world: &mut World) -> Option<Box<dyn State>> { None }
    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 ui(&mut self, _world: &mut World, _ui_context: &egui::Context) {}
    fn secondary_ui(&mut self, _world: &mut World, _window_index: usize, _ui_context: &egui::Context) {}
    fn run_systems(&mut self, _world: &mut World) {}
    fn pre_render(&mut self, _renderer: &mut dyn Render, _world: &mut World) {}
    fn update_render_graph(&mut self, _graph: &mut RenderGraph<World>, _world: &World) {}
    fn handle_event(&mut self, _world: &mut World, _message: &Message) {}
    fn on_keyboard_input(&mut self, _world: &mut World, _key_code: KeyCode, _key_state: ElementState) {}
    fn on_dropped_file(&mut self, _world: &mut World, _path: &std::path::Path) {}
    fn on_dropped_file_data(&mut self, _world: &mut World, _name: &str, _data: &[u8]) {}
    fn on_hovered_file(&mut self, _world: &mut World, _path: &std::path::Path) {}
    fn on_hovered_file_cancelled(&mut self, _world: &mut World) {}
    fn on_gamepad_event(&mut self, _world: &mut World, _event: gilrs::Event) {}
    fn on_suspend(&mut self, _world: &mut World) {}
    fn on_resume(&mut self, _world: &mut World) {}
    fn on_mouse_input(&mut self, _world: &mut World, _state: ElementState, _button: MouseButton) {}
    fn handle_mcp_command(&mut self, _world: &mut World, _command: &McpCommand) -> Option<McpResponse> { None }
    fn after_mcp_command(&mut self, _world: &mut World, _command: &McpCommand, _response: &McpResponse) {}
}
}

All methods have default implementations, so you only need to implement the ones relevant to your game.

Commonly Used Methods

title()

Returns the window title. Defaults to "Nightshade" if not overridden:

#![allow(unused)]
fn main() {
fn title(&self) -> &str {
    "My Awesome Game"
}
}

log_config()

Configure file-based logging. Desktop only, requires the tracing feature. Returns a LogConfig with directory, rotation strategy, and default log filter:

#![allow(unused)]
fn main() {
fn log_config(&self) -> LogConfig {
    LogConfig {
        directory: "logs".to_string(),
        rotation: LogRotation::Daily,
        default_filter: "info".to_string(),
        timestamp_format: "%Y-%m-%d_%H-%M-%S".to_string(),
    }
}
}

Rotation options: LogRotation::PerSession (new file each launch), LogRotation::Daily, LogRotation::Never (append to single file).

initialize()

Called once when the application starts. Use this to set up your initial game state:

#![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. This is where your game logic lives:

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

Optional Methods

ui()

For egui-based user interfaces. Requires the egui feature. Note that world comes before ui_context:

#![allow(unused)]
fn main() {
fn ui(&mut self, world: &mut World, ui_context: &egui::Context) {
    egui::Window::new("Debug").show(ui_context, |ui| {
        ui.label(format!("FPS: {:.0}", world.resources.window.timing.frames_per_second));
        ui.label(format!("Entities: {}", world.core.query_entities(RENDER_MESH).count()));
    });
}
}

on_keyboard_input()

Handle keyboard events directly:

#![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),
            _ => {}
        }
    }
}
}

on_mouse_input()

Handle mouse button events:

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

on_gamepad_event()

Handle gamepad button presses:

#![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(),
            _ => {}
        }
    }
}
}

on_suspend() / on_resume()

Android lifecycle hooks. Called when the app is suspended (backgrounded) or resumed. Use these to release and restore GPU resources:

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

fn on_resume(&mut self, world: &mut World) {
    self.restore_state(world);
}
}

secondary_ui()

For multi-window applications using egui. Called with a window_index parameter that identifies which secondary window is being drawn, allowing you to render different UI per window. Requires the egui feature:

#![allow(unused)]
fn main() {
fn secondary_ui(&mut self, world: &mut World, window_index: usize, ui_context: &egui::Context) {
    match window_index {
        0 => {
            egui::Window::new("Inspector").show(ui_context, |ui| {
                ui.label("Secondary window 0");
            });
        }
        1 => {
            egui::Window::new("Scene View").show(ui_context, |ui| {
                ui.label("Secondary window 1");
            });
        }
        _ => {}
    }
}
}

configure_render_graph()

Customize the rendering pipeline. Called once during initialization. The default implementation sets up bloom, post-processing, and swapchain blit passes. Override this to replace or extend the default 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 each frame to update render graph state dynamically:

#![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 rendering begins each frame. Useful for custom GPU uploads or renderer state changes:

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

next_state()

Allows transitioning to a different State. Return Some(new_state) to switch:

#![allow(unused)]
fn main() {
fn next_state(&mut self, world: &mut World) -> Option<Box<dyn State>> {
    if self.transition_to_gameplay {
        Some(Box::new(GameplayState::new()))
    } else {
        None
    }
}
}

on_dropped_file() / on_dropped_file_data()

Handle files dropped onto the window:

#![allow(unused)]
fn main() {
fn on_dropped_file(&mut self, world: &mut World, path: &Path) {
    if path.extension() == Some("glb".as_ref()) {
        self.load_model(world, path);
    }
}

fn on_dropped_file_data(&mut self, world: &mut World, name: &str, data: &[u8]) {
    self.process_dropped_data(world, name, data);
}
}

on_hovered_file() / on_hovered_file_cancelled()

Handle file drag hover events:

#![allow(unused)]
fn main() {
fn on_hovered_file(&mut self, world: &mut World, path: &Path) {
    self.show_drop_indicator = true;
}

fn on_hovered_file_cancelled(&mut self, world: &mut World) {
    self.show_drop_indicator = false;
}
}

handle_mcp_command()

Intercept MCP commands before the engine processes them. Requires the mcp feature. Return Some(response) to handle a command yourself, or None to let the engine handle it with default behavior:

#![allow(unused)]
fn main() {
#[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
fn handle_mcp_command(
    &mut self,
    world: &mut World,
    command: &McpCommand,
) -> Option<McpResponse> {
    match command {
        McpCommand::SpawnEntity { name, .. } => {
            self.pending_scene_refresh = true;
            None
        }
        _ => None,
    }
}
}

See AI Integration for full details on the MCP system.

after_mcp_command()

Called after an MCP command has been processed (either by the engine or by your handle_mcp_command override). Receives both the command and the response. Useful for recording undo entries, refreshing UI state, or reacting to the outcome of MCP operations:

#![allow(unused)]
fn main() {
#[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
fn after_mcp_command(
    &mut self,
    world: &mut World,
    command: &McpCommand,
    response: &McpResponse,
) {
    if let McpResponse::Success(_) = response {
        match command {
            McpCommand::SpawnEntity { name, .. } => {
                self.scene_tree_dirty = true;
            }
            McpCommand::DespawnEntity { .. } => {
                self.scene_tree_dirty = true;
            }
            _ => {}
        }
    }
}
}

handle_event()

Handle custom EventBus messages:

#![allow(unused)]
fn main() {
fn handle_event(&mut self, world: &mut World, message: &Message) {
    match message {
        Message::Custom(data) => self.process_event(world, data),
        _ => {}
    }
}
}

Launching Your Game

Use the nightshade::launch function to run your game:

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

Or with an HDR skybox:

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

Main Loop

Understanding the frame lifecycle helps you structure game logic correctly and debug timing issues.

Frame Execution Order

Each frame executes in this order:

1.  Process window/input events (winit)
2.  Update input state from events
3.  Calculate delta time
4.  Begin egui frame (if enabled)
5.  Call State::run_systems() — Your game logic
6.  Dispatch EventBus messages
7.  Process MCP commands (if mcp feature enabled)
    - Calls State::handle_mcp_command() (pre-hook)
    - Executes command
    - Calls State::after_mcp_command() (post-hook)
8.  Run FrameSchedule — Engine systems dispatched in order:
    a. Initialize and update audio (if audio feature)
    b. Update camera aspect ratios
    c. Step physics simulation (if physics feature)
    d. Run scripts (if scripting feature)
    e. Update tweens
    f. Update animation players
    g. Apply animations to transforms
    h. Propagate transform hierarchy
    i. Update instanced mesh caches
    j. Run retained UI systems (input sync, picking, layout, rendering)
    k. Reset mouse, keyboard, and touch input state
    l. Process deferred commands
    m. Cleanup unused resources
9.  Execute render graph passes
10. End egui frame
11. Present to swapchain

The frame schedule is stored as a resource at world.resources.frame_schedule. You can customize it in State::initialize() to insert your own systems between engine systems, remove systems you don't 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);
}
}

See system_names in the prelude for the full list of engine system name constants.

Timing

All timing information is accessed through 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;
}
}

Fixed Timestep Physics

Physics runs at a fixed 60 Hz regardless of frame rate:

#![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);
}
}

Physics Interpolation

For smooth rendering between physics steps:

#![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

Before Physics

Place movement and input handling before physics:

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

    player_movement_system(world);

    ai_decision_system(world);
}
}

After Physics

Query physics results after the step:

#![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 Usage

Always multiply movement by delta time for frame-rate independence:

#![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;
    }
}
}

Accumulating Time

For periodic actions:

#![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

Desktop

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

WASM

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

VR (OpenXR)

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

Debugging Frame Issues

Frame Spikes

If you see occasional stuttering:

#![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);
    }
}
}

Consistent Slowdown

Profile your systems:

#![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);
    }
}
}

Best Practices

1. Don't block the main thread: Use async for file I/O
2. Batch similar operations: Process all enemies together, not interleaved
3. Use spatial partitioning: For collision checks with many entities
4. Profile before optimizing: Measure, don't guess
5. Consider fixed timestep for gameplay: Not just physics

World & Resources

The World is the central data container in Nightshade. It holds all entities, components, and global resources.

World Structure

The World is generated by the freecs::ecs! macro and contains:

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

Resources

Resources are global singletons accessible throughout the engine:

#![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(feature = "scripting")]
    pub script_runtime: ScriptRuntime,
    #[cfg(feature = "openxr")]
    pub xr: XrResources,
    #[cfg(all(feature = "steam", not(target_arch = "wasm32")))]
    pub steam: SteamResources,
    #[cfg(feature = "physics")]
    pub picking_world: PickingWorld,
    pub gpu_picking: GpuPicking,
    #[cfg(feature = "sdf_sculpt")]
    pub sdf_world: SdfWorld,
    #[cfg(feature = "sdf_sculpt")]
    pub sdf_materials: SdfMaterialRegistry,
    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_metadata: HashMap<Entity, HashMap<String, MetadataValue>>,
    pub pending_particle_textures: Vec<ParticleTextureUpload>,
    pub ibl_views: IblViews,
    pub retained_ui: RetainedUiState,
    pub frame_schedule: FrameSchedule,
    pub sprite_slot_allocator: SpriteSlotAllocator,
    #[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
    pub mcp_command_queue: CommandQueue,
}
}

There is no separate Time resource. Timing information is accessed through world.resources.window.timing.

Accessing Resources

Resources are accessed through world.resources:

#![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

Time & Timing

Timing is accessed through world.resources.window.timing:

#![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;
}

The WindowTiming struct contains:

#![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

#![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 Settings

#![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

#![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

Operations that require GPU access or must be deferred are queued as WorldCommand values and processed during the render phase:

#![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 });
}

For immediate recursive despawning without deferral:

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

Scene Hierarchy

Nightshade supports parent-child relationships between entities, enabling hierarchical transforms where child entities move relative to their parents.

Parent-Child Relationships

Setting a Parent

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

When you set a parent, the child's LocalTransform becomes relative to the parent's position, rotation, and scale.

Getting Children

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

Removing a Parent

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

Transform Propagation

Each frame, transforms propagate through the hierarchy:

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

How It Works

1. Find all entities marked with LocalTransformDirty
2. Mark all their descendants as dirty
3. Sort entities by depth (parents before children)
4. For each entity:
   • If has parent: GlobalTransform = parent.GlobalTransform * LocalTransform
   • If no parent: GlobalTransform = LocalTransform.to_matrix()
5. Remove the LocalTransformDirty marker

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: Position, rotation, scale relative to parent (or world if no parent)
• GlobalTransform: Final world-space transformation matrix used for rendering

Scene Serialization

Scenes can be saved and loaded for level editing and persistence.

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 a Scene

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

Loading a Scene

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

Binary Serialization

For faster loading and smaller file sizes:

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

Recursive Operations

Despawning with Children

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

This removes the entity and all its descendants from the world.

Cloning Hierarchy

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

Creates a deep copy of an entity and all its children.

Example: Building a Robot Arm

#![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);
}
}

Rotating the lower arm automatically rotates the upper arm and hand with it.

Input System

Input state is aggregated each frame into world.resources.input. Nightshade supports keyboard, mouse, and gamepad input through both polling and event-driven patterns.

Polling Input

Check input state at any point during run_systems:

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

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

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

Event-Driven Input

Handle input events through the State trait:

#![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

Nightshade provides ready-to-use input systems:

#![allow(unused)]
fn main() {
fn run_systems(&mut self, world: &mut World) {
    // WASD + mouse fly camera
    fly_camera_system(world);

    // Escape key exits the application
    escape_key_exit_system(world);

    // Pan-orbit camera (middle mouse drag to orbit, scroll to zoom)
    pan_orbit_camera_system(world);
}
}

Chapters

• Keyboard & Mouse - Key detection, mouse tracking, cursor control
• Gamepad Support - Controller input, analog sticks, rumble

Keyboard & Mouse

Handle keyboard and mouse input through the input resources.

Keyboard Input

Checking Key State

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

    // Key currently held down
    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

Direct Event Handling

Handle key events in the State trait:

#![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 Input

Mouse Position

#![allow(unused)]
fn main() {
let mouse = &world.resources.input.mouse;
let position = mouse.position;  // Screen coordinates (x, y)
}

Mouse Movement (Delta)

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

Mouse Buttons

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

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

// Button just pressed
if mouse.state.contains(MouseState::LEFT_JUST_PRESSED) {
    start_drag();
}

// Button just released
if mouse.state.contains(MouseState::LEFT_JUST_RELEASED) {
    end_drag();
}

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

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

Mouse Scroll

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

Direct Event Handling

#![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(),
        _ => {}
    }
}
}

Movement Input Pattern

Common WASD movement:

#![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 Pattern

First-person camera control:

#![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) {
            // Horizontal rotation (yaw)
            let yaw = nalgebra_glm::quat_angle_axis(
                -delta.x * sensitivity,
                &Vec3::y(),
            );

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

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

Cursor Visibility

For first-person games:

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

Key Bindings

Create rebindable controls:

#![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 Buffer

Buffer inputs for responsive controls:

#![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

Nightshade provides cross-platform gamepad support through the gilrs library.

Enabling Gamepad

Gamepad requires the gamepad feature:

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

Gamepad Resource

The gamepad state lives in world.resources.input.gamepad, which wraps the gilrs library:

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

The engine automatically initializes gilrs and tracks the active gamepad.

Querying the Active Gamepad

Use query_active_gamepad to get a gilrs gamepad handle for polling input:

#![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();
        }
    }
}
}

Button Input

Button States

#![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

Analog Sticks

#![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);
}
}

Axis values range from -1.0 to 1.0.

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-Based Input

Handle gamepad events in the State trait using raw gilrs events:

#![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

#![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

Nightshade provides an event bus for decoupled communication between systems. Events are published to a queue and consumed by interested systems.

EventBus

The event bus is accessible through world.resources.event_bus:

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

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

Defining Custom Events

Create a struct for your event:

#![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 Events

Use publish_app_event to send events:

#![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 Events

Process events in your game loop:

#![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;
}
}

Event Patterns

One-to-Many Communication

Events allow one system to notify multiple listeners without direct coupling:

#![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);
}
}

Deferred Actions

Events let you schedule actions without immediate execution:

#![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 Pattern

For queries that need responses, use a shared resource:

#![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 event bus also handles input-related messages:

#![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 },
}
}

Best Practices

1. Keep events small: Only include necessary data
2. Use descriptive names: PlayerDied not Event1
3. Process events each frame: Don't let the queue grow unbounded
4. Consider event ordering: Events are processed in FIFO order
5. Avoid circular events: A handling B which triggers A can cause infinite loops

Rendering Architecture

This chapter explains how ECS data flows to pixels on screen. Nightshade's renderer is built on wgpu and uses a dependency-driven render graph to orchestrate all GPU work.

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

All rendering goes through the Render trait, which abstracts the GPU backend:

#![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 that owns the wgpu device, queue, surface, and render graph.

WgpuRenderer

The renderer holds all GPU state:

• Instance, Adapter, Device, Queue - wgpu initialization chain
• Surface - the window's swapchain
• RenderGraph - the dependency-driven frame graph with all passes
• Resource IDs - handles to all transient and external textures
• Texture Cache - uploaded GPU textures
• Font Atlas - glyph texture for text rendering
• Camera Viewports - render-to-texture for editor viewports

Initialization

When the application starts:

1. Instance creation - wgpu creates a wgpu::Instance, which selects the GPU backend (Vulkan on Linux/Windows, Metal on macOS, DX12 on Windows, WebGPU on WASM). The instance is the entry point to the GPU API.
2. Adapter request - The instance queries available GPUs and selects one. The adapter describes the GPU's capabilities (supported texture formats, limits, features).
3. Device and queue - The adapter opens a logical device (the interface for creating GPU resources) and a command queue (where command buffers are submitted for execution). All GPU work goes through the queue.
4. Surface configuration - The window surface is configured with the GPU's preferred format (typically Bgra8UnormSrgb) and the presentation mode (Fifo for vsync, Mailbox for low-latency).
5. Pass creation - All built-in passes are created. Each pass constructs its shader modules, pipeline layouts, render pipelines, bind group layouts, and any persistent GPU buffers during initialization.
6. Render graph construction - A RenderGraph<World> is constructed with all transient textures and passes registered.
7. User configuration - State::configure_render_graph() is called, allowing the game to add custom passes, textures, or modify the pipeline.
8. Graph compilation - The graph builds dependency edges, topologically sorts passes, computes resource lifetimes, determines aliasing, and calculates load/store operations.

Transient Textures

The renderer declares all intermediate textures at initialization:

External textures (provided each frame):

• swapchain - the window surface texture
• viewport_output - editor viewport render target

Per-Frame Rendering

Each frame, render_frame() executes:

1. Sync data - Upload transform matrices, material uniforms, light data, and animation bone matrices to GPU buffers
2. Process commands - Handle queued WorldCommand values (texture loads, screenshots, etc.)
3. Set swapchain texture - Acquire the next swapchain image and bind it as the external swapchain resource
4. Call State::update_render_graph() - Allow per-frame graph modifications
5. Execute render graph - Run all enabled, non-culled passes in topological order, collecting command buffers
6. Submit - Send command buffers to the GPU queue
7. Present - Display the frame

Resize Handling

When the window resizes:

1. The surface is reconfigured with new dimensions
2. All transient textures are resized to match
3. The render graph recomputes resource aliasing
4. Passes that cache bind groups invalidate them

SSGI textures resize to half the new dimensions.

Custom Rendering

Games customize rendering through two State methods:

• configure_render_graph() - Called once at startup. Add custom passes, textures, and change the pipeline structure.
• update_render_graph() - Called each frame. Enable/disable passes, update pass parameters.

See The Render Graph for details on how the graph system works, and Custom Passes for implementation examples.

The Render Graph

Live Demos: Custom Pass | Custom Multipass | Render Layers

The render graph is a dependency-driven frame graph that automatically schedules GPU work. Instead of manually ordering render passes, you declare what each pass reads and writes, and the graph figures out the rest.

The Problem: Manual Pass Ordering

A modern renderer has dozens of passes: shadow maps, geometry, SSAO, SSR, bloom, tonemapping, UI. Each reads from and writes to intermediate textures. Without automation, you must:

1. Manually order passes - Shadow maps before geometry, geometry before SSAO, SSAO before compositing. Add one pass and you must figure out where it fits in the chain. Reorder one pass and you break three others.
2. Manually manage textures - Allocate intermediate textures, track which ones are alive when, decide when to clear vs load, when to store vs discard. Get it wrong and you see black screens or stale data from previous frames.
3. Manually optimize memory - SSAO's intermediate texture and SSR's intermediate texture might never be alive at the same time. Without aliasing, you waste VRAM on textures that could share the same memory.
4. Manually handle dynamic passes - Disabling bloom shouldn't require rewriting the compositing pass's inputs. But with hardcoded ordering, every conditional pass is an if statement that must be threaded through the entire pipeline.

A render graph (also called a frame graph, as described in the Frostbite GDC 2017 talk "FrameGraph: Extensible Rendering Architecture in Frostbite") solves all of this. You describe what each pass needs, and the graph handles ordering, memory, and lifecycle.

How It Works

The render graph models the frame as a directed acyclic graph (DAG) where:

• Nodes are render passes
• Edges are resource dependencies (an edge from A to 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 dependency edges, a topological sort produces a valid execution order. The graph can then analyze resource lifetimes across that order to alias memory, compute load/store operations, and cull unused passes.

The key insight is that passes declare their dependencies declaratively through named slots, not imperatively through explicit ordering. This makes the system composable: adding a new pass means declaring what it reads and writes, not editing every other pass that touches the same resources.

Why a Render Graph?

• Automatic ordering - Passes are topologically sorted based on read/write dependencies
• Automatic memory management - Transient textures with non-overlapping lifetimes share GPU memory
• Automatic load/store ops - The graph determines whether to Clear, Load, Store, or Discard each attachment
• Dead pass culling - Passes that don't contribute to any external output are automatically skipped
• Runtime toggling - Passes can be enabled/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.

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

When compile() is called:

1. Build dependency edges - For each resource, the graph creates an edge from writer to reader
2. Topological sort - Passes are sorted so every pass executes after its dependencies
3. Compute store ops - Determine Store vs Discard for each resource write
4. Compute clear ops - Determine which pass performs the initial Clear for each resource
5. Compute resource lifetimes - Track first_use and last_use for each transient resource
6. Compute resource aliasing - Transient resources with non-overlapping lifetimes share GPU memory
7. Dead pass culling - Passes that don't contribute to external outputs are marked for skipping

Sub-Chapters

• Resources & Textures - Resource types, builders, external vs transient
• Passes & the PassNode Trait - Implementing custom passes
• Dependency Resolution & Scheduling - How passes are ordered
• Resource Aliasing & Memory - GPU memory sharing
• Custom Passes - Full examples of custom rendering

Resources & Textures

Render graph resources are GPU textures and buffers that passes read from and write to. Each resource has a ResourceId handle used for all graph operations.

ResourceId

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

ResourceId is an opaque handle returned when you declare a resource. Pass it to add_pass() slot bindings to connect passes to resources.

Resource Types

External vs Transient

External resources are owned by you. You provide them each frame via set_external_texture(). The graph never creates or destroys them. The swapchain texture is the most common external resource.

Transient resources are owned by the graph. The graph creates GPU textures/buffers as needed, tracks their lifetimes, and can alias them (share memory between resources with non-overlapping lifetimes) to minimize VRAM usage.

Creating Color Textures

Use the fluent builder:

#![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

For creating multiple similar resources, use templates:

#![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

For batch allocation from a 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 each frame before execute():

#![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:

#![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)?;
}

This invalidates the aliasing info and triggers reallocation on the next execution.

Passes & the PassNode Trait

Every render pass implements the PassNode trait to declare its resource dependencies and execute GPU commands.

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.

Slot-Based Resource Binding

Passes declare named slots that map to graph resources. The slot names are strings that match the keys in the add_pass() bindings:

#![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![] }
    // ...
}
}

When adding the pass to the graph, you bind slot names to resource IDs:

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

PassExecutionContext

The context provides access to resources during execution:

#![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 automatically determines the correct load and store operations:

• LoadOp::Clear - Used when this pass is the first writer and the resource has a clear value
• LoadOp::Load - Used when a previous pass already wrote to this resource
• StoreOp::Store - Used when another pass will read this resource later
• StoreOp::Discard - Used when no subsequent pass reads this resource

You don't choose these yourself - the get_color_attachment() and get_depth_attachment() methods return the correct ops.

Prepare Phase

prepare() is called before execution for each non-culled pass. Use it to upload uniforms:

#![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 resources (e.g. after resize), invalidate_bind_groups() is called on affected passes. Clear any cached bind groups:

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

The graph tracks resource versions and only invalidates passes that reference changed resources.

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![])
    }
}
}

Sub-Graph Execution

Passes can trigger sub-graph execution for multi-pass effects:

#![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())
}
}

Dependency Resolution & Scheduling

The render graph automatically orders passes based on their resource dependencies. This chapter explains how that works.

Dependency Edge Construction

When compile() is called, the graph builds edges between passes:

1. Iterate through all passes
2. For each resource a pass reads, find the pass that last wrote to it
3. Create 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 is treated as both a reader and a writer. Optional reads create edges only if a writer exists.

Topological Sort

After building edges, the graph performs a topological sort using petgraph. A topological sort of a DAG produces a linear ordering where for every edge A -> B, A appears before B. This guarantees every pass runs after all the passes that produce its inputs.

For a graph with V passes and E dependency edges, topological sorting runs in O(V + E) time using Kahn's algorithm (iteratively remove nodes with no incoming edges) or depth-first search. petgraph implements this efficiently.

If the graph contains cycles (A depends on B, B depends on A), no valid topological ordering exists and compilation fails with RenderGraphError::CyclicDependency. Cycles in a render graph indicate a logical error: two passes cannot each depend on the other's output.

Dead Pass Culling

Not all passes may contribute to the final output. The graph uses backward reachability from external resources to determine which passes are needed:

1. Start with all external resources as "required"
2. Walk backward through the execution order
3. A pass is required if it writes to a required resource (or has no writes/reads_writes, indicating side effects)
4. If a pass is required, all resources it reads become required too
5. Passes not marked as required are 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

Runtime Pass Toggling

Passes can be enabled or disabled at runtime without recompiling the graph:

#![allow(unused)]
fn main() {
graph.set_pass_enabled("bloom_pass", false)?;
}

When a pass is disabled, its execute() method receives is_pass_enabled() == false. The pass can check this and skip all 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
}
}

Recompilation

The graph tracks a needs_recompile flag. Adding or removing passes sets this flag. On the next execute(), the graph:

1. Removes all existing edges
2. Rebuilds dependency edges
3. Re-sorts topologically
4. Recomputes store ops, clear ops, lifetimes, and aliasing

This happens automatically - you don't need to call compile() again manually.

Store and Clear Operations

Store Operations

On tile-based GPU architectures (mobile GPUs, Apple Silicon), render pass attachments are stored in fast on-chip tile memory during rendering. At the end of the render pass, the driver must decide whether to write that tile memory back to main VRAM. This write-back is called a "store" operation and it has significant bandwidth cost.

For each resource write, the graph determines whether to store the result:

• Store - If any later pass reads this resource, or if it's an external resource with force_store. The data must survive to be read later.
• Discard - If no later pass reads this resource. The GPU can skip the write-back entirely, saving memory bandwidth. This is a significant optimization on tile-based architectures.

Clear Operations

Similarly, at the start of a render pass, the GPU must decide what to do with the existing attachment contents:

• Clear - Write a known value (black, zero depth) into the attachment. This is cheap because the GPU can initialize tile memory without reading from VRAM.
• Load - Read the existing contents from VRAM into tile memory. This is necessary when a previous pass has already written data that this pass needs to preserve.

The first pass that writes to a resource with a clear value (clear_color or clear_depth) gets a LoadOp::Clear. All subsequent writers get LoadOp::Load.

These are computed during compilation and used automatically by get_color_attachment() and get_depth_attachment(). Getting these wrong is a common source of rendering bugs: using Clear when you should Load erases previous passes' work; using Load when you should Clear wastes bandwidth loading garbage data.

Resource Aliasing & Memory

Transient resources with non-overlapping lifetimes can share the same GPU memory. The render graph computes this automatically to minimize VRAM usage.

Why Aliasing Matters

A modern rendering pipeline might use 15+ intermediate textures: shadow maps, SSAO buffers, bloom mip chains, SSR buffers, selection masks, and more. At 1080p, a single Rgba16Float texture is about 16 MB. At 4K, it's 64 MB. Without aliasing, all these textures exist simultaneously in VRAM even if they're never alive at the same time.

Resource aliasing is the GPU equivalent of stack allocation: the same memory region is reused by different variables (textures) whose lifetimes don't overlap. The render graph's execution order gives a total ordering of pass execution, which makes it possible to compute exact lifetimes and find aliasing opportunities.

This technique is inspired by the Frostbite engine's frame graph (GDC 2017) and is standard practice in modern engines. The savings can be 30-50% of transient VRAM depending on the pipeline.

How It Works

After topological sorting, the graph knows the execution order. For each transient resource, it computes:

• first_use - The pass index where the resource is first written
• last_use - The pass index where the resource is last read

If resource A's lifetime ends before resource B's lifetime begins, and they have compatible formats, 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

Here, A's lifetime is [0, 1] and C's lifetime is [2, 3]. Since they don't overlap and have compatible descriptors, the graph assigns them to the same pool slot.

Compatibility Requirements

Two textures can alias if they have identical:

• 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 can alias if the pool's size is at least as large as the reuser's, and usage flags match exactly.

If a reuser needs additional usage flags, the pool texture is recreated with the combined flags.

Pool-Based Allocation

The aliasing system uses a pool with a BinaryHeap for efficient slot reuse:

1. Sort transient resources by first_use
2. For each resource:
   • Check if any pool slot has a lifetime_end before this resource's first_use
   • If a compatible slot is found, reuse it
   • Otherwise, allocate a new pool slot
3. Each pool slot holds at most one GPU texture/buffer at a time

The heap is ordered by lifetime_end (min-heap), so the earliest-expiring slots are checked first.

Bind Group Invalidation

When a transient resource gets a new GPU texture (because the pool slot was reallocated), any passes that reference that resource need to recreate their bind groups.

The graph tracks a version number per resource. When a resource's version changes between frames:

1. Find all passes that read, write, or reads_write that resource
2. Call invalidate_bind_groups() on those passes
3. Update the stored version

This ensures passes always reference the correct GPU texture, even after aliasing changes or window resizes.

Memory Savings

For a typical scene with 15+ transient textures, aliasing can reduce VRAM usage significantly. For example:

• ssao_raw and ssgi_raw may never be alive at the same time
• Shadow depth maps are only needed during shadow passes, then their memory can be reused
• Intermediate blur textures from bloom can share memory with SSR blur textures

The exact savings depend on pass ordering and resource sizes.

External Resources

External resources (swapchain, viewport outputs) are never aliased. They are always owned externally and provided fresh each frame.

Custom Passes

Customize the rendering pipeline by adding your own passes to the render graph.

configure_render_graph()

Override this State method to add custom passes at startup:

#![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

The RenderResources struct provides resource IDs for all built-in textures:

update_render_graph()

For per-frame changes, use update_render_graph():

#![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

Use the built-in pass types in your custom graph:

#![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

Instead of add_pass(), you can use the fluent builder:

#![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);
}

The PassBuilder automatically adds the pass to the graph when it goes out of scope (via Drop).

Conditional Passes

Enable or disable passes based on settings:

#![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),
            ],
        );
    }
}
}

Or toggle 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);
}
}

Default Pipeline

If you don't override configure_render_graph(), the default implementation adds:

1. BloomPass - HDR bloom at half resolution
2. PostProcessPass - Tonemapping and compositing
3. BlitPass - Copy to swapchain

The engine always adds the core passes (clear, sky, shadow, mesh, skinned mesh, water, grass, grid, lines, selection) regardless of your custom configuration.

The Default Pipeline

The engine constructs a default render graph with all built-in passes. This chapter shows the complete pass ordering and data flow.

Pass Execution Order

The graph topologically sorts these passes based on their dependencies. The typical execution order is:

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.  WaterPass           - Render water surface
8.  WaterMeshPass       - Render water mesh displacement
9.  GrassPass           - Render GPU-instanced grass
10. GridPass            - Render infinite ground grid
11. LinesPass           - Render debug lines
12. SelectionMaskPass   - Generate selection mask for editor
13. OutlinePass         - Render selection outline

    --- User passes (from configure_render_graph) ---

14. BloomPass           - HDR bloom (default)
15. PostProcessPass     - Tonemapping and compositing (default)
16. BlitPass            - Copy to swapchain (default)

    --- UI passes ---

17. EguiPass            - egui UI (if egui feature enabled)

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
                        |
WaterPass --------> 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, but can be disabled at runtime.

ClearPass

Clears scene_color to black and depth to 0.0 (reversed-Z far plane).

SkyPass

Renders the procedural atmosphere or solid background color. Controlled by world.resources.graphics.atmosphere.

ScenePass

A simple scene rendering pass for basic objects.

ShadowDepthPass

Renders the shadow map. See Shadow Mapping.

MeshPass

The main PBR mesh rendering pass. See Geometry Passes.

SkinnedMeshPass

Renders animated skeletal meshes with GPU skinning.

Selection Passes

SelectionMaskPass and OutlinePass generate and render editor selection outlines.

User-Configurable Passes (Default)

These passes are added by the default configure_render_graph() implementation. Override this 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 includes bloom and tonemapping. To enable SSAO, SSGI, or SSR, override configure_render_graph() and add the appropriate passes. See Post-Processing for the full list of available post-processing passes and Custom Passes for examples.

Shadow Mapping

Live Demos: Shadows | Spotlight Shadows

Nightshade uses cascaded shadow mapping for directional lights and a shadow atlas for spotlights.

How Shadow Mapping Works

Shadow mapping is a two-pass technique. In the first pass, the scene is rendered from the light's point of view into a depth-only texture (the shadow map). In the second pass (the main geometry pass), each fragment projects itself into the light's coordinate space and compares its depth against the stored shadow map value. If the fragment is farther from the light than the shadow map records, something closer is blocking the light, and the fragment is in shadow.

The core idea is that the shadow map captures the "closest surface to the light" at every pixel. Any surface behind that closest surface must be occluded.

The Resolution Problem

A single shadow map has finite resolution. A directional light (like the sun) illuminates the entire scene, but the shadow map must cover it all. Objects near the camera need high-resolution shadows (you can see the shadow edges clearly), while distant objects can tolerate lower resolution. A single shadow map wastes resolution on distant geometry while providing insufficient detail nearby.

Cascaded Shadow Maps (CSM)

CSM solves this by splitting the camera's view frustum into multiple depth ranges (cascades), each with its own shadow map. Near cascades cover a small area at high texel density. Far cascades cover a large area at lower density.

The ShadowDepthPass renders 4 shadow cascades (NUM_SHADOW_CASCADES = 4) into a single large depth texture:

• Cascade 0 - Near range, highest detail (covers roughly 0-10% of the view distance)
• Cascade 1 - Mid-near range (covers roughly 10-30%)
• Cascade 2 - Mid-far range (covers roughly 30-60%)
• Cascade 3 - Far range, lowest detail (covers roughly 60-100%)

Shadow Map Resolution

Each cascade uses a quarter of the texture (rendered into its own viewport region), giving each cascade an effective resolution of 4096x4096 on native.

How Cascades Work

Each frame, the engine:

1. Frustum computation - Computes the camera's view frustum (the truncated pyramid defined by the near plane, far plane, and field of view)
2. Frustum splitting - Divides the frustum into 4 depth ranges using a logarithmic-linear split scheme. Logarithmic splitting gives more resolution to nearby cascades, while linear splitting distributes more evenly. A blend between the two (typically 0.5-0.8 toward logarithmic) produces good results across most scenes.
3. Tight projection fitting - For each cascade, computes the 8 corner points of that frustum slice, transforms them into light space, and builds a tight orthographic projection matrix that just encompasses those points. This minimizes wasted shadow map texels.
4. Shadow rendering - Renders all shadow-casting meshes from the directional light's perspective into each cascade's viewport region of the shadow texture.

During the mesh pass, each fragment determines which cascade to sample based on its distance from the camera. The shader selects the highest-resolution cascade that contains the fragment, projects it into that cascade's light-space coordinates, and performs the depth comparison.

Cascade Selection and Blending

At cascade boundaries, shadows can exhibit visible seams where resolution changes abruptly. The fragment shader compares the fragment's view-space depth against cascade split distances to choose the appropriate cascade. Some implementations blend between adjacent cascades at boundaries for smooth transitions.

Spotlight Shadow Atlas

Spotlights use a separate shadow atlas:

Each spotlight that has cast_shadows: true is assigned a slot in the atlas. The atlas is subdivided to accommodate multiple spotlights.

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 manually configure:

#![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 occurs because the shadow map has limited 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 causes the surface to falsely report itself as in shadow. This creates a Moiré-like pattern of alternating lit and shadowed stripes on surfaces.

Shadow bias adds a small depth offset during the shadow comparison, pushing the comparison point slightly toward the light so surfaces don't self-shadow. The trade-off is that too much bias causes peter-panning: shadows detach from the base of objects because the bias pushes them too far away.

shadow_bias controls this 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 with higher effective resolution.

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 depth buffer. Each pass handles a different type of geometry.

ClearPass

Clears scene_color to black and depth to 0.0 (reversed-Z far plane). Always runs first.

Writes: scene_color, depth

SkyPass

Renders the sky/atmosphere background. Controlled by world.resources.graphics.atmosphere:

• Atmosphere::None - Solid background color (default)
• Atmosphere::Sky - Procedural clear sky gradient
• Atmosphere::CloudySky - Procedural sky with volumetric clouds
• Atmosphere::Space - Procedural starfield
• Atmosphere::Nebula - Procedural nebula with stars
• Atmosphere::Sunset - Procedural sunset gradient
• Atmosphere::DayNight - Procedural day/night cycle driven by hour parameter
• Atmosphere::Hdr - HDR environment cubemap

Writes: scene_color

ScenePass

Basic scene rendering pass for simple objects.

Reads/Writes: scene_color, depth

MeshPass

The main PBR mesh rendering pass. Renders all entities with RENDER_MESH | MATERIAL_REF | GLOBAL_TRANSFORM. Features:

• PBR shading with metallic-roughness workflow
• Cascaded shadow mapping - Samples the shadow depth texture
• Spotlight shadows - Samples the spotlight shadow atlas
• Normal mapping - Per-pixel normals from normal textures
• Alpha modes - Opaque, mask (alpha cutoff), and blend
• Entity ID output - Writes entity IDs for GPU picking
• View normals output - Writes view-space normals for SSAO/SSGI

Reads: shadow_depth, spotlight_shadow_atlas Writes: scene_color, depth, entity_id, view_normals

SkinnedMeshPass

Renders animated skeletal meshes. Reads bone matrices from the skinning buffer and transforms vertices on the GPU.

Reads: shadow_depth, spotlight_shadow_atlas Writes: scene_color, depth

WaterPass

Renders water surfaces with procedural wave displacement, reflections, and refractions.

Reads/Writes: scene_color, depth

WaterMeshPass

Renders water mesh geometry with tessellation and displacement.

Reads/Writes: scene_color, depth

GrassPass

GPU-instanced grass rendering. Renders thousands of grass blades using instance data from GrassRegion components. Supports wind animation and interactive bending via GrassInteractor components.

Reads/Writes: scene_color, depth

DecalPass

Renders projected decals onto scene geometry. Decals sample the depth buffer to project textures onto surfaces.

Reads/Writes: scene_color, depth

ParticlePass

GPU billboard particle rendering. Reads ParticleEmitter component data and renders camera-facing quads.

Reads/Writes: scene_color, depth

TextPass

Renders 3D world-space text using the font atlas.

Reads/Writes: scene_color, depth

HudPass

Renders screen-space HUD text. Unlike TextPass, HUD text is rendered in screen coordinates with configurable anchoring.

Reads/Writes: scene_color, depth

LinesPass

Renders debug lines from Lines components. Useful for visualization, bounding boxes, and debugging.

Reads/Writes: scene_color, depth

GridPass

Renders an infinite ground grid. Controlled by world.resources.graphics.show_grid.

Reads/Writes: scene_color, depth

UiRectPass

Renders UI rectangles for the immediate-mode UI system.

SelectionMaskPass

Generates a selection mask texture for selected entities. Used by the editor for selection outlines.

Reads: depth Writes: selection_mask

OutlinePass

Reads the selection mask and renders outlines around selected entities by detecting edges in the mask.

Reads: selection_mask Writes: scene_color

SDF Passes (feature: sdf_sculpt)

SdfComputePass

Computes SDF brick maps on the GPU.

SdfPass

Raymarches signed distance fields for real-time sculpting visualization.

InteriorMappingPass

Renders interior mapping (parallax cubemap) for building windows.

ProjectionPass / HiZPass

Hierarchical-Z buffer generation for occlusion culling.

Post-Processing

Live Demos: Bloom | SSAO | Depth of Field

Post-processing passes read the HDR scene color, depth, and normals to produce the final image. These passes are added in configure_render_graph().

Available Passes

Enabling Effects

Control post-processing 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)

In the real world, corners, crevices, and enclosed spaces receive less ambient light because surrounding geometry occludes incoming light from many directions. SSAO approximates this effect in screen space by analyzing 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 to check the depth buffer: if the stored depth is closer than the sample point, that direction is occluded. The ratio of occluded samples to total samples gives the occlusion factor.

The key inputs are:

• Depth buffer - Provides the 3D position of each pixel
• View-space normals - Orients the sampling hemisphere along the surface
• Random noise - Rotates the sample kernel per-pixel to avoid banding patterns

The raw SSAO output is noisy because of the limited sample count (typically 16-64 samples per pixel). A bilateral blur pass smooths the result while preserving edges (it avoids blurring across depth discontinuities, which would cause halos around objects).

#![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 - The hemisphere radius in world units. Larger values detect occlusion from farther geometry but can cause over-darkening.
• ssao_bias - A small depth offset to prevent self-occlusion artifacts on flat surfaces.
• ssao_intensity - Multiplier for the final occlusion factor.

SSGI (Screen-Space Global Illumination)

In real-world lighting, light bounces between surfaces. A red wall next to a white floor tints the floor red. Traditional rasterization only computes direct lighting (light source to surface to camera). Global illumination (GI) adds these indirect bounces.

SSGI approximates one bounce of indirect light using only screen-space information. For each pixel, the shader traces short rays through the depth buffer to find nearby surfaces, then samples the color at those hit points as incoming indirect light. This is conceptually similar to SSAO but samples color instead of just occlusion.

SSGI is computed at half resolution for performance (the indirect illumination is low-frequency and doesn't need full resolution), then bilaterally blurred and upsampled.

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 intersects a surface (the ray's depth exceeds the depth buffer value), the color at that screen position becomes the reflection.

This technique works well for reflections of on-screen geometry but has inherent limitations: off-screen objects cannot be reflected, and reflections at grazing angles stretch across large screen areas. The blur pass hides artifacts from these limitations, and a fallback to environment maps or IBL fills in where SSR has no data.

Bloom

Bloom simulates the light scattering that occurs in real cameras and the human eye when bright light sources bleed into surrounding areas. In HDR rendering, pixels can have values above 1.0 (the displayable range). Bloom extracts these bright pixels and spreads their light outward.

How Bloom Works

The bloom pipeline uses a progressive downsample/upsample approach (similar to the technique described in the Call of Duty: Advanced Warfare presentation):

1. Threshold - Extract pixels brighter than a threshold from the HDR scene color
2. Downsample chain - Progressively halve the resolution through multiple mip levels (e.g., 1920x1080 -> 960x540 -> 480x270 -> ...), applying a blur at each step. This is much cheaper than blurring at full resolution because each mip level has 1/4 the pixels.
3. Upsample chain - Walk back up the mip chain, additively blending each level with the one above it. This produces a smooth, wide blur that spans many pixels without requiring a massive blur kernel.
4. Composite - Add the bloom result to the scene color during the final post-process pass.

The mip-chain approach produces natural-looking bloom because it captures both tight glow (from the high-resolution mips) and wide glow (from the low-resolution mips) simultaneously.

Bloom creates a glow effect around bright pixels using this mip-chain downsample/upsample approach:

#![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; objects nearer or farther than the focal plane appear blurred. The amount of blur (the circle of confusion, or CoC) increases with distance from the focal plane and is controlled by the aperture size.

How DoF Works

1. CoC computation - For each pixel, compute the circle of confusion from the depth buffer value, the focus distance, and the aperture. The CoC is the diameter (in pixels) of the blur disc for that pixel.
2. Blur - Apply a variable-radius blur where the kernel size is proportional to the CoC. Pixels with large CoC values (far from focus) get blurred heavily; pixels near the focal plane remain sharp.
3. Bokeh - Bright out-of-focus highlights form characteristic shapes (circles, hexagons) called bokeh. The shader can emphasize bright pixels during the blur to simulate this optical effect.

Focus blur based on distance from a focus plane:

#![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. But displays can only show values between 0 and 1. Tonemapping is the process of compressing the HDR range into the displayable LDR range while preserving the perception of brightness differences and color relationships.

Different tonemapping curves make different trade-offs:

• Reinhard - Simple color / (color + 1) mapping. Preserves highlights but can look washed out.
• ACES (Academy Color Encoding System) - Film-industry standard curve with good contrast and a slight warm tint. Widely used in games.
• AgX - A more recent curve designed to handle highly saturated colors better than ACES (which can produce hue shifts in bright saturated regions).
• Neutral - Minimal color manipulation, useful when color grading is handled externally.

The PostProcessPass performs HDR-to-LDR tonemapping:

#![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:

• Color grading presets
• Chromatic aberration
• Film grain
• Custom shader effects

See Effects Pass for details.

Custom Post-Processing

Add custom post-processing passes via the render graph. See Custom Passes for implementation examples.

Performance

Disable expensive effects for better performance:

#![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

Cameras define the viewpoint and projection used to render the scene. Nightshade uses reversed-Z depth buffers for both perspective and orthographic projections, and supports infinite far planes, input smoothing, and arc-ball orbit controllers.

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 uses a perspective projection (45 degree FOV, infinite far plane, 0.01 near plane) with smoothing enabled.

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 where the near plane maps to depth 1.0 and the far plane maps to 0.0. This distributes floating-point precision more evenly across the depth range, dramatically reducing z-fighting artifacts at large distances.

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 also uses reversed-Z, 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

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

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 all camera input. The smoothing factor is computed as:

smoothing_factor = 1.0 - smoothness^7 ^ delta_time

Where smoothness is the per-device smoothness parameter. A smoothness of 0 gives instant response; values approaching 1 make the input increasingly sluggish. The powi(7) exponent makes the smoothness parameter feel linear to adjust.

#![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 provides 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, then the current values interpolate towards them using the smoothing formula. The system snaps to the target when the difference falls below 0.001.

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 ±90 degrees. When the camera goes upside down, the yaw direction is automatically reversed for intuitive mouse control.

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 is placed at focus + rotate(yaw, pitch) * (0, 0, radius) — the rotation is composed as yaw (around Y) 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

Switch between cameras:

#![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

Materials define the visual appearance of meshes using PBR (Physically Based Rendering) following the glTF 2.0 metallic-roughness workflow. Nightshade supports the full glTF PBR model plus several extensions: 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

These fields implement light transmission through surfaces (glass, water, thin-shell materials):

Specular

Overrides 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 roughness and metallic values are multiplied with the texture's green and blue channels respectively.

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 (e.g., from Substance or older 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

Generate textures at runtime:

#![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

Nightshade provides 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

Remove root motion from animations:

#![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

Create meshes programmatically:

#![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

Assign a mesh to an entity:

#![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 efficiently:

#![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

Access the mesh cache:

#![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 skeletons:

#![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

Control whether a mesh casts shadows:

#![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 lights.

Light Types

Directional Light (Sun)

Illuminates the entire scene from a direction, simulating distant light sources like the sun:

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

let sun = spawn_sun(world);
}

spawn_sun returns the Entity for the directional light, which you can further configure:

#![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

Emits light in all directions from a point:

#![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

Cone-shaped light, perfect for flashlights or stage lighting:

#![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

Create a flickering fire/torch effect:

#![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

Animated color changes:

#![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)

Attach a spotlight to the camera for a flashlight effect:

#![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 (up to 256 lights per cluster). During the mesh pass, each fragment looks up its cluster and only evaluates the lights assigned to it, avoiding the cost of testing every light for every pixel.

PBR Lighting Model

All lights are evaluated using the Cook-Torrance microfacet BRDF:

• Normal Distribution Function (D): Trowbridge-Reitz GGX models the statistical distribution of microfacet orientations. The squared roughness parameter (a = roughness * roughness) controls how concentrated the specular highlight is.

• Geometry Function (G): Schlick-Beckmann approximation with Smith's method accounts for self-shadowing between microfacets. Two terms are combined: one for the view direction and one for the light direction.

• Fresnel (F): Schlick's approximation 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:

• Irradiance map: Pre-convolved diffuse environment lighting, sampled in the surface normal direction
• Prefiltered environment map: 5 mip levels of increasingly blurred specular reflections, sampled in the reflection direction at a mip level determined by roughness

A 2D BRDF lookup texture (computed via 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 multiple lights in a scene. Create point and spot lights manually as shown above:

#![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, asynchronously, or generated procedurally.

Texture Cache

The TextureCache stores all loaded textures as TextureEntry values (wgpu texture + view + sampler) in a GenerationalRegistry. Each texture is identified by a TextureId containing an index and generation counter, ensuring stale references are detected.

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 processes this command and uploads the RGBA data to the GPU. The texture is stored in the cache under the given name.

Procedural Textures

The engine provides built-in procedural textures loaded at startup via load_procedural_textures():

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

This creates three textures:

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:

#![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() will free it.

Dummy Textures

If a texture is missing, texture_cache_ensure_dummy() creates a 64x64 purple-and-black checkerboard placeholder. This prevents rendering errors from missing assets.

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 loading progress for loading screens:

#![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 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
}

Sprite Texture Atlas

Sprites use a separate texture atlas rather than the main texture cache. The atlas is a single large GPU texture divided into a grid of slots.

Upload textures to specific atlas slots via WorldCommand::UploadSpriteTexture:

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::UploadSpriteTexture {
    slot: 0,
    rgba_data: image_bytes,
    width: 256,
    height: 256,
});
}

The Sprite component references textures by their slot index. See Sprites for details.

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.

Water

Live Demo: Water

Nightshade includes a procedural water system with three rendering paths: ray-marched surface water, mesh-based water with vertex displacement, and volumetric water for waterfalls and mist.

How Water Rendering Works

Wave Generation

Water surfaces are animated using multi-octave procedural noise. The sea_octave function creates wave-like patterns by combining abs(sin) and abs(cos) of noise-distorted UV coordinates, then raising the result to a choppiness exponent. Higher choppiness values produce sharper wave peaks.

The height map evaluates 5 octaves of this function. Each octave doubles the frequency and reduces amplitude by 0.22x, while increasing choppiness by 20%. Between octaves, UV coordinates are rotated by a fixed 2x2 matrix [1.6, 1.2; -1.2, 1.6] to prevent visible repetition. Two offset directions (uv + time and uv - time) create coherent wave interference patterns.

Fresnel Reflections

The water shader computes the Fresnel effect to blend between refraction (seeing into the water) and reflection (seeing the sky):

fresnel = pow(1.0 - dot(normal, view_direction), fresnel_power)

At steep viewing angles (looking straight down), fresnel is near 0 and the water shows its base color. At grazing angles (looking across the surface), fresnel approaches 1 and the water reflects the sky. The fresnel_power parameter (default 3.0) controls how quickly this transition happens.

Specular sun reflections use a cosine power of 60 for tight, bright highlights on wave crests.

Three Rendering Paths

Path 1: Ray-Marched Surface Water - For bounded water regions without mesh geometry. The fragment shader traces rays from the camera through the 3D height field using heightmap_tracing() with 32 march steps and geometric refinement iterations. This produces per-pixel correct reflections and refractions. Supports polygon bounds with soft edge feathering. Limited to 16 simultaneous water regions.

Path 2: Mesh-Based Water - For large flat surfaces. The vertex shader applies procedural wave displacement to mesh vertices using the same water_height() function. The fragment shader computes normals from height gradients, applies Fresnel-based sky reflection, and adds subsurface scattering: pow(max(dot(view, -sun_dir), 0.0), 2.0) * 0.2. More efficient than ray-marching and integrates properly with the depth buffer.

Path 3: Volumetric Water - For waterfalls, mist, and cascading water. A per-pixel ray-marching shader traces through SDF-bounded volumes (box, cylinder, or sphere) with up to 64 steps. Three flow types have different density functions:

• Waterfall: High vertical stretch with turbulence, top-to-bottom falloff
• Mist: Rising motion with horizontal drift, wispy patterns using 3D FBM noise
• Cascade: Multiple parallel streams using 3 layered FBM noise functions

Volumetric water is lit with sun shadowing through the volume and foam blending based on accumulated density.

Vertical Water

For waterfall surfaces, a separate shader (water_mesh_vertical.wgsl) displaces vertices along the surface normal instead of the Y-axis. Wave frequency is stretched (2.0x horizontally, 0.5x vertically) to create vertical streaks. Foam patterns are generated from layered noise and blended with the water color.

Frustum Culling

A compute shader (water_mesh_culling.wgsl) tests each water object's bounding sphere against the 6 frustum planes. Culled objects skip rendering entirely. For volumetric water, the bounding sphere is derived from the volume's half-size. Visible instances are appended to an indirect draw buffer via atomic operations.

Water Component

#![allow(unused)]
fn main() {
pub struct Water {
    pub wave_height: f32,           // Wave amplitude (default: 0.6)
    pub choppy: f32,                // Wave sharpness (default: 4.0, higher = sharper peaks)
    pub speed: f32,                 // Animation speed (default: 0.8)
    pub frequency: f32,             // Wave frequency (default: 0.16, lower = longer waves)
    pub base_height: f32,           // Water level (default: 0.0)
    pub base_color: Vec4,           // Dark water color
    pub water_color: Vec4,          // Light water color
    pub specular_strength: f32,     // Sun reflection intensity (default: 1.0)
    pub fresnel_power: f32,         // Reflection balance (default: 3.0)
    pub edge_feather_distance: f32, // Shore softness (default: 2.0)
    pub is_vertical: bool,          // Waterfall mode
    pub is_volumetric: bool,        // 3D volume mode
    pub volume_shape: VolumeShape,  // Box, Cylinder, or Sphere
    pub volume_flow_type: VolumeFlowType, // Waterfall, Mist, or Cascade
    pub volume_size: Vec3,          // Volume dimensions
    pub flow_direction: Vec2,       // Normalized flow direction
    pub flow_strength: f32,         // Flow intensity
}
}

Spawning Water

Planar Water

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

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

world.core.set_water(water_entity, Water {
    wave_height: 0.5,
    speed: 1.0,
    frequency: 0.5,
    choppy: 4.0,
    base_color: Vec4::new(0.0, 0.1, 0.2, 1.0),
    water_color: Vec4::new(0.0, 0.3, 0.5, 1.0),
    fresnel_power: 3.0,
    specular_strength: 1.0,
    edge_feather_distance: 1.0,
    ..Default::default()
});
}

Volumetric Water (Waterfall)

#![allow(unused)]
fn main() {
world.core.set_water(waterfall_entity, Water {
    is_volumetric: true,
    volume_shape: VolumeShape::Box,
    volume_flow_type: VolumeFlowType::Waterfall,
    volume_size: Vec3::new(2.0, 10.0, 1.0),
    flow_direction: Vec2::new(0.0, -1.0),
    flow_strength: 2.0,
    base_color: Vec4::new(0.0, 0.15, 0.25, 1.0),
    water_color: Vec4::new(0.1, 0.4, 0.6, 1.0),
    ..Default::default()
});
}

Wave Parameters

Dynamic Weather

Water properties can be changed at runtime for weather transitions:

#![allow(unused)]
fn main() {
fn stormy_weather(world: &mut World, water: Entity) {
    if let Some(w) = world.core.get_water_mut(water) {
        w.wave_height = 3.0;
        w.speed = 2.0;
        w.choppy = 6.0;
    }
}

fn calm_weather(world: &mut World, water: Entity) {
    if let Some(w) = world.core.get_water_mut(water) {
        w.wave_height = 0.3;
        w.speed = 0.5;
        w.choppy = 2.0;
    }
}
}

Decals

Live Demo: Decals

Decals are textures projected onto scene geometry using deferred projection through the depth buffer. They are used for bullet holes, blood splatters, footprints, scorch marks, and environmental details without modifying the underlying mesh geometry.

How Decal Rendering Works

Each decal is rendered 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 within the decal's projection volume (±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 (from the depth buffer gradients) against the decal's forward direction. Surfaces angled beyond the threshold are rejected, preventing decals from wrapping around sharp edges.

Distance fade uses a smoothstep between fade_start and fade_end based on the camera-to-decal distance.

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:

#![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
}
}

Sprites

Live Demo: Sprites

Sprites are 2D textured quads rendered in 3D space. They support texture blending, animation, and GPU-instanced rendering with automatic z-sorting.

Sprite Component

The Sprite component defines the visual properties of a sprite entity:

#![allow(unused)]
fn main() {
pub struct Sprite {
    pub position: Vec2,
    pub size: Vec2,
    pub scale: Vec2,
    pub rotation: f32,
    pub depth: f32,
    pub color: [f32; 4],
    pub texture_index: u32,
    pub texture_index2: u32,
    pub blend_factor: f32,
    pub uv_min: Vec2,
    pub uv_max: Vec2,
    pub blend_mode: SpriteBlendMode,
}
}

Creating Sprites

Sprites live in the Sprite2d sub-ECS, not Core. Use the spawn_sprite helper or manually add sprite components:

#![allow(unused)]
fn main() {
let entity = spawn_sprite(world, Vec2::new(0.0, 0.0), Vec2::new(32.0, 32.0));

if let Some(sprite) = world.sprite2d.get_sprite_mut(entity) {
    sprite.texture_index = 0;
    sprite.color = [1.0, 0.5, 0.5, 1.0];
}
}

Core and Sprite2d flags cannot be mixed in one spawn_entities call. The spawn_sprite helper handles this for you.

Texture Blending

Blend between two textures for smooth transitions:

#![allow(unused)]
fn main() {
let sprite = Sprite::new()
    .with_multitexture(0, 1, 0.5);
}

Loading Sprite Textures

Sprite textures are stored in the sprite texture atlas, not the main texture cache. Upload textures to atlas slots using WorldCommand::UploadSpriteTexture:

#![allow(unused)]
fn main() {
world.queue_command(WorldCommand::UploadSpriteTexture {
    slot: 0,
    rgba_data: image_bytes,
    width: 256,
    height: 256,
});
}

Each slot is 512x512 pixels. There are 128 total slots. Textures smaller than the slot size are placed in the top-left corner of the slot.

Sprite Animation

The SpriteAnimator component drives frame-based animation by updating the sprite's UV coordinates each frame.

Grid-Based Animation

For sprite sheets arranged in a grid:

#![allow(unused)]
fn main() {
let animator = SpriteAnimator::from_grid(
    8,      // columns
    4,      // rows
    32,     // total frames
    0.1,    // seconds per frame
);

world.sprite2d.add_components(entity, SPRITE_ANIMATOR);
world.sprite2d.set_sprite_animator(entity, animator);
}

This computes UV coordinates for each frame automatically based on the grid layout.

Loop Modes

#![allow(unused)]
fn main() {
let animator = SpriteAnimator::from_grid(4, 1, 4, 0.15)
    .with_loop_mode(LoopMode::Loop);      // default
}

Playback Control

#![allow(unused)]
fn main() {
animator.play();
animator.pause();
animator.reset();
}

Speed

#![allow(unused)]
fn main() {
let animator = SpriteAnimator::from_grid(4, 1, 4, 0.1)
    .with_speed(2.0); // 2x playback speed
}

Manual Frames

For non-uniform frame layouts, define frames individually:

#![allow(unused)]
fn main() {
let animator = SpriteAnimator {
    frames: vec![
        SpriteFrame {
            uv_min: Vec2::new(0.0, 0.0),
            uv_max: Vec2::new(0.25, 0.5),
            duration: 0.1,
            texture_index: None,
        },
        SpriteFrame {
            uv_min: Vec2::new(0.25, 0.0),
            uv_max: Vec2::new(0.5, 0.5),
            duration: 0.2,
            texture_index: Some(1), // switch to atlas slot 1
        },
    ],
    ..Default::default()
};
}

The texture_index field on SpriteFrame optionally switches the sprite's atlas slot on that frame.

Animation System

The sprite_animation_system must run each frame to advance animations:

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

Rendering

The SpritePass renders all sprite entities using GPU instancing. It:

• Collects all entities with Sprite + GlobalTransform components
• Performs frustum culling based on camera position
• Sorts sprites by depth for correct alpha blending
• Renders camera-facing quads with instanced draw calls

Sprites are rendered as part of the geometry pass pipeline and write to both scene_color and depth.

Physics Overview

Live Demo: Physics

Nightshade integrates Rapier3D for physics simulation, providing rigid body dynamics, collision detection, and character controllers.

Enabling Physics

Physics is enabled with the physics feature:

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

Physics World

The physics world is accessed through resources:

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

// Configuration
physics.gravity = Vec3::new(0.0, -9.81, 0.0);
physics.fixed_timestep = 1.0 / 60.0;
}

Core Concepts

Rigid Bodies

Objects that can move and be affected by forces:

• Dynamic: Affected by gravity and forces
• Kinematic: Moved by code, affects dynamic bodies
• Fixed: Immovable, infinite mass

Colliders

Shapes used for collision detection:

• Cuboid, Ball, Capsule, Cylinder
• Triangle mesh, Heightfield
• Compound shapes

Character Controllers

Kinematic bodies with special handling for player movement.

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));
    }
}
}

Physics Synchronization

Physics runs at a fixed timestep. Transforms are automatically synchronized:

1. Game logic updates entity transforms
2. Physics simulation steps (may run multiple times per frame)
3. Physics transforms sync back to entities
4. Interpolation smooths visual positions

Querying Physics

Picking (Raycasting)

The picking system casts rays from screen coordinates to find entities:

#![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;
}
}

For precise trimesh-based raycasting (requires physics feature):

#![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;
}
}

Physics Materials

Friction, restitution, and density are set directly on the ColliderComponent:

#![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));
}

Debug Visualization

Enable physics debug drawing:

#![allow(unused)]
fn main() {
world.resources.physics.debug_draw = true;

// In run_systems
physics_debug_draw_system(world);
}

This renders:

• Collider shapes (wireframe)
• Contact points
• Collision normals

Performance Tips

1. Use simple collider shapes (boxes, spheres) when possible
2. Disable collision between groups that don't need it
3. Use compound colliders instead of many small colliders
4. Set bodies to sleep when inactive
5. Use appropriate fixed timestep (60 Hz is standard)

Joints

Connect bodies with joints for:

• Doors (revolute)
• Drawers (prismatic)
• Ropes (rope/spring)
• Chains (spherical)

See Physics Joints for details.

Rigid Bodies

Rigid bodies are the foundation of physics simulation. They define how objects move and respond to forces.

Body Types

Dynamic Bodies

Fully simulated physics objects:

#![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));
}

Kinematic Bodies

Controlled by code, not affected by forces:

#![allow(unused)]
fn main() {
world.core.set_rigid_body(entity, RigidBodyComponent::new_kinematic());
}

Move kinematic bodies by updating their transform:

#![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);
}

Static Bodies

Immovable objects (floors, walls):

#![allow(unused)]
fn main() {
world.core.set_rigid_body(entity, RigidBodyComponent::new_static());
}

Helper Functions

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));
}

Applying Forces

Access the Rapier rigid body directly:

#![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,  // wake up if sleeping
        );
    }
}
}

Applying Impulses

Instant velocity change:

#![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,
        );
    }
}
}

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,
        );
    }
}
}

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);
    }
}
}

Locking Axes

Prevent rotation or translation on specific axes:

#![allow(unused)]
fn main() {
if let Some(rigid_body) = world.resources.physics.rigid_body_set.get_mut(handle.into()) {
    // Lock rotation (useful for character controllers)
    rigid_body.lock_rotations(true, true);

    // Lock specific translation axes
    // rigid_body.lock_translations(true, true);  // Lock X and Y
}
}

Damping

Add drag to slow objects:

#![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);   // Translation damping
    rigid_body.set_angular_damping(0.5);  // Rotation damping
}
}

Sleeping

Bodies automatically sleep when stationary. Wake them:

#![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

Colliders define the physical shape of objects for collision detection.

Collider Shapes

Ball (Sphere)

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_ball(0.5));
}

Cuboid (Box)

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_cuboid(1.0, 0.5, 1.0));
}

Capsule

Perfect for characters:

#![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()
});
}

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

For complex static geometry:

#![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()
});
}

Heightfield

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()
});
}

Compound

Multiple shapes combined:

#![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 directly on ColliderComponent:

#![allow(unused)]
fn main() {
world.core.set_collider(entity, ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.5)       // Sliding resistance (0 = ice, 1 = rubber)
    .with_restitution(0.3)    // Bounciness (0 = no bounce, 1 = perfect bounce)
    .with_density(1.0));      // Mass per unit volume
}

Material Examples

#![allow(unused)]
fn main() {
// Ice
let ice = ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.05)
    .with_restitution(0.1)
    .with_density(0.9);

// Rubber
let rubber = ColliderComponent::new_ball(0.5)
    .with_friction(0.9)
    .with_restitution(0.8)
    .with_density(1.1);

// Metal
let metal = ColliderComponent::new_cuboid(0.5, 0.5, 0.5)
    .with_friction(0.4)
    .with_restitution(0.2)
    .with_density(7.8);
}

Collision Groups

Filter which objects collide:

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

// Define groups
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;

// Player collides with enemies and world, not own projectiles
let player_filter = CollisionGroups::new(
    GROUP_PLAYER,
    GROUP_ENEMY | GROUP_WORLD,
);
}

Sensor Colliders

Detect overlaps without physical response:

#![allow(unused)]
fn main() {
// Create a trigger zone
if let Some(collider) = world.resources.physics.collider_set.get_mut(handle.into()) {
    collider.set_sensor(true);
}
}

Sensor collisions are reported through the collision events system (see below).

Collision Events

Query collision pairs each frame. collision_events() returns &[CollisionEvent]:

#![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 CollisionEvent has:

#![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 complex shapes on dynamic bodies, use convex decomposition:

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

// This creates multiple convex pieces from a concave mesh
let decomposed = SharedShape::convex_decomposition(&vertices, &indices);
}

Performance Tips

• Prefer primitive shapes over meshes
• Use trimesh only for static geometry
• Compound colliders are better than multiple entities
• Simplify collision geometry vs visual geometry

Character Controllers

Character controllers provide smooth player movement with collision handling, slopes, and stairs.

First-Person Player

The easiest way to get started:

#![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;
    }
}
}

Custom Character Controller

For third-person or specialized characters:

#![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
}
}

Controller Properties

Movement Input

The built-in character_controller_input_system(world) handles WASD movement, jumping, sprinting, and crouching automatically. Call it each frame:

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

Ground Detection

Check if the character is grounded:

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller(player) {
    if controller.grounded {
        // On ground - can jump
    } else {
        // In air
    }
}
}

Slope Handling

Controllers automatically handle slopes:

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller_mut(player) {
    controller.config.max_slope_climb_angle = 0.8;  // ~45 degrees in radians
    controller.config.min_slope_slide_angle = 0.5;   // ~30 degrees
}
}

Camera Integration

First-Person Camera

The camera is a child of the player:

#![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),  // Eye height
    ..Default::default()
});

world.resources.active_camera = Some(camera);
}

Third-Person Camera

Follow the character with an offset:

#![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;
    };

    // Camera behind and above player
    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

Controllers can automatically climb small steps:

#![allow(unused)]
fn main() {
if let Some(controller) = world.core.get_character_controller_mut(player) {
    controller.config.autostep_max_height = Some(0.3);  // Can climb 30cm steps
    controller.config.autostep_min_width = Some(0.2);   // Minimum step width
}
}

Interaction Cooldowns

Prevent rapid repeated actions:

#![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;
}
}

Physics Joints

Joints connect two rigid bodies together, constraining their relative motion.

Joint Types

Fixed Joint

Rigidly connects two bodies:

#![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)),
);
}

Spherical Joint (Ball-and-Socket)

Allows rotation in all directions:

#![allow(unused)]
fn main() {
// Pendulum
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)),
);
}

Revolute Joint (Hinge)

Rotates around a single axis:

#![allow(unused)]
fn main() {
// Door hinge
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)  // Rotate around Y axis
        .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)),  // Limit rotation
);
}

Adding Motor

Make the door swing automatically:

#![allow(unused)]
fn main() {
RevoluteJoint::new(JointAxisDirection::Y)
    .with_motor(JointMotor::position(0.0, 5.0, 100.0))
}

Prismatic Joint (Slider)

Slides along an axis:

#![allow(unused)]
fn main() {
// Drawer
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)  // Slide on Z axis
        .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)),  // Min/max extension
);
}

Rope Joint

Maximum distance constraint:

#![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)  // Max length
        .with_local_anchor1(Vec3::new(0.0, -0.15, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 0.0, 0.0)),
);
}

Spring Joint

Elastic connection:

#![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)  // rest_length, stiffness, damping
        .with_local_anchor1(Vec3::new(0.0, -0.15, 0.0))
        .with_local_anchor2(Vec3::new(0.0, 0.2, 0.0)),
);
}

Joint Limits

Constrain movement range:

#![allow(unused)]
fn main() {
// Rotation limits (radians)
RevoluteJoint::new(JointAxisDirection::Z)
    .with_limits(JointLimits::new(-1.57, 1.57))  // -90° to +90°

// Translation limits (meters)
PrismaticJoint::new(JointAxisDirection::X)
    .with_limits(JointLimits::new(-2.0, 2.0))
}

Breaking Joints

Joints can break under force:

#![allow(unused)]
fn main() {
if let Some(joint) = world.resources.physics.get_joint_mut(joint_handle) {
    joint.set_max_force(1000.0);  // Break if force exceeds this
}
}

Chain Example

Create a chain of connected spheres:

#![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;
    }
}
}

Interactive Door Example

Complete door with momentum:

#![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));

    // Lock vertical rotation
    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);  // Only Y rotation allowed
            }
        }
    }

    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
}
}

Loading Animated Models

Nightshade supports skeletal animation through glTF/GLB files.

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()?;

    // 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 with animations and skins
    result.prefabs.first().map(|prefab| {
        spawn_prefab_with_animations(
            world,
            prefab,
            &result.animations,
            Vec3::zeros(),
        )
    })
}
}

Animation Data Structure