@pkmn/engine 0.1.0-dev.62399ed5 → 0.1.0-dev.6be9a775

package/src/lib/common/util.zig

@@ -1,12 +1,61 @@
 const std = @import("std");
 
+const expect = std.testing.expect;
 const expectEqual = std.testing.expectEqual;
 
+const Pointer = if (@hasField(std.builtin.Type, "pointer")) .pointer else .Pointer;
+
 pub fn PointerType(comptime P: type, comptime C: type) type {
-    return if (@typeInfo(P).Pointer.is_const) *const C else *C;
+    return if (@field(@typeInfo(P), @tagName(Pointer)).is_const) *const C else *C;
 }
 
 test PointerType {
     try expectEqual(*bool, PointerType(*u8, bool));
     try expectEqual(*const f64, PointerType(*const i32, f64));
 }
+
+pub fn isPointerTo(p: anytype, comptime P: type) bool {
+    const info = @typeInfo(@TypeOf(p));
+    return switch (info) {
+        Pointer => @field(info, @tagName(Pointer)).child == P,
+        else => false,
+    };
+}
+
+test isPointerTo {
+    const S = struct {};
+    const s: S = .{};
+    try expect(!isPointerTo(s, S));
+    try expect(isPointerTo(&s, S));
+}
+
+// NOTE: std.mem.bytesAsValue backported from ziglang/zig#18061
+pub fn bytesAsValue(comptime T: type, bytes: anytype) BytesAsValueReturnType(T, @TypeOf(bytes)) {
+    return @as(BytesAsValueReturnType(T, @TypeOf(bytes)), @ptrCast(bytes));
+}
+
+fn BytesAsValueReturnType(comptime T: type, comptime B: type) type {
+    return CopyPtrAttrs(B, .One, T);
+}
+
+fn CopyPtrAttrs(
+    comptime source: type,
+    comptime size: std.builtin.Type.Pointer.Size,
+    comptime child: type,
+) type {
+    const info = @field(@typeInfo(source), @tagName(Pointer));
+    const args = .{
+        .size = size,
+        .is_const = info.is_const,
+        .is_volatile = info.is_volatile,
+        .is_allowzero = info.is_allowzero,
+        .alignment = info.alignment,
+        .address_space = info.address_space,
+        .child = child,
+        .sentinel = null,
+    };
+    return @Type(if (@hasField(std.builtin.Type, "pointer"))
+        .{ .pointer = args }
+    else
+        .{ .Pointer = args });
+}

package/src/lib/gen1/calc.zig

@@ -17,6 +17,7 @@ const assert = std.debug.assert;
 
 const expect = std.testing.expect;
 const expectEqual = std.testing.expectEqual;
+const expectEqualSlices = std.testing.expectEqualSlices;
 
 const enabled = pkmn.options.calc;
 
@@ -29,18 +30,19 @@ const Optional = optional.Optional;
 const Rational = rational.Rational;
 
 const PointerType = util.PointerType;
+const isPointerTo = util.isPointerTo;
 
 const Actions = chance.Actions;
 const Action = chance.Action;
 const Chance = chance.Chance;
 const Durations = chance.Durations;
-const Duration = chance.Duration;
-
-const Rolls = helpers.Rolls;
 
 const tty = true; // DEBUG
 const summary = false; // DEBUG
 
+const Int = if (@hasField(std.builtin.Type, "int")) .int else .Int;
+const Enum = if (@hasField(std.builtin.Type, "enum")) .@"enum" else .Enum;
+
 /// Information relevant to damage calculation that occured during a Generation I battle `update`.
 pub const Summaries = extern struct {
     /// Relevant information for Player 1.
@@ -54,7 +56,7 @@ pub const Summaries = extern struct {
 
     /// Returns the `Summary` for the given `player`.
     pub fn get(self: anytype, player: Player) PointerType(@TypeOf(self), Summary) {
-        assert(@typeInfo(@TypeOf(self)).Pointer.child == Summaries);
+        assert(isPointerTo(self, Summaries));
         return if (player == .P1) &self.p1 else &self.p2;
     }
 };
@@ -90,25 +92,11 @@ pub const Summary = extern struct {
     }
 };
 
-/// TODO
-pub const Overrides = extern struct {
-    /// TODO
-    actions: Actions = .{},
-    /// TODO
-    durations: Durations = .{},
-
-    _: u32 = 0,
-
-    comptime {
-        assert(@sizeOf(Overrides) == 24);
-    }
-};
-
 /// Allows for forcing the value of specific RNG events during a Generation I battle `update` via
 /// `overrides` and tracks `summaries` of information relevant to damage calculation.
 pub const Calc = struct {
     /// Overrides the normal behavior of the RNG during an `update` to force specific outcomes.
-    overrides: Overrides = .{},
+    overrides: Actions = .{},
     /// Information relevant to damage calculation.
     summaries: Summaries = .{},
 
@@ -119,28 +107,14 @@ pub const Calc = struct {
     ) ?std.meta.FieldType(Action, field) {
         if (!enabled) return null;
 
-        const overrides =
-            if (player == .P1) self.overrides.actions.p1 else self.overrides.actions.p2;
-        const val = @field(overrides, @tagName(field));
+        const val = @field(self.overrides.get(player), @tagName(field));
         return if (switch (@typeInfo(@TypeOf(val))) {
-            .Enum => val != .None,
-            .Int => val != 0,
+            Enum => val != .None,
+            Int => val != 0,
             else => unreachable,
         }) val else null;
     }
 
-    pub fn modify(self: Calc, player: Player, comptime field: Duration.Field) ?bool {
-        if (!enabled) return null;
-
-        const durations = self.overrides.durations;
-        const set = @field(if (player == .P1) durations.p1 else durations.p2, @tagName(field));
-        if (set == 0) return null;
-
-        const actions = self.overrides.actions;
-        const overrides = if (player == .P1) actions.p1.durations else actions.p2.durations;
-        return @field(overrides, @tagName(field)) != 0;
-    }
-
     pub fn base(self: *Calc, player: Player, val: u16) void {
         if (!enabled) return;
 
@@ -174,11 +148,6 @@ const Null = struct {
         return null;
     }
 
-    pub fn modify(self: Null, player: Player, comptime field: Duration.Field) ?bool {
-        _ = .{ self, player, field };
-        return null;
-    }
-
     pub fn base(self: Null, player: Player, val: u16) void {
         _ = .{ self, player, val };
     }
@@ -200,7 +169,7 @@ pub const Stats = struct {
 };
 
 pub const Options = struct {
-    actions: Actions = .{},
+    durations: Durations,
     seed: ?u64 = null,
     cap: bool = false,
     metronome: bool = false,
@@ -218,7 +187,6 @@ pub fn transitions(
 ) !?Stats {
     var stats: Stats = .{};
 
-    const actions = options.actions;
     const cap = options.cap;
 
     var seen = std.AutoHashMap(Actions, void).init(allocator);
@@ -228,11 +196,8 @@ pub fn transitions(
 
     var opts = pkmn.battle.options(
         protocol.NULL,
-        Chance(Rational(u128)){ .probability = .{}, .actions = actions },
-        Calc{ .overrides = .{ .actions = actions, .durations = .{
-            .p1 = actions.p1.durations,
-            .p2 = actions.p2.durations,
-        } } },
+        Chance(Rational(u128)){ .probability = .{}, .durations = options.durations },
+        Calc{},
     );
 
     var b = battle;
@@ -254,13 +219,9 @@ pub fn transitions(
     var i: usize = 0;
     assert(frontier.items.len == 1);
     while (i < frontier.items.len) : (i += 1) {
-        const template = frontier.items[i];
-        opts.calc.overrides.durations = .{
-            .p1 = template.p1.durations,
-            .p2 = template.p2.durations,
-        };
+        const f = frontier.items[i];
 
-        try debug(writer, template, .{
+        try debug(writer, f, .{
             .shape = true,
             .color = i,
             .bold = true,
@@ -268,43 +229,34 @@ pub fn transitions(
             .indent = false,
         });
 
-        var a: Actions = .{ .p1 = .{ .metronome = p1_move }, .p2 = .{ .metronome = p2_move } };
-
-        for (Rolls.speedTie(template.p1)) |tie| { a.p1.speed_tie = tie; a.p2.speed_tie = tie;
-        for (Rolls.sleep(template.p1, actions.p1)) |p1_slp| { a.p1.durations.sleep = p1_slp;
-        for (Rolls.sleep(template.p2, actions.p2)) |p2_slp| { a.p2.durations.sleep = p2_slp;
-        for (Rolls.disable(template.p1, actions.p1, p1_slp)) |p1_disable| { a.p1.durations.disable = p1_disable;
-        for (Rolls.disable(template.p2, actions.p2, p2_slp)) |p2_disable| { a.p2.durations.disable = p2_disable;
-        for (Rolls.confusion(template.p1, actions.p1, p1_slp)) |p1_cfz| { a.p1.durations.confusion = p1_cfz;
-        for (Rolls.confusion(template.p2, actions.p2, p1_slp)) |p2_cfz| { a.p2.durations.confusion = p2_cfz;
-        for (Rolls.confused(template.p1, p1_cfz)) |p1_cfzd| { a.p1.confused = p1_cfzd;
-        for (Rolls.confused(template.p2, p2_cfz)) |p2_cfzd| { a.p2.confused = p2_cfzd;
-        for (Rolls.paralyzed(template.p1, p1_cfzd)) |p1_par| { a.p1.paralyzed = p1_par;
-        for (Rolls.paralyzed(template.p2, p2_cfzd)) |p2_par| { a.p2.paralyzed = p2_par;
-        for (Rolls.attacking(template.p1, actions.p1, p1_par)) |p1_atk| { a.p1.durations.attacking = p1_atk;
-        for (Rolls.attacking(template.p2, actions.p2, p2_par)) |p2_atk| { a.p2.durations.attacking = p2_atk;
-        for (Rolls.binding(template.p1, actions.p1, p1_par)) |p1_bind| { a.p1.durations.binding = p1_bind;
-        for (Rolls.binding(template.p2, actions.p2, p2_par)) |p2_bind| { a.p2.durations.binding = p2_bind;
-        for (Rolls.duration(template.p1, p1_par)) |p1_dur| { a.p1.duration = p1_dur;
-        for (Rolls.duration(template.p2, p2_par)) |p2_dur| { a.p2.duration = p2_dur;
-        for (Rolls.hit(template.p1, p1_par)) |p1_hit| { a.p1.hit = p1_hit;
-        for (Rolls.hit(template.p2, p2_par)) |p2_hit| { a.p2.hit = p2_hit;
-        for (Rolls.psywave(template.p1, p1, p1_hit)) |p1_psywave| { a.p1.psywave = p1_psywave;
-        for (Rolls.psywave(template.p2, p2, p2_hit)) |p2_psywave| { a.p2.psywave = p2_psywave;
-        for (Rolls.moveSlot(template.p1, p1_hit)) |p1_slot| { a.p1.move_slot = p1_slot;
-        for (Rolls.moveSlot(template.p2, p2_hit)) |p2_slot| { a.p2.move_slot = p2_slot;
-        for (Rolls.multiHit(template.p1, p1_hit)) |p1_multi| { a.p1.multi_hit = p1_multi;
-        for (Rolls.multiHit(template.p2, p2_hit)) |p2_multi| { a.p2.multi_hit = p2_multi;
-        for (Rolls.secondaryChance(template.p1, p1_hit)) |p1_sec| { a.p1.secondary_chance = p1_sec;
-        for (Rolls.secondaryChance(template.p2, p2_hit)) |p2_sec| { a.p2.secondary_chance = p2_sec;
-        for (Rolls.criticalHit(template.p1, p1_hit)) |p1_crit| { a.p1.critical_hit = p1_crit;
-        for (Rolls.criticalHit(template.p2, p2_hit)) |p2_crit| { a.p2.critical_hit = p2_crit;
-
-        var p1_dmg = Rolls.damage(template.p1, p1_hit);
+        var a: Actions = .{
+            .p1 = .{ .metronome = p1_move, .pp = f.p1.pp, .duration = f.p1.duration },
+            .p2 = .{ .metronome = p2_move, .pp = f.p2.pp, .duration = f.p2.duration },
+        };
+
+        for (Rolls.speedTie(f.p1)) |tie| { a.p1.speed_tie = tie; a.p2.speed_tie = tie;
+        for (Rolls.confused(f.p1)) |p1_cfzd| { a.p1.confused = p1_cfzd;
+        for (Rolls.confused(f.p2)) |p2_cfzd| { a.p2.confused = p2_cfzd;
+        for (Rolls.paralyzed(f.p1, p1_cfzd)) |p1_par| { a.p1.paralyzed = p1_par;
+        for (Rolls.paralyzed(f.p2, p2_cfzd)) |p2_par| { a.p2.paralyzed = p2_par;
+        for (Rolls.hit(f.p1, p1_par)) |p1_hit| { a.p1.hit = p1_hit;
+        for (Rolls.hit(f.p2, p2_par)) |p2_hit| { a.p2.hit = p2_hit;
+        for (Rolls.psywave(f.p1, p1, p1_hit)) |p1_psywave| { a.p1.psywave = p1_psywave;
+        for (Rolls.psywave(f.p2, p2, p2_hit)) |p2_psywave| { a.p2.psywave = p2_psywave;
+        for (Rolls.moveSlot(f.p1, p1_hit)) |p1_slot| { a.p1.move_slot = p1_slot;
+        for (Rolls.moveSlot(f.p2, p2_hit)) |p2_slot| { a.p2.move_slot = p2_slot;
+        for (Rolls.multiHit(f.p1, p1_hit)) |p1_multi| { a.p1.multi_hit = p1_multi;
+        for (Rolls.multiHit(f.p2, p2_hit)) |p2_multi| { a.p2.multi_hit = p2_multi;
+        for (Rolls.secondaryChance(f.p1, p1_hit)) |p1_sec| { a.p1.secondary_chance = p1_sec;
+        for (Rolls.secondaryChance(f.p2, p2_hit)) |p2_sec| { a.p2.secondary_chance = p2_sec;
+        for (Rolls.criticalHit(f.p1, p1_hit)) |p1_crit| { a.p1.critical_hit = p1_crit;
+        for (Rolls.criticalHit(f.p2, p2_hit)) |p2_crit| { a.p2.critical_hit = p2_crit;
+
+        var p1_dmg = Rolls.damage(f.p1, p1_hit);
         while (p1_dmg.min < p1_dmg.max) : (p1_dmg.min += 1) {
             a.p1.damage = @intCast(p1_dmg.min);
 
-            var p2_dmg = Rolls.damage(template.p2, p2_hit);
+            var p2_dmg = Rolls.damage(f.p2, p2_hit);
 
             const p1_min: u9 = p1_dmg.min;
             const p2_min: u9 = p2_dmg.min;
@@ -312,13 +264,14 @@ pub fn transitions(
             while (p2_dmg.min < p2_dmg.max) : (p2_dmg.min += 1) {
                 a.p2.damage = @intCast(p2_dmg.min);
 
-                opts.calc.overrides.actions = a;
+                opts.calc.overrides = a;
                 opts.calc.summaries = .{};
-                opts.chance = .{ .probability = .{}, .actions = actions };
+                opts.chance = .{ .probability = .{}, .durations = options.durations };
                 const q = &opts.chance.probability;
 
                 b = battle;
                 _ = try b.update(c1, c2, &opts);
+
                 stats.updates += 1;
 
                 const summaries = &opts.calc.summaries;
@@ -329,7 +282,7 @@ pub fn transitions(
                 const p2_max: u9 =
                     try Rolls.coalesce(.P2, @as(u8, @intCast(p2_dmg.min)), summaries, cap);
 
-                if (opts.chance.actions.matches(template)) {
+                if (opts.chance.actions.matches(f)) {
                     if (!opts.chance.actions.eql(a)) {
                         if (!summary) {
                             try debug(writer, opts.chance.actions, .{
@@ -405,7 +358,7 @@ pub fn transitions(
                 p2_dmg.min = p2_max;
             }
 
-        }}}}}}}}}}}}}}}}}}}}}}}}}}}}}}
+        }}}}}}}}}}}}}}}}}}
 
         if (@TypeOf(writer) != @TypeOf(std.io.null_writer)) {
             p.reduce();
@@ -444,61 +397,90 @@ pub fn update(
     writer: anytype,
     transition: bool,
 ) !Result {
+    const durations = options.chance.durations;
     options.chance.reset();
 
-    if (!pkmn.options.chance or !pkmn.options.calc or @TypeOf(battle.rng) != data.PRNG) {
-        return battle.update(c1, c2, options);
-    }
+    if (!pkmn.options.chance or !pkmn.options.calc) return battle.update(c1, c2, options);
 
-    var copy = battle.*;
-    const actions = options.chance.actions;
+    const original = battle.*;
 
     // Perfom the actual update
     const result = battle.update(c1, c2, options);
-
-    // Ensure we can encode the diffs in less than MAX_DIFFS bytes.
-    var buf: [helpers.MAX_DIFFS]u8 = undefined;
-    var stream: protocol.ByteStream = .{ .buffer = &buf };
-    const n = try helpers.diff(&copy, battle, stream.writer());
-
-    // Applying the diff to the battle should take us back to the original copy
-    // of the battle (ignoring the RNG).
-    var patched = battle.*;
-    patched.rng = copy.rng;
-    helpers.patch(&patched, buf[0..n]);
-    try expectEqual(copy, patched);
-
-    if (!pkmn.options.chance or !pkmn.options.calc) return result;
+    var overrides = options.chance.actions;
+    const updated = options.chance.durations;
+
+    if (@TypeOf(battle.rng) == data.PRNG) {
+        // Ensure we can encode the diffs in less than MAX_DIFFS bytes.
+        var buf: [helpers.MAX_DIFFS]u8 = undefined;
+        var stream: protocol.ByteStream = .{ .buffer = &buf };
+        const n = try helpers.diff(&original, battle, stream.writer());
+
+        // Applying the diff to the battle should take us back to the original copy
+        // of the battle (ignoring the RNG).
+        var patched = battle.*;
+        patched.rng = original.rng;
+        helpers.patch(&patched, buf[0..n]);
+        try expectEqual(original, patched);
+    }
 
     if (transition) {
         // Ensure we can generate all transitions from the same original state
         // (we must change the battle's RNG from a FixedRNG to a PRNG because
         // the transitions function relies on RNG for discovery of states)
-        if (try transitions(unfix(copy), c1, c2, allocator, writer, .{
-            .actions = actions,
+        if (try transitions(unfix(original), c1, c2, allocator, writer, .{
+            .durations = durations,
             .cap = true,
         })) |stats| try expect(stats.frontier <= MAX_FRONTIER);
     }
 
     // Demonstrate that we can produce the same state by forcing the RNG to behave the
-    // same as we observed - note that because we do not pass in a durations override
-    // mask none of the durations will be extended.
+    // same as we observed.
     var override = pkmn.battle.options(
         protocol.NULL,
-        chance.NULL,
-        Calc{ .overrides = .{ .actions = actions } },
+        Chance(Rational(u128)){ .probability = .{}, .durations = durations },
+        Calc{ .overrides = overrides },
     );
-    const overridden = copy.update(c1, c2, &override);
+    var copy = original;
+    var overridden = copy.update(c1, c2, &override);
     try expectEqual(result, overridden);
+    try expectEqualActions(overrides, override.chance.actions);
+    try expectEqual(updated, override.chance.durations);
 
     // The actual battle excluding its RNG field should match a copy updated with
     // overridden RNG (the copy RNG may have advanced because of no-ops)
     copy.rng = battle.rng;
-    try expectEqual(copy, battle.*);
+    try expectEqual(battle.*, copy);
+
+    // Demonstrate that even with the duration rolls changed, the duration
+    // fields on their own are sufficient to achieve the same outcomes
+    // NB: The actual battle bytes will differ because the durations won't match
+    overrides.p1.duration = if (overrides.p1.duration > 0) 2 else 0;
+    overrides.p2.duration = if (overrides.p2.duration > 0) 2 else 0;
+
+    override = pkmn.battle.options(
+        protocol.NULL,
+        Chance(Rational(u128)){ .probability = .{}, .durations = durations },
+        Calc{ .overrides = overrides },
+    );
+    copy = original;
+    overridden = copy.update(c1, c2, &override);
+    try expectEqual(result, overridden);
+    try expectEqualActions(overrides, override.chance.actions);
+    try expectEqual(updated, override.chance.durations);
 
     return result;
 }
 
+fn expectEqualActions(expected: Actions, actual: Actions) !void {
+    return expectEqual(expected, actual) catch |e| switch (e) {
+        error.TestExpectedEqual => {
+            std.debug.print("expected {}, found {}\n", .{ expected, actual });
+            return e;
+        },
+        else => return e,
+    };
+}
+
 fn unfix(actual: anytype) data.Battle(data.PRNG) {
     return .{
         .sides = actual.sides,
@@ -594,3 +576,231 @@ fn format(writer: anytype, actions: Actions, p1: u9, p2: u9) !void {
 
     try writer.writeAll(output[0..len]);
 }
+
+const NONE = @intFromEnum(Optional(bool).None);
+
+/// Helper functions that efficiently return valid ranges for various RNG events based on the
+/// state of an `Action` and other events to be used to construct a "transitions" function.
+pub const Rolls = struct {
+    const PLAYER_NONE = [_]Optional(Player){.None};
+    const PLAYERS = [_]Optional(Player){ .P1, .P2 };
+
+    /// Returns a slice with the correct range of values for speed ties given the `action` state.
+    pub fn speedTie(action: Action) []const Optional(Player) {
+        return if (action.speed_tie == .None) &PLAYER_NONE else &PLAYERS;
+    }
+
+    const BOOL_NONE = [_]Optional(bool){.None};
+    const BOOLS = [_]Optional(bool){ .false, .true };
+
+    /// Returns a slice with the correct range of values for hits given the `action` state
+    /// and the state of the `parent` (whether the player's Pokémon was fully paralyzed).
+    pub fn hit(action: Action, parent: Optional(bool)) []const Optional(bool) {
+        if (parent == .true) return &BOOL_NONE;
+        return if (action.hit == .None) &BOOL_NONE else &BOOLS;
+    }
+
+    /// Returns a slice with the correct range of values for critical hits given the `action` state
+    /// and the state of the `parent` (whether the player's Pokémon's move hit).
+    pub fn criticalHit(action: Action, parent: Optional(bool)) []const Optional(bool) {
+        if (parent == .false) return &BOOL_NONE;
+        return if (action.critical_hit == .None) &BOOL_NONE else &BOOLS;
+    }
+
+    /// Returns a slice with the correct range of values for secondary chances hits given the
+    /// `action` state and the state of the `parent` (whether the player's Pokémon's move hit).
+    pub fn secondaryChance(action: Action, parent: Optional(bool)) []const Optional(bool) {
+        if (parent == .false) return &BOOL_NONE;
+        return if (@field(action, "secondary_chance") == .None) &BOOL_NONE else &BOOLS;
+    }
+
+    /// The min and max bounds on iteration over damage rolls.
+    pub const Range = struct { min: u9, max: u9 };
+
+    /// Returns the range bounding damage rolls given the `action` state and the state of
+    /// the `parent` (whether the player's Pokémon's move hit).
+    pub fn damage(action: Action, parent: Optional(bool)) Range {
+        return if (parent == .false or action.damage == 0)
+            .{ .min = 0, .max = 1 }
+        else
+            .{ .min = 217, .max = 256 };
+    }
+
+    /// Returns the max damage roll which will produce the same damage as `roll`
+    /// given the base damage in `summaries`.
+    pub fn coalesce(player: Player, roll: u8, summaries: *Summaries, cap: bool) !u8 {
+        if (roll == 0) return roll;
+
+        const dmg = summaries.get(player.foe()).damage;
+        if (dmg.base == 0 or (cap and dmg.capped)) return 255;
+
+        // Closed form solution for max damage roll provided by Orion Taylor (taylorott)
+        return @min(255, roll + ((254 - ((@as(u32, dmg.base) * roll) % 255)) / dmg.base));
+    }
+
+    /// Returns a slice with the correct range of values for confused.
+    pub fn confused(action: Action) []const Optional(bool) {
+        return if (action.confused == .None) &BOOL_NONE else &BOOLS;
+    }
+
+    /// Returns a slice with the correct range of values for paralysis given the `action` state
+    /// and the state of the `parent` (whether the player's Pokémon was confused).
+    pub fn paralyzed(action: Action, parent: Optional(bool)) []const Optional(bool) {
+        if (parent == .true) return &BOOL_NONE;
+        return if (action.paralyzed == .None) &BOOL_NONE else &BOOLS;
+    }
+
+    const SLOT_NONE = [_]u4{0};
+    const SLOT = [_]u4{ 1, 2, 3, 4 };
+
+    /// Returns a slice with a range of values for move slots given the `action` state
+    /// and the state of the `parent` (whether the player's Pokémon's move hit).
+    ///
+    /// These slots may or **may not be valid** as slots may be unset / have 0 PP.
+    pub fn moveSlot(action: Action, parent: Optional(bool)) []const u4 {
+        if (parent == .false) return &SLOT_NONE;
+        return if (action.move_slot == 0) &SLOT_NONE else &SLOT;
+    }
+
+    const MULTI_NONE = [_]u4{0};
+    const MULTI = [_]u4{ 2, 3, 4, 5 };
+
+    /// Returns a slice with the correct range of values for multi hit given the `action` state
+    /// and the state of the `parent` (whether the player's Pokémon's move hit).
+    pub fn multiHit(action: Action, parent: Optional(bool)) []const u4 {
+        if (parent == .false) return &MULTI_NONE;
+        return if (action.multi_hit == 0) &MULTI_NONE else &MULTI;
+    }
+
+    const PSYWAVE_NONE = [_]u8{0};
+    const PSYWAVE = init: {
+        var rolls: [150]u8 = undefined;
+        for (0..150) |i| rolls[i] = i + 1;
+        break :init rolls;
+    };
+
+    /// Returns a slice with the correct range of values for psywave given the `action` state,
+    /// the `side`, and the state of the `parent` (whether the player's Pokémon's move hit).
+    pub fn psywave(
+        action: Action,
+        side: *data.Side,
+        parent: Optional(bool),
+    ) []const u8 {
+        if (parent == .false) return &PSYWAVE_NONE;
+        return if (action.psywave == 0)
+            &PSYWAVE_NONE
+        else
+            PSYWAVE[0 .. @as(u16, side.stored().level) * 3 / 2];
+    }
+
+    const MOVE_NONE = [_]data.Move{.None};
+
+    /// Returns a slice with the correct range of values for metronome given the `action` state.
+    pub fn metronome(action: Action) []const data.Move {
+        return if (action.metronome == .None) &MOVE_NONE else &data.Move.METRONOME;
+    }
+};
+
+test "Rolls.speedTie" {
+    const actions: Actions = .{ .p1 = .{ .speed_tie = .P2 } };
+    try expectEqualSlices(Optional(Player), &.{ .P1, .P2 }, Rolls.speedTie(actions.p1));
+    try expectEqualSlices(Optional(Player), &.{.None}, Rolls.speedTie(actions.p2));
+}
+
+test "Rolls.damage" {
+    const actions: Actions = .{ .p2 = .{ .damage = 221 } };
+    try expectEqual(Rolls.Range{ .min = 0, .max = 1 }, Rolls.damage(actions.p1, .None));
+    try expectEqual(Rolls.Range{ .min = 217, .max = 256 }, Rolls.damage(actions.p2, .None));
+    try expectEqual(Rolls.Range{ .min = 0, .max = 1 }, Rolls.damage(actions.p2, .false));
+}
+
+test "Rolls.coalesce" {
+    var summaries = Summaries{ .p1 = .{ .damage = .{ .base = 74, .final = 69, .capped = true } } };
+    try expectEqual(@as(u8, 0), try Rolls.coalesce(.P2, 0, &summaries, false));
+    try expectEqual(@as(u8, 241), try Rolls.coalesce(.P2, 238, &summaries, false));
+    try expectEqual(@as(u8, 255), try Rolls.coalesce(.P2, 238, &summaries, true));
+    summaries.p1.damage.final = 74;
+    try expectEqual(@as(u8, 217), try Rolls.coalesce(.P2, 217, &summaries, false));
+    try expectEqual(@as(u8, 255), try Rolls.coalesce(.P2, 217, &summaries, true));
+}
+
+test "Rolls.hit" {
+    const actions: Actions = .{ .p2 = .{ .hit = .true } };
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.hit(actions.p1, .None));
+    try expectEqualSlices(Optional(bool), &.{ .false, .true }, Rolls.hit(actions.p2, .None));
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.hit(actions.p2, .true));
+    try expectEqualSlices(Optional(bool), &.{ .false, .true }, Rolls.hit(actions.p2, .false));
+}
+
+test "Rolls.secondaryChance" {
+    const actions: Actions = .{ .p1 = .{ .secondary_chance = .true } };
+    try expectEqualSlices(
+        Optional(bool),
+        &.{ .false, .true },
+        Rolls.secondaryChance(actions.p1, .None),
+    );
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.secondaryChance(actions.p1, .false));
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.secondaryChance(actions.p2, .None));
+}
+
+test "Rolls.criticalHit" {
+    const actions: Actions = .{ .p1 = .{ .critical_hit = .true } };
+    try expectEqualSlices(
+        Optional(bool),
+        &.{ .false, .true },
+        Rolls.criticalHit(actions.p1, .None),
+    );
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.criticalHit(actions.p1, .false));
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.criticalHit(actions.p2, .None));
+}
+
+test "Rolls.confused" {
+    const actions: Actions = .{ .p2 = .{ .confused = .true } };
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.confused(actions.p1));
+    try expectEqualSlices(Optional(bool), &.{ .false, .true }, Rolls.confused(actions.p2));
+}
+
+test "Rolls.paralyzed" {
+    const actions: Actions = .{ .p2 = .{ .paralyzed = .true } };
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.paralyzed(actions.p1, .None));
+    try expectEqualSlices(Optional(bool), &.{ .false, .true }, Rolls.paralyzed(actions.p2, .None));
+    try expectEqualSlices(Optional(bool), &.{ .false, .true }, Rolls.paralyzed(actions.p2, .false));
+    try expectEqualSlices(Optional(bool), &.{.None}, Rolls.paralyzed(actions.p2, .true));
+}
+
+test "Rolls.moveSlot" {
+    const actions: Actions = .{ .p2 = .{ .move_slot = 3 } };
+    try expectEqualSlices(u4, &.{0}, Rolls.moveSlot(actions.p1, .None));
+    try expectEqualSlices(u4, &.{ 1, 2, 3, 4 }, Rolls.moveSlot(actions.p2, .None));
+    try expectEqualSlices(u4, &.{0}, Rolls.moveSlot(actions.p2, .false));
+}
+
+test "Rolls.multiHit" {
+    const actions: Actions = .{ .p2 = .{ .multi_hit = 3 } };
+    try expectEqualSlices(u4, &.{0}, Rolls.multiHit(actions.p1, .None));
+    try expectEqualSlices(u4, &.{ 2, 3, 4, 5 }, Rolls.multiHit(actions.p2, .None));
+    try expectEqualSlices(u4, &.{0}, Rolls.multiHit(actions.p2, .false));
+}
+
+test "Rolls.metronome" {
+    const actions: Actions = .{ .p2 = .{ .metronome = .Surf } };
+    try expectEqualSlices(data.Move, &.{.None}, Rolls.metronome(actions.p1));
+    try expectEqual(@as(data.Move, @enumFromInt(24)), Rolls.metronome(actions.p2)[23]);
+}
+
+test "Rolls.psywave" {
+    const actions: Actions = .{ .p2 = .{ .psywave = 79 } };
+    var side = helpers.Side.init(&[_]helpers.Pokemon{.{
+        .species = .Bulbasaur,
+        .level = 100,
+        .moves = &[_]data.Move{.Tackle},
+    }});
+
+    try expectEqualSlices(u8, &.{0}, Rolls.psywave(actions.p1, &side, .None));
+    var rolls = Rolls.psywave(actions.p2, &side, .None);
+    try expectEqual(@as(u8, 150), rolls[rolls.len - 1]);
+    side.stored().level = 81;
+    rolls = Rolls.psywave(actions.p2, &side, .None);
+    try expectEqual(@as(u8, 121), rolls[rolls.len - 1]);
+    try expectEqualSlices(u8, &.{0}, Rolls.psywave(actions.p2, &side, .false));
+}