Crate nightshade_api 

nightshade-api

A procedural high level API over the nightshade engine. Write a full 3d scene or a small game as straight-line code with free functions and plain data. No trait to implement, no callbacks to wire up, no ECS knowledge required to get started.

A spinning cube is the whole pitch:

use nightshade_api::prelude::*;

fn main() {
    let mut app = open();
    let cube = spawn_cube(&mut app.world, vec3(0.0, 0.5, 0.0));
    while frame(&mut app) {
        let step = delta_time(&app.world);
        rotate(&mut app.world, cube, Vec3::y(), step);
    }
}

Add to Cargo.toml:

nightshade-api = "0.40"

What you get for free

prelude::open gives you a window with a sky, a sun with shadows, a reference grid, an orbit camera focused on the origin, prototype textures like "checkerboard", and escape to exit. Every program starts from a lit, navigable scene. Override any of it with one call: prelude::set_background, prelude::show_grid, prelude::fly_camera, prelude::set_sun.

The two entry points

Own the loop (native only). Setup is ordinary code before the loop, state is ordinary locals across loop iterations:

let mut app = open();
let mut score = 0;
while frame(&mut app) {
    score += 1;
}

Or hand the engine the loop with prelude::run, which also works on wasm. Setup returns your state, the update closure receives it back every frame:

run(
    |world| spawn_cube(world, vec3(0.0, 0.5, 0.0)),
    |world, cube| {
        let step = delta_time(world);
        rotate(world, *cube, Vec3::y(), step);
    },
)
.unwrap();

Vocabulary

Two verbs carry the lifetime rules. spawn_ is retained: the thing exists until you prelude::despawn it. draw_ is immediate: visible for exactly one frame, redraw it every frame you want it on screen.

• Scene content: prelude::spawn_cube, prelude::spawn_sphere, prelude::spawn_floor, prelude::spawn_model, prelude::spawn_object
• Crowds: prelude::spawn_objects, prelude::spawn_instanced
• Tags: prelude::tag, prelude::tagged, prelude::for_each_tagged
• Looks: prelude::set_color, prelude::set_metallic_roughness, prelude::set_emissive, prelude::set_texture
• Placement: prelude::set_position, prelude::rotate, prelude::set_scale, prelude::set_parent
• Cameras: prelude::orbit_camera, prelude::fly_camera, prelude::first_person, prelude::fixed_camera
• Input: prelude::key_down, prelude::wasd, prelude::mouse_clicked, prelude::clicked_entity
• Immediate drawing: prelude::draw_cube, prelude::draw_sphere, prelude::draw_line
• Text: prelude::spawn_text, prelude::set_text, prelude::spawn_label

Dropping down to the engine

Every function here takes the real engine prelude::World and bottoms out in normal nightshade calls. Nothing is hidden behind a wrapper type, so when a program outgrows the facade you replace one call site at a time. The full engine is re-exported at nightshade, one path away:

use nightshade_api::nightshade::prelude::*;

Examples

The examples/ directory is the tour. Run one with just run-example solar_system from the repo root, or cargo run -r -p nightshade-api --example solar_system.

Re-exports

pub use nightshade;

Modules

prelude

Everything in one import.