tiny.game.dev

1//! A parser for the commands that drive a headless game: advance some steps, report status, or2//! quit.3//!4//! A tool or test drives the game one command at a time and waits as long as it likes between5//! commands, so the game advances only when a command asks it to. A host keeps commands of its own6//! beside the shared ones.7//!8//! A line from an outside tool can name any command and any count, so the host bounds the step9//! count and separates the commands it knows from all others.10//!11//! Each command is one JSON object on its own line, with its name in a `cmd` field and, for a step12//! command, a step count in a `frames` field that is 1 when the line leaves it out. The `frames`13//! field counts simulation steps. `common` maps a name and a count to a `Command`, and it returns14//! `null` for a name outside the three, so a host can try its own commands next. `parse` reads a15//! whole line and returns `error.UnknownCommand` for a name outside the three. A step count runs16//! from 1 to a maximum the caller passes, and both functions return `error.StepCountOutOfRange` for17//! any other count.18const std = @import("std");1920/// One of the three commands every headless host understands. A host switches on it to decide21/// whether to advance, report or stop.22pub const Command = union(enum) {23    /// Advance the simulation by the given number of steps, from 1 to the caller's maximum.24    step: u32,25    /// Report the host's state. A host leaves the simulation at the step it had reached for this26    /// command.27    status,28    /// Stop serving commands.29    quit,30};3132/// Checks that a step count lies between 1 and `max_steps`. `common` checks the count of each step33/// command with it. The call returns `error.StepCountOutOfRange` for a count of zero or above34/// `max_steps`, so a `max_steps` of zero refuses every count. `frames` is a count of simulation35/// steps.36pub fn validateStepCount(frames: u32, max_steps: u32) error{StepCountOutOfRange}!void {37    if (frames == 0 or frames > max_steps) return error.StepCountOutOfRange;38}3940/// Maps a command name and a step count to a `Command`, or returns `null` for a name other than41/// `step`, `status` or `quit`. A host that has commands of its own calls it first and handles a42/// `null` result with its own names. The call checks the count for `step` alone, and returns43/// `error.StepCountOutOfRange` for a count of zero or above `max_steps`. Names match byte for byte,44/// case included.45pub fn common(name: []const u8, frames: u32, max_steps: u32) error{StepCountOutOfRange}!?Command {46    if (std.mem.eql(u8, name, "step")) {47        try validateStepCount(frames, max_steps);48        return .{ .step = frames };49    }50    if (std.mem.eql(u8, name, "status")) return .status;51    if (std.mem.eql(u8, name, "quit")) return .quit;52    return null;53}5455const Raw = struct { cmd: []const u8, frames: u32 = 1 };5657/// Parses one line holding a JSON object into a `Command`. A host that understands only the three58/// shared commands parses each line with it. The object names its command in `cmd` and its step59/// count in `frames`, which is 1 when the line leaves it out, and the parser skips any other field.60/// The call returns `error.UnknownCommand` for a name outside the three, checks the count for61/// `step` alone, and returns `error.StepCountOutOfRange` for a count of zero or above `max_steps`.62/// The call returns the errors of `std.json.parseFromSliceLeaky` for a line that is malformed JSON,63/// a line whose JSON value is an array, a string, a number, a Boolean or null, a line that repeats64/// a field, a line that lacks `cmd`, or a line that holds a field of the wrong type, such as a65/// `cmd` that is a number or a `frames` that is negative, fractional or above the `u32` range. A66/// `frames` written as a string of digits, such as `"3"`, parses as that number. The parsed strings67/// live in `arena`, and the call frees nothing, so the caller resets or frees the arena.68pub fn parse(arena: std.mem.Allocator, line: []const u8, max_steps: u32) !Command {69    const raw = try std.json.parseFromSliceLeaky(Raw, arena, line, .{ .ignore_unknown_fields = true });70    return (try common(raw.cmd, raw.frames, max_steps)) orelse return error.UnknownCommand;71}7273test "headless protocol advances only on step commands" {74    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);75    defer arena_state.deinit();76    const arena = arena_state.allocator();77    var clock = try @import("clock.zig").Clock.init(.{ .steps_per_second = 60, .source_frames_per_second = 20 });78    for ([_][]const u8{ "{\"cmd\":\"status\"}", "{\"cmd\":\"step\",\"frames\":3}", "{\"cmd\":\"status\"}" }) |line| {79        const command = try parse(arena, line, 8);80        switch (command) {81            .step => |count| {82                for (0..count) |_| _ = clock.commandStep();83            },84            else => {},85        }86    }87    try std.testing.expectEqual(@as(u64, 3), clock.index);88}

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