tiny.game.session

1pub const session = @import("session.zig");

1//! Recording and replay of the input each step of a run received, and a reader that gives the input2//! for any step from a short list of input changes. A developer wants to record the input each step3//! of a run received and replay it later, so the same run happens again step for step. A scripted4//! test wants to state its input only at the steps at which the input changes, and to read the5//! input for any step from that list.6//!7//! A replay repeats a run only when every step receives the exact input it received live, in the8//! same order. The memory for a recording is fixed ahead of the run, so a long run can fill it. A9//! value held from one change to the next would repeat a one-time event, such as a reset, on every10//! step until the next change.11//!12//! A recorder (`Session`) stores each step beside the step's input as a fixed-size array of bytes13//! (a *snapshot*), in storage the caller provides. The recorder calls no allocator, and its14//! capacity is the length of the caller's storage. `append` returns `error.SessionCapacityExceeded`15//! once the storage is full. Recording starts at step 0 and takes the steps in order, so `append`16//! returns `error.NonSequentialStep` for a step out of order. `Session.replay` calls the caller's17//! update with each recorded step and snapshot, in order, hands it only the context the caller18//! passes and those two values, and reads no clock of its own. A script lists its input as entries19//! that each hold from the step in their `tick` field until the next entry (*spans*), sorted by20//! step, and `inputAt` gives the input for any one step from that list. The fields a caller lists21//! in `pulse_fields`, such as a reset, keep their value only at the step their span starts, and22//! read false at every later step of that span.23const std = @import("std");24const clock = @import("clock.zig");25const input = @import("input.zig");2627/// Returns the input for step `index` from `spans`: the last span whose `tick` is at or before28/// `index`, with its `tick` set to `index`. A scripted run calls it once per step to turn a short29/// list of input changes into the input for every step. `spans` is sorted by `tick`, ascending,30/// because the scan stops at the first span past `index`. Each span holds its values until the next31/// span starts. Before the first span, every field has its default value. Each field named in32/// `pulse_fields` keeps its span's value only at the span's own `tick`, and reads false at every33/// later step of that span. `Input` gives every field a default value, has a `tick` field that34/// compares with a `u32`, and holds a boolean for each name in `pulse_fields`. The call scans35/// `spans` from the start on every call.36pub fn inputAt(comptime Input: type, spans: []const Input, index: u32, comptime pulse_fields: []const []const u8) Input {37    var active = Input{};38    for (spans) |span| {39        if (span.tick > index) break;40        active = span;41    }42    inline for (pulse_fields) |name| {43        @field(active, name) = @field(active, name) and active.tick == index;44    }45    active.tick = index;46    return active;47}4849/// Returns a recorder type that stores steps with their snapshots of `input_bytes` bytes, in50/// storage the caller provides. A test or a host records a run with it and replays the run later,51/// step for step. The recorder calls no allocator, and its capacity is the length of the slice52/// passed to `init`.53pub fn Session(comptime input_bytes: usize) type {54    return struct {55        const Self = @This();56        /// The snapshot type of this recorder, `input.Snapshot(input_bytes)`. A caller builds each57        /// step's input as this type before it appends the step.58        pub const Input = input.Snapshot(input_bytes);59        /// One recorded step: the `clock.Step` and its snapshot. A caller declares the storage as60        /// an array of these and reads them back from `records`.61        pub const Record = struct { step: clock.Step, input: Input };6263        storage: []Record,64        count: usize = 0,6566        /// Returns an empty recorder that writes into `storage`. A caller passes storage sized for67        /// the longest run it records. The recorder borrows `storage`, so the slice has to outlive68        /// it.69        pub fn init(storage: []Record) Self {70            return .{ .storage = storage };71        }7273        /// Stores `step` and `snapshot` after the last recorded step. A host calls it once per74        /// step, after the clock hands out the step and the game encodes that step's input. The75        /// call returns `error.SessionCapacityExceeded` when the storage is full. The call returns76        /// `error.NonSequentialStep` when `step.index` differs from the number of steps already77        /// recorded, so recording starts at step 0. A full recorder returns the capacity error even78        /// for a step out of order.79        pub fn append(self: *Self, step: clock.Step, snapshot: Input) !void {80            if (self.count == self.storage.len) return error.SessionCapacityExceeded;81            if (step.index != @as(u64, @intCast(self.count))) return error.NonSequentialStep;82            self.storage[self.count] = .{ .step = step, .input = snapshot };83            self.count += 1;84        }8586        /// Returns the recorded steps, in order. A caller reads the stored run back, for example87        /// the `phase` of its last step. The slice points into the caller's storage and covers the88        /// steps recorded when the call returns.89        pub fn records(self: *const Self) []const Record {90            return self.storage[0..self.count];91        }9293        /// Calls `update(context, step, snapshot)` for each recorded step, in order. A test replays94        /// a recording into the update it ran live and checks that both runs end in the same state.95        /// The replay hands `update` only `context` and the recorded step and snapshot, and it96        /// reads no clock of its own. `update` is known at compile time.97        pub fn replay(self: *const Self, context: anytype, comptime update: anytype) void {98            for (self.records()) |record| update(context, record.step, record.input);99        }100    };101}102103test "recorded 60 Hz input replays with identical state hash" {104    const Log = Session(2);105    var storage: [12]Log.Record = undefined;106    var log = Log.init(&storage);107    var timer = try clock.Clock.init(.{ .steps_per_second = 60, .source_frames_per_second = 20 });108    var live_hash: u64 = 14695981039346656037;109    for (0..12) |i| {110        const step = timer.commandStep();111        const snapshot = Log.Input{ .bytes = .{ @intCast(i), @intCast(i * 3) } };112        try log.append(step, snapshot);113        fold(&live_hash, step, snapshot);114    }115    var replay_hash: u64 = 14695981039346656037;116    log.replay(&replay_hash, fold);117    try std.testing.expectEqual(@as(u64, 0x786dd5e860a2d561), live_hash);118    try std.testing.expectEqual(live_hash, replay_hash);119    try std.testing.expectEqual(@as(u32, 2), log.records()[11].step.phase);120}121122fn fold(hash: *u64, step: clock.Step, snapshot: Session(2).Input) void {123    const bytes = [_]u8{ @intCast(step.phase), snapshot.bytes[0], snapshot.bytes[1] };124    for (bytes) |byte| {125        hash.* = (hash.* ^ byte) *% 1099511628211;126    }127}