bevy_director 0.2.0

//! The data model: what a sequence IS, on disk and in memory. Everything
//! here is plain serde data; the runtime never reads it directly, it bakes
//! it first (see eval.rs). Times are seconds. Shot starts are absolute on
//! the sequence timeline; key times are local to their shot.

use bevy::prelude::*;
use serde::{Deserialize, Serialize};

/// A cinematic sequence: an ordered list of shots (the camera-cuts track)
/// plus named markers and an optional handback blend at the end.
#[derive(Asset, Reflect, Clone, Debug, Serialize, Deserialize)]
pub struct SequenceAsset {
    pub name: String,
    pub shots: Vec<Shot>,
    #[serde(default)]
    pub markers: Vec<Marker>,
    /// Blend back to the live gameplay camera when the sequence ends.
    /// None means a hard cut back.
    #[serde(default)]
    pub blend_out: Option<Blend>,
}

impl SequenceAsset {
    /// A sequence with no shots yet, for the viewfinder to fill.
    pub fn empty(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            shots: Vec::new(),
            markers: Vec::new(),
            blend_out: None,
        }
    }

    /// End of the last shot; zero for an empty sequence.
    pub fn duration(&self) -> f32 {
        self.shots
            .iter()
            .map(|s| s.start + s.duration)
            .fold(0.0, f32::max)
    }
}

/// One camera setup for a span of the timeline. Shots cut hard by default;
/// give a shot a blend_in to ease from the previous one (or, on the first
/// shot, from the live gameplay camera).
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub struct Shot {
    /// Absolute start on the sequence timeline.
    pub start: f32,
    pub duration: f32,
    #[serde(default)]
    pub blend_in: Option<Blend>,
    pub rig: Rig,
    #[serde(default)]
    pub look: Look,
    #[serde(default)]
    pub lens: Lens,
    /// Handheld wobble layered on top of everything else.
    #[serde(default)]
    pub shake: Option<Shake>,
}

/// A deterministic handheld layer. Same seed, same take, every run.
#[derive(Reflect, Clone, Copy, Debug, Serialize, Deserialize)]
pub struct Shake {
    /// Peak angular wobble, degrees.
    pub amplitude_deg: f32,
    pub frequency_hz: f32,
    #[serde(default)]
    pub seed: u32,
    /// Peak positional wobble in local space, meters.
    #[serde(default)]
    pub pos_amplitude: f32,
}

/// How the camera transform is produced over the shot.
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub enum Rig {
    /// Keyframed poses, eased per key toward the next.
    Keys {
        keys: Vec<Key>,
        #[serde(default)]
        interp: KeyInterp,
    },
    /// A dolly on a spline through the given points. `progress` is the
    /// 0..1 travel over the shot (empty track = linear over the whole
    /// shot); `constant_speed` makes equal time cover equal distance.
    Rail {
        points: Vec<Vec3>,
        #[serde(default)]
        kind: RailKind,
        #[serde(default = "yes")]
        constant_speed: bool,
        #[serde(default)]
        progress: ScalarTrack,
    },
    /// A crane circling a target: spherical coordinates over time.
    /// Yaw 0 / pitch 0 sits on +Z of the center; yaw sweeps toward +X.
    Orbit {
        center: TargetRef,
        radius: ScalarTrack,
        #[serde(default)]
        yaw_deg: ScalarTrack,
        #[serde(default)]
        pitch_deg: ScalarTrack,
    },
}

fn yes() -> bool {
    true
}

/// How key positions travel between keys.
#[derive(Reflect, Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum KeyInterp {
    /// Straight line per segment, shaped by each key's ease.
    #[default]
    Eased,
    /// Catmull-Rom through the key positions: one smooth curve, still
    /// paced by each key's ease.
    CatmullRom,
}

/// The spline family under a rail.
#[derive(Reflect, Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum RailKind {
    /// Passes through every point. Needs at least 2.
    #[default]
    CatmullRom,
    /// Smoother, does not touch the points. Needs at least 4.
    BSpline,
}

/// Something in the world a shot can aim at or focus on.
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub enum TargetRef {
    Point(Vec3),
    /// Resolved against bevy `Name` at runtime.
    Entity(String),
}

/// One captured framing.
#[derive(Reflect, Clone, Copy, Debug, Serialize, Deserialize)]
pub struct Key {
    /// Seconds from the shot's start.
    pub time: f32,
    pub pos: Vec3,
    /// Used while the shot's look is Free. Rig rotations are ignored when
    /// a look-at owns the aim.
    #[serde(default)]
    pub rot: Option<Quat>,
    /// Shapes the travel toward the NEXT key.
    #[serde(default = "linear")]
    pub ease: EaseFunction,
}

fn linear() -> EaseFunction {
    EaseFunction::Linear
}

/// Where the camera aims.
#[derive(Reflect, Clone, Debug, Default, Serialize, Deserialize)]
pub enum Look {
    /// Aim comes from the rig's key rotations. Rails have none, so a
    /// rail shot must pick At or Velocity.
    #[default]
    Free,
    /// Track a target. `damping` is an exponential decay rate (higher =
    /// tighter); None snaps.
    At {
        target: TargetRef,
        #[serde(default)]
        damping: Option<f32>,
    },
    /// Face wherever the rig is moving: the dolly operator's default.
    Velocity,
}

/// A scalar animated over the shot: fov, and later focus and aperture.
#[derive(Reflect, Clone, Debug, Default, Serialize, Deserialize)]
pub struct ScalarTrack {
    pub keys: Vec<ScalarKey>,
}

#[derive(Reflect, Clone, Copy, Debug, Serialize, Deserialize)]
pub struct ScalarKey {
    pub time: f32,
    pub value: f32,
    #[serde(default = "linear")]
    pub ease: EaseFunction,
}

impl ScalarTrack {
    pub fn constant(value: f32) -> Self {
        Self {
            keys: vec![ScalarKey {
                time: 0.0,
                value,
                ease: EaseFunction::Linear,
            }],
        }
    }

    /// Sample at a shot-local time. Holds the first and last values
    /// outside the keyed range. Keys must be sorted (bake checks).
    pub fn sample(&self, t: f32) -> f32 {
        let keys = &self.keys;
        let Some(first) = keys.first() else {
            return 0.0;
        };
        if t <= first.time {
            return first.value;
        }
        for pair in keys.windows(2) {
            let (a, b) = (&pair[0], &pair[1]);
            if t <= b.time {
                let span = (b.time - a.time).max(f32::EPSILON);
                let w = a.ease.sample_clamped((t - a.time) / span);
                return a.value + (b.value - a.value) * w;
            }
        }
        keys.last().map_or(0.0, |k| k.value)
    }
}

/// The lens: field of view, focus, aperture, exposure. Focus and
/// aperture become bevy DepthOfField on the cine camera; exposure
/// becomes the Exposure component. All optional beyond fov.
#[derive(Reflect, Clone, Debug, Default, Serialize, Deserialize)]
pub struct Lens {
    #[serde(default)]
    pub fov: FovSpec,
    #[serde(default)]
    pub focus: Option<FocusTrack>,
    #[serde(default)]
    pub aperture_f_stops: Option<ScalarTrack>,
    #[serde(default)]
    pub exposure_ev100: Option<ScalarTrack>,
    #[serde(default)]
    pub dof_mode: DofMode,
}

/// Field of view over the shot.
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub enum FovSpec {
    /// Vertical fov in DEGREES (the engine wants radians; eval converts).
    VerticalFovDeg(ScalarTrack),
    /// A real lens: focal length in millimeters against a filmback.
    /// fov_y = 2 atan(sensor_height / 2 focal).
    FocalLengthMm {
        track: ScalarTrack,
        #[serde(default)]
        filmback: Filmback,
    },
}

impl Default for FovSpec {
    fn default() -> Self {
        FovSpec::VerticalFovDeg(ScalarTrack::constant(45.0))
    }
}

/// Sensor heights for the focal-length math. Super35 matches bevy's
/// PhysicalCameraParameters default (18.66 mm).
#[derive(Reflect, Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum Filmback {
    #[default]
    Super35,
    FullFrame,
    Super16,
    Custom {
        sensor_height_mm: f32,
    },
}

impl Filmback {
    pub fn sensor_height_mm(&self) -> f32 {
        match self {
            Filmback::Super35 => 18.66,
            Filmback::FullFrame => 24.0,
            Filmback::Super16 => 7.41,
            Filmback::Custom { sensor_height_mm } => *sensor_height_mm,
        }
    }
}

/// Where the focus plane sits over the shot.
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub enum FocusTrack {
    /// Meters from the camera.
    Distance(ScalarTrack),
    /// Follow a target; offset shifts the plane in meters.
    Target {
        target: TargetRef,
        #[serde(default)]
        offset: f32,
    },
}

/// bevy's two depth-of-field looks.
#[derive(Reflect, Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum DofMode {
    /// Cheap and safe everywhere.
    #[default]
    Gaussian,
    /// The pretty one; needs dual-source blending support.
    Bokeh,
}

/// An eased transition window.
#[derive(Reflect, Clone, Copy, Debug, Serialize, Deserialize)]
pub struct Blend {
    pub secs: f32,
    pub ease: EaseFunction,
}

/// A named point on the timeline. Markers are presentation cues (captions,
/// stingers): they fire only while playing forward across their time, and
/// skipping does not retro-fire them. Hang story-critical flags off
/// SequenceFinished instead.
#[derive(Reflect, Clone, Debug, Serialize, Deserialize)]
pub struct Marker {
    pub time: f32,
    pub name: String,
}

// ---------- code-side authoring ----------

impl Key {
    /// A key at a shot-local time, filled in with the builder calls.
    pub fn at(time: f32) -> Self {
        Self {
            time,
            pos: Vec3::ZERO,
            rot: None,
            ease: EaseFunction::Linear,
        }
    }

    pub fn pos(mut self, pos: Vec3) -> Self {
        self.pos = pos;
        self
    }

    pub fn rot(mut self, rot: Quat) -> Self {
        self.rot = Some(rot);
        self
    }

    /// Aim this key at a point (a Free-look convenience).
    pub fn looking_at(mut self, target: Vec3) -> Self {
        self.rot = Some(
            Transform::from_translation(self.pos)
                .looking_at(target, Vec3::Y)
                .rotation,
        );
        self
    }

    pub fn ease(mut self, ease: EaseFunction) -> Self {
        self.ease = ease;
        self
    }
}

impl Shot {
    /// A keyed shot with defaults everywhere else.
    pub fn keys(start: f32, duration: f32, keys: impl Into<Vec<Key>>) -> Self {
        Self {
            start,
            duration,
            blend_in: None,
            rig: Rig::Keys {
                keys: keys.into(),
                interp: KeyInterp::Eased,
            },
            look: Look::default(),
            lens: Lens::default(),
            shake: None,
        }
    }

    pub fn blend_in(mut self, secs: f32, ease: EaseFunction) -> Self {
        self.blend_in = Some(Blend { secs, ease });
        self
    }

    pub fn look(mut self, look: Look) -> Self {
        self.look = look;
        self
    }

    pub fn lens(mut self, lens: Lens) -> Self {
        self.lens = lens;
        self
    }

    pub fn shake(mut self, shake: Shake) -> Self {
        self.shake = Some(shake);
        self
    }
}

impl SequenceAsset {
    /// The one-shot convenience for code and tests.
    pub fn single_shot(name: impl Into<String>, shot: Shot) -> Self {
        Self {
            name: name.into(),
            shots: vec![shot],
            markers: Vec::new(),
            blend_out: None,
        }
    }
}