Crate nightshade

Expand description

§Nightshade

A data-oriented game engine written in Rust.

§Getting Started

§1. Add to Cargo.toml

[dependencies]
nightshade = "0.14"

§2. Create Your Game

use nightshade::prelude::*;

struct Game {
    camera: Option<Entity>,
}

impl Default for Game {
    fn default() -> Self {
        Self { camera: None }
    }
}

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

        // Graphics setup
        world.resources.graphics.atmosphere = Atmosphere::Sky;
        spawn_sun(world);

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

        // Spawn objects
        spawn_cube_at(world, Vec3::new(0.0, 0.5, 0.0));
    }

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

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

§3. Loading 3D Models

let model_data = include_bytes!("../assets/character.glb");
let result = import_gltf_from_bytes(model_data).unwrap();
let prefab = &result.prefabs[0];
let entity = spawn_prefab_with_animations(world, prefab, &result.animations, Vec3::zeros());

if let Some(player) = world.core.get_animation_player_mut(entity) {
    player.play(0);
    player.looping = true;
}

§Architecture

§World

The World contains all game state:

Entities: Unsigned integer handles (Entity) identifying objects
Components: Data attached to entities (transforms, meshes, physics, etc.)
Resources: Global singletons (world.resources.window.timing, .input, .graphics, .physics)

§Component Flags

Entities are created with bitflags specifying their components:

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

Flag	Description
`LOCAL_TRANSFORM`	Position/rotation/scale relative to parent
`GLOBAL_TRANSFORM`	World-space transform (computed)
`LOCAL_TRANSFORM_DIRTY`	Marks transform for hierarchy update
`RENDER_MESH`	Visible 3D geometry
`MATERIAL_REF`	Material reference
`CAMERA`	Camera component
`PARENT` / `CHILDREN`	Hierarchy relationships
`RIGID_BODY`	Physics body
`COLLIDER`	Collision shape
`ANIMATION_PLAYER`	Animation controller
`PARTICLE_EMITTER`	GPU particles
`AUDIO_SOURCE`	Sound playback
`DECAL`	Projected texture

§Resources

// Timing
let dt = world.resources.window.timing.delta_time;
let fps = world.resources.window.timing.frames_per_second;
let uptime_ms = world.resources.window.timing.uptime_milliseconds;

// Input
let keyboard = &world.resources.input.keyboard;
let mouse = &world.resources.input.mouse;

// Graphics
world.resources.graphics.bloom_enabled = true;
world.resources.graphics.atmosphere = Atmosphere::Sky;

// Camera
world.resources.active_camera = Some(camera_entity);

§Render Graph

Rendering uses a pass-based graph. Override State::configure_render_graph for bloom, SSAO, or custom effects. See the render module.

§Troubleshooting

Black Screen

Set world.resources.active_camera to a valid camera
Ensure camera can see objects (position/orientation)
Add lighting: spawn_sun(world)

No Audio (WASM)

Browsers require user interaction first
Trigger audio from click/key handlers

Physics Falls Through

Floor needs RigidBodyComponent::new_static() AND ColliderComponent
Check collider dimensions match mesh

Animations Not Playing

Use spawn_prefab_with_animations() not spawn_prefab()
Call player.play(index) to start

Textures Missing

Call world.texture_cache_add_reference(path) before material creation
Paths are case-sensitive

Entity Invisible

Needs RENDER_MESH flag
Needs valid MaterialRef
Check transform position

§Features

§Aggregate Features

engine (default) - Full engine functionality including asset loading, scene graphs, file dialogs, and more. This is the standard feature for building games.
runtime - Minimal rendering without asset loading. Use with wgpu for lightweight apps that don’t need gltf/image loading.
full - Everything in engine plus audio, physics, gamepad, navmesh.
wgpu (default) - WebGPU-based rendering with DirectX 12, Metal, Vulkan, and WebGPU.

§Granular Features

These allow fine-grained control over dependencies:

core - Foundation: ECS (freecs), math (nalgebra), windowing (winit), time, petgraph.
text - MSDF text rendering using ttf-parser. Requires core.
assets - Asset loading: gltf, image, half, bincode, serde_json. Requires core.
scene_graph - Scene hierarchy system. Requires assets.
file_dialog - Native file dialogs using rfd. Requires core.
screenshot - PNG screenshot saving using image. Standalone feature.

§Optional Features

shell - Developer console with command registration, rendered via the retained UI.
audio - Audio playback using Kira.
physics - 3D physics using Rapier.
navmesh - Navigation mesh generation using Recast.
picking - Ray-based entity picking. Trimesh picking requires physics.
gamepad - Gamepad input using gilrs.

§Platform Features

steam - Steamworks integration.

§Profiling Features

tracing - Rolling log files and RUST_LOG support.
tracy - Real-time profiling with Tracy. Implies tracing.
chrome - Chrome tracing output. Implies tracing.

§Feature Quick Reference

§Audio (`audio` feature)

// Load and play a sound
let sound = audio_engine_load_sound(&mut world.resources.audio, include_bytes!("sound.ogg"));
world.resources.audio.play(sound);

// 3D spatial audio
let source = spawn_entities(world, AUDIO_SOURCE | LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];
world.core.set_audio_source(source, AudioSource::new(sound).with_spatial(true));
world.core.set_local_transform(source, LocalTransform::from_translation(Vec3::new(5.0, 0.0, 0.0)));

§Physics (`physics` feature)

// Dynamic rigid body with collider
let entity = spawn_entities(world,
    RIGID_BODY | COLLIDER | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
    1
)[0];
world.core.set_rigid_body(entity, RigidBodyComponent::new_dynamic());
world.core.set_collider(entity, ColliderComponent::cuboid(1.0, 1.0, 1.0));
world.core.set_local_transform(entity, LocalTransform::from_translation(Vec3::new(0.0, 5.0, 0.0)));

// Static floor
let floor = spawn_entities(world, RIGID_BODY | COLLIDER | LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];
world.core.set_rigid_body(floor, RigidBodyComponent::new_static());
world.core.set_collider(floor, ColliderComponent::cuboid(10.0, 0.1, 10.0));

// Step physics each frame
fn run_systems(&mut self, world: &mut World) {
    physics_world_step(&mut world.resources.physics, world.resources.window.timing.delta_time);
    sync_physics_transforms(world);
}

§Navigation Mesh (`navmesh` feature)

// Generate navmesh from world geometry
let config = RecastNavMeshConfig::default();
generate_navmesh_recast(world, &config);

// Spawn an agent
let agent = spawn_navmesh_agent(world, Vec3::new(0.0, 0.0, 0.0), 0.5, 2.0);

// Set destination
set_agent_destination(world, agent, Vec3::new(10.0, 0.0, 10.0));
set_agent_speed(world, agent, 3.5);

// Update each frame
fn run_systems(&mut self, world: &mut World) {
    run_navmesh_systems(world, world.resources.window.timing.delta_time);
}

§Entity Picking (`picking` feature)

// Ray picking (bounding box)
let mouse_pos = world.resources.input.mouse.position;
let ray = PickingRay::from_screen_position(world, mouse_pos);
if let Some(hit) = pick_closest_entity(world, &ray, &PickingOptions::default()) {
    println!("Hit {:?} at distance {}", hit.entity, hit.distance);
}

// GPU picking (pixel-perfect)
world.resources.gpu_picking.request_pick(mouse_pos.x as u32, mouse_pos.y as u32);
// Next frame:
if let Some(result) = world.resources.gpu_picking.take_result() {
    let world_pos = result.world_position;
    let normal = result.world_normal;
}

§Developer Console (`shell` feature)

use nightshade::shell::{Command, ShellState};

fn spawn_cubes(args: &[&str], world: &mut World, _ctx: &mut ()) -> String {
    let count: usize = args.first().and_then(|s| s.parse().ok()).unwrap_or(1);
    for _ in 0..count {
        spawn_cube_at(world, Vec3::new(rand::random(), rand::random(), rand::random()));
    }
    format!("Spawned {} cubes", count)
}

fn initialize(shell: &mut ShellState<()>) {
    shell.register_builtin_commands();
    shell.registry.register(Command {
        name: "spawn",
        description: "Spawn random cubes",
        usage: "spawn [count]",
        execute: spawn_cubes,
    });
}
// Press Alt+C to open console, type "spawn 10"

§Gamepad Input (`gamepad` feature)

fn run_systems(&mut self, world: &mut World) {
    if let Some(gamepad) = &world.resources.input.gamepad {
        // Analog sticks
        let move_x = gamepad.left_stick.x;
        let move_y = gamepad.left_stick.y;
        let look_x = gamepad.right_stick.x;
        let look_y = gamepad.right_stick.y;

        // Triggers (0.0 - 1.0)
        let accelerate = gamepad.right_trigger;
        let brake = gamepad.left_trigger;

        // Buttons
        if gamepad.pressed(GamepadButton::South) { /* A/Cross */ }
        if gamepad.just_pressed(GamepadButton::North) { /* Y/Triangle */ }
    }
}

§Steam Integration (`steam` feature)

fn initialize(&mut self, world: &mut World) {
    world.resources.steam.initialize().ok();
    world.resources.steam.request_stats();
}

fn run_systems(&mut self, world: &mut World) {
    world.resources.steam.run_callbacks();

    // Unlock achievement
    if self.score >= 1000 {
        world.resources.steam.unlock_achievement("ACH_HIGH_SCORE").ok();
        world.resources.steam.store_stats().ok();
    }

    // Update stat
    world.resources.steam.set_stat_int("total_score", self.score).ok();
}

§Debug Lines

// Create debug lines entity
let debug = spawn_entities(world, LINES, 1)[0];

fn run_systems(&mut self, world: &mut World) {
    if let Some(lines) = world.core.get_lines_mut(self.debug) {
        lines.clear();

        // Draw a line
        lines.push(Line {
            start: Vec3::zeros(),
            end: Vec3::new(1.0, 1.0, 1.0),
            color: Vec4::new(1.0, 0.0, 0.0, 1.0),
        });

        // Draw coordinate axes
        lines.push(Line { start: Vec3::zeros(), end: Vec3::x(), color: Vec4::new(1.0, 0.0, 0.0, 1.0) });
        lines.push(Line { start: Vec3::zeros(), end: Vec3::y(), color: Vec4::new(0.0, 1.0, 0.0, 1.0) });
        lines.push(Line { start: Vec3::zeros(), end: Vec3::z(), color: Vec4::new(0.0, 0.0, 1.0, 1.0) });
    }
}

§Particles

let emitter = spawn_entities(world,
    PARTICLE_EMITTER | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
    1
)[0];

world.core.set_particle_emitter(emitter, ParticleEmitter {
    max_particles: 1000,
    emission_rate: 100.0,
    lifetime: 2.0,
    initial_velocity: Vec3::new(0.0, 5.0, 0.0),
    velocity_randomness: 1.0,
    size: 0.1,
    color: ColorGradient::new(
        Vec4::new(1.0, 0.5, 0.0, 1.0),  // Start: orange
        Vec4::new(1.0, 0.0, 0.0, 0.0),  // End: red, faded
    ),
    shape: EmitterShape::Sphere { radius: 0.5 },
    ..Default::default()
});

world.core.set_local_transform(emitter, LocalTransform::from_translation(Vec3::new(0.0, 0.0, 0.0)));

// Runs automatically via frame schedule

§Decals

let decal = spawn_entities(world,
    DECAL | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY,
    1
)[0];

world.core.set_decal(decal, Decal {
    texture_index: world.texture_cache_lookup("decal_texture"),
    size: Vec2::new(2.0, 2.0),
    depth: 1.0,  // Projection depth
    opacity: 1.0,
});

// Position and orient decal (projects along -Y)
world.core.set_local_transform(decal, LocalTransform {
    translation: hit_position + hit_normal * 0.01,
    rotation: UnitQuaternion::face_towards(&(-hit_normal), &Vec3::x()),
    ..Default::default()
});

§Minimal Example

For a lightweight app without asset loading:

nightshade = { default-features = false, features = ["runtime", "wgpu"] }

§Example

use nightshade::prelude::*;

struct Game;

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

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

§Frame Lifecycle

Each frame executes in this order:

Process window/input events
Update keyboard/mouse/gamepad state
Calculate delta time
Call State::run_systems()
Dispatch event bus messages
Run FrameSchedule (engine systems):
- Initialize and update audio (if audio enabled)
- Update camera aspect ratios
- Step physics simulation (if physics enabled)
- Update animation players, apply to transforms
- Propagate transform hierarchy
- Update instanced mesh caches, sync text
- Reset input state
- Process deferred commands, cleanup
Execute render graph passes

The frame schedule is a resource at world.resources.schedules.frame, with the retained UI sub-schedule at world.resources.schedules.retained_ui. Modify either in State::initialize() to insert, remove, or reorder engine systems. See system_names and retained_ui_system_names for the available system name constants.

§Threading Model

The engine runs on a single thread with async GPU operations via wgpu and fixed timestep physics with interpolation for smooth rendering.

§Platform Notes

Native (Windows/macOS/Linux): Full feature support with DirectX 12, Metal, or Vulkan.
WebAssembly: WebGPU backend. Files via drag-and-drop or HTTP. No WASI plugins. Async initialization.

Re-exports§

pub use crate::ecs::ui::widget_systems::ui_retained_input_sync_system;
pub use crate::ecs::camera::systems::*;
pub use crate::ecs::input::systems::*;
pub use crate::ecs::transform::systems::*;
pub use crate::ecs::ui::picking::*;
pub use crate::ecs::ui::render_sync::*;
pub use crate::ecs::ui::systems::*;

Modules§

ecs: Entity Component System module.
filesystem
logging: File-based logging configuration types.
prelude: Common re-exports for application code.
render: Rendering system using WebGPU (wgpu).
run: Application entry point and main loop.
schedule
state: Application state trait and render-graph resource handles.

Macros§

widget_data: Defines a widget data struct with Default, Clone, Debug derived and a WidgetData impl, removing the impl_widget_data! line that would otherwise be needed.