dte.zig

//! `.DTE` missions: the 44 campaign and multiplayer missions, and everything scripted in them.
//!
//! A mission is a fixed-capacity image. A 27-entry directory at offset zero gives each section a
//! count and an offset, and the offsets are the same in every mission built from the same
//! template, so a section is a reservation that a mission fills as far as it needs.
//!
//! Inside a `.HOG` the image is RefPack compressed; a mission sitting loose in `missions\` is
//! stored expanded. `hog.Archive.read` handles the first case, so this module always sees the
//! expanded form.

const std = @import("std");
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;

const layout = @import("layout.zig");
const refpack = @import("refpack.zig");
const commands = @import("../engine/game/executor/commands.zig");
const conditions = @import("../engine/vm/conditions.zig");
const opcodes = @import("../engine/vm/opcodes.zig");

pub const section_count = 27;

/// Writing mission files and their scripts.
pub const write = @import("dte/write.zig");
pub const assemble = @import("dte/assemble.zig");
/// A script's instructions as text.
pub const listing = @import("dte/listing.zig");
/// A routine's code as statements (#1127).
pub const statements = @import("dte/statements.zig");
/// Reading a routine's bytecode as statements.
pub const decompile = @import("dte/decompile.zig");
/// Whether two missions are the same mission.
pub const same = @import("dte/same.zig");

/// Identity and typed references for mission source collections (#608).
pub const source = @import("dte/source.zig");

/// What each directory slot holds. Sections the loader reads but this module does not interpret
/// keep their index as a name.
pub const Section = enum(u8) {
    /// NUL-terminated names, addressed by byte offset rather than by index.
    strings = 0,
    operands_a = 1,
    /// `u16` name offset and a `u32` value, read and written by script.
    globals = 2,
    /// The ships: every ship, station and nav point the mission places.
    ships = 3,
    /// Flight groups, stride `0x14`. Each starts with its object ID.
    flight_groups = 4,
    triggers = 5,
    /// The script bytecode. Its count is in **halfwords**, so the section is `count * 2` bytes.
    script = 6,
    /// The object table, indexed by object ID: see [`Object`].
    objects = 7,
    /// One [`Part`] per named script routine in `script`, which the loader turns into the table
    /// `call_part` indexes.
    parts = 8,
    unknown_9 = 9,
    /// One flag per bytecode byte, which the interpreter consults for the script debugger.
    script_flags = 10,
    targets = 11,
    /// Squads, stride `0x0C`. Each starts with its object ID, and lists its members in
    /// `squad_members`.
    squads = 12,
    /// Squad membership records, stride `0x0C`: the member's object ID at `+0` and the owning
    /// squad's index at `+4`. A squad's records are consecutive.
    squad_members = 13,
    /// The formations ([`Formation`]), which the formation orders fly flight groups into.
    formations = 14,
    /// The formations' points ([`FormationPoint`]).
    formation_points = 15,
    /// The curves, stride `0x44` ([`Curve`]): paths from one of the mission's ships to another,
    /// which the director's camera flies along.
    curves = 16,
    /// Part descriptors for `script_b`, in the same form as `parts`.
    parts_b = 17,
    /// A second bytecode section, counted in halfwords like `script`. Empty in every shipped
    /// mission.
    script_b = 18,
    unused_19 = 19,
    unused_20 = 20,
    /// **OpenReliant's own:** the mission's name, as `OpenReliantName` keeps it. The game binds
    /// this section into a local variable of its binder and reads nothing of it, and no shipped
    /// mission has one.
    openreliant_name = 21,
    operands_b = 22,
    unknown_23 = 23,
    /// One word of flags per Executor command (`CommandFlags`), which `command` sets its flag by
    /// before each call. It reads the word the command's number places past the section's offset,
    /// whatever the section's count. In the missions of the writer's template each word has a bit
    /// for each of the command's parameters, save six whose word is 0
    /// (`write.template.command_flags`). The other missions either leave the section unused, at
    /// `DirectoryEntry.unused_offset`, inside section 1, whose operands then serve as the flags in
    /// the game and the template's in OpenReliant, or start it at the file's end, past which
    /// OpenReliant takes none.
    command_flags = 24,
    /// The same for the second, empty command catalogue.
    command_flags_b = 25,
    /// A third table of operands, which `0x004529D0` picks among `operands_a` and `operands_b` by a
    /// bank number.
    operands_c = 26,
    _,

    /// The bytes each of the section's records takes, which its directory count counts: bytes for
    /// the string pool, the script flags and OpenReliant's name, halfwords for the scripts. Null
    /// where the record's size is not known, as for section 20, which every shipped mission leaves
    /// empty.
    pub fn stride(section: Section) ?u8 {
        return switch (section) {
            .strings, .script_flags, .openreliant_name => 1,
            .operands_a, .script, .script_b, .operands_b, .operands_c, .unknown_23, .command_flags, .command_flags_b => 2,
            .unknown_9, .targets => 4,
            .formations => @sizeOf(Formation),
            .objects => @sizeOf(Object),
            .globals, .squads, .squad_members, .unused_19 => 0x0C,
            .formation_points => @sizeOf(FormationPoint),
            .flight_groups => @sizeOf(FlightGroup),
            .parts, .parts_b => @sizeOf(Part),
            .triggers => @sizeOf(Trigger),
            .curves => @sizeOf(Curve),
            .ships => @sizeOf(Ship),
            .unused_20, _ => null,
        };
    }
};

pub const DirectoryEntry = extern struct {
    /// Records in use, not the capacity reserved for them.
    count: u16,
    _unused: u8,
    formats: Formats,
    offset: u32,

    /// Sections the template reserves but this mission does not use.
    pub const unused_offset: u32 = 0xFFFF;

    /// The entry of a section the mission doesn't use.
    pub const unused: DirectoryEntry = .{ .count = 0, ._unused = 0, .formats = .{}, .offset = unused_offset };

    /// Four flags, in the low bits, which binding the mission notes where any section has them
    /// (`mission_bind_section`); nothing reads them. Every entry of a shipped mission holds the
    /// same: all four in most, the first three in `mission191` and `mission271`, the first two in
    /// `mission801` and the first alone in `mission88`.
    pub const Formats = packed struct(u8) {
        first: bool = false,
        second: bool = false,
        third: bool = false,
        fourth: bool = false,
        /// Kept as the file has them, though no shipped mission sets them.
        _unused: u4 = 0,

        pub const all: Formats = .{ .first = true, .second = true, .third = true, .fourth = true };

        /// These flags, with each that `other` sets set too, as binding notes them section by
        /// section. The bits past the four are left as they are.
        pub fn noting(formats: Formats, other: Formats) Formats {
            return .{
                .first = formats.first or other.first,
                .second = formats.second or other.second,
                .third = formats.third or other.third,
                .fourth = formats.fourth or other.fourth,
                ._unused = formats._unused,
            };
        }

        /// The flags as the file holds them, for a listing.
        pub fn byte(formats: Formats) u8 {
            return @bitCast(formats);
        }
    };

    pub fn isUsed(entry: DirectoryEntry) bool {
        return entry.offset != unused_offset;
    }

    comptime {
        assert(@sizeOf(DirectoryEntry) == 8);
    }
};

/// One placed object: a ship, a capital ship, a station or a nav point.
pub const Ship = extern struct {
    /// The ship's object ID: its index into the object table.
    object_id: u32,
    /// Byte offset into the string pool.
    name: u16,
    _unknown_06: u16,
    /// Mirrored from `position` when the mission loads, then copied from the live object's position
    /// by `mission_ships_sync` (`0x0045A5F0`).
    runtime_position: [3]f32,
    /// Index of the ship's flight group, or `no_flight_group`.
    flight_group: u8,
    /// The record of `pilotstats.bin` that flies the ship (`object_set_pilot`), or `no_pilot`, as
    /// the player's own record, the nav points and the planets have.
    pilot: u8,
    _unknown_16: u8,
    /// The engine's own state: zero in the files, and cleared for every ship when the mission's
    /// script starts.
    flags: Flags,
    /// Role. Ordinary ships stay below `0x100`; nav points and markers use 999 and the `0x3E3` to
    /// `0x3E8` range, so reading this as a byte truncates many of them.
    kind: u16,
    _unknown_1a: u8,
    /// Set for a waypoint once binding the mission has listed it (`mission_list_waypoints`).
    waypoint_listed: u8,
    /// As authored. The loader copies it into `runtime_position`.
    position: [3]f32,
    /// The kind of the ship it launches from, where `launch_gate` names a gate: the first of the
    /// mission's ships of that kind (`mission_ship_create`).
    launch_from: u16,
    _unknown_2a: u8,
    /// The gate of that ship it launches through, which its Launch order takes as its target's
    /// component, or `no_launch`.
    launch_gate: u8,
    runtime_yaw: i16,
    /// Whole degrees. The engine scales it by pi/180, which is what proves the unit.
    yaw: i16,
    /// The ship's components that are still intact, a bit each (`componentIntact`). Set to
    /// `all_intact` when the mission's script starts; destroying component `n` clears bit `n & 31`
    /// (`loseComponent`).
    intact_components: u32,
    /// Its place in a formation, by its index in `formation_points`, which the formation orders
    /// fly it to, or `no_formation_point`. With the next two bytes it makes a reference: the tag of
    /// `formation_points` where it names a point, `none` where it names none, then 0xFF.
    formation_point: u16,
    formation_point_tag: Reference.Tag,
    _unknown_37: u8,
    runtime_pitch: i16,
    pitch: i16,
    _unknown_3c: u8,
    /// The loadout tier its missile racks are fitted by (`create_object`), as `create.settledTier`
    /// settles it: 0 or 255, as most records hold, asks for the campaign's.
    tier: u8,
    _unknown_3e: [2]u8,
    /// For a point (`point_kind`) that marks a place on a curve: the curve's index, which
    /// `markedCurve` gives, and the share of the way along it the place lies at, which the
    /// director's camera reaches as it passes (`0x00457510`). -1 and 0 elsewhere.
    marker_curve: i16,
    _unknown_42: [2]u8,
    marker_at: f32,
    runtime_roll: i16,
    roll: i16,

    /// The `flight_group` of a ship in none.
    pub const no_flight_group: u8 = 0xFF;

    /// The `pilot` of a record flown by no pilot of `pilotstats.bin`.
    pub const no_pilot: u8 = 0xFF;

    /// The `launch_gate` of a ship that does not launch.
    pub const no_launch: u8 = 0xFF;

    /// The `formation_point` of a ship in no formation.
    pub const no_formation_point: u16 = 0xFFFF;
    /// The `tier` most records hold, which asks for the campaign's loadout tier.
    pub const campaign_tier: u8 = 0xFF;

    /// The `launch_from` of a ship that doesn't launch, as every shipped record holds.
    pub const no_launch_from: u16 = 0xFFFF;

    /// The `marker_curve` of a record that marks no curve.
    pub const no_marked_curve: i16 = -1;

    /// A ship with nothing set: in no flight group, flown by no pilot, launching from nothing, in
    /// no formation and marking no curve, with every component intact. The bytes the engine
    /// doesn't read hold what most of the shipped missions' ships hold.
    pub const blank: Ship = blank: {
        var ship = std.mem.zeroes(Ship);
        ship.flight_group = no_flight_group;
        ship.pilot = no_pilot;
        ship.launch_from = no_launch_from;
        ship._unknown_2a = 0xFF;
        ship.launch_gate = no_launch;
        ship.intact_components = all_intact;
        ship.formation_point = no_formation_point;
        ship.formation_point_tag = .none;
        ship._unknown_37 = 0xFF;
        ship._unknown_3c = 0xFF;
        ship.tier = campaign_tier;
        ship.marker_curve = no_marked_curve;
        ship._unknown_42 = .{ 0xFF, 0xFF };
        break :blank ship;
    };

    /// The `kind` of a waypoint: a point a flight group's Patrol Route flies through, in the order
    /// the mission lists them.
    pub const waypoint_kind: u16 = 0x3E5;

    /// Its flight group, where it is in one.
    pub fn flightGroup(ship: Ship) ?u8 {
        return if (ship.flight_group == no_flight_group) null else ship.flight_group;
    }

    /// Its point in a formation, where it has one.
    pub fn formationPoint(ship: Ship) ?u16 {
        return if (ship.formation_point == no_formation_point) null else ship.formation_point;
    }

    /// Its pilot, where it has one.
    pub fn pilotRecord(ship: Ship) ?u8 {
        return if (ship.pilot == no_pilot) null else ship.pilot;
    }

    /// The gate it launches through, where it launches.
    pub fn launchGate(ship: Ship) ?u8 {
        return if (ship.launch_gate == no_launch) null else ship.launch_gate;
    }

    /// The `intact_components` of a ship whose components are all intact.
    pub const all_intact: u32 = std.math.maxInt(u32);

    /// Whether its component `component` is intact: bit `component & 31` of `intact_components`.
    pub fn componentIntact(ship: Ship, component: u8) bool {
        return ship.intact_components & componentBit(component) != 0;
    }

    /// Its component `component` is destroyed: bit `component & 31` of `intact_components` clears.
    pub fn loseComponent(ship: *align(1) Ship, component: u8) void {
        ship.intact_components &= ~componentBit(component);
    }

    fn componentBit(component: u8) u32 {
        return @as(u32, 1) << @as(u5, @truncate(component));
    }

    /// Whether it is a waypoint (`waypoint_kind`).
    pub fn isWaypoint(ship: Ship) bool {
        return ship.kind == waypoint_kind;
    }

    /// The `kind` of a point the mission marks, such as where a ship jumps in, or a place on a
    /// curve (`marker_curve`).
    pub const point_kind: u16 = 0x3E3;

    /// The `kind` of the points the curves run between, and of those their tangents are drawn to.
    pub const curve_point_kind: u16 = 0x3E4;

    /// The `kind` of a mission's nav points (`mission_ship_create`, `0x00457CD9`), which
    /// ShipReached's watches look from as from a waypoint (`0x0045B105`).
    pub const nav_point_kind: u16 = 999;

    /// Whether it is a nav point or one of the mission's markers, a waypoint or a point, which
    /// `mission_ship_create` (`0x00457CD9` to `0x00457CF7`) makes a marker object of rather than a
    /// ship.
    pub fn isMarker(ship: Ship) bool {
        return switch (ship.kind) {
            nav_point_kind, waypoint_kind, curve_point_kind, point_kind => true,
            else => false,
        };
    }

    /// The curve whose place it marks, where it is a point that marks one.
    pub fn markedCurve(ship: Ship) ?u16 {
        if (ship.kind != point_kind) return null;
        return std.math.cast(u16, ship.marker_curve);
    }

    pub const Flags = packed struct(u8) {
        /// Set when the engine raises the ship's Destroyed event, which it then raises no more.
        destroyed: bool,
        _unknown: u7,
    };

    comptime {
        assert(@offsetOf(Ship, "name") == 0x04);
        assert(@offsetOf(Ship, "pilot") == 0x15);
        assert(@offsetOf(Ship, "kind") == 0x18);
        assert(@offsetOf(Ship, "position") == 0x1C);
        assert(@offsetOf(Ship, "launch_from") == 0x28);
        assert(@offsetOf(Ship, "launch_gate") == 0x2B);
        assert(@offsetOf(Ship, "yaw") == 0x2E);
        assert(@offsetOf(Ship, "formation_point") == 0x34);
        assert(@offsetOf(Ship, "pitch") == 0x3A);
        assert(@offsetOf(Ship, "tier") == 0x3D);
        assert(@offsetOf(Ship, "roll") == 0x4A);
        assert(@offsetOf(Ship, "marker_curve") == 0x40);
        assert(@offsetOf(Ship, "marker_at") == 0x44);
        assert(@sizeOf(Ship) == 0x4C);
    }
};

/// A curve, section `curves`: a cubic Hermite spline from one of the mission's ships to another,
/// which leaves the first along one tangent and reaches the second along another. The director's
/// camera flies along the curves, and one that starts where another ends carries its path on.
/// Its points and tangents are the ships' places as the mission placed them, which the record
/// keeps as they are while the mission runs.
pub const Curve = extern struct {
    /// The ship it starts at, and the ship it ends at, `Reference.unset` for none.
    start: Reference,
    end: Reference,
    /// Where it starts and where it ends.
    from: [3]f32,
    to: [3]f32,
    /// The ships its tangents are drawn to, one each side: `leaving` runs from `from` to the
    /// first, and `arriving` from the second to `to`. `0x004573B0` makes the curve afresh from
    /// the places of its four ships, on a message of the shared memory the game watches
    /// (`0x00457730`).
    leaving_handle: Reference,
    arriving_handle: Reference,
    /// Its tangents, each a tenth of its weight in the curve: the way it heads as it leaves its
    /// start, and the way back from where it heads as it reaches its end.
    leaving: [3]f32,
    arriving: [3]f32,
    _unknown_40: u32,

    /// A curve between no ships, at the origin, its last word as most shipped curves hold it.
    pub const blank: Curve = .{
        .start = .none,
        .end = .none,
        .from = @splat(0),
        .to = @splat(0),
        .leaving_handle = .none,
        .arriving_handle = .none,
        .leaving = @splat(0),
        .arriving = @splat(0),
        ._unknown_40 = 0xFFFFFFFF,
    };

    /// The ship it starts at, where it starts at one.
    pub fn startShip(curve: Curve) ?u16 {
        return if (curve.start.index == Reference.unset) null else curve.start.index;
    }

    /// The ship it ends at, where it ends at one.
    pub fn endShip(curve: Curve) ?u16 {
        return if (curve.end.index == Reference.unset) null else curve.end.index;
    }

    comptime {
        assert(@offsetOf(Curve, "end") == 0x04);
        assert(@offsetOf(Curve, "from") == 0x08);
        assert(@offsetOf(Curve, "to") == 0x14);
        assert(@offsetOf(Curve, "leaving_handle") == 0x20);
        assert(@offsetOf(Curve, "arriving_handle") == 0x24);
        assert(@offsetOf(Curve, "leaving") == 0x28);
        assert(@offsetOf(Curve, "arriving") == 0x34);
        assert(@sizeOf(Curve) == 0x44);
    }
};

/// One named script routine.
///
/// The loader expands each of these into a 0x74-byte runtime entry, of which only the block
/// address and the argument count come from here; `call_part` and `spawn_part` index that table by
/// a single byte, so a mission has at most 256 parts. An `offset` of `no_block` leaves the entry
/// empty.
///
/// Parts are contiguous and in address order: each one's `offset + length` is the next one's
/// `offset`, and the last ends at the end of the script section.
pub const Part = extern struct {
    /// Byte offset into the string pool. Missions ship with their authors' own names for these,
    /// such as `(F)Arrival at CONVOY`.
    name: u16,
    _unknown_02: u16,
    _unknown_04: [6]u8,
    /// Start of the part, in **halfwords** from the start of the script section.
    offset: u16,
    flags: Flags,
    /// Arguments the part takes. The caller reserves `4 * arguments + 16` bytes of frame for it.
    arguments: u8,
    _unknown_0e: u16,
    /// Extent of the part, in halfwords: its entry block, then a trailer of zero or more 8-byte
    /// records whose meaning is not yet known.
    length: u16,
    _unknown_12: [7]u8,
    /// Read by the loader and passed to the routine that fills the runtime entry.
    kind: u8,
    _unknown_1a: u16,

    /// An `offset` meaning the part has no block.
    pub const no_block: u16 = 0xFFFF;

    /// A part with no block, which takes no arguments and doesn't run at the start. The bytes the
    /// engine doesn't read hold what most of the shipped missions' parts hold.
    pub const blank: Part = .{
        .name = 0,
        ._unknown_02 = 0,
        ._unknown_04 = @splat(0),
        .offset = no_block,
        .flags = .{ .start = false, ._unknown = 0 },
        .arguments = 0,
        ._unknown_0e = 0,
        .length = 0,
        ._unknown_12 = .{ 0, 0, 0, 0, 0xFF, 0xFF, 0xFF },
        .kind = 0,
        ._unknown_1a = 2,
    };

    pub const Flags = packed struct(u8) {
        /// Run when the mission starts, before any trigger is armed. Every mission has one such
        /// part (`mission_script_start`, `0x0045CBC0`).
        start: bool,
        _unknown: u7,
    };

    pub fn isEmpty(part: Part) bool {
        return part.offset == no_block;
    }

    /// Byte offset of the part's entry block within the script section.
    pub fn start(part: Part) usize {
        return halfwords(part.offset);
    }

    /// The block it runs, as a byte offset into the script: null for an empty part (`isEmpty`).
    pub fn block(part: Part) ?usize {
        return if (part.isEmpty()) null else part.start();
    }

    /// Bytes the part spans.
    pub fn size(part: Part) usize {
        return halfwords(part.length);
    }

    comptime {
        assert(@offsetOf(Part, "name") == 0x00);
        assert(@offsetOf(Part, "offset") == 0x0A);
        assert(@offsetOf(Part, "arguments") == 0x0D);
        assert(@offsetOf(Part, "length") == 0x10);
        assert(@offsetOf(Part, "kind") == 0x19);
        assert(@sizeOf(Part) == 0x1C);
    }
};

/// What `Mission.findPart` and `Mission.findShip` find: one record, by its index, none, or more
/// than one.
pub const Found = union(enum) {
    one: usize,
    none,
    several,
};

/// A block of script, the constants after it, and what runs it.
///
/// The script section is a sequence of these. Each is a block, then the block's constant table: a
/// whole number of 8-byte units, which `push_constant` reads a dword at a time. The table runs to
/// the start of the next routine.
pub const Routine = struct {
    /// Byte offset of the block within the script.
    start: usize,
    /// Bytes of block and constants together.
    extent: usize,
    owner: Owner,

    pub const Owner = union(enum) {
        /// The indices of the triggers that run this block. Only triggers some object's slice
        /// holds are counted, since no other can fire.
        triggers: []const u16,
        /// The index of the part this block is.
        part: u16,
    };

    /// The constant table: the dwords from the block's end to the routine's.
    pub fn constants(routine: Routine, script: []const u8) []align(1) const u32 {
        const block = BlockReader.at(script, routine.start) orelse return &.{};
        const from = routine.start + block.code.len + BlockReader.header_len;
        const to = @min(routine.start + routine.extent, script.len);
        if (from >= to) return &.{};
        const bytes = script[from..to];
        return std.mem.bytesAsSlice(u32, bytes[0 .. bytes.len - bytes.len % 4]);
    }
};

/// A named value the script reads and writes.
pub const Global = extern struct {
    name: u16,
    _unknown_02: u16,
    value: u32,
    /// 7 in every shipped mission.
    _unknown_08: u32,

    /// A global that starts at 0, its last word as every shipped global holds it.
    pub const blank: Global = .{ .name = 0, ._unknown_02 = 0, .value = 0, ._unknown_08 = 7 };

    comptime {
        assert(@sizeOf(Global) == 0x0C);
    }
};

pub const Objective = extern struct {
    data: [0x14]u8,

    comptime {
        assert(@sizeOf(Objective) == 0x14);
    }
};

/// Runs a block of script when an event it watches happens to its subject.
///
/// A trigger holds no subject. It is reached through the subject object's entry in `objects`,
/// which gives the index of the ship's first trigger and how many follow, so a trigger that no
/// ship lists can never fire. When an event happens to a ship, the engine fires each of that
/// ship's triggers that is armed, whose `condition` and `qualifier` are the event's, and whose
/// operands pass the condition's checks. Firing starts a thread on the block `link` names, unless
/// a thread the trigger started is still running.
pub const Trigger = extern struct {
    condition: Condition,
    repeat: Repeat,
    /// The block to run, as a halfword offset into the script, like a part's start. `0xFFFF` for
    /// none. The blocks fill the script ahead of the first part.
    link: u16,
    _unknown_04: [16]u8,
    /// Set for every trigger when the mission starts. Firing clears it, per `repeat`.
    armed: u8,
    /// The component of the subject the trigger watches, by its index among the subject's
    /// components, or `whole_object`. It must equal the event's: a ShotAt or Destroyed event on a
    /// component, such as a capital ship's turret, carries the component's index, and every other
    /// event `whole_object`.
    qualifier: u8,
    /// Zero runs the new thread at once, inside the event; any other value leaves it to the
    /// scheduler.
    deferred: u8,
    /// Byte arrays rather than wider types: these sit at odd offsets, and an `extern struct` would
    /// pad a `u16` here into the wrong place.
    _unknown_17: [2]u8,
    /// Firings left, for `counted`.
    repeat_counter: u8,
    /// The firings a `counted` trigger has each time the script arms it (`SetTriggerState`), which
    /// `repeat_counter` takes again then (`trigger_set_armed`).
    repeat_count: u8,
    _unknown_1b: u8,
    /// Condition arguments, four bytes each, checked against the event's values: those the
    /// condition marks as checked, and of those, the ones whose low halfword is not `0xFFFF`. A
    /// Proximity trigger also keeps its distance in one (`proximity_distance`).
    operands: [5]u32,

    /// The qualifier of an event on the subject itself rather than one of its components.
    pub const whole_object: u8 = 0xFF;

    /// The operand of a Proximity trigger that gives how far its watch looks, in the radii of the
    /// ship it watches (`0x0045AF60`). The matcher doesn't check it against the event's value, and
    /// a trigger without it never fires.
    pub const proximity_distance = 1;

    /// A trigger on Shot At that runs nothing, fires once, watches the whole subject and checks no
    /// value of its event. The bytes the engine doesn't read hold what most of the shipped
    /// missions' triggers hold.
    pub const blank: Trigger = .{
        .condition = .shot_at,
        .repeat = .once,
        .link = Part.no_block,
        ._unknown_04 = @splat(0),
        .armed = 1,
        .qualifier = whole_object,
        .deferred = 0,
        ._unknown_17 = .{ 0xFF, 0 },
        .repeat_counter = 0,
        .repeat_count = 0,
        ._unknown_1b = 0x88,
        .operands = @splat(Operand.write(.unset)),
    };

    pub const Repeat = enum(u8) {
        /// Disarms when it fires.
        once = 0,
        /// Never disarms, so it fires every time.
        always = 1,
        /// Disarms when `repeat_counter`, counted down on each firing, reaches zero.
        counted = 2,
        _,

        pub fn format(repeat: Repeat, writer: *std.Io.Writer) std.Io.Writer.Error!void {
            return layout.formatTag(Repeat, repeat, writer);
        }
    };

    /// The component its event is on, or null for the subject itself (`whole_object`).
    pub fn component(trigger: Trigger) ?u8 {
        return if (trigger.qualifier == whole_object) null else trigger.qualifier;
    }

    /// The block this trigger runs, as a byte offset into the script.
    pub fn block(trigger: Trigger) ?usize {
        if (trigger.link == Part.no_block) return null;
        return halfwords(trigger.link);
    }

    comptime {
        assert(@offsetOf(Trigger, "condition") == 0x00);
        assert(@offsetOf(Trigger, "link") == 0x02);
        assert(@offsetOf(Trigger, "armed") == 0x14);
        assert(@offsetOf(Trigger, "qualifier") == 0x15);
        assert(@offsetOf(Trigger, "deferred") == 0x16);
        assert(@offsetOf(Trigger, "repeat_counter") == 0x19);
        assert(@offsetOf(Trigger, "operands") == 0x1C);
        assert(@sizeOf(Trigger) == 0x30);
    }
};

/// A command's word of flags in section 24 (`Section.command_flags`), or in section 25 for the
/// second catalogue. `command` reads its low byte alone (`fromLow`). In the missions of the
/// writer's template the word has a bit for each of the command's parameters, the first's bit 0.
pub const CommandFlags = packed struct(u16) {
    /// Whether `for_each_ship` walks the players' ships in a flight group, a squad's too, rather
    /// than passing over them.
    players: bool = false,
    _unknown_1: u15 = 0,

    /// The flags of a word whose low byte is `low`, all that `command` reads of it.
    pub fn fromLow(low: u8) CommandFlags {
        return @bitCast(@as(u16, low));
    }
};

/// How a trigger operand names a ship, a flight group or a squad: an index into the section the tag
/// selects. The matcher turns a reference into the address of the record (`FUN_004530A0`), which is
/// how event values name them.
pub const Reference = packed struct(u32) {
    index: u16,
    tag: Tag,
    /// **Unknown.** The matcher ignores it.
    _unknown_24: u8,

    /// The table a reference points into, by its entry in `editor_tables` (`0x004EE970`). The
    /// executable's image holds the ships' and the flight groups' entries, and `editor_tables_fill`
    /// (`0x00451620`) fills the others as the game starts: the squads' at `0x00451900`, their
    /// members' at `0x0045192A`, the formations' at `0x0045197B` and their points' at
    /// `0x004519A7`.
    pub const Tag = enum(u8) {
        ship = 0x00,
        flight_group = 0x01,
        squad = 0x16,
        squad_member = 0x17,
        formation = 0x19,
        formation_point = 0x1A,
        /// No table: the tag of a reference that is all ones, such as an unset operand.
        none = 0xFF,
        _,
    };

    /// An operand whose low halfword is this is not set, and is not checked.
    pub const unset: u16 = 0xFFFF;

    /// A reference to nothing, every bit set, as an unset trigger operand holds.
    pub const none: Reference = .{ .index = unset, .tag = .none, ._unknown_24 = 0xFF };

    /// A reference to record `index` of the table `tag` names, as the shipped missions write one:
    /// its last byte 0xFF.
    pub fn of(tag: Tag, index: u16) Reference {
        return .{ .index = index, .tag = tag, ._unknown_24 = 0xFF };
    }

    /// Set in the index of an operand for a ship value, it matches any of the players' ships: in a
    /// game of one, the player's.
    pub const any_ship: u16 = 0x2000;
};

/// A trigger operand, read the way the matcher reads it for a value of the given kinds.
pub const Operand = union(enum) {
    unset,
    /// For a value that is a number: taken as it is.
    number: u32,
    /// For a ship value: any of the players' ships matches.
    any_ship,
    /// A ship, a flight group or a squad, by its index among the mission's records of its kind
    /// (`Reference.Tag`).
    ship: u16,
    flight_group: u16,
    squad: u16,
    /// A tag the matcher cannot resolve.
    other: u32,

    /// The raw operand that reads back as `operand`, as the shipped missions write one
    /// (`Reference.of`), and every bit set for none.
    pub fn write(operand: Operand) u32 {
        return switch (operand) {
            .unset => @bitCast(Reference.none),
            .number, .other => |raw| raw,
            .any_ship => @bitCast(Reference.of(.ship, Reference.any_ship)),
            .ship => |index| @bitCast(Reference.of(.ship, index)),
            .flight_group => |index| @bitCast(Reference.of(.flight_group, index)),
            .squad => |index| @bitCast(Reference.of(.squad, index)),
        };
    }

    pub fn read(raw: u32, kinds: commands.Kinds) Operand {
        const reference: Reference = @bitCast(raw);
        if (reference.index == Reference.unset) return .unset;
        if (kinds.number) return .{ .number = raw };
        if (kinds.ship and reference.index & Reference.any_ship != 0) return .any_ship;
        return switch (reference.tag) {
            .ship => .{ .ship = reference.index },
            .flight_group => .{ .flight_group = reference.index },
            .squad => .{ .squad = reference.index },
            .squad_member, .formation, .formation_point, .none, _ => .{ .other = raw },
        };
    }
};

test Operand {
    const Kinds = commands.Kinds;
    const ship: Kinds = @bitCast(@as(u32, 0x400));
    const number: Kinds = @bitCast(@as(u32, 0x80));
    try std.testing.expectEqual(Operand.unset, Operand.read(0xFFFFFFFF, ship));
    try std.testing.expectEqual(Operand{ .number = 50 }, Operand.read(50, number));
    try std.testing.expectEqual(Operand.any_ship, Operand.read(0xFF002000, ship));
    try std.testing.expectEqual(Operand{ .flight_group = 4 }, Operand.read(0x00010004, ship));
    try std.testing.expectEqual(Operand{ .ship = 7 }, Operand.read(0xFF000007, ship));
    try std.testing.expectEqual(Operand{ .squad = 2 }, Operand.read(0x00160002, ship));
    try std.testing.expectEqual(Operand{ .other = 0x000C0050 }, Operand.read(0x000C0050, @bitCast(@as(u32, 0x1000))));
    // The matcher doesn't resolve a reference to a squad's member.
    try std.testing.expectEqual(Operand{ .other = 0xFF170003 }, Operand.read(0xFF170003, ship));
    // Written as the shipped missions write them, operands read back as they were.
    for ([_]Operand{ .unset, .any_ship, .{ .ship = 7 }, .{ .flight_group = 4 }, .{ .squad = 2 }, .{ .other = 0xFF170003 } }) |operand| {
        try std.testing.expectEqual(operand, Operand.read(Operand.write(operand), ship));
    }
    try std.testing.expectEqual(Operand{ .number = 50 }, Operand.read(Operand.write(.{ .number = 50 }), number));
    try std.testing.expectEqual(0xFF002000, Operand.write(.any_ship));
}

/// One entry of the object table, section `objects`, indexed by object ID.
///
/// Ships, flight groups and squads each carry an object ID at their start, and an event names its
/// subject by one. The entry gives the object's kind and its slice of the trigger list.
pub const Object = extern struct {
    kind: Kind,
    /// Triggers in the object's slice.
    count: u8,
    /// Index of the first trigger in it.
    first: u16,
    tool_flags: ToolFlags,

    /// Flags for the original's tools. Nothing in the game reads them. Only a ship's entry has
    /// any set: a flight group's or a squad's is 0 in every shipped mission.
    pub const ToolFlags = packed struct(u32) {
        /// Set on exactly one entry, ship 0's, in most of the shipped missions. In most of those,
        /// ship 0's name says it is the player's.
        player: bool = false,
        _unknown_1: u2 = 0,
        /// Set only on curve points (kind `0x3E4`), on most of them.
        curve_point: bool = false,
        /// **Unknown:** set on some ships and some points, by no rule found.
        _unknown_4: bool = false,
        _unknown_5: u27 = 0,
    };

    /// The `first` of an object with no triggers, as every shipped mission's holds.
    pub const no_triggers: u16 = 0xFFFF;

    /// Where its slice starts and ends in a trigger list of `triggers` triggers, as far as the list
    /// reaches.
    pub fn triggerBounds(object: Object, triggers: usize) [2]usize {
        const start = @min(object.first, triggers);
        return .{ start, @min(start + object.count, triggers) };
    }

    pub const Kind = enum(u8) {
        ship = 0,
        flight_group = 1,
        squad = 2,
        _,

        pub fn format(kind: Kind, writer: *std.Io.Writer) std.Io.Writer.Error!void {
            return layout.formatTag(Kind, kind, writer);
        }
    };

    /// A set of kinds, a bit for each.
    pub const KindSet = packed struct(u16) {
        ship: bool,
        flight_group: bool,
        squad: bool,
        _unused: u13,

        pub fn has(set: KindSet, kind: Kind) bool {
            return switch (kind) {
                .ship => set.ship,
                .flight_group => set.flight_group,
                .squad => set.squad,
                _ => false,
            };
        }

        comptime {
            for (.{ "ship", "flight_group", "squad" }) |name| {
                assert(@bitOffsetOf(KindSet, name) == @backingInt(@field(Kind, name)));
            }
        }
    };

    comptime {
        assert(@offsetOf(Object, "tool_flags") == 4);
        assert(@sizeOf(Object) == 8);
    }
};

/// **OpenReliant's own:** a mission's name, which OpenReliant keeps in section `openreliant_name`,
/// a section the game binds but never reads. The section's count is its size in bytes: this header,
/// then `length` bytes of the name in UTF-8, then a NUL. A mission is complete without it, and the
/// game plays one with it as it plays any other.
pub const OpenReliantName = extern struct {
    tag: [4]u8 = OpenReliantName.expected_tag,
    version: u16 = OpenReliantName.current_version,
    length: u16,

    /// The tag that marks the section as holding a name of this kind, and the one version so far.
    pub const expected_tag = "ORMN".*;
    pub const current_version: u16 = 1;

    /// The name `section` holds, where it starts with a header of this kind and the name fits;
    /// null for anything else, which OpenReliant leaves alone.
    pub fn read(section: []const u8) ?[]const u8 {
        if (section.len < @sizeOf(OpenReliantName)) return null;
        const header: *align(1) const OpenReliantName = @ptrCast(section[0..@sizeOf(OpenReliantName)]);
        if (!std.mem.eql(u8, &header.tag, &expected_tag) or header.version != current_version) return null;
        const name = section[@sizeOf(OpenReliantName)..];
        if (header.length > name.len) return null;
        return name[0..header.length];
    }

    comptime {
        assert(@sizeOf(OpenReliantName) == 8);
    }
};

/// A flight group: its object ID, the wing it is listed in, and where its ships stand in the list
/// of the groups' ships that binding the mission makes.
pub const FlightGroup = extern struct {
    object_id: u16,
    /// 0 in every shipped mission, as are `_unknown_06` and `_unknown_0a`.
    _unknown_02: u16,
    /// Byte offset into the string pool, such as `(FG)Reliant`.
    name: u16,
    _unknown_06: u16,
    /// The wing the mission lists the group's ships in (`mission_wings_build`).
    wing: Wing,
    /// How many of the mission's ships are in the group, and where the first stands in the list of
    /// the groups' ships, or `no_ship`: both worked out as the mission is bound
    /// (`mission_list_group_ships`, `0x00452EC0`), whatever the file holds.
    ship_count: u8,
    _unknown_0a: u16,
    first_ship: u32,
    /// A formation for the group, as a reference to `formations` (tag `formation`). No shipped
    /// mission names one: each holds `no_formation`.
    formation: Reference,

    pub const no_ship: u32 = 0xFFFFFFFF;

    /// The `formation` of a group with none, as every shipped mission's has.
    pub const no_formation: Reference = .{ .index = Reference.unset, .tag = .formation, ._unknown_24 = 0xFF };

    /// A group of no wing and no formation, whose ships binding the mission lists
    /// (`mission.bind.listGroupShips`), its unread bytes 0, as in every shipped mission.
    pub const blank: FlightGroup = .{
        .object_id = 0,
        ._unknown_02 = 0,
        .name = 0,
        ._unknown_06 = 0,
        .wing = .none,
        .ship_count = 0,
        ._unknown_0a = 0,
        .first_ship = no_ship,
        .formation = no_formation,
    };

    /// A flight group's wing, as a byte: the player's, which `mission_ship_create` tests for
    /// (`0x00457D39`), two more, or none.
    pub const Wing = enum(u8) {
        player = 0,
        second = 1,
        third = 2,
        none = 0xFF,
        _,

        pub fn format(wing: Wing, writer: *std.Io.Writer) std.Io.Writer.Error!void {
            return layout.formatTag(Wing, wing, writer);
        }
    };

    /// Where its ships start in the flight groups' list, where it has any.
    pub fn firstShip(group: FlightGroup) ?u32 {
        return if (group.first_ship == no_ship) null else group.first_ship;
    }

    comptime {
        assert(@offsetOf(FlightGroup, "name") == 0x04);
        assert(@offsetOf(FlightGroup, "wing") == 0x08);
        assert(@offsetOf(FlightGroup, "ship_count") == 0x09);
        assert(@offsetOf(FlightGroup, "first_ship") == 0x0C);
        assert(@offsetOf(FlightGroup, "formation") == 0x10);
        assert(@sizeOf(FlightGroup) == 0x14);
    }
};

/// A squad: its object ID, its name and its first membership record.
pub const Squad = extern struct {
    object_id: u16,
    /// 0 in every shipped mission, as is `_unknown_06`.
    _unknown_02: u16,
    /// Byte offset into the string pool, such as `(AI)sabretargets`.
    name: u16,
    _unknown_06: u16,
    /// Index of its first record in `squad_members`, or `no_member`. With the next two bytes it
    /// makes a reference: the tag of `squad_members` where the squad has members, `none` where it
    /// has none, then 0xFF.
    first_member: u16,
    first_member_tag: Reference.Tag,
    _unknown_0b: u8,

    /// The `first_member` of a squad with none.
    pub const no_member: u16 = 0xFFFF;

    /// A squad with no members, its unread bytes as every shipped squad holds them.
    pub const blank: Squad = .{
        .object_id = 0,
        ._unknown_02 = 0,
        .name = 0,
        ._unknown_06 = 0,
        .first_member = no_member,
        .first_member_tag = .none,
        ._unknown_0b = 0xFF,
    };

    /// Its first record in `squad_members`, where it has one.
    pub fn firstMember(squad: Squad) ?u16 {
        return if (squad.first_member == no_member) null else squad.first_member;
    }

    comptime {
        assert(@offsetOf(Squad, "name") == 0x04);
        assert(@offsetOf(Squad, "first_member") == 0x08);
        assert(@sizeOf(Squad) == 0x0C);
    }
};

/// One member of a squad, in section `squad_members`. A member can itself be a flight group or a
/// squad, and `in_squad` follows those.
pub const SquadMember = extern struct {
    object_id: u16,
    _unknown_02: u16,
    /// Index of the squad in `squads`. A squad's members are consecutive.
    squad: u16,
    _unknown_06: u16,
    /// The member's component, by its index among the object's components, or
    /// `Trigger.whole_object`: a squad can hold single components of a ship, such as a capital
    /// ship's turrets. An event on a squad member counts for the squad only on the component
    /// named here.
    component: u8,
    _unknown_09: [3]u8,

    /// A member that is a whole object, its unread bytes as most shipped members hold them.
    pub const blank: SquadMember = .{
        .object_id = 0,
        ._unknown_02 = 0,
        .squad = 0,
        ._unknown_06 = 0,
        .component = Trigger.whole_object,
        ._unknown_09 = .{ 0x87, 0x1E, 0x0D },
    };

    /// The members of squad `squad` among `members`, from member `first` on while they are its
    /// own, as the game walks them (`squad_walk`, `0x00401D80`): none from past the members.
    pub fn run(members: []align(1) const SquadMember, squad: usize, first: usize) []align(1) const SquadMember {
        const start = @min(first, members.len);
        var end = start;
        while (end < members.len and members[end].squad == squad) end += 1;
        return members[start..end];
    }

    /// The component it names, or null for the whole object (`Trigger.whole_object`).
    pub fn part(member: SquadMember) ?u8 {
        return if (member.component == Trigger.whole_object) null else member.component;
    }

    comptime {
        assert(@offsetOf(SquadMember, "squad") == 0x04);
        assert(@sizeOf(SquadMember) == 0x0C);
    }
};

/// A formation, in section `formations`: places for ships about an origin, which the formation
/// orders fly a flight group into (Formation Regroup and Patrol Route). Its points follow one
/// another in `formation_points` from its first, each naming the formation.
pub const Formation = extern struct {
    /// Byte offset into the string pool, such as `sabres`.
    name: u16,
    _unknown_02: u16,
    /// Its first point, by its index in `formation_points`. With the next two bytes it makes a
    /// reference: the tag of `formation_points`, then 0xFF.
    first_point: u16,
    first_point_tag: Reference.Tag,
    _unknown_07: u8,

    /// A formation whose points start at the first, its unread byte as every shipped formation
    /// holds it.
    pub const blank: Formation = .{ .name = 0, ._unknown_02 = 0, .first_point = 0, .first_point_tag = .formation_point, ._unknown_07 = 0xFF };

    comptime {
        assert(@offsetOf(Formation, "first_point") == 0x04);
        assert(@sizeOf(Formation) == 8);
    }
};

/// A point of a formation, in section `formation_points`: the place of the ship whose
/// `Ship.formation_point` names it.
pub const FormationPoint = extern struct {
    /// Its formation, by its index in `formations`. With the next two bytes it makes a reference:
    /// the tag of `formations`, then 0xFF.
    formation: u16,
    formation_tag: Reference.Tag,
    _unknown_03: u8,
    /// Where it stands from the formation's origin.
    offset: [3]f32,

    /// A point of the first formation at its origin, its unread byte as every shipped point holds
    /// it.
    pub const blank: FormationPoint = .{ .formation = 0, .formation_tag = .formation, ._unknown_03 = 0xFF, .offset = @splat(0) };

    /// A formation's points, by their indices: from the formation's first point on, those that
    /// name it, as OpenReliant's formation orders take them (`ai.formations`).
    pub const Walk = struct {
        points: []align(1) const FormationPoint,
        formation: usize,
        at: usize,

        pub fn next(walk: *Walk) ?u16 {
            while (walk.at < walk.points.len) {
                const at = walk.at;
                walk.at += 1;
                if (walk.points[at].formation == walk.formation) return @intCast(at);
            }
            return null;
        }
    };

    comptime {
        assert(@offsetOf(FormationPoint, "offset") == 0x04);
        assert(@sizeOf(FormationPoint) == 0x10);
    }
};

/// The 35 conditions, in the order of the engine's descriptor table at `0x4F6698`, named after its
/// `TT_*` constants. The last two are internal and cannot be scripted. What each applies to and
/// what its events carry is in [`engine/vm/conditions.zig`](../engine/vm/conditions.zig), generated
/// from that table.
pub const Condition = enum(u8) {
    shot_at = 0x00,
    destroyed = 0x01,
    launched = 0x02,
    camera_reached = 0x03,
    ship_reached = 0x04,
    proximity_close = 0x05,
    proximity_general = 0x06,
    object_scooped = 0x07,
    player_ready_to_jump = 0x08,
    jumped_in = 0x09,
    /// `TT_FG_JUMPED_IN`: a ship has come in through a fixed gate (`FixedGateJumpedIn`).
    fixed_gate_jumped_in = 0x0A,
    player_ready_to_warp = 0x0B,
    jumped_through_hoop = 0x0C,
    player_wants_backup = 0x0D,
    ripper_grabbed_object = 0x0E,
    ripper_dropped_object = 0x0F,
    cloaked = 0x10,
    decloaked = 0x11,
    targetted = 0x12,
    player_l1_doubletap = 0x13,
    player_l2_doubletap = 0x14,
    player_r1_doubletap = 0x15,
    player_r2_doubletap = 0x16,
    player_l1_l2_r1_r2_pressed = 0x17,
    player_l1_r1_pressed = 0x18,
    game_timer_expired = 0x19,
    tractor_beam_locked = 0x1A,
    tractor_beam_broken = 0x1B,
    inside_object = 0x1C,
    outside_object = 0x1D,
    docked = 0x1E,
    undocked = 0x1F,
    being_chased = 0x20,
    call_reinforcements = 0x21,
    explosion_ship = 0x22,
    _,

    /// Conditions above this are internal to the engine.
    pub const last_scriptable: Condition = .being_chased;

    /// The condition's entry in the engine's catalogue, or null for a value the catalogue lacks.
    pub fn descriptor(condition: Condition) ?conditions.Condition {
        return conditions.find(@backingInt(condition));
    }

    /// What a trigger of the condition keeps in its operand for value `slot` of its events.
    pub fn keeps(condition: Condition, slot: usize) Kept {
        const described = condition.descriptor() orelse return .nothing;
        if (slot >= described.values.len) return .nothing;
        if (described.values[slot].checked) return .check;
        if (condition == .proximity_general and slot == Trigger.proximity_distance) return .distance;
        return .nothing;
    }

    /// What a trigger keeps in the operand of one of its condition's values.
    pub const Kept = enum {
        /// Nothing the engine reads.
        nothing,
        /// What the event's value must be for the trigger to fire, which the matcher checks.
        check,
        /// How far a Proximity trigger's watch looks (`Trigger.proximity_distance`).
        distance,
    };

    comptime {
        const tags = @typeInfo(Condition).@"enum";
        if (tags.field_names.len != conditions.table.len) {
            @compileError("dte.Condition does not name every entry of conditions.table");
        }
        for (tags.field_names, tags.field_values, 0..) |name, value, index| {
            if (value != index) @compileError("dte.Condition." ++ name ++ " is out of order");
        }
    }

    pub fn format(condition: Condition, writer: *std.Io.Writer) std.Io.Writer.Error!void {
        return layout.formatTag(Condition, condition, writer);
    }
};

/// Script bytecode.
///
/// The interpreter is a plain dispatch loop: fetch one byte, index a 256-entry handler table,
/// advance the instruction pointer by one, call the handler, and repeat until a handler returns
/// zero. A parallel flag array, section `script_flags`, is indexed by the same instruction pointer:
/// with the script debugger attached, the interpreter can stop a thread at a flagged byte and
/// report where it is.
///
/// The handler table holds 86 entries, of which 71 are filled: `0x02` to `0x07` and `0x14` to
/// `0x55`, minus `0x50`. Those 71 are the whole instruction set. Their sizes and shapes are in
/// [`engine/vm/opcodes.zig`](../engine/vm/opcodes.zig), derived from the handlers themselves by
/// `src/tools/tablegen`.
pub const Opcode = enum(u8) {
    // Comparisons pop `b`, then `a`, and push 1 or 0. Values are unsigned.
    equal = 0x02,
    not_equal = 0x03,
    greater = 0x04,
    greater_equal = 0x05,
    less = 0x06,
    less_equal = 0x07,
    /// Whether ship `a` belongs to flight group `b`.
    in_flight_group = 0x14,
    not_in_flight_group = 0x15,

    // Stores pop the value and the target's old value, and write to the target the last `select_`
    // opcode chose.
    assign = 0x16,
    add_assign = 0x17,
    sub_assign = 0x18,
    mul_assign = 0x19,
    div_assign = 0x1A,

    // Arithmetic pops `b`, then `a`, and pushes the result.
    add = 0x1B,
    sub = 0x1C,
    mul = 0x1D,
    div = 0x1E,
    logical_and = 0x1F,
    logical_or = 0x20,

    /// Calls Executor command `n`,
    /// [`engine/game/executor/commands.zig`](../engine/game/executor/commands.zig), with its
    /// arguments popped off the stack. Its result is kept for `push_result`.
    command = 0x21,
    /// Calls part `n` through the part table.
    call_part = 0x22,
    /// Pops a value and branches when it is zero, over a big-endian displacement counted from the
    /// displacement's own position. `0x24` runs the same handler.
    branch_if_zero = 0x23,
    branch_if_zero_alt = 0x24,
    /// Returns from a part: restores the caller's frame, instruction pointer and block end. When
    /// the call depth is already zero the thread is finished instead. `0x25` is the same handler.
    @"return" = 0x43,
    return_alt = 0x25,

    // Pushes.
    /// Array slot `n`'s value.
    push_array = 0x26,
    /// Global `n`'s value.
    push_global = 0x27,
    /// Constant `n` of the running block: the `n`th dword after the block's end.
    push_constant = 0x28,
    /// `push_constant` with a big-endian 16-bit index.
    push_constant_wide = 0x29,
    /// A pointer to the bytes that follow, which it steps over. The operand byte is the length of
    /// the run, itself included, and the bytes are a NUL-terminated string: the name of a speech,
    /// cutscene or movie file, or text. `0x2B` runs the same handler.
    push_string = 0x2A,
    push_string_alt = 0x2B,
    /// A pointer to ship record `n`.
    push_ship = 0x2C,
    /// `push_ship` with a big-endian 16-bit index.
    push_ship_wide = 0x52,
    /// A pointer to ship record `n`, naming its component `c`, the second operand byte: a command
    /// that takes the value acts on that component, such as the turret `DestroySubObject`
    /// destroys or `SetPrimaryTarget` targets. `0x55` runs the same handler.
    push_component = 0x47,
    push_component_alt = 0x55,
    /// A pointer to flight group record `n`.
    push_flight_group = 0x2D,
    /// A pointer to squad record `n`.
    push_squad = 0x44,
    /// A pointer to curve record `n`.
    push_curve = 0x49,
    /// A pointer to record `n` of section 19, which no mission uses.
    push_section_19 = 0x54,
    /// The operand byte itself. `0x2E` runs the same handler.
    push_byte = 0x32,
    push_byte_alt = 0x2E,
    /// `n` percent of the value on top of the stack, which stays.
    push_percent = 0x2F,
    /// Value `n` of the running thread: a trigger block's thread holds the event's arguments.
    push_local = 0x30,
    /// Argument `n` of the running part.
    push_argument = 0x31,
    /// `-1`, which the parameters labelled "can be NULL" take for none.
    push_null = 0x48,
    /// The result of the last `command`.
    push_result = 0x4C,
    /// A value the event matcher stored for an object: three operand bytes name the condition,
    /// the value and the object.
    push_event_value = 0x4B,

    // The same operations with a floating-point step. Operands still come off the stack as
    // unsigned integers; the comparisons give the same results as `0x04` to `0x07`.
    greater_f = 0x33,
    greater_equal_f = 0x34,
    less_f = 0x35,
    less_equal_f = 0x36,
    /// Stores to a float target.
    add_assign_f = 0x37,
    sub_assign_f = 0x38,
    mul_assign_f = 0x39,
    div_assign_f = 0x3A,
    /// Computed in floating point and truncated.
    add_f = 0x3B,
    sub_f = 0x3C,
    mul_f = 0x3D,
    div_f = 0x3E,

    // Selecting a store target also pushes its current value.
    select_array = 0x3F,
    select_global = 0x40,
    select_argument = 0x41,

    /// Whether object `a` belongs to squad `b`, following squads within squads.
    in_squad = 0x45,
    not_in_squad = 0x46,

    /// Jumps forward by a **big-endian** 16-bit displacement, as all the script's two-byte operands
    /// are big-endian.
    jump = 0x42,
    /// `call_part` through the second part table, which serves `script_b`.
    call_part_b = 0x4A,
    /// Starts part `n` on a thread of its own and carries on. The part's arguments move from this
    /// thread's stack to the new one's.
    spawn_part = 0x4D,
    /// `spawn_part` through the second part table.
    spawn_part_b = 0x4E,
    /// `command` through the second command table, whose one command has no implementation: it
    /// pops the command's arguments and gives 1.
    command_b = 0x4F,
    /// Branches to one of a table of arms, chosen by a roll below 100 against each arm's
    /// threshold. A count byte, a big-endian default target, then that many four-byte arms, with
    /// room for ten in the shipped missions.
    random_branch = 0x51,
    nop = 0x53,
    _,

    /// Its entry in the VM's opcode table (`opcodes.find`): null for an opcode the payload's
    /// handler table does not implement.
    pub fn info(opcode: Opcode) ?opcodes.Info {
        return opcodes.find(opcode);
    }

    /// Opcodes the payload's handler table implements.
    pub fn isImplemented(opcode: Opcode) bool {
        return opcode.info() != null;
    }

    pub fn format(opcode: Opcode, writer: *std.Io.Writer) std.Io.Writer.Error!void {
        return layout.formatTag(Opcode, opcode, writer);
    }
};

/// What an opcode does to the instruction pointer.
pub const Instruction = struct {
    /// Offset of the opcode within whatever the instruction was decoded from.
    address: usize,
    opcode: Opcode,
    /// The operand bytes, including any inline data or arm table.
    operands: []const u8,
    /// Where execution goes next.
    flow: Flow,

    /// Bytes the whole instruction occupies.
    pub fn size(instruction: Instruction) usize {
        return 1 + instruction.operands.len;
    }

    /// Its two-byte operand, such as `push_ship_wide`'s index: big-endian, as the script's two-byte
    /// operands are.
    pub fn wide(instruction: Instruction) u16 {
        return std.mem.readInt(u16, instruction.operands[0..2], .big);
    }

    /// The index in the block's constant table of the constant it pushes: `push_constant`'s and
    /// `push_constant_wide`'s.
    pub fn constant(instruction: Instruction) ?u16 {
        return switch (instruction.opcode) {
            .push_constant => instruction.operands[0],
            .push_constant_wide => instruction.wide(),
            else => null,
        };
    }

    /// Whether execution can continue at the following instruction.
    pub fn fallsThrough(instruction: Instruction) bool {
        return switch (instruction.flow) {
            .next, .inline_data, .call => true,
            .branch => |branch| branch.conditional,
            .random, .@"return" => false,
        };
    }
};

/// Where execution goes after an instruction.
pub const Flow = union(enum) {
    /// To the next instruction.
    next,
    /// To the next instruction, past the inline bytes the instruction carries, a pointer to which
    /// it has pushed.
    inline_data: []const u8,
    /// To `target`, and when `conditional` possibly to the next instruction instead.
    branch: Branch,
    /// To one of several targets, chosen by a roll: `random_branch`.
    random: ArmIterator,
    /// Into a part, coming back to the next instruction when it returns.
    call,
    /// Out of the part, or when nothing called it, out of the thread.
    @"return",

    pub const Branch = struct {
        /// In the same coordinates as the instruction's `address`.
        target: usize,
        conditional: bool,
    };
};

/// Walks a `random_branch`'s targets: its default first, then one per arm.
///
/// Like a branch's, each target is big-endian and relative, but counted from the opcode rather
/// than from the operands: the handler adds it to the instruction pointer and subtracts one.
pub const ArmIterator = struct {
    /// Address of the `random_branch` opcode.
    origin: usize,
    operands: []const u8,
    index: usize = 0,

    /// The operands before the arms: the arm count and the default target.
    pub const Header = extern struct {
        count: u8,
        default: layout.Big(u16),
    };

    /// An arm: a big-endian target, a threshold, and one byte not yet identified.
    pub const Arm = extern struct {
        target: layout.Big(u16),
        threshold: u8,
        _unknown_3: u8,
    };

    comptime {
        assert(@sizeOf(Header) == 3);
        assert(@sizeOf(Arm) == 4);
    }

    pub fn next(iterator: *ArmIterator) ?usize {
        const header = layout.view(Header, iterator.operands) catch return null;
        if (iterator.index > header.count) return null;
        defer iterator.index += 1;
        // The default target first, then each arm's.
        if (iterator.index == 0) return iterator.origin + header.default.get();
        const arms = layout.array(Arm, iterator.operands[@sizeOf(Header)..], header.count) catch return null;
        return iterator.origin + arms[iterator.index - 1].target.get();
    }
};

/// Decodes the instruction at `pos` in `code`, whose addresses it reports as offsets into `code`.
pub fn decodeAt(code: []const u8, pos: usize) ?Instruction {
    const length = instructionSize(code, pos) orelse return null;
    const opcode: Opcode = @fromBackingInt(code[pos]);
    const info = opcodes.find(opcode) orelse return null;
    const operands = code[pos + 1 ..][0 .. length - 1];

    const flow: Flow = switch (info.form) {
        .sequential => .next,
        .inline_data => .{ .inline_data = operands[1..] },
        // The displacement is big-endian, as the script's two-byte operands all are, unsigned, and
        // counts from its own position rather than from the end of the instruction.
        .branch => .{ .branch = .{
            .target = pos + 1 + (layout.view(layout.Big(u16), operands) catch return null).get(),
            .conditional = info.falls_through,
        } },
        // Every transfer in the table is classified, which the check below enforces.
        .transfer => switch (transferKind(opcode) orelse unreachable) {
            .call => .call,
            .@"return" => .@"return",
            .random => .{ .random = .{ .origin = pos, .operands = operands } },
        },
    };
    return .{ .address = pos, .opcode = opcode, .operands = operands, .flow = flow };
}

// Every opcode the handler table implements has a name, and every name is one it implements.
comptime {
    @setEvalBranchQuota(20_000);
    for (opcodes.table) |info| {
        if (std.enums.tagName(Opcode, info.opcode) == null) {
            @compileError(std.fmt.comptimePrint("opcode 0x{X:0>2} has no name", .{@backingInt(info.opcode)}));
        }
    }
    const tags = @typeInfo(Opcode).@"enum";
    for (tags.field_names, tags.field_values) |name, value| {
        if (opcodes.find(@fromBackingInt(value)) == null) {
            @compileError("no handler for opcode " ++ name);
        }
    }
}

/// What a `transfer` opcode does, by name.
///
/// The derived table cannot say this. For a call, the only path it sees that leaves the
/// instruction pointer sequential is the one taken when the part is missing; the return that
/// brings execution back happens in another handler. For `return`, the path that leaves it alone
/// is the one that ends the thread, signalled through the handler's return value, which the
/// analysis does not model.
const TransferKind = enum { call, @"return", random };

fn transferKind(opcode: Opcode) ?TransferKind {
    return switch (opcode) {
        .call_part, .call_part_b => .call,
        .@"return", .return_alt => .@"return",
        .random_branch => .random,
        else => null,
    };
}

comptime {
    for (opcodes.table) |info| {
        if (info.form == .transfer and transferKind(info.opcode) == null) {
            @compileError(std.fmt.comptimePrint("transfer opcode 0x{X:0>2} has no kind", .{@backingInt(info.opcode)}));
        }
    }
}

/// How many bytes the instruction at `code[pos]` occupies, or null when it cannot be decoded.
///
/// Most opcodes are a fixed size. Three shapes are not, and each carries its length in its own
/// operands, so the size is still known without tracking any state:
///
/// - `inline_data` (`0x2A`, `0x2B`): one byte holding the total length of the operand run.
/// - `jump_table` (`0x51`): a count, a two-byte default target, then that many four-byte arms.
///   The handler is the only one whose encoding this module reads rather than `tablegen` deriving
///   it, because its length depends on a byte the instruction-pointer analysis cannot follow.
/// - `branch` and `transfer` are fixed sizes; only where execution resumes differs.
pub fn instructionSize(code: []const u8, pos: usize) ?usize {
    if (pos >= code.len) return null;
    const info = opcodes.find(@fromBackingInt(code[pos])) orelse return null;
    const operands = code[pos + 1 ..];
    const length: usize = switch (info.form) {
        .inline_data => blk: {
            if (operands.len < 1) return null;
            // The byte counts itself, so a run of 1 is the byte alone.
            break :blk @max(operands[0], 1);
        },
        else => if (info.opcode == .random_branch) blk: {
            const header = layout.view(ArmIterator.Header, operands) catch return null;
            break :blk @sizeOf(ArmIterator.Header) + @sizeOf(ArmIterator.Arm) * @as(usize, header.count);
        } else info.operands,
    };
    if (pos + 1 + length > code.len) return null;
    return 1 + length;
}

/// A part's instructions, in address order, reached by following control flow from its entry.
///
/// A linear sweep is not enough: three opcodes never fall through, so the bytes after them are
/// reached only by a branch, and sweeping past one decodes whatever happens to sit there.
pub const Disassembly = struct {
    instructions: []const Instruction,
    /// Bytes of the block that nothing reaches. Trailing alignment padding is not counted.
    unreached: usize,
    /// Set when an instruction could not be decoded, which means a reachable byte is not an
    /// opcode this module knows.
    incomplete: bool,
};

/// Disassembles the block at `entry` in `script`, following every branch it can see.
///
/// Addresses are offsets into `script`. Returns null when there is no block at `entry`.
pub fn disassemble(allocator: Allocator, script: []const u8, entry: usize) Allocator.Error!?Disassembly {
    const block = BlockReader.at(script, entry) orelse return null;
    const first = entry + BlockReader.header_len;
    const limit = first + block.code.len;

    const decoded = try allocator.alloc(bool, block.code.len);
    defer allocator.free(decoded);
    @memset(decoded, false);

    var instructions: std.ArrayList(Instruction) = .empty;
    var pending: std.ArrayList(usize) = .empty;
    defer pending.deinit(allocator);
    try pending.append(allocator, first);

    var incomplete = false;
    while (pending.pop()) |start| {
        var pos = start;
        while (pos >= first and pos < limit and !decoded[pos - first]) {
            const instruction = decodeAt(script[0..limit], pos) orelse {
                incomplete = true;
                break;
            };
            decoded[pos - first] = true;
            try instructions.append(allocator, instruction);

            switch (instruction.flow) {
                .branch => |branch| try pending.append(allocator, branch.target),
                .random => |arms| {
                    var iterator = arms;
                    while (iterator.next()) |target| try pending.append(allocator, target);
                },
                .next, .inline_data, .call, .@"return" => {},
            }
            if (!instruction.fallsThrough()) break;
            pos += instruction.size();
        }
    }

    std.mem.sort(Instruction, instructions.items, {}, struct {
        fn lessThan(_: void, a: Instruction, b: Instruction) bool {
            return a.address < b.address;
        }
    }.lessThan);

    var covered: usize = 0;
    for (instructions.items) |instruction| covered += instruction.size();

    // Up to three bytes at the end of the block are alignment padding rather than a hole, but
    // only when everything before them was reached.
    var unreached = (limit - first) - covered;
    if (unreached < BlockReader.alignment) unreached = 0;

    return .{
        .instructions = try instructions.toOwnedSlice(allocator),
        .unreached = unreached,
        .incomplete = incomplete,
    };
}

/// Decodes one block of bytecode.
///
/// A block begins with a `u16` length that **counts its own two bytes**: the engine starts a
/// thread with its instruction pointer at `block + 2` and its limit at `block + length`, so the
/// instructions occupy `length - 2` bytes. The last of those is a `return`, followed by up to
/// three bytes of padding that bring the block to a four-byte boundary. Decoding therefore runs to
/// the limit rather than stopping at the first `return`, which may be an early exit from a branch,
/// and treats only a short run after a `return` as padding.
///
/// Blocks are entered by address, from a part table a `call_part` reaches, so a section cannot
/// simply be walked from its start.
pub const BlockReader = struct {
    code: []const u8,
    pos: usize = 0,
    /// Set once a `return` has been decoded, after which a short tail is padding.
    returned: bool = false,
    /// The length the block's header declares. A handful of missions declare more than their
    /// script section holds, so `code` is clamped to the section and this records the claim.
    declared: u16 = 0,

    /// Blocks are padded out to this many bytes.
    pub const alignment = 4;

    /// Bytes of a block header, which its length field includes.
    pub const header_len = 2;

    /// Reads the block at `offset` in `section`, returning a reader over its instructions.
    pub fn at(section: []const u8, offset: usize) ?BlockReader {
        if (offset > section.len) return null;
        const declared = (layout.view(u16, section[offset..]) catch return null).*;
        if (declared <= header_len) return null;
        const body = section[offset + header_len ..];
        return .{
            .code = body[0..@min(declared - header_len, body.len)],
            .declared = declared,
        };
    }

    /// Whether the block runs past the end of its section.
    pub fn isShort(reader: BlockReader) bool {
        return reader.code.len + header_len < reader.declared;
    }

    /// Why decoding stopped, once `next` has returned null.
    pub const Stop = enum {
        /// The block's instructions were decoded in full.
        complete,
        /// A byte the handler table leaves unimplemented.
        unimplemented,
        /// An instruction runs past the block's end.
        truncated,
    };

    /// The bytes from the cursor to the end of the block.
    pub fn rest(reader: BlockReader) []const u8 {
        return reader.code[reader.pos..];
    }

    /// The block's trailing padding, once decoding has reached it. Empty until then, and empty
    /// once the block is exhausted.
    pub fn padding(reader: BlockReader) []const u8 {
        const left = reader.rest();
        const is_padding = reader.returned and left.len != 0 and left.len < alignment;
        return if (is_padding) left else &.{};
    }

    pub fn next(reader: *BlockReader) ?Instruction {
        const left = reader.rest();
        if (left.len == 0 or reader.padding().len != 0) return null;

        const instruction = decodeAt(reader.code, reader.pos) orelse return null;
        reader.pos += instruction.size();
        if (instruction.opcode == .@"return") reader.returned = true;
        return instruction;
    }

    pub fn stop(reader: BlockReader) Stop {
        const left = reader.rest();
        if (left.len == 0 or reader.padding().len != 0) return .complete;
        return if (opcodes.find(@fromBackingInt(left[0])) == null) .unimplemented else .truncated;
    }
};

pub const Error = error{
    /// Too small to hold a directory.
    NotAMission,
    /// A section runs past the end of the image.
    Truncated,
    /// Still RefPack compressed. Read it through a `.HOG` archive, which expands it.
    Compressed,
};

/// The bytes of `count` halfwords, as the script's offsets and lengths count them.
fn halfwords(count: u16) usize {
    return @as(usize, count) * @sizeOf(u16);
}

pub const Mission = struct {
    image: []const u8,
    directory: []align(1) const DirectoryEntry,

    pub fn parse(image: []const u8) Error!Mission {
        if (refpack.gameExpands(image)) return error.Compressed;
        const directory = layout.array(DirectoryEntry, image, section_count) catch return error.NotAMission;
        return .{ .image = image, .directory = directory };
    }

    /// The mission of another game on StarLancer's engine, whose directory, `entries`, holds
    /// StarLancer's sections in another order. `Theirs` is that game's enum of its sections, and
    /// its `asDte` gives StarLancer's section for an entry, or null if the layout differs.
    /// `directory` takes StarLancer's entries; a section no entry holds is unused.
    pub fn remapped(
        image: []const u8,
        entries: []align(1) const DirectoryEntry,
        comptime Theirs: type,
        directory: *[section_count]DirectoryEntry,
    ) Mission {
        directory.* = @splat(.unused);
        for (entries, 0..) |held, index| {
            const theirs: Theirs = @fromBackingInt(@intCast(index));
            if (theirs.asDte()) |section| directory[@backingInt(section)] = held;
        }
        return .{ .image = image, .directory = directory };
    }

    pub fn entry(mission: Mission, section: Section) DirectoryEntry {
        const index = @backingInt(section);
        return if (index < mission.directory.len) mission.directory[index] else .unused;
    }

    /// The records of a fixed-stride section, as `T`.
    pub fn records(mission: Mission, comptime T: type, section: Section) Error![]align(1) const T {
        const at = try mission.span(section) orelse return &.{};
        return layout.array(T, mission.image[at.offset..], at.count);
    }

    /// Where a fixed-stride section's records lie in the image: null for an unused or empty
    /// section.
    pub fn span(mission: Mission, section: Section) Error!?Span {
        const slot = mission.entry(section);
        if (!slot.isUsed() or slot.count == 0) return null;
        if (slot.offset > mission.image.len) return error.Truncated;
        return .{ .offset = slot.offset, .count = slot.count };
    }

    /// Where a section's records start in the image, and how many there are.
    pub const Span = struct { offset: u32, count: u16 };

    /// How many bytes a section's reservation holds: from its start to the next section's, or to
    /// the image's end. The mission editor's files reserve more than a section's records fill,
    /// which the editor link's copies can fill (`game.mission.editor`). None for an unused section.
    pub fn room(mission: Mission, section: Section) u32 {
        const slot = mission.entry(section);
        if (!slot.isUsed() or slot.offset > mission.image.len) return 0;
        var end: u32 = @intCast(mission.image.len);
        for (mission.directory) |other| {
            if (other.isUsed() and other.offset > slot.offset) end = @min(end, other.offset);
        }
        return end - slot.offset;
    }

    /// The script bytecode, which the directory counts in halfwords.
    pub fn script(mission: Mission) Error![]const u8 {
        return std.mem.sliceAsBytes(try mission.records(u16, .script));
    }

    /// The size of the script's flags (section 10) as the editor link copies them: a byte for each
    /// of the script's bytes, rounded up to a multiple of 4 (`script_flags_size`, `0x00457B70`).
    pub fn scriptFlagsSize(mission: Mission) u32 {
        return std.mem.alignForward(u32, @as(u32, mission.entry(.script).count) * @sizeOf(u16), 4);
    }

    /// The mission's name as OpenReliant keeps it in section `openreliant_name`; null for a mission
    /// without one, or one whose section holds anything else.
    pub fn openReliantName(mission: Mission) ?[]const u8 {
        const slot = mission.entry(.openreliant_name);
        if (!slot.isUsed() or slot.offset > mission.image.len) return null;
        const bytes = mission.image[slot.offset..];
        return OpenReliantName.read(bytes[0..@min(slot.count, bytes.len)]);
    }

    /// The script's named routines, in the order the loader installs them.
    pub fn parts(mission: Mission) Error![]align(1) const Part {
        return mission.records(Part, .parts);
    }

    /// The part that `text` picks: its number in the part table, as `sltool dte parts` lists
    /// them, or its name or a piece of it in any case, such as `zakov launch` for
    /// `<F> SETUP ZAKOV LAUNCH`. Parts without a block are never picked.
    pub fn findPart(mission: Mission, text: []const u8) Error!Found {
        return mission.findNamed(Part, try mission.parts(), text, Part.isEmpty);
    }

    /// The ship that `text` picks: its number in the ship table, as `sltool dte ships` lists
    /// them, or its name or a piece of it in any case. Nav points and markers are never picked
    /// (`Ship.isMarker`).
    pub fn findShip(mission: Mission, text: []const u8) Error!Found {
        return mission.findNamed(Ship, try mission.ships(), text, Ship.isMarker);
    }

    /// The record of `all` that `text` picks, by its index, by its whole name in any case, or by a
    /// piece of its name where no record has that whole name, passing over the records `left_out`
    /// picks. A name the game pads with spaces counts without them.
    fn findNamed(mission: Mission, comptime T: type, all: []align(1) const T, text: []const u8, left_out: fn (T) bool) Found {
        if (std.fmt.parseInt(usize, text, 10)) |number| {
            return if (number < all.len and !left_out(all[number])) .{ .one = number } else .none;
        } else |_| {}
        var whole: Found = .none;
        var piece: Found = .none;
        for (all, 0..) |record, index| {
            if (left_out(record)) continue;
            const named = std.mem.trim(u8, mission.name(record.name), " ");
            if (std.ascii.eqlIgnoreCase(named, text)) {
                whole = if (whole == .none) .{ .one = index } else .several;
            } else if (std.ascii.findIgnoreCase(named, text) != null) {
                piece = if (piece == .none) .{ .one = index } else .several;
            }
        }
        return if (whole != .none) whole else piece;
    }

    pub fn ships(mission: Mission) Error![]align(1) const Ship {
        return mission.records(Ship, .ships);
    }

    /// The player's own record: the first, since in a single-player game the player's ship is the
    /// first object (`player_index`), and the mission's ships take the objects' places in turn
    /// (`mission_ship_create`). Null for a mission with no ships.
    pub fn player(mission: Mission) Error!?Ship {
        const all = try mission.ships();
        return if (all.len > 0) all[0] else null;
    }

    pub fn triggers(mission: Mission) Error![]align(1) const Trigger {
        return mission.records(Trigger, .triggers);
    }

    /// The object table, indexed by object ID.
    pub fn objects(mission: Mission) Error![]align(1) const Object {
        return mission.records(Object, .objects);
    }

    pub fn flightGroups(mission: Mission) Error![]align(1) const FlightGroup {
        return mission.records(FlightGroup, .flight_groups);
    }

    pub fn squadMembers(mission: Mission) Error![]align(1) const SquadMember {
        return mission.records(SquadMember, .squad_members);
    }

    pub fn squads(mission: Mission) Error![]align(1) const Squad {
        return mission.records(Squad, .squads);
    }

    pub fn curves(mission: Mission) Error![]align(1) const Curve {
        return mission.records(Curve, .curves);
    }

    pub fn formations(mission: Mission) Error![]align(1) const Formation {
        return mission.records(Formation, .formations);
    }

    pub fn formationPoints(mission: Mission) Error![]align(1) const FormationPoint {
        return mission.records(FormationPoint, .formation_points);
    }

    /// The members of squad `squad` from its first (`SquadMember.run`). None for a squad the
    /// mission lacks.
    pub fn membersOf(mission: Mission, squad: usize) Error![]align(1) const SquadMember {
        const list = try mission.squads();
        if (squad >= list.len) return &.{};
        return SquadMember.run(try mission.squadMembers(), squad, list[squad].first_member);
    }

    /// The points of formation `formation` (`FormationPoint.Walk`), where the mission has the
    /// formation.
    pub fn formationWalk(mission: Mission, formation: usize) Error!?FormationPoint.Walk {
        const list = try mission.formations();
        if (formation >= list.len) return null;
        return .{ .points = try mission.formationPoints(), .formation = formation, .at = list[formation].first_point };
    }

    /// The points of formation `formation`, by their indices (`FormationPoint.Walk`). None for a
    /// formation the mission lacks.
    pub fn pointsOf(mission: Mission, allocator: Allocator, formation: usize) (Error || Allocator.Error)![]u16 {
        var walk = try mission.formationWalk(formation) orelse return &.{};
        var found: std.ArrayList(u16) = .empty;
        while (walk.next()) |point| try found.append(allocator, point);
        return found.toOwnedSlice(allocator);
    }

    /// For each trigger, the ID of the object whose slice holds it, or null when none does and
    /// the trigger can never fire. No shipped trigger is in two slices; for one that is, the first
    /// object's, as the engine finds it (`0x00453530`).
    pub fn triggerObjects(mission: Mission, allocator: Allocator) (Error || Allocator.Error)![]?u16 {
        const all = try mission.triggers();
        const owners = try allocator.alloc(?u16, all.len);
        @memset(owners, null);
        for (try mission.objects(), 0..) |object, id| {
            const first, const end = object.triggerBounds(all.len);
            for (owners[first..end]) |*owner| {
                if (owner.* == null) owner.* = @intCast(id);
            }
        }
        return owners;
    }

    /// The script section as routines in address order: first the blocks that triggers run, then
    /// the parts. Together, with their constants, they cover the whole section.
    pub fn routines(mission: Mission, allocator: Allocator) (Error || Allocator.Error)![]Routine {
        const code = try mission.script();
        const all_triggers = try mission.triggers();
        const owners = try mission.triggerObjects(allocator);
        defer allocator.free(owners);

        var result: std.ArrayList(Routine) = .empty;
        errdefer result.deinit(allocator);

        var first_part: usize = code.len;
        for (try mission.parts(), 0..) |part, index| {
            if (part.isEmpty()) continue;
            first_part = @min(first_part, part.start());
            try result.append(allocator, .{
                .start = part.start(),
                .extent = part.size(),
                .owner = .{ .part = @intCast(index) },
            });
        }

        // Group the triggers that can fire by the block they run. Blocks shared by several
        // triggers are common.
        var by_block: std.array_hash_map.Auto(usize, std.ArrayList(u16)) = .empty;
        defer {
            for (by_block.values()) |*list| list.deinit(allocator);
            by_block.deinit(allocator);
        }
        for (all_triggers, owners, 0..) |trigger, owner, index| {
            if (owner == null) continue;
            const start = trigger.block() orelse continue;
            if (start >= first_part) continue;
            const slot = try by_block.getOrPut(allocator, start);
            if (!slot.found_existing) slot.value_ptr.* = .empty;
            try slot.value_ptr.append(allocator, @intCast(index));
        }
        const starts = try allocator.dupe(usize, by_block.keys());
        defer allocator.free(starts);
        std.mem.sort(usize, starts, {}, std.sort.asc(usize));
        for (starts, 0..) |start, i| {
            // A trigger block's constants run up to the next block.
            const next = if (i + 1 < starts.len) starts[i + 1] else first_part;
            const list = by_block.getPtr(start).?;
            try result.append(allocator, .{
                .start = start,
                .extent = next - start,
                .owner = .{ .triggers = try list.toOwnedSlice(allocator) },
            });
        }

        std.mem.sort(Routine, result.items, {}, struct {
            fn lessThan(_: void, a: Routine, b: Routine) bool {
                return a.start < b.start;
            }
        }.lessThan);
        return result.toOwnedSlice(allocator);
    }

    pub fn globals(mission: Mission) Error![]align(1) const Global {
        return mission.records(Global, .globals);
    }

    /// Resolves a name. Offsets are relative to the start of the string pool, not to the file, and
    /// the pool is a run of NUL-terminated strings rather than an indexed table.
    pub fn name(mission: Mission, offset: u16) []const u8 {
        const pool = mission.entry(.strings);
        if (!pool.isUsed()) return "";
        const start = std.math.add(usize, pool.offset, offset) catch return "";
        if (start >= mission.image.len) return "";
        const rest = mission.image[start..];
        const end = std.mem.findScalar(u8, rest, 0) orelse return "";
        return rest[0..end];
    }

    /// Where the string pool ends, which is where the next used section begins.
    pub fn stringPoolEnd(mission: Mission) usize {
        const pool = mission.entry(.strings);
        if (!pool.isUsed()) return 0;
        var end = mission.image.len;
        for (mission.directory) |slot| {
            if (slot.isUsed() and slot.offset > pool.offset and slot.offset < end) end = slot.offset;
        }
        return end;
    }
};

/// A mission's records for the tests here and in the modules that bind or run missions, as a
/// mission's file holds them.
pub const testing = struct {
    /// A ship's record: `object_id`, in `flight_group`, of `kind`, flown by no pilot, launching
    /// from nothing, and fitted by the campaign's loadout tier.
    pub fn ship(object_id: u32, flight_group: u8, kind: u16) Ship {
        var made = std.mem.zeroes(Ship);
        made.object_id = object_id;
        made.flight_group = flight_group;
        made.kind = kind;
        made.pilot = Ship.no_pilot;
        made.launch_gate = Ship.no_launch;
        made.tier = Ship.campaign_tier;
        return made;
    }

    /// `count` ship records of `kind`, each in no flight group, its object ID its index.
    pub fn ships(comptime count: usize, kind: u16) [count]Ship {
        var made: [count]Ship = undefined;
        for (&made, 0..) |*record, index| record.* = ship(@intCast(index), Ship.no_flight_group, kind);
        return made;
    }

    /// A flight group's record: `object_id`, in `wing`.
    pub fn flightGroup(object_id: u16, wing: FlightGroup.Wing) FlightGroup {
        var made = std.mem.zeroes(FlightGroup);
        made.object_id = object_id;
        made.wing = wing;
        return made;
    }

    /// A squad's record: `object_id`, its members from `first_member`.
    pub fn squad(object_id: u16, first_member: u16) Squad {
        var made = std.mem.zeroes(Squad);
        made.object_id = object_id;
        made.first_member = first_member;
        return made;
    }

    /// A squad's member: object `object_id`, of squad `squad_index`, as its component
    /// `component`, or whole for `Trigger.whole_object`.
    pub fn squadMember(object_id: u16, squad_index: u16, component: u8) SquadMember {
        return .{ .object_id = object_id, ._unknown_02 = 0, .squad = squad_index, ._unknown_06 = 0, .component = component, ._unknown_09 = @splat(0) };
    }

    /// The records of a chain of `count` squads after `leading` ships, which take objects 0 to
    /// `leading - 1`: each squad names the next one twice, and the last names ship 0 twice, so a
    /// walk down every member would reach ship 0 2^`count` times.
    pub fn DoubledChain(comptime leading: usize, comptime count: usize) type {
        return struct {
            objects: [leading + count]Object,
            squads: [count]Squad,
            members: [2 * count]SquadMember,

            pub fn init() @This() {
                var made: @This() = undefined;
                for (made.objects[0..leading]) |*entry| entry.* = object(.ship, 0, 0);
                for (0..count) |index| {
                    made.objects[leading + index] = object(.squad, 0, 0);
                    made.squads[index] = squad(@intCast(leading + index), @intCast(2 * index));
                    const named: u16 = if (index + 1 < count) @intCast(leading + index + 1) else 0;
                    made.members[2 * index] = squadMember(named, @intCast(index), Trigger.whole_object);
                    made.members[2 * index + 1] = made.members[2 * index];
                }
                return made;
            }
        };
    }

    /// An entry of the object table: a record of `kind`, holding `count` triggers from `first`.
    pub fn object(kind: Object.Kind, first: u16, count: u8) Object {
        return .{ .kind = kind, .count = count, .first = first, .tool_flags = .{} };
    }

    /// A curve from ship `start` at `from` to ship `end` at `to`, with no tangents.
    pub fn curve(start: u16, end: u16, from: [3]f32, to: [3]f32) Curve {
        var made = std.mem.zeroes(Curve);
        made.start = .{ .index = start, .tag = .ship, ._unknown_24 = 0xFF };
        made.end = .{ .index = end, .tag = .ship, ._unknown_24 = 0xFF };
        made.from = from;
        made.to = to;
        return made;
    }
};

test "directory and records line up" {
    // A mission image with a string pool and one ship.
    var image: [0x400]u8 = @splat(0);
    const directory: []align(1) DirectoryEntry =
        @alignCast(std.mem.bytesAsSlice(DirectoryEntry, image[0 .. section_count * 8]));
    for (directory) |*slot| slot.* = .{
        .count = 0,
        ._unused = 0,
        .formats = .{},
        .offset = DirectoryEntry.unused_offset,
    };

    const pool_at = 0x100;
    directory[@backingInt(Section.strings)] = .{
        .count = 2,
        ._unused = 0,
        .formats = .all,
        .offset = pool_at,
    };
    @memcpy(image[pool_at..][0..12], "Player_Ship\x00");

    const ships_at = 0x200;
    directory[@backingInt(Section.ships)] = .{
        .count = 1,
        ._unused = 0,
        .formats = .all,
        .offset = ships_at,
    };
    const ship: *align(1) Ship = @ptrCast(image[ships_at..][0..@sizeOf(Ship)]);
    ship.* = std.mem.zeroes(Ship);
    ship.object_id = 3;
    ship.name = 0;
    ship.pilot = Ship.no_pilot;
    ship.kind = Ship.nav_point_kind;
    ship.yaw = 90;
    ship.roll = -1;

    const mission: Mission = try .parse(&image);
    const list = try mission.ships();
    try std.testing.expectEqual(@as(usize, 1), list.len);
    try std.testing.expectEqualStrings("Player_Ship", mission.name(list[0].name));
    try std.testing.expectEqual(Ship.nav_point_kind, list[0].kind);
    try std.testing.expectEqual(@as(i16, 90), list[0].yaw);

    // The player's own record is the first.
    try std.testing.expectEqual(@as(u32, 3), (try mission.player()).?.object_id);
    // Without OpenReliant's section, the mission has no name of OpenReliant's.
    try std.testing.expectEqual(null, mission.openReliantName());
    const name_at = 0x300;
    directory[@backingInt(Section.openreliant_name)] = .{ .count = 8 + 12, ._unused = 0, .formats = .all, .offset = name_at };
    @as(*align(1) OpenReliantName, @ptrCast(image[name_at..][0..8])).* = .{ .length = 11 };
    @memcpy(image[name_at + 8 ..][0..12], "The Sandbox\x00");
    try std.testing.expectEqualStrings("The Sandbox", (try Mission.parse(&image)).openReliantName().?);

    // An unused section yields nothing rather than reading stray bytes.
    try std.testing.expectEqual(@as(usize, 0), (try mission.triggers()).len);

    // Where each section's records lie: none for an unused one; past the image, an error.
    try std.testing.expectEqual(Mission.Span{ .offset = ships_at, .count = 1 }, (try mission.span(.ships)).?);
    try std.testing.expectEqual(null, try mission.span(.triggers));
    // A section's reservation runs to the next section's start, and the last one's to the image's
    // end, whatever its records fill.
    try std.testing.expectEqual(ships_at - pool_at, mission.room(.strings));
    try std.testing.expectEqual(name_at - ships_at, mission.room(.ships));
    try std.testing.expectEqual(image.len - name_at, mission.room(.openreliant_name));
    try std.testing.expectEqual(0, mission.room(.triggers));
    directory[@backingInt(Section.ships)].offset = image.len + 1;
    try std.testing.expectError(error.Truncated, (try Mission.parse(&image)).span(.ships));
    // A string pool placed so that its offset and a name's add up past the image names nothing,
    // even past what 32 bits hold.
    directory[@backingInt(Section.strings)].offset = std.math.maxInt(u32) - 4;
    try std.testing.expectEqualStrings("", (try Mission.parse(&image)).name(0x20));
}

test "Mission.findPart and findShip" {
    // Three parts, the last without a block, and two ships and a nav point.
    var image: [0x400]u8 = @splat(0);
    const directory: []align(1) DirectoryEntry =
        @alignCast(std.mem.bytesAsSlice(DirectoryEntry, image[0 .. section_count * 8]));
    for (directory) |*slot| slot.* = .{ .count = 0, ._unused = 0, .formats = .{}, .offset = DirectoryEntry.unused_offset };
    const pool_at = 0x100;
    const names = "<F> Startlaunch\x00<F> SETUP ZAKOV LAUNCH\x00<F> Zakov gone\x00ZAKOV\x00Nav ZAKOV\x00ZAKOV ESCORT\x00";
    directory[@backingInt(Section.strings)] = .{ .count = 6, ._unused = 0, .formats = .all, .offset = pool_at };
    @memcpy(image[pool_at..][0..names.len], names);
    const parts_at = 0x200;
    directory[@backingInt(Section.parts)] = .{ .count = 3, ._unused = 0, .formats = .all, .offset = parts_at };
    const parts: []align(1) Part = @alignCast(std.mem.bytesAsSlice(Part, image[parts_at..][0 .. 3 * @sizeOf(Part)]));
    for (parts, [_]u16{ 0, 16, 39 }, [_]u16{ 0, 8, Part.no_block }) |*part, name, offset| {
        part.* = std.mem.zeroes(Part);
        part.name = name;
        part.offset = offset;
    }
    const ships_at = 0x300;
    directory[@backingInt(Section.ships)] = .{ .count = 3, ._unused = 0, .formats = .all, .offset = ships_at };
    const ships: []align(1) Ship = @alignCast(std.mem.bytesAsSlice(Ship, image[ships_at..][0 .. 3 * @sizeOf(Ship)]));
    ships[0] = testing.ship(0, Ship.no_flight_group, 0);
    ships[0].name = 54;
    ships[1] = testing.ship(1, Ship.no_flight_group, Ship.nav_point_kind);
    ships[1].name = 60;
    ships[2] = testing.ship(2, Ship.no_flight_group, 0);
    ships[2].name = 70;
    const mission: Mission = try .parse(&image);

    // By number, or by a piece of its name in any case.
    try std.testing.expectEqual(Found{ .one = 1 }, try mission.findPart("1"));
    try std.testing.expectEqual(Found{ .one = 1 }, try mission.findPart("zakov launch"));
    try std.testing.expectEqual(Found{ .one = 0 }, try mission.findPart("STARTLAUNCH"));
    // A piece of two names, and parts that are missing or have no block.
    try std.testing.expectEqual(Found.several, try mission.findPart("<F>"));
    try std.testing.expectEqual(Found.none, try mission.findPart("kirov"));
    try std.testing.expectEqual(Found.none, try mission.findPart("3"));
    try std.testing.expectEqual(Found.none, try mission.findPart("2"));
    try std.testing.expectEqual(Found.none, try mission.findPart("gone"));
    // Ships likewise, passing over the nav points.
    try std.testing.expectEqual(Found{ .one = 2 }, try mission.findShip("escort"));
    // A whole name picks its record, though it is a piece of another's too.
    try std.testing.expectEqual(Found{ .one = 0 }, try mission.findShip("zakov"));
    try std.testing.expectEqual(Found{ .one = 0 }, try mission.findShip("0"));
    try std.testing.expectEqual(Found.none, try mission.findShip("1"));
    try std.testing.expectEqual(Found.none, try mission.findShip("nav"));
}

test OpenReliantName {
    var section: [@sizeOf(OpenReliantName) + 8]u8 = undefined;
    @as(*align(1) OpenReliantName, @ptrCast(section[0..8])).* = .{ .length = 7 };
    @memcpy(section[8..], "Sandbox\x00");
    try std.testing.expectEqualStrings("Sandbox", OpenReliantName.read(&section).?);
    // Too short for its name, of another tag or of a later version, it is left alone.
    try std.testing.expectEqual(null, OpenReliantName.read(section[0..10]));
    section[0] = 'X';
    try std.testing.expectEqual(null, OpenReliantName.read(&section));
    section[0] = 'O';
    section[4] = 2;
    try std.testing.expectEqual(null, OpenReliantName.read(&section));
}

test "rejects a compressed or truncated image" {
    try std.testing.expectError(error.Compressed, Mission.parse(&.{ 0x10, 0xFB, 0, 0, 0 }));
    try std.testing.expectError(error.NotAMission, Mission.parse(&.{ 0, 1, 2 }));
}

test "condition names cover the scriptable range" {
    try std.testing.expectEqual(@as(u8, 0x20), @backingInt(Condition.last_scriptable));
    try std.testing.expectEqual(Condition.proximity_close, @as(Condition, @fromBackingInt(5)));
    // The two internal conditions are named; past them the enum stays open.
    try std.testing.expectEqual(Condition.explosion_ship, @as(Condition, @fromBackingInt(0x22)));
    const internal: Condition = @fromBackingInt(0x23);
    try std.testing.expect(std.enums.tagName(Condition, internal) == null);
}

test "Condition.keeps" {
    // A trigger keeps the values the matcher checks, and a Proximity trigger its distance too.
    try std.testing.expectEqual(.check, Condition.proximity_general.keeps(0));
    try std.testing.expectEqual(.distance, Condition.proximity_general.keeps(Trigger.proximity_distance));
    // CloseProximity's watches look a fixed distance, so its triggers keep none.
    try std.testing.expectEqual(.nothing, Condition.proximity_close.keeps(Trigger.proximity_distance));
    // Shot At's shield damage isn't checked, and it carries no sixth value.
    try std.testing.expectEqual(.nothing, Condition.shot_at.keeps(1));
    try std.testing.expectEqual(.nothing, Condition.shot_at.keeps(5));
}

test "decodes a block down to its alignment padding" {
    // The opening block of mission1: call, command, read a global, push a constant, compare,
    // branch, call, jump, call, command, push a byte, return, then two bytes that pad the block to
    // a multiple of four.
    const section = [_]u8{
        0x1C, 0x00, 0x22, 0x01, 0x21, 0x17, 0x27, 0x00, 0x28, 0x00, 0x02, 0x24, 0x00, 0x07,
        0x22, 0x15, 0x42, 0x00, 0x04, 0x22, 0x18, 0x21, 0x17, 0x32, 0x01, 0x43, 0x32, 0x01,
    };
    var reader = BlockReader.at(&section, 0).?;
    try std.testing.expectEqual(@as(u16, 0x1C), reader.declared);
    try std.testing.expect(!reader.isShort());
    try std.testing.expectEqual(@as(usize, 26), reader.code.len);

    const expected = [_]Opcode{
        .call_part, .command, .push_global, .push_constant, .equal,     .branch_if_zero_alt,
        .call_part, .jump,    .call_part,   .command,       .push_byte, .@"return",
    };
    for (expected) |opcode| {
        try std.testing.expectEqual(opcode, reader.next().?.opcode);
    }
    try std.testing.expectEqual(@as(?Instruction, null), reader.next());
    try std.testing.expectEqual(BlockReader.Stop.complete, reader.stop());
    try std.testing.expectEqual(@as(usize, 24), reader.pos);
    try std.testing.expectEqualSlices(u8, &.{ 0x32, 0x01 }, reader.padding());
}

test "decodes an inline string and steps over it" {
    // The opening block of mission81, which cues a speech file by name.
    const section = [_]u8{
        0x58, 0x00, 0x28, 0x00, 0x21, 0x05, 0x2A, 0x0F,
    } ++ "new_sim02.wav\x00".* ++ [_]u8{ 0x28, 0x01 };
    var reader = BlockReader.at(&section, 0).?;
    // The block claims more than the section holds, so it is clamped rather than rejected.
    try std.testing.expect(reader.isShort());

    try std.testing.expectEqual(Opcode.push_constant, reader.next().?.opcode);
    try std.testing.expectEqual(Opcode.command, reader.next().?.opcode);

    const speech = reader.next().?;
    try std.testing.expectEqual(Opcode.push_string, speech.opcode);
    try std.testing.expectEqualStrings("new_sim02.wav\x00", speech.flow.inline_data);
    try std.testing.expectEqual(Opcode.push_constant, reader.next().?.opcode);
}

test "the records' none values" {
    var ship = std.mem.zeroes(Ship);
    ship.flight_group = Ship.no_flight_group;
    ship.kind = Ship.waypoint_kind;
    ship.pilot = Ship.no_pilot;
    ship.launch_gate = Ship.no_launch;
    ship.formation_point = Ship.no_formation_point;
    try std.testing.expectEqual(null, ship.flightGroup());
    try std.testing.expect(ship.isWaypoint());
    try std.testing.expect(ship.isMarker());
    try std.testing.expectEqual(null, ship.pilotRecord());
    try std.testing.expectEqual(null, ship.launchGate());
    try std.testing.expectEqual(null, ship.formationPoint());
    ship.flight_group = 3;
    ship.pilot = 42;
    ship.launch_gate = 2;
    ship.formation_point = 5;
    try std.testing.expectEqual(3, ship.flightGroup());
    try std.testing.expectEqual(42, ship.pilotRecord());
    try std.testing.expectEqual(2, ship.launchGate());
    try std.testing.expectEqual(5, ship.formationPoint());

    var group = std.mem.zeroes(FlightGroup);
    group.first_ship = FlightGroup.no_ship;
    try std.testing.expectEqual(null, group.firstShip());
    group.first_ship = 4;
    try std.testing.expectEqual(4, group.firstShip());

    var squad = std.mem.zeroes(Squad);
    squad.first_member = Squad.no_member;
    try std.testing.expectEqual(null, squad.firstMember());

    var trigger = std.mem.zeroes(Trigger);
    trigger.qualifier = Trigger.whole_object;
    try std.testing.expectEqual(null, trigger.component());
    trigger.qualifier = 2;
    try std.testing.expectEqual(2, trigger.component());

    try std.testing.expectEqual(null, testing.squadMember(0, 0, Trigger.whole_object).part());
    try std.testing.expectEqual(2, testing.squadMember(0, 0, 2).part());

    const curve = testing.curve(Reference.unset, 3, @splat(0), @splat(0));
    try std.testing.expectEqual(null, curve.startShip());
    try std.testing.expectEqual(3, curve.endShip());
    try std.testing.expectEqual(5, testing.curve(5, Reference.unset, @splat(0), @splat(0)).startShip());
    try std.testing.expectEqual(null, testing.curve(5, Reference.unset, @splat(0), @splat(0)).endShip());
}

test "Ship.isMarker" {
    var ship = testing.ship(0, Ship.no_flight_group, 2);
    try std.testing.expect(!ship.isMarker());
    for ([_]u16{ Ship.nav_point_kind, Ship.waypoint_kind, Ship.curve_point_kind, Ship.point_kind }) |kind| {
        ship.kind = kind;
        try std.testing.expect(ship.isMarker());
    }
    // The other kinds of the range the markers share are ships to it.
    ship.kind = 0x3E6;
    try std.testing.expect(!ship.isMarker());
}

test "Ship.componentIntact" {
    var ship = testing.ship(0, Ship.no_flight_group, 2);
    ship.intact_components = Ship.all_intact;
    try std.testing.expect(ship.componentIntact(3));
    ship.loseComponent(3);
    try std.testing.expect(!ship.componentIntact(3));
    try std.testing.expect(ship.componentIntact(4));
    try std.testing.expectEqual(~@as(u32, 1 << 3), ship.intact_components);
    // Component 35 shares component 3's bit.
    try std.testing.expect(!ship.componentIntact(35));
    ship.intact_components = Ship.all_intact;
    ship.loseComponent(35);
    try std.testing.expect(!ship.componentIntact(3));
}

test "the records' references" {
    // A squad as the shipped missions hold one: object ID 0x40, named at 0x1234, and from its
    // first member on, a reference to member record 5.
    const bytes = [_]u8{ 0x40, 0, 0, 0, 0x34, 0x12, 0, 0, 5, 0, 0x17, 0xFF };
    const squad = std.mem.bytesToValue(Squad, &bytes);
    try std.testing.expectEqual(0x1234, squad.name);
    try std.testing.expectEqual(5, squad.firstMember().?);
    const member: Reference = @bitCast(std.mem.readInt(u32, bytes[8..12], .little));
    try std.testing.expectEqual(Reference{ .index = 5, .tag = .squad_member, ._unknown_24 = 0xFF }, member);
    // Every shipped flight group's last word.
    try std.testing.expectEqual(0xFF19FFFF, @as(u32, @bitCast(FlightGroup.no_formation)));
}

test "Object.ToolFlags" {
    try std.testing.expectEqual(Object.ToolFlags{ .player = true }, @as(Object.ToolFlags, @bitCast(@as(u32, 1))));
    try std.testing.expectEqual(Object.ToolFlags{ .curve_point = true }, @as(Object.ToolFlags, @bitCast(@as(u32, 8))));
}

test "SquadMember.run" {
    const whole = Trigger.whole_object;
    const members = [_]SquadMember{
        testing.squadMember(1, 0, whole),
        testing.squadMember(2, 0, whole),
        testing.squadMember(3, 1, whole),
        testing.squadMember(4, 0, whole),
    };
    // From the first, while they are the squad's own: squad 0's last member, past squad 1's, is
    // none of the walk's.
    try std.testing.expectEqual(2, SquadMember.run(&members, 0, 0).len);
    try std.testing.expectEqual(1, SquadMember.run(&members, 1, 2).len);
    try std.testing.expectEqual(0, SquadMember.run(&members, 0, 2).len);
    try std.testing.expectEqual(0, SquadMember.run(&members, 0, Squad.no_member).len);
}

test "FormationPoint.Walk" {
    var points: [4]FormationPoint = @splat(.blank);
    points[0].formation = 1;
    points[2].formation = 1;
    // From the formation's first point on, those that name it, past another's between them.
    var walk: FormationPoint.Walk = .{ .points = &points, .formation = 1, .at = 0 };
    try std.testing.expectEqual(0, walk.next().?);
    try std.testing.expectEqual(2, walk.next().?);
    try std.testing.expectEqual(null, walk.next());
}

test "FlightGroup.Wing" {
    var buffer: [16]u8 = undefined;
    try std.testing.expectEqualStrings("player", try std.mem.print(&buffer, "{f}", .{FlightGroup.Wing.player}));
    try std.testing.expectEqualStrings("7", try std.mem.print(&buffer, "{f}", .{@as(FlightGroup.Wing, @fromBackingInt(7))}));
    try std.testing.expectEqual(.none, testing.flightGroup(0, .none).wing);
}

test "DirectoryEntry.Formats" {
    const first: DirectoryEntry.Formats = .{ .first = true, ._unused = 5 };
    const noted = first.noting(.{ .third = true, ._unused = 0xF });
    // The four flags gather; the bits past them stay as they were.
    try std.testing.expectEqual(DirectoryEntry.Formats{ .first = true, .third = true, ._unused = 5 }, noted);
    try std.testing.expectEqual(0x0F, DirectoryEntry.Formats.all.byte());
}

test "the implemented opcode range matches the payload's handler table" {
    try std.testing.expect(Opcode.equal.isImplemented());
    try std.testing.expect(Opcode.spawn_part.isImplemented());
    try std.testing.expect(@as(Opcode, @fromBackingInt(0x55)).isImplemented());
    // Null entries in the table: no handler, so the opcode does not exist.
    try std.testing.expect(!@as(Opcode, @fromBackingInt(0x00)).isImplemented());
    try std.testing.expect(!@as(Opcode, @fromBackingInt(0x10)).isImplemented());
    try std.testing.expect(!@as(Opcode, @fromBackingInt(0x56)).isImplemented());
    // Between the second command table and the random branch, the table holds no handler.
    try std.testing.expect(!@as(Opcode, @fromBackingInt(0x50)).isImplemented());
}

test "an unnamed value formats as a number instead of panicking" {
    var buffer: [32]u8 = undefined;

    var named: std.Io.Writer = .fixed(&buffer);
    try named.print("{f}", .{Condition.destroyed});
    try std.testing.expectEqualStrings("destroyed", named.buffered());

    // `{t}` would panic here; this path is generated per tag at comptime and cannot.
    var unnamed: std.Io.Writer = .fixed(&buffer);
    try unnamed.print("{f}", .{@as(Condition, @fromBackingInt(0x23))});
    try std.testing.expectEqualStrings("35", unnamed.buffered());

    var repeat: std.Io.Writer = .fixed(&buffer);
    try repeat.print("{f}", .{@as(Trigger.Repeat, @fromBackingInt(3))});
    try std.testing.expectEqualStrings("3", repeat.buffered());
}

test "follows a branch rather than sweeping past a jump" {
    // The opening block of mission1, as a section with its length prefix. The `jump` at 14 never
    // falls through, so 17 is reached only by the `branch_if_zero_alt` at 9.
    const section = [_]u8{
        0x1C, 0x00, 0x22, 0x01, 0x21, 0x17, 0x27, 0x00, 0x28, 0x00, 0x02, 0x24, 0x00, 0x07,
        0x22, 0x15, 0x42, 0x00, 0x04, 0x22, 0x18, 0x21, 0x17, 0x32, 0x01, 0x43, 0x32, 0x01,
    };
    const disassembly = (try disassemble(std.testing.allocator, &section, 0)).?;
    defer std.testing.allocator.free(disassembly.instructions);

    try std.testing.expect(!disassembly.incomplete);
    try std.testing.expectEqual(@as(usize, 0), disassembly.unreached);

    // Addresses are offsets into the section, so the header shifts them by two.
    const expected = [_]struct { usize, Opcode }{
        .{ 2, .call_part },     .{ 4, .command },    .{ 6, .push_global },
        .{ 8, .push_constant }, .{ 10, .equal },     .{ 11, .branch_if_zero_alt },
        .{ 14, .call_part },    .{ 16, .jump },      .{ 19, .call_part },
        .{ 21, .command },      .{ 23, .push_byte }, .{ 25, .@"return" },
    };
    try std.testing.expectEqual(expected.len, disassembly.instructions.len);
    for (expected, disassembly.instructions) |want, got| {
        try std.testing.expectEqual(want[0], got.address);
        try std.testing.expectEqual(want[1], got.opcode);
    }
    // The branch and the jump agree on where the two arms are, and only the jump is unconditional.
    const branch = disassembly.instructions[5].flow.branch;
    try std.testing.expectEqual(@as(usize, 19), branch.target);
    try std.testing.expect(branch.conditional);
    const jump = disassembly.instructions[7].flow.branch;
    try std.testing.expectEqual(@as(usize, 21), jump.target);
    try std.testing.expect(!jump.conditional);
    try std.testing.expect(!disassembly.instructions[11].fallsThrough());
}

test "reads a weighted branch's arms" {
    // The one shape whose encoding is read by hand: a count, a default target, then that many
    // four-byte arms of target and threshold. This one is the 50/50 split in mission18.
    const code = [_]u8{ 0x51, 0x02, 0x00, 0x43, 0x00, 0x2C, 0x32, 0x00, 0x00, 0x39, 0x64, 0x00 };
    const instruction = decodeAt(&code, 0).?;
    try std.testing.expectEqual(Opcode.random_branch, instruction.opcode);
    try std.testing.expectEqual(@as(usize, code.len), instruction.size());
    try std.testing.expect(!instruction.fallsThrough());

    var iterator = instruction.flow.random;
    try std.testing.expectEqual(@as(?usize, 0x43), iterator.next());
    try std.testing.expectEqual(@as(?usize, 0x2C), iterator.next());
    try std.testing.expectEqual(@as(?usize, 0x39), iterator.next());
    try std.testing.expectEqual(@as(?usize, null), iterator.next());
}

test "a part's offset and length are in halfwords" {
    var part = std.mem.zeroes(Part);
    part.offset = 870;
    part.length = 96;
    part.arguments = 2;
    try std.testing.expectEqual(@as(usize, 1740), part.start());
    try std.testing.expectEqual(@as(usize, 192), part.size());
    try std.testing.expect(!part.isEmpty());

    part.offset = Part.no_block;
    try std.testing.expect(part.isEmpty());
}

test "maps the script into trigger blocks and parts, with their constants" {
    var image: [0x300]u8 = @splat(0);
    const directory: []align(1) DirectoryEntry =
        @alignCast(std.mem.bytesAsSlice(DirectoryEntry, image[0 .. section_count * 8]));
    for (directory) |*slot| slot.* = .{
        .count = 0,
        ._unused = 0,
        .formats = .{},
        .offset = DirectoryEntry.unused_offset,
    };
    const place = struct {
        fn at(dir: []align(1) DirectoryEntry, section: Section, count: u16, offset: u32) void {
            dir[@backingInt(section)] = .{ .count = count, ._unused = 0, .formats = .all, .offset = offset };
        }
    }.at;

    // Two triggers. Only the first is in an object's slice; the second links to junk, which is
    // harmless because nothing can fire it.
    const triggers_at = 0x100;
    place(directory, .triggers, 2, triggers_at);
    const both: []align(1) Trigger = @alignCast(std.mem.bytesAsSlice(Trigger, image[triggers_at..][0 .. 2 * @sizeOf(Trigger)]));
    both[0] = std.mem.zeroes(Trigger);
    both[0].condition = .destroyed;
    both[0].link = 0;
    both[0].armed = 1;
    both[0].qualifier = Trigger.whole_object;
    both[1] = both[0];
    both[1].condition = .shot_at;
    both[1].link = 1;

    const slices_at = 0x180;
    place(directory, .objects, 1, slices_at);
    (try layout.viewMut(Object, image[slices_at..])).* = testing.object(.ship, 0, 1);

    // One part, at byte 16, spanning its block and one 8-byte unit of constants.
    const parts_at = 0x1A0;
    place(directory, .parts, 1, parts_at);
    const part = try layout.viewMut(Part, image[parts_at..]);
    part.offset = 8;
    part.length = 6;

    const script_at = 0x200;
    const script = [_]u8{
        // The trigger's block: push constant 0, return, padding. Then its constants.
        0x08, 0x00, 0x28, 0x00, 0x43, 0x00, 0x00, 0x00,
        0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        // The part's block: return, padding. Then its constants.
        0x04, 0x00, 0x43, 0x00, 0x2A, 0x00, 0x00, 0x00,
        0x00, 0x00, 0x00, 0x00,
    };
    place(directory, .script, script.len / 2, script_at);
    @memcpy(image[script_at..][0..script.len], &script);

    const mission: Mission = try .parse(&image);
    const objects = try mission.triggerObjects(std.testing.allocator);
    defer std.testing.allocator.free(objects);
    try std.testing.expectEqualSlices(?u16, &.{ 0, null }, objects);

    const map = try mission.routines(std.testing.allocator);
    defer {
        for (map) |routine| switch (routine.owner) {
            .triggers => |indices| std.testing.allocator.free(indices),
            .part => {},
        };
        std.testing.allocator.free(map);
    }
    try std.testing.expectEqual(@as(usize, 2), map.len);

    try std.testing.expectEqual(@as(usize, 0), map[0].start);
    try std.testing.expectEqual(@as(usize, 16), map[0].extent);
    try std.testing.expectEqualSlices(u16, &.{0}, map[0].owner.triggers);
    const code = try mission.script();
    try std.testing.expectEqual(@as(u32, 7), map[0].constants(code)[0]);

    try std.testing.expectEqual(@as(usize, 16), map[1].start);
    try std.testing.expectEqual(@as(u16, 0), map[1].owner.part);
    try std.testing.expectEqual(@as(u32, 0x2A), map[1].constants(code)[0]);
}

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