Difficulty You Can Prove

/// The tightest row spacing that is still winnable at this speed: enough time
/// to cross the whole board, plus the time the current row spends sitting on
/// top of the player. Below this the game is impossible, however open the rows
/// look.
pub fn fairnessFloor(speed: f32) f32 {
    return 2 * config.lane_change_time + blockedSeconds(speed);
}

/// Seconds between rows, decaying towards the floor without ever reaching it.
///
/// Difficulty therefore rises for as long as anyone keeps playing, and the
/// margin above unwinnable is a named constant rather than an accident of two
/// hand-tuned endpoints agreeing with a third.
pub fn rowGapSeconds(speed: f32, time: f32) f32 {
    const floor = fairnessFloor(speed) + config.gap_safety;
    const decay = std.math.exp(-time / config.gap_tau);
    if (config.row_gap_easy <= floor) return floor;
    return floor + (config.row_gap_easy - floor) * decay;
}

/// How much slack the row spacing keeps above the point where the game stops
/// being winnable.
///
/// The spacing has a hard floor under it, set by the game's physics: between
/// one row arriving and the next, the player must be able to cross the whole
/// board (`2 * lane_change_time`), and they cannot begin while the current
/// row is level with them (`2 * (player_half_h + block_half_h) / speed`).
/// Spacing rows any tighter than that sum makes the game unwinnable, and it
/// would fail silently, because every row would still leave a lane open, just
/// not one anybody could reach.
///
/// So `sim.rowGapSeconds` computes that floor, adds this margin, and decays
/// towards it. The game gets harder forever and stays solvable forever. This
/// margin is the constant a designer tunes, and it only sets how much room to
/// leave. The floor, which decides whether the game can be won, is computed.
pub const gap_safety: f32 = 0.06;

/// The lane the bot wants to be in.
pub fn targetLane(w: *const sim.World) u8 {
    const current = w.player.lane;
    const pos = position(w);
    const view = look(w);

    var best: ?u8 = null;
    var best_cost: f32 = std.math.floatMax(f32);

    for (0..config.lane_count) |i| {
        const lane: u8 = @intCast(i);
        const lane_f: f32 = @floatFromInt(i);

        if (view.blocked_now[lane]) continue;
        if (view.next) |next| {
            if (next.blocked[lane]) continue;
        }
        if (!pathClear(pos, lane_f, view.blocked_now)) continue;

        const distance = @abs(lane_f - pos);
        const travel = distance * config.lane_change_time;
        if (view.next) |next| {
            if (travel + margin > next.seconds) continue;
        }

        var cost = distance;
        // Prefer somewhere that is still good one row later, so the bot is not
        // forever solving the problem it just created.
        if (view.after) |after| {
            if (after.blocked[lane]) cost += 1.5;
        }
        // Take a coin when it is on the way and there is comfortable time.
        // The bot limits how hard it chases coins: a missed dodge ends the run,
        // and a missed coin only costs a multiplier.
        if (view.next) |next| {
            if (next.coin_lane == lane and next.seconds > travel * 2) cost -= 0.5;
        }
        if (cost < best_cost) {
            best_cost = cost;
            best = lane;
        }
    }

    // Nothing safe is reachable. The spacing rule in config.zig is supposed to
    // make this impossible and the tests check that. But if the policy
    // panicked here, a tuning mistake would crash the program.
    return best orelse current;
}

test "solvable course: the bot survives a long run at every seed" {
    // This test proves that the generator is fair. Four minutes is well past the
    // point where the difficulty ramp saturates, so this covers the hardest
    // spacing the game ever produces.
    for (0..24) |seed| {
        const w = playWithBot(seed, 240);
        std.testing.expectEqual(sim.Phase.playing, w.phase) catch |err| {
            std.debug.print(
                "seed {d}: crashed after {d:.1}s at score {d}\n",
                .{ seed, w.time, w.score },
            );
            return err;
        };
    }
}

/// Vertical half-span within which a block and the player overlap. A block is
/// dangerous from `+reach` ahead of the player until `-reach` behind: using
/// only the block's own half-height here is the off-by-one-body bug that the
/// fairness test found.
const reach = config.player_half_h + config.block_half_h;

test "the bot will not slide into a block that is still level with it" {
    // The regression that the fairness test caught: a block whose centre is
    // behind the player's centre can still be overlapping it. Treating it as
    // passed makes the bot steer straight into its side.
    var w: sim.World = .init(1);
    w.start();
    w.entities.clear();
    const beside: u8 = w.player.lane + 1;
    _ = w.entities.create(.{
        .kind = .block,
        .lane = beside,
        // Behind the player's centre, but well inside the overlap band.
        .y = config.player_y + reach * 0.8,
        .y_prev = config.player_y + reach * 0.8,
    });
    try std.testing.expect(targetLane(&w) != beside);
}

/// A player who sees the threat, then takes a moment to act on it, modelled as
/// pure latency: the decision made from the world as it looked `delay` ticks
/// ago is the one acted on now.
///
/// With this model the tests can say something about whether the game is
/// *fun*. The bot proves the course is solvable, but the bot has no reaction
/// time at all, and a course only a machine can run is not a game. With a
/// delay in front of the same policy, the test asks whether the game is fair
/// to a person.
const Human = struct {
    delay: usize,
    buffer: [64]u8 = @splat(config.lane_count / 2),
    index: usize = 0,

    fn init(reaction_seconds: f32) Human {
        return .{ .delay = @intFromFloat(reaction_seconds * config.tick_hz) };
    }

    fn play(self: *Human, w: *const World) Input {
        self.buffer[self.index % self.buffer.len] = bot.targetLane(w);
        const decided = self.buffer[(self.index + self.buffer.len - self.delay) % self.buffer.len];
        self.index += 1;
        if (decided < w.player.lane) return .{ .left = true };
        if (decided > w.player.lane) return .{ .right = true };
        return .none;
    }
};

test "a run lasts about as long as a hyper casual run should" {
    // A quarter second is a slow, relaxed player. They should get a proper run,
    // not a game over screen after a few seconds.
    const casual = meanSurvival(0.25, 24, 300);
    std.testing.expect(casual > 12 and casual < 70) catch |err| {
        std.debug.print("casual player averaged {d:.1}s\n", .{casual});
        return err;
    };

    // A sharp player must last longer, or skill makes no difference.
    const sharp = meanSurvival(0.10, 24, 300);
    std.testing.expect(sharp > casual * 1.5) catch |err| {
        std.debug.print("sharp {d:.1}s vs casual {d:.1}s\n", .{ sharp, casual });
        return err;
    };

    // A sharp player must still lose. This check would have caught the
    // saturating difficulty curve, where a sharp player never died.
    std.testing.expect(sharp < 180) catch |err| {
        std.debug.print("sharp player averaged {d:.1}s: the game stops getting harder\n", .{sharp});
        return err;
    };
}

/// Opening seconds during which no row blocks more than one lane.
///
/// This is a judgement call, not a measurement. The reaction time model in the
/// tests already knows the controls, so it cannot show a first-time player
/// who is still looking for the keys. Turning the window off moves the
/// modelled 200 ms average from 29.5 s to 29.2 s. Inside the grace window
/// every row leaves two lanes open, so one lane change is always enough to
/// pass it.
pub const grace_seconds: f32 = 7;

    fn spawnRow(w: *World) void {
        const d = w.difficulty();

        // Shuffle the lanes, then block a prefix of them. Blocking a prefix of
        // a shuffle is what guarantees the blocked lanes are distinct, and the
        // count is capped below `lane_count`, so a free lane always remains.
        var lanes: [config.lane_count]u8 = undefined;
        for (&lanes, 0..) |*lane, i| lane.* = @intCast(i);
        var i: usize = lanes.len;
        while (i > 1) {
            i -= 1;
            const j = w.rng.below(@intCast(i + 1));
            std.mem.swap(u8, &lanes[i], &lanes[j]);
        }

        const two = w.time > config.grace_seconds and w.rng.chance(lerp(
            config.two_block_chance_easy,
            config.two_block_chance_hard,
            d,
        ));
        const blocked: usize = if (two) 2 else 1;
        std.debug.assert(blocked <= config.max_blocked_lanes);

        for (lanes[0..blocked]) |lane| {
            _ = w.entities.create(.{
                .kind = .block,
                .lane = lane,
                .y = config.spawn_y,
                .y_prev = config.spawn_y,
            });
        }

        // The coin goes in a lane this row leaves open. This keeps the row
        // fair, and it also teaches the player: when a row blocks two of three
        // lanes, the coin is sitting in the one gap, so following the coins is
        // the same thing as playing correctly.
        const free = lanes[blocked..];
        if (free.len > 0 and w.rng.chance(config.coin_chance)) {
            const lane = free[w.rng.below(@intCast(free.len))];
            _ = w.entities.create(.{
                .kind = .coin,
                .lane = lane,
                .y = config.spawn_y,
                .y_prev = config.spawn_y,
            });
        }
    }