gizmo_scripting/
lib.rs

1//! Gizmo Scripting — a Lua-based game-logic scripting layer for the Gizmo engine.
2//!
3//! Scripts run inside a sandboxed [`mlua`] Lua 5.4 VM. Because Lua callbacks
4//! cannot borrow and mutate the ECS `World` directly, they enqueue changes as
5//! [`ScriptCommand`]s into a [`CommandQueue`]; the [`ScriptEngine`] later drains
6//! and applies those commands at a controlled point in the frame.
7//!
8//! ## Usage
9//! ```rust,ignore
10//! let mut script_engine = ScriptEngine::new().unwrap();
11//! script_engine.load_script("scripts/player.lua").unwrap();
12//!
13//! // Each frame:
14//! script_engine.update(&world, &input, dt).unwrap();
15//! script_engine.flush_commands(&mut world);
16//! ```
17//!
18//! ## Lua API surface
19//! - `entity` — read/write position, rotation, scale, velocity; spawn/destroy
20//! - `input` — query key and mouse state
21//! - `physics` — apply forces and impulses
22//! - `scene` — save/load scenes, look up entities
23//! - `audio` — play 2D/3D sounds
24//! - `time` — delta time, elapsed time, FPS
25
26pub mod api_ai;
27pub mod api_audio;
28pub mod api_entity;
29pub mod api_fighter;
30pub mod api_input;
31pub mod api_physics;
32pub mod api_scene;
33pub mod api_time;
34pub mod api_vehicle;
35pub mod commands;
36
37#[cfg(target_arch = "wasm32")]
38pub mod dummy_engine;
39pub mod engine;
40
41pub use commands::{CommandQueue, ScriptCommand};
42
43pub use engine::{Script, ScriptContext, ScriptEngine, ScriptResult};
44
45/// Registers the scripting layer's serializable scene components (currently
46/// [`Script`]) into a scene `ComponentRegistry`.
47///
48/// Call this from the layer that wires both scenes and scripting together (the
49/// app / editor / facade) so that `gizmo-scene` itself stays free of any
50/// dependency on `gizmo-scripting`. Without this call a scene round-trips fine,
51/// it simply won't (de)serialize `Script` components.
52#[cfg(not(target_arch = "wasm32"))]
53pub fn register_script_components(reg: &mut gizmo_core::registry::ComponentRegistry) {
54    reg.register_serializable::<Script>("Script")
55        .expect("built-in component 'Script' registration must not conflict");
56}
57
58/// No-op on `wasm32`, where the Lua-backed scripting engine is unavailable.
59#[cfg(target_arch = "wasm32")]
60pub fn register_script_components(_reg: &mut gizmo_core::registry::ComponentRegistry) {}
61
62#[cfg(target_arch = "wasm32")]
63pub use dummy_engine::{
64    Script as DummyScript, ScriptContext as DummyContext, ScriptEngine as DummyEngine,
65    ScriptResult as DummyResult,
66};
gizmo_scripting/lib.rs

gizmo_scripting/
lib.rs
