mecha10-sim 0.8.2

//! Environment config (`environment.json`) parsing and validation.
//!
//! This module is the Rust-side representation of the full `environment.json` document (schema:
//! `configs/simulation/schemas/environment-config.schema.json`, published by the separate
//! `mecha10-assets` repo and fetched at runtime -- see
//! `mecha10_schema_registry::environment_config_schema`), most notably the `type: "image"`
//! billboard object introduced for LAB-2025 (porting Godot's config-driven PNG billboard
//! rendering to the MuJoCo simulator).
//!
//! `EnvironmentConfig` now mirrors every field the hand-written schema requires/describes
//! (previously only `id`/`version`/`name`/`description`/`features.objects[]` were modeled here;
//! `scene_path`, `dimensions`, and the rest of `features` were silently unparsed even though the
//! schema already required/described them). This is deliberately option (b) from that
//! tightening pass rather than making this struct `schemars`-derive the schema: the hand-written
//! schema fetched from `mecha10-assets` stays the source of truth (it's what `mecha10 config
//! push`'s validation gate and `cargo run --example export_schemas` both read via
//! `mecha10_schema_registry::environment_config_schema`), and this struct is kept in lockstep
//! with it by hand -- see `config_validation.rs`'s `validate_environment_configs_rejects_*` tests
//! (schema-side) and this module's own tests (struct-side) for the two halves of that guarantee.
//! `rewards` stays `serde_json::Value`: no committed `environment.json` (here or in
//! `mecha10-assets`) has ever populated it, so there's no real shape to type against yet.
//!
//! Scope note (LAB-2025): the actual MJCF generation that turns a `type: "image"` object into a
//! MuJoCo `<texture>`/`<material>`/`<geom type="plane">` triple lives in
//! `mecha10_rl.mujoco.mjcf_generator` (Python), which was extracted out of this repo into the
//! external `mecha-industries/mecha10-rl` repo (LAB-1830) and is not reachable from here. This
//! module only covers what's verifiable in-repo: parsing `environment.json` into typed Rust
//! structs and validating that an image object's fields (in particular, that `source` resolves to
//! a file that actually exists on disk) are well-formed. See
//! the "Simulation: MuJoCo Architecture" Linear doc for the target MJCF mapping contract and the
//! tracked `mecha10-rl` follow-up.

use anyhow::{bail, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnvironmentConfig {
    pub id: String,
    pub version: String,
    pub name: String,
    pub description: String,
    pub scene_path: String,
    pub dimensions: EnvironmentDimensions,
    pub features: EnvironmentFeatures,
    #[serde(default)]
    pub rewards: Option<serde_json::Value>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnvironmentDimensions {
    pub width: f64,
    pub length: f64,
    pub height: f64,
    pub unit: DistanceUnit,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DistanceUnit {
    Meters,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EnvironmentFeatures {
    #[serde(default)]
    pub floor: Option<FloorFeature>,
    #[serde(default)]
    pub walls: Option<WallsFeature>,
    #[serde(default)]
    pub lighting: Option<LightingFeature>,
    #[serde(default)]
    pub spawn_points: Option<SpawnPointsFeature>,
    #[serde(default)]
    pub obstacles: Option<ObstaclesFeature>,
    #[serde(default)]
    pub objects: Vec<SceneObject>,
    #[serde(default)]
    pub goals: Option<GoalsFeature>,
    #[serde(default)]
    pub npcs: Option<NpcsFeature>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FloorFeature {
    #[serde(rename = "type")]
    pub floor_type: String,
    pub material: String,
    pub friction: f64,
    pub collision: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WallsFeature {
    pub count: u32,
    pub height: f64,
    pub thickness: f64,
    pub material: String,
    pub collision: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LightingFeature {
    pub directional: DirectionalLight,
    pub ambient: AmbientLight,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DirectionalLight {
    pub enabled: bool,
    pub energy: f64,
    pub shadows: bool,
    pub angle: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AmbientLight {
    pub enabled: bool,
    pub color: [f64; 4],
    pub source: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SpawnPointsFeature {
    pub count: u32,
    pub positions: Vec<[f64; 3]>,
    pub default_index: u32,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObstaclesFeature {
    pub count: u32,
    #[serde(rename = "type")]
    pub obstacle_type: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GoalsFeature {
    pub count: u32,
    #[serde(rename = "type")]
    pub goal_type: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NpcsFeature {
    pub enabled: bool,
    pub count: u32,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum SceneObject {
    Cube(CubeObject),
    Image(ImageObject),
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CubeObject {
    pub position: [f64; 3],
    #[serde(default = "default_scale")]
    pub size: [f64; 3],
    #[serde(default)]
    pub color: Option<[f64; 4]>,
    #[serde(default)]
    pub add_collision: bool,
    #[serde(default)]
    pub material_type: Option<String>,
    #[serde(default)]
    pub roughness: Option<f64>,
    #[serde(default)]
    pub metallic: Option<f64>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ImageObject {
    pub source: String,
    pub position: [f64; 3],
    #[serde(default)]
    pub rotation: [f64; 3],
    #[serde(default = "default_scale")]
    pub scale: [f64; 3],
    #[serde(default)]
    pub interactive: bool,
    #[serde(default = "default_true")]
    pub visible: bool,
    /// Optional back-and-forth patrol motion along one world axis (`find_target_patrol`).
    /// Declares the contract only -- `mecha10-rl` (not this repo) actually advances the
    /// object's position along the line during an episode. Absent for every other bundled
    /// task's image objects, which stay stationary.
    #[serde(default)]
    pub motion: Option<ObjectMotion>,
}

/// Patrol-motion contract for an [`ImageObject`] (schema:
/// `configs/simulation/schemas/environment-config.schema.json`'s `imageObject.motion`,
/// published by `mecha10-assets`). Field names/shape are an agreed contract with the external
/// `mecha10-rl` repo, which is what actually moves the object each step -- keep them in
/// lockstep with that schema rather than renaming independently.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObjectMotion {
    #[serde(rename = "type")]
    pub motion_type: MotionType,
    pub axis: MotionAxis,
    pub range_min: f64,
    pub range_max: f64,
    #[serde(default = "default_motion_speed")]
    pub speed: f64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MotionType {
    Patrol,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MotionAxis {
    X,
    Y,
}

fn default_motion_speed() -> f64 {
    1.0
}

fn default_scale() -> [f64; 3] {
    [1.0, 1.0, 1.0]
}

fn default_true() -> bool {
    true
}

impl EnvironmentConfig {
    /// Load and parse an `environment.json` file from `path`.
    pub fn load(path: &Path) -> Result<Self> {
        super::load_json(path, "environment config")
    }

    /// All `type: "image"` billboard objects declared in this environment.
    pub fn image_objects(&self) -> impl Iterator<Item = &ImageObject> {
        self.features.objects.iter().filter_map(|obj| match obj {
            SceneObject::Image(image) => Some(image),
            SceneObject::Cube(_) => None,
        })
    }
}

impl ImageObject {
    /// Validate this image object, resolving `source` relative to `repo_root` and confirming the
    /// asset file actually exists on disk.
    ///
    /// This is the extent of "generates valid MuJoCo XML" verification achievable from this repo
    /// (LAB-2025): we cannot invoke the external `mecha10_rl.mujoco.mjcf_generator` from here, so
    /// this validates the config contract that generator depends on instead.
    pub fn validate(&self, repo_root: &Path) -> Result<PathBuf> {
        if self.source.trim().is_empty() {
            bail!("image object has an empty `source` path");
        }

        let resolved = repo_root.join(&self.source);
        if !resolved.is_file() {
            bail!(
                "image object `source` does not resolve to a file: {} (resolved: {})",
                self.source,
                resolved.display()
            );
        }

        if self.scale.iter().any(|component| *component <= 0.0) {
            bail!("image object `scale` components must be positive, got {:?}", self.scale);
        }

        Ok(resolved)
    }
}

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

    fn repo_root() -> PathBuf {
        Path::new(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .and_then(Path::parent)
            .expect("repo root")
            .to_path_buf()
    }

    // The real `environment.json`/`preset.json`/`task.json` bundle used to live in-repo under
    // `mecha10-templates/templates/configs/{simulation,rl}/`. That tree was extracted to the
    // separate `mecha10-assets` repo and deleted from here (mecha-industries/mecha10#1348) - it's
    // now served live via `mecha10-api`'s `GET /api/downloads/assets`, not readable from this
    // crate at test time. The constants below are realistic hand-maintained copies of what
    // `mecha10-assets` publishes (kept in lockstep by hand - there is no compile-time or
    // test-time link to the real files anymore).
    //
    // `configs/simulation/images/aiko.jpg`/`phoebe.jpg` at this repo's own root are a separate,
    // still-present, trimmed-down dev sample (not part of the deleted `mecha10-templates` tree) -
    // tests that exercise `ImageObject::validate`'s on-disk file check still resolve against
    // those real files below.

    const BASIC_ARENA_ENVIRONMENT_JSON: &str = r#"{
        "id": "basic_arena",
        "version": "1.0.0",
        "name": "Basic Arena",
        "description": "Versatile starter arena with flat plane, walls, lighting, and multiple spawn points",
        "scene_path": "res://packages/mecha10-templates/templates/configs/simulation/environments/basic_arena/basic_arena.tscn",
        "dimensions": {"width": 20.0, "length": 20.0, "height": 3.0, "unit": "meters"},
        "features": {
            "floor": {"type": "flat", "material": "concrete", "friction": 0.8, "collision": true},
            "walls": {"count": 4, "height": 3.0, "thickness": 0.5, "material": "concrete", "collision": true},
            "lighting": {
                "directional": {"enabled": true, "energy": 1.2, "shadows": true, "angle": "45_degrees"},
                "ambient": {"enabled": true, "color": [0.8, 0.8, 0.8, 1.0], "source": "background"}
            },
            "spawn_points": {
                "count": 5,
                "positions": [[0, 5.0, 0], [-5, 5.0, -5], [5, 5.0, -5], [-5, 5.0, 5], [5, 5.0, 5]],
                "default_index": 0
            },
            "obstacles": {"count": 5, "type": "mixed"},
            "objects": [
                {
                    "type": "cube",
                    "position": [3.0, 0.5, 3.0],
                    "size": [1.0, 1.0, 1.0],
                    "color": [0.8, 0.2, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.8,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-3.0, 0.5, 3.0],
                    "size": [0.8, 0.8, 0.8],
                    "color": [0.2, 0.8, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.8,
                    "metallic": 0.0
                }
            ],
            "goals": {"count": 0, "type": "none"},
            "npcs": {"enabled": false, "count": 0}
        }
    }"#;

    const HOME_OUTDOOR_URBAN_ENVIRONMENT_JSON: &str = r#"{
        "id": "home_outdoor_urban",
        "version": "1.0.0",
        "name": "Home & Outdoor Urban",
        "description": "Realistic mixed-use environment: a partitioned home interior opening onto an outdoor urban street.",
        "scene_path": "res://packages/mecha10-templates/templates/configs/simulation/environments/home_outdoor_urban/home_outdoor_urban.tscn",
        "dimensions": {"width": 34.0, "length": 20.0, "height": 4.0, "unit": "meters"},
        "features": {
            "floor": {"type": "flat", "material": "concrete", "friction": 0.85, "collision": true},
            "walls": {"count": 4, "height": 3.2, "thickness": 0.3, "material": "brick", "collision": true},
            "lighting": {
                "directional": {"enabled": true, "energy": 1.4, "shadows": true, "angle": "60_degrees"},
                "ambient": {"enabled": true, "color": [0.75, 0.78, 0.85, 1.0], "source": "sky"}
            },
            "spawn_points": {
                "count": 4,
                "positions": [[-12.0, 0.5, 0.0], [-1.0, 0.5, 0.0], [5.0, 0.5, -3.0], [12.0, 0.5, 6.0]],
                "default_index": 0
            },
            "obstacles": {"count": 18, "type": "mixed"},
            "objects": [
                {
                    "type": "cube",
                    "position": [-9.0, 1.6, -4.0],
                    "size": [0.3, 3.2, 10.0],
                    "color": [0.7, 0.65, 0.6, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.9,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-5.0, 1.6, 2.0],
                    "size": [8.0, 3.2, 0.3],
                    "color": [0.7, 0.65, 0.6, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.9,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-13.0, 0.4, -6.0],
                    "size": [2.2, 0.8, 0.9],
                    "color": [0.35, 0.25, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.8,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-12.0, 0.25, -3.5],
                    "size": [1.0, 0.5, 0.6],
                    "color": [0.4, 0.3, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.7,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-7.0, 0.4, 5.0],
                    "size": [1.6, 0.8, 1.0],
                    "color": [0.5, 0.35, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.7,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [-4.0, 0.45, 6.0],
                    "size": [1.8, 0.9, 0.8],
                    "color": [0.85, 0.85, 0.85, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.4,
                    "metallic": 0.1
                },
                {
                    "type": "cube",
                    "position": [-14.0, 0.3, 4.0],
                    "size": [1.6, 0.6, 2.0],
                    "color": [0.6, 0.6, 0.7, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.8,
                    "metallic": 0.0
                },
                {
                    "type": "cube",
                    "position": [8.0, 0.6, -7.0],
                    "size": [4.2, 1.2, 1.8],
                    "color": [0.15, 0.15, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "metallic",
                    "roughness": 0.3,
                    "metallic": 0.7
                },
                {
                    "type": "cube",
                    "position": [3.0, 2.0, 8.0],
                    "size": [0.25, 4.0, 0.25],
                    "color": [0.2, 0.2, 0.2, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.6,
                    "metallic": 0.2
                },
                {
                    "type": "cube",
                    "position": [10.0, 0.25, 8.0],
                    "size": [1.6, 0.5, 0.5],
                    "color": [0.3, 0.2, 0.1, 1.0],
                    "add_collision": true,
                    "material_type": "standard",
                    "roughness": 0.9,
                    "metallic": 0.0
                }
            ],
            "goals": {"count": 2, "type": "waypoint"},
            "npcs": {"enabled": true, "count": 2}
        }
    }"#;

    const MOVING_OBJECTS_ARENA_ENVIRONMENT_JSON: &str = r#"{
        "id": "moving_objects_arena",
        "version": "1.0.0",
        "name": "Moving Objects Arena",
        "description": "basic_arena's generic arena with image objects that patrol back and forth instead of sitting still.",
        "scene_path": "res://packages/mecha10-templates/templates/configs/simulation/environments/moving_objects_arena/moving_objects_arena.tscn",
        "dimensions": {"width": 20.0, "length": 20.0, "height": 3.0, "unit": "meters"},
        "features": {
            "floor": {"type": "flat", "material": "concrete", "friction": 0.8, "collision": true},
            "walls": {"count": 4, "height": 3.0, "thickness": 0.5, "material": "concrete", "collision": true},
            "lighting": {
                "directional": {"enabled": true, "energy": 1.2, "shadows": true, "angle": "45_degrees"},
                "ambient": {"enabled": true, "color": [0.8, 0.8, 0.8, 1.0], "source": "background"}
            },
            "spawn_points": {
                "count": 5,
                "positions": [[0, 5.0, 0], [-5, 5.0, -5], [5, 5.0, -5], [-5, 5.0, 5], [5, 5.0, 5]],
                "default_index": 0
            },
            "obstacles": {"count": 0, "type": "none"},
            "objects": [
                {
                    "type": "image",
                    "source": "configs/simulation/images/aiko.jpg",
                    "position": [-6.0, 0.5, -4.0],
                    "rotation": [0, 90, 0],
                    "scale": [1.0, 1.0, 1.0],
                    "interactive": false,
                    "visible": true,
                    "motion": {"type": "patrol", "axis": "x", "range_min": -8.0, "range_max": 8.0, "speed": 1.0}
                },
                {
                    "type": "image",
                    "source": "configs/simulation/images/phoebe.jpg",
                    "position": [6.0, 0.5, 2.0],
                    "rotation": [0, -90, 0],
                    "scale": [1.0, 1.0, 1.0],
                    "interactive": false,
                    "visible": true,
                    "motion": {"type": "patrol", "axis": "x", "range_min": -8.0, "range_max": 8.0, "speed": 1.6}
                }
            ],
            "goals": {"count": 0, "type": "none"},
            "npcs": {"enabled": false, "count": 0}
        }
    }"#;

    const CATS_PRESET_JSON: &str = r#"{
        "id": "cats",
        "version": "1.0.0",
        "description": "Cat detection targets (aiko/phoebe) for find_target-style tasks - two stationary image billboards positioned for a rotate-in-place-to-center find/hold task.",
        "objects": [
            {
                "type": "image",
                "source": "configs/simulation/images/aiko.jpg",
                "position": [-3.0, 0.5, 0.0],
                "rotation": [0, 90, 0],
                "scale": [1.0, 1.0, 1.0],
                "interactive": false,
                "visible": true
            },
            {
                "type": "image",
                "source": "configs/simulation/images/phoebe.jpg",
                "position": [3.0, 0.5, 1.5],
                "rotation": [0, -90, 0],
                "scale": [1.0, 1.0, 1.0],
                "interactive": false,
                "visible": true
            }
        ]
    }"#;

    const OBJECTS_PATROL_PRESET_JSON: &str = r#"{
        "id": "objects_patrol",
        "version": "1.0.0",
        "description": "Same mixed image set as the `objects` preset, but every object declares a patrol `motion` block instead of sitting still - used by find_target_patrol.",
        "objects": [
            {
                "type": "image",
                "source": "configs/simulation/images/aiko.jpg",
                "position": [-3.0, 0.5, 0.0],
                "rotation": [0, 90, 0],
                "scale": [1.0, 1.0, 1.0],
                "interactive": false,
                "visible": true,
                "motion": {"type": "patrol", "axis": "x", "range_min": -8.0, "range_max": 8.0, "speed": 1.0}
            },
            {
                "type": "image",
                "source": "configs/simulation/images/phoebe.jpg",
                "position": [3.0, 0.5, 1.5],
                "rotation": [0, -116.6, 0],
                "scale": [1.0, 1.0, 1.0],
                "interactive": false,
                "visible": true,
                "motion": {"type": "patrol", "axis": "x", "range_min": -8.0, "range_max": 8.0, "speed": 1.0}
            },
            {
                "type": "image",
                "source": "configs/simulation/images/dog1.jpg",
                "position": [0.0, 0.5, 3.0],
                "rotation": [0, 180, 0],
                "scale": [1.0, 1.0, 1.0],
                "interactive": false,
                "visible": true,
                "motion": {"type": "patrol", "axis": "x", "range_min": -8.0, "range_max": 8.0, "speed": 1.0}
            }
        ]
    }"#;

    const FIND_TARGET_TASK_JSON: &str = r#"{
        "id": "find_target",
        "version": "1.0.0",
        "env_name": "basic_arena",
        "model": "rover",
        "goal_type": "find",
        "target": "cat",
        "preset": "cats",
        "room_size": 8.0,
        "target_range_min": 3.0,
        "target_range_max": 4.0,
        "goal_radius": 0.15,
        "obstacle_count": 0,
        "obstacle_radius": 0.3,
        "max_episode_steps": 200,
        "action_duration_s": 0.25,
        "target_hold_steps": 10,
        "max_linear_speed": 0.3,
        "max_angular_speed": 1.0
    }"#;

    const DEFAULT_TASK_JSON: &str = r#"{
        "id": "default",
        "version": "1.0.0",
        "env_name": "basic_arena",
        "model": "rover",
        "goal_type": "none",
        "preset": "default",
        "max_episode_steps": 200,
        "action_duration_s": 0.25,
        "max_linear_speed": 0.3,
        "max_angular_speed": 1.0
    }"#;

    const FIND_TARGET_PATROL_TASK_JSON: &str = r#"{
        "id": "find_target_patrol",
        "version": "1.0.0",
        "env_name": "basic_arena",
        "model": "rover",
        "goal_type": "find",
        "target": "cat",
        "targets": ["cat", "dog", "car", "bicycle", "bird", "bottle", "chair", "backpack"],
        "preset": "objects_patrol",
        "room_size": 8.0,
        "target_range_min": 3.0,
        "target_range_max": 4.0,
        "goal_radius": 0.15,
        "obstacle_count": 0,
        "obstacle_radius": 0.3,
        "max_episode_steps": 200,
        "action_duration_s": 0.25,
        "target_hold_steps": 5,
        "center_margin": 0.2,
        "max_linear_speed": 0.3,
        "max_angular_speed": 1.0
    }"#;

    #[test]
    fn parses_cube_object() {
        let json = r#"{
            "type": "cube",
            "position": [1.0, 0.5, 2.0],
            "size": [1.0, 1.0, 1.0],
            "color": [0.8, 0.2, 0.2, 1.0],
            "add_collision": true,
            "material_type": "standard",
            "roughness": 0.8,
            "metallic": 0.0
        }"#;
        let obj: SceneObject = serde_json::from_str(json).unwrap();
        match obj {
            SceneObject::Cube(cube) => {
                assert_eq!(cube.position, [1.0, 0.5, 2.0]);
                assert!(cube.add_collision);
            }
            SceneObject::Image(_) => panic!("expected cube"),
        }
    }

    #[test]
    fn parses_image_object() {
        let json = r#"{
            "type": "image",
            "source": "configs/simulation/images/aiko.jpg",
            "position": [0.0, 0.5, 3.5],
            "rotation": [0, 180, 0],
            "scale": [2.5, 2.5, 2.5],
            "interactive": false,
            "visible": true
        }"#;
        let obj: SceneObject = serde_json::from_str(json).unwrap();
        match obj {
            SceneObject::Image(image) => {
                assert_eq!(image.source, "configs/simulation/images/aiko.jpg");
                assert_eq!(image.position, [0.0, 0.5, 3.5]);
                assert_eq!(image.rotation, [0.0, 180.0, 0.0]);
                assert_eq!(image.scale, [2.5, 2.5, 2.5]);
                assert!(!image.interactive);
                assert!(image.visible);
            }
            SceneObject::Cube(_) => panic!("expected image"),
        }
    }

    #[test]
    fn image_object_defaults() {
        let json = r#"{
            "type": "image",
            "source": "assets/waypoint.png",
            "position": [1.0, 1.0, 1.0]
        }"#;
        let obj: SceneObject = serde_json::from_str(json).unwrap();
        match obj {
            SceneObject::Image(image) => {
                assert_eq!(image.rotation, [0.0, 0.0, 0.0]);
                assert_eq!(image.scale, [1.0, 1.0, 1.0]);
                assert!(!image.interactive);
                assert!(image.visible);
            }
            SceneObject::Cube(_) => panic!("expected image"),
        }
    }

    #[test]
    fn basic_arena_environment_stays_generic_with_no_task_specific_image_objects() {
        let config: EnvironmentConfig =
            serde_json::from_str(BASIC_ARENA_ENVIRONMENT_JSON).expect("basic_arena environment.json should parse");

        assert_eq!(config.id, "basic_arena");

        assert!(
            config.image_objects().next().is_none(),
            "basic_arena should declare no image objects - those are task-specific, got: {:?}",
            config.image_objects().map(|i| &i.source).collect::<Vec<_>>()
        );
    }

    #[test]
    fn find_target_task_references_its_cats_preset() {
        let value: serde_json::Value =
            serde_json::from_str(FIND_TARGET_TASK_JSON).expect("find_target/task.json should parse");

        assert_eq!(
            value["preset"], "cats",
            "find_target should reference its 'cats' preset (LAB-3629) rather than authoring objects[] inline"
        );
        assert!(
            value.get("objects").is_none(),
            "find_target/task.json should no longer declare an inline objects[] key"
        );
    }

    #[test]
    fn default_task_references_its_default_preset() {
        let value: serde_json::Value = serde_json::from_str(DEFAULT_TASK_JSON).expect("default/task.json should parse");

        assert_eq!(
            value["env_name"], "basic_arena",
            "default task must declare which environment its 'default' preset resolves against"
        );
        assert_eq!(
            value["preset"], "default",
            "default task should reference its 'default' preset (LAB-3630) rather than authoring objects[] inline"
        );
        assert!(
            value.get("objects").is_none(),
            "default/task.json should not declare an inline objects[] key"
        );
    }

    #[test]
    fn find_target_cats_preset_declares_its_own_image_objects() {
        let root = repo_root();
        let value: serde_json::Value = serde_json::from_str(CATS_PRESET_JSON).expect("preset.json should parse");
        let objects: Vec<SceneObject> =
            serde_json::from_value(value["objects"].clone()).expect("preset.json objects[] should parse");

        let images: Vec<&ImageObject> = objects
            .iter()
            .filter_map(|obj| match obj {
                SceneObject::Image(image) => Some(image),
                SceneObject::Cube(_) => None,
            })
            .collect();

        let aiko = images
            .iter()
            .find(|image| image.source.ends_with("aiko.jpg"))
            .expect("cats preset should declare an aiko.jpg image object");
        let resolved = aiko.validate(&root).expect("aiko image object should validate");
        assert!(resolved.is_file());
        assert_eq!(aiko.position.len(), 3);
        assert_eq!(aiko.rotation.len(), 3);
        assert_eq!(aiko.scale.len(), 3);

        assert!(
            images.iter().any(|image| image.source.ends_with("phoebe.jpg")),
            "cats preset should also declare a phoebe.jpg image object"
        );
    }

    #[test]
    fn parses_image_object_with_motion_block() {
        let json = r#"{
            "type": "image",
            "source": "configs/simulation/images/aiko.jpg",
            "position": [-3.0, 0.5, 0.0],
            "motion": {
                "type": "patrol",
                "axis": "x",
                "range_min": -8.0,
                "range_max": 8.0,
                "speed": 1.0
            }
        }"#;
        let obj: SceneObject = serde_json::from_str(json).unwrap();
        match obj {
            SceneObject::Image(image) => {
                let motion = image.motion.expect("motion block should round-trip");
                assert_eq!(motion.motion_type, MotionType::Patrol);
                assert_eq!(motion.axis, MotionAxis::X);
                assert_eq!(motion.range_min, -8.0);
                assert_eq!(motion.range_max, 8.0);
                assert_eq!(motion.speed, 1.0);
            }
            SceneObject::Cube(_) => panic!("expected image"),
        }
    }

    #[test]
    fn image_object_motion_defaults_to_none_and_speed_defaults_to_one() {
        let no_motion: SceneObject =
            serde_json::from_str(r#"{"type": "image", "source": "assets/waypoint.png", "position": [1.0, 1.0, 1.0]}"#)
                .unwrap();
        match no_motion {
            SceneObject::Image(image) => assert!(image.motion.is_none()),
            SceneObject::Cube(_) => panic!("expected image"),
        }

        let motion_without_speed: SceneObject = serde_json::from_str(
            r#"{
                "type": "image",
                "source": "assets/waypoint.png",
                "position": [1.0, 1.0, 1.0],
                "motion": {"type": "patrol", "axis": "y", "range_min": -2.0, "range_max": 2.0}
            }"#,
        )
        .unwrap();
        match motion_without_speed {
            SceneObject::Image(image) => {
                let motion = image.motion.expect("motion block should round-trip");
                assert_eq!(motion.axis, MotionAxis::Y);
                assert_eq!(motion.speed, 1.0, "speed should default to 1.0 when omitted");
            }
            SceneObject::Cube(_) => panic!("expected image"),
        }
    }

    #[test]
    fn find_target_patrol_task_references_its_objects_patrol_preset() {
        let value: serde_json::Value =
            serde_json::from_str(FIND_TARGET_PATROL_TASK_JSON).expect("find_target_patrol/task.json should parse");
        assert_eq!(
            value["env_name"], "basic_arena",
            "find_target_patrol must reuse basic_arena"
        );
        assert_eq!(
            value["preset"], "objects_patrol",
            "find_target_patrol should reference its 'objects_patrol' preset (LAB-3629) rather than authoring objects[] inline"
        );
        assert!(
            value.get("objects").is_none(),
            "find_target_patrol/task.json should no longer declare an inline objects[] key"
        );
    }

    #[test]
    fn objects_patrol_preset_declares_patrol_motion_on_its_image_objects() {
        let root = repo_root();
        let value: serde_json::Value =
            serde_json::from_str(OBJECTS_PATROL_PRESET_JSON).expect("preset.json should parse");

        let objects: Vec<SceneObject> =
            serde_json::from_value(value["objects"].clone()).expect("preset.json objects[] should parse");

        let images: Vec<&ImageObject> = objects
            .iter()
            .filter_map(|obj| match obj {
                SceneObject::Image(image) => Some(image),
                SceneObject::Cube(_) => None,
            })
            .collect();

        assert!(!images.is_empty(), "find_target_patrol should declare image objects");

        for image in &images {
            // The full `mecha10-templates`-bundled images directory that used to ship every
            // asset these presets reference (dog1.jpg et al.) was deleted along with the rest
            // of `configs/simulation/` (mecha-industries/mecha10#1348) and now lives only in the
            // external `mecha10-assets` repo, unreachable from here - so the on-disk
            // `ImageObject::validate` file-exists check can only still be exercised for the
            // handful of images that happen to also exist as this repo's own trimmed-down dev
            // sample under `configs/simulation/images/` (`aiko.jpg`/`phoebe.jpg`). Every other
            // image's motion contract is still fully checked below; only the file-exists check
            // is skipped for it.
            if image.source.ends_with("aiko.jpg") || image.source.ends_with("phoebe.jpg") {
                let resolved = image
                    .validate(&root)
                    .expect("patrol image object with a locally-available asset should validate");
                assert!(resolved.is_file());
            }

            let motion = image
                .motion
                .as_ref()
                .unwrap_or_else(|| panic!("{} should declare a motion block", image.source));
            assert_eq!(motion.motion_type, MotionType::Patrol);
            assert_eq!(motion.axis, MotionAxis::X);
            assert!(
                motion.range_min < motion.range_max,
                "range_min should be less than range_max for {}",
                image.source
            );
            // basic_arena is a 20x20m room with 0.5m-thick walls (half-extent 10, wall
            // half-thickness 0.25) - the patrol range must stay clear of both walls.
            assert!(motion.range_min > -9.75 && motion.range_max < 9.75);
        }
    }

    #[test]
    fn moving_objects_arena_declares_patrolling_image_objects_with_no_static_obstacles() {
        let root = repo_root();
        let config: EnvironmentConfig = serde_json::from_str(MOVING_OBJECTS_ARENA_ENVIRONMENT_JSON)
            .expect("moving_objects_arena environment.json should parse");

        assert_eq!(config.id, "moving_objects_arena");

        let images: Vec<&ImageObject> = config.image_objects().collect();
        assert!(
            images.len() >= 2,
            "moving_objects_arena should declare at least two moving image objects, got {}",
            images.len()
        );

        for image in &images {
            let resolved = image
                .validate(&root)
                .unwrap_or_else(|e| panic!("{} should validate: {e}", image.source));
            assert!(resolved.is_file());

            let motion = image
                .motion
                .as_ref()
                .unwrap_or_else(|| panic!("{} should declare a motion block", image.source));
            assert_eq!(motion.motion_type, MotionType::Patrol);
            assert!(
                motion.range_min < motion.range_max,
                "range_min should be less than range_max for {}",
                image.source
            );
            // 20x20m room with 0.5m-thick walls (half-extent 10, wall half-thickness 0.25) - the
            // patrol range must stay clear of both walls.
            assert!(motion.range_min > -9.75 && motion.range_max < 9.75);
        }

        assert!(
            config
                .features
                .obstacles
                .as_ref()
                .map_or(true, |obstacles| obstacles.count == 0),
            "moving_objects_arena should have no static obstacles cluttering the moving-target test"
        );
    }

    #[test]
    fn validate_rejects_missing_source_file() {
        let root = repo_root();
        let image = ImageObject {
            source: "configs/simulation/images/does_not_exist.jpg".to_string(),
            position: [0.0, 0.0, 0.0],
            rotation: [0.0, 0.0, 0.0],
            scale: [1.0, 1.0, 1.0],
            interactive: false,
            visible: true,
            motion: None,
        };
        let err = image
            .validate(&root)
            .expect_err("missing source file should fail validation");
        assert!(err.to_string().contains("does not resolve to a file"));
    }

    /// Minimal document satisfying every field the hand-written schema marks `required`.
    fn minimal_environment_json() -> serde_json::Value {
        serde_json::json!({
            "id": "basic_arena",
            "version": "1.0.0",
            "name": "Basic Arena",
            "description": "A test arena",
            "scene_path": "res://basic_arena.tscn",
            "dimensions": {"width": 20.0, "length": 20.0, "height": 3.0, "unit": "meters"},
            "features": {}
        })
    }

    #[test]
    fn parses_a_minimal_valid_environment_config() {
        let config: EnvironmentConfig = serde_json::from_value(minimal_environment_json()).unwrap();
        assert_eq!(config.scene_path, "res://basic_arena.tscn");
        assert_eq!(config.dimensions.width, 20.0);
        assert_eq!(config.dimensions.unit, DistanceUnit::Meters);
        assert!(config.features.floor.is_none());
    }

    #[test]
    fn rejects_environment_config_missing_scene_path() {
        let mut value = minimal_environment_json();
        value.as_object_mut().unwrap().remove("scene_path");
        let err = serde_json::from_value::<EnvironmentConfig>(value).unwrap_err();
        assert!(err.to_string().contains("scene_path"), "{err}");
    }

    #[test]
    fn rejects_environment_config_missing_dimensions() {
        let mut value = minimal_environment_json();
        value.as_object_mut().unwrap().remove("dimensions");
        let err = serde_json::from_value::<EnvironmentConfig>(value).unwrap_err();
        assert!(err.to_string().contains("dimensions"), "{err}");
    }

    #[test]
    fn rejects_malformed_floor_feature() {
        let mut value = minimal_environment_json();
        value["features"]["floor"] = serde_json::json!({
            "type": "flat",
            "material": "concrete",
            "friction": 0.8
        });
        let err = serde_json::from_value::<EnvironmentConfig>(value).unwrap_err();
        assert!(err.to_string().contains("collision"), "{err}");
    }

    #[test]
    fn parses_full_basic_arena_environment_including_dimensions_and_features() {
        let config: EnvironmentConfig =
            serde_json::from_str(BASIC_ARENA_ENVIRONMENT_JSON).expect("basic_arena environment.json should parse");

        assert_eq!(
            config.scene_path,
            "res://packages/mecha10-templates/templates/configs/simulation/environments/basic_arena/basic_arena.tscn"
        );
        assert_eq!(config.dimensions.unit, DistanceUnit::Meters);

        let floor = config.features.floor.expect("basic_arena should declare a floor");
        assert_eq!(floor.material, "concrete");
        assert!(floor.collision);

        let walls = config.features.walls.expect("basic_arena should declare walls");
        assert_eq!(walls.count, 4);

        let lighting = config.features.lighting.expect("basic_arena should declare lighting");
        assert!(lighting.directional.enabled);
        assert!(lighting.ambient.enabled);

        let spawn_points = config
            .features
            .spawn_points
            .expect("basic_arena should declare spawn points");
        assert_eq!(spawn_points.count, 5);
        assert_eq!(spawn_points.positions.len(), 5);

        let obstacles = config.features.obstacles.expect("basic_arena should declare obstacles");
        assert_eq!(obstacles.obstacle_type, "mixed");

        let goals = config.features.goals.expect("basic_arena should declare goals");
        assert_eq!(goals.count, 0);

        let npcs = config.features.npcs.expect("basic_arena should declare npcs");
        assert!(!npcs.enabled);
    }

    #[test]
    fn home_outdoor_urban_environment_stays_generic_with_no_task_specific_image_objects() {
        let config: EnvironmentConfig = serde_json::from_str(HOME_OUTDOOR_URBAN_ENVIRONMENT_JSON)
            .expect("home_outdoor_urban environment.json should parse");

        assert_eq!(config.id, "home_outdoor_urban");

        assert!(
            config.image_objects().next().is_none(),
            "home_outdoor_urban should declare no image objects - those are task-specific, got: {:?}",
            config.image_objects().map(|i| &i.source).collect::<Vec<_>>()
        );
    }

    #[test]
    fn every_bundled_environment_is_structural_only_except_the_tracked_moving_objects_arena_exception() {
        // Environments model ground/walls/lighting/obstacles, not task content - `cat_environment`
        // violated this by baking cat image billboards directly into `environment.json` (LAB-3628)
        // and was deleted for it. This test used to walk every environment bundled under
        // `templates/configs/simulation/environments` on disk so a future environment couldn't
        // reintroduce the same mistake without this test catching it.
        //
        // That directory was extracted to the external `mecha10-assets` repo and deleted from
        // here (mecha-industries/mecha10#1348), so this repo can no longer discover "every
        // bundled environment" by listing a local directory - `mecha10-assets` is the new
        // source of truth and isn't readable from this crate. This test is downgraded to
        // checking the known, hand-maintained fixtures above (`BASIC_ARENA_ENVIRONMENT_JSON`,
        // `HOME_OUTDOOR_URBAN_ENVIRONMENT_JSON`) rather than silently dropped - it still catches
        // a regression on either of those two, but can no longer catch a *new* environment
        // added directly to `mecha10-assets` smuggling in task-specific image objects. That gap
        // is real and not covered by any test in this repo any more.
        //
        // `moving_objects_arena` is a known, tracked exception (see its own
        // `moving_objects_arena_declares_patrolling_image_objects_with_no_static_obstacles` test
        // above and the sibling issue to migrate it off baked-in image objects) - it is
        // deliberately excluded here rather than silently allowed to multiply.
        let mut checked = Vec::new();
        for (name, fixture) in [
            ("basic_arena", BASIC_ARENA_ENVIRONMENT_JSON),
            ("home_outdoor_urban", HOME_OUTDOOR_URBAN_ENVIRONMENT_JSON),
        ] {
            let config: EnvironmentConfig =
                serde_json::from_str(fixture).unwrap_or_else(|e| panic!("{name} should parse: {e}"));
            assert!(
                config.image_objects().next().is_none(),
                "{} should declare no image objects - environments are structural-only, task \
                 content belongs in task.json, got: {:?}",
                name,
                config.image_objects().map(|i| &i.source).collect::<Vec<_>>()
            );
            checked.push(name.to_string());
        }

        assert!(
            checked.contains(&"basic_arena".to_string()) && checked.contains(&"home_outdoor_urban".to_string()),
            "expected to have actually checked the known structural-only environments, got: {checked:?}"
        );
    }

    #[test]
    fn parses_full_home_outdoor_urban_environment_including_dimensions_and_features() {
        let config: EnvironmentConfig = serde_json::from_str(HOME_OUTDOOR_URBAN_ENVIRONMENT_JSON)
            .expect("home_outdoor_urban environment.json should parse");

        assert_eq!(
            config.scene_path,
            "res://packages/mecha10-templates/templates/configs/simulation/environments/home_outdoor_urban/home_outdoor_urban.tscn"
        );
        assert_eq!(config.dimensions.unit, DistanceUnit::Meters);

        // Bigger than basic_arena (20x20) - this environment needs room for
        // a partitioned home interior *and* a separate outdoor urban street section.
        assert!(config.dimensions.width > 20.0);
        assert!(config.dimensions.length > 0.0);

        let floor = config
            .features
            .floor
            .expect("home_outdoor_urban should declare a floor");
        assert!(floor.collision);

        let walls = config.features.walls.expect("home_outdoor_urban should declare walls");
        assert_eq!(walls.count, 4);

        let lighting = config
            .features
            .lighting
            .expect("home_outdoor_urban should declare lighting");
        assert!(lighting.directional.enabled);
        assert!(lighting.ambient.enabled);

        let spawn_points = config
            .features
            .spawn_points
            .expect("home_outdoor_urban should declare spawn points");
        assert_eq!(spawn_points.count, spawn_points.positions.len() as u32);
        assert!(
            spawn_points.count >= 2,
            "home_outdoor_urban should offer spawn points in both the home and outdoor sections"
        );

        let goals = config.features.goals.expect("home_outdoor_urban should declare goals");
        assert!(
            goals.count > 0,
            "a navigation-focused environment should declare goal zones"
        );

        let npcs = config.features.npcs.expect("home_outdoor_urban should declare npcs");
        assert!(npcs.enabled, "home_outdoor_urban should model dynamic pedestrians");

        // Dense obstacle layout (interior partition walls + furniture + street furniture) is the
        // whole point of this environment - planning/navigation needs more to avoid than the
        // open basic_arena provides.
        assert!(
            config.features.objects.len() >= 10,
            "home_outdoor_urban should be densely furnished for navigation testing, got {} objects",
            config.features.objects.len()
        );
        assert!(
            config
                .features
                .objects
                .iter()
                .all(|obj| matches!(obj, SceneObject::Cube(_))),
            "home_outdoor_urban's structural/furniture objects should all be cubes, not task-specific images"
        );
    }

    #[test]
    fn validate_rejects_zero_scale() {
        let root = repo_root();
        let image = ImageObject {
            source: "configs/simulation/images/aiko.jpg".to_string(),
            position: [0.0, 0.0, 0.0],
            rotation: [0.0, 0.0, 0.0],
            scale: [0.0, 1.0, 1.0],
            interactive: false,
            visible: true,
            motion: None,
        };
        let err = image.validate(&root).expect_err("zero scale should fail validation");
        assert!(err.to_string().contains("scale"));
    }
}