tiny.game.clock

1//! A clock that turns the time a host measures between draws into fixed simulation steps and2//! numbers each step it hands out. A host wants each step to cover the same span of simulated time3//! however often it draws the screen. A game whose update logic was written for a second, slower4//! rate, for example 20 updates a second inside 60 steps a second, needs each step to know which5//! slower update it falls in and its position inside it. A tool that drives the game headless6//! advances it one step per command, and the game stays at the step it has reached while the tool7//! waits.8//!9//! The time between two draws varies, so it rarely comes to a whole number of steps, and the time10//! left over has to count toward a later step. A long pause between draws owes the simulation many11//! steps at once: 100 milliseconds at 60 steps a second owes six.12//!13//! The caller offers the clock the nanoseconds since its last draw (`Clock.offerElapsed`), and the14//! clock turns them into whole steps and keeps the leftover, as an exact integer, for the next15//! offer. The clock reads no time of its own, and it leaves to the caller the choice of when to16//! draw and whether to blend between steps. Each offer returns the number of steps to run with a17//! count of the whole steps dropped past a cap (a *plan*), and the cap18//! (`Config.max_catch_up_steps`) is four steps unless the caller sets another. For the19//! 100-millisecond pause, the plan holds four steps and counts two dropped. The caller runs every20//! planned step, one call to `Clock.next` each, before it offers time again, and the clock asserts21//! that order. When a caller breaks that order, `Clock.offerElapsed` and `Clock.next` panic in22//! Debug and ReleaseSafe builds, and their behavior is undefined in ReleaseFast and ReleaseSmall23//! builds. For a host driven by commands, `Clock.commandStep` advances exactly one step and reads24//! no elapsed time. Each step (`Step`) carries its index, counted from zero, and its length as a25//! fraction of a second, one over the step rate. Each step also carries which frame of the slower26//! rate it falls in (a *slower frame*) and its position inside that frame, counted from zero27//! (`phase`). At 60 steps and 20 slower frames a second, each slower frame holds three steps, and28//! the positions run 0, 1, 2. `Clock.init` checks the rates with `Config.validate` before it builds29//! a clock.30const std = @import("std");3132/// The number of nanoseconds in one second, one billion. `offerElapsed` divides by it to turn33/// elapsed nanoseconds into whole steps, and `Config.validate` refuses a step rate above it.34pub const nanoseconds_per_second: u64 = 1_000_000_000;3536/// The rates a clock runs at: steps a second, slower frames a second, and the most steps one offer37/// plans. A host fills one in and passes it to `Clock.init`. `Clock.init` checks it with `validate`38/// before it builds a clock.39pub const Config = struct {40    /// Simulation steps in one second of simulated time, from 1 to one billion. Each step lasts one41    /// over this rate of a second.42    steps_per_second: u32,43    /// Slower frames in one second. The step rate has to be a whole multiple of it. At 60 steps and44    /// 20 slower frames a second, each slower frame holds three steps.45    source_frames_per_second: u32,46    /// The most steps one `Clock.offerElapsed` call plans, 4 unless the caller sets another value,47    /// and at least 1. Whole steps past this cap are dropped and counted in `Plan.dropped_steps`.48    max_catch_up_steps: u32 = 4,4950    /// Checks that the rates can drive a clock. `Clock.init` calls it before it builds a clock. The51    /// call returns `error.InvalidRate` for a step rate of zero or above one billion a second, a52    /// slower-frame rate of zero, or a cap of zero. The limit of one step per nanosecond keeps the53    /// count of whole steps from any offer within 64 bits. The call returns54    /// `error.NonIntegralCadence` when the remainder of the step rate divided by the slower-frame55    /// rate is above zero.56    pub fn validate(self: Config) !void {57        if (self.steps_per_second == 0 or self.steps_per_second > nanoseconds_per_second or58            self.source_frames_per_second == 0 or59            self.max_catch_up_steps == 0) return error.InvalidRate;60        if (self.steps_per_second % self.source_frames_per_second != 0) return error.NonIntegralCadence;61    }6263    /// Returns the number of steps in each slower frame: the step rate divided by the slower-frame64    /// rate. The clock derives each step's slower frame and position from it. The call divides by65    /// the slower-frame rate, and `validate` refuses a rate of zero. With a rate of zero, the call66    /// panics in Debug and ReleaseSafe builds, and its behavior is undefined in ReleaseFast and67    /// ReleaseSmall builds.68    pub fn cadence(self: Config) u32 {69        return self.steps_per_second / self.source_frames_per_second;70    }71};7273/// One simulation step: its index, the slower frame it falls in, its position inside that frame,74/// and its length as a fraction of a second. A host passes each step to the game's update, and a75/// recording stores it beside that step's input. `Clock.next` and `Clock.commandStep` return one.76pub const Step = struct {77    /// The step's number, counted from zero by the clock that made it. A recording takes steps in78    /// order of this number, starting at 0.79    index: u64,80    /// The slower frame the step falls in: its index divided by the steps in each slower frame.81    source_frame: u64,82    /// The step's position inside its slower frame, counted from zero: its index modulo the steps83    /// in each slower frame. At 60 steps and 20 slower frames a second, the positions run 0, 1, 2.84    phase: u32,85    /// The numerator of the step's length in seconds, always 1.86    dt_numerator: u32,87    /// The denominator of the step's length in seconds, equal to `Config.steps_per_second`.88    dt_denominator: u32,89};9091/// The result of one `Clock.offerElapsed` call: the number of steps to run now and the count of92/// whole steps dropped past the cap. A host runs `steps` calls to `Clock.next` before it offers93/// time again, and reports `dropped_steps` when it is above zero.94pub const Plan = struct {95    /// Steps to run before the next offer, one call to `Clock.next` each. The count is at most96    /// `Config.max_catch_up_steps`.97    steps: u32,98    /// Whole steps past the cap that the clock skipped. No later offer returns them, and a dropped99    /// step takes no index. The next step the clock hands out takes the next index in sequence, so100    /// step indexes stay contiguous. The part of a step left over after the whole steps still101    /// carries to the next offer.102    dropped_steps: u64,103};104105/// A fixed-step clock that turns elapsed time into planned steps, numbers each step it hands out,106/// and carries the leftover time from one offer to the next. A host that draws on its own schedule107/// offers it the time since each draw, and a host driven by commands takes one step per command108/// from it. The clock keeps the rates it was built with, the next step's index, the leftover time,109/// and the count of planned steps still to run. The clock reads no time of its own: elapsed time110/// enters only as the argument of `offerElapsed`. The clock asserts that a caller runs every111/// planned step before it offers time again or takes a command step. When a caller breaks this112/// order, `offerElapsed`, `commandStep` and `next` panic in Debug and ReleaseSafe builds, and their113/// behavior is undefined in ReleaseFast and ReleaseSmall builds.114pub const Clock = struct {115    config: Config,116    /// The index the next step gets, 0 for a new clock. A host that resumes a run sets it before117    /// the first step to the step it has reached, and reads it back as the current step number.118    index: u64 = 0,119    remainder: u64 = 0,120    pending: u32 = 0,121122    /// Returns a clock at step 0 for `config`, once `Config.validate` accepts it. A host builds its123    /// clock once, before its loop. The call returns `error.InvalidRate` or124    /// `error.NonIntegralCadence` from `validate`.125    pub fn init(config: Config) !Clock {126        try config.validate();127        return .{ .config = config };128    }129130    /// Takes the nanoseconds since the caller's last chance to draw and returns a plan of at most131    /// `Config.max_catch_up_steps` steps. A host calls it once each time it could draw, then runs132    /// the planned steps. The clock multiplies the nanoseconds by the step rate and adds the133    /// leftover from the last offer, and it keeps the new leftover for the next offer, all in134    /// integers. Whole steps past the cap are dropped and counted in the plan. The clock leaves to135    /// the caller the choice of when to draw and whether to blend the drawn state between steps.136    /// The call asserts that every step of the previous plan has run. When planned steps are left,137    /// the call panics in Debug and ReleaseSafe builds, and its behavior is undefined in138    /// ReleaseFast and ReleaseSmall builds. At 60 steps a second, an offer of 100 milliseconds139    /// plans four steps and drops two.140    pub fn offerElapsed(self: *Clock, elapsed_ns: u64) Plan {141        std.debug.assert(self.pending == 0);142        const scaled: u128 = @as(u128, elapsed_ns) * self.config.steps_per_second + self.remainder;143        const whole = scaled / nanoseconds_per_second;144        self.remainder = @intCast(scaled % nanoseconds_per_second);145        const cap = self.config.max_catch_up_steps;146        self.pending = @intCast(@min(whole, @as(u128, cap)));147        return .{ .steps = self.pending, .dropped_steps = @intCast(whole - @as(u128, self.pending)) };148    }149150    /// Advances the clock by exactly one step and returns it, reading no elapsed time. A headless151    /// host calls it once for each step a step command asks for, and other commands leave the clock152    /// at its current step. The call asserts that no step of a plan from `offerElapsed` is waiting.153    /// When planned steps are waiting, the call panics in Debug and ReleaseSafe builds, and its154    /// behavior is undefined in ReleaseFast and ReleaseSmall builds.155    pub fn commandStep(self: *Clock) Step {156        std.debug.assert(self.pending == 0);157        return self.advance();158    }159160    /// Returns the next planned step and counts it off the current plan. A host calls it once for161    /// each step the last `offerElapsed` planned. The call asserts that a planned step is left.162    /// Past the end of the plan, the call panics in Debug and ReleaseSafe builds, and its behavior163    /// is undefined in ReleaseFast and ReleaseSmall builds.164    pub fn next(self: *Clock) Step {165        std.debug.assert(self.pending > 0);166        self.pending -= 1;167        return self.advance();168    }169170    fn advance(self: *Clock) Step {171        const index = self.index;172        self.index += 1;173        const cadence = self.config.cadence();174        return .{175            .index = index,176            .source_frame = index / cadence,177            .phase = @intCast(index % cadence),178            .dt_numerator = 1,179            .dt_denominator = self.config.steps_per_second,180        };181    }182};183184test "60 Hz steps carry a three-phase 20 Hz frame and bound catch-up" {185    var clock = try Clock.init(.{ .steps_per_second = 60, .source_frames_per_second = 20 });186    for (0..6) |i| {187        const step = clock.commandStep();188        try std.testing.expectEqual(@as(u64, @intCast(i)), step.index);189        try std.testing.expectEqual(@as(u64, @intCast(i / 3)), step.source_frame);190        try std.testing.expectEqual(@as(u32, @intCast(i % 3)), step.phase);191    }192    const plan = clock.offerElapsed(100_000_000);193    try std.testing.expectEqual(@as(u32, 4), plan.steps);194    try std.testing.expectEqual(@as(u64, 2), plan.dropped_steps);195    for (0..plan.steps) |_| _ = clock.next();196    try std.testing.expectEqual(@as(u64, 10), clock.index);197}198199test "rates finer than a nanosecond are rejected before drop accounting" {200    try std.testing.expectError(error.InvalidRate, Clock.init(.{201        .steps_per_second = 1_000_000_001,202        .source_frames_per_second = 1,203    }));204}

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