Skip to main content

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:
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.47"
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 [`run`](fn@crate::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//! `run` returns a `Result`, so a real `main` returns it. For several per-frame
66//! jobs, the [`run!`](crate::run!) macro takes any number of update systems:
67//!
68//! ```ignore
69//! fn main() -> Result<(), Box<dyn std::error::Error>> {
70//!     run!(setup, handle_input, move_player, check_collisions)
71//! }
72//! ```
73//!
74//! For immediate-mode UI, enable the `egui` feature, call
75//! [`enable_egui`](fn@crate::prelude::enable_egui) once in setup, then draw from
76//! your update closure by pulling the frame's context with
77//! [`egui_context`](fn@crate::prelude::egui_context). No extra closure: it
78//! composes with [`run`](fn@crate::prelude::run) and [`run!`](crate::run!) as is.
79//! `egui` is re-exported from the prelude.
80//!
81//! ```ignore
82//! run(
83//!     |world| { enable_egui(world); spawn_cube(world, vec3(0.0, 0.5, 0.0)) },
84//!     |world, cube| {
85//!         rotate(world, *cube, Vec3::y(), delta_time(world));
86//!         if let Some(ctx) = egui_context(world) {
87//!             egui::Window::new("Inspector").show(&ctx, |ui| ui.label(format!("{cube:?}")));
88//!         }
89//!     },
90//! )
91//! .unwrap();
92//! ```
93//!
94//! ## Vocabulary
95//!
96//! Two verbs carry the lifetime rules. `spawn_` is retained: the thing exists
97//! until you [`prelude::despawn`] it. `draw_` is immediate: visible for
98//! exactly one frame, redraw it every frame you want it on screen.
99//!
100//! - Scene content: [`prelude::spawn_cube`], [`prelude::spawn_sphere`],
101//!   [`prelude::spawn_floor`], [`prelude::spawn_model`], [`prelude::spawn_object`]
102//! - Crowds: [`prelude::spawn_objects`], [`prelude::spawn_instanced`]
103//! - Tags: [`prelude::tag`], [`prelude::tagged`], [`prelude::for_each_tagged`]
104//! - Looks: [`prelude::set_color`], [`prelude::set_metallic_roughness`],
105//!   [`prelude::set_emissive`], [`prelude::set_texture`],
106//!   [`prelude::set_normal_texture`]
107//! - Placement: [`prelude::set_position`], [`prelude::rotate`], [`prelude::set_scale`],
108//!   [`prelude::set_parent`]
109//! - Cameras: [`prelude::orbit_camera`], [`prelude::fly_camera`],
110//!   [`prelude::first_person`], [`prelude::fixed_camera`],
111//!   [`prelude::set_field_of_view`], [`prelude::set_orthographic`]
112//! - Input: [`prelude::key_down`], [`prelude::wasd`], [`prelude::mouse_clicked`],
113//!   [`prelude::clicked_entity`]
114//! - Immediate drawing: [`prelude::draw_cube`], [`prelude::draw_sphere`],
115//!   [`prelude::draw_line`]
116//! - Text: [`prelude::spawn_text`], [`prelude::set_text`], [`prelude::spawn_label`]
117//! - UI: [`prelude::spawn_panel`], [`prelude::panel_button`],
118//!   [`prelude::panel_label`], [`prelude::button_clicked`]; plus the full widget
119//!   set: [`prelude::panel_data_grid`], [`prelude::panel_tree_view`],
120//!   [`prelude::panel_property_grid`], [`prelude::panel_color_picker`],
121//!   [`prelude::panel_date_picker`], [`prelude::panel_command_palette`],
122//!   [`prelude::panel_modal`], [`prelude::panel_virtual_list`]
123//! - Animation: [`prelude::play_animation`], [`prelude::play_animation_named`],
124//!   [`prelude::blend_to_animation`], [`prelude::set_animation_speed`]
125//! - Post-processing: [`prelude::set_ssao`], [`prelude::set_ssr`],
126//!   [`prelude::set_tonemap`], [`prelude::set_color_grading`]
127//! - Live physics tuning: [`prelude::set_friction`], [`prelude::set_restitution`],
128//!   [`prelude::set_mass`], [`prelude::set_gravity_scale`]
129//! - Layout containers: [`prelude::panel_row`], [`prelude::panel_grid`],
130//!   [`prelude::panel_scroll`]; world-space UI: [`prelude::spawn_world_panel`]
131//! - Animation extras: [`prelude::add_animation_event`],
132//!   [`prelude::add_animation_layer`], [`prelude::reach_to`], [`prelude::aim_at`]
133//! - Prefabs and undo: [`prelude::make_prefab`], [`prelude::spawn_prefab`],
134//!   [`prelude::UndoStack`]
135//!
136//! ## Reading the scene back
137//!
138//! The setters have readers, which is what a tool that edits a scene rather than
139//! just building one needs. [`prelude::describe_entity`] gathers an entity's
140//! whole editable state, [`prelude::get_color`] and friends read one field,
141//! [`prelude::scene_tree`] and [`prelude::children`] walk the hierarchy,
142//! [`prelude::list_materials`] reads the shared material registry, and
143//! [`prelude::bounds_of`] with [`prelude::frame_entities`] measure and frame a
144//! selection. [`prelude::save_scene`] and [`prelude::load_scene`] round-trip the
145//! whole world to bytes. Components are added, removed, and snapshotted for undo
146//! by [`prelude::ComponentKind`], the surface the standalone editor is built on.
147//!
148//! ## Commands
149//!
150//! Every call also has a data form. [`prelude::Command`] is a serde enum with
151//! one variant per function, [`prelude::submit_command`] runs one, and
152//! [`prelude::submit_commands`] runs a batch where a later command can name an
153//! entity an earlier one produced with [`prelude::Ref::Result`], so one batch
154//! builds and wires up a scene. The enum is the wire format a binding targets:
155//! build `Command` values, read [`prelude::CommandReply`] back, with the json
156//! schema from [`prelude::command_schema`]. The free functions stay the real
157//! implementations and the dispatch forwards to them.
158//! See the `commands` example and `docs/COMMAND_API.md`.
159//!
160//! ## Dropping down to the engine
161//!
162//! Every function here takes the real engine [`prelude::World`] and bottoms
163//! out in normal nightshade calls. Nothing is hidden behind a wrapper type,
164//! so when a program outgrows the facade you replace one call site at a time.
165//! The full engine is re-exported at [`nightshade`], one path away:
166//!
167//! ```ignore
168//! use nightshade_api::nightshade::prelude::*;
169//! ```
170//!
171//! ## Examples
172//!
173//! The `examples/` directory is the tour. Run one with
174//! `just run-example solar_system` from the repo root, or
175//! `cargo run -r -p nightshade-api --example solar_system`. Every example also
176//! runs in the browser with `just run-example-wasm solar_system`, which serves
177//! it through trunk.
178
179pub use nightshade;
180
181mod animate;
182#[cfg(not(target_arch = "wasm32"))]
183mod app;
184mod appearance;
185#[cfg(feature = "audio")]
186mod audio;
187mod bounds;
188mod camera;
189#[cfg(feature = "physics")]
190mod character;
191mod cloth;
192mod command;
193mod cutscene;
194mod decals;
195mod draw;
196#[cfg(feature = "scripting")]
197mod dynamic_de;
198#[cfg(feature = "protocol")]
199pub mod editor;
200mod effects;
201mod environment;
202mod events;
203mod filesystem;
204mod groups;
205mod hierarchy;
206mod input;
207mod inspect;
208mod lighting;
209mod materials;
210mod mesh;
211mod messaging;
212mod morph;
213#[cfg(feature = "navmesh")]
214mod navigation;
215#[cfg(all(feature = "net", not(target_arch = "wasm32")))]
216mod net;
217mod palette;
218#[cfg(feature = "physics")]
219mod physics;
220#[cfg(feature = "picking")]
221mod picking;
222mod placement;
223mod prefab;
224mod reflect;
225mod render;
226mod runner;
227mod scene;
228#[cfg(feature = "scripting")]
229mod scripting;
230mod serialize;
231#[cfg(any(feature = "terrain", feature = "grass"))]
232mod terrain;
233mod text;
234mod ui;
235mod undo;
236mod window;
237#[cfg(feature = "picking")]
238mod world_ui;
239
240/// Everything in one import.
241///
242/// ```ignore
243/// use nightshade_api::prelude::*;
244/// ```
245///
246/// Pulls in the full api surface plus the engine types it hands you:
247/// [`World`](crate::prelude::World), [`Entity`](crate::prelude::Entity), the math types, [`KeyCode`](crate::prelude::KeyCode), and [`MouseButton`](crate::prelude::MouseButton).
248pub mod prelude {
249    pub use crate::animate::*;
250    #[cfg(not(target_arch = "wasm32"))]
251    pub use crate::app::{App, Window, frame, open, open_with, render_image};
252    pub use crate::appearance::*;
253    #[cfg(feature = "audio")]
254    pub use crate::audio::*;
255    pub use crate::bounds::*;
256    pub use crate::camera::*;
257    #[cfg(feature = "physics")]
258    pub use crate::character::*;
259    pub use crate::cloth::*;
260    pub use crate::command::*;
261    pub use crate::cutscene::*;
262    pub use crate::decals::*;
263    pub use crate::draw::*;
264    pub use crate::effects::*;
265    pub use crate::environment::*;
266    pub use crate::events::*;
267    pub use crate::filesystem::*;
268    pub use crate::groups::*;
269    pub use crate::hierarchy::*;
270    pub use crate::input::*;
271    pub use crate::inspect::*;
272    pub use crate::lighting::*;
273    pub use crate::materials::*;
274    pub use crate::mesh::*;
275    pub use crate::messaging::*;
276    pub use crate::morph::*;
277    #[cfg(feature = "navmesh")]
278    pub use crate::navigation::*;
279    #[cfg(all(feature = "net", not(target_arch = "wasm32")))]
280    pub use crate::net::*;
281    pub use crate::palette::*;
282    #[cfg(feature = "physics")]
283    pub use crate::physics::*;
284    #[cfg(feature = "picking")]
285    pub use crate::picking::*;
286    pub use crate::placement::*;
287    pub use crate::prefab::*;
288    pub use crate::reflect::*;
289    pub use crate::render::*;
290    pub use crate::run;
291    pub use crate::runner::{run, run_scene, systems};
292    pub use crate::scene::*;
293    #[cfg(feature = "scripting")]
294    pub use crate::scripting::*;
295    pub use crate::serialize::*;
296    #[cfg(any(feature = "terrain", feature = "grass"))]
297    pub use crate::terrain::*;
298    pub use crate::text::*;
299    pub use crate::ui::*;
300    pub use crate::undo::*;
301    pub use crate::window::*;
302    #[cfg(feature = "picking")]
303    pub use crate::world_ui::*;
304    pub use nightshade::ecs::material::components::Material;
305    pub use nightshade::ecs::particles::components::ParticleEmitter;
306    #[cfg(feature = "navmesh")]
307    pub use nightshade::prelude::RecastNavMeshConfig;
308    #[cfg(feature = "egui")]
309    pub use nightshade::prelude::{egui, egui_context};
310
311    pub use nightshade::ecs::graphics::resources::DepthOfField;
312    #[cfg(feature = "physics")]
313    pub use nightshade::ecs::physics::joints::{
314        FixedJoint, JointAxisDirection, JointHandle, RevoluteJoint, RopeJoint, SpringJoint,
315    };
316    #[cfg(feature = "physics")]
317    pub use nightshade::prelude::{CollisionEvent, RaycastHit};
318    pub use nightshade::prelude::{
319        EasingFunction, Entity, Fog, InstanceTransform, KeyCode, Line, MouseButton, ShadingMode,
320        TextAlignment, Vec2, Vec3, Vec4, VerticalAlignment, ViewportShading, World, nalgebra_glm,
321        vec2, vec3, vec4,
322    };
323}