nightshade_api/
lib.rs

1//! # nightshade-api
2//!
3//! A procedural high level API over the nightshade engine. Write a full 3d
4//! scene or a small game as straight-line code with free functions and plain
5//! data. No trait to implement, no callbacks to wire up, no ECS knowledge
6//! required to get started.
7//!
8//! A spinning cube is the whole pitch:
9//!
10//! ```ignore
11//! use nightshade_api::prelude::*;
12//!
13//! fn main() {
14//!     let mut app = open();
15//!     let cube = spawn_cube(&mut app.world, vec3(0.0, 0.5, 0.0));
16//!     while frame(&mut app) {
17//!         let step = delta_time(&app.world);
18//!         rotate(&mut app.world, cube, Vec3::y(), step);
19//!     }
20//! }
21//! ```
22//!
23//! Add to Cargo.toml:
24//!
25//! ```toml
26//! nightshade-api = "0.38"
27//! ```
28//!
29//! ## What you get for free
30//!
31//! [`prelude::open`] gives you a window with a sky, a sun with shadows, a
32//! reference grid, an orbit camera focused on the origin, prototype textures
33//! like `"checkerboard"`, and escape to exit. Every program starts from a lit,
34//! navigable scene. Override any of it with one call: [`prelude::set_background`],
35//! [`prelude::show_grid`], [`prelude::fly_camera`], [`prelude::set_sun`].
36//!
37//! ## The two entry points
38//!
39//! Own the loop (native only). Setup is ordinary code before the loop, state
40//! is ordinary locals across loop iterations:
41//!
42//! ```ignore
43//! let mut app = open();
44//! let mut score = 0;
45//! while frame(&mut app) {
46//!     score += 1;
47//! }
48//! ```
49//!
50//! Or hand the engine the loop with [`prelude::run`], which also works on
51//! wasm. Setup returns your state, the update closure receives it back every
52//! frame:
53//!
54//! ```ignore
55//! run(
56//!     |world| spawn_cube(world, vec3(0.0, 0.5, 0.0)),
57//!     |world, cube| {
58//!         let step = delta_time(world);
59//!         rotate(world, *cube, Vec3::y(), step);
60//!     },
61//! )
62//! .unwrap();
63//! ```
64//!
65//! ## Vocabulary
66//!
67//! Two verbs carry the lifetime rules. `spawn_` is retained: the thing exists
68//! until you [`prelude::despawn`] it. `draw_` is immediate: visible for
69//! exactly one frame, redraw it every frame you want it on screen.
70//!
71//! - Scene content: [`prelude::spawn_cube`], [`prelude::spawn_sphere`],
72//!   [`prelude::spawn_floor`], [`prelude::spawn_model`], [`prelude::spawn_object`]
73//! - Looks: [`prelude::set_color`], [`prelude::set_metallic_roughness`],
74//!   [`prelude::set_emissive`], [`prelude::set_texture`]
75//! - Placement: [`prelude::set_position`], [`prelude::rotate`], [`prelude::set_scale`],
76//!   [`prelude::set_parent`]
77//! - Cameras: [`prelude::orbit_camera`], [`prelude::fly_camera`],
78//!   [`prelude::first_person`], [`prelude::fixed_camera`]
79//! - Input: [`prelude::key_down`], [`prelude::wasd`], [`prelude::mouse_clicked`],
80//!   [`prelude::clicked_entity`]
81//! - Immediate drawing: [`prelude::draw_cube`], [`prelude::draw_sphere`],
82//!   [`prelude::draw_line`]
83//! - Text: [`prelude::spawn_text`], [`prelude::set_text`], [`prelude::spawn_label`]
84//!
85//! ## Dropping down to the engine
86//!
87//! Every function here takes the real engine [`prelude::World`] and bottoms
88//! out in normal nightshade calls. Nothing is hidden behind a wrapper type,
89//! so when a program outgrows the facade you replace one call site at a time.
90//! The full engine is re-exported at [`nightshade`], one path away:
91//!
92//! ```ignore
93//! use nightshade_api::nightshade::prelude::*;
94//! ```
95//!
96//! ## Examples
97//!
98//! The `examples/` directory is the tour. Run one with
99//! `just run-example solar_system` from the repo root, or
100//! `cargo run -r -p nightshade-api --example solar_system`.
101
102pub use nightshade;
103
104#[cfg(not(target_arch = "wasm32"))]
105mod app;
106mod appearance;
107#[cfg(feature = "audio")]
108mod audio;
109mod camera;
110mod draw;
111mod environment;
112mod input;
113mod lighting;
114mod palette;
115#[cfg(feature = "physics")]
116mod physics;
117#[cfg(feature = "picking")]
118mod picking;
119mod placement;
120mod runner;
121mod scene;
122mod text;
123
124/// Everything in one import.
125///
126/// ```ignore
127/// use nightshade_api::prelude::*;
128/// ```
129///
130/// Pulls in the full api surface plus the engine types it hands you:
131/// [`World`], [`Entity`], the math types, [`KeyCode`], and [`MouseButton`].
132pub mod prelude {
133    #[cfg(not(target_arch = "wasm32"))]
134    pub use crate::app::{App, Window, frame, open, open_with};
135    pub use crate::appearance::*;
136    #[cfg(feature = "audio")]
137    pub use crate::audio::*;
138    pub use crate::camera::*;
139    pub use crate::draw::*;
140    pub use crate::environment::*;
141    pub use crate::input::*;
142    pub use crate::lighting::*;
143    pub use crate::palette::*;
144    #[cfg(feature = "physics")]
145    pub use crate::physics::*;
146    #[cfg(feature = "picking")]
147    pub use crate::picking::*;
148    pub use crate::placement::*;
149    pub use crate::runner::{run, run_scene};
150    pub use crate::scene::*;
151    pub use crate::text::*;
152
153    #[cfg(feature = "physics")]
154    pub use nightshade::prelude::{CollisionEvent, RaycastHit};
155    pub use nightshade::prelude::{
156        Entity, Fog, KeyCode, Line, MouseButton, Vec2, Vec3, Vec4, World, nalgebra_glm, vec2, vec3,
157        vec4,
158    };
159}
nightshade_api/lib.rs

nightshade_api/
lib.rs
