Feature Flags

Nightshade is split into Cargo features so you can compile only the parts you use. Turning a feature off drops its dependencies and shortens build times.

Default Features

The default set is ["engine", "wgpu"]:

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

That gives you the engine with the wgpu backend. You only need to set features explicitly when adding optional ones or stripping the build down.

Aggregate Features

engine (default)

The everything-included build for making a game.

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

Includes: runtime, assets, scene_graph, picking, file_dialog, terrain, screenshot, plus rand, rayon, ehttp, futures, and the WASM support crates (js-sys, wasm-bindgen, wasm-bindgen-futures, web-sys).

Provides:

• Window creation and event loop
• wgpu rendering backend
• ECS (freecs)
• Transform hierarchy
• Camera systems
• Mesh rendering and GPU instancing
• PBR material system
• Lighting (directional, point, spot) with shadows
• Post-processing (bloom, SSAO, depth of field, tonemapping)
• Procedural atmospheres (sky, clouds, space, nebula)
• glTF/GLB model loading
• Scene save/load
• Input handling (keyboard, mouse, touch)
• Procedural terrain
• Picking (bounding box ray casting)
• File dialogs
• Screenshot capture

runtime

Rendering without asset loading. Use this for small apps that do not need glTF or image decoding.

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

Includes: core, text, behaviors.

full

engine plus every optional feature.

nightshade = { git = "...", features = ["full"] }

Includes: engine, wgpu, shell, audio, physics, gamepad, navmesh.

Granular Features

These let you pick exactly which dependencies come along.

core

The foundation. ECS (freecs), math (nalgebra, nalgebra-glm), windowing (winit), time (web-time), graph (petgraph), tracing, UUIDs, and JSON serialization.

text

Text rendering via cosmic-text and swash. Requires core.

assets

Asset loading: gltf, image, half, bincode, serde_json, lz4 compression. Requires core.

scene_graph

Scene hierarchy with save and load. Requires assets.

terrain

Procedural terrain generation using noise and rand. Requires core.

file_dialog

Native file dialogs via rfd and dirs. Turns on the native-only functions in nightshade::filesystem (pick_file, pick_folder, save_file_dialog, read_file, write_file). The cross-platform functions (save_file, request_file_load) are always available on WASM and require this feature on native. See the File System chapter. Requires core.

screenshot

PNG screenshot writing via the image crate.

picking

Ray-based entity picking with bounding box intersection. Trimesh picking also requires physics.

file_watcher

File-watch support via notify. Provides FileWatcher for hot reloads. Native only, not available on WASM.

behaviors

Built-in behavior components and systems.

Rendering

wgpu (default)

The wgpu rendering backend, which targets DirectX 12, Metal, Vulkan, and WebGPU through one API.

Optional Features

shell

Marker feature for the developer console and its command registration.

nightshade = { git = "...", features = ["shell"] }

audio

Audio playback via Kira.

nightshade = { git = "...", features = ["audio"] }

Provides:

• Sound loading (WAV, OGG, MP3, FLAC)
• Volume, pitch, and panning controls
• Spatial 3D audio with distance attenuation
• Audio listener and source components
• Looping and one-shot playback

physics

Rapier3D physics integration.

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

Provides:

• Rigid body simulation (dynamic, kinematic, static)
• Collider shapes (box, sphere, capsule, cylinder, cone, convex hull, trimesh, heightfield)
• Collision detection
• Character controllers
• Physics interpolation for smooth rendering between fixed steps
• Trimesh picking when combined with picking

Additional dependencies: rapier3d

gamepad

Gamepad and controller support via gilrs.

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

Provides:

• Gamepad detection and hot-plugging
• Button input (face buttons, triggers, bumpers, D-pad)
• Analog stick input with deadzone handling
• Trigger pressure in the 0.0 to 1.0 range
• Rumble and vibration
• Multiple connected gamepads

navmesh

AI navigation meshes via Recast.

nightshade = { git = "...", features = ["navmesh"] }

Provides:

• Navigation mesh generation from world geometry
• A* and Dijkstra pathfinding
• NavMesh agent component with autonomous movement
• Height sampling on the mesh
• Debug visualization

Additional dependencies: rerecast, glam

grass

GPU grass rendering with wind, distance fade, and interaction.

nightshade = { git = "...", features = ["grass"] }

Platform Features

steam

Steamworks integration for achievements, stats, multiplayer, and friends.

nightshade = { git = "...", features = ["steam"] }

Additional dependencies: steamworks, steamworks-sys

windows-app-icon

Embeds a custom icon into Windows executables at build time.

nightshade = { git = "...", features = ["windows-app-icon"] }

Additional dependencies: winresource, ico, image

Profiling Features

tracing

Rolling log files and RUST_LOG support via tracing-appender.

tracy

Real-time profiling with Tracy. Implies tracing.

chrome

Trace files for chrome://tracing. Implies tracing.

Feature Combinations

Minimal Rendering App

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

A small runtime build with no asset loading.

Standard Game

nightshade = { git = "...", features = ["physics", "audio", "gamepad"] }

The engine plus physics, audio, and gamepad input.

Open World Game

nightshade = { git = "...", features = [
    "physics",
    "audio",
    "gamepad",
    "navmesh",
    "grass",
] }

Adds AI pathfinding and GPU grass on top of the standard set.

Feature Dependencies

Several features pull others in implicitly.

Checking Enabled Features

Use cfg attributes to gate code on a feature being on:

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

    #[cfg(feature = "physics")]
    {
        let entity = world.spawn_entities(
            RIGID_BODY | COLLIDER | LOCAL_TRANSFORM | GLOBAL_TRANSFORM | LOCAL_TRANSFORM_DIRTY | RENDER_MESH,
            1,
        )[0];
        world.core.set_rigid_body(entity, RigidBodyComponent::new_dynamic());
        world.core.set_collider(entity, ColliderComponent::new_cuboid(0.5, 0.5, 0.5));
    }

    #[cfg(feature = "audio")]
    {
        let source = world.spawn_entities(AUDIO_SOURCE | LOCAL_TRANSFORM | GLOBAL_TRANSFORM, 1)[0];
        world.core.set_audio_source(source, AudioSource::new("music").with_looping(true).playing());
    }
}
}