nightshade_api/

lib.rs

//! # 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:
//!
//! ```ignore
//! 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:
//!
//! ```toml
//! nightshade-api = "0.43"
//! ```
//!
//! ## 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:
//!
//! ```ignore
//! 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:
//!
//! ```ignore
//! 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();
//! ```
//!
//! `run` returns a `Result`, so a real `main` returns it. For several per-frame
//! jobs, the [`run!`](crate::run) macro takes any number of update systems:
//!
//! ```ignore
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     run!(setup, handle_input, move_player, check_collisions)
//! }
//! ```
//!
//! ## 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:
//!
//! ```ignore
//! 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`. Every example also
//! runs in the browser with `just run-example-wasm solar_system`, which serves
//! it through trunk.

pub use nightshade;

mod animate;
#[cfg(not(target_arch = "wasm32"))]
mod app;
mod appearance;
#[cfg(feature = "audio")]
mod audio;
mod camera;
mod decals;
mod draw;
mod effects;
mod environment;
mod groups;
mod input;
mod lighting;
#[cfg(feature = "navmesh")]
mod navigation;
mod palette;
#[cfg(feature = "physics")]
mod physics;
#[cfg(feature = "picking")]
mod picking;
mod placement;
mod runner;
mod scene;
mod text;

/// Everything in one import.
///
/// ```ignore
/// use nightshade_api::prelude::*;
/// ```
///
/// Pulls in the full api surface plus the engine types it hands you:
/// [`World`], [`Entity`], the math types, [`KeyCode`], and [`MouseButton`].
pub mod prelude {
    pub use crate::animate::*;
    #[cfg(not(target_arch = "wasm32"))]
    pub use crate::app::{App, Window, frame, open, open_with, render_image};
    pub use crate::appearance::*;
    #[cfg(feature = "audio")]
    pub use crate::audio::*;
    pub use crate::camera::*;
    pub use crate::decals::*;
    pub use crate::draw::*;
    pub use crate::effects::*;
    pub use crate::environment::*;
    pub use crate::groups::*;
    pub use crate::input::*;
    pub use crate::lighting::*;
    #[cfg(feature = "navmesh")]
    pub use crate::navigation::*;
    pub use crate::palette::*;
    #[cfg(feature = "physics")]
    pub use crate::physics::*;
    #[cfg(feature = "picking")]
    pub use crate::picking::*;
    pub use crate::placement::*;
    pub use crate::run;
    pub use crate::runner::{run, run_scene, systems};
    pub use crate::scene::*;
    pub use crate::text::*;

    pub use nightshade::ecs::graphics::resources::DepthOfField;
    #[cfg(feature = "physics")]
    pub use nightshade::ecs::physics::joints::{
        FixedJoint, JointAxisDirection, JointHandle, RevoluteJoint, RopeJoint, SpringJoint,
    };
    #[cfg(feature = "physics")]
    pub use nightshade::prelude::{CollisionEvent, RaycastHit};
    pub use nightshade::prelude::{
        EasingFunction, Entity, Fog, InstanceTransform, KeyCode, Line, MouseButton, Vec2, Vec3,
        Vec4, World, nalgebra_glm, vec2, vec3, vec4,
    };
}