@pkmn/engine 0.1.0-dev.d97c6e03 → 0.1.0-dev.f3aaee39

package/src/lib/gen2/README.md

@@ -54,13 +54,12 @@ The following information is required to simulate a Generation II Pokémon battl
 |                                |                                   |                                       |
 | `active.last_used_move`        | `PlayerUsedMove`                  | `side.lastMove`                       |
 
-- Pokémon Showdown does not implement the correct Generation II RNG and as such its `seed` is
+- Pokémon Showdown doesn't implement the correct Generation II RNG and as such its `seed` is
   different
-- `battle.turn` only needs to be tracked in order to be compatible with the Pokémon Showdown
-  protocol
+- `battle.turn` only needs to be tracked to be compatible with the Pokémon Showdown protocol
 - Battle results (win, lose, draw) or request states are communicated via the return code of
   `Battle.update`
-- Nicknames (`BattleMonNick`/`pokemon.name`) are not handled by the pkmn engine as they are expected
+- Nicknames (`BattleMonNick`/`pokemon.name`) aren't handled by the pkmn engine as they're expected
   to be handled by driver code if required
 
 ==**TODO**==
@@ -77,9 +76,9 @@ between the data structure for the "active" Pokémon and its party members (see
 
 ### `Pokemon` / `ActivePokemon`
 
-Similar to the cartridge, in order to save space different information is stored depending on
-whether a [Pokémon](https://pkmn.cc/bulba/Pok%c3%a9mon_data_structure_%28Generation_II%29) is
-actively participating in battle vs. is switched out (pret's [`battle_struct` vs.
+Similar to the cartridge, to save space different information is stored depending on whether a
+[Pokémon](https://pkmn.cc/bulba/Pok%c3%a9mon_data_structure_%28Generation_II%29) is actively
+participating in battle vs. is switched out (pret's [`battle_struct` vs.
 `party_struct`](https://pkmn.cc/pokecrystal/macros/ram.asm)). In Pokémon Showdown, all the Pokemon
 are represented by the same
 [`Pokemon`](https://github.com/smogon/pokemon-showdown/blob/master/sim/pokemon.ts) class, and static
@@ -93,14 +92,14 @@ A `MoveSlot` is a data-type for a `(move, current pp)` pair. A pared down versio
 Showdown's `Pokemon#moveSlot`, it also stores data from the cartridge's `battle_struct::Move` macro
 and can be used to replace the `PlayerMove*` data. Move PP is stored as a full byte instead of how
 the cartridge (`battle_struct::PP`) stores it (6 bits for current PP and the remaining 2 bits used
-to store the number of applied PP Ups). PP Up bits do not actually need to be stored on move slot
+to store the number of applied PP Ups). PP Up bits don't actually need to be stored on move slot
 as max PP is never relevant in Generation II (the Mystery Berry always increases PP from 0 -> 5).
 
 #### `Status`
 
 Bitfield representation of a Pokémon's major [status
-condition](https://pkmn.cc/bulba/Status_condition), mirroring how it is stored on the cartridge. A
-value of `0x00` means that the Pokémon is not affected by any major status, otherwise the lower 3
+condition](https://pkmn.cc/bulba/Status_condition), mirroring how it's stored on the cartridge. A
+value of `0x00` means that the Pokémon isn't affected by any major status, otherwise the lower 3
 bits represent the remaining duration for Sleep. Other status are denoted by the presence of
 individual bits - at most one status should be set at any given time.
 
@@ -161,7 +160,7 @@ boosts should always range from `-6`...`6` instead of `1`...`13` as on the cartr
 
 `Moves` serves as an identifier for a unique [Pokémon move](https://pkmn.cc/bulba/Move) that can be
 used to retrieve a `Move` with information regarding base power, accuracy and type. As covered
-above, PP information isn't strictly necessary in Generation I, but fits neatly into the 4 bits of
+earlier, PP information isn't strictly necessary in Generation I, but fits neatly into the 4 bits of
 padding after noticing that all PP values are multiples of 5. `Moves.None` exists as a special
 sentinel value to indicate `null`.
 
@@ -215,8 +214,8 @@ entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory))) is as foll
 | **wrap**       | 0...5   | 3    |     | **perish song**   | 0...4    | 3    |
 | **item**       | TODO    | 5?   |     | **gender**        | 0..1     | 1    |
 
-From this we can determine the minimum bits required to store each data structure to determine how
-much overhead the representations above have after taking into consideration [alignment &
+From this one can determine the minimum bits required to store each data structure to determine how
+much overhead the preceding representations have after taking into consideration [alignment &
 padding](https://en.wikipedia.org/wiki/Data_structure_alignment) and
 [denormalization](https://en.wikipedia.org/wiki/Denormalization):
 

package/src/lib/gen2/data/items.zig

@@ -219,18 +219,18 @@ pub const Item = enum(u8) {
     pub inline fn boost(item: Item) ?Type {
         assert(item != .None);
         if (item == .PolkadotBow) return .Normal;
-        return if (@enumToInt(item) <= 18) @intToEnum(Type, @enumToInt(item) - 1) else null;
+        return if (@intFromEnum(item) <= 18) @enumFromInt(@intFromEnum(item) - 1) else null;
     }
 
     /// Whether or not this item is a Berry.
     pub inline fn berry(item: Item) bool {
         assert(item != .None);
-        return @enumToInt(item) > 30 and @enumToInt(item) <= 40;
+        return @intFromEnum(item) > 30 and @intFromEnum(item) <= 40;
     }
 
     /// Whether or not this item is Mail.
     pub inline fn mail(item: Item) bool {
         assert(item != .None);
-        return @enumToInt(item) > 60 and @enumToInt(item) <= 70;
+        return @intFromEnum(item) > 60 and @intFromEnum(item) <= 70;
     }
 };

package/src/lib/gen2/data/moves.zig

@@ -2779,6 +2779,6 @@ pub const Move = enum(u8) {
     /// Returns the `Data` corresponding to the move.
     pub inline fn get(id: Move) Data {
         assert(id != .None);
-        return DATA[@enumToInt(id) - 1];
+        return DATA[@intFromEnum(id) - 1];
     }
 };

package/src/lib/gen2/data/species.zig

@@ -1793,6 +1793,6 @@ pub const Species = enum(u8) {
     /// Returns the `Data` corresponding to the species.
     pub fn get(id: Species) Data {
         assert(id != .None);
-        return DATA[@enumToInt(id) - 1];
+        return DATA[@intFromEnum(id) - 1];
     }
 };

package/src/lib/gen2/data/types.zig

@@ -86,17 +86,17 @@ pub const Type = enum(u8) {
 
     /// Whether or not this type is considered to be special as opposed to physical.
     pub inline fn special(self: Type) bool {
-        return @enumToInt(self) >= @enumToInt(Type.Fire);
+        return @intFromEnum(self) >= @intFromEnum(Type.Fire);
     }
 
     /// The `Effectiveness` of type `t2` vs. type `t1`.
     pub inline fn effectiveness(t1: Type, t2: Type) Effectiveness {
-        return CHART[@enumToInt(t1)][@enumToInt(t2)];
+        return CHART[@intFromEnum(t1)][@intFromEnum(t2)];
     }
 
     /// The precedence order of type type.
     pub inline fn precedence(self: Type) u8 {
-        return PRECEDENCE[@enumToInt(self)];
+        return PRECEDENCE[@intFromEnum(self)];
     }
 };
 

package/src/lib/gen2/data.zig

@@ -1,10 +1,12 @@
 const std = @import("std");
 const builtin = @import("builtin");
 
+const pkmn = @import("../pkmn.zig");
+
 const data = @import("../common/data.zig");
 const DEBUG = @import("../common/debug.zig").print;
-const options = @import("../common/options.zig");
 const rng = @import("../common/rng.zig");
+const util = @import("../common/util.zig");
 
 const items = @import("data/items.zig");
 const moves = @import("data/moves.zig");
@@ -36,7 +38,9 @@ const ID = data.ID;
 const Player = data.Player;
 const Result = data.Result;
 
-const showdown = options.showdown;
+const PointerType = util.PointerType;
+
+const showdown = pkmn.options.showdown;
 
 pub const PRNG = rng.PRNG(2);
 
@@ -49,20 +53,22 @@ pub fn Battle(comptime RNG: anytype) type {
         turn: u16 = 0,
         field: Field = .{},
 
-        pub inline fn side(self: *Self, player: Player) *Side {
-            return &self.sides[@enumToInt(player)];
+        pub inline fn side(self: anytype, player: Player) PointerType(@TypeOf(self), Side) {
+            assert(@typeInfo(@TypeOf(self)).Pointer.child == Self);
+            return &self.sides[@intFromEnum(player)];
         }
 
-        pub inline fn foe(self: *Self, player: Player) *Side {
-            return &self.sides[@enumToInt(player.foe())];
+        pub inline fn foe(self: anytype, player: Player) PointerType(@TypeOf(self), Side) {
+            assert(@typeInfo(@TypeOf(self)).Pointer.child == Self);
+            return &self.sides[@intFromEnum(player.foe())];
         }
 
-        pub inline fn active(self: *Self, player: Player) ID {
-            return player.ident(@intCast(u3, self.side(player).pokemon[0].position));
+        pub inline fn active(self: *const Self, player: Player) ID {
+            return player.ident(@intCast(self.side(player).pokemon[0].position));
         }
 
-        pub fn update(self: *Self, c1: Choice, c2: Choice, log: anytype) !Result {
-            return mechanics.update(self, c1, c2, log);
+        pub fn update(self: *Self, c1: Choice, c2: Choice, options: anytype) !Result {
+            return mechanics.update(self, c1, c2, options);
         }
 
         pub fn choices(self: *Self, player: Player, request: Choice.Type, out: []Choice) u8 {
@@ -118,14 +124,16 @@ const Side = extern struct {
         assert(@sizeOf(Side) == 240);
     }
 
-    pub inline fn get(self: *const Side, slot: u8) *Pokemon {
+    pub inline fn get(self: anytype, slot: u8) PointerType(@TypeOf(self), Pokemon) {
+        assert(@typeInfo(@TypeOf(self)).Pointer.child == Side);
         assert(slot > 0 and slot <= 6);
         const id = self.pokemon[slot - 1].position;
         assert(id > 0 and id <= 6);
         return &self.pokemon[id - 1];
     }
 
-    pub inline fn stored(self: *Side) *Pokemon {
+    pub inline fn stored(self: anytype) PointerType(@TypeOf(self), Pokemon) {
+        assert(@typeInfo(@TypeOf(self)).Pointer.child == Side);
         return self.get(1);
     }
 };
@@ -145,7 +153,8 @@ const ActivePokemon = extern struct {
         assert(@sizeOf(ActivePokemon) == 44);
     }
 
-    pub inline fn move(self: *ActivePokemon, mslot: u8) *MoveSlot {
+    pub inline fn move(self: anytype, mslot: u8) PointerType(@TypeOf(self), MoveSlot) {
+        assert(@typeInfo(@TypeOf(self)).Pointer.child == Pokemon);
         assert(mslot > 0 and mslot <= 4);
         assert(self.moves[mslot - 1].id != .None);
         return &self.moves[mslot - 1];
@@ -169,7 +178,8 @@ const Pokemon = extern struct {
         assert(@sizeOf(Pokemon) == 32);
     }
 
-    pub inline fn move(self: *Pokemon, mslot: u8) *MoveSlot {
+    pub inline fn move(self: anytype, mslot: u8) PointerType(@TypeOf(self), MoveSlot) {
+        assert(@typeInfo(@TypeOf(self)).Pointer.child == Pokemon);
         assert(mslot > 0 and mslot <= 4);
         assert(self.moves[mslot - 1].id != .None);
         return &self.moves[mslot - 1];
@@ -205,11 +215,11 @@ const DVs = packed struct {
             0xFF => .Unknown,
             else => if ((@as(u8, dvs.atk) << 4 | dvs.spe) < ratio) Gender.Female else Gender.Male,
         };
-        const p = @intCast(u6, 1 + ((5 * @as(u8, (dvs.atk & 0b1000) | ((dvs.def & 0b1000)) >> 1 |
+        const p: u6 = @intCast(1 + ((5 * @as(u8, (dvs.atk & 0b1000) | ((dvs.def & 0b1000)) >> 1 |
             ((dvs.spe & 0b1000)) >> 2 | ((dvs.spc & 0b1000)) >> 3) + (dvs.spc & 0b0011)) >> 1));
         var t = @as(u8, dvs.def & 0b0011) + (@as(u8, dvs.atk & 0b0011) << 2) + 1;
-        if (t >= @enumToInt(Type.@"???")) t = t + 1;
-        return DVs{ .gender = g, .pow = p, .type = @intToEnum(Type, t) };
+        if (t >= @intFromEnum(Type.@"???")) t = t + 1;
+        return DVs{ .gender = g, .pow = p, .type = @enumFromInt(t) };
     }
 
     comptime {
@@ -327,10 +337,11 @@ pub fn Stats(comptime T: type) type {
 
         pub fn calc(comptime stat: []const u8, base: T, dv: u4, exp: u16, level: u8) T {
             assert(level > 0 and level <= 100);
-            const evs = @min(255, @floatToInt(u16, @ceil(@sqrt(@intToFloat(f32, exp)))));
+            const float: f32 = @floatFromInt(exp);
+            const evs: u16 = @min(255, @as(u16, @intFromFloat(@ceil(@sqrt(float)))));
             const core: u32 = (2 *% (@as(u32, base) +% dv)) +% (evs / 4);
             const factor: u32 = if (std.mem.eql(u8, stat, "hp")) level + 10 else 5;
-            return @intCast(T, core *% @as(u32, level) / 100 +% factor);
+            return @intCast(core *% @as(u32, level) / 100 +% factor);
         }
     };
 }
@@ -390,7 +401,7 @@ test Item {
 pub const Move = moves.Move;
 
 test Move {
-    try expectEqual(251, @enumToInt(Move.BeatUp));
+    try expectEqual(251, @intFromEnum(Move.BeatUp));
     const move = Move.get(.DynamicPunch);
     try expectEqual(Move.Effect.ConfusionChance, move.effect);
     try expectEqual(@as(u8, 50), move.accuracy);
@@ -400,7 +411,7 @@ test Move {
 pub const Species = species.Species;
 
 test Species {
-    try expectEqual(152, @enumToInt(Species.Chikorita));
+    try expectEqual(152, @intFromEnum(Species.Chikorita));
     try expectEqual(@as(u8, 100), Species.get(.Celebi).stats.spd);
 }
 
@@ -409,7 +420,7 @@ pub const Types = types.Types;
 pub const Effectiveness = gen1.Effectiveness;
 
 test Types {
-    try expectEqual(13, @enumToInt(Type.Electric));
+    try expectEqual(13, @intFromEnum(Type.Electric));
 
     try expect(!Type.Steel.special());
     try expect(Type.Dark.special());

package/src/lib/gen2/helpers.zig

@@ -72,11 +72,9 @@ pub fn prng(rand: *PSRNG) data.PRNG {
                 rand.newSeed()
             else
                 .{
-                    rand.range(u8, 0, 256), rand.range(u8, 0, 256),
-                    rand.range(u8, 0, 256), rand.range(u8, 0, 256),
-                    rand.range(u8, 0, 256), rand.range(u8, 0, 256),
-                    rand.range(u8, 0, 256), rand.range(u8, 0, 256),
-                    rand.range(u8, 0, 256), rand.range(u8, 0, 256),
+                    rand.range(u8, 0, 256), rand.range(u8, 0, 256), rand.range(u8, 0, 256),
+                    rand.range(u8, 0, 256), rand.range(u8, 0, 256), rand.range(u8, 0, 256),
+                    rand.range(u8, 0, 256), rand.range(u8, 0, 256), rand.range(u8, 0, 256),
                 },
         },
     };
@@ -141,7 +139,7 @@ pub const Pokemon = struct {
                 .id = m,
                 .pp_ups = 3,
                 // NB: PP can be at most 61 legally (though can overflow to 63)
-                .pp = @intCast(u8, @min(Move.pp(m) / 5 * 8, 61)),
+                .pp = @intCast(@min(Move.pp(m) / 5 * 8, 61)),
             };
         }
         pokemon.item = p.item;
@@ -158,11 +156,11 @@ pub const Pokemon = struct {
     }
 
     pub fn random(rand: *PSRNG, opt: Options) data.Pokemon {
-        const s = @intToEnum(Species, rand.range(u8, 1, Species.size + 1));
+        const s: Species = @enumFromInt(rand.range(u8, 1, Species.size + 1));
         const species = Species.get(s);
         const lvl = if (rand.chance(u8, 1, 20)) rand.range(u8, 1, 99 + 1) else 100;
         // Pokémon Showdown does not support most items without in-battle held item effects
-        const max_item = @enumToInt(if (showdown) Item.FlowerMail else Item.TM50);
+        const max_item = @intFromEnum(if (showdown) Item.FlowerMail else Item.TM50);
         const item = if (rand.chance(u8, 1, 10)) 0 else rand.range(u8, 1, max_item + 1);
 
         var stats: Stats(u16) = .{};
@@ -184,14 +182,14 @@ pub const Pokemon = struct {
         for (0..n) |i| {
             var m: Move = .None;
             sample: while (true) {
-                m = @intToEnum(Move, rand.range(u8, 1, 164 + 1));
+                m = @enumFromInt(rand.range(u8, 1, 164 + 1));
                 for (0..i) |j| if (ms[j].id == m) continue :sample;
                 break;
             }
-            const pp_ups =
+            const pp_ups: u8 =
                 if (!opt.cleric and rand.chance(u8, 1, 10)) rand.range(u2, 0, 2 + 1) else 3;
             // NB: PP can be at most 61 legally (though can overflow to 63)
-            const max_pp = @intCast(u8, Move.pp(m) + @as(u8, pp_ups) * @min(Move.pp(m) / 5, 7));
+            const max_pp: u8 = @intCast(Move.pp(m) + pp_ups * @min(Move.pp(m) / 5, 7));
             ms[i] = .{
                 .id = m,
                 .pp_ups = pp_ups,

package/src/lib/gen2/mechanics.zig

@@ -1,8 +1,9 @@
 const std = @import("std");
 
+const pkmn = @import("../pkmn.zig");
+
 const common = @import("../common/data.zig");
 const DEBUG = @import("../common/debug.zig").print;
-const options = @import("../common/options.zig");
 const protocol = @import("../common/protocol.zig");
 const rng = @import("../common/rng.zig");
 
@@ -17,7 +18,7 @@ const ID = common.ID;
 const Player = common.Player;
 const Result = common.Result;
 
-const showdown = options.showdown;
+const showdown = pkmn.options.showdown;
 
 const Damage = protocol.Damage;
 const Heal = protocol.Heal;
@@ -34,11 +35,11 @@ const Species = data.Species;
 const Stats = data.Stats;
 const Status = data.Status;
 
-pub fn update(battle: anytype, c1: Choice, c2: Choice, log: anytype) !Result {
+pub fn update(battle: anytype, c1: Choice, c2: Choice, options: anytype) !Result {
     _ = battle;
     _ = c1;
     _ = c2;
-    _ = log;
+    _ = options;
 
     return Result.Default;
 }

package/src/lib/pkmn.zig

@@ -1,4 +1,4 @@
-/// Configurated Options for the pkmn package.
+/// Configured Options for the pkmn package.
 pub const options = @import("common/options.zig");
 /// Configures the behavior of the pkmn package.
 pub const Options = options.Options;
@@ -25,12 +25,12 @@ pub const Result = @import("common/data.zig").Result;
 /// Pokémon Showdown's RNG (backed by a Generation V & VI RNG).
 pub const PSRNG = @import("common/rng.zig").PSRNG;
 
-/// Namespace for helpers related to protocol trace logging.
+/// Namespace for helpers related to protocol message logging.
 pub const protocol = if (options.internal) struct {
     pub usingnamespace @import("common/protocol.zig");
 } else struct {
     /// Logs protocol information to its `Writer` during a battle update when
-    /// `options.trace` is enabled.
+    /// `options.log` is enabled.
     pub const Log = @import("common/protocol.zig").Log;
     /// Stripped down version of `std.io.FixedBufferStream` optimized for
     /// efficiently writing the individual protocol bytes. Note that the
@@ -41,14 +41,73 @@ pub const protocol = if (options.internal) struct {
     /// intialized with a `LOGS_SIZE`-sized buffer.
     pub const FixedLog = @import("common/protocol.zig").FixedLog;
     /// Null object pattern implementation of `Log` backed by a
-    /// `std.io.null_writer`. Ignores anything sent to it, though trace logging
-    /// should addtionally be turned off entirely by using `options.trace`.
+    /// `std.io.null_writer`. Ignores anything sent to it, though protocol
+    /// logging should additionally be turned off entirely with `options.log`.
     pub const NULL = @import("common/protocol.zig").NULL;
 };
 
-/// Namespace for Generation I Pokémon
+pub usingnamespace @import("common/rational.zig");
+
+/// Namespace for cross-generation battle-related types.
+pub const battle = @import("common/battle.zig");
+
+/// Namespace for Generation I Pokémon.
 pub const gen1 = struct {
     pub usingnamespace @import("gen1/data.zig");
+    /// Tracks chance actions and their associated probability during a
+    /// Generation I battle update when `options.chance` is enabled.
+    pub const Chance = @import("gen1/chance.zig").Chance;
+    /// Namespace for types associated with tracking Generation I Pokémon chance outcomes.
+    pub const chance = struct {
+        /// Actions taken by a hypothetical "chance player" that convey
+        /// information about which RNG events were observed during a Generation
+        /// I battle `update`. This can additionally be provided as input to the
+        /// `update` call via the `Calc` when `options.calc` is enabled to
+        /// override the normal behavior of the RNG in order to force specific
+        /// outcomes.
+        pub const Actions = @import("gen1/chance.zig").Actions;
+        /// Information about the RNG that was observed during a Generation I
+        /// battle `update` for a single player.
+        pub const Action = @import("gen1/chance.zig").Action;
+        /// TODO
+        pub const Durations = @import("gen1/chance.zig").Durations;
+        /// TODO
+        pub const Duration = @import("gen1/chance.zig").Duration;
+        /// Null object pattern implementation of Generation I `Chance` which
+        /// does nothing, though chance tracking should additionally be turned
+        /// off entirely via `options.chance`.
+        pub const NULL = @import("gen1/chance.zig").NULL;
+    };
+    /// 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 = @import("gen1/calc.zig").Calc;
+    /// Namespace for types associated with supported Generation I Pokémon damage calc features.
+    pub const calc = if (options.internal) struct {
+        pub usingnamespace @import("gen1/calc.zig");
+    } else struct {
+        /// TODO
+        pub const Overrides = @import("gen1/calc.zig").Overrides;
+        /// Information relevant to damage calculation that occured during a Generation I
+        /// battle `update`.
+        pub const Summaries = @import("gen1/calc.zig").Summaries;
+        /// Information relevant to damage calculation that occured during a Generation I
+        ///  battle `update` for a single player.
+        pub const Summary = @import("gen1/calc.zig").Summary;
+        /// Null object pattern implementation of Generation I `Calc` which does nothing,
+        /// though damage calculator support should additionally be turned off
+        /// entirely via `options.calc`.
+        pub const NULL = @import("gen1/calc.zig").NULL;
+    };
     /// Provides helpers for initializing Generation I Pokémon battles.
     pub const helpers = @import("gen1/helpers.zig");
 };
+
+// Internal APIs used by other pkmn libraries, not actually part of the public API.
+// NOTE: `pub usingnamespace struct { ... }` here results in a (false?) dependency loop
+pub const js = if (options.internal) struct {
+    pub usingnamespace @import("common/js.zig");
+} else struct {};
+pub const bindings = if (options.internal) struct {
+    pub const node = @import("binding/node.zig");
+    pub const wasm = @import("binding/wasm.zig");
+} else struct {};