nightshade-api 0.44.0

//! A serializable command form of the API.
//!
//! Every call here also exists as a free function. The command layer mirrors the
//! API as a single [`Command`] enum so the same work can be driven three ways:
//! call the free function directly, [`submit_command`] one [`Command`], or
//! [`submit_commands`] a whole batch. The enum derives serde, so it doubles as
//! the wire format a binding (FFI, network, scripting) targets: a binding only
//! builds `Command` values and reads [`CommandReply`] back.
//!
//! Entities cross the boundary as the engine [`Entity`] itself, which is
//! serializable and stable, so a reply hands one back and a binding stores it.
//! Within a [`submit_commands`] batch a later command can also reference an
//! entity an earlier command produced through [`Ref::Result`], with no round
//! trip, which is what makes a single batch able to build and wire up a scene.
//!
//! The free functions stay the real implementations. The whole enum and its
//! dispatch are generated from one registry by the [`commands`] macro, so the
//! command surface cannot drift from the functions, and reference resolution and
//! reply wrapping are uniform across every command rather than retyped per arm.

use crate::scene::{Body, Object, Shape};
use nightshade::prelude::{Entity, KeyCode, MouseButton, TextAlignment, Vec3, World, vec3};
use serde::{Deserialize, Serialize};

/// How a command names an entity: an existing [`Entity`] a reply handed back, or
/// the entity produced by an earlier command in the same [`submit_commands`]
/// batch. `Entity` is itself serializable and stable, so a binding stores it and
/// hands it back verbatim, no separate handle type needed.
#[derive(Serialize, Deserialize, Clone, Copy, Debug, enum2schema::Schema)]
pub enum Ref {
    Entity(#[schema(with = entity_schema)] Entity),
    Result(u32),
    /// A live entity named by its id alone, resolved against the world at
    /// dispatch. Lets a caller reference an existing entity without tracking
    /// its generation, which is what a picked editor selection or a script's
    /// entity handle has.
    Existing(u32),
}

/// What a [`Command`] returns. Setters reply [`CommandReply::None`], spawns reply
/// the [`Entity`] they made, queries reply their value, and a failed reference
/// resolution replies [`CommandReply::Error`].
#[derive(Serialize, Deserialize, Clone, Debug, enum2schema::Schema)]
pub enum CommandReply {
    None,
    Entity(#[schema(with = entity_schema)] Entity),
    Bool(bool),
    Float(f32),
    Vector([f32; 3]),
    Entities(#[schema(with = entities_schema)] Vec<Entity>),
    Strings(Vec<String>),
    Error(String),
}

/// One field of a [`Command`] as data: its name, its Rust type as written, and
/// the dispatch role that says how the value is bound. Emitted by the same
/// registry that defines the commands, so a binding generator reads the surface
/// from a compiled artifact instead of parsing source.
#[derive(Serialize, Clone, Debug)]
pub struct FieldSpec {
    pub name: &'static str,
    pub type_name: &'static str,
    pub role: &'static str,
}

/// One [`Command`] as data: its variant name, fields, and reply kind.
#[derive(Serialize, Clone, Debug)]
pub struct CommandSpec {
    pub name: &'static str,
    pub fields: Vec<FieldSpec>,
    pub reply: &'static str,
}

/// [`command_manifest`] as a json string, the input a binding code generator
/// reads alongside [`command_schema`].
pub fn command_manifest_json() -> String {
    enum2schema::serde_json::to_string(&command_manifest()).unwrap_or_default()
}

fn entity_schema() -> enum2schema::serde_json::Value {
    enum2schema::serde_json::json!({
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "generation": { "type": "integer" }
        },
        "required": ["id", "generation"]
    })
}

fn entities_schema() -> enum2schema::serde_json::Value {
    enum2schema::serde_json::json!({ "type": "array", "items": entity_schema() })
}

/// The json schema for [`Command`], the wire form a binding builds. Derived from
/// the command enum by the same registry that defines it, so it always matches
/// the surface. Pair with [`command_reply_schema`] for the output shape.
pub fn command_schema() -> enum2schema::serde_json::Value {
    <Command as enum2schema::Schema>::schema()
}

/// The json schema for [`CommandReply`], what a binding reads back.
pub fn command_reply_schema() -> enum2schema::serde_json::Value {
    <CommandReply as enum2schema::Schema>::schema()
}

/// Runs one command and returns its reply.
pub fn submit_command(world: &mut World, command: &Command) -> CommandReply {
    dispatch(world, command, &[])
}

/// Runs a batch in order and returns one reply per command. A command may name
/// an entity an earlier command in the same batch produced with [`Ref::Result`],
/// so a batch can spawn entities and then configure and parent them in one call.
pub fn submit_commands(world: &mut World, commands: &[Command]) -> Vec<CommandReply> {
    let mut produced: Vec<Option<Entity>> = Vec::with_capacity(commands.len());
    let mut replies = Vec::with_capacity(commands.len());
    for command in commands {
        let reply = dispatch(world, command, &produced);
        produced.push(match &reply {
            CommandReply::Entity(entity) => Some(*entity),
            _ => None,
        });
        replies.push(reply);
    }
    replies
}

fn resolve(world: &World, reference: Ref, produced: &[Option<Entity>]) -> Option<Entity> {
    match reference {
        Ref::Entity(entity) => Some(entity),
        Ref::Result(index) => produced.get(index as usize).copied().flatten(),
        Ref::Existing(id) => world
            .core
            .entity_locations
            .get(id)
            .filter(|location| location.allocated)
            .map(|location| Entity {
                id,
                generation: location.generation,
            }),
    }
}

fn array_to_vec3(values: [f32; 3]) -> Vec3 {
    vec3(values[0], values[1], values[2])
}

fn array_to_vec2(values: [f32; 2]) -> nightshade::prelude::Vec2 {
    nightshade::prelude::vec2(values[0], values[1])
}

/// Adapts the flat command fields to [`spawn_object`](crate::scene::spawn_object),
/// which takes an [`Object`] struct. The dispatch macro calls functions with
/// positional arguments, so the one command that builds a struct goes through
/// this rather than special casing the macro.
fn spawn_object_command(
    world: &mut World,
    shape: Shape,
    position: Vec3,
    scale: Vec3,
    color: [f32; 4],
    body: Body,
) -> Entity {
    crate::scene::spawn_object(
        world,
        Object {
            shape,
            position,
            scale,
            color,
            body,
        },
    )
}

/// Maps a plain key name to a [`KeyCode`] for the input-query commands, so the
/// wire form names keys as strings like `"a"`, `"space"`, or `"left"` rather
/// than carrying the engine's key enum.
fn key_from_name(name: &str) -> Option<KeyCode> {
    let lower = name.to_ascii_lowercase();
    Some(match lower.as_str() {
        "a" => KeyCode::KeyA,
        "b" => KeyCode::KeyB,
        "c" => KeyCode::KeyC,
        "d" => KeyCode::KeyD,
        "e" => KeyCode::KeyE,
        "f" => KeyCode::KeyF,
        "g" => KeyCode::KeyG,
        "h" => KeyCode::KeyH,
        "i" => KeyCode::KeyI,
        "j" => KeyCode::KeyJ,
        "k" => KeyCode::KeyK,
        "l" => KeyCode::KeyL,
        "m" => KeyCode::KeyM,
        "n" => KeyCode::KeyN,
        "o" => KeyCode::KeyO,
        "p" => KeyCode::KeyP,
        "q" => KeyCode::KeyQ,
        "r" => KeyCode::KeyR,
        "s" => KeyCode::KeyS,
        "t" => KeyCode::KeyT,
        "u" => KeyCode::KeyU,
        "v" => KeyCode::KeyV,
        "w" => KeyCode::KeyW,
        "x" => KeyCode::KeyX,
        "y" => KeyCode::KeyY,
        "z" => KeyCode::KeyZ,
        "0" => KeyCode::Digit0,
        "1" => KeyCode::Digit1,
        "2" => KeyCode::Digit2,
        "3" => KeyCode::Digit3,
        "4" => KeyCode::Digit4,
        "5" => KeyCode::Digit5,
        "6" => KeyCode::Digit6,
        "7" => KeyCode::Digit7,
        "8" => KeyCode::Digit8,
        "9" => KeyCode::Digit9,
        "space" => KeyCode::Space,
        "enter" | "return" => KeyCode::Enter,
        "escape" | "esc" => KeyCode::Escape,
        "tab" => KeyCode::Tab,
        "backspace" => KeyCode::Backspace,
        "delete" => KeyCode::Delete,
        "left" => KeyCode::ArrowLeft,
        "right" => KeyCode::ArrowRight,
        "up" => KeyCode::ArrowUp,
        "down" => KeyCode::ArrowDown,
        "shift" | "lshift" => KeyCode::ShiftLeft,
        "rshift" => KeyCode::ShiftRight,
        "ctrl" | "control" | "lctrl" => KeyCode::ControlLeft,
        "rctrl" => KeyCode::ControlRight,
        "alt" | "lalt" => KeyCode::AltLeft,
        "ralt" => KeyCode::AltRight,
        _ => return None,
    })
}

/// Maps a button index to a [`MouseButton`]: 0 left, 1 middle, 2 right.
fn mouse_button_from_index(index: u8) -> MouseButton {
    match index {
        1 => MouseButton::Middle,
        2 => MouseButton::Right,
        _ => MouseButton::Left,
    }
}

fn key_down_command(world: &World, key: &str) -> bool {
    key_from_name(key)
        .map(|key| crate::input::key_down(world, key))
        .unwrap_or(false)
}

fn key_pressed_command(world: &World, key: &str) -> bool {
    key_from_name(key)
        .map(|key| crate::input::key_pressed(world, key))
        .unwrap_or(false)
}

fn mouse_down_command(world: &World, button: u8) -> bool {
    crate::input::mouse_down(world, mouse_button_from_index(button))
}

fn mouse_clicked_command(world: &World, button: u8) -> bool {
    crate::input::mouse_clicked(world, mouse_button_from_index(button))
}

macro_rules! bind_argument {
    ($field:ident, entity, $produced:ident, $world:ident) => {
        let $field = match resolve($world, *$field, $produced) {
            Some(entity) => entity,
            None => {
                return CommandReply::Error(
                    concat!(stringify!($field), ": unresolved entity reference").to_string(),
                );
            }
        };
    };
    ($field:ident, opt_entity, $produced:ident, $world:ident) => {
        let $field = match $field {
            Some(reference) => match resolve($world, *reference, $produced) {
                Some(entity) => Some(entity),
                None => {
                    return CommandReply::Error(
                        concat!(stringify!($field), ": unresolved entity reference").to_string(),
                    );
                }
            },
            None => None,
        };
    };
    ($field:ident, vec3, $produced:ident, $world:ident) => {
        let $field = array_to_vec3(*$field);
    };
    ($field:ident, vec2, $produced:ident, $world:ident) => {
        let $field = array_to_vec2(*$field);
    };
    ($field:ident, copy, $produced:ident, $world:ident) => {
        let $field = *$field;
    };
    ($field:ident, owned, $produced:ident, $world:ident) => {
        let $field = $field.clone();
    };
    ($field:ident, text, $produced:ident, $world:ident) => {
        let $field = $field.as_str();
    };
    ($field:ident, bytes, $produced:ident, $world:ident) => {
        let $field = $field.as_slice();
    };
}

macro_rules! wrap_reply {
    (none, $call:expr) => {{
        $call;
        CommandReply::None
    }};
    (entity, $call:expr) => {
        CommandReply::Entity($call)
    };
    (opt_entity, $call:expr) => {
        match $call {
            Some(entity) => CommandReply::Entity(entity),
            None => CommandReply::None,
        }
    };
    (bool, $call:expr) => {
        CommandReply::Bool($call)
    };
    (float, $call:expr) => {
        CommandReply::Float($call)
    };
    (vector, $call:expr) => {{
        let value = $call;
        CommandReply::Vector([value.x, value.y, value.z])
    }};
    (opt_vector, $call:expr) => {
        match $call {
            Some(value) => CommandReply::Vector([value.x, value.y, value.z]),
            None => CommandReply::None,
        }
    };
    (entities, $call:expr) => {
        CommandReply::Entities($call)
    };
    (strings, $call:expr) => {
        CommandReply::Strings($call)
    };
}

macro_rules! commands {
    (
        $(
            $(#[$meta:meta])*
            $variant:ident { $( $field:ident : $field_type:ty [$role:ident] ),* $(,)? }
                => $func:path , $reply:ident ;
        )*
    ) => {
        /// One API call as data. Field names and types match the free function
        /// it mirrors. Positions, axes, and colors are plain arrays so the wire
        /// form is clean json rather than a math library's internal layout.
        #[derive(Serialize, Deserialize, Clone, Debug, enum2schema::Schema)]
        pub enum Command {
            $(
                $(#[$meta])*
                $variant { $( $field : $field_type ),* },
            )*
        }

        impl Command {
            /// This command's variant name, the key the manifest and a binding use,
            /// read straight off the value with no serialization.
            pub fn name(&self) -> &'static str {
                match self {
                    $(
                        $(#[$meta])*
                        Command::$variant { .. } => stringify!($variant),
                    )*
                }
            }
        }

        fn dispatch(
            world: &mut World,
            command: &Command,
            produced: &[Option<Entity>],
        ) -> CommandReply {
            match command {
                $(
                    $(#[$meta])*
                    Command::$variant { $( $field ),* } => {
                        $( bind_argument!($field, $role, produced, world); )*
                        wrap_reply!($reply, $func(world $(, $field)*))
                    }
                )*
            }
        }

        /// The command surface as data, generated from the same registry as
        /// [`Command`] and its dispatch. cfg-gated commands appear only when
        /// their feature is compiled, so the manifest matches the surface a
        /// binding can actually reach.
        pub fn command_manifest() -> Vec<CommandSpec> {
            let mut specs = Vec::new();
            $(
                $(#[$meta])*
                specs.extend([CommandSpec {
                    name: stringify!($variant),
                    fields: vec![
                        $( FieldSpec {
                            name: stringify!($field),
                            type_name: stringify!($field_type),
                            role: stringify!($role),
                        } ),*
                    ],
                    reply: stringify!($reply),
                }]);
            )*
            specs
        }
    };
}

commands! {
    SpawnCube { position: [f32; 3] [vec3] } => crate::scene::spawn_cube, entity;
    SpawnSphere { position: [f32; 3] [vec3] } => crate::scene::spawn_sphere, entity;
    SpawnCylinder { position: [f32; 3] [vec3] } => crate::scene::spawn_cylinder, entity;
    SpawnCone { position: [f32; 3] [vec3] } => crate::scene::spawn_cone, entity;
    SpawnPlane { position: [f32; 3] [vec3] } => crate::scene::spawn_plane, entity;
    SpawnTorus { position: [f32; 3] [vec3] } => crate::scene::spawn_torus, entity;
    SpawnFloor { half_extent: f32 [copy] } => crate::scene::spawn_floor, entity;
    SpawnGroup { position: [f32; 3] [vec3] } => crate::scene::spawn_group, entity;
    SpawnModel { glb: Vec<u8> [bytes], position: [f32; 3] [vec3] } => crate::scene::spawn_model, entity;
    SpawnObject { shape: Shape [copy], position: [f32; 3] [vec3], scale: [f32; 3] [vec3], color: [f32; 4] [copy], body: Body [copy] } => spawn_object_command, entity;

    SetColor { entity: Ref [entity], color: [f32; 4] [copy] } => crate::appearance::set_color, none;
    SetMetallicRoughness { entity: Ref [entity], metallic: f32 [copy], roughness: f32 [copy] } => crate::appearance::set_metallic_roughness, none;
    SetEmissive { entity: Ref [entity], color: [f32; 3] [copy], strength: f32 [copy] } => crate::appearance::set_emissive, none;
    SetUnlit { entity: Ref [entity], unlit: bool [copy] } => crate::appearance::set_unlit, none;
    SetTexture { entity: Ref [entity], texture: String [text] } => crate::appearance::set_texture, none;
    SetTextureTiling { entity: Ref [entity], repeats: f32 [copy] } => crate::appearance::set_texture_tiling, none;
    SetNormalTexture { entity: Ref [entity], texture: String [text] } => crate::appearance::set_normal_texture, none;
    SetMetallicRoughnessTexture { entity: Ref [entity], texture: String [text] } => crate::appearance::set_metallic_roughness_texture, none;
    SetEmissiveTexture { entity: Ref [entity], texture: String [text] } => crate::appearance::set_emissive_texture, none;
    SetOcclusionTexture { entity: Ref [entity], texture: String [text] } => crate::appearance::set_occlusion_texture, none;

    SetPosition { entity: Ref [entity], position: [f32; 3] [vec3] } => crate::placement::set_position, none;
    SetScale { entity: Ref [entity], scale: [f32; 3] [vec3] } => crate::placement::set_scale, none;
    SetRotation { entity: Ref [entity], axis: [f32; 3] [vec3], radians: f32 [copy] } => crate::placement::set_rotation, none;
    Rotate { entity: Ref [entity], axis: [f32; 3] [vec3], radians: f32 [copy] } => crate::placement::rotate, none;
    Position { entity: Ref [entity] } => crate::placement::position, vector;

    SetParent { child: Ref [entity], parent: Option<Ref> [opt_entity] } => crate::scene::set_parent, none;
    SetVisible { entity: Ref [entity], visible: bool [copy] } => crate::scene::set_visible, none;
    Despawn { entity: Ref [entity] } => crate::scene::despawn, none;

    Tag { entity: Ref [entity], label: String [text] } => crate::groups::tag, none;
    Untag { entity: Ref [entity], label: String [text] } => crate::groups::untag, none;
    HasTag { entity: Ref [entity], label: String [text] } => crate::groups::has_tag, bool;
    QueryTagged { label: String [text] } => crate::groups::tagged, entities;

    PointLight { position: [f32; 3] [vec3], color: [f32; 3] [copy], intensity: f32 [copy] } => crate::lighting::point_light, entity;
    SpotLight { position: [f32; 3] [vec3], target: [f32; 3] [vec3], color: [f32; 3] [copy], intensity: f32 [copy] } => crate::lighting::spot_light, entity;
    SetSun { color: [f32; 3] [copy], intensity: f32 [copy] } => crate::lighting::set_sun, none;

    SetBackground { background: crate::environment::Background [owned] } => crate::environment::set_background, none;
    ShowGrid { enabled: bool [copy] } => crate::environment::show_grid, none;
    SetAmbient { color: [f32; 4] [copy] } => crate::environment::set_ambient, none;
    SetBloom { enabled: bool [copy] } => crate::environment::set_bloom, none;
    SetBloomIntensity { intensity: f32 [copy] } => crate::environment::set_bloom_intensity, none;
    SetSsao { enabled: bool [copy] } => crate::environment::set_ssao, none;
    SetSsr { enabled: bool [copy] } => crate::environment::set_ssr, none;
    SetSsgi { enabled: bool [copy] } => crate::environment::set_ssgi, none;
    SetFxaa { enabled: bool [copy] } => crate::environment::set_fxaa, none;
    SetExposure { exposure: f32 [copy] } => crate::environment::set_exposure, none;
    SetColorGrading { saturation: f32 [copy], contrast: f32 [copy], brightness: f32 [copy] } => crate::environment::set_color_grading, none;
    SetTimeOfDay { hour: f32 [copy] } => crate::environment::set_time_of_day, none;
    SetTitle { title: String [text] } => crate::environment::set_title, none;

    EmitFire { position: [f32; 3] [vec3] } => crate::effects::emit_fire, entity;
    EmitSmoke { position: [f32; 3] [vec3] } => crate::effects::emit_smoke, entity;
    EmitBurst { position: [f32; 3] [vec3], color: [f32; 4] [copy], count: u32 [copy] } => crate::effects::emit_burst, entity;

    DrawCube { position: [f32; 3] [vec3], scale: [f32; 3] [vec3], color: [f32; 4] [copy] } => crate::draw::draw_cube, none;
    DrawSphere { position: [f32; 3] [vec3], radius: f32 [copy], color: [f32; 4] [copy] } => crate::draw::draw_sphere, none;
    DrawCylinder { position: [f32; 3] [vec3], scale: [f32; 3] [vec3], color: [f32; 4] [copy] } => crate::draw::draw_cylinder, none;
    DrawCone { position: [f32; 3] [vec3], scale: [f32; 3] [vec3], color: [f32; 4] [copy] } => crate::draw::draw_cone, none;
    DrawTorus { position: [f32; 3] [vec3], scale: [f32; 3] [vec3], color: [f32; 4] [copy] } => crate::draw::draw_torus, none;
    DrawLine { start: [f32; 3] [vec3], end: [f32; 3] [vec3], color: [f32; 4] [copy] } => crate::draw::draw_line, none;
    DrawText3d { text: String [text], position: [f32; 3] [vec3] } => crate::draw::draw_text_3d, none;

    SpawnLabel { text: String [text], position: [f32; 3] [vec3] } => crate::text::spawn_label, entity;
    SpawnText { text: String [text], anchor: crate::text::ScreenAnchor [copy] } => crate::text::spawn_text, entity;
    SetText { entity: Ref [entity], text: String [text] } => crate::text::set_text, none;
    SetTextColor { entity: Ref [entity], color: [f32; 4] [copy] } => crate::text::set_text_color, none;
    SetTextSize { entity: Ref [entity], size: f32 [copy] } => crate::text::set_text_size, none;

    SpawnPanel { anchor: crate::text::ScreenAnchor [copy], width: f32 [copy], height: f32 [copy] } => crate::ui::spawn_panel, entity;
    PanelLabel { panel: Ref [entity], text: String [text] } => crate::ui::panel_label, entity;
    PanelButton { panel: Ref [entity], text: String [text] } => crate::ui::panel_button, entity;
    ButtonClicked { button: Ref [entity] } => crate::ui::button_clicked, bool;
    ButtonHovered { button: Ref [entity] } => crate::ui::button_hovered, bool;
    DespawnPanel { panel: Ref [entity] } => crate::ui::despawn_panel, none;
    PanelRow { panel: Ref [entity], height: f32 [copy] } => crate::ui::panel_row, entity;
    PanelGrid { panel: Ref [entity], columns: usize [copy], row_height: f32 [copy], height: f32 [copy] } => crate::ui::panel_grid, entity;
    PanelScroll { panel: Ref [entity], height: f32 [copy] } => crate::ui::panel_scroll, entity;
    SetScrollOffset { scroll_area: Ref [entity], offset: f32 [copy] } => crate::ui::set_scroll_offset, none;
    SetFocusOrder { entity: Ref [entity], order: i32 [copy] } => crate::ui::set_focus_order, none;
    FocusWidget { entity: Ref [entity] } => crate::ui::focus_widget, none;
    SpawnPanelAt { anchor: crate::text::ScreenAnchor [copy], offset: [f32; 2] [vec2], size: [f32; 2] [vec2], color: [f32; 4] [copy] } => crate::ui::spawn_panel_at, entity;
    PanelText { parent: Ref [entity], text: String [text], rect: [f32; 4] [copy], font_size: f32 [copy], color: [f32; 4] [copy], align: TextAlignment [copy] } => crate::ui::panel_text, entity;
    PanelBox { parent: Ref [entity], offset: [f32; 2] [vec2], size: [f32; 2] [vec2], color: [f32; 4] [copy] } => crate::ui::panel_box, entity;
    PanelButtonAt { parent: Ref [entity], label: String [text], offset: [f32; 2] [vec2], size: [f32; 2] [vec2] } => crate::ui::panel_button_at, entity;
    SetPanelRect { node: Ref [entity], offset: [f32; 2] [vec2], size: [f32; 2] [vec2] } => crate::ui::set_panel_rect, none;
    SetPanelColor { node: Ref [entity], color: [f32; 4] [copy] } => crate::ui::set_panel_color, none;
    SetPanelText { label: Ref [entity], text: String [text] } => crate::ui::set_panel_text, none;
    SetPanelTextColor { label: Ref [entity], color: [f32; 4] [copy] } => crate::ui::set_panel_text_color, none;
    SetPanelSelected { button: Ref [entity], selected: bool [copy], accent: [f32; 4] [copy] } => crate::ui::set_panel_selected, none;
    SetPanelVisible { node: Ref [entity], visible: bool [copy] } => crate::ui::set_panel_visible, none;

    PlayAnimation { entity: Ref [entity], clip: usize [copy] } => crate::scene::play_animation, none;
    PlayAnimationNamed { entity: Ref [entity], name: String [text] } => crate::scene::play_animation_named, bool;
    SetAnimationLooping { entity: Ref [entity], looping: bool [copy] } => crate::scene::set_animation_looping, none;
    SetAnimationSpeed { entity: Ref [entity], speed: f32 [copy] } => crate::scene::set_animation_speed, none;
    BlendToAnimation { entity: Ref [entity], clip: usize [copy], seconds: f32 [copy] } => crate::scene::blend_to_animation, none;
    PauseAnimation { entity: Ref [entity] } => crate::scene::pause_animation, none;
    ResumeAnimation { entity: Ref [entity] } => crate::scene::resume_animation, none;
    StopAnimation { entity: Ref [entity] } => crate::scene::stop_animation, none;
    AnimationClips { entity: Ref [entity] } => crate::scene::animation_clips, strings;
    AddAnimationEvent { entity: Ref [entity], clip_index: usize [copy], time: f32 [copy], name: String [text] } => crate::scene::add_animation_event, bool;
    AddAnimationEventNamed { entity: Ref [entity], clip_name: String [text], time: f32 [copy], name: String [text] } => crate::scene::add_animation_event_named, bool;
    SetAnimationLayerWeight { entity: Ref [entity], layer_index: usize [copy], weight: f32 [copy] } => crate::scene::set_animation_layer_weight, none;
    ClearAnimationLayers { entity: Ref [entity] } => crate::scene::clear_animation_layers, none;
    AimAt { bone: Ref [entity], target: [f32; 3] [vec3], forward: [f32; 3] [vec3] } => crate::animate::aim_at, none;

    OrbitCamera { focus: [f32; 3] [vec3], radius: f32 [copy] } => crate::camera::orbit_camera, entity;
    FlyCamera { position: [f32; 3] [vec3] } => crate::camera::fly_camera, entity;
    FixedCamera { eye: [f32; 3] [vec3], target: [f32; 3] [vec3] } => crate::camera::fixed_camera, entity;
    LookAt { eye: [f32; 3] [vec3], target: [f32; 3] [vec3] } => crate::camera::look_at, none;
    SetOrbitFocus { focus: [f32; 3] [vec3] } => crate::camera::set_orbit_focus, none;
    SetOrbitView { focus: [f32; 3] [vec3], radius: f32 [copy], yaw: f32 [copy], pitch: f32 [copy] } => crate::camera::set_orbit_view, none;
    SetOrbitZoom { enabled: bool [copy] } => crate::camera::set_orbit_zoom, none;
    SetFieldOfView { degrees: f32 [copy] } => crate::camera::set_field_of_view, none;
    SetOrthographic { half_height: f32 [copy] } => crate::camera::set_orthographic, none;
    SetPerspective { degrees: f32 [copy] } => crate::camera::set_perspective, none;
    CameraPosition {} => crate::camera::camera_position, vector;
    CameraForward {} => crate::camera::camera_forward, vector;
    #[cfg(feature = "physics")]
    FirstPerson { position: [f32; 3] [vec3] } => crate::camera::first_person, entity;

    DeltaTime {} => crate::input::delta_time, float;
    ElapsedSeconds {} => crate::input::elapsed_seconds, float;
    KeyDown { key: String [text] } => key_down_command, bool;
    KeyPressed { key: String [text] } => key_pressed_command, bool;
    MouseDown { button: u8 [copy] } => mouse_down_command, bool;
    MouseClicked { button: u8 [copy] } => mouse_clicked_command, bool;
    Wasd {} => crate::input::wasd, vector;
    PointerOverUi {} => crate::input::pointer_over_ui, bool;
    MouseScroll {} => crate::input::mouse_scroll, float;

    #[cfg(feature = "physics")]
    Push { entity: Ref [entity], impulse: [f32; 3] [vec3] } => crate::physics::push, none;
    #[cfg(feature = "physics")]
    SetVelocity { entity: Ref [entity], velocity: [f32; 3] [vec3] } => crate::physics::set_velocity, none;
    #[cfg(feature = "physics")]
    ApplyForce { entity: Ref [entity], force: [f32; 3] [vec3] } => crate::physics::apply_force, none;
    #[cfg(feature = "physics")]
    ApplyTorque { entity: Ref [entity], torque: [f32; 3] [vec3] } => crate::physics::apply_torque, none;
    #[cfg(feature = "physics")]
    SetAngularVelocity { entity: Ref [entity], velocity: [f32; 3] [vec3] } => crate::physics::set_angular_velocity, none;
    #[cfg(feature = "physics")]
    Velocity { entity: Ref [entity] } => crate::physics::velocity, opt_vector;
    #[cfg(feature = "physics")]
    AngularVelocity { entity: Ref [entity] } => crate::physics::angular_velocity, opt_vector;
    #[cfg(feature = "physics")]
    MakeSensor { entity: Ref [entity] } => crate::physics::make_sensor, none;
    #[cfg(feature = "physics")]
    OverlapSphere { center: [f32; 3] [vec3], radius: f32 [copy] } => crate::physics::overlap_sphere, entities;
    #[cfg(feature = "physics")]
    SetCollisionGroups { entity: Ref [entity], membership: u32 [copy], filter: u32 [copy] } => crate::physics::set_collision_groups, none;
    #[cfg(feature = "physics")]
    SetFriction { entity: Ref [entity], friction: f32 [copy] } => crate::physics::set_friction, none;
    #[cfg(feature = "physics")]
    SetRestitution { entity: Ref [entity], restitution: f32 [copy] } => crate::physics::set_restitution, none;
    #[cfg(feature = "physics")]
    SetLinearDamping { entity: Ref [entity], damping: f32 [copy] } => crate::physics::set_linear_damping, none;
    #[cfg(feature = "physics")]
    SetAngularDamping { entity: Ref [entity], damping: f32 [copy] } => crate::physics::set_angular_damping, none;
    #[cfg(feature = "physics")]
    SetMass { entity: Ref [entity], mass: f32 [copy] } => crate::physics::set_mass, none;
    #[cfg(feature = "physics")]
    SetGravityScale { entity: Ref [entity], scale: f32 [copy] } => crate::physics::set_gravity_scale, none;

    #[cfg(feature = "navmesh")]
    BakeNavmesh {} => crate::navigation::bake_navmesh, none;
    #[cfg(feature = "navmesh")]
    SpawnWalker { position: [f32; 3] [vec3] } => crate::navigation::spawn_walker, entity;
    #[cfg(feature = "navmesh")]
    WalkTo { agent: Ref [entity], destination: [f32; 3] [vec3] } => crate::navigation::walk_to, none;
    #[cfg(feature = "navmesh")]
    SetWalkSpeed { agent: Ref [entity], speed: f32 [copy] } => crate::navigation::set_walk_speed, none;
    #[cfg(feature = "navmesh")]
    StopWalking { agent: Ref [entity] } => crate::navigation::stop_walking, none;

    #[cfg(feature = "picking")]
    ClickedEntity {} => crate::picking::clicked_entity, opt_entity;
    #[cfg(feature = "picking")]
    EntityUnderCursor {} => crate::picking::entity_under_cursor, opt_entity;
    #[cfg(feature = "picking")]
    CursorOnGround {} => crate::picking::cursor_on_ground, opt_vector;
    #[cfg(feature = "picking")]
    SpawnWorldPanel { position: [f32; 3] [vec3], width: f32 [copy], height: f32 [copy], color: [f32; 4] [copy] } => crate::world_ui::spawn_world_panel, entity;
    #[cfg(feature = "picking")]
    WorldPanelButton { panel: Ref [entity], x: f32 [copy], y: f32 [copy], width: f32 [copy], height: f32 [copy], color: [f32; 4] [copy] } => crate::world_ui::world_panel_button, entity;
    #[cfg(feature = "picking")]
    WorldPanelLabel { panel: Ref [entity], text: String [text], x: f32 [copy], y: f32 [copy] } => crate::world_ui::world_panel_label, entity;
    #[cfg(feature = "picking")]
    WorldButtonClicked { button: Ref [entity] } => crate::world_ui::world_button_clicked, bool;

    #[cfg(feature = "audio")]
    PauseSound { entity: Ref [entity] } => crate::audio::pause_sound, none;
    #[cfg(feature = "audio")]
    ResumeSound { entity: Ref [entity] } => crate::audio::resume_sound, none;
    #[cfg(feature = "audio")]
    FadeVolume { entity: Ref [entity], volume: f32 [copy], seconds: f32 [copy] } => crate::audio::fade_volume, none;
    #[cfg(feature = "audio")]
    Crossfade { fade_out: Ref [entity], fade_in: Ref [entity], volume: f32 [copy], seconds: f32 [copy] } => crate::audio::crossfade, none;
    #[cfg(feature = "audio")]
    SetBusVolume { bus: nightshade::prelude::AudioBus [copy], decibels: f32 [copy], fade_seconds: f32 [copy] } => crate::audio::set_bus_volume, none;
    #[cfg(feature = "audio")]
    DuckVoice { amount: f32 [copy], fade_seconds: f32 [copy] } => crate::audio::duck_voice, none;

    DirectionalLight { direction: [f32; 3] [vec3], color: [f32; 3] [copy], intensity: f32 [copy] } => crate::lighting::directional_light, entity;
    AreaLight { position: [f32; 3] [vec3], target: [f32; 3] [vec3], width: f32 [copy], height: f32 [copy], color: [f32; 3] [copy], intensity: f32 [copy] } => crate::lighting::area_light, entity;
    SetLightShadows { light: Ref [entity], enabled: bool [copy] } => crate::lighting::set_light_shadows, none;

    EmitSparks { position: [f32; 3] [vec3] } => crate::effects::emit_sparks, entity;
    EmitFirework { position: [f32; 3] [vec3], velocity: [f32; 3] [vec3] } => crate::effects::emit_firework, entity;
    EmitParticles { position: [f32; 3] [vec3], rate: f32 [copy], lifetime: f32 [copy], size: f32 [copy], gravity: [f32; 3] [vec3] } => crate::effects::emit_particles, entity;

    SetAlphaBlend { entity: Ref [entity], enabled: bool [copy] } => crate::appearance::set_alpha_blend, none;
    SetAlphaCutoff { entity: Ref [entity], cutoff: f32 [copy] } => crate::appearance::set_alpha_cutoff, none;
    SetDoubleSided { entity: Ref [entity], double_sided: bool [copy] } => crate::appearance::set_double_sided, none;
    SetIor { entity: Ref [entity], ior: f32 [copy] } => crate::appearance::set_ior, none;
    SetTransmission { entity: Ref [entity], factor: f32 [copy] } => crate::appearance::set_transmission, none;
    SetClearcoat { entity: Ref [entity], factor: f32 [copy], roughness: f32 [copy] } => crate::appearance::set_clearcoat, none;
    SetAnisotropy { entity: Ref [entity], strength: f32 [copy], rotation: f32 [copy] } => crate::appearance::set_anisotropy, none;
    SetUvTransform { entity: Ref [entity], offset: [f32; 2] [copy], scale: [f32; 2] [copy], rotation: f32 [copy] } => crate::appearance::set_uv_transform, none;
    SetSheen { entity: Ref [entity], color: [f32; 3] [copy], roughness: f32 [copy] } => crate::appearance::set_sheen, none;
    SetIridescence { entity: Ref [entity], factor: f32 [copy], ior: f32 [copy] } => crate::appearance::set_iridescence, none;
    SetSpecular { entity: Ref [entity], factor: f32 [copy], color: [f32; 3] [copy] } => crate::appearance::set_specular, none;
    SetNormalScale { entity: Ref [entity], scale: f32 [copy] } => crate::appearance::set_normal_scale, none;
    SetOcclusionStrength { entity: Ref [entity], strength: f32 [copy] } => crate::appearance::set_occlusion_strength, none;
    SetEmissiveStrength { entity: Ref [entity], strength: f32 [copy] } => crate::appearance::set_emissive_strength, none;
    SetThickness { entity: Ref [entity], thickness: f32 [copy] } => crate::appearance::set_thickness, none;

    SetTextOutline { entity: Ref [entity], width: f32 [copy], color: [f32; 4] [copy] } => crate::text::set_text_outline, none;

    SetMorphWeight { entity: Ref [entity], index: u32 [copy], weight: f32 [copy] } => crate::morph::set_morph_weight, none;

    SetWindowTitle { title: String [text] } => crate::window::set_window_title, none;
    LockCursor { locked: bool [copy] } => crate::window::lock_cursor, none;
    RequestExit {} => crate::window::request_exit, none;

    SetRenderLayer { entity: Ref [entity], layer: u32 [copy] } => crate::render::set_render_layer, none;
    SetCameraLayers { camera: Ref [entity], mask: u32 [copy] } => crate::render::set_camera_layers, none;

    ThirdPersonCamera { target: Ref [entity], distance: f32 [copy] } => crate::camera::third_person_camera, entity;

    SpawnCloth { position: [f32; 3] [vec3], width: f32 [copy], height: f32 [copy], columns: u32 [copy], rows: u32 [copy] } => crate::cloth::spawn_cloth, entity;
    ResetCloth { entity: Ref [entity] } => crate::cloth::reset_cloth, none;
    SetWind { direction: [f32; 3] [vec3], strength: f32 [copy] } => crate::cloth::set_wind, none;

    PauseCutscene {} => crate::cutscene::pause_cutscene, none;
    ResumeCutscene {} => crate::cutscene::resume_cutscene, none;
    StopCutscene {} => crate::cutscene::stop_cutscene, none;
    SeekCutscene { seconds: f32 [copy] } => crate::cutscene::seek_cutscene, none;
    SetCutsceneCamera { camera: Ref [entity] } => crate::cutscene::set_cutscene_camera, none;
    BindCutsceneActor { name: String [text], entity: Ref [entity] } => crate::cutscene::bind_cutscene_actor, none;

    #[cfg(feature = "physics")]
    SpawnCylinderBody { position: [f32; 3] [vec3], half_height: f32 [copy], radius: f32 [copy], mass: f32 [copy], color: [f32; 4] [copy] } => crate::physics::spawn_cylinder_body, entity;
    #[cfg(feature = "physics")]
    SpawnCapsuleBody { position: [f32; 3] [vec3], half_height: f32 [copy], radius: f32 [copy], mass: f32 [copy], color: [f32; 4] [copy] } => crate::scene::spawn_capsule_body, entity;
    #[cfg(feature = "physics")]
    SetControllerSpeed { entity: Ref [entity], speed: f32 [copy] } => crate::character::set_controller_speed, none;
    #[cfg(feature = "physics")]
    SetControllerJump { entity: Ref [entity], impulse: f32 [copy] } => crate::character::set_controller_jump, none;
    #[cfg(feature = "physics")]
    IsGrounded { entity: Ref [entity] } => crate::character::is_grounded, bool;

    #[cfg(feature = "terrain")]
    EnableTerrain { seed: u32 [copy] } => crate::terrain::enable_terrain, none;
    #[cfg(feature = "terrain")]
    DisableTerrain {} => crate::terrain::disable_terrain, none;
    #[cfg(feature = "terrain")]
    SetTerrainHeightRange { min: f32 [copy], max: f32 [copy] } => crate::terrain::set_terrain_height_range, none;
    #[cfg(feature = "terrain")]
    SetTerrainSnowHeight { height: f32 [copy] } => crate::terrain::set_terrain_snow_height, none;
    #[cfg(feature = "grass")]
    EnableGrass {} => crate::terrain::enable_grass, none;
    #[cfg(feature = "grass")]
    DisableGrass {} => crate::terrain::disable_grass, none;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn command_schema_covers_the_surface() {
        let schema = command_schema();
        assert!(schema.get("oneOf").is_some());
        let text = enum2schema::serde_json::to_string(&schema).unwrap();
        for variant in [
            "SpawnCube",
            "SpawnObject",
            "SetColor",
            "Rotate",
            "QueryTagged",
        ] {
            assert!(text.contains(variant), "schema missing {variant}");
        }
    }

    #[test]
    fn reply_schema_is_generated() {
        assert!(command_reply_schema().get("oneOf").is_some());
    }

    #[test]
    fn manifest_covers_the_surface() {
        let manifest = command_manifest();
        assert!(!manifest.is_empty());
        let names: Vec<&str> = manifest.iter().map(|spec| spec.name).collect();
        for variant in [
            "SpawnCube",
            "SpawnObject",
            "SetColor",
            "Rotate",
            "QueryTagged",
        ] {
            assert!(names.contains(&variant), "manifest missing {variant}");
        }
        let replies = [
            "none",
            "entity",
            "opt_entity",
            "bool",
            "float",
            "vector",
            "opt_vector",
            "entities",
            "strings",
        ];
        for spec in &manifest {
            assert!(
                replies.contains(&spec.reply),
                "unknown reply {}",
                spec.reply
            );
        }
    }

    #[test]
    fn entity_reference_serializes_as_its_schema_claims() {
        let entity = Entity {
            id: 3,
            generation: 1,
        };
        let value = enum2schema::serde_json::to_value(Ref::Entity(entity)).unwrap();
        let inner = value
            .get("Entity")
            .and_then(|tagged| tagged.as_object())
            .expect("Ref::Entity serializes as an externally tagged object");
        assert!(inner.contains_key("id"));
        assert!(inner.contains_key("generation"));
        assert_eq!(inner.len(), 2);
    }
}