camera.zig

//! `C:\lancer\game\camera.cpp`: the views and where each puts the camera. `camera_set_view`
//! (`0x0045F1B0`) switches view, `camera_frame` (`0x0045FC90`) places the camera once a frame, and
//! `frame_controls` (`0x00414060`) picks views and steers the orbiting ones from the keyboard. The
//! game keeps the view (`Viewing`, `switchView`, `gameFrame`), and the camera shows it (`Camera`).

const std = @import("std");

const math = @import("../surrender/math.zig");
const srapi = @import("../surrender/surrenderlib/srapi.zig");
const input = @import("../input.zig");
const controls = @import("../input/controls.zig");
const Random = @import("../random.zig").Random;
const create = @import("create.zig");
const Order = @import("ai/orders.zig").Order;
const hud = @import("hud.zig");
const gameobj = @import("gameobj.zig");
const missiles = @import("missiles.zig");
const launch = @import("launch.zig");
const yamato_launch = @import("launch/yamato.zig");
const table = @import("table.zig");
const wgate = @import("wgate.zig");
const Vector = math.Vector;

/// The view table, which [`camera/views.zig`](camera/views.zig) transcribes.
pub const views = @import("camera/views.zig");
/// The director's shots, which the director's view shows.
pub const shots = @import("camera/shots.zig");
const director = @import("executor/director.zig");
const Matrix = math.Matrix;

test {
    std.testing.refAllDecls(@This());
}

/// Where the camera is and which way it looks.
pub const Place = math.Place;

// --- Projection ---------------------------------------------------------------------------------

/// The factors every view but `View.launch_bay` projects with (`sr_set_projection`): the screen
/// spans 5/6 of a view unit either side of the middle across and 5/8 up and down, square on a 4:3
/// screen: about 80 degrees across and 64 down.
pub const factors = [2]f32{ 0.6, 0.8 };

/// `View.launch_bay` projects wider, about 110 degrees across, over the whole screen.
pub const wide_factors = [2]f32{ 0.35, 0.467 };

/// The tenth of a pixel `sr_set_projection` takes off the screen's size before it scales it
/// (`0x004DC420`, `srapi.Projection.init`), which `unstretched` takes off likewise so that its
/// pixels come out square.
const projection_trim: f32 = 0.1;

/// The cinematic views' bars: the viewport leaves out this much of the screen at the top and the
/// bottom once they have slid in (`camera_frame`, `0x004DC420`).
pub const letterbox: f32 = 0.1;

/// OpenReliant's factors for a screen of any shape: the game's down, and across whatever keeps
/// pixels square. **Improvement:** the game uses its factors on every screen, which stretches the
/// picture on any but a 4:3 one; OpenReliant shows more at the sides instead. On a 4:3 screen the
/// factors are the game's to within a thousandth of a percent.
pub fn unstretched(width: u32, height: u32, base: [2]f32) [2]f32 {
    const w: f32 = @floatFromInt(width);
    const h: f32 = @floatFromInt(height);
    return .{ base[1] * (h - projection_trim) / (w - projection_trim), base[1] };
}

/// How far `factors` see up and down, in degrees: the screen spans 5/8 of a view unit either side
/// of the middle, which is about 64 degrees.
pub const original_field_of_view: f32 = 2 * std.math.radiansToDegrees(std.math.atan(0.5 / factors[1]));

/// The narrowest and the widest field of view the settings screen's FIELD OF VIEW offers, in
/// degrees up and down, the game's in the middle.
pub const least_field_of_view: f32 = 34;
pub const most_field_of_view: f32 = 94;

/// The factors that see `degrees` up and down, in the game's shape: `factors` at
/// `original_field_of_view`.
///
/// **Improvement:** the settings screen's FIELD OF VIEW sets how far the views the player flies in
/// see (`Camera.projection`). The game always projects them with `factors`.
pub fn factorsFor(degrees: f32) [2]f32 {
    const down = 0.5 / @tan(std.math.degreesToRadians(degrees) / 2);
    return .{ down * factors[0] / factors[1], down };
}

// --- Views --------------------------------------------------------------------------------------

/// A view, numbered as the game numbers them (`camera_view`, `0x00539A34`). The numbers not named
/// here are the game's cutaways: launches, landings, jumps, deaths and the like.
pub const View = enum(u8) {
    /// From the cockpit, ahead; `CockpitMode` says which of three ways.
    cockpit = 0,
    cockpit_left = 1,
    cockpit_right = 2,
    cockpit_rear = 3,
    /// Behind and above an object, lagging its turns.
    chase = 4,
    /// The spectator's view: the chase view under a number of its own, in which the player's
    /// missile lock doesn't build. Once the player is out of a network game, the camera watches
    /// the other players' ships in it, in turn (`camera_watch_next_player`, `0x004775D0`).
    spectator = 0x1E,
    /// The first of a launch's three cutaways (`launch_reliant_run`), from inside the carrier's
    /// bay beside the ship, which projects wider than the rest (`wide_factors`) and tilts down
    /// after the ship as it drops out.
    launch_bay = 0x20,
    /// The second: from far below the ship, looking up at it as it drops out.
    launch_below = 0x21,
    /// The third: from beside and below the carrier, which the view shows whole, looking at the
    /// ship as it drops out.
    launch_aside = 0x22,
    /// The first of the two views the Reliant's landing picks from at random (`ailand`): from
    /// beside the launch tube the ship lands in, within the carrier's hull, looking at the
    /// player's ship as it comes in through the tube's upper door and sinks.
    landing_tube = 0x23,
    /// The second: from above the carrier, aside and behind the tube, watching the ship.
    landing_aside = 0x26,
    /// The player's Jump Out ([jumps](../../../docs/engine/jump.md)): from out along each of the
    /// ship's axes where it began, watching it go.
    jump_out = 0x27,
    /// The first of three views the player's Jump In picks from at random: from close ahead of the
    /// ship and above it, looking back at it as it flies in, pulling away a little and shaking as
    /// hits shake the cockpit.
    jump_in_close = 0x17,
    /// The second: from far ahead, beyond where the ship arrives and below it, held, looking level
    /// in the ship's frame at where it came in from.
    jump_in_ahead = 0x18,
    /// The third: from beside where the ship arrives and above it, watching it fly in.
    jump_in_aside = 0x19,
    /// Around the player's target, looking at it, steered from the keyboard.
    target = 6,
    /// Around the player's ship, likewise.
    external = 0xC,
    /// The director's: the mission's script's shots (`shots`), each flown along the mission's
    /// curves or standing at a ship, locked, the ships each holds kept still. A ship keeps its
    /// undamaged speed in it (`ai.cruiseSpeed`), the player's engine and afterburner are not heard
    /// (`sound3d`), and CLOAK SHIP does nothing (`input.playerWeapons`).
    director = 0xD,
    /// Behind the camera's object, turning slowly with it and pulling away, as the player's ship is
    /// destroyed.
    pull_back = 8,
    /// Behind a missile.
    missile = 0x12,
    /// Circling the pilot's pod as the pilot ejects: Eject Camera.
    eject = 7,
    /// Round the ship picking the pilot's pod up, a Nanny or the enemy's Antanov, closing in.
    pickup = 0x1C,
    /// From behind the pilot's pod, at the Sabre that shoots it down, pulling back as it bursts.
    pod_shot = 0x1D,
    /// From where the camera was, watching its object.
    watch = 0x1A,
    /// From where the camera was, watching where the player's ship burst
    /// (`explode.Explosions.marker`).
    watch_marker = 0x1B,
    /// From a point the player flies past.
    flyby = 0x24,
    /// Watches the player's ship dock at a Nanny, from beside the Nanny.
    nanny_dock = 0x2B,
    /// Orbits beside the player while the warp tunnel opens, turned as the ship stood when it lined
    /// up for the warp, or as the ship stands while it runs no Warp Out (`playerRunning`).
    warp_prepare = 9,
    /// Holds the preparation camera as the ship enters its warp.
    warp_depart = 10,
    /// Watches the ship emerge from its arrival tunnel.
    warp_arrive = 11,
    /// The first of the two views the Yamato's landing picks from at random (`ailand`): from low in
    /// its landing bay, sliding along it as the landing goes on, turned level to face the ship
    /// (`landingBay`).
    landing_bay = 0x0E,
    /// The second: from above the player's ship and behind it, looking down as it rises, then from
    /// beside it, looking back at it as the view slides along it (`landingShip`).
    landing_ship = 0x25,
    /// The Yamato's launch: beside the ship, rising with time and following its position. Until the
    /// ship is clear of the bay, and `yamato_look_delay` ticks after, it faces the way the ship
    /// does. While the ship runs no Yamato launch, it always looks at the ship (`playerRunning`).
    yamato_beside = 0x0F,
    /// Far ahead of the ship, held still with a fixed pitch, looking back toward the bay.
    yamato_ahead = 0x10,
    /// Beside and ahead of the bay, held still and watching the ship fly out.
    yamato_aside = 0x11,
    _,

    /// The view's record in the view table (`0x004F72A8`), or null for a number past it, which
    /// `camera_set_view` stops the game for as an invalid camera type.
    pub fn record(view: View) ?views.Record {
        const n = @backingInt(view);
        return if (n < views.records.len) views.records[n] else null;
    }

    /// Whether the bars slide in: for the cutaways from 7 to `0x27` and `0x2B`, but not the
    /// external view.
    pub fn letterboxed(view: View) bool {
        return if (view.record()) |found| found.bars else false;
    }

    /// Whether the view is from the cockpit, so the object's own model is not drawn: views 0 to 3.
    pub fn fromCockpit(view: View) bool {
        return if (view.record()) |found| found.cockpit else false;
    }

    /// The language string that names the view, which `hud_draw` shows at the top of the screen
    /// in every view but the one ahead from the cockpit.
    pub fn name(view: View) ?u16 {
        return if (view.record()) |found| found.name else null;
    }

    /// Whether the player's missile lock builds and its rings show while the last frame's view is
    /// this one: the cockpit's views and the chase view, views 0 to 4 (`mission_frame`,
    /// `0x004933D7`), but not the spectator's view.
    pub fn showsLock(view: View) bool {
        return switch (view) {
            .cockpit, .cockpit_left, .cockpit_right, .cockpit_rear, .chase => true,
            else => false,
        };
    }

    /// How far the view turns from ahead, about the object's down axis, in degrees: the cockpit's
    /// side and rear views, and no other (`camera_frame`'s table, `0x0045FC9B`).
    pub fn cockpitTurn(view: View) f32 {
        return switch (view) {
            .cockpit_left => -90,
            .cockpit_right => 90,
            .cockpit_rear => 180,
            else => 0,
        };
    }
};

/// Whether a view puts the camera in its ship's cockpit: one of the views from the cockpit, save
/// the view ahead in the chase mode.
pub fn inCockpit(view: View, mode: CockpitMode) bool {
    return view.fromCockpit() and !(view == .cockpit and mode == .chase);
}

/// What the cockpit view shows (`cockpit_mode`, `0x00539A9C`). The cockpit key cycles it while
/// that view is up; the options set it at the start of a mission.
pub const CockpitMode = enum(u2) {
    /// From the eye, with no cockpit drawn.
    open = 0,
    /// From the eye, with the cockpit's model over the view (hardware renderers only).
    cockpit = 1,
    /// The chase view instead.
    chase = 2,

    pub fn next(mode: CockpitMode) CockpitMode {
        return switch (mode) {
            .open => .cockpit,
            .cockpit => .chase,
            .chase => .open,
        };
    }
};

/// The options' cockpit setting (`cockpit_mode_setting`, `0x005D5A78`), which the game keeps in
/// its ini as `[Device] View`, 0 when the ini has none.
pub const CockpitSetting = enum(u32) {
    cockpit = 0,
    chase = 1,
    none = 2,
    _,

    /// The cockpit mode a mission's launch ends in (`launch_reliant_run`, `0x0041B240`), as it switches
    /// the camera from the launch's cutaway to view 0: the cockpit's model for 0, the chase view
    /// for 1, and no cockpit for any other.
    pub fn mode(setting: CockpitSetting) CockpitMode {
        return switch (setting) {
            .cockpit => .cockpit,
            .chase => .chase,
            else => .open,
        };
    }
};

/// The camera keys, in the order `frame_controls` reads them.
pub const camera_actions = [_]controls.Action{
    .cockpit_camera, .left_view_camera, .right_view_camera, .rear_view_camera,
    .flyby_camera,   .target_camera,    .external_camera,   .missile_camera,
};

/// The view the joystick's hat switches to (`frame_controls`) for each of its four straight
/// directions, given in DirectInput's hundredths of a degree clockwise from forward: the cockpit's
/// front, right, rear or left view. Diagonals and the center select nothing.
pub fn hatView(pov: u32) ?View {
    return switch (pov) {
        0 => .cockpit,
        9000 => .cockpit_right,
        18000 => .cockpit_rear,
        27000 => .cockpit_left,
        else => null,
    };
}

/// The view a camera key picks (`frame_controls`), or null for another action. The cockpit key
/// picks the cockpit view, and, pressed in it, cycles the cockpit mode.
pub fn keyView(action: controls.Action) ?View {
    return switch (action) {
        .cockpit_camera => .cockpit,
        .left_view_camera => .cockpit_left,
        .right_view_camera => .cockpit_right,
        .rear_view_camera => .cockpit_rear,
        .flyby_camera => .flyby,
        .target_camera => .target,
        .external_camera => .external,
        .missile_camera => .missile,
        else => null,
    };
}

// --- The camera ---------------------------------------------------------------------------------

/// What a view reads of an object.
pub const Subject = struct {
    position: Vector,
    orientation: Matrix,
    /// The model header's eye point.
    eye: Vector = @splat(0),
    /// `GameObject.radius`: its farthest vertex from its origin.
    radius: f32 = 0,
    motion: Chase.Motion = .{},
    /// Whether it is exploding, which the pod-shot view waits for.
    exploding: bool = false,

    /// Where it stands and how it is turned.
    pub fn place(subject: Subject) Place {
        return .{ .position = subject.position, .orientation = subject.orientation };
    }

    /// What the camera follows of the object in `slot`: where its root's frame has it drawn, its
    /// model's eye point and its size, and for the chase view its type, its throttle and its rates
    /// of turn.
    pub fn of(slot: *const create.Slot) Subject {
        const live = &slot.object;
        return .{
            .position = slot.drawn.position,
            .orientation = slot.drawn.orientation,
            .eye = if (slot.type) |loaded| loaded.model.header.eye.vector() else @splat(0),
            .radius = live.radius,
            // The chase view sits farther back the more throttle the ship carries and swings
            // against its rates of turn, so it lags a turn rather than riding rigidly behind the
            // ship.
            .motion = .{
                .ship_type = live.type,
                .throttle = live.throttle,
                .afterburner = live.afterburner,
                .pitch_rate = live.pitch_rate,
                .yaw_rate = live.yaw_rate,
                .roll_rate = live.roll_rate,
            },
            .exploding = live.flags.exploding,
        };
    }
};

/// What `Camera.frame` reads of the world.
pub const World = struct {
    /// The object the view shows, `Camera.object`.
    object: Subject,
    /// The player's ship.
    player: Subject,
    /// The player's target, when it has one.
    target: ?Subject = null,
    /// Hundredths of a second since the last frame (`frame_duration`).
    ticks: u32,
    /// The mission's ticks this frame (`frame_start`), which the views that move with time go by,
    /// from when the view was switched to.
    now: u32 = 0,
    /// How far past `now` the frame is drawn, as a share of a tick (`objects.pastTick`), which
    /// those views go on by as well.
    ///
    /// **Improvement:** with smooth motion the views that move with time move on every frame, as
    /// the objects they watch do; the game moves them on a tick at a time, which a display's frames
    /// fall between unevenly.
    ahead: f32 = 0,
    /// Where the player's ship burst, for `watch_marker`; null before it has.
    marker: ?Vector = null,
    /// The cockpit's model and what moves it, for view 0 outside the chase mode; null for an
    /// object with no cockpit.
    cockpit: ?Cockpit.Input = null,
    /// The game's random numbers (`Random`), which the cockpit's jitter and the shake from hits
    /// draw on.
    random: ?*Random = null,
    /// Whether the player's ship has begun to drop out of its carrier's bay, which the bay view
    /// tilts down after (`launch.dropping`).
    dropping: bool = false,
    /// What the landing's views stand by, while the view's object lands (`ailand.seen`).
    landing: ?Landing = null,
    /// The game's world as the drawn frame sees it (`main.Drawn.world`), through which the
    /// director's view flies along the mission's curves and the missile view finds its missile;
    /// null where no game runs, as in a test.
    game: ?gameobj.World = null,
    /// What the game has the camera view (`input.Player.viewing`).
    viewing: *const Viewing,
    /// The game's shake from hits (`gameobj.World.shake`), as the last game frame left it.
    shake: f32 = 0,

    /// How long the view has been up at the frame, in ticks: since it was switched to, and on by as
    /// much past the tick as the frame is drawn (`ahead`).
    fn shown(world: World) f32 {
        return @as(f32, @floatFromInt(world.now -| world.viewing.switched)) + world.ahead;
    }
};

/// What the landing's views stand by, by the carrier the ship lands on (`ailand.seen`).
pub const Landing = union(enum) {
    /// The Reliant's: the middle of its launch tube the ship lands in, which the landing keeps
    /// (`ailand.State.tube`), and how the carrier is turned.
    reliant: struct { tube: Vector, carrier: Matrix },
    /// The Yamato's: where its landing bay stands, the bounds of the bay's hangar as it was drawn
    /// last, and the tick the view from the bay slides from (`ailand.State.due`).
    yamato: struct { bay: Place, hangar: [2]Vector, due: i32 },
    /// OpenReliant's own, a hangar bay's (`ailand.State.gate_place`).
    bay: Bay,

    /// What a landing in a hangar bay's views stand by: where the launch point of the gate the
    /// ship lands at stands and how it is turned, its Z axis the way the ship launches out, and
    /// the mouth of the bay, where that way leaves the carrier's bounds.
    pub const Bay = struct {
        gate: Place,
        mouth: Vector,

        /// The bay's depth, from the launch point to the mouth.
        pub fn depth(bay: Bay) f32 {
            return math.distance(bay.gate.position, bay.mouth);
        }
    };
};

/// What the camera views, which the game keeps in `camera_set_view`'s globals: the view, the object
/// it shows, since when, and whether a script holds it, with the director's shots and the ships
/// they hold, the cockpit mode and the orbit the camera keys steer. The game goes by it as well as
/// the camera: the mission ends once the player's end has been watched long enough
/// (`main.missionOver`), and the ships' cruise speed, the cloak and the missile lock depend on the
/// view. The camera (`Camera`) shows what it says. A world that draws nothing keeps it just the
/// same (`input.Player.viewing`).
///
/// What the original's game work changes in the camera as it switches the view, OpenReliant's
/// game frames record here, and the camera, which drawing keeps, takes it up as it next frames
/// (`changes`, `Camera.notice`). The game keeps the camera's shake too (`gameobj.World.shake`).
pub const Viewing = struct {
    view: View = .cockpit,
    /// The object the view shows (`camera_object`, `0x00539A8C`).
    object: ?u16 = null,
    /// Set while a script holds the camera (`0x00539ACC`): the camera keys do nothing.
    locked: bool = false,
    /// `frame_start` when the view last changed (`0x00539AA4`).
    switched: u32 = 0,
    /// OpenReliant's: the watch view (`View.watch`) is one that lasts, as `--watch` sets it, rather
    /// than the one the player's end switches to, so it doesn't end the mission
    /// (`main.missionOver`). Any change of view clears it (`set`).
    lasting: bool = false,
    /// The view as the last game frame ended (`camera_view_last`, `0x00539A64`), which the missile
    /// lock and the display go by.
    last: View = .cockpit,
    /// The missile the missile view follows (`camera_missile`, `0x00539A94`), and whether it has
    /// ended (`0x00539A7C`), after which the view holds still for `missile_linger` ticks and goes
    /// back to the cockpit (`gameFrame`).
    missile: u8 = 0,
    missile_gone: bool = false,
    /// The director's shots waiting, the first on screen (`shots.Shots`), and what the director
    /// keeps of that one (`director.Director`).
    shots: shots.Shots = .{},
    director: director.Director = .{},
    /// The ships the director's shot on screen holds still (`camera_held_kind`, `0x00539A30`, and
    /// `camera_held_index`, `0x00539A40`), and those the first shot waiting holds, as the view
    /// takes it (`camera_shot_hold_kind`, `0x00539A5C`, and `camera_shot_hold_index`,
    /// `0x00539938`).
    held: ?shots.Held = null,
    holding: ?shots.Held = null,
    /// What the cockpit view shows, which the cockpit key cycles (`key`), and the options' setting
    /// that a mission's start and the end of a launch put it back to (`cockpit_mode_setting`,
    /// `0x005D5A78`).
    cockpit_mode: CockpitMode = .open,
    cockpit_setting: CockpitSetting = .cockpit,
    /// Where the target and external views go round their object, which the arrow keys steer
    /// (`frameControls`).
    orbit: Orbit = .{},
    /// Set while the joystick's hat is held (`0x0051CF8C`), so that the view returns to the front
    /// when it is released.
    hat_glancing: bool = false,
    /// OpenReliant's: what the game changed of what the camera shows, which the camera takes up as
    /// it next frames (`Camera.notice`).
    changes: Changes = .{},
    /// OpenReliant's: where the camera stood as the last frame was drawn (`Camera.place`), which
    /// the driver hands the game as input, like what the player aims at (`hud.State.aim`). The
    /// effects that depend on the camera go by it: the particles, fewer behind it, the flames
    /// spread across the view, the sparks and the flak only near it, an Uber's bits thrown at it,
    /// and the screen's flash near it. Null where nothing is drawn, which leaves them out.
    seen_from: ?Place = null,
    /// OpenReliant's: how many of the switches of view the drawing side asked for the game has
    /// made (`Camera.requests`, `takeUp`).
    requests_seen: u32 = 0,

    /// What a switch of view goes by: the gates, whose worm the player's ship may be riding, and
    /// the missiles in flight, which the missile view follows; null where there are none.
    pub const Bounds = struct {
        gates: ?*const wgate.Gates = null,
        missiles: ?*const missiles.Missiles = null,

        /// `world`'s.
        pub fn of(world: gameobj.World) Bounds {
            return .{ .gates = world.gates, .missiles = &world.objects.missiles };
        }
    };

    /// The game's part of `camera_set_view`: the view's own part (`turn`), then, out of the
    /// director's view, the ships its shot held go (`shots.Held.hold`), and into it, the shot's own
    /// are held. The camera takes up the switch as it next frames (`Camera.cutTo`).
    pub fn set(viewing: *Viewing, view: View, object: ?u16, lock: bool, force: bool, now: u32, by: Bounds) bool {
        const cut = viewing.make(view, object, lock, force, now, by) orelse return false;
        viewing.changes.add(.{ .cut = cut });
        return true;
    }

    /// `set` without the change for the camera: returns the cut, or null where the switch is
    /// refused.
    fn make(viewing: *Viewing, view: View, object: ?u16, lock: bool, force: bool, now: u32, by: Bounds) ?Cut {
        const leaving: ?shots.Held = if (viewing.view == .director) viewing.held else null;
        const cut = viewing.turn(view, object, lock, force, now, by) orelse return null;
        if (leaving) |held| held.hold(false);
        if (view == .director) if (viewing.held) |held| held.hold(true);
        return cut;
    }

    /// The view's own part of a switch (`set`): switches to `view` at tick `now`, `object` the one
    /// it shows, `lock` keeping the camera keys off it. Refused while the player's ship rides the
    /// worm between gates, forced or not (`wgate.ridingWorm`, `0x0045F1B0`), and while the camera
    /// is locked, unless `force`. The missile view follows the next missile in flight, from the one
    /// it last followed, that `object` launched; with none, it is refused. The target and external
    /// views start their orbit again. It leaves the ships the director's shots hold as they are,
    /// which is how the drawn frame's copy of the view takes a switch (`Camera.ask`). Returns the
    /// cut for the camera, or null where the switch is refused.
    pub fn turn(viewing: *Viewing, view: View, object: ?u16, lock: bool, force: bool, now: u32, by: Bounds) ?Cut {
        if (wgate.ridingWorm(by.gates)) return null;
        if (viewing.locked and !force) return null;
        if (view == .missile) {
            const records = by.missiles orelse return null;
            viewing.missile = nextMissile(records, viewing.missile, object orelse return null) orelse return null;
            viewing.missile_gone = false;
        }
        const cut: Cut = .{ .from = viewing.view, .from_object = viewing.object, .view = view, .object = object, .cockpit_mode = viewing.cockpit_mode };
        viewing.view = view;
        viewing.object = object;
        viewing.locked = lock;
        viewing.switched = now;
        viewing.lasting = false;
        if (view == .director) viewing.held = viewing.holding;
        if (view == .target or view == .external) viewing.orbit = .{};
        return cut;
    }

    /// OpenReliant's: makes the switches of view the drawing side asked for since the game last
    /// took them up (`Camera.requests`), in the order they were asked, as `set` makes the game's
    /// own. The game's view then ends up as it would have if drawing had switched it directly.
    /// Where the camera cut to a switch as it was asked (`Request.cut_at_once`), `subtarget`
    /// follows the switch here (`Camera.Subtarget.follow`), and the camera gets no change to take
    /// up. Otherwise the camera takes the switch up as it next frames, as for the game's own.
    pub fn takeUp(viewing: *Viewing, requests: *const Requests, by: Bounds, subtarget: ?Camera.Subtarget) void {
        var asked = requests.since(viewing.requests_seen);
        while (asked.next()) |request| {
            const made = if (request.cut_at_once) made: {
                const cut = viewing.make(request.view, request.object, request.lock, request.force, request.now, by) orelse break :made false;
                if (subtarget) |sub| sub.follow(cut.view);
                break :made true;
            } else viewing.set(request.view, request.object, request.lock, request.force, request.now, by);
            if (made and request.lasting) viewing.lasting = true;
        }
        viewing.requests_seen = requests.count;
    }

    /// Whether the view is in `object`'s cockpit, in the cockpit mode: `camera_set_view` then sets
    /// the object's flag bit 0, so that it isn't drawn.
    pub fn inside(viewing: *const Viewing, object: u16) bool {
        return viewing.object == object and inCockpit(viewing.view, viewing.cockpit_mode);
    }

    /// A camera key (`frame_controls`): the cockpit key, in the cockpit view, cycles the cockpit
    /// mode first, and into the chase mode, the chase starts from its start distance. Returns the
    /// view to switch to, with the player's ship as its object for the views from it, or null for
    /// another action.
    pub fn key(viewing: *Viewing, action: controls.Action) ?View {
        const view = keyView(action) orelse return null;
        if (action == .cockpit_camera and viewing.view == .cockpit and !viewing.locked) {
            viewing.cockpit_mode = viewing.cockpit_mode.next();
            if (viewing.cockpit_mode == .chase) viewing.changes.add(.chase_mode);
        }
        return view;
    }

    /// The camera's part of `frame_controls` for a frame `ticks` hundredths of a second long: in
    /// the target and external views, the arrow keys steer the orbit, with Shift up and down to
    /// zoom. With `HatEnable`, holding the hat in a straight direction switches to the matching
    /// cockpit view, and releasing it returns to the front view. Then each camera key that was
    /// pressed selects its view (the last one in the game's order wins), which it returns, for the
    /// caller to switch to with the player's ship as its object (`switchView`). The keys are read
    /// in the game's order, since `key_pressed` clears latches.
    ///
    /// `orbited` is the radius of the object the orbit goes round, null for none. The original's
    /// camera keeps the orbit's distance in range as it places the camera each frame
    /// (`Orbit.keep`); OpenReliant's camera places it without writing into the orbit, so the orbit
    /// is kept in range here, as the frame before would have left it and as the frame after will
    /// show it.
    pub fn frameControls(viewing: *Viewing, devices: *input.Devices, ticks: u32, orbited: ?f32) ?View {
        const keyboard = &devices.keyboard;
        if (viewing.view == .target or viewing.view == .external) {
            const scan = input.scan;
            var keys: Orbit.Keys = .{};
            if (keyboard.pressed(scan.left, .none, false)) {
                keys.left = true;
            } else if (keyboard.pressed(scan.right, .none, false)) {
                keys.right = true;
            }
            if (keyboard.pressed(scan.up, .shift, false)) {
                keys = .{ .left = keys.left, .right = keys.right, .up = true, .shift = true };
            } else if (keyboard.pressed(scan.down, .shift, false)) {
                keys = .{ .left = keys.left, .right = keys.right, .down = true, .shift = true };
            } else if (keyboard.pressed(scan.up, .none, false)) {
                keys.up = true;
            } else if (keyboard.pressed(scan.down, .none, false)) {
                keys.down = true;
            }
            if (orbited) |radius| viewing.orbit.keep(viewing.view, radius);
            viewing.orbit.steer(keys, @floatFromInt(ticks));
            if (orbited) |radius| viewing.orbit.keep(viewing.view, radius);
        }
        var chosen: ?View = null;
        const glancing = viewing.hat_glancing;
        viewing.hat_glancing = false;
        if (devices.settings.hat_enabled and devices.joystick.hats != 0) {
            if (hatView(devices.joystick.state.pov[0])) |view| {
                chosen = view;
                viewing.hat_glancing = true;
            }
        }
        if (glancing and !viewing.hat_glancing) chosen = .cockpit;
        for (camera_actions) |action| {
            if (devices.active(action, true)) chosen = viewing.key(action);
        }
        return chosen;
    }
};

/// OpenReliant's: a change the game makes to what the camera shows, which the camera takes up as
/// it next frames (`Camera.notice`), where the original's game work makes it to the camera at
/// once.
pub const Change = union(enum) {
    /// A switch of view (`Viewing.set`), which the camera cuts to (`Camera.cutTo`).
    cut: Cut,
    /// The cockpit key put the cockpit view in the chase mode (`Viewing.key`): the chase starts
    /// from its start distance.
    chase_mode,
    /// Where an ejection's view stands off from what it watches, as it is switched to
    /// (`switchCutaway`, `Camera.placeCutaway`).
    cutaway: struct { view: View, seen: Subject, pod: Subject },
    /// Where a launch's view puts the camera (`switchLaunch`, `Camera.placeLaunch`).
    launch: struct { view: View, seen: Subject, player: Subject, even_gate: bool },
    /// Where one of the Yamato's exterior views puts the camera (`switchYamato`,
    /// `Camera.placeYamato`).
    yamato: struct { view: View, player: Subject },
    /// Where a jump's view puts the camera (`switchJump`, `Camera.placeJump`).
    jump: struct { view: View, seen: Subject, player: Subject },
};

/// A switch of view: from `from` of `from_object` to `view` of `object`, in the cockpit mode it
/// was made in.
pub const Cut = struct {
    from: View,
    from_object: ?u16,
    view: View,
    object: ?u16,
    cockpit_mode: CockpitMode,
};

/// OpenReliant's: the latest changes the game made to what the camera shows (`Change`), which the
/// camera takes up as it frames (`Camera.notice`). More than a few come between two drawn frames
/// only where the game frames run with none drawn, as while `--skip-launch` passes over the
/// launch; the camera then takes up the latest.
pub const Changes = table.Latest(Change, 16);

/// OpenReliant's: a switch of view the drawing side asks the game for, as a mod's script and
/// `--watch` make them (`Camera.ask`), which the game makes before it next runs
/// (`Viewing.takeUp`).
pub const Request = struct {
    view: View,
    object: ?u16,
    lock: bool = false,
    force: bool = false,
    /// The tick it is asked at (`main.Clock.viewTime`), which the game switches at too.
    now: u32,
    /// Whether the view lasts (`Viewing.lasting`), as `--watch` has it.
    lasting: bool = false,
    /// Whether the camera cuts to it as it is asked, as for a mod's script, which can read the view
    /// back straight away. Otherwise, as for `--watch`, the camera cuts as it next frames, once the
    /// game has made the switch.
    cut_at_once: bool = true,
};

/// How many switches of view the drawing side can ask for before the game takes them up
/// (`Camera.ask`).
const most_requests = 16;

/// OpenReliant's: the latest switches of view the drawing side asked for (`Request`), which the
/// game takes up before it next runs (`Viewing.takeUp`).
pub const Requests = table.Latest(Request, most_requests);

/// Switches the world's view (`camera_set_view`, `Viewing.set`) at the mission's tick.
pub fn switchView(world: gameobj.World, view: View, object: ?u16, lock: bool, force: bool) bool {
    return world.player.viewing.set(view, object, lock, force, world.clock.viewTime(), .of(world));
}

/// Makes the switches of view the drawing side asked the game for through `drawn`, the camera
/// (`Viewing.takeUp`), in `world`.
pub fn takeUp(world: gameobj.World, drawn: *const Camera) void {
    world.player.viewing.takeUp(&drawn.requests, .of(world), drawn.subtarget);
}

/// Switches to one of the ejection's views, `view`, of `object`, locked and forced
/// (`switchView`), with what the camera stands off by taken from `seen`, the object, and `pod`, the
/// pilot's, as they stand now (`Camera.placeCutaway`).
pub fn switchCutaway(world: gameobj.World, view: View, object: u16, seen: Subject, pod: Subject) bool {
    return switchPlacing(world, view, object, .{ .cutaway = .{ .view = view, .seen = seen, .pod = pod } });
}

/// Switches to one of a launch's views, `view`, of `object`, locked and forced (`switchView`),
/// placing the camera once where the view stands (`Camera.placeLaunch`).
pub fn switchLaunch(world: gameobj.World, view: View, object: u16, seen: Subject, player: Subject, even_gate: bool) bool {
    return switchPlacing(world, view, object, .{ .launch = .{ .view = view, .seen = seen, .player = player, .even_gate = even_gate } });
}

/// Switches to one of the Yamato's exterior views, `view`, of `object`, locked and forced
/// (`switchView`), placing the camera once where the view stands (`Camera.placeYamato`).
pub fn switchYamato(world: gameobj.World, view: View, object: u16, player: Subject) bool {
    return switchPlacing(world, view, object, .{ .yamato = .{ .view = view, .player = player } });
}

/// Switches to one of a jump's views, `view`, of `object`, locked and forced (`switchView`),
/// placing the camera once where the view stands (`Camera.placeJump`).
pub fn switchJump(world: gameobj.World, view: View, object: u16, seen: Subject, player: Subject) bool {
    return switchPlacing(world, view, object, .{ .jump = .{ .view = view, .seen = seen, .player = player } });
}

/// Switches to `view` of `object`, locked and forced (`switchView`), and has the camera place
/// itself as `placing` says once it takes the switch up.
fn switchPlacing(world: gameobj.World, view: View, object: u16, placing: Change) bool {
    if (!switchView(world, view, object, true, true)) return false;
    world.player.viewing.changes.add(placing);
    return true;
}

/// The camera: Surrender's camera frame, which `camera_frame` places as the game's view
/// (`Viewing`) says, and what the original keeps to place it, with the cockpit's model it moves in
/// view 0. Leaves out the views not named in `View`, and the shake from hits in any view but 0.
pub const Camera = struct {
    place: Place = .{ .position = @splat(0), .orientation = math.identity },
    /// How much of the screen each bar covers (`0x00539A38`), and how fast they move
    /// (`0x00539A50`).
    bars: f32 = 0,
    bar_speed: f32 = 0,
    /// Where the ejection's views stand off from what they watch, as they are switched to
    /// (`0x00539A44`): the eject view's reach out to its object's right, the pickup's way to half
    /// between the picking ship and the pod, and the pod shot's way from the pod to the Sabre.
    cutaway: Vector = @splat(0),
    chase: Chase = .{},
    /// What is left of the game's shake from hits as the frame is drawn, a tick on
    /// (`Cockpit.faded`), which the camera and the display shake by.
    shake_left: f32 = 0,
    /// The guns' kick on the cockpit's hands (`0x005636E0`): 1 as the player's guns fire
    /// (`0x0047BE3A`), and a twentieth less each frame.
    recoil: f32 = 0,
    /// Where the cockpit's model stands this frame, in view 0 outside the chase mode; null in the
    /// rest.
    cockpit_place: ?Cockpit.Placed = null,
    /// Set as the view switches, which resets the star streaks (`backdrop_reset_streaks`), so that
    /// the frame drawn next draws none, even where the view switches back to what it was.
    cut: bool = false,
    /// The player's subtarget picked out in red, which a switch of view picks out or puts back
    /// (`Subtarget.follow`), with the objects it is picked out of; null where there is no display.
    subtarget: ?Subtarget = null,
    /// OpenReliant's: how many of the game's changes to what it shows it has taken up
    /// (`Viewing.changes`, `notice`).
    seen: u32 = 0,
    /// OpenReliant's: the switches of view the drawing side asked the game for (`ask`).
    requests: Requests = .{},

    pub const Subtarget = struct {
        shown: *hud.subtarget.Subtarget,
        all: *create.Objects,

        /// The subtarget's part of a switch to `view`: its parts are picked out in view 0 and put
        /// back in any other (`0x0045F42D`, `0x0045F397`).
        pub fn follow(subtarget: Subtarget, view: View) void {
            if (view == .cockpit) subtarget.shown.pick(subtarget.all) else subtarget.shown.clear(subtarget.all);
        }
    };

    /// Bars grow this share of the screen a tick, times their speed (`camera_frame`, `0x004DC418`).
    pub const bar_rate: f32 = 0.001;

    /// Takes up the changes the game made to what the camera shows since it last did
    /// (`Viewing.changes`), in the order the game made them, with the subtarget following each
    /// switch of view. It does so as it frames, and the drawn frame has it do so before it copies
    /// the objects, which a cut's subtarget changes.
    pub fn notice(camera: *Camera, viewing: *const Viewing) void {
        var changes = viewing.changes.since(camera.seen);
        while (changes.next()) |change| switch (change) {
            .cut => |cut| {
                camera.cutTo(cut);
                if (camera.subtarget) |sub| sub.follow(cut.view);
            },
            .chase_mode => camera.chase.distance = Chase.start_distance,
            .cutaway => |placed| camera.placeCutaway(placed.view, placed.seen, placed.pod),
            .launch => |placed| camera.placeLaunch(placed.view, placed.seen, placed.player, placed.even_gate),
            .yamato => |placed| camera.placeYamato(placed.view, placed.player),
            .jump => |placed| camera.placeJump(placed.view, placed.seen, placed.player),
        };
        camera.seen = viewing.changes.count;
    }

    /// OpenReliant's: a switch of view the drawing side makes, as `request` asks: `viewing`, the
    /// drawn frame's copy of the view, switches at once (`Viewing.turn`), and the game makes the
    /// same switch before it next runs (`requests`, `Viewing.takeUp`). Where the request says so,
    /// the camera cuts to it at once too. Refused where the game would refuse it, and past
    /// `most_requests` the game hasn't taken up yet. Returns whether it switched.
    pub fn ask(camera: *Camera, viewing: *Viewing, request: Request, by: Viewing.Bounds) bool {
        if (camera.requests.count -% viewing.requests_seen >= most_requests) return false;
        const cut = viewing.turn(request.view, request.object, request.lock, request.force, request.now, by) orelse return false;
        if (request.lasting) viewing.lasting = true;
        if (request.cut_at_once) camera.cutTo(cut);
        camera.requests.add(request);
        return true;
    }

    /// The camera's part of a switch of view (`camera_set_view`, `Viewing.set`): it has the stars
    /// draw no streaks next frame, and slides the bars in for a letterboxed view or takes them away
    /// for another.
    fn cutTo(camera: *Camera, cut: Cut) void {
        const view = cut.view;
        camera.cut = true;
        if (view.letterboxed()) {
            camera.bar_speed = 1;
        } else {
            camera.bars = 0;
            camera.bar_speed = 0;
        }
        if (view == .chase and (cut.from != .chase or cut.from_object != cut.object)) {
            camera.chase.distance = Chase.start_distance;
        }
        switch (view) {
            .cockpit => if (cut.cockpit_mode == .chase) camera.chase.resetTurns(),
            .chase, .spectator => camera.chase.resetTurns(),
            else => {},
        }
    }

    /// What the ejection's views stand off by from what they watch, as `view` is switched to
    /// (`switchCutaway`), from `seen`, the object, and `pod`, the pilot's, as they stand now.
    pub fn placeCutaway(camera: *Camera, view: View, seen: Subject, pod: Subject) void {
        camera.cutaway = switch (view) {
            .eject => math.xAxis(seen.orientation) * @as(Vector, @splat(eject_reach)),
            .pickup => (pod.position - seen.position) * @as(Vector, @splat(pickup_share)),
            .pod_shot => math.normalize(seen.position - pod.position),
            else => camera.cutaway,
        };
    }

    /// Where a launch's view, `view`, puts the camera once as it is switched to (`switchLaunch`):
    /// the bay view beside `seen`, the object, on its left where `even_gate` and else on its right;
    /// the view from below under `player`, the player's ship, looking up at it; and the view aside
    /// beside and below the object. `frame` then turns it.
    pub fn placeLaunch(camera: *Camera, view: View, seen: Subject, player: Subject, even_gate: bool) void {
        switch (view) {
            .launch_bay => {
                const across: Vector = .{ if (even_gate) -bay_offset[0] else bay_offset[0], bay_offset[1], bay_offset[2] };
                camera.place.position = seen.place().point(across);
            },
            // Looking at the player's ship (`camera_look_at_player`, `0x00461D00`).
            .launch_below => camera.place = lookingAt(player.place().point(below_offset), player.position),
            .launch_aside => camera.place.position = seen.place().point(aside_offset),
            else => {},
        }
    }

    /// Where the Yamato's exterior views put the camera as they are switched to (`switchYamato`,
    /// `camera_set_view`, `0x0045F4B0` onward). The ahead view keeps its orientation; the aside
    /// view keeps its position and follows the ship.
    pub fn placeYamato(camera: *Camera, view: View, player: Subject) void {
        switch (view) {
            .yamato_beside => camera.place = yamatoBeside(player, 0),
            .yamato_ahead => camera.place = .{
                .position = player.place().point(yamato_ahead_offset),
                .orientation = math.turned(math.turned(player.orientation, .x, yamato_ahead_pitch), .y, std.math.pi),
            },
            .yamato_aside => camera.place = lookingAt(player.place().point(yamato_aside_offset), player.position),
            else => {},
        }
    }

    /// Where a jump's view, `view`, puts the camera once as it is switched to (`switchJump`): Jump
    /// Out's view `jump_out_reach` out from `seen`, the object, along each of its axes; the view
    /// ahead `jump_ahead_offset` from it, looking at it level in the frame of `player`, the player's
    /// ship; and the view aside `jump_aside_offset` from it. `frame` then moves it. The close view
    /// needs no placing: `frame` places it from the player's ship every frame, as it does at the
    /// switch.
    pub fn placeJump(camera: *Camera, view: View, seen: Subject, player: Subject) void {
        switch (view) {
            .jump_out => camera.place.position = seen.place().point(@splat(jump_out_reach)),
            .jump_in_ahead => camera.place = levelLookingAt(seen.place().point(jump_ahead_offset), seen.position, player.orientation),
            .jump_in_aside => camera.place.position = seen.place().point(jump_aside_offset),
            else => {},
        }
    }

    /// Places the camera for a drawn frame (`camera_frame`), once it has taken up the game's
    /// changes (`notice`): moves the bars, then puts the camera where the view says. Where the view
    /// can't go on, it holds still until the game switches it back. The game frames do the rest of
    /// `camera_frame`, the shake from hits on the controller among it (`gameFrame`).
    ///
    /// **Improvement:** with smooth motion, the missile view keeps behind its missile where the
    /// frame draws it, between the ticks, as the other views follow their objects; the game keeps
    /// behind it where the last tick left it.
    pub fn frame(camera: *Camera, world: World) void {
        camera.notice(world.viewing);
        const ticks: f32 = @floatFromInt(world.ticks);
        // What the shake from hits jitters by this frame, before it dies away some more, which the
        // game frames make it do (`main.gameFrames`).
        const shake: f32 = if (world.shake > 0) @min(world.shake, Cockpit.shake_most) * Cockpit.shake_share else 0;
        camera.shake_left = Cockpit.faded(world.shake);
        camera.cockpit_place = null;
        if (camera.bar_speed != 0) {
            camera.bars += ticks * camera.bar_speed * bar_rate;
            if (camera.bars >= 0) {
                if (camera.bars > letterbox) {
                    camera.bars = letterbox;
                    camera.bar_speed = 0;
                }
            } else {
                camera.bars = 0;
                camera.bar_speed = 0;
            }
        }
        switch (world.viewing.view) {
            .cockpit => if (world.viewing.cockpit_mode == .chase) {
                camera.place = camera.chase.frame(world.object.motion, world.object.position, world.object.orientation);
            } else {
                camera.place = cockpit(.cockpit, world.object.position, world.object.orientation, world.object.eye);
                if (world.cockpit) |model| camera.cockpit_place = Cockpit.place(model, &camera.recoil, shake, world.random);
                // The camera itself shakes with a hit, by what is left of it.
                if (shake > 0) camera.place.orientation = math.product(
                    Cockpit.jitter(camera.shake_left * Cockpit.camera_shake, world.random),
                    camera.place.orientation,
                );
            },
            .cockpit_left, .cockpit_right, .cockpit_rear => |side| {
                camera.place = if (side == .cockpit_rear and world.object.motion.ship_type.base() == .kamov)
                    kamovRear(world.object.position, world.object.orientation)
                else
                    cockpit(side, world.object.position, world.object.orientation, world.object.eye);
            },
            .chase, .spectator => if (world.object.motion.ship_type.hasStats()) {
                camera.place = camera.chase.frame(world.object.motion, world.object.position, world.object.orientation);
            },
            .target => if (world.target) |target| {
                camera.place = world.viewing.orbit.place(.target, target.position, target.radius);
            },
            .external => camera.place = world.viewing.orbit.place(.external, world.player.position, world.player.radius),
            .flyby => camera.place = flyby(camera.place.position, world.player.position, world.player.orientation, world.player.radius),
            .pull_back => camera.place = pullBack(world.object.position, world.object.orientation, world.shown()),
            .eject => camera.place = ejected(camera.cutaway, world.object.position, world.shown()),
            .pickup => camera.place = pickedUp(camera.cutaway, world.object.position, world.object.orientation, world.shown()),
            .pod_shot => {
                // Until the pod bursts, the view holds its time at nothing (`main.missionOver`).
                const since = if (world.player.exploding) world.shown() else 0;
                camera.place = podShot(camera.cutaway, world.player.position, world.object.position, since);
            },
            .launch_bay => {
                // Until the ship drops, the view holds its time at nothing (`gameFrame`).
                const since = if (world.dropping) world.shown() else 0;
                camera.place.orientation = math.product(world.player.orientation, math.fromAngles(bay_pitch - since * bay_tilt, 0, 0));
            },
            // `camera_ease_to_player` (`0x00461C60`) eases the view's angles toward looking at the
            // player's ship by a share, which every call gives as all the way: the look itself.
            .launch_below => camera.place = lookingAt(camera.place.position, world.player.position),
            .launch_aside => camera.place = lookingAt(camera.place.position, world.player.position),
            .yamato_beside => {
                camera.place = yamatoBeside(world.player, world.shown());
                if (world.game) |game| if (playerRunning(game, .launch)) |slot| if (slot.state.launch.style == .yamato) {
                    const state = slot.state.launch;
                    const step = state.step.as(yamato_launch.Step);
                    if (!state.step.reached(yamato_launch.Step.clear) or
                        (step == .clear and state.due + yamato_look_delay >= game.clock.frame_start))
                        camera.place.orientation = world.player.orientation;
                };
            },
            .yamato_ahead => {},
            .yamato_aside => camera.place = lookingAt(camera.place.position, world.player.position),
            // The Reliant's landing's views stand off the tube's middle each frame, turned as the
            // carrier is, looking at the player's ship and at the view's object. A landing in a
            // hangar bay uses the same two, standing off the gate's launch point and its doors.
            .landing_tube => if (world.landing) |landing| switch (landing) {
                .reliant => |tube| camera.place = lookingAt(tube.tube + math.transform(tube.carrier, landing_tube_offset), world.player.position),
                .bay => |bay| camera.place = lookingAt(bay.gate.point(bay_tube_radii * @as(Vector, @splat(world.player.radius))), world.player.position),
                .yamato => {},
            },
            .landing_aside => if (world.landing) |landing| switch (landing) {
                .reliant => |tube| camera.place = lookingAt(tube.tube + math.transform(tube.carrier, landing_aside_offset), world.object.position),
                .bay => |bay| camera.place = lookingAt(bay.mouth + math.transform(bay.gate.orientation, bay_aside_share * @as(Vector, @splat(bayReach(bay, world.object.radius)))), world.object.position),
                .yamato => {},
            },
            .landing_bay => if (world.landing) |landing| if (landing == .yamato) {
                const bay = landing.yamato;
                const since = @as(f32, @floatFromInt(@as(i64, world.now) - bay.due)) + world.ahead;
                camera.place = landingBay(bay.bay, bay.hangar, since, world.object.position);
            },
            .landing_ship => if (landingShip(world.player, world.shown())) |place| {
                camera.place = place;
            },
            .jump_out => camera.place = lookingAt(camera.place.position, world.object.position),
            .nanny_dock => camera.place = lookingAt(world.object.place().point(nanny_dock_offset), world.player.position),
            .warp_prepare => {
                const turn = math.rotation(.y, warp_prepare_yaw - world.shown() * warp_prepare_turn);
                const warping = if (world.game) |game| playerRunning(game, .warp_out) else null;
                const facing = if (warping) |slot| slot.state.warp.orientation else world.player.orientation;
                camera.place = .{
                    .position = world.player.position + math.transform(facing, math.transform(turn, warp_prepare_offset)),
                    .orientation = math.product(facing, turn),
                };
            },
            .warp_depart => {},
            .warp_arrive => if (world.game) |game| if (game.gates) |gates| if (gates.of(game.objects.player)) |record| {
                const distance = if (gates.grid.segments < @import("wgate/tunnel.zig").Grid.of(.high).segments) warp_arrive_distance_low else warp_arrive_distance;
                camera.place = lookingAt(record.warp_place.ahead(distance), world.player.position);
                camera.place.orientation = math.turned(camera.place.orientation, .z, world.shown() * warp_arrive_roll);
            },
            .jump_in_close => {
                camera.place = lookingAt(world.player.place().point(jumpCloseOffset(world.shown())), world.player.position);
                // The camera shakes with a hit, as the cockpit's does.
                if (shake > 0) camera.place.orientation = math.product(
                    Cockpit.jitter(camera.shake_left * Cockpit.camera_shake, world.random),
                    camera.place.orientation,
                );
            },
            .jump_in_ahead => {},
            .jump_in_aside => camera.place = lookingAt(camera.place.position, world.player.position),
            .director => if (world.game) |game| director.show(game, camera, world.viewing.director, world.ahead),
            .watch => camera.place = lookingAt(camera.place.position, world.object.position),
            .watch_marker => if (world.marker) |marker| {
                camera.place = lookingAt(camera.place.position, marker);
            },
            // Once its missile is gone, the view holds still (`gameFrame`).
            .missile => if (!world.viewing.missile_gone and world.object.motion.ship_type.hasStats()) {
                const game = world.game orelse return;
                const missile = game.objects.missiles.records[world.viewing.missile] orelse return;
                const object = &missile.slot.object;
                camera.place = camera.chase.follow(.{
                    .throttle = object.throttle,
                    .pitch_rate = object.pitch_rate,
                    .yaw_rate = object.yaw_rate,
                    .roll_rate = object.roll_rate,
                }, missile.slot.drawn.position, missile.slot.drawn.orientation);
            },
            else => {},
        }
    }

    /// The projection for the view and the bars on a screen of `width` by `height`, unstretched:
    /// the bay view's wide over the whole screen, whatever the bars (`camera_frame`); the views
    /// the player flies in, those without the bars, seeing `field_of_view` degrees up and down
    /// (`factorsFor`); and the other cutaways the game's, as their shots were framed.
    pub fn projection(camera: Camera, view: View, width: u32, height: u32, field_of_view: f32) srapi.Projection {
        if (view == .launch_bay) return .init(width, height, .{ 0, 0, 1, 1 }, unstretched(width, height, wide_factors));
        const base = if (view.letterboxed()) factors else factorsFor(field_of_view);
        return .init(width, height, .{ 0, camera.bars, 1, 1 - camera.bars }, unstretched(width, height, base));
    }
};

/// How long the missile view holds still once its missile has ended, before it goes back to the
/// cockpit (`camera_frame`, `0x00460C90`).
const missile_linger = 150;

/// The game's part of `camera_frame`, once a game frame: a view that can't go on goes back to the
/// player's cockpit, forced (`switchView`). Those are the chase and spectator views of an object
/// with no stats, the target view with no target, and the missile view of an object with no stats
/// or once its missile has been gone `missile_linger` ticks. Until the player's ship drops out of
/// its carrier's bay, the bay view holds its time at nothing (`launch.dropping`). The view aside
/// shows the mission's scene whole (`main.Showing`). In the director's view, the shot runs on, and
/// the next waiting begins once it is over.
///
/// First, while the camera shakes from hits by more than `shake_rumbles`, the controller plays the
/// shake too (`force_shake`, `0x004BE000`), as `camera_frame` begins.
pub fn gameFrame(world: gameobj.World) void {
    const viewing = &world.player.viewing;
    const all = world.objects;
    const now = world.clock.viewTime();
    if (world.forces) |forces| if (world.shake.* > shake_rumbles) forces.startUnlessPlaying(.shake, @intCast(now));
    const stats = all.slots[viewing.object orelse all.player].object.type.hasStats();
    const back = switch (viewing.view) {
        .chase, .spectator => !stats,
        .target => if (world.display) |display| display.target == null else false,
        .missile => back: {
            if (viewing.missile_gone) break :back viewing.switched < now;
            if (all.missiles.records[viewing.missile] == null) {
                viewing.switched = now + missile_linger;
                viewing.missile_gone = true;
                break :back false;
            }
            break :back !stats;
        },
        .launch_bay => back: {
            if (!launch.dropping(all, all.player)) viewing.switched = now;
            break :back false;
        },
        .launch_aside => back: {
            world.player.showing = .everything;
            break :back false;
        },
        // The director's shot runs on (`director.step`); once it is over, and the view with it,
        // the next shot waiting begins.
        .director => {
            director.step(world);
            if (viewing.view != .director) {
                viewing.shots.pop();
                shots.start(world);
            }
            return;
        },
        else => false,
    };
    if (back) _ = switchView(world, .cockpit, all.player, false, true);
}

/// The next missile in flight after `from`, going round the records, that `launcher` launched
/// (`camera_set_view`), or null for none.
fn nextMissile(records: *const missiles.Missiles, from: u8, launcher: u16) ?u8 {
    var at = from;
    for (0..missiles.max_missiles) |_| {
        at = @intCast((@as(usize, at) + 1) % missiles.max_missiles);
        const missile = records.records[at] orelse continue;
        if (missile.launcher == launcher) return at;
    }
    return null;
}

/// How hard the camera shakes from hits before the controller shakes with it (`0x004DC420`).
const shake_rumbles: f32 = 0.1;

// --- Cockpit ------------------------------------------------------------------------------------

/// The Kamov's rear view is from this far along its back instead of from its eye (`camera_frame`,
/// `0x00461307`).
pub const kamov_rear_distance: f32 = 1500;

fn kamovRear(position: Vector, orientation: Matrix) Place {
    const turned = math.turned(orientation, .y, std.math.pi);
    return .{ .position = position + math.transform(turned, .{ 0, 0, kamov_rear_distance }), .orientation = turned };
}

/// The camera in a cockpit view: turned from the object's orientation by the view's turn
/// (`View.cockpitTurn`), and at its eye point, the model header's `eye`, turned likewise.
pub fn cockpit(view: View, position: Vector, orientation: Matrix, eye: Vector) Place {
    const turned = math.turned(orientation, .y, std.math.degreesToRadians(view.cockpitTurn()));
    return .{ .position = position + math.transform(turned, eye), .orientation = turned };
}

// --- The cockpit's model ------------------------------------------------------------------------

/// The cockpit's model as `camera_frame` moves it in view 0 outside the chase mode. The mission's
/// start makes an object of the ship's cockpit frame (`0x005883F4`) and hangs its root from the
/// camera's frame; each frame the camera sways the root against the ship's turns and slides it
/// with its speed, and turns the hands, its second part, with the stick.
pub const Cockpit = struct {
    /// How far the root turns against each rate of turn at its full: its pitch, its yaw and its
    /// roll.
    pub const sway: [3]f32 = .{ -0.1, -0.15, -0.1 };
    /// How far it slides back at the cruise speed.
    pub const slide: f32 = 50;
    /// How far the hands turn: their pitch with the ship's pitch rate, and their roll with its
    /// roll and its yaw rates together.
    pub const hands_pitch: f32 = 0.15;
    pub const hands_roll: f32 = 0.2;
    /// How far the guns' kick moves the hands back at its full, and what is left of it the frame
    /// after.
    pub const recoil_kick: f32 = 30;
    pub const recoil_fade: f32 = 0.95;
    /// The shake from a hit: `hit_shake` goes no higher than `shake_most` (`0x004DC480`) and dies
    /// away by `shake_fade` a tick (`0x004DC4AC`); the root jitters by a random share of
    /// `root_jitter_share` (`0x004DC408`) of `shake_share` of it (`0x004DC420`), up to half of that
    /// either way, and the camera by a share of `camera_shake` of what is left (`0x004DC754`).
    pub const shake_most: f32 = 2;
    pub const shake_share: f32 = 0.1;
    pub const shake_fade: f32 = 0.02;
    pub const camera_shake: f32 = 0.03;
    pub const root_jitter_share: f32 = 0.5;

    /// What is left of the shake from hits `shake` a tick on, as `camera_frame` has it die away
    /// after each frame's work: no more than `shake_most`, less `shake_fade`, and no less than
    /// nothing.
    pub fn faded(shake: f32) f32 {
        if (!(shake > 0)) return shake;
        return @max(@min(shake, shake_most) - shake_fade, 0);
    }

    /// What moves the cockpit, and where its model stands.
    pub const Input = struct {
        /// The ship's rates of turn over its flight model's full ones: pitch, yaw and roll.
        rates: [3]f32,
        /// Its speed over its cruise speed (`object_cruise_speed`).
        speed: f32,
        /// The cockpit frame model's eye (its header's vector at `0x08`), which the root is set
        /// back by so that the eye stands at the camera.
        eye: Vector,
        /// Where the hands stand from the root, their part's position less the object's centre,
        /// and the point they turn about, their part's mount point.
        hands_origin: Vector,
        hands_pivot: Vector,
    };

    /// Where the root stands in the camera's frame, and the hands in the root's.
    pub const Placed = struct {
        root: Place,
        hands: Place,
    };

    /// Moves the cockpit for a frame. The rates and the speed count to 1 either way at most.
    pub fn place(model: Input, recoil: *f32, shake: f32, random: ?*Random) Placed {
        var rates = model.rates;
        for (&rates) |*rate| rate.* = std.math.clamp(rate.*, -1, 1);
        const speed = std.math.clamp(model.speed, -1, 1);
        const swayed = math.fromAngles(rates[0] * sway[0], rates[1] * sway[1], rates[2] * sway[2]);
        const root: Place = .{
            .position = Vector{ 0, 0, speed * slide } - model.eye,
            // The game halves each of the jitter's angles rather than the shake, which comes to the
            // same, since halving is exact.
            .orientation = math.product(jitter(shake * root_jitter_share, random), swayed),
        };

        const turn = math.fromAngles(rates[0] * hands_pitch, 0, (rates[2] + rates[1]) * hands_roll);
        var at = model.hands_origin;
        at[2] -= recoil.* * recoil_kick;
        recoil.* *= recoil_fade;
        // They turn about their mount point rather than their origin.
        at += model.hands_pivot - math.transform(turn, model.hands_pivot);
        return .{ .root = root, .hands = .{ .position = at, .orientation = turn } };
    }

    /// A turn of up to half of `amount` either way in yaw and in roll, as `camera_frame` draws two
    /// of `rand`'s numbers (`Random.centred`), the first for the roll. Without a `rand` it
    /// draws none, and does not turn.
    pub fn jitter(amount: f32, random: ?*Random) Matrix {
        const source = random orelse return math.identity;
        const roll = source.centred() * amount;
        const yaw = source.centred() * amount;
        return math.fromAngles(0, yaw, roll);
    }
};

test Cockpit {
    const model: Cockpit.Input = .{
        .rates = .{ 0, 0, 0 },
        .speed = 0,
        .eye = .{ 0, -100, 300 },
        .hands_origin = .{ 10, 20, 30 },
        .hands_pivot = .{ 0, 0, 50 },
    };
    // At rest the root stands back by the eye, unturned, and the hands where their part does.
    var recoil: f32 = 0;
    const still = Cockpit.place(model, &recoil, 0, null);
    try expectVector(.{ 0, 100, -300 }, still.root.position);
    try std.testing.expectEqual(math.identity, still.root.orientation);
    try expectVector(.{ 10, 20, 30 }, still.hands.position);

    // Flying at the cruise speed, the root slides 50 back; turning, it sways against the turn,
    // to no more than a full rate's worth.
    var moving = model;
    moving.speed = 3;
    moving.rates = .{ 2, 0, 0 };
    const swayed = Cockpit.place(moving, &recoil, 0, null);
    try expectVector(.{ 0, 100, -250 }, swayed.root.position);
    try math.testing.expectMatrixWithin(math.fromAngles(-0.1, 0, 0), swayed.root.orientation, 1e-6);

    // The guns' kick moves the hands back, and fades by a twentieth each frame.
    recoil = 1;
    const kicked = Cockpit.place(model, &recoil, 0, null);
    try expectVector(.{ 10, 20, 0 }, kicked.hands.position);
    try std.testing.expectApproxEqAbs(0.95, recoil, 1e-6);

    // The hands turn about their mount point: that point stays where it is.
    var turning = model;
    turning.rates = .{ 1, 0, 0 };
    const turned = Cockpit.place(turning, &recoil, 0, null);
    const pivot_after = turned.hands.position + math.transform(turned.hands.orientation, model.hands_pivot);
    try expectVector(model.hands_origin + model.hands_pivot - Vector{ 0, 0, 0.95 * 30 }, pivot_after);
}

test "the shake from a hit dies away and turns the camera" {
    // It goes no higher than 2, then dies away by 0.02 a tick, to nothing.
    try std.testing.expectApproxEqAbs(1.98, Cockpit.faded(3), 1e-6);
    try std.testing.expectApproxEqAbs(0.48, Cockpit.faded(0.5), 1e-6);
    try std.testing.expectEqual(0, Cockpit.faded(0.01));
    try std.testing.expectEqual(0, Cockpit.faded(0));

    var camera: Camera = .{};
    var viewing: Viewing = .{};
    var random: Random = .{};
    const ship: Subject = .{ .position = @splat(0), .orientation = math.identity };
    camera.frame(.{ .object = ship, .player = ship, .ticks = 10, .random = &random, .viewing = &viewing, .shake = 3 });
    // The frame shows what is left of the game's shake a tick on, which the game frames take it
    // down by.
    try std.testing.expectApproxEqAbs(1.98, camera.shake_left, 1e-6);
    // The camera is turned off the ship's own orientation.
    try std.testing.expect(!std.meta.eql(math.identity, camera.place.orientation));
    // Without a cockpit model there is nothing to place.
    try std.testing.expectEqual(null, camera.cockpit_place);
}

// --- Chase --------------------------------------------------------------------------------------

/// The chase view (`camera_chase`, `0x0045ED60`): behind the object and above it, the farther the
/// more throttle, swinging with its turns. Its state carries from frame to frame and is smoothed
/// once a frame.
pub const Chase = struct {
    /// Along the object's forward axis; negative is behind.
    distance: f32 = start_distance,
    pitch: f32 = 0,
    yaw: f32 = 0,
    roll: f32 = 0,

    /// Where the camera starts on switching to the view, ahead of the object, to swing round
    /// (`chase_distance`, `0x004F72A4`, as the executable holds it).
    pub const start_distance: f32 = 1500;

    /// A ship type's height, negative for above, and distance behind at no throttle.
    pub const Offset = struct { height: f32, distance: f32 };

    /// The type's offset (`camera_chase`): the heights are its immediates, and the distances
    /// `0x004DC580`, `0x004DC438`, `0x004DC744` and `0x004DC740`.
    pub fn offset(ship_type: gameobj.Type) Offset {
        return switch (ship_type.base()) {
            .grendel => .{ .height = -650, .distance = 1800 },
            .wolverine => .{ .height = -850, .distance = 2000 },
            .reaper => .{ .height = -800, .distance = 2400 },
            .kamov => .{ .height = -1000, .distance = 3400 },
            else => .{ .height = -750, .distance = 1800 },
        };
    }

    /// Farther back for each unit of throttle (`0x004DC5A8`); the afterburner counts as 1.5
    /// (`0x004DC4E0`).
    pub const throttle_distance: f32 = 400;
    pub const afterburner_throttle: f32 = 1.5;

    /// How the camera turns against the object's rates of turn, in radians per update, and how
    /// far it may: at most a sixteenth of a turn up or down and a tenth either way (`0x004F7288`
    /// to `0x004F72A0`, the limits each way).
    pub const pitch_swing: f32 = 5.7;
    pub const yaw_swing: f32 = 5;
    pub const roll_swing: f32 = 3;
    pub const pitch_limit: f32 = std.math.pi / 8.0;
    pub const turn_limit: f32 = std.math.pi / 5.0;

    /// What the pitch's swing is scaled by as the nose goes down, and as it goes up (`0x004DC4E0`,
    /// `0x004DC408`): nose up swings the camera a third as far as nose down.
    pub const nose_down_swing: f32 = 1.5;
    pub const nose_up_swing: f32 = 0.5;

    /// The share of the way to its target the distance, and the turns, go each frame (`0x004DC420`,
    /// `0x004DC474`).
    pub const distance_smoothing: f32 = 0.1;
    pub const turn_smoothing: f32 = 0.05;

    /// What the view follows of the object.
    pub const Motion = struct {
        ship_type: gameobj.Type = .of(.predator),
        throttle: f32 = 0,
        afterburner: bool = false,
        pitch_rate: f32 = 0,
        yaw_rate: f32 = 0,
        roll_rate: f32 = 0,
    };

    /// Levels the swing, as switching to the view does (`0x0045ED40`).
    pub fn resetTurns(chase: *Chase) void {
        chase.pitch = 0;
        chase.yaw = 0;
        chase.roll = 0;
    }

    /// Places the camera for this frame and moves the state on.
    pub fn frame(chase: *Chase, motion: Motion, position: Vector, orientation: Matrix) Place {
        const to = offset(motion.ship_type);
        const throttle = if (motion.afterburner) afterburner_throttle else motion.throttle;
        chase.distance = math.lerp(chase.distance, -(throttle * throttle_distance + to.distance), distance_smoothing);

        var swing = swings(motion);
        swing.pitch *= if (swing.pitch < 0) nose_up_swing else nose_down_swing;
        chase.pitch = math.lerp(chase.pitch, swing.pitch, turn_smoothing);
        chase.yaw = math.lerp(chase.yaw, swing.yaw, turn_smoothing);
        // The roll goes toward the roll's swing and the yaw's together, adding in the game's order.
        chase.roll += (swing.roll - chase.roll + swing.yaw) * turn_smoothing;
        return chase.placed(position, orientation, to.height);
    }

    /// The missile view's `camera_frame` (`0x0045FC90`, view `0x12`): the chase view's, behind a
    /// missile, 800 back and 400 more at full throttle, 300 above, swinging ten times slower, and
    /// rolling with a twentieth of its yaw.
    pub fn follow(chase: *Chase, motion: Motion, position: Vector, orientation: Matrix) Place {
        chase.distance = math.lerp(chase.distance, -(motion.throttle * throttle_distance + missile_distance), distance_smoothing);
        const swing = swings(motion);
        chase.pitch = math.lerp(chase.pitch, swing.pitch, missile_smoothing);
        chase.yaw = math.lerp(chase.yaw, swing.yaw, missile_smoothing);
        chase.roll += swing.yaw * missile_roll + (swing.roll - chase.roll) * missile_smoothing;
        return chase.placed(position, orientation, missile_height);
    }

    /// Behind a missile at no throttle, and above it (`0x004DC5EC`); how far the missile view's
    /// swings go a frame (`0x004DC4D0`), and how much of its yaw it rolls with (`0x004DC474`).
    pub const missile_distance: f32 = 800;
    pub const missile_height: f32 = -300;
    pub const missile_smoothing: f32 = 0.005;
    pub const missile_roll: f32 = 0.05;

    /// The swings the object's rates of turn ask for, each within its limit.
    fn swings(motion: Motion) struct { pitch: f32, yaw: f32, roll: f32 } {
        return .{
            .pitch = std.math.clamp(-pitch_swing * motion.pitch_rate, -pitch_limit, pitch_limit),
            .yaw = std.math.clamp(-yaw_swing * motion.yaw_rate, -turn_limit, turn_limit),
            .roll = std.math.clamp(-roll_swing * motion.roll_rate, -turn_limit, turn_limit),
        };
    }

    /// The camera `height` below the object and `distance` along it, swung by the pitch and then
    /// the yaw, and rolled by the roll.
    fn placed(chase: *const Chase, position: Vector, orientation: Matrix, height: f32) Place {
        const swung = math.turned(math.turned(orientation, .x, chase.pitch), .y, chase.yaw);
        return .{
            .position = position + math.transform(swung, .{ 0, height, chase.distance }),
            .orientation = math.turned(orientation, .z, chase.roll),
        };
    }
};

// --- Orbit --------------------------------------------------------------------------------------

/// The target and external views: the camera goes round an object, in the world's axes, and looks
/// at it. The arrow keys turn it, Shift with up or down moves it in or out. Its state is reset on
/// switching to either view.
pub const Orbit = struct {
    /// Degrees about `Y`, from 0 to 360.
    yaw: f32 = 0,
    /// Degrees about `X`, from -89.5 to 89.5.
    pitch: f32 = 0,
    /// Degrees a tick.
    yaw_speed: f32 = 0,
    pitch_speed: f32 = 0,
    /// Kept between `near` and the view's farthest, in the object's radii.
    distance: f32 = 0,

    /// How fast the arrow keys speed its turns up and let them settle, in degrees a tick for each
    /// tick, and how fast they turn it at most (`frame_controls`: `0x004DC420`, `0x004DC474`, and
    /// immediates at `0x004140ED`); how far up or down it goes (`0x004DC558`); and a full turn
    /// about `Y` (`0x004DC3E0`).
    pub const acceleration: f32 = 0.1;
    pub const deceleration: f32 = 0.05;
    pub const max_speed: f32 = 5;
    pub const max_pitch: f32 = 89.5;
    pub const full_turn: f32 = 360;
    /// Units a tick, with Shift held (`0x004DC560`).
    pub const zoom_speed: f32 = 60;

    /// The nearest it comes, and the farthest in the target view and in the external view, in the
    /// object's radii (`camera_frame`: `0x004DC794`, `0x004DC790`, `0x004DC78C`).
    pub const near: f32 = 1.8;
    pub const target_far: f32 = 5.8;
    pub const external_far: f32 = 3.8;

    pub fn far(view: View) f32 {
        return if (view == .target) target_far else external_far;
    }

    /// The keys that steer it, held this frame.
    pub const Keys = struct {
        left: bool = false,
        right: bool = false,
        up: bool = false,
        down: bool = false,
        shift: bool = false,
    };

    /// Steers the orbit for a frame `ticks` hundredths of a second long.
    pub fn steer(orbit: *Orbit, keys: Keys, ticks: f32) void {
        if (keys.left) {
            orbit.yaw_speed -= ticks * acceleration;
        } else if (keys.right) {
            orbit.yaw_speed += ticks * acceleration;
        }
        orbit.yaw_speed = settle(std.math.clamp(orbit.yaw_speed, -max_speed, max_speed), ticks);
        orbit.yaw += ticks * orbit.yaw_speed;
        if (orbit.yaw >= 0) {
            if (orbit.yaw > full_turn) orbit.yaw -= full_turn;
        } else {
            orbit.yaw += full_turn;
        }

        if (keys.shift and keys.up) {
            orbit.distance -= ticks * zoom_speed;
        } else if (keys.shift and keys.down) {
            orbit.distance += ticks * zoom_speed;
        } else if (keys.up) {
            orbit.pitch_speed += ticks * acceleration;
        } else if (keys.down) {
            orbit.pitch_speed -= ticks * acceleration;
        }
        orbit.pitch_speed = std.math.clamp(settle(orbit.pitch_speed, ticks), -max_speed, max_speed);
        orbit.pitch = std.math.clamp(orbit.pitch + ticks * orbit.pitch_speed, -max_pitch, max_pitch);
        if (@abs(orbit.pitch) == max_pitch) orbit.pitch_speed = 0;
    }

    /// A speed slowed toward 0 by the deceleration, stopping there.
    fn settle(speed: f32, ticks: f32) f32 {
        if (speed > 0) return @max(speed - ticks * deceleration, 0);
        if (speed < 0) return @min(speed + ticks * deceleration, 0);
        return 0;
    }

    /// Keeps the distance in range of `view` round an object of `radius`, as placing the camera
    /// does (`camera_frame`).
    pub fn keep(orbit: *Orbit, view: View, radius: f32) void {
        orbit.distance = std.math.clamp(orbit.distance, radius * near, radius * far(view));
    }

    /// Places the camera round an object of `radius` at `centre`, at a distance kept in range
    /// (`keep`).
    pub fn place(orbit: Orbit, view: View, centre: Vector, radius: f32) Place {
        var kept = orbit;
        kept.keep(view, radius);
        const turn = math.turned(math.turned(math.identity, .y, std.math.degreesToRadians(kept.yaw)), .x, std.math.degreesToRadians(kept.pitch));
        const position = centre + math.transform(turn, .{ 0, 0, kept.distance });
        return .{ .position = position, .orientation = math.lookAt(math.normalize(centre - position)) };
    }
};

// --- Pull back ---------------------------------------------------------------------------------

/// How `pull_back` starts behind the object and how fast it pulls away, a tick (`0x004DC508`,
/// `0x004DC788`).
const pull_back_distance: f32 = 3000;
const pull_back_speed: f32 = 10;
/// How fast `pull_back` and `eject` turn about their object, a tick (`0x004DC4D0`).
const slow_turn: f32 = 0.005;

/// View `pull_back` (`camera_frame`, view 8), `since` ticks after it was switched to: looking along
/// the object's heading turned about its own `Y`, from behind it along that heading.
pub fn pullBack(position: Vector, orientation: Matrix, since: f32) Place {
    return behind(position, orientation, since * slow_turn, pull_back_distance + since * pull_back_speed);
}

/// Turned as `orientation` turned by `angle` about its own `Y`, and standing `back` behind `point`
/// along its axis ahead, so looking at it: views 8 and `0x1C`.
fn behind(point: Vector, orientation: Matrix, angle: f32, back: f32) Place {
    const turned = math.turned(orientation, .y, angle);
    return .{ .position = point - math.forward(turned) * @as(Vector, @splat(back)), .orientation = turned };
}

/// Standing at `at` and looking at `target`, with no roll (`mat3_look_at`): the views that watch a
/// point from where they stand.
pub fn lookingAt(at: Vector, target: Vector) Place {
    return .{ .position = at, .orientation = math.lookAt(target - at) };
}

test pullBack {
    // It starts behind the object, looking along its heading, and pulls away as it turns.
    const start = pullBack(.{ 0, 0, 100 }, math.identity, 0);
    try std.testing.expectEqual(Vector{ 0, 0, 100 - pull_back_distance }, start.position);
    const later = pullBack(.{ 0, 0, 100 }, math.identity, 100);
    const away = later.position - Vector{ 0, 0, 100 };
    try std.testing.expectApproxEqAbs(pull_back_distance + 100 * pull_back_speed, @sqrt(math.dot(away, away)), 1e-2);
    try std.testing.expect(later.position[0] != 0);
}

// --- The launch ---------------------------------------------------------------------------------

/// The Yamato's view offsets (`camera_set_view`, views 16 and 17), and view 15's rise from
/// -600 to 300 at 0.0013 of the way per tick (`camera_frame`, `0x004DC768`).
const yamato_ahead_offset: Vector = .{ 0, -600, 40000 };
const yamato_aside_offset: Vector = .{ -800, 200, 5000 };
const yamato_ahead_pitch: f32 = 0.33;
const yamato_beside_start: Vector = .{ 1500, -600, 500 };
const yamato_beside_end: Vector = .{ 1500, 300, 500 };
const yamato_beside_rate: f32 = 0.0013;
/// View 15 starts looking at the ship after step 5's due tick plus 150 (`camera_frame`).
const yamato_look_delay = 150;

/// Nanny docking view offset (`camera_frame`, `0x00461AE3`).
const nanny_dock_offset: Vector = .{ 10000, -1800, -1400 };
/// Warp preparation camera yaw and turn per tick (`0x004DC408`, `0x004DC784`).
const warp_prepare_yaw: f32 = 0.5;
const warp_prepare_turn: f32 = 0.0005;
const warp_prepare_offset: Vector = .{ 0, -350, -2000 };
/// Highest-detail arrival distance and roll rate (`camera_frame`, `0x004DC77C`).
const warp_arrive_distance: f32 = 10000;
const warp_arrive_distance_low: f32 = 3000;
const warp_arrive_roll: f32 = -0.003;

/// The player's slot in `game`, where the player's ship runs `order`, for a view that reads that
/// order's state. In the game only Warp Out and the Yamato's launch switch to those views, which
/// read the state whatever order the ship runs. A script can switch to them at any time
/// (`camera.set_view`), so OpenReliant reads the state only while the order runs.
fn playerRunning(game: gameobj.World, order: Order) ?*const create.Slot {
    const slot = &game.objects.slots[game.objects.player];
    return if (slot.running(order) != null) slot else null;
}

fn yamatoBeside(player: Subject, since: f32) Place {
    const offset = math.lerp(yamato_beside_start, yamato_beside_end, since * yamato_beside_rate);
    return lookingAt(player.place().point(offset), player.position);
}

test "the Yamato cutaways follow or hold their original camera positions" {
    const player: Subject = .{ .position = .{ 100, 200, 300 }, .orientation = math.identity };
    var view: Camera = .{};
    var viewing: Viewing = .{};
    try std.testing.expect(testingSwitch(&viewing, &view, .yamato_ahead, 0, true, true, 0));
    view.placeYamato(.yamato_ahead, player);
    const ahead = view.place;
    try std.testing.expectEqual(Vector{ 100, -400, 40300 }, ahead.position);
    var moved = player;
    moved.position[2] += 1000;
    view.frame(.{ .object = moved, .player = moved, .ticks = 1, .now = 100, .viewing = &viewing });
    try std.testing.expectEqual(ahead, view.place);
    try std.testing.expect(testingSwitch(&viewing, &view, .yamato_aside, 0, true, true, 0));
    view.placeYamato(.yamato_aside, player);
    const aside = view.place.position;
    view.frame(.{ .object = moved, .player = moved, .ticks = 1, .now = 100, .viewing = &viewing });
    try std.testing.expectEqual(aside, view.place.position);
    try std.testing.expectApproxEqAbs(1, math.dot(math.forward(view.place.orientation), math.normalize(moved.position - aside)), 1e-6);
    try std.testing.expect(testingSwitch(&viewing, &view, .yamato_beside, 0, true, true, 0));
    view.placeYamato(.yamato_beside, player);
    view.frame(.{ .object = moved, .player = moved, .ticks = 1, .now = 1000, .viewing = &viewing });
    // The original extrapolates past the interpolation's end instead of clamping it.
    try std.testing.expectApproxEqAbs(770, view.place.position[1], 1e-3);
    try std.testing.expectEqual(moved.position[2] + 500, view.place.position[2]);
}

test "the views that read an order's state read it only while that order runs" {
    const aigeneric = @import("aigeneric.zig");
    var mission: gameobj.testing.Mission = undefined;
    try mission.init(std.testing.allocator);
    defer mission.deinit();
    const ship = try mission.add(.of(.predator), @splat(0));
    mission.objects.player = ship;
    const slot = mission.slot(ship);
    const player: Subject = .{ .position = .{ 100, 200, 300 }, .orientation = math.identity };
    const turned = math.rotation(.y, 1);
    for ([_]View{ .warp_prepare, .yamato_beside }) |shown| {
        var view: Camera = .{};
        var viewing: Viewing = .{};
        try std.testing.expect(testingSwitch(&viewing, &view, shown, ship, false, true, 0));
        view.frame(.{ .object = player, .player = player, .ticks = 1, .now = 0, .viewing = &viewing });
        const alone = view.place;
        // Another order's state, which the views would read as a turn and as a launch's step.
        try std.testing.expect(try aigeneric.push(mission.orders(), ship, .player_control, .none));
        slot.state.warp.orientation = turned;
        slot.state.launch.style = .yamato;
        try std.testing.expect(testingSwitch(&viewing, &view, shown, ship, false, true, 0));
        view.frame(.{ .object = player, .player = player, .ticks = 1, .now = 0, .game = mission.world(), .viewing = &viewing });
        try std.testing.expectEqual(alone, view.place);
        aigeneric.popAll(mission.orders(), ship);
    }
    // Warping out, the view turns as the ship stood when it lined up.
    var view: Camera = .{};
    var viewing: Viewing = .{};
    try std.testing.expect(try aigeneric.push(mission.orders(), ship, .warp_out, .none));
    slot.state.warp.orientation = turned;
    try std.testing.expect(testingSwitch(&viewing, &view, .warp_prepare, ship, false, true, 0));
    view.frame(.{ .object = player, .player = player, .ticks = 1, .now = 0, .game = mission.world(), .viewing = &viewing });
    try std.testing.expectApproxEqAbs(1, math.dot(math.forward(view.place.orientation), math.forward(math.product(turned, math.rotation(.y, warp_prepare_yaw)))), 1e-5);
}

/// Where the launch's views stand, in the frame of what they watch as they are switched to
/// (`camera_set_view`): the bay view 750 to the side of its ship, 600 above it and 300 behind
/// (`0x0045F6BF`), on the left for a gate of even number; the view from below 600 to the right of
/// the player's ship, 10000 below it and 100 ahead (`0x0045F737`); and the view aside 1700 to the
/// left of its ship and 6000 below (`0x0045F7B0`).
const bay_offset: Vector = .{ 750, -600, -300 };
const below_offset: Vector = .{ 600, 10000, 100 };
const aside_offset: Vector = .{ -1700, 6000, 0 };

/// How far down the bay view looks, turned about the player's ship's X axis from its nose
/// (`0x004DC760`), and how much further it tilts a tick once the ship drops (`0x004DC764`).
/// **Improvement:** 54 degrees, which the game rounds to 0.942478.
const bay_pitch: f32 = std.math.degreesToRadians(-54.0);
const bay_tilt: f32 = 0.0007;

// --- The landing --------------------------------------------------------------------------------

/// Where the landing's views stand, in the carrier's frame from the middle of the tube the ship
/// lands in (`camera_frame`): the tube view 500 to its right and 500 behind (`0x00460A17`), and
/// the view aside 3500 to its left, 1000 above and 3000 behind (`0x00460AB9`).
const landing_tube_offset: Vector = .{ 500, 0, -500 };
const landing_aside_offset: Vector = .{ -3500, -1000, -3000 };

/// OpenReliant's own: where the views of a landing in a hangar bay stand (`Landing.Bay`), in the
/// gate's frame: to its right, above it and out along the way the ship launches. They go by the
/// ship and the bay rather than by fixed distances, so that they frame a landing on any carrier.
/// The tube view stands in the bay off the gate's launch point, by the landing ship's radius: a
/// radius to the right, a third of one above and one and three quarters out, and watches the ship
/// come in and stop beside it. The view aside stands outside off the bay's mouth, by the bay's
/// reach (`bayReach`): a third of it to the side and out, and an eighth above, which the ship
/// passes on its way in.
const bay_tube_radii: Vector = .{ 1, -0.35, 1.75 };
const bay_aside_share: Vector = .{ 1.0 / 3.0, -1.0 / 8.0, 1.0 / 3.0 };

/// The least the bay's reach is, in radii of the ship landing in it, so that a shallow bay's view
/// aside isn't on top of the ship.
const bay_least_radii: f32 = 12;

/// The reach the view aside of a landing in a hangar bay goes by: the bay's depth, from the launch
/// point to the mouth, or `bay_least_radii` times the radius of the ship landing in it, whichever
/// is more.
fn bayReach(bay: Landing.Bay, radius: f32) f32 {
    return @max(bay.depth(), bay_least_radii * radius);
}

/// How the view from the Yamato's landing bay slides along it (`camera_frame`, view `0x0E`): over
/// `bay_slide_ticks` from the landing's due tick (`0x004DC774` holds its reciprocal), eased by a
/// cosine, its share `f` going from `bay_slide_from` up by `bay_slide` (`0x004DC408` and
/// `0x004DC4C0` added, `0x004DC770`); and how far down the hangar's height it stands, of its
/// bottom, the rest of its top (`0x004DC414`).
const bay_slide_ticks: f32 = 1100;
const bay_slide_from: f32 = 0.8;
const bay_slide: f32 = 0.45;
const bay_low: f32 = 0.95;

/// View `landing_bay` (`camera_frame`, view `0x0E`), `since` ticks after the landing's due tick:
/// halfway across the bay's hangar, of whose bounds `hangar` it stands `bay_low` of the way down,
/// and along it at `f` of its far end and `1 - f / 2` of its near end, as it slides
/// (`bay_slide_ticks`); turned level to face the ship at `object`. The hangar's frame is the bay's.
///
/// **Improvement:** the cosine and the angle come from `std.math` rather than the engine's tables
/// (`sr_cos`, `sr_atan2`).
fn landingBay(bay: Place, hangar: [2]Vector, since: f32, object: Vector) Place {
    const time = std.math.clamp(since / bay_slide_ticks, 0, 1);
    const eased = (1 - @cos(time * std.math.pi)) / 2;
    const f = bay_slide_from + eased * bay_slide;
    const local: Vector = .{
        (hangar[1][0] + hangar[0][0]) * 0.5,
        hangar[1][1] * bay_low + hangar[0][1] * (1 - bay_low),
        hangar[1][2] * f + hangar[0][2] * (1 - f * 0.5),
    };
    const position = bay.point(local);
    const off = object - position;
    return .{ .position = position, .orientation = math.fromAngles(0, std.math.atan2(off[0], off[2]), 0) };
}

/// Where view `landing_ship` stands from the player's ship (`camera_frame`, view `0x25`): for its
/// first `ship_above_ticks` (`0x00460877`), `ship_above` above it and higher by `ship_rise` a
/// tick, `ship_behind` behind, looking down by `ship_look_down` (`0x004DC76C`, `0x004DC59C`,
/// `0x0046088A`, `0x00460925`); then until `ship_aside_ticks` (`0x00460951`), `ship_aside` to its
/// left, `ship_aside_up` above and `ship_aside_ahead` ahead and on by a unit a tick, looking back
/// by `ship_look_back` (`0x00460984`, `0x0046097F`, `0x004DC508`, `0x004609FF`).
const ship_above_ticks: f32 = 700;
const ship_above: f32 = -1600;
const ship_rise: f32 = 2.5;
const ship_behind: f32 = -500;
const ship_look_down: f32 = -(std.math.pi / 2.0 - 0.4);
const ship_aside_ticks: f32 = 1500;
const ship_aside: f32 = -1000;
const ship_aside_up: f32 = -470;
const ship_aside_ahead: f32 = 3000;
const ship_look_back: f32 = std.math.pi - 0.3;

/// View `landing_ship` (`camera_frame`, view `0x25`), `since` ticks after it was switched to: from
/// the player's ship `ship`, above it and then beside it; null once it has run its course, after
/// which the camera stays where it was.
fn landingShip(ship: Subject, since: f32) ?Place {
    const local: Vector, const turn: Matrix = if (since < ship_above_ticks)
        .{ .{ 0, ship_above - since * ship_rise, ship_behind }, math.fromAngles(ship_look_down, 0, 0) }
    else if (since < ship_aside_ticks)
        .{ .{ ship_aside, ship_aside_up, since - ship_above_ticks + ship_aside_ahead }, math.fromAngles(0, ship_look_back, 0) }
    else
        return null;
    return .{ .position = ship.place().point(local), .orientation = math.product(ship.orientation, turn) };
}

// --- The jumps ----------------------------------------------------------------------------------

/// How far out along each of its ship's axes Jump Out's view stands (`camera_set_view`,
/// `0x0045FB18`).
const jump_out_reach: f32 = 8000;

/// Where the arrival's views stand from the player's ship as they are switched to, while it stands
/// far behind where it arrives (`jump.arrival_distance`): the view ahead 300 below it and 27000
/// ahead (`0x0045F8E7`), and the view aside 2000 to its left, 100 above it and 25000 ahead
/// (`0x0045F91E`).
const jump_ahead_offset: Vector = .{ 0, 300, 27000 };
const jump_aside_offset: Vector = .{ -2000, -100, 25000 };

/// The close view (`camera_frame`, `0x00460EC5`): 200 to the right of the player's ship and 500
/// above it (`0x00460F1A`), and ahead of it by `jump_close_near` for its first `jump_close_hold`
/// ticks, then by `jump_close_pull` a tick more until `jump_close_end`, and by `jump_close_far`
/// from then on (`0x00460ED2`, `0x004DC48C`, `0x004DC520`, `0x004DC75C`, `0x00460F09`).
const jump_close_side: f32 = 200;
const jump_close_height: f32 = -500;
const jump_close_near: f32 = 1200;
const jump_close_hold: f32 = 50;
const jump_close_pull: f32 = 10;
const jump_close_end: f32 = 70;
const jump_close_far: f32 = 1400;

/// Where the close view stands from the player's ship, `since` ticks after it was switched to.
fn jumpCloseOffset(since: f32) Vector {
    const ahead = if (since < jump_close_hold)
        jump_close_near
    else if (since < jump_close_end)
        (since - jump_close_hold) * jump_close_pull + jump_close_near
    else
        jump_close_far;
    return .{ jump_close_side, jump_close_height, ahead };
}

/// Standing at `at` and looking at `target`, with no roll in the frame `upright` turns to
/// (`camera_set_view`, `0x0045F956`): the look is taken between the two points turned back into
/// that frame, and turned out of it again.
fn levelLookingAt(at: Vector, target: Vector, upright: Matrix) Place {
    return .{ .position = at, .orientation = math.product(upright, math.lookAt(math.transformTransposed(upright, target - at))) };
}

test "Jump Out's view watches its ship go" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    const turned = math.rotation(.y, 1);
    const ship: Subject = .{ .position = .{ 100, 200, 300 }, .orientation = turned };
    try std.testing.expect(testingSwitch(&viewing, &camera, .jump_out, 3, true, true, 10));
    camera.placeJump(.jump_out, ship, ship);
    try std.testing.expect(viewing.locked);
    try expectVector(ship.place().point(@splat(jump_out_reach)), camera.place.position);
    // As the ship goes, the camera stays and turns after it.
    const gone: Subject = .{ .position = .{ 100, 200, 50000 }, .orientation = turned };
    camera.frame(.{ .object = gone, .player = gone, .ticks = 1, .now = 20, .viewing = &viewing });
    try expectVector(ship.place().point(@splat(jump_out_reach)), camera.place.position);
    try expectVector(math.normalize(gone.position - camera.place.position), math.forward(camera.place.orientation));
}

test "the arrival's views" {
    const turned = math.product(math.rotation(.x, 0.5), math.rotation(.y, 1));
    const ship: Subject = .{ .position = .{ 1000, -2000, 3000 }, .orientation = turned };

    // Close: ahead of the ship, looking back at it, pulling away between 50 and 70 ticks in.
    var close: Camera = .{};
    var viewing: Viewing = .{};
    try std.testing.expect(testingSwitch(&viewing, &close, .jump_in_close, 0, true, true, 100));
    close.placeJump(.jump_in_close, ship, ship);
    for ([_]struct { u32, f32 }{ .{ 100, 1200 }, .{ 150, 1200 }, .{ 160, 1300 }, .{ 170, 1400 }, .{ 400, 1400 } }) |at| {
        close.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = at[0], .viewing = &viewing });
        try expectVector(ship.place().point(.{ 200, -500, at[1] }), close.place.position);
        try expectVector(math.normalize(ship.position - close.place.position), math.forward(close.place.orientation));
    }

    // Ahead: held where it was put, level in the ship's frame, looking at where the ship was.
    var ahead: Camera = .{};
    try std.testing.expect(testingSwitch(&viewing, &ahead, .jump_in_ahead, 0, true, true, 100));
    ahead.placeJump(.jump_in_ahead, ship, ship);
    const held = ahead.place;
    try expectVector(ship.place().point(jump_ahead_offset), held.position);
    try expectVector(math.normalize(ship.position - held.position), math.forward(held.orientation));
    try std.testing.expectApproxEqAbs(0, math.dot(math.xAxis(held.orientation), math.yAxis(turned)), 1e-5);
    const moved: Subject = .{ .position = ship.place().point(.{ 0, 0, 25000 }), .orientation = turned };
    ahead.frame(.{ .object = moved, .player = moved, .ticks = 1, .now = 200, .viewing = &viewing });
    try std.testing.expectEqual(held, ahead.place);

    // Aside: where it was put, watching the ship fly in.
    var aside: Camera = .{};
    try std.testing.expect(testingSwitch(&viewing, &aside, .jump_in_aside, 0, true, true, 100));
    aside.placeJump(.jump_in_aside, ship, ship);
    aside.frame(.{ .object = moved, .player = moved, .ticks = 1, .now = 200, .viewing = &viewing });
    try expectVector(ship.place().point(jump_aside_offset), aside.place.position);
    try expectVector(math.normalize(moved.position - aside.place.position), math.forward(aside.place.orientation));
}

// --- The ejection -------------------------------------------------------------------------------

/// How far out to its object's right the eject view stands (`0x0045F479`).
const eject_reach: f32 = 5000;

/// View `eject` (`camera_frame`, view 7), `since` ticks after it was switched to: `cutaway` out
/// from the pod at `position`, turned about the world's `Y` by `slow_turn` a tick, looking at the
/// pod.
pub fn ejected(cutaway: Vector, position: Vector, since: f32) Place {
    return lookingAt(math.transform(math.rotation(.y, since * slow_turn), cutaway) + position, position);
}

/// The share of the way from the picking ship to the pod that the pickup view looks at
/// (`0x0045FAAC`); how fast it turns about the picking ship, a tick, and from where it starts
/// (`0x004DC74C`, `0x004DC51C`); and how far off it starts, how fast it closes in, a tick, and how
/// near it comes (`0x004DC43C`, `0x004DC44C`).
///
/// **Improvement:** it starts a quarter turn round exactly, where the game has 0.785398.
const pickup_share: f32 = 0.5;
const pickup_turn: f32 = 0.002;
const pickup_start: f32 = std.math.pi / 4.0;
const pickup_reach: f32 = 10000;
const pickup_closing: f32 = 2;
const pickup_nearest: f32 = 1000;

/// View `pickup` (view `0x1C`), `since` ticks after it was switched to: the picking ship's
/// orientation turned about its own `Y`, `pickup_start` on and more by `pickup_turn` a tick,
/// looking along it at `cutaway` from the ship at `position`, from `pickup_reach` off and closing.
pub fn pickedUp(cutaway: Vector, position: Vector, orientation: Matrix, since: f32) Place {
    const off = @max(pickup_reach - since * pickup_closing, pickup_nearest);
    return behind(cutaway + position, orientation, since * pickup_turn + pickup_start, off);
}

/// How far behind the pod the pod-shot view stands, and how fast it pulls back once the pod bursts,
/// a tick (`0x004DC44C`, `0x004DC72C`).
const pod_shot_reach: f32 = 1000;
const pod_shot_pull: f32 = 20;

/// View `pod_shot` (view `0x1D`), `since` ticks after the pod at `pod` began to burst:
/// `pod_shot_reach` and more from it, the other way from `cutaway`, the way to the Sabre, looking
/// at the Sabre at `sabre`.
pub fn podShot(cutaway: Vector, pod: Vector, sabre: Vector, since: f32) Place {
    return lookingAt(pod - cutaway * @as(Vector, @splat(pod_shot_reach + since * pod_shot_pull)), sabre);
}

test ejected {
    // Out to the right of the pod, looking at it, and a quarter turn round after a while.
    const start = ejected(.{ eject_reach, 0, 0 }, .{ 0, 0, 100 }, 0);
    try std.testing.expectEqual(Vector{ eject_reach, 0, 100 }, start.position);
    const quarter = std.math.pi / 2.0 / slow_turn;
    const later = ejected(.{ eject_reach, 0, 0 }, .{ 0, 0, 100 }, quarter);
    try std.testing.expectApproxEqAbs(0, later.position[0], 5);
    try std.testing.expectApproxEqAbs(eject_reach, @abs(later.position[2] - 100), 5);
    const looking = math.forward(later.orientation);
    try std.testing.expect(math.dot(looking, math.normalize(Vector{ 0, 0, 100 } - later.position)) > 0.999);
}

test pickedUp {
    // It starts out at its reach, closes in two a tick, and comes no nearer than its nearest.
    const cutaway: Vector = .{ 0, 0, 7500 };
    const start = pickedUp(cutaway, @splat(0), math.identity, 0);
    try std.testing.expectApproxEqAbs(pickup_reach, math.distance(start.position, cutaway), 1e-2);
    const later = pickedUp(cutaway, @splat(0), math.identity, 1000);
    try std.testing.expectApproxEqAbs(pickup_reach - 2000, math.distance(later.position, cutaway), 1e-2);
    const last = pickedUp(cutaway, @splat(0), math.identity, 100000);
    try std.testing.expectApproxEqAbs(pickup_nearest, math.distance(last.position, cutaway), 1e-2);
}

test "Camera.setCutaway" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    const turned: Subject = .{ .position = .{ 0, 0, 100 }, .orientation = math.rotation(.y, std.math.pi / 2.0) };
    const pod: Subject = .{ .position = .{ 0, 0, 1000 }, .orientation = math.identity };
    // The eject view stands off the object's right.
    try std.testing.expect(testingSwitch(&viewing, &camera, .eject, 0, true, true, 10));
    camera.placeCutaway(.eject, turned, turned);
    try expectVector(math.xAxis(turned.orientation) * @as(Vector, @splat(eject_reach)), camera.cutaway);
    try std.testing.expect(viewing.locked);
    try std.testing.expectEqual(10, viewing.switched);
    // The pickup view looks halfway from the picking ship to the pod.
    try std.testing.expect(testingSwitch(&viewing, &camera, .pickup, 1, true, true, 20));
    camera.placeCutaway(.pickup, turned, pod);
    try expectVector(.{ 0, 0, 450 }, camera.cutaway);
    // The pod-shot view stands off the pod the other way from the Sabre.
    try std.testing.expect(testingSwitch(&viewing, &camera, .pod_shot, 1, true, true, 30));
    camera.placeCutaway(.pod_shot, turned, pod);
    try expectVector(.{ 0, 0, -1 }, camera.cutaway);
    // Locked as they are, only another forced switch takes the camera from them.
    try std.testing.expect(!testingSwitch(&viewing, &camera, .chase, 0, false, false, 40));
}

test "Camera.setLaunch" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    // The ship faces along the world's X axis, its own left along +Z.
    const ship: Subject = .{ .position = .{ 0, 0, 1000 }, .orientation = math.rotation(.y, std.math.pi / 2.0) };
    // The bay view stands beside it, on the left for a gate of even number, above and behind.
    try std.testing.expect(testingSwitch(&viewing, &camera, .launch_bay, 0, true, true, 10));
    camera.placeLaunch(.launch_bay, ship, ship, true);
    try expectVector(.{ -300, -600, 1750 }, camera.place.position);
    try std.testing.expect(viewing.locked);
    try std.testing.expect(testingSwitch(&viewing, &camera, .launch_bay, 0, true, true, 10));
    camera.placeLaunch(.launch_bay, ship, ship, false);
    try expectVector(.{ -300, -600, 250 }, camera.place.position);
    // The view from below stands far under the player's ship, looking up at it.
    try std.testing.expect(testingSwitch(&viewing, &camera, .launch_below, 0, true, true, 20));
    camera.placeLaunch(.launch_below, ship, ship, true);
    try expectVector(.{ 100, 10000, 400 }, camera.place.position);
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
    // The view aside stands to the ship's left and below it.
    try std.testing.expect(testingSwitch(&viewing, &camera, .launch_aside, 0, true, true, 30));
    camera.placeLaunch(.launch_aside, ship, ship, true);
    try expectVector(.{ 0, 6000, 2700 }, camera.place.position);
}

test "the landing's views stand off the carrier's tube, watching the ship" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    const ship: Subject = .{ .position = .{ 0, -3000, 5000 }, .orientation = math.identity };
    const landing: Landing = .{ .reliant = .{ .tube = .{ 0, 0, 1000 }, .carrier = math.rotation(.y, std.math.pi) } };
    try std.testing.expect(testingSwitch(&viewing, &camera, .landing_tube, 0, true, true, 10));
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 10, .landing = landing, .viewing = &viewing });
    // Turned with the carrier, half a turn round: 500 to the left of the tube and 500 ahead.
    try expectVector(.{ -500, 0, 1500 }, camera.place.position);
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
    try std.testing.expect(testingSwitch(&viewing, &camera, .landing_aside, 0, true, true, 20));
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 20, .landing = landing, .viewing = &viewing });
    try expectVector(.{ 3500, -1000, 4000 }, camera.place.position);
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
}

test "a landing in a hangar bay's views stand off the gate's launch point and its doors" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    // A gate launching ships astern, half a turn round, its bay's mouth 10000 astern of its point;
    // a ship of radius 800 landing, so that the bay's depth is its reach.
    const landing: Landing = .{ .bay = .{
        .gate = .{ .position = .{ 0, 0, 1000 }, .orientation = math.rotation(.y, std.math.pi) },
        .mouth = .{ 0, 0, -9000 },
    } };
    const ship: Subject = .{ .position = .{ 0, -3000, -20000 }, .orientation = math.identity, .radius = 800 };
    try std.testing.expectEqual(10000, bayReach(landing.bay, 800));
    try std.testing.expect(testingSwitch(&viewing, &camera, .landing_tube, 0, true, true, 10));
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 10, .landing = landing, .viewing = &viewing });
    // Turned with the gate, by the ship's radius: 800 to the left of its point, 280 above and
    // 1400 astern of it.
    try expectVector(.{ -800, -280, -400 }, camera.place.position);
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
    try std.testing.expect(testingSwitch(&viewing, &camera, .landing_aside, 0, true, true, 20));
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 20, .landing = landing, .viewing = &viewing });
    // Off the mouth, by the bay's depth: a third of it to the gate's left and out astern, and an
    // eighth above.
    try expectVector(.{ -10000.0 / 3.0, -1250, -9000 - 10000.0 / 3.0 }, camera.place.position);
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
    // A shallow bay's reach is twelve of the ship's radii instead.
    try std.testing.expectEqual(9600, bayReach(.{ .gate = landing.bay.gate, .mouth = .{ 0, 0, 500 } }, 800));
}

test "the Yamato's landing's views" {
    // From the bay: halfway across its hangar, low in it, sliding along it, facing the ship.
    const hangar: [2]Vector = .{ .{ -100, -200, -300 }, .{ 100, 0, 700 } };
    const bay: Place = .{ .position = .{ 0, 0, 1000 } };
    const ship: Vector = .{ 0, -10, 3000 };
    const before = landingBay(bay, hangar, -50, ship);
    try expectVector(.{ 0, -10, 1380 }, before.position);
    try expectVector(.{ 0, 0, 1 }, math.forward(before.orientation));
    try expectVector(.{ 0, -10, 1762.5 }, landingBay(bay, hangar, bay_slide_ticks, ship).position);
    // From the player's ship: above it and rising, then beside it, then held where it was.
    const player: Subject = .{ .position = @splat(0), .orientation = math.identity };
    try expectVector(.{ 0, -1850, -500 }, landingShip(player, 100).?.position);
    try expectVector(.{ -1000, -470, 3100 }, landingShip(player, 800).?.position);
    try std.testing.expectEqual(null, landingShip(player, ship_aside_ticks));
}

test "the launch's views follow the ship" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    var ship: Subject = .{ .position = .{ 0, 0, 1000 }, .orientation = math.identity };
    _ = testingSwitch(&viewing, &camera, .launch_bay, 0, true, true, 10);
    camera.placeLaunch(.launch_bay, ship, ship, true);
    // Until the ship drops, the bay view looks 54 degrees down from its nose (`gameFrame` holds its
    // time).
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 50, .viewing = &viewing });
    const looking = math.forward(camera.place.orientation);
    try std.testing.expectApproxEqAbs(@sin(std.math.degreesToRadians(54.0)), looking[1], 1e-6);
    // Once it drops, the view tilts further down after it.
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 150, .dropping = true, .viewing = &viewing });
    try std.testing.expect(math.forward(camera.place.orientation)[1] > looking[1]);

    // The views from below and aside keep looking at the ship as it goes.
    _ = testingSwitch(&viewing, &camera, .launch_aside, 0, true, true, 200);
    camera.placeLaunch(.launch_aside, ship, ship, true);
    ship.position = .{ 0, 3000, 1000 };
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 210, .viewing = &viewing });
    try expectVector(math.normalize(ship.position - camera.place.position), math.forward(camera.place.orientation));
}

test "the views that move with time go on between ticks" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    const ship: Subject = .{ .position = .{ 0, 0, 100 }, .orientation = math.identity };
    // Half a tick past its hundredth, view 8 stands where it would a hundred and a half ticks on.
    _ = testingSwitch(&viewing, &camera, .pull_back, 0, true, true, 0);
    camera.frame(.{ .object = ship, .player = ship, .ticks = 1, .now = 100, .ahead = 0.5, .viewing = &viewing });
    try expectVector(pullBack(ship.position, ship.orientation, 100.5).position, camera.place.position);
    // The pod-shot view holds at nothing until the pod bursts, the time past the tick with it. The
    // game holds its time meanwhile (`main.missionOver`).
    const sabre: Subject = .{ .position = .{ 0, 0, 5000 }, .orientation = math.identity };
    try std.testing.expect(testingSwitch(&viewing, &camera, .pod_shot, 1, true, true, 0));
    camera.placeCutaway(.pod_shot, sabre, ship);
    camera.frame(.{ .object = sabre, .player = ship, .ticks = 1, .now = 200, .ahead = 0.5, .viewing = &viewing });
    try expectVector(podShot(camera.cutaway, ship.position, sabre.position, 0).position, camera.place.position);
}

test podShot {
    // Behind the pod from the Sabre, looking at it, and pulling back once the pod bursts.
    const way = math.normalize(Vector{ 2, 1, -2 });
    const sabre = way * @as(Vector, @splat(30000));
    const start = podShot(way, @splat(0), sabre, 0);
    try std.testing.expectApproxEqAbs(pod_shot_reach, math.length(start.position), 1e-2);
    try std.testing.expect(math.dot(math.forward(start.orientation), way) > 0.999);
    const later = podShot(way, @splat(0), sabre, 100);
    try std.testing.expectApproxEqAbs(pod_shot_reach + 100 * pod_shot_pull, math.length(later.position), 1e-2);
}

// --- Flyby --------------------------------------------------------------------------------------

/// The flyby view stays where it is, looking at the player, until the player is farther than this
/// (`camera_frame`, `0x004DC778`); then it moves ahead of the player, a radius below and
/// `flyby_ahead` radii ahead (`0x004DC424`).
pub const flyby_range: f32 = 23000;
pub const flyby_ahead: f32 = 4;

/// Places the flyby camera, from where it was, for a ship at `position` with `orientation` and
/// `radius`. It never comes nearer than a radius.
pub fn flyby(from: Vector, position: Vector, orientation: Matrix, radius: f32) Place {
    var at = from;
    if (math.length(at - position) > flyby_range) {
        at = position + math.transform(orientation, .{ 0, radius, radius * flyby_ahead });
    }
    if (math.length(at - position) < radius) {
        at = position + math.normalize(at - position) * @as(Vector, @splat(radius));
    }
    return lookingAt(at, position);
}

/// Whether `actual` is `expected`, each of its axes within a thousandth.
fn expectVector(expected: Vector, actual: Vector) !void {
    return math.testing.expectVectorWithin(expected, actual, 1e-3);
}

/// For the tests: switches `viewing`, with nothing to refuse it, as `switchView` does in a game,
/// and `drawn` takes the switch up at once, as the drawn frame does.
fn testingSwitch(viewing: *Viewing, drawn: *Camera, view: View, object: ?u16, lock: bool, force: bool, now: u32) bool {
    if (!viewing.set(view, object, lock, force, now, .{})) return false;
    drawn.notice(viewing);
    return true;
}

/// For the tests: the camera's keys over a frame `ticks` long, and the switch to the view they pick
/// at tick `now`, as the controls' frame makes it (`main.controlsFrame`).
fn testingKeys(camera: *Camera, viewing: *Viewing, devices: *input.Devices, ticks: u32, now: u32) void {
    if (viewing.frameControls(devices, ticks, null)) |chosen| _ = testingSwitch(viewing, camera, chosen, 0, false, false, now);
}

test unstretched {
    // At 4:3 the game's own; wider screens widen the view rather than stretch it.
    const four_three = unstretched(1024, 768, factors);
    try std.testing.expectApproxEqAbs(factors[0], four_three[0], 1e-4);
    const camera: Camera = .{};
    const sixteen_nine = camera.projection(.cockpit, 1920, 1080, original_field_of_view);
    try std.testing.expectApproxEqAbs(sixteen_nine.scale[0], sixteen_nine.scale[1], 1e-3);
    try std.testing.expect(sixteen_nine.bounds[2] > 1.1);
    try std.testing.expectApproxEqAbs(0.625, sixteen_nine.bounds[3], 1e-4);
    // The bay view projects wider, over the whole screen whatever the bars.
    const wide: Camera = .{ .bars = letterbox };
    const bay = wide.projection(.launch_bay, 1024, 768, original_field_of_view);
    try std.testing.expect(bay.scale[1] < four_three[1] * 768);
    try std.testing.expectEqual(0, bay.viewport[1]);
    try std.testing.expectEqual(768, bay.viewport[3]);
}

test factorsFor {
    // The game's own at its field of view, about 64 degrees up and down.
    try std.testing.expectApproxEqAbs(64.01, original_field_of_view, 0.01);
    const own = factorsFor(original_field_of_view);
    for (factors, own) |expected, actual| try std.testing.expectApproxEqRel(expected, actual, 1e-6);
    // At 90 degrees, the screen spans a view unit either side of the middle, up and down.
    const square = factorsFor(90);
    try std.testing.expectApproxEqAbs(0.5, square[1], 1e-6);
    try std.testing.expectApproxEqAbs(0.375, square[0], 1e-6);
    // The views the player flies in see what the setting says; the cutaways keep the game's.
    const flying: Camera = .{};
    try std.testing.expectApproxEqAbs(1, flying.projection(.cockpit, 1024, 768, 90).bounds[3], 1e-4);
    try std.testing.expectApproxEqAbs(0.625, flying.projection(.director, 1024, 768, 90).bounds[3], 1e-4);
}

test "no switch of view while the player's ship rides the worm" {
    var gates: wgate.Gates = undefined;
    gates.riding = true;
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    // Refused, forced or not, and the frame drawn next is no cut.
    const asked: Request = .{ .view = .external, .object = 0, .force = true, .now = 10 };
    try std.testing.expect(!camera.ask(&viewing, asked, .{ .gates = &gates }));
    try std.testing.expect(!camera.cut);
    try std.testing.expectEqual(View.cockpit, viewing.view);
    try std.testing.expectEqual(0, camera.requests.count);
    // Out of the worm, it goes ahead.
    gates.riding = false;
    try std.testing.expect(camera.ask(&viewing, asked, .{ .gates = &gates }));
    try std.testing.expectEqual(View.external, viewing.view);
}

test "the drawing side's switches of view are the game's once it takes them up" {
    var mission: gameobj.testing.Mission = undefined;
    try mission.init(std.testing.allocator);
    defer mission.deinit();
    const all = mission.objects;
    const ship = try mission.add(.of(.predator), @splat(0));
    var game: Viewing = .{};
    var held: shots.Held = .{ .objects = all };
    held.ships.set(ship);
    game.holding = held;
    var camera: Camera = .{};
    // A mod's script switches to the director's view: the drawn frame's copy of the view switches,
    // and the camera cuts to it at once, but the game's view and the ships stay as they were.
    var copy = game;
    try std.testing.expect(camera.ask(&copy, .{ .view = .director, .object = null, .now = 10 }, .{}));
    try std.testing.expectEqual(View.director, copy.view);
    try std.testing.expect(camera.cut);
    try std.testing.expectEqual(View.cockpit, game.view);
    try std.testing.expect(!all.slots[ship].object.flags.jumping);
    // The game makes the switch as it takes it up, at the tick it was asked at, holding the shot's
    // ships, with no change for the camera to cut to again.
    game.takeUp(&camera.requests, .{}, null);
    try std.testing.expectEqual(View.director, game.view);
    try std.testing.expectEqual(10, game.switched);
    try std.testing.expect(all.slots[ship].object.flags.jumping);
    camera.cut = false;
    camera.notice(&game);
    try std.testing.expect(!camera.cut);
    // `--watch`'s switch lasts, and the camera cuts to it once the game has made it, as it next
    // frames. Out of the director's view, the shot's ships go.
    copy = game;
    try std.testing.expect(camera.ask(&copy, .{ .view = .watch, .object = ship, .lock = true, .force = true, .now = 20, .lasting = true, .cut_at_once = false }, .{}));
    try std.testing.expect(copy.lasting and !camera.cut);
    game.takeUp(&camera.requests, .{}, null);
    try std.testing.expectEqual(View.watch, game.view);
    try std.testing.expect(game.locked and game.lasting);
    try std.testing.expect(!all.slots[ship].object.flags.jumping);
    camera.notice(&game);
    try std.testing.expect(camera.cut);
    // A switch is taken up once.
    game.view = .cockpit;
    game.takeUp(&camera.requests, .{}, null);
    try std.testing.expectEqual(View.cockpit, game.view);
    // Past as many as the game takes up at once, a switch is refused.
    copy = game;
    for (0..most_requests) |at| try std.testing.expect(camera.ask(&copy, .{ .view = .chase, .object = ship, .force = true, .now = @intCast(at) }, .{}));
    try std.testing.expect(!camera.ask(&copy, .{ .view = .external, .object = ship, .force = true, .now = 30 }, .{}));
    try std.testing.expectEqual(View.chase, copy.view);
}

test Camera {
    const ship: Subject = .{
        .position = .{ 0, 0, 1000 },
        .orientation = math.identity,
        .eye = .{ 0, -100, 300 },
        .radius = 500,
    };
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    try std.testing.expect(testingSwitch(&viewing, &camera, .cockpit, 0, false, false, 10));
    camera.frame(.{ .object = ship, .player = ship, .ticks = 3, .viewing = &viewing });
    try expectVector(.{ 0, -100, 1300 }, camera.place.position);
    try std.testing.expect(viewing.inside(0));
    try std.testing.expect(!viewing.inside(1));

    // The cockpit key in the cockpit view cycles the mode: to the cockpit model, then the chase,
    // which starts from its start distance as the camera next frames.
    try std.testing.expectEqual(View.cockpit, viewing.key(.cockpit_camera).?);
    try std.testing.expectEqual(CockpitMode.cockpit, viewing.cockpit_mode);
    camera.chase.distance = 0;
    _ = viewing.key(.cockpit_camera);
    try std.testing.expectEqual(CockpitMode.chase, viewing.cockpit_mode);
    try std.testing.expect(!viewing.inside(0));
    try std.testing.expectEqual(0, camera.chase.distance);
    camera.frame(.{ .object = ship, .player = ship, .ticks = 3, .viewing = &viewing });
    try std.testing.expect(camera.chase.distance > 0);
    try std.testing.expect(camera.place.position[2] > 1000);

    // A locked camera refuses a switch unless forced; cutaways bring in the bars. A switch that
    // goes ahead is a cut, which the frame drawn next draws no streaks across.
    camera.cut = false;
    try std.testing.expect(testingSwitch(&viewing, &camera, .pull_back, 0, true, false, 20));
    try std.testing.expect(camera.cut);
    camera.cut = false;
    try std.testing.expect(!testingSwitch(&viewing, &camera, .external, 0, false, false, 30));
    try std.testing.expect(!camera.cut);
    try std.testing.expectEqual(1, camera.bar_speed);
    for (0..40) |_| camera.frame(.{ .object = ship, .player = ship, .ticks = 3, .viewing = &viewing });
    try std.testing.expectEqual(letterbox, camera.bars);
    try std.testing.expectEqual(0, camera.bar_speed);
    try std.testing.expectApproxEqAbs(76.8, camera.projection(viewing.view, 1024, 768, original_field_of_view).viewport[1], 1e-3);

    // Forced to the external view: bars gone, orbiting the player at the nearest it may.
    try std.testing.expect(testingSwitch(&viewing, &camera, .external, 0, false, true, 40));
    try std.testing.expectEqual(0, camera.bars);
    camera.frame(.{ .object = ship, .player = ship, .ticks = 3, .viewing = &viewing });
    try expectVector(.{ 0, 0, 1000 + 500 * Orbit.near }, camera.place.position);

    // The target view needs a target; without one the camera holds still, until the game goes
    // back to the cockpit (`gameFrame`).
    _ = testingSwitch(&viewing, &camera, .target, 0, false, false, 50);
    const held = camera.place;
    camera.frame(.{ .object = ship, .player = ship, .ticks = 3, .viewing = &viewing });
    try std.testing.expectEqual(held, camera.place);
    // With one, it goes round the target at the nearest it may.
    var target = ship;
    target.position = .{ 5000, 0, 0 };
    target.radius = 100;
    _ = testingSwitch(&viewing, &camera, .target, 0, false, false, 60);
    camera.frame(.{ .object = ship, .player = ship, .target = target, .ticks = 3, .viewing = &viewing });
    try expectVector(.{ 5000, 0, 100 * Orbit.near }, camera.place.position);
}

test View {
    try std.testing.expect(View.cockpit_rear.fromCockpit());
    try std.testing.expect(!View.chase.fromCockpit());
    try std.testing.expect(!View.external.letterboxed());
    try std.testing.expect(View.missile.letterboxed());
    try std.testing.expect(!View.target.letterboxed());
    // The last few views have no bars, but for the table's last.
    try std.testing.expect(!@as(View, @fromBackingInt(0x28)).letterboxed());
    try std.testing.expect(@as(View, @fromBackingInt(0x2B)).letterboxed());
    // A view past the table has no record.
    try std.testing.expectEqual(null, @as(View, @fromBackingInt(0x2C)).record());
    try std.testing.expect(!@as(View, @fromBackingInt(0x2C)).fromCockpit());
    // Each named view has its own string; the cutaways share theirs.
    try std.testing.expectEqual(170, View.cockpit.name().?);
    try std.testing.expectEqual(180, View.external.name().?);
    try std.testing.expectEqual(View.chase.name(), @as(View, @fromBackingInt(0x0D)).name());
    // The lock shows from the cockpit's views and the chase view, but not under its second number.
    try std.testing.expect(View.cockpit_rear.showsLock() and View.chase.showsLock());
    try std.testing.expect(!View.spectator.showsLock() and !View.target.showsLock());
    try std.testing.expectEqual(-90, View.cockpit_left.cockpitTurn());
    try std.testing.expectEqual(0, View.chase.cockpitTurn());
    try std.testing.expectEqual(View.external, keyView(.external_camera).?);
    try std.testing.expectEqual(null, keyView(.fire_lasers));
    try std.testing.expectEqual(CockpitMode.open, CockpitMode.chase.next());
    try std.testing.expectEqual(CockpitMode.cockpit, CockpitSetting.cockpit.mode());
    try std.testing.expectEqual(CockpitMode.chase, CockpitSetting.chase.mode());
    try std.testing.expectEqual(CockpitMode.open, CockpitSetting.none.mode());
    try std.testing.expectEqual(CockpitMode.open, @as(CockpitSetting, @fromBackingInt(7)).mode());
}

test cockpit {
    const eye: Vector = .{ 0, -100, 300 };
    const ahead = cockpit(.cockpit, .{ 10, 0, 0 }, math.identity, eye);
    try expectVector(.{ 10, -100, 300 }, ahead.position);
    // Looking back, the eye point turns with the view.
    const rear = cockpit(.cockpit_rear, .{ 0, 0, 0 }, math.identity, eye);
    try expectVector(.{ 0, -100, -300 }, rear.position);
    try expectVector(.{ 0, 0, -1 }, math.transform(rear.orientation, .{ 0, 0, 1 }));
    // Looking left: forward turns to -X.
    try expectVector(.{ -1, 0, 0 }, math.transform(cockpit(.cockpit_left, @splat(0), math.identity, eye).orientation, .{ 0, 0, 1 }));
}

test Chase {
    var chase: Chase = .{};
    // Level flight at half throttle: the distance closes on -2000, a tenth of the way a frame.
    const still = chase.frame(.{ .throttle = 0.5 }, .{ 0, 0, 0 }, math.identity);
    try std.testing.expectApproxEqAbs(1500 + (-2000 - 1500) * 0.1, chase.distance, 1e-3);
    try expectVector(.{ 0, -750, chase.distance }, still.position);
    for (0..200) |_| _ = chase.frame(.{ .throttle = 0.5 }, .{ 0, 0, 0 }, math.identity);
    try std.testing.expectApproxEqAbs(-2000, chase.distance, 1e-2);

    // Turning, the camera swings the other way, within its limit.
    for (0..400) |_| _ = chase.frame(.{ .yaw_rate = 1 }, .{ 0, 0, 0 }, math.identity);
    try std.testing.expectApproxEqAbs(-Chase.turn_limit, chase.yaw, 1e-3);
    try std.testing.expectEqual(Chase.Offset{ .height = -1000, .distance = 3400 }, Chase.offset(.of(.kamov)));
}

test Orbit {
    var orbit: Orbit = .{};
    // Held right for a while, the orbit turns ever faster up to its limit, less the frame's
    // slowing, which comes after.
    for (0..100) |_| orbit.steer(.{ .right = true }, 3);
    try std.testing.expectApproxEqAbs(Orbit.max_speed - 3 * Orbit.deceleration, orbit.yaw_speed, 1e-5);
    // Let go, it slows to a stop.
    for (0..100) |_| orbit.steer(.{}, 3);
    try std.testing.expectEqual(0, orbit.yaw_speed);
    try std.testing.expect(orbit.yaw >= 0 and orbit.yaw < 360);
    // Pitched all the way, it stops at the limit.
    for (0..400) |_| orbit.steer(.{ .up = true }, 3);
    try std.testing.expectEqual(Orbit.max_pitch, orbit.pitch);

    var level: Orbit = .{};
    const place = level.place(.external, .{ 0, 0, 100 }, 50);
    // Placed at the nearest it may be, ahead along +Z, looking back at the centre; the orbit
    // itself is kept in range only where the game keeps it.
    try expectVector(.{ 0, 0, 190 }, place.position);
    try expectVector(.{ 0, 0, -1 }, math.transform(place.orientation, .{ 0, 0, 1 }));
    try std.testing.expectEqual(0, level.distance);
    level.keep(.external, 50);
    try std.testing.expectEqual(90, level.distance);
}

test "the orbit's zoom stays in range as the keys steer it" {
    var viewing: Viewing = .{};
    var devices: input.Devices = .{};
    viewing.view = .external;
    // Shift and down pull it out, as far as the external view's farthest.
    devices.keyboard.down[input.scan.left_shift] = true;
    devices.keyboard.down[input.scan.down] = true;
    for (0..100) |_| _ = viewing.frameControls(&devices, 1, 50);
    try std.testing.expectEqual(50 * Orbit.external_far, viewing.orbit.distance);
    // Shift and up bring it in from there at once, as far as the nearest.
    devices.keyboard.down[input.scan.down] = false;
    devices.keyboard.down[input.scan.up] = true;
    _ = viewing.frameControls(&devices, 1, 50);
    try std.testing.expectEqual(50 * Orbit.external_far - Orbit.zoom_speed, viewing.orbit.distance);
    for (0..100) |_| _ = viewing.frameControls(&devices, 1, 50);
    try std.testing.expectEqual(50 * Orbit.near, viewing.orbit.distance);
}

test flyby {
    // Too far: the camera moves ahead of the ship, and looks back at it.
    const place = flyby(.{ 0, 0, 30000 + 23000 }, .{ 0, 0, 0 }, math.identity, 100);
    try expectVector(.{ 0, 100, 400 }, place.position);
    // Too near: it backs off to a radius.
    try expectVector(.{ 0, 0, 100 }, flyby(.{ 0, 0, 10 }, .{ 0, 0, 0 }, math.identity, 100).position);
}

test "Camera.frameControls" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    var devices: input.Devices = .{};
    const keyboard = &devices.keyboard;
    // The external camera's key, 7, picks its view once for the press.
    keyboard.down[controls.binding(.external_camera).key] = true;
    testingKeys(&camera, &viewing, &devices, 1, 100);
    try std.testing.expectEqual(View.external, viewing.view);
    try std.testing.expectEqual(100, viewing.switched);
    viewing.switched = 0;
    testingKeys(&camera, &viewing, &devices, 1, 200);
    try std.testing.expectEqual(0, viewing.switched);

    // In it, the left arrow turns the orbit.
    keyboard.down[input.scan.left] = true;
    testingKeys(&camera, &viewing, &devices, 10, 300);
    try std.testing.expect(viewing.orbit.yaw_speed < 0);

    // The cockpit key, pressed in the cockpit view, cycles the cockpit mode.
    _ = testingSwitch(&viewing, &camera, .cockpit, 0, false, false, 0);
    keyboard.* = .{};
    keyboard.down[controls.binding(.cockpit_camera).key] = true;
    testingKeys(&camera, &viewing, &devices, 1, 400);
    try std.testing.expectEqual(CockpitMode.cockpit, viewing.cockpit_mode);
}

test "the hat switches views while it is held" {
    var camera: Camera = .{};
    var viewing: Viewing = .{};
    var devices: input.Devices = .{};
    devices.joystick.hats = 1;
    const pov = &devices.joystick.state.pov[0];

    // Holding the hat left selects the left view, again every frame.
    pov.* = 27000;
    testingKeys(&camera, &viewing, &devices, 1, 100);
    try std.testing.expectEqual(View.cockpit_left, viewing.view);
    testingKeys(&camera, &viewing, &devices, 1, 200);
    try std.testing.expectEqual(200, viewing.switched);
    // Releasing it returns to the front view; a diagonal selects nothing.
    pov.* = input.JoystickState.centred;
    testingKeys(&camera, &viewing, &devices, 1, 300);
    try std.testing.expectEqual(View.cockpit, viewing.view);
    pov.* = 4500;
    testingKeys(&camera, &viewing, &devices, 1, 400);
    try std.testing.expectEqual(300, viewing.switched);

    // Without HatEnable, the hat does nothing.
    pov.* = 18000;
    devices.settings.hat_enabled = false;
    testingKeys(&camera, &viewing, &devices, 1, 500);
    try std.testing.expectEqual(View.cockpit, viewing.view);
    devices.settings.hat_enabled = true;
    testingKeys(&camera, &viewing, &devices, 1, 600);
    try std.testing.expectEqual(View.cockpit_rear, viewing.view);
}

test gameFrame {
    var mission: gameobj.testing.Mission = undefined;
    try mission.init(std.testing.allocator);
    defer mission.deinit();
    const ship = try mission.add(.of(.predator), @splat(0));
    mission.objects.player = ship;
    const world = mission.world();
    const viewing = &mission.player.viewing;
    // With nothing drawn, until the ship drops out of the bay, the bay view holds its time at
    // nothing.
    try std.testing.expect(switchView(world, .launch_bay, ship, true, true));
    mission.clock.mission_ticks = 50;
    gameFrame(world);
    try std.testing.expectEqual(50, viewing.switched);
    try std.testing.expectEqual(View.launch_bay, viewing.view);
    // The chase view of an object with no stats goes back to the player's cockpit.
    const marker = try mission.add(.of(.marker), @splat(0));
    try std.testing.expect(switchView(world, .chase, marker, false, true));
    gameFrame(world);
    try std.testing.expectEqual(View.cockpit, viewing.view);
    try std.testing.expectEqual(ship, viewing.object.?);
    // The launch's view aside shows the whole scene.
    mission.player.showing = .launch;
    try std.testing.expect(switchView(world, .launch_aside, ship, true, true));
    gameFrame(world);
    try std.testing.expectEqual(.everything, mission.player.showing);
}

test "the shake from hits plays on the controller" {
    const gpa = std.testing.allocator;
    var mission: gameobj.testing.Mission = undefined;
    try mission.init(gpa);
    defer mission.deinit();
    mission.objects.player = try mission.add(.of(.predator), @splat(0));
    var made: input.force.testing.Made = .{};
    defer made.deinit(gpa);
    try made.add(gpa, .shake, &.{.{ .id = 0, .name = "Cosine1", .kind = 2, .type = 103, .duration = 1000, .rest = &.{ 14, 30, @bitCast(@as(i32, -30)) } }});
    var forces: input.force.Forces = .{ .library = &made.library, .feedback = true };
    var world = mission.world();
    world.forces = &forces;
    // A light shake leaves the controller still; past `shake_rumbles`, the game frame plays it.
    world.shake.* = shake_rumbles;
    gameFrame(world);
    try std.testing.expect(!forces.playing(.shake, 0));
    world.shake.* = 0.5;
    mission.clock.mission_ticks = 10;
    gameFrame(world);
    try std.testing.expect(forces.playing(.shake, 10));
}

test "the missile view" {
    var armed: missiles.testing.Armed = undefined;
    try armed.init(std.testing.allocator);
    defer armed.deinit();
    const player = try armed.add(.friendly, @splat(0));
    const other = try armed.add(.hostile, .{ 0, 0, 50000 });
    const mission = &armed.mission;
    var camera: Camera = .{};
    const world = mission.world();
    const viewing = &mission.player.viewing;
    // With none of the player's in flight, the view is refused.
    try std.testing.expect(!switchView(world, .missile, player, false, false));
    missiles.launch(world, other, 0, .none);
    missiles.launch(world, player, 0, .none);
    try std.testing.expect(!switchView(world, .missile, other + 1, false, false));
    // It follows the player's, behind and above it, easing out from where the chase view left it.
    try std.testing.expect(switchView(world, .missile, player, false, false));
    try std.testing.expectEqual(1, viewing.missile);
    const subject: Subject = .{ .position = @splat(0), .orientation = math.identity, .motion = .{ .ship_type = .of(.predator) } };
    camera.frame(.{ .object = subject, .player = subject, .ticks = 1, .now = 10, .game = world, .viewing = viewing });
    const missile = armed.missile(1);
    try std.testing.expectEqual(missile.slot.drawn.position[1] + Chase.missile_height, camera.place.position[1]);
    // Once it ends, the view holds for a second and a half, then the game goes back to the cockpit.
    missiles.end(world, 1);
    mission.clock.mission_ticks = 20;
    gameFrame(world);
    try std.testing.expect(viewing.missile_gone);
    mission.clock.mission_ticks = 170;
    gameFrame(world);
    try std.testing.expectEqual(View.missile, viewing.view);
    mission.clock.mission_ticks = 171;
    gameFrame(world);
    try std.testing.expectEqual(View.cockpit, viewing.view);
}