nightshade-api 0.44.0

Procedural high level API for the nightshade game engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

//! The event boundary's read side.
//!
//! A participant reads [`drain_events`] to see what the engine published this
//! cycle. To act it builds a [`Command`](crate::Command) and runs
//! [`submit_command`](crate::submit_command), or, for rhai, the
//! [`scripting`](crate::scripting) runner produces and submits typed commands.
//! There is no separate command queue: the command is the one api `Command`,
//! applied the moment a participant produces it (deferred-batched for scripts),
//! so nothing serializes in process.

use enum2schema::serde_json::{self, Value};
use nightshade::ecs::event::{cycle, set_journal_enabled};
use nightshade::prelude::World;

pub use nightshade::ecs::event::{Event, emit_event};

/// A snapshot of the events visible this cycle. The set is frozen for the cycle
/// and replaced at the next frame, so taking a copy here never disturbs other
/// participants reading the same set.
pub fn drain_events(world: &World) -> Vec<Event> {
    nightshade::ecs::event::events(world).to_vec()
}

/// This cycle's events as a json array, the read side of the boundary for a
/// consumer across a language or process edge: it drains events as json and
/// reacts, the mirror of submitting a command as json. In process, prefer
/// [`drain_events`], which hands back typed values with no serialization.
pub fn drain_events_json(world: &World) -> String {
    serde_json::to_string(&drain_events(world)).unwrap_or_else(|_| "[]".to_string())
}

/// The JSON Schema for [`Event`], for tools that document or validate the
/// engine's published event set, and that a binding's event decoder is
/// generated from.
pub fn event_schema() -> Value {
    <Event as enum2schema::Schema>::schema()
}

/// Turns the engine's event journal on or off. A tool that wants to show the
/// published events drains
/// [`drain_journal`](nightshade::prelude::drain_journal) while it is on.
pub fn watch_events(world: &mut World, enabled: bool) {
    set_journal_enabled(world, enabled);
}

/// The current cycle index.
pub fn current_cycle(world: &World) -> u64 {
    cycle(world)
}