Feature Flags

Nightshade uses Cargo feature flags to enable optional functionality. This allows you to include only the features you need, reducing compile times and binary size.

Default Features

Nightshade defaults to ["engine", "wgpu"]:

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

This gives you the full engine with the wgpu rendering backend. You only need to specify features explicitly if you want additional optional features or a minimal configuration.

Aggregate Features

engine (default)

The main engine feature. Includes everything needed for building games.

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

Includes: runtime, assets, scene_graph, picking, file_dialog, async_runtime, terrain, screenshot, plus rand, rayon, ehttp, futures, and WASM support libraries (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

Minimal rendering without asset loading. Use for lightweight apps that don't need glTF/image loading.

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

Includes: core, text, behaviors.

full

Everything in engine plus all major optional features.

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

Includes: engine, wgpu, egui, shell, audio, physics, gamepad, navmesh, scripting, fbx, lattice, sdf_sculpt, mosaic, editor, plugins.

Granular Features

These provide fine-grained control over dependencies:

core

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

text

MSDF text rendering using ttf-parser. Requires core.

assets

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

scene_graph

Scene hierarchy system with save/load. Requires assets.

terrain

Procedural terrain generation using noise and rand. Requires core.

file_dialog

Native file dialogs using rfd and dirs. Enables 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.

async_runtime

Tokio async runtime for non-blocking operations. Requires core.

screenshot

PNG screenshot saving using image.

picking

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

file_watcher

File watching support via notify. Enables FileWatcher for monitoring file changes and triggering hot-reloads. Native only (not available on WASM).

behaviors

Built-in behavior components and systems.

Rendering

wgpu (default)

WebGPU-based rendering backend supporting DirectX 12, Metal, Vulkan, and WebGPU.

Optional Features

egui

Immediate mode GUI framework. Enables fn ui() on the State trait.

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

Additional Dependencies: egui, egui_extras, egui-winit, egui-wgpu, egui_tiles

shell

Developer console with command registration. Press backtick to open. Requires egui.

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

audio

Audio playback using Kira.

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

Provides:

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

fft

FFT-based audio analysis for music-reactive applications.

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

Provides:

• Real-time FFT spectral analysis
• Six-band frequency decomposition (sub-bass to highs)
• Beat detection (kick, snare, hi-hat)
• BPM estimation and beat phase tracking
• Spectral features (centroid, flatness, rolloff, flux)
• Onset detection with adaptive thresholding

Additional Dependencies: rustfft

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
• Trimesh picking (when combined with picking)

Additional Dependencies: rapier3d

gamepad

Gamepad/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 (0.0 - 1.0)
• Rumble/vibration
• Multiple gamepad support

navmesh

AI navigation mesh generation 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 navigation mesh
• Debug visualization

Additional Dependencies: rerecast, glam

scripting

Rhai scripting runtime for dynamic behavior.

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

fbx

FBX model loading using ufbx. Requires assets.

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

lattice

Lattice deformation system for free-form mesh deformation.

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

sdf_sculpt

Signed Distance Field sculpting system.

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

Platform Features

openxr

OpenXR VR support. Uses Vulkan backend. Provides launch_xr() entry point, VR input (head/hand tracking, controllers), and locomotion.

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

Additional Dependencies: openxr, ash, wgpu-hal, gpu-allocator

steam

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

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

Additional Dependencies: steamworks, steamworks-sys

webview

Bidirectional IPC for hosting web frontends (Leptos, Yew, etc.) inside a nightshade window.

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

Additional Dependencies: wry, tiny_http, include_dir, wasm-bindgen, js-sys, web-sys

mosaic

Multi-pane desktop application framework built on egui_tiles. Provides dockable tile-based layouts, a Widget trait for serializable panes, theming with 11 presets, modal dialogs, toast notifications, command palettes, keyboard shortcuts, file dialogs, project save/load, status bars, FPS counters, undo/redo history, clipboard helpers, drag-and-drop support, and a built-in ViewportWidget for rendering camera outputs.

Requires egui.

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

Key types: Mosaic, Widget, Pane, WidgetContext, ViewportWidget, ThemeState, Modals, Toasts, StatusBar, CommandPalette, ShortcutManager, Settings, EventLog, FpsCounter, MosaicConfig, ProjectSaveFile, LayoutEvent

editor

Scene editor infrastructure for building custom editors. Provides gizmo manipulation, undo/redo, component inspectors, entity picking, selection management, clipboard operations, keyboard shortcuts, scene tree UI, context menus, camera controls, and asset loading utilities.

Requires mosaic and picking.

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

Provides:

• Transform gizmos (translate, rotate, scale) with local/global coordinate spaces
• Modal transform operations (Blender-style G/R/S keys with axis constraints)
• Undo/redo history with entity snapshots
• Component inspector UI for all built-in components
• GPU-based entity picking and marquee selection
• Entity selection with multi-select, copy/paste, duplicate
• Scene tree with drag-and-drop reparenting
• Context menus and add-node modal
• Camera view presets and ortho toggle
• Keyboard shortcut handler (Blender-style)
• Code editor with syntax highlighting (syntect, native only)
• Clipboard integration (arboard, native only)

Additional Dependencies: syntect (native only), arboard (native only)

Key types: EditorContext, UndoHistory, ComponentInspectorUi, InspectorContext, WorldTreeUi, EntitySelection, TreeCache, GizmoInteraction, InputSignal

windows-app-icon

Embed 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

Chrome tracing output for chrome://tracing. Implies tracing.

Plugin Features

plugins

Guest-side WASM plugin API for creating plugins.

plugin_runtime

WASM plugin hosting via Wasmtime. Requires assets.

Additional Dependencies: wasmtime, wasmtime-wasi, anyhow

Terminal Features

tui

Terminal UI framework built on the engine's rendering. Includes runtime and text.

Additional Dependencies: rand

terminal

Crossterm-based terminal applications without the full rendering pipeline.

Additional Dependencies: crossterm, rand, freecs

Other Features

mcp

Starts an HTTP-based Model Context Protocol server on http://127.0.0.1:3333/mcp when the application launches. Any MCP client (Claude Code, Claude Desktop, or custom tooling) can connect and manipulate the running scene in real time through 50+ tools covering entities, transforms, materials, lighting, physics, animation, scripting, and more.

Requires async_runtime and behaviors. Native only (not available on WASM).

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

Connect Claude Code to the running engine:

claude mcp add --transport http nightshade http://127.0.0.1:3333/mcp

Applications can intercept MCP commands before the engine processes them with handle_mcp_command and react to results with after_mcp_command on the State trait. See the AI Integration chapter for details.

Additional Dependencies: axum, rmcp, schemars

claude

Provides types and a background worker thread for spawning Claude Code CLI as a subprocess and streaming its JSON output. This lets applications embed an AI assistant that can send queries, receive streamed responses (text, thinking, tool use events), and manage sessions.

Native only (not available on WASM).

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

Key types:

• ClaudeConfig — system prompt, allowed/disallowed tools, MCP config, custom CLI args
• CliCommand — StartQuery (with prompt, optional session ID and model) and Cancel
• CliEvent — SessionStarted, TextDelta, ThinkingDelta, ToolUseStarted, ToolUseInputDelta, ToolUseFinished, TurnComplete, Complete, Error

When both claude and mcp are enabled, McpConfig::Auto automatically generates the MCP config JSON pointing at http://127.0.0.1:3333/mcp, so Claude Code connects to the engine without manual setup.

Additional Dependencies: serde_json

Feature Combinations

Minimal Rendering App

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

Lightweight egui app without asset loading.

Standard Game

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

Full game features with UI, physics, audio, and gamepad.

Open World Game

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

Everything for large outdoor environments with AI pathfinding.

VR Game

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

Virtual reality with physics and audio.

Music Visualizer

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

Audio-reactive visualizations with FFT analysis.

Desktop Tool

nightshade = { git = "...", features = ["mosaic", "egui"] }

Multi-pane desktop application with dockable widgets.

Custom Scene Editor

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

Full scene editor with gizmos, inspectors, undo/redo, FBX import, physics colliders, and navmesh editing.

Feature Dependencies

Some features have implicit dependencies:

Checking Enabled Features

Use cfg attributes for conditional compilation:

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