dreamwell_engine/input/

frame.rs

// InputFrame — per-frame input snapshot consumed by game logic.
// The exchange currency between platform adapters and game systems.
// Produced once per frame by the input system, consumed by movement, combat, UI, etc.

use super::action::InputAction;

/// Per-frame input snapshot. Immutable once built. Consumed by game systems.
///
/// Separates input collection (platform-specific) from input consumption (game logic).
/// Adapters write to InputFrameBuilder, then finalize to InputFrame.
#[derive(Debug, Clone)]
pub struct InputFrame {
    /// Actions active this frame (just pressed or held).
    pub actions: Vec<InputAction>,

    /// Movement vector: [x, y] in [-1, 1]. Composite of WASD/stick/dpad.
    /// x: negative=left, positive=right. y: negative=backward, positive=forward.
    pub movement: [f32; 2],

    /// Camera look delta: [dx, dy] in pixels or normalized units.
    /// dx: negative=look left, positive=look right.
    /// dy: negative=look up, positive=look down.
    pub look_delta: [f32; 2],

    /// Scroll wheel delta (positive=zoom in / scroll up).
    pub scroll_delta: f32,

    /// Cursor position in window coordinates [x, y].
    pub cursor_position: [f32; 2],

    /// Cursor delta since last frame [dx, dy].
    pub cursor_delta: [f32; 2],

    /// Frame timestamp (monotonic, seconds since start).
    pub timestamp: f32,
}

impl InputFrame {
    /// Whether a specific action is active this frame.
    pub fn has_action(&self, action: InputAction) -> bool {
        self.actions.contains(&action)
    }

    /// Whether any movement input is present.
    pub fn has_movement(&self) -> bool {
        self.movement[0] != 0.0 || self.movement[1] != 0.0
    }

    /// Whether any look/rotation input is present.
    pub fn has_look(&self) -> bool {
        self.look_delta[0] != 0.0 || self.look_delta[1] != 0.0
    }

    /// Whether any scroll input is present.
    pub fn has_scroll(&self) -> bool {
        self.scroll_delta != 0.0
    }
}

impl Default for InputFrame {
    fn default() -> Self {
        Self {
            actions: Vec::new(),
            movement: [0.0; 2],
            look_delta: [0.0; 2],
            scroll_delta: 0.0,
            cursor_position: [0.0; 2],
            cursor_delta: [0.0; 2],
            timestamp: 0.0,
        }
    }
}

/// Builder for constructing an InputFrame. Used by platform adapters.
pub struct InputFrameBuilder {
    actions: Vec<InputAction>,
    movement: [f32; 2],
    look_delta: [f32; 2],
    scroll_delta: f32,
    cursor_position: [f32; 2],
    cursor_delta: [f32; 2],
    timestamp: f32,
}

impl InputFrameBuilder {
    pub fn new(timestamp: f32) -> Self {
        Self {
            actions: Vec::new(),
            movement: [0.0; 2],
            look_delta: [0.0; 2],
            scroll_delta: 0.0,
            cursor_position: [0.0; 2],
            cursor_delta: [0.0; 2],
            timestamp,
        }
    }

    /// Add an action to the frame.
    pub fn action(mut self, action: InputAction) -> Self {
        if !self.actions.contains(&action) {
            self.actions.push(action);
        }
        self
    }

    /// Set movement vector.
    pub fn movement(mut self, x: f32, y: f32) -> Self {
        self.movement = [x, y];
        self
    }

    /// Set look delta.
    pub fn look(mut self, dx: f32, dy: f32) -> Self {
        self.look_delta = [dx, dy];
        self
    }

    /// Set scroll delta.
    pub fn scroll(mut self, delta: f32) -> Self {
        self.scroll_delta = delta;
        self
    }

    /// Set cursor position.
    pub fn cursor(mut self, x: f32, y: f32) -> Self {
        self.cursor_position = [x, y];
        self
    }

    /// Set cursor delta.
    pub fn cursor_delta(mut self, dx: f32, dy: f32) -> Self {
        self.cursor_delta = [dx, dy];
        self
    }

    /// Finalize into an immutable InputFrame.
    pub fn build(self) -> InputFrame {
        InputFrame {
            actions: self.actions,
            movement: self.movement,
            look_delta: self.look_delta,
            scroll_delta: self.scroll_delta,
            cursor_position: self.cursor_position,
            cursor_delta: self.cursor_delta,
            timestamp: self.timestamp,
        }
    }
}

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

    #[test]
    fn empty_frame() {
        let frame = InputFrame::default();
        assert!(!frame.has_movement());
        assert!(!frame.has_look());
        assert!(!frame.has_scroll());
        assert!(frame.actions.is_empty());
    }

    #[test]
    fn builder_actions() {
        let frame = InputFrameBuilder::new(0.0)
            .action(InputAction::MoveForward)
            .action(InputAction::Sprint)
            .build();

        assert!(frame.has_action(InputAction::MoveForward));
        assert!(frame.has_action(InputAction::Sprint));
        assert!(!frame.has_action(InputAction::Jump));
    }

    #[test]
    fn builder_no_duplicate_actions() {
        let frame = InputFrameBuilder::new(0.0)
            .action(InputAction::Attack)
            .action(InputAction::Attack)
            .build();

        assert_eq!(frame.actions.len(), 1);
    }

    #[test]
    fn builder_movement() {
        let frame = InputFrameBuilder::new(0.0).movement(-1.0, 1.0).build();

        assert!(frame.has_movement());
        assert_eq!(frame.movement, [-1.0, 1.0]);
    }

    #[test]
    fn builder_look_and_scroll() {
        let frame = InputFrameBuilder::new(0.0).look(5.0, -3.0).scroll(1.5).build();

        assert!(frame.has_look());
        assert!(frame.has_scroll());
        assert_eq!(frame.look_delta, [5.0, -3.0]);
        assert_eq!(frame.scroll_delta, 1.5);
    }

    #[test]
    fn builder_cursor() {
        let frame = InputFrameBuilder::new(1.0)
            .cursor(100.0, 200.0)
            .cursor_delta(2.0, -1.0)
            .build();

        assert_eq!(frame.cursor_position, [100.0, 200.0]);
        assert_eq!(frame.cursor_delta, [2.0, -1.0]);
        assert_eq!(frame.timestamp, 1.0);
    }

    #[test]
    fn full_frame_build() {
        let frame = InputFrameBuilder::new(0.016)
            .action(InputAction::MoveForward)
            .action(InputAction::Sprint)
            .movement(0.0, 1.0)
            .look(0.0, 0.0)
            .scroll(-0.5)
            .cursor(640.0, 480.0)
            .cursor_delta(0.0, 0.0)
            .build();

        assert!(frame.has_action(InputAction::MoveForward));
        assert!(frame.has_action(InputAction::Sprint));
        assert!(frame.has_movement());
        assert!(!frame.has_look());
        assert!(frame.has_scroll());
        assert_eq!(frame.timestamp, 0.016);
    }
}

// ── InputPacket ───────────────────────────────────────────────────────
//
// Tick-stamped, simulation-ready input contract. The canonical exchange type
// between the platform input layer and the CausalComputeKernel. Produced
// once per tick from an InputFrame (binding-aware, normalized).

/// Simulation-ready input packet. Single canonical type consumed by
/// CausalComputeKernel, CausalEngineEncoder, and all downstream systems.
#[derive(Debug, Clone)]
pub struct InputPacket {
    // ── Movement (from InputFrame.movement, already binding-aware + normalized) ──
    /// Camera-relative movement in [-1,1]. x=right, y=forward.
    pub movement: [f32; 2],
    /// Camera yaw in radians, for world-space direction derivation.
    pub camera_yaw: f32,

    // ── Edge-triggered (fire once per tick) ──
    pub jump: bool,
    pub interact: bool,

    // ── Level-triggered (held state) ──
    pub sprint: bool,
    pub gather: bool,
    /// Analog primary action strength [0,1].
    pub emit_strength: f32,
    /// Form coherence target [0,1]. 1.0=Cohere, 0.0=Wave.
    pub coherence_target: f32,

    // ── Timing ──
    pub dt: f32,
    /// Monotonic seconds since session start.
    pub timestamp: f64,
    pub tick: u64,

    // ── Physics context (from previous frame) ──
    pub grounded: bool,
}

impl InputPacket {
    /// Idle packet with all zeros. For tests and no-input frames.
    pub fn idle(dt: f32, tick: u64) -> Self {
        Self {
            movement: [0.0; 2],
            camera_yaw: 0.0,
            jump: false,
            interact: false,
            sprint: false,
            gather: false,
            emit_strength: 0.0,
            coherence_target: 1.0,
            dt,
            timestamp: 0.0,
            tick,
            grounded: true,
        }
    }

    /// Bridge an InputFrame to an InputPacket with additional simulation context.
    pub fn from_frame(
        frame: &InputFrame,
        camera_yaw: f32,
        dt: f32,
        timestamp: f64,
        tick: u64,
        grounded: bool,
        coherence_target: f32,
        gather: bool,
        emit_strength: f32,
    ) -> Self {
        Self {
            movement: frame.movement,
            camera_yaw,
            jump: frame.has_action(InputAction::Jump),
            interact: frame.has_action(InputAction::Interact),
            sprint: frame.has_action(InputAction::Sprint),
            gather,
            emit_strength,
            coherence_target,
            dt,
            timestamp,
            tick,
            grounded,
        }
    }

    /// Encode active actions as u8 discriminants for Weave serialization.
    pub fn actions_as_u8(&self) -> Vec<u8> {
        let mut out = Vec::with_capacity(4);
        if self.movement[1] > 0.0 {
            out.push(0);
        } // MoveForward
        if self.movement[1] < 0.0 {
            out.push(1);
        } // MoveBackward
        if self.movement[0] < 0.0 {
            out.push(2);
        } // MoveLeft
        if self.movement[0] > 0.0 {
            out.push(3);
        } // MoveRight
        if self.sprint {
            out.push(6);
        } // Sprint
        if self.jump {
            out.push(8);
        } // Jump
        if self.interact {
            out.push(16);
        } // Interact
        if self.gather {
            out.push(100);
        } // Gather (extended)
        out
    }

    /// BLAKE3 digest of the packet for attestation chains.
    pub fn digest(&self) -> [u8; 32] {
        let mut hasher = blake3::Hasher::new();
        hasher.update(&self.movement[0].to_le_bytes());
        hasher.update(&self.movement[1].to_le_bytes());
        hasher.update(&self.camera_yaw.to_le_bytes());
        hasher.update(&[
            self.jump as u8,
            self.interact as u8,
            self.sprint as u8,
            self.gather as u8,
        ]);
        hasher.update(&self.emit_strength.to_le_bytes());
        hasher.update(&self.coherence_target.to_le_bytes());
        hasher.update(&self.dt.to_le_bytes());
        hasher.update(&self.timestamp.to_le_bytes());
        hasher.update(&self.tick.to_le_bytes());
        hasher.update(&[self.grounded as u8]);
        *hasher.finalize().as_bytes()
    }

    /// Whether any movement input is present.
    pub fn has_movement(&self) -> bool {
        self.movement[0] != 0.0 || self.movement[1] != 0.0
    }
}

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

    #[test]
    fn idle_packet_is_zero() {
        let p = InputPacket::idle(1.0 / 60.0, 0);
        assert!(!p.has_movement());
        assert!(!p.jump);
        assert!(!p.sprint);
        assert!(p.grounded);
        assert_eq!(p.coherence_target, 1.0);
    }

    #[test]
    fn from_frame_maps_actions() {
        let frame = InputFrameBuilder::new(0.0)
            .action(InputAction::Jump)
            .action(InputAction::Sprint)
            .movement(0.5, 1.0)
            .build();
        let p = InputPacket::from_frame(&frame, 0.0, 0.016, 1.0, 1, true, 0.8, false, 0.0);
        assert!(p.jump);
        assert!(p.sprint);
        assert!(!p.interact);
        assert_eq!(p.movement, [0.5, 1.0]);
        assert_eq!(p.coherence_target, 0.8);
    }

    #[test]
    fn actions_as_u8_encodes_movement() {
        let mut p = InputPacket::idle(0.016, 0);
        p.movement = [0.0, 1.0]; // forward
        p.sprint = true;
        let actions = p.actions_as_u8();
        assert!(actions.contains(&0)); // MoveForward
        assert!(actions.contains(&6)); // Sprint
        assert!(!actions.contains(&8)); // no Jump
    }

    #[test]
    fn digest_is_nonzero() {
        let p = InputPacket::idle(0.016, 0);
        let d = p.digest();
        assert_ne!(d, [0u8; 32]);
    }

    #[test]
    fn digest_changes_with_input() {
        let p1 = InputPacket::idle(0.016, 0);
        let mut p2 = InputPacket::idle(0.016, 0);
        p2.jump = true;
        assert_ne!(p1.digest(), p2.digest());
    }
}