dreamwell-engine 1.0.0

// Particle input domain — procedurally driven particle cloud character controller.
//
// The particle controller is a first-class input domain alongside humanoid.
// It requires no FBX animations — the cloud shape is driven by velocity,
// acceleration, and locomotion state via pure math.
//
// Clean Compute: all state is inline [f32] arrays. Zero allocation per frame.

/// Particle locomotion state — drives the cloud shape procedurally.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ParticleLocomotion {
    /// Tight sphere, particles close together. Player is stationary.
    #[default]
    Idle,
    /// Stretched ellipsoid in movement direction. Player is walking/running.
    Moving,
    /// Expanded sphere, particles spread out. Player is jumping/ascending.
    Jumping,
    /// Compressed disc, particles flatten. Player just landed.
    Landing,
    /// Elongated stream, particles trail behind. Player is sprinting.
    Sprinting,
}

impl ParticleLocomotion {
    /// Shape scale multipliers for the cloud [x_stretch, y_stretch, z_stretch, radius_scale].
    /// Applied to the base sphere distribution to produce the locomotion-appropriate shape.
    pub fn shape_params(self) -> ParticleShapeParams {
        match self {
            Self::Idle => ParticleShapeParams {
                stretch: [1.0, 1.0, 1.0],
                radius_scale: 1.0,
                particle_scale: 0.08,
                noise_amplitude: 0.06,
            },
            Self::Moving => ParticleShapeParams {
                stretch: [1.0, 0.9, 1.3],
                radius_scale: 1.2,
                particle_scale: 0.07,
                noise_amplitude: 0.10,
            },
            Self::Jumping => ParticleShapeParams {
                stretch: [1.2, 1.5, 1.2],
                radius_scale: 1.5,
                particle_scale: 0.06,
                noise_amplitude: 0.14,
            },
            Self::Landing => ParticleShapeParams {
                stretch: [1.5, 0.5, 1.5],
                radius_scale: 1.3,
                particle_scale: 0.09,
                noise_amplitude: 0.08,
            },
            Self::Sprinting => ParticleShapeParams {
                stretch: [0.8, 0.85, 1.8],
                radius_scale: 1.4,
                particle_scale: 0.06,
                noise_amplitude: 0.12,
            },
        }
    }

    pub fn label(self) -> &'static str {
        match self {
            Self::Idle => "Idle",
            Self::Moving => "Moving",
            Self::Jumping => "Jumping",
            Self::Landing => "Landing",
            Self::Sprinting => "Sprinting",
        }
    }
}

/// Shape parameters for the particle cloud at a given locomotion state.
#[derive(Debug, Clone, Copy)]
pub struct ParticleShapeParams {
    /// Axis stretch multipliers [x, y, z] applied to sphere offsets.
    pub stretch: [f32; 3],
    /// Overall radius multiplier (1.0 = base radius).
    pub radius_scale: f32,
    /// Per-particle visual scale.
    pub particle_scale: f32,
    /// Noise amplitude for organic movement.
    pub noise_amplitude: f32,
}

// ═══════════════════════════════════════════════════════════════════
// Wave Formation System — real wave mathematics for particle positions.
//
// Moving: particles form a traveling wave surface (fabric in wind).
//   y(x, z, t) = A · sin(k·x - ω·t) · cos(k·z)
//   where k = 2π/λ (wave number), ω = 2π·f (angular frequency)
//
// Idle: particles decohere from wave into Fibonacci phyllotaxis disc.
//   Uses golden angle θ = 2π/φ² placement with exponential radius growth.
//   Transition from wave → disc uses Lindblad kernel: blend = exp(-Γ·t_idle).
// ═══════════════════════════════════════════════════════════════════

/// Per-particle wave formation state. Pre-allocated, updated every frame.
/// Drives the visual shape of the particle using real wave equation math.
#[derive(Clone)]
pub struct WaveFormationState {
    /// Cumulative phase time (seconds). Drives ω·t in the wave equation.
    pub phase_time: f32,
    /// Time spent in current idle (seconds). Drives idle→Fibonacci decoherence.
    pub idle_time: f32,
    /// Blend from wave(0.0) to Fibonacci(1.0). Uses exp(-Γ·t_idle).
    pub fibonacci_blend: f32,
    /// Wave amplitude A. Scales with velocity for weighty feel.
    pub amplitude: f32,
    /// Wave frequency f (Hz). Higher = faster ripple.
    pub frequency: f32,
    /// Wavelength λ. Controls spatial density of ripples.
    pub wavelength: f32,
    /// Heading direction [x, z] normalized. Wave propagates along this axis.
    pub heading: [f32; 2],
    /// Pre-computed particle offsets for current frame. Reused by GPU upload.
    pub offsets: Vec<[f32; 3]>,
}

impl WaveFormationState {
    pub fn new(particle_count: u32) -> Self {
        Self {
            phase_time: 0.0,
            idle_time: 0.0,
            fibonacci_blend: 0.0,
            amplitude: 0.3,
            frequency: 2.0,
            wavelength: 1.5,
            heading: [0.0, 1.0],
            offsets: vec![[0.0; 3]; particle_count as usize],
        }
    }

    /// Update wave formation from controller state.
    /// `speed`: current movement speed (0 = idle).
    /// `heading`: normalized [x, z] movement direction.
    /// `dt`: frame delta time.
    pub fn update(&mut self, speed: f32, heading: [f32; 2], yaw: f32, dt: f32, particle_count: u32, radius: f32) {
        self.phase_time += dt;
        let moving = speed > 0.5;

        if moving {
            // Reset idle decoherence when moving.
            self.idle_time = 0.0;
            // Wave amplitude scales with speed for weighty feel.
            // Clamp to prevent extreme distortion.
            self.amplitude = (speed * 0.06).clamp(0.1, 0.5);
            self.heading = if heading[0].abs() + heading[1].abs() > 0.01 {
                heading
            } else {
                [yaw.sin(), yaw.cos()]
            };
            // Fibonacci blend decays toward 0 (wave form) using exponential.
            self.fibonacci_blend *= (-6.0 * dt).exp(); // fast re-wave
        } else {
            // Idle: decohere into Fibonacci disc.
            self.idle_time += dt;
            // Lindblad kernel: fibonacci_blend approaches 1.0 exponentially.
            // Rate Γ = 2.0: gentle formation over ~1.5 seconds.
            self.fibonacci_blend = 1.0 - (-2.0 * self.idle_time).exp();
            // Dampen wave amplitude toward 0 for smooth settling.
            self.amplitude *= (-3.0 * dt).exp();
        }

        // Generate per-particle positions.
        let n = particle_count as usize;
        if self.offsets.len() != n {
            self.offsets.resize(n, [0.0; 3]);
        }

        let k = std::f32::consts::TAU / self.wavelength; // wave number
        let omega = std::f32::consts::TAU * self.frequency; // angular frequency
        let t = self.phase_time;
        let a = self.amplitude;
        let golden_angle = std::f32::consts::TAU / (((1.0 + 5.0f32.sqrt()) / 2.0) * ((1.0 + 5.0f32.sqrt()) / 2.0));
        let fib_blend = self.fibonacci_blend.clamp(0.0, 1.0);

        for i in 0..n {
            let frac = (i as f32 + 0.5) / n as f32;

            // ── Traveling Wave Formation ──
            // Particles on a rectangular grid, displaced by wave equation.
            // Grid: sqrt(N) × sqrt(N) in the heading-perpendicular plane.
            let grid_side = (n as f32).sqrt().ceil() as usize;
            let gx = (i % grid_side) as f32 / grid_side as f32 - 0.5;
            let gz = (i / grid_side) as f32 / grid_side as f32 - 0.5;

            // Rotate grid to align with heading direction.
            let hx = self.heading[0];
            let hz = self.heading[1];
            let world_x = gx * hz - gz * hx; // perpendicular to heading
            let world_z = gx * hx + gz * hz; // along heading

            // Wave equation: y = A · sin(k·along - ω·t) · cos(k·perp × 0.5)
            // The cos term creates a natural tapering at the edges.
            let wave_y = a * (k * world_z * radius * 2.0 - omega * t).sin() * (k * world_x * radius * 0.5).cos();

            let wave_pos = [world_x * radius * 2.0, wave_y, world_z * radius * 2.0];

            // ── Fibonacci Phyllotaxis Disc ──
            // Golden angle spiral on a flat disc. Radius grows as sqrt(i).
            let fib_r = frac.sqrt() * radius * 1.2;
            let fib_theta = i as f32 * golden_angle + t * 0.3; // slow rotation
            let fib_pos = [
                fib_r * fib_theta.cos(),
                a * 0.1 * (fib_theta * 3.0 + t).sin(), // gentle vertical bob
                fib_r * fib_theta.sin(),
            ];

            // ── Blend: wave → fibonacci using decoherence kernel ──
            self.offsets[i] = [
                wave_pos[0] * (1.0 - fib_blend) + fib_pos[0] * fib_blend,
                wave_pos[1] * (1.0 - fib_blend) + fib_pos[1] * fib_blend,
                wave_pos[2] * (1.0 - fib_blend) + fib_pos[2] * fib_blend,
            ];
        }
    }
}

/// Particle controller state — owns position, velocity, and locomotion.
/// Updated per frame from input, drives the particle cloud shape.
pub struct ParticleController {
    /// World-space center of the particle.
    pub position: [f32; 3],
    /// Previous frame position (GPU derives anchor velocity).
    pub previous_position: [f32; 3],
    /// Current velocity (m/s).
    pub velocity: [f32; 3],
    /// Movement speed (m/s).
    pub move_speed: f32,
    /// Sprint speed multiplier.
    pub sprint_multiplier: f32,
    /// Current locomotion state.
    pub locomotion: ParticleLocomotion,
    /// Gravity (m/s²).
    pub gravity: f32,
    /// Whether the particle is on the ground.
    pub grounded: bool,
    /// Time since last landing (seconds) — used for landing squash duration.
    pub landing_timer: f32,
    /// Facing direction (yaw in radians, 0 = +Z).
    pub facing_yaw: f32,
    /// Cloud base radius (meters).
    pub cloud_radius: f32,
    /// Number of particles in the particle.
    pub particle_count: u32,
    /// Base particle color [r, g, b, a].
    pub base_color: [f32; 4],
    /// Normalized world-space movement direction (from WASD+yaw).
    pub movement_force_direction: [f32; 3],
    /// Movement force magnitude: 0=idle, move_speed=walk, sprint=sprint.
    pub movement_force_magnitude: f32,
    /// Current rheology blend (smooth interpolation toward target, 8/sec exponential).
    pub rheology_blend: f32,
    /// Rheology target per locomotion state.
    pub rheology_target: f32,
    /// Wave formation state — real wave math for particle positions.
    pub wave_formation: WaveFormationState,
}

impl Default for ParticleController {
    fn default() -> Self {
        Self {
            position: [0.0, 1.0, 0.0],
            previous_position: [0.0, 1.0, 0.0],
            velocity: [0.0; 3],
            move_speed: 5.0,
            sprint_multiplier: 2.0,
            locomotion: ParticleLocomotion::Idle,
            gravity: 1.2,
            grounded: true,
            landing_timer: 0.0,
            facing_yaw: 0.0,
            cloud_radius: 0.8,
            particle_count: 256,
            base_color: [0.4, 0.6, 1.0, 0.85],
            movement_force_direction: [0.0; 3],
            movement_force_magnitude: 0.0,
            rheology_blend: 0.15,
            rheology_target: 0.15,
            wave_formation: WaveFormationState::new(256),
        }
    }
}

impl ParticleController {
    pub fn new(position: [f32; 3], particle_count: u32) -> Self {
        Self {
            position,
            particle_count,
            wave_formation: WaveFormationState::new(particle_count),
            ..Default::default()
        }
    }

    /// Update the particle from WASD input relative to camera yaw.
    /// Returns true if the particle moved this frame.
    pub fn update(
        &mut self,
        forward: bool,
        back: bool,
        left: bool,
        right: bool,
        jump: bool,
        sprint: bool,
        camera_yaw: f32,
        dt: f32,
    ) -> bool {
        // Store previous position before update (GPU derives anchor velocity).
        self.previous_position = self.position;

        // Compute movement direction from input in view-local space.
        let mut dir_fwd = 0.0f32;
        let mut dir_right = 0.0f32;
        if forward {
            dir_fwd += 1.0;
        }
        if back {
            dir_fwd -= 1.0;
        }
        if left {
            dir_right -= 1.0;
        }
        if right {
            dir_right += 1.0;
        }

        let len = (dir_fwd * dir_fwd + dir_right * dir_right).sqrt();
        let moving = len > 0.001;

        if moving {
            dir_fwd /= len;
            dir_right /= len;
        }

        // Rotate view-local input to world space using camera yaw.
        let cos_yaw = camera_yaw.cos();
        let sin_yaw = camera_yaw.sin();
        let world_x = dir_fwd * (-cos_yaw) + dir_right * sin_yaw;
        let world_z = dir_fwd * (-sin_yaw) + dir_right * (-cos_yaw);

        // Apply speed
        let speed = if sprint {
            self.move_speed * self.sprint_multiplier
        } else {
            self.move_speed
        };
        self.velocity[0] = if moving { world_x * speed } else { 0.0 };
        self.velocity[2] = if moving { world_z * speed } else { 0.0 };

        // Gravity + jump
        if !self.grounded {
            self.velocity[1] -= self.gravity * dt;
        } else if jump {
            self.velocity[1] = 3.5;
            self.grounded = false;
        }

        // Apply velocity
        self.position[0] += self.velocity[0] * dt;
        self.position[1] += self.velocity[1] * dt;
        self.position[2] += self.velocity[2] * dt;

        // Ground collision at Y=0
        let was_airborne = !self.grounded;
        if self.position[1] <= 0.5 {
            self.position[1] = 0.5;
            self.velocity[1] = 0.0;
            self.grounded = true;
            if was_airborne {
                self.landing_timer = 0.3;
            }
        }

        // Update facing
        if moving {
            self.facing_yaw = world_z.atan2(world_x);
        }

        // Update locomotion state
        self.landing_timer = (self.landing_timer - dt).max(0.0);
        self.locomotion = if self.landing_timer > 0.0 {
            ParticleLocomotion::Landing
        } else if !self.grounded {
            ParticleLocomotion::Jumping
        } else if sprint && moving {
            ParticleLocomotion::Sprinting
        } else if moving {
            ParticleLocomotion::Moving
        } else {
            ParticleLocomotion::Idle
        };

        // Update movement force direction and magnitude for GPU force field.
        if moving {
            self.movement_force_direction = [world_x, 0.0, world_z];
            self.movement_force_magnitude = speed;
        } else {
            self.movement_force_direction = [0.0; 3];
            self.movement_force_magnitude = 0.0;
        }

        // Update rheology: smooth exponential interpolation toward target (8/sec).
        self.rheology_target = match self.locomotion {
            ParticleLocomotion::Idle => 0.15,
            ParticleLocomotion::Moving => 0.5,
            ParticleLocomotion::Sprinting => 0.7,
            ParticleLocomotion::Jumping => 0.1,
            ParticleLocomotion::Landing => 0.6,
        };
        let blend_rate = 1.0 - (-8.0 * dt).exp();
        self.rheology_blend += (self.rheology_target - self.rheology_blend) * blend_rate;

        // Update wave formation: traveling wave when moving, Fibonacci disc when idle.
        let speed_mag = (self.velocity[0] * self.velocity[0] + self.velocity[2] * self.velocity[2]).sqrt();
        let heading = if speed_mag > 0.01 {
            [self.velocity[0] / speed_mag, self.velocity[2] / speed_mag]
        } else {
            [0.0, 0.0]
        };
        self.wave_formation.update(
            speed_mag,
            heading,
            self.facing_yaw,
            dt,
            self.particle_count,
            self.cloud_radius,
        );

        moving
    }

    /// Get wave formation particle offsets (relative to particle center).
    /// These are the real wave-equation-driven positions for GPU upload.
    pub fn wave_offsets(&self) -> &[[f32; 3]] {
        &self.wave_formation.offsets
    }

    /// Get the current shape parameters for the particle cloud.
    pub fn shape_params(&self) -> ParticleShapeParams {
        self.locomotion.shape_params()
    }
}

/// Generate sphere-distributed offsets using the golden ratio spiral.
/// Deterministic — same input always produces the same output.
/// Returns `count` unit-sphere offsets that are then scaled by radius + shape params.
pub fn particle_sphere_offsets(count: u32) -> Vec<[f32; 3]> {
    let golden_ratio = (1.0 + 5.0f32.sqrt()) / 2.0;
    let angle_increment = std::f32::consts::TAU * golden_ratio;
    let mut offsets = Vec::with_capacity(count as usize);

    for i in 0..count {
        let t = (i as f32 + 0.5) / count as f32;
        let phi = (1.0 - 2.0 * t).acos();
        let theta = angle_increment * i as f32;

        let x = phi.sin() * theta.cos();
        let y = phi.cos();
        let z = phi.sin() * theta.sin();
        offsets.push([x, y, z]);
    }

    offsets
}

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

    #[test]
    fn golden_spiral_produces_correct_count() {
        let pts = particle_sphere_offsets(128);
        assert_eq!(pts.len(), 128);
        // All points should be on the unit sphere (length ≈ 1.0)
        for p in &pts {
            let len = (p[0] * p[0] + p[1] * p[1] + p[2] * p[2]).sqrt();
            assert!((len - 1.0).abs() < 0.01, "point not on unit sphere: len={len}");
        }
    }

    #[test]
    fn particle_locomotion_transitions() {
        let mut ctrl = ParticleController::default();
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Idle);

        // Move forward
        ctrl.update(true, false, false, false, false, false, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Moving);

        // Sprint
        ctrl.update(true, false, false, false, false, true, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Sprinting);

        // Stop
        ctrl.update(false, false, false, false, false, false, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Idle);
    }

    #[test]
    fn particle_jump_and_land() {
        let mut ctrl = ParticleController::default();
        ctrl.position = [0.0, 0.5, 0.0];

        // Jump
        ctrl.update(false, false, false, false, true, false, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Jumping);
        assert!(!ctrl.grounded);

        // Fall back to ground (simulate many frames — needs more with low gravity)
        for _ in 0..400 {
            ctrl.update(false, false, false, false, false, false, 0.0, 0.016);
        }
        assert!(ctrl.grounded);
        // Should be landing or idle after settling
        assert!(ctrl.locomotion == ParticleLocomotion::Idle || ctrl.locomotion == ParticleLocomotion::Landing);
    }

    #[test]
    fn shape_params_vary_by_state() {
        let idle = ParticleLocomotion::Idle.shape_params();
        let moving = ParticleLocomotion::Moving.shape_params();
        assert!(idle.radius_scale < moving.radius_scale);
        assert!(idle.noise_amplitude < moving.noise_amplitude);
    }

    // ── ParticleController state tracking tests ────────────────────────────

    #[test]
    fn particle_controller_previous_position_stored() {
        let mut ctrl = ParticleController::new([3.0, 1.0, -2.0], 128);
        let pos_before = ctrl.position;

        // Move forward — position changes, previous_position should be the old value.
        ctrl.update(true, false, false, false, false, false, 0.0, 0.016);
        assert_eq!(
            ctrl.previous_position, pos_before,
            "previous_position should equal position before update"
        );
        // Position itself should have changed (moving forward with nonzero speed).
        assert_ne!(ctrl.position, pos_before, "position should change when moving forward");
    }

    #[test]
    fn particle_controller_force_direction_when_moving() {
        let mut ctrl = ParticleController::default();
        ctrl.update(true, false, false, false, false, false, 0.0, 0.016);

        let dir = ctrl.movement_force_direction;
        let len = (dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2]).sqrt();
        assert!(
            len > 0.001,
            "movement_force_direction should be nonzero when moving, got length {}",
            len
        );
    }

    #[test]
    fn particle_controller_force_direction_when_idle() {
        let mut ctrl = ParticleController::default();
        // No movement input.
        ctrl.update(false, false, false, false, false, false, 0.0, 0.016);

        assert_eq!(
            ctrl.movement_force_magnitude, 0.0,
            "movement_force_magnitude should be 0 when idle"
        );
        assert_eq!(
            ctrl.movement_force_direction, [0.0; 3],
            "movement_force_direction should be zero when idle"
        );
    }

    #[test]
    fn particle_controller_rheology_idle_target() {
        let mut ctrl = ParticleController::default();
        ctrl.update(false, false, false, false, false, false, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Idle);
        assert!(
            (ctrl.rheology_target - 0.15).abs() < 1e-5,
            "idle rheology_target should be 0.15, got {}",
            ctrl.rheology_target
        );
    }

    #[test]
    fn particle_controller_rheology_sprinting_target() {
        let mut ctrl = ParticleController::default();
        ctrl.update(true, false, false, false, false, true, 0.0, 0.016);
        assert_eq!(ctrl.locomotion, ParticleLocomotion::Sprinting);
        assert!(
            (ctrl.rheology_target - 0.7).abs() < 1e-5,
            "sprinting rheology_target should be 0.7, got {}",
            ctrl.rheology_target
        );
    }

    #[test]
    fn particle_controller_rheology_blend_approaches_target() {
        let mut ctrl = ParticleController::default();
        // Start at idle default (0.15), switch to sprinting (target 0.7).
        for _ in 0..600 {
            ctrl.update(true, false, false, false, false, true, 0.0, 0.016);
        }
        // After many frames at 8/sec exponential, blend should be close to 0.7.
        assert!(
            (ctrl.rheology_blend - ctrl.rheology_target).abs() < 0.01,
            "after 600 frames, rheology_blend ({}) should approach target ({})",
            ctrl.rheology_blend,
            ctrl.rheology_target
        );
    }

    #[test]
    fn particle_controller_default_particle_count_256() {
        let ctrl = ParticleController::default();
        assert_eq!(
            ctrl.particle_count, 256,
            "default particle_count should be 256, got {}",
            ctrl.particle_count
        );
    }

    #[test]
    fn particle_controller_default_cloud_radius_08() {
        let ctrl = ParticleController::default();
        assert!(
            (ctrl.cloud_radius - 0.8).abs() < 1e-5,
            "default cloud_radius should be 0.8, got {}",
            ctrl.cloud_radius
        );
    }
}