konjure_lang/

spatial.rs

//! Validated scene adaptation and fixed-step rigid-body simulation.
//!
//! Language execution, spatial validation, and physics form one transaction. Media
//! components stay in the ECS for a host to resolve; this module performs no I/O.
use crate::{Diagnostic, Limits, Machine, Snapshot, Span, Value, compile};
use konjure_sdk::{self as sdk, EntityId, Frame, Geometry, Mesh, SceneDocument};
use rapier3d::{
    glamx::{DQuat, EulerRot},
    prelude::*,
};
use serde::Serialize;
use std::collections::{BTreeMap, BTreeSet};

/// Fixed simulation interval in seconds.
pub const FIXED_DT: f64 = 1.0 / 60.0;
/// Maximum fixed ticks accepted by one synchronous host call.
pub const MAX_STEP_COUNT: u32 = 600;
/// Maximum points in a PointCloud component.
pub const MAX_CLOUD_POINTS: usize = 256;
const MAX_MESH_VERTICES: usize = 16_384;
const MAX_MESH_INDICES: usize = 98_304;
const MAX_SCENE_VERTICES: usize = 262_144;
const GEOMETRIES: &[&str] = &[
    "Sphere",
    "Box",
    "Cylinder",
    "Quad",
    "Line",
    "Ray",
    "Mesh",
    "PointCloud",
];

/// An active collision pair from the latest committed physics tick.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize)]
pub struct Contact {
    /// First stable language entity ID, always smaller than `entity_b`.
    pub entity_a: u64,
    /// Second stable language entity ID.
    pub entity_b: u64,
}

/// Renderer-neutral scene state. SDK IDs are `entity_N` for language entity N.
#[derive(Clone, Debug, Serialize)]
pub struct RenderOutput {
    /// Semantic controls from the same committed state as the geometry below.
    pub ui: konjure_sdk::presentation::UiDocument,
    /// Validated scene graph; custom geometry references adapter-owned meshes below.
    pub document: SceneDocument,
    /// Owned local meshes keyed by stable SDK entity ID.
    pub meshes: BTreeMap<EntityId, Mesh>,
    /// Evaluated transforms at the committed simulation time.
    pub frame: Frame,
    /// Active collision pairs, sorted by language entity ID.
    pub contacts: Vec<Contact>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum BodyKind {
    Dynamic,
    Fixed,
    Kinematic,
}
#[derive(Clone, Debug, PartialEq)]
enum CollisionShape {
    Sphere(f32),
    Box(Vector),
}
#[derive(Clone, Debug, PartialEq)]
struct BodyConfig {
    kind: BodyKind,
    shape: CollisionShape,
    mass: f32,
    restitution: f32,
    friction: f32,
}
#[derive(Clone)]
struct Binding {
    handle: RigidBodyHandle,
    config: BodyConfig,
    transform: Value,
    rigid_body: Value,
}

/// A reusable language machine coupled to a persistent deterministic Rapier world.
pub struct SpatialRuntime {
    machine: Machine,
    world: PhysicsWorld,
    bindings: BTreeMap<u64, Binding>,
    contacts: Vec<Contact>,
}

impl Clone for SpatialRuntime {
    fn clone(&self) -> Self {
        // Rapier's pipeline and CCD solver contain scratch buffers. Persistent
        // broad/narrow phase, islands, bodies, and joints must survive rollback.
        Self {
            machine: self.machine.clone(),
            world: PhysicsWorld {
                gravity: self.world.gravity,
                integration_parameters: self.world.integration_parameters,
                physics_pipeline: PhysicsPipeline::new(),
                islands: self.world.islands.clone(),
                broad_phase: self.world.broad_phase.clone(),
                narrow_phase: self.world.narrow_phase.clone(),
                bodies: self.world.bodies.clone(),
                colliders: self.world.colliders.clone(),
                impulse_joints: self.world.impulse_joints.clone(),
                multibody_joints: self.world.multibody_joints.clone(),
                ccd_solver: CCDSolver::new(),
            },
            bindings: self.bindings.clone(),
            contacts: self.contacts.clone(),
        }
    }
}

fn accept_action_result(value: &Value) -> Result<(), Diagnostic> {
    if let Value::Enum(value) = value
        && value.case == "Err"
        && matches!(&value.ty,crate::Type::Applied{name,..}if name=="Res")
    {
        let cause = value
            .payload
            .first()
            .map(ToString::to_string)
            .unwrap_or_else(|| "Unknown".into());
        let code = match cause.as_str() {
            "Overflow" => "numeric_overflow",
            "DivisionByZero" => "division_by_zero",
            "InexactConversion" => "inexact_conversion",
            "Bounds" => "index_out_of_bounds",
            "InvalidUtf8" => "invalid_utf8",
            "InvalidShape" | "ShapeMismatch" => "shape_mismatch",
            _ => "data_error",
        };
        return Err(Diagnostic::new(
            code,
            format!("action returned Err({cause})"),
            value
                .origin
                .clone()
                .unwrap_or_else(|| Span::new("main", 0, 0)),
        ));
    }
    Ok(())
}
impl SpatialRuntime {
    /// Compiles, initializes, and validates a program without advancing physics.
    /// Imports use only the explicitly supplied module map.
    pub fn new(source: &str, modules: &BTreeMap<String, String>) -> Result<Self, Vec<Diagnostic>> {
        let program = compile(source, modules)?;
        let machine = Machine::new(program, Limits::default()).map_err(|error| vec![error])?;
        let mut runtime = Self {
            machine,
            world: PhysicsWorld::default(),
            bindings: BTreeMap::new(),
            contacts: Vec::new(),
        };
        runtime.world.integration_parameters.dt = FIXED_DT as f32;
        runtime.normalize().map_err(|error| vec![error])?;
        runtime.render().map_err(|error| vec![error])?;
        runtime.reconcile(false).map_err(|error| vec![error])?;
        Ok(runtime)
    }

    /// Returns the language fixed tick and terminal lifecycle state without
    /// materializing a scene or snapshot.
    #[must_use]
    pub const fn execution_state(&self) -> (u64, bool) {
        self.machine.execution_state()
    }

    /// Advances up to [`MAX_STEP_COUNT`] fixed ticks. A rejected batch preserves
    /// all previously committed language and physics state, including impulses.
    pub fn step(&mut self, count: u32) -> Result<Snapshot, Diagnostic> {
        if count > MAX_STEP_COUNT {
            return Err(error(
                &Span::default(),
                "step_limit",
                format!("step count exceeds {MAX_STEP_COUNT}"),
            ));
        }
        if count == 0 {
            return Ok(self.snapshot());
        }
        let mut candidate = self.clone();
        for _ in 0..count {
            candidate.machine.tick(FIXED_DT)?;
            candidate.normalize()?;
            candidate.render()?;
            candidate.reconcile(true)?;
            candidate.world.step();
            candidate.write_back()?;
            candidate.render()?;
            candidate.reconcile(false)?;
        }
        *self = candidate;
        Ok(self.snapshot())
    }

    /// Runs system teardown and validates its spatial edits as one transaction.
    /// Repeated calls return the finished snapshot without repeating callbacks.
    ///
    /// # Errors
    /// A failed callback or invalid spatial edit preserves the running world.
    pub fn finish(&mut self) -> Result<Snapshot, Diagnostic> {
        if self.snapshot().finished {
            return Ok(self.snapshot());
        }
        let mut candidate = self.clone();
        candidate.machine.finish()?;
        candidate.normalize()?;
        candidate.render()?;
        candidate.reconcile(false)?;
        *self = candidate;
        Ok(self.snapshot())
    }

    /// Invokes an exported function, validating all resulting spatial edits before
    /// committing. Impulses are applied only when a subsequent tick succeeds.
    pub fn invoke(&mut self, name: &str, arguments: &[Value]) -> Result<Value, Diagnostic> {
        let mut candidate = self.clone();
        let result = candidate.machine.invoke(name, arguments.to_vec())?;
        accept_action_result(&result)?;
        candidate.normalize()?;
        candidate.render()?;
        candidate.reconcile(false)?;
        *self = candidate;
        Ok(result)
    }

    /// Invokes a function stored in an exact component field. Resulting spatial
    /// edits and physics reconciliation join the language transaction.
    pub fn invoke_component(
        &mut self,
        id: u64,
        component: &str,
        field: &str,
        arguments: &[Value],
    ) -> Result<Value, Diagnostic> {
        let mut candidate = self.clone();
        let result =
            candidate
                .machine
                .invoke_component(id, component, field, arguments.to_vec())?;
        accept_action_result(&result)?;
        candidate.normalize()?;
        candidate.render()?;
        candidate.reconcile(false)?;
        *self = candidate;
        Ok(result)
    }

    /// Invokes an unambiguous zero-argument or typed component method on one
    /// entity, with the same spatial transaction as a named function call.
    pub fn invoke_entity(
        &mut self,
        id: u64,
        method: &str,
        arguments: &[Value],
    ) -> Result<Value, Diagnostic> {
        let mut candidate = self.clone();
        let result = candidate
            .machine
            .invoke_entity(id, method, arguments.to_vec())?;
        accept_action_result(&result)?;
        candidate.normalize()?;
        candidate.render()?;
        candidate.reconcile(false)?;
        *self = candidate;
        Ok(result)
    }

    /// Returns the committed ECS, globals, logs, and simulation clock.
    pub fn snapshot(&self) -> Snapshot {
        self.machine.snapshot()
    }

    /// Validates and adapts every geometry component to an SDK scene and mesh.
    pub fn render(&self) -> Result<RenderOutput, Diagnostic> {
        let snapshot = self.snapshot();
        let ui = crate::ui::document(&snapshot, 0)
            .map_err(|problem| error(&Span::default(), "invalid_ui", problem.to_string()))?;
        let mut document = SceneDocument {
            format: "konjure.scene".into(),
            version: sdk::FORMAT_VERSION,
            id: sdk::SceneId("language_scene".into()),
            title: "Konjure language scene".into(),
            entities: Vec::new(),
            conversation: Vec::new(),
        };
        let mut meshes = BTreeMap::new();
        let mut vertex_count = 0;
        let parent_targets: BTreeSet<u64> = snapshot
            .entities
            .iter()
            .filter_map(|entity| entity.components.get("Parent"))
            .filter_map(|value| field(value, "entity", &Span::default()).ok())
            .filter_map(|value| match value {
                Value::Entity(id) => Some(*id),
                _ => None,
            })
            .collect();
        for entity in &snapshot.entities {
            let span = &entity.source;
            // Presentation values must remain valid even on resource-only entities.
            let transform = entity
                .components
                .get("Transform")
                .map(|value| transform(value, span))
                .transpose()?
                .unwrap_or_default();
            let (color, material) = entity
                .components
                .get("Material")
                .map(|value| material(value, span))
                .transpose()?
                .unwrap_or((
                    sdk::Color {
                        r: 111,
                        g: 227,
                        b: 255,
                        a: 255,
                    },
                    sdk::Material {
                        roughness: 0.6,
                        emissive: 0.0,
                    },
                ));
            let geometry_value = geometry_component(&entity.components, span)?;
            if geometry_value.is_none()
                && !entity.components.contains_key("Parent")
                && !parent_targets.contains(&entity.id)
            {
                continue;
            }
            let id = EntityId(format!("entity_{}", entity.id));
            let (geometry, mesh) = match geometry_value {
                Some((name, value)) => geometry(name, value, &id, span)?,
                None => (
                    Geometry::Group,
                    Mesh {
                        positions: Vec::new(),
                        normals: Vec::new(),
                        indices: Vec::new(),
                    },
                ),
            };
            if !mesh.positions.is_empty() {
                vertex_count += mesh.positions.len();
                if vertex_count > MAX_SCENE_VERTICES {
                    return Err(error(
                        span,
                        "mesh_limit",
                        "scene exceeds its generated vertex budget",
                    ));
                }
                meshes.insert(id.clone(), mesh);
            }
            let parent = entity
                .components
                .get("Parent")
                .map(|value| {
                    let Value::Entity(parent) = field(value, "entity", span)? else {
                        return Err(error(
                            span,
                            "invalid_parent",
                            "Parent.entity must be an Entity",
                        ));
                    };
                    if !snapshot
                        .entities
                        .iter()
                        .any(|candidate| candidate.id == *parent)
                    {
                        return Err(error(
                            span,
                            "unknown_parent",
                            "Parent.entity must reference an existing entity",
                        ));
                    }
                    Ok(EntityId(format!("entity_{parent}")))
                })
                .transpose()?;
            document.entities.push(sdk::Entity {
                id,
                parent,
                transform,
                geometry,
                color,
                material,
                animations: Vec::new(),
                actions: BTreeMap::new(),
            });
        }
        sdk::validate(&document).map_err(|diagnostic| {
            error(&Span::default(), "invalid_scene", diagnostic.to_string())
        })?;
        // The SDK evaluates transforms; custom meshes are resolved by this adapter.
        let mut sampling_document = document.clone();
        for entity in &mut sampling_document.entities {
            entity.geometry = Geometry::Group;
        }
        let evaluator = sdk::Runtime::new(sampling_document).map_err(|diagnostic| {
            error(&Span::default(), "invalid_scene", diagnostic.to_string())
        })?;
        let mut frame = evaluator.sample(snapshot.time).map_err(|diagnostic| {
            error(&Span::default(), "invalid_scene", diagnostic.to_string())
        })?;
        for draw in &mut frame.draws {
            draw.mesh_entity = Some(draw.entity.clone());
        }
        Ok(RenderOutput {
            ui,
            document,
            meshes,
            frame,
            contacts: self.contacts.clone(),
        })
    }

    fn normalize(&mut self) -> Result<(), Diagnostic> {
        let mut updates = Vec::new();
        for entity in self.snapshot().entities {
            if geometry_component(&entity.components, &entity.source)?.is_some() {
                if !entity.components.contains_key("Transform") {
                    updates.push((entity.id, default_transform()));
                }
                if !entity.components.contains_key("Material") {
                    updates.push((entity.id, default_material()));
                }
            }
        }
        self.machine.upsert_components_for_adapter(&updates)
    }

    fn reconcile(&mut self, apply_forces: bool) -> Result<(), Diagnostic> {
        let snapshot = self.snapshot();
        let present: BTreeSet<_> = snapshot
            .entities
            .iter()
            .filter(|entity| entity.components.contains_key("RigidBody"))
            .map(|entity| entity.id)
            .collect();
        let removed: Vec<_> = self
            .bindings
            .keys()
            .filter(|id| !present.contains(id))
            .copied()
            .collect();
        for id in removed {
            if let Some(binding) = self.bindings.remove(&id) {
                self.world.remove_body(binding.handle);
            }
        }
        let mut spatial_change = false;
        for entity in &snapshot.entities {
            let span = &entity.source;
            let force = entity
                .components
                .get("Force")
                .map(|value| vector(field(value, "value", span)?, span))
                .transpose()?;
            let impulse = entity
                .components
                .get("Impulse")
                .map(|value| vector(field(value, "value", span)?, span))
                .transpose()?;
            let Some(body_value) = entity.components.get("RigidBody") else {
                if force.is_some() || impulse.is_some() {
                    return Err(error(
                        span,
                        "missing_body",
                        "Force and Impulse require a dynamic RigidBody",
                    ));
                }
                continue;
            };
            let transform_value = entity.components.get("Transform").ok_or_else(|| {
                error(
                    span,
                    "missing_shape",
                    "RigidBody requires a Sphere or Box geometry",
                )
            })?;
            let transform = transform(transform_value, span)?;
            let config = body_config(body_value, &entity.components, transform.scale, span)?;
            if config.kind != BodyKind::Dynamic && (force.is_some() || impulse.is_some()) {
                return Err(error(
                    span,
                    "invalid_force",
                    "Force and Impulse require a dynamic RigidBody",
                ));
            }
            let velocity = vector(field(body_value, "velocity", span)?, span)?;
            let angular_velocity = vector(field(body_value, "angular_velocity", span)?, span)?;
            if config.kind == BodyKind::Fixed
                && (velocity != sdk::Vec3::ZERO || angular_velocity != sdk::Vec3::ZERO)
            {
                return Err(error(
                    span,
                    "fixed_velocity",
                    "a fixed RigidBody cannot have nonzero velocity",
                ));
            }
            let mut old = self.bindings.get(&entity.id).cloned();
            if let Some(binding) = &old {
                if binding.config.kind == BodyKind::Dynamic
                    && (binding.transform.field("position") != transform_value.field("position")
                        || binding.transform.field("rotation") != transform_value.field("rotation"))
                {
                    return Err(error(
                        span,
                        "dynamic_pose_edit",
                        "dynamic body position and rotation are owned by physics; use velocity, Force, or Impulse",
                    ));
                }
                if binding.config != config {
                    self.world.remove_body(binding.handle);
                    old = None;
                }
            }
            let pose = pose(transform);
            let handle = if let Some(binding) = old {
                let body =
                    self.world.bodies.get_mut(binding.handle).ok_or_else(|| {
                        error(span, "physics_state", "missing persistent rigid body")
                    })?;
                if binding.transform != *transform_value {
                    body.set_position(pose, true);
                    spatial_change = true;
                }
                if binding.rigid_body.field("velocity") != body_value.field("velocity") {
                    body.set_linvel(to_vector(velocity), true);
                }
                if binding.rigid_body.field("angular_velocity")
                    != body_value.field("angular_velocity")
                {
                    body.set_angvel(to_vector(angular_velocity), true);
                }
                binding.handle
            } else {
                let builder = match config.kind {
                    BodyKind::Dynamic => RigidBodyBuilder::dynamic(),
                    BodyKind::Fixed => RigidBodyBuilder::fixed(),
                    BodyKind::Kinematic => RigidBodyBuilder::kinematic_velocity_based(),
                };
                let collider = match config.shape {
                    CollisionShape::Sphere(radius) => ColliderBuilder::ball(radius),
                    CollisionShape::Box(size) => {
                        ColliderBuilder::cuboid(size.x / 2.0, size.y / 2.0, size.z / 2.0)
                    }
                };
                let (handle, _) = self.world.insert(
                    builder
                        .pose(pose)
                        .linvel(to_vector(velocity))
                        .angvel(to_vector(angular_velocity))
                        .ccd_enabled(true)
                        .user_data(u128::from(entity.id)),
                    collider
                        .mass(config.mass)
                        .restitution(config.restitution)
                        .friction(config.friction)
                        .user_data(u128::from(entity.id)),
                );
                spatial_change = true;
                handle
            };
            if apply_forces {
                let body = self.world.bodies.get_mut(handle).ok_or_else(|| {
                    error(
                        span,
                        "physics_state",
                        "missing rigid body during force application",
                    )
                })?;
                body.reset_forces(false);
                if let Some(force) = force {
                    body.add_force(to_vector(force), true);
                }
                if let Some(impulse) = impulse {
                    body.apply_impulse(to_vector(impulse), true);
                }
            }
            self.bindings.insert(
                entity.id,
                Binding {
                    handle,
                    config,
                    transform: transform_value.clone(),
                    rigid_body: body_value.clone(),
                },
            );
        }
        // Contacts describe a completed tick, and are invalidated by pose/shape edits.
        if spatial_change {
            self.contacts.clear();
        }
        self.contacts
            .retain(|pair| present.contains(&pair.entity_a) && present.contains(&pair.entity_b));
        Ok(())
    }

    fn write_back(&mut self) -> Result<(), Diagnostic> {
        let mut updates = Vec::new();
        let snapshot = self.snapshot();
        for entity in &snapshot.entities {
            let Some(binding) = self.bindings.get_mut(&entity.id) else {
                continue;
            };
            let body = self.world.bodies.get(binding.handle).ok_or_else(|| {
                error(
                    &entity.source,
                    "physics_state",
                    "missing simulated rigid body",
                )
            })?;
            let position = body.translation();
            let (x, y, z) = body.rotation().to_euler(EulerRot::XYZ);
            let mut transform_value = binding.transform.clone();
            replace_field(
                &mut transform_value,
                "position",
                vector_value(from_vector(position)),
                &entity.source,
            )?;
            replace_field(
                &mut transform_value,
                "rotation",
                vector_value(sdk::Vec3 {
                    x: f64::from(x),
                    y: f64::from(y),
                    z: f64::from(z),
                }),
                &entity.source,
            )?;
            let mut rigid_body = binding.rigid_body.clone();
            replace_field(
                &mut rigid_body,
                "velocity",
                vector_value(from_vector(body.linvel())),
                &entity.source,
            )?;
            replace_field(
                &mut rigid_body,
                "angular_velocity",
                vector_value(from_vector(body.angvel())),
                &entity.source,
            )?;
            binding.transform = transform_value.clone();
            binding.rigid_body = rigid_body.clone();
            updates.push((entity.id, transform_value));
            updates.push((entity.id, rigid_body));
            if entity.components.contains_key("Impulse") {
                updates.push((
                    entity.id,
                    record("Impulse", [("value", vector_value(sdk::Vec3::ZERO))]),
                ));
            }
        }
        self.machine.patch_components_for_adapter(&updates)?;
        let mut pairs = BTreeSet::new();
        for contact in self
            .world
            .contact_pairs()
            .filter(|contact| contact.has_any_active_contact())
        {
            let Some(a) = self.world.colliders.get(contact.collider1) else {
                continue;
            };
            let Some(b) = self.world.colliders.get(contact.collider2) else {
                continue;
            };
            let a = u64::try_from(a.user_data).map_err(|_| {
                error(
                    &Span::default(),
                    "physics_state",
                    "invalid contact entity ID",
                )
            })?;
            let b = u64::try_from(b.user_data).map_err(|_| {
                error(
                    &Span::default(),
                    "physics_state",
                    "invalid contact entity ID",
                )
            })?;
            pairs.insert(Contact {
                entity_a: a.min(b),
                entity_b: a.max(b),
            });
        }
        self.contacts = pairs.into_iter().collect();
        Ok(())
    }
}

fn error(span: &Span, code: &str, message: impl Into<String>) -> Diagnostic {
    Diagnostic::new(code, message, span.clone())
}
fn field<'a>(value: &'a Value, name: &str, span: &Span) -> Result<&'a Value, Diagnostic> {
    value.field(name).ok_or_else(|| {
        error(
            span,
            "spatial_field",
            format!("{} requires field `{name}`", value.type_name()),
        )
    })
}
fn number(value: &Value, span: &Span) -> Result<f64, Diagnostic> {
    match value {
        Value::Number(number) if number.is_finite() && number.abs() <= sdk::MAX_COORDINATE_M => {
            Ok(*number)
        }
        _ => Err(error(
            span,
            "spatial_number",
            "spatial number must be finite and within +/-1,000,000",
        )),
    }
}
fn numeric_field(value: &Value, name: &str, span: &Span) -> Result<f64, Diagnostic> {
    number(field(value, name, span)?, span)
}
fn positive(value: f64, span: &Span) -> Result<f64, Diagnostic> {
    if value.is_finite() && (1e-6..=sdk::MAX_COORDINATE_M).contains(&value) {
        Ok(value)
    } else {
        Err(error(
            span,
            "spatial_dimension",
            "dimensions must be between 0.000001 and 1,000,000",
        ))
    }
}
fn text<'a>(value: &'a Value, span: &Span) -> Result<&'a str, Diagnostic> {
    if let Value::Text(text) = value {
        Ok(text)
    } else {
        Err(error(span, "spatial_type", "expected a Str"))
    }
}
fn vector(value: &Value, span: &Span) -> Result<sdk::Vec3, Diagnostic> {
    if value.type_name() != "Vec3" {
        return Err(error(span, "spatial_type", "expected a Vec3"));
    }
    Ok(sdk::Vec3 {
        x: numeric_field(value, "x", span)?,
        y: numeric_field(value, "y", span)?,
        z: numeric_field(value, "z", span)?,
    })
}
fn tensor<'a>(value: &'a Value, span: &Span) -> Result<&'a sdk::data::Tensor, Diagnostic> {
    if let Value::Tensor(value) = value {
        Ok(value)
    } else {
        Err(error(span, "spatial_type", "expected a Tensor"))
    }
}

// Materialize only at the renderer boundary; strided tensor views preserve their logical order.
fn tensor_positions(
    value: &Value,
    maximum: usize,
    span: &Span,
) -> Result<Vec<sdk::Vec3>, Diagnostic> {
    let tensor = tensor(value, span)?;
    let shape = tensor.shape();
    if tensor.dtype() != sdk::data::DType::F32
        || shape.len() != 2
        || shape[1] != 3
        || shape[0] > maximum
    {
        return Err(error(
            span,
            "spatial_shape",
            "positions require a bounded N by 3 Tensor[f32]",
        ));
    }
    (0..shape[0])
        .map(|row| {
            let coordinate = |axis| {
                let value = tensor
                    .get(&[row as isize, axis])
                    .and_then(|value| value.to_f64())
                    .map_err(|e| error(span, "spatial_type", e.to_string()))?;
                if value.abs() > sdk::MAX_COORDINATE_M {
                    return Err(error(
                        span,
                        "spatial_dimension",
                        "position exceeds coordinate bounds",
                    ));
                }
                Ok(value)
            };
            Ok(sdk::Vec3 {
                x: coordinate(0)?,
                y: coordinate(1)?,
                z: coordinate(2)?,
            })
        })
        .collect()
}
fn record<const N: usize>(class: &str, fields: [(&str, Value); N]) -> Value {
    Value::record(
        class,
        fields.into_iter().map(|(name, value)| (name.into(), value)),
    )
}
fn vector_value(vector: sdk::Vec3) -> Value {
    record(
        "Vec3",
        [
            ("x", Value::Number(vector.x)),
            ("y", Value::Number(vector.y)),
            ("z", Value::Number(vector.z)),
        ],
    )
}
fn default_transform() -> Value {
    record(
        "Transform",
        [
            ("position", vector_value(sdk::Vec3::ZERO)),
            ("rotation", vector_value(sdk::Vec3::ZERO)),
            (
                "scale",
                vector_value(sdk::Vec3 {
                    x: 1.0,
                    y: 1.0,
                    z: 1.0,
                }),
            ),
        ],
    )
}
fn default_material() -> Value {
    record(
        "Material",
        [
            ("color", Value::Text("#6fe3ff".into())),
            ("roughness", Value::Number(0.6)),
            ("emissive", Value::Number(0.0)),
        ],
    )
}
fn replace_field(
    value: &mut Value,
    key: &str,
    replacement: Value,
    span: &Span,
) -> Result<(), Diagnostic> {
    if let Value::Record(record) = value {
        record.fields.insert(key.into(), replacement);
        Ok(())
    } else {
        Err(error(span, "spatial_type", "component must be a record"))
    }
}
fn to_vector(value: sdk::Vec3) -> Vector {
    Vector::new(value.x as f32, value.y as f32, value.z as f32)
}
fn from_vector(value: Vector) -> sdk::Vec3 {
    sdk::Vec3 {
        x: f64::from(value.x),
        y: f64::from(value.y),
        z: f64::from(value.z),
    }
}
fn pose(transform: sdk::Transform) -> Pose {
    let q = transform.rotation;
    Pose::from_parts(
        to_vector(transform.translation),
        Rotation::from_xyzw(q.x as f32, q.y as f32, q.z as f32, q.w as f32).normalize(),
    )
}
fn transform(value: &Value, span: &Span) -> Result<sdk::Transform, Diagnostic> {
    let translation = vector(field(value, "position", span)?, span)?;
    let angles = vector(field(value, "rotation", span)?, span)?;
    let scale = vector(field(value, "scale", span)?, span)?;
    for dimension in [scale.x, scale.y, scale.z] {
        positive(dimension, span)?;
    }
    let q = DQuat::from_euler(EulerRot::XYZ, angles.x, angles.y, angles.z);
    Ok(sdk::Transform {
        translation,
        rotation: sdk::Quaternion {
            x: q.x,
            y: q.y,
            z: q.z,
            w: q.w,
        },
        scale,
    })
}
fn material(value: &Value, span: &Span) -> Result<(sdk::Color, sdk::Material), Diagnostic> {
    let color = text(field(value, "color", span)?, span)?;
    let digits = color
        .strip_prefix('#')
        .filter(|digits| {
            matches!(digits.len(), 6 | 8)
                && digits.is_ascii()
                && digits.bytes().all(|byte| byte.is_ascii_hexdigit())
        })
        .ok_or_else(|| {
            error(
                span,
                "invalid_color",
                "Material.color must be #RRGGBB or #RRGGBBAA",
            )
        })?;
    let channel = |offset: usize| {
        u8::from_str_radix(&digits[offset..offset + 2], 16)
            .map_err(|_| error(span, "invalid_color", "invalid hexadecimal color"))
    };
    let roughness = numeric_field(value, "roughness", span)?;
    let emissive = numeric_field(value, "emissive", span)?;
    if !(0.0..=1.0).contains(&roughness) || !(0.0..=100.0).contains(&emissive) {
        return Err(error(
            span,
            "invalid_material",
            "roughness must be 0..=1 and emissive must be 0..=100",
        ));
    }
    Ok((
        sdk::Color {
            r: channel(0)?,
            g: channel(2)?,
            b: channel(4)?,
            a: if digits.len() == 8 { channel(6)? } else { 255 },
        },
        sdk::Material {
            roughness: roughness as f32,
            emissive: emissive as f32,
        },
    ))
}
fn geometry_component<'a>(
    components: &'a BTreeMap<String, Value>,
    span: &Span,
) -> Result<Option<(&'static str, &'a Value)>, Diagnostic> {
    let mut present = GEOMETRIES
        .iter()
        .filter_map(|name| components.get(*name).map(|value| (*name, value)));
    let first = present.next();
    if present.next().is_some() {
        return Err(error(
            span,
            "multiple_geometry",
            "an entity may have only one geometry component",
        ));
    }
    Ok(first)
}
fn body_config(
    value: &Value,
    components: &BTreeMap<String, Value>,
    scale: sdk::Vec3,
    span: &Span,
) -> Result<BodyConfig, Diagnostic> {
    let kind = match text(field(value, "kind", span)?, span)? {
        "dynamic" => BodyKind::Dynamic,
        "fixed" => BodyKind::Fixed,
        "kinematic" => BodyKind::Kinematic,
        _ => {
            return Err(error(
                span,
                "invalid_body",
                "RigidBody.kind must be dynamic, fixed, or kinematic",
            ));
        }
    };
    let shape = match geometry_component(components, span)? {
        Some(("Sphere", sphere)) => {
            if scale.x != scale.y || scale.x != scale.z {
                return Err(error(
                    span,
                    "unsupported_shape",
                    "a physical Sphere requires uniform scale",
                ));
            }
            CollisionShape::Sphere(
                positive(numeric_field(sphere, "radius", span)? * scale.x, span)? as f32,
            )
        }
        Some(("Box", box_value)) => {
            let size = vector(field(box_value, "size", span)?, span)?;
            CollisionShape::Box(Vector::new(
                positive(size.x * scale.x, span)? as f32,
                positive(size.y * scale.y, span)? as f32,
                positive(size.z * scale.z, span)? as f32,
            ))
        }
        _ => {
            return Err(error(
                span,
                "unsupported_shape",
                "RigidBody collision geometry must be Sphere or Box",
            ));
        }
    };
    let mass = positive(numeric_field(value, "mass", span)?, span)? as f32;
    let restitution = numeric_field(value, "restitution", span)?;
    let friction = numeric_field(value, "friction", span)?;
    if !(0.0..=1.0).contains(&restitution) || !(0.0..=1.0).contains(&friction) {
        return Err(error(
            span,
            "invalid_body",
            "restitution and friction must be 0..=1",
        ));
    }
    Ok(BodyConfig {
        kind,
        shape,
        mass,
        restitution: restitution as f32,
        friction: friction as f32,
    })
}

fn geometry(
    name: &str,
    value: &Value,
    id: &EntityId,
    span: &Span,
) -> Result<(Geometry, Mesh), Diagnostic> {
    let geometry = match name {
        "Sphere" => Geometry::Sphere {
            radius_m: positive(numeric_field(value, "radius", span)?, span)?,
        },
        "Box" => Geometry::Box {
            size_m: vector(field(value, "size", span)?, span)?,
        },
        "Cylinder" => Geometry::Cylinder {
            radius_m: positive(numeric_field(value, "radius", span)?, span)?,
            height_m: positive(numeric_field(value, "height", span)?, span)?,
        },
        "Line" => Geometry::Line {
            from_m: vector(field(value, "from", span)?, span)?,
            to_m: vector(field(value, "to", span)?, span)?,
        },
        "Ray" => {
            let origin = vector(field(value, "origin", span)?, span)?;
            let direction = vector(field(value, "direction", span)?, span)?;
            let length = positive(numeric_field(value, "length", span)?, span)?;
            let magnitude = direction.x.hypot(direction.y).hypot(direction.z);
            if magnitude <= 1e-12 {
                return Err(error(span, "invalid_ray", "Ray.direction must be nonzero"));
            }
            Geometry::Line {
                from_m: origin,
                to_m: sdk::Vec3 {
                    x: origin.x + direction.x / magnitude * length,
                    y: origin.y + direction.y / magnitude * length,
                    z: origin.z + direction.z / magnitude * length,
                },
            }
        }
        "Quad" => {
            let x = positive(numeric_field(value, "width", span)?, span)? / 2.0;
            let y = positive(numeric_field(value, "height", span)?, span)? / 2.0;
            return Ok((
                Geometry::Mesh {
                    asset: id.0.clone(),
                },
                Mesh {
                    positions: vec![
                        sdk::Vec3 {
                            x: -x,
                            y: -y,
                            z: 0.0,
                        },
                        sdk::Vec3 { x, y: -y, z: 0.0 },
                        sdk::Vec3 { x, y, z: 0.0 },
                        sdk::Vec3 { x: -x, y, z: 0.0 },
                    ],
                    normals: vec![
                        sdk::Vec3 {
                            x: 0.0,
                            y: 0.0,
                            z: 1.0
                        };
                        4
                    ],
                    indices: vec![0, 1, 2, 0, 2, 3],
                },
            ));
        }
        "Mesh" => {
            return Ok((
                Geometry::Mesh {
                    asset: id.0.clone(),
                },
                custom_mesh(value, span)?,
            ));
        }
        "PointCloud" => {
            return Ok((
                Geometry::Mesh {
                    asset: id.0.clone(),
                },
                point_cloud(value, span)?,
            ));
        }
        _ => {
            return Err(error(
                span,
                "unsupported_geometry",
                "unsupported geometry component",
            ));
        }
    };
    let mesh = sdk::tessellate(&geometry)
        .map_err(|diagnostic| error(span, "invalid_geometry", diagnostic.to_string()))?;
    Ok((geometry, mesh))
}

pub(crate) fn custom_mesh(value: &Value, span: &Span) -> Result<Mesh, Diagnostic> {
    let positions = tensor_positions(field(value, "positions", span)?, MAX_MESH_VERTICES, span)?;
    let index_data = tensor(field(value, "indices", span)?, span)?;
    let shape = index_data.shape();
    if positions.len() < 3
        || index_data.dtype() != sdk::data::DType::U32
        || shape.len() != 2
        || shape[1] != 3
        || shape[0] == 0
        || shape[0] > MAX_MESH_INDICES / 3
    {
        return Err(error(
            span,
            "invalid_mesh",
            "Mesh requires N by 3 positions and M by 3 triangle indices within the mesh limits",
        ));
    }
    let mut indices = Vec::with_capacity(shape[0] * 3);
    for triangle in 0..shape[0] {
        for corner in 0..3 {
            let index = index_data
                .get(&[triangle as isize, corner])
                .map_err(|e| error(span, "invalid_mesh_index", e.to_string()))?
                .as_u128()
                .ok_or_else(|| error(span, "spatial_type", "mesh indices must be u32"))?;
            if index >= positions.len() as u128 {
                return Err(error(
                    span,
                    "invalid_mesh_index",
                    "mesh indices must address an existing vertex",
                ));
            }
            indices.push(index as u32);
        }
    }
    let supplied_normals =
        tensor_positions(field(value, "normals", span)?, MAX_MESH_VERTICES, span)?;
    if !supplied_normals.is_empty() && supplied_normals.len() != positions.len() {
        return Err(error(
            span,
            "invalid_mesh_normals",
            "Mesh.normals must be empty or have one N by 3 normal for every position",
        ));
    }
    let mut normals = vec![sdk::Vec3::ZERO; positions.len()];
    for triangle in indices.as_chunks::<3>().0 {
        let a = positions[triangle[0] as usize];
        let b = positions[triangle[1] as usize];
        let c = positions[triangle[2] as usize];
        let ab = sdk::Vec3 {
            x: b.x - a.x,
            y: b.y - a.y,
            z: b.z - a.z,
        };
        let ac = sdk::Vec3 {
            x: c.x - a.x,
            y: c.y - a.y,
            z: c.z - a.z,
        };
        let normal = sdk::Vec3 {
            x: ab.y * ac.z - ab.z * ac.y,
            y: ab.z * ac.x - ab.x * ac.z,
            z: ab.x * ac.y - ab.y * ac.x,
        };
        if normal.x.hypot(normal.y).hypot(normal.z) <= 1e-18 {
            if !supplied_normals.is_empty() {
                continue;
            }
            return Err(error(
                span,
                "degenerate_mesh",
                "mesh triangles must have nonzero area",
            ));
        }
        for &index in triangle {
            let n = &mut normals[index as usize];
            n.x += normal.x;
            n.y += normal.y;
            n.z += normal.z;
        }
    }
    if !supplied_normals.is_empty() {
        normals = supplied_normals;
        for normal in &mut normals {
            let length = normal.x.hypot(normal.y).hypot(normal.z);
            if !length.is_finite() || length <= 1e-18 {
                return Err(error(
                    span,
                    "invalid_mesh_normals",
                    "Mesh.normals must be finite and nonzero",
                ));
            }
            normal.x /= length;
            normal.y /= length;
            normal.z /= length;
        }
        return Ok(Mesh {
            positions,
            normals,
            indices,
        });
    }
    for normal in &mut normals {
        let length = normal.x.hypot(normal.y).hypot(normal.z);
        if length <= 1e-18 {
            return Err(error(
                span,
                "invalid_mesh_normals",
                "mesh vertices must have a nonzero accumulated normal; remove unused vertices and split opposing faces",
            ));
        }
        normal.x /= length;
        normal.y /= length;
        normal.z /= length;
    }
    Ok(Mesh {
        positions,
        normals,
        indices,
    })
}

fn point_cloud(value: &Value, span: &Span) -> Result<Mesh, Diagnostic> {
    let points = tensor_positions(field(value, "points", span)?, MAX_CLOUD_POINTS, span)?;
    if points.is_empty() || points.len() > MAX_CLOUD_POINTS {
        return Err(error(
            span,
            "point_cloud_limit",
            format!("PointCloud requires 1..={MAX_CLOUD_POINTS} points"),
        ));
    }
    let radius = positive(numeric_field(value, "radius", span)?, span)?;
    let sphere = sdk::tessellate(&Geometry::Sphere { radius_m: radius })
        .map_err(|diagnostic| error(span, "invalid_geometry", diagnostic.to_string()))?;
    let mut mesh = Mesh {
        positions: Vec::with_capacity(sphere.positions.len() * points.len()),
        normals: Vec::with_capacity(sphere.normals.len() * points.len()),
        indices: Vec::with_capacity(sphere.indices.len() * points.len()),
    };
    for point in points {
        let offset = u32::try_from(mesh.positions.len())
            .map_err(|_| error(span, "mesh_limit", "point cloud exceeds index range"))?;
        for vertex in &sphere.positions {
            let vertex = sdk::Vec3 {
                x: vertex.x + point.x,
                y: vertex.y + point.y,
                z: vertex.z + point.z,
            };
            if [vertex.x, vertex.y, vertex.z]
                .iter()
                .any(|coordinate| coordinate.abs() > sdk::MAX_COORDINATE_M)
            {
                return Err(error(
                    span,
                    "spatial_dimension",
                    "point cloud surface exceeds coordinate bounds",
                ));
            }
            mesh.positions.push(vertex);
        }
        mesh.normals.extend_from_slice(&sphere.normals);
        mesh.indices
            .extend(sphere.indices.iter().map(|index| index + offset));
    }
    Ok(mesh)
}