tiny.game.input

1//! The input a game receives for one step: the edges of a button, and a fixed-size array of bytes2//! that holds the step's input for recording. A game wants to know whether a button went down or3//! came up on this step, besides whether it is down. A developer wants to record the input each4//! step received and replay it later, step for step. Whether a button changed depends on the5//! previous step as well as this one, so the edges come from two steps of state. Input held as an6//! in-memory struct carries padding bytes, pointers and the machine's byte order, and all three can7//! differ from one run or machine to the next. The transition function `Button.transition` takes8//! whether the button was down on the previous step and whether it is down now, and returns the9//! button's state with its two edges. The game encodes each step's input as a fixed-size array of10//! bytes (a *snapshot*) before the step runs, so a recording holds only bytes the game chose. The11//! type constructor `Snapshot(n)` makes the type for n bytes, and n is at least 1.12const std = @import("std");1314/// The state of one button on one step: whether it is down, and whether it went down or came up on15/// this step. A game reads the edges from it, so an action that happens once per press happens on16/// the pressing step alone. The struct has a C-compatible layout (`extern`), so it can sit inside17/// input records that a host passes across a C call into a game library. Every field is false by18/// default.19pub const Button = extern struct {20    /// True while the button is held on this step.21    down: bool = false,22    /// True on the step the button went down: down now and up on the previous step.23    pressed: bool = false,24    /// True on the step the button came up: up now and down on the previous step.25    released: bool = false,2627    /// Returns a button's state from whether it was down on the previous step and whether it is28    /// down now. A game calls it once per step for each button, with the level it kept from the29    /// step before. The edges depend on those two levels alone, so a button held across steps30    /// reports `pressed` on its first step only.31    pub fn transition(previous_down: bool, down: bool) Button {32        return .{ .down = down, .pressed = down and !previous_down, .released = !down and previous_down };33    }34};3536/// Returns the type of one step's input as an array of `byte_count` bytes, which the game fills37/// before the step runs. A recording stores one of these per step, and a replay hands the same38/// bytes back to the game. The game chooses the encoding, and an explicit encoding in a fixed byte39/// order keeps padding bytes, pointers and the machine's byte order out of the recorded input. A40/// `byte_count` of zero is a compile error.41pub fn Snapshot(comptime byte_count: usize) type {42    if (byte_count == 0) @compileError("input snapshots need at least one byte");43    return struct {44        /// The encoded input: `byte_count` bytes that the game writes before the step and reads45        /// during it.46        bytes: [byte_count]u8,4748        /// Returns true when two snapshots hold the same bytes.49        pub fn eql(a: @This(), b: @This()) bool {50            return std.mem.eql(u8, &a.bytes, &b.bytes);51        }52    };53}5455test "button edges derive only from adjacent levels" {56    const pressed = Button.transition(false, true);57    try std.testing.expect(pressed.pressed);58    try std.testing.expect(!Button.transition(true, true).pressed);59    try std.testing.expect(Button.transition(true, false).released);60}

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