@pkmn/engine 0.1.0-dev.b9fb6eab → 0.1.0-dev.be951af1

package/src/lib/gen2/README.md

@@ -32,35 +32,36 @@ The following information is required to simulate a Generation II Pokémon battl
 | `pokemon.species`              | `party_struct.Species`            | `pokemon.baseSpecies`                 |
 | `active.species`               | `battle_struct.Species`           | `pokemon.species`                     |
 | `active.stats`                 | `TODO modified`                   | `pokemon.storedStats`                 |
-| `active.trapped FIXME`         | `PlayerTrappingMove`              | `pokemon.trapped`                     |
-| `active.switching`             | `PlayerIsSwitching`               | `pokemon.switchFlag`                  |
 | `active.boosts`                | `PlayerStatLevels`                | `pokemon.boosts`                      |
 | `active.volatiles`             | `PlayerBattleStatus{1,2,3}`       | `pokemon.volatiles`                   |
-| `volatiles.data.bide`          | `PlayerDamageTaken`               | `volatiles.bide.totalDamage`          |
-| `volatiles.data.substitute`    | `PlayerSubstituteHP`              | `volatiles.substitute.hp`             |
-| `volatiles.data.rollout`       | `PlayerRolloutCount`              | `volatiles.rollout.hitCount`          |
-| `volatiles.data.confusion`     | `PlayerConfuseCount`              | `volatiles.confusion.duration`        |
-| `volatiles.data.toxic`         | `PlayerToxicCount`                | `volatiles.residualdmg.counter`       |
-| `volatiles.data.disabled`      | `PlayerDisableCount`              | `moveSlots.disabled`                  |
-| `volatiles.data.encore`        | `PlayerEncoreCount`               | `volatiles.encore.duration`           |
-| `volatiles.data.perish_song`   | `PlayerPerishCount`               | `volatiles.perishsong.duration`       |
-| `volatiles.data.fury_cutter`   | `PlayerFuryCutterCount`           | `volatiles.furycutter.multiplier`     |
-| `volatiles.data.protect`       | `PlayerProtectCount`              | `volatiles.stall.counter`             |
-| `volatiles.data.future_sight`  | `PlayerFutureSight{Damage,Count}` | `slotConditions[i].futuremove`        |
-| `volatiles.data.rage`          | `PlayerRageCounter`               | **BUG**                               |
-| `volatiles.data.bind`          | `PlayerWrapCount`                 | `volatiles.partiallytrapped.duration` |
+| `volatiles.bide`               | `PlayerDamageTaken`               | `volatiles.bide.totalDamage`          |
+| `volatiles.substitute`         | `PlayerSubstituteHP`              | `volatiles.substitute.hp`             |
+| `volatiles.rollout`            | `PlayerRolloutCount`              | `volatiles.rollout.hitCount`          |
+| `volatiles.confusion`          | `PlayerConfuseCount`              | `volatiles.confusion.duration`        |
+| `volatiles.toxic`              | `PlayerToxicCount`                | `volatiles.residualdmg.counter`       |
+| `volatiles.disable`            | `PlayerDisableCount`              | `moveSlots.disabled`                  |
+| `volatiles.encore`             | `PlayerEncoreCount`               | `volatiles.encore.duration`           |
+| `volatiles.perish_song`        | `PlayerPerishCount`               | `volatiles.perishsong.duration`       |
+| `volatiles.fury_cutter`        | `PlayerFuryCutterCount`           | `volatiles.furycutter.multiplier`     |
+| `volatiles.protect`            | `PlayerProtectCount`              | `volatiles.stall.counter`             |
+| `volatiles.future_sight`       | `PlayerFutureSight{Damage,Count}` | `slotConditions[i].futuremove`        |
+| `volatiles.rage`               | `PlayerRageCounter`               | **BUG**                               |
+| `volatiles.bind`               | `PlayerWrapCount`                 | `volatiles.partiallytrapped.duration` |
+| `volatiles.bind_reason`        | `PlayerTrappingMove`              | `volatiles.effectState.sourceEffect`  |
 |                                | `PlayerCharging`                  |                                       |
-|                                | `PlayerJustGotFrozen`             |                                       |
+| `volatiles.trapped FIXME`      | `FIXME`                           | `pokemon.trapped`                     |
+| `volatiles.switched`           | `TODO`                            | `pokemon.switchFlag`                  |
+| `volatiles.switching`          | `PlayerIsSwitching`               | `pokemon.switchFlag`                  |
+| `volatiles.frozen`             | `PlayerJustGotFrozen`             | `volatiles.frozen`                    |
 |                                |                                   |                                       |
 | `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 +78,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 +94,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 +162,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,11 +216,86 @@ 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):
 
+## Details
+
+| pkmn                      | Pokémon Crystal (pret)                            |
+| ------------------------- | ------------------------------------------------- |
+| `start`                   | `DoBattle`                                        |
+| `update`                  | `BattleTurn`                                      |
+| `selectMove` / `saveMove` | `CheckPlayerLockedIn` / `ParsePlayerAction`       |
+| `switchIn`                | `SwitchPlayerMon` / `SendOutPlayerMon`            |
+| `turnOrder`               | `DetermineMoveOrder`                              |
+| `doTurn`                  | `DoTurn`                                          |
+| `executeMove`             | `DoMove`                                          |
+| `beforeMove`              | `CheckTurn`                                       |
+| `canMove`                 |                                                   |
+| `decrementPP`             |                                                   |
+| `doMove`                  |                                                   |
+| `checkCriticalHit`        | `BattleCommand_Critical`                          |
+| `calcDamage`              | `BattleCommand_DamageCalc` / `PlayerAttackDamage` |
+| `adjustDamage`            | `BattleCommand_Stab`                              |
+| `randomizeDamage`         | `BattleCommand_DamageVariation`                   |
+| `specialDamage`           | `BattleCommand_ConstantDamage`                    |
+| `applyDamage`             | `BattleCommand_ApplyDamage`                       |
+| `checkHit`                | `BattleCommand_CheckHit`                          |
+| `checkFaint`              | `CheckFaint`                                      |
+| `handleResidual`          | `ResidualDamage`                                  |
+| `endTurn`                 | `EndTurn`                                         |
+
+DoBattle
+BattleTurn
+- HandleBerserkGene
+- CheckPlayerLockedIn
+- BattleMenu
+- ParsePlayerAction
+- DetermineMoveOrder
+  - CompareMovePriority
+  - GetMovePriority
+- Battle_*
+  - Handle*Switch
+    - SwitchPlayerMon
+      - BreakAttraction
+      - SendOutPlayerMon
+    - SpikesDamage
+  - *Turn_EndOpponentProtectEndureDestinyBond
+    - EndUserDestinyBond
+    - Do*Turn
+    - EndOpponentProtectEndureDestinyBond
+  - ResidualDamage
+  - CheckFaint_*
+  - HandleBetweenTurnEffects
+    - HandleFutureSight
+    - HandleWeather
+    - HandleWrap
+    - HandlePerishSong
+    - HandleLeftovers
+    - HandleMysteryBerry
+    - HandleDefrost
+    - HandleSafeguard
+    - HandleScreens
+    - HandleStatBoostingHeldItems
+    - HandleHealingItems
+    - HandleEncore
+
+DoTurn
+DoMove = executeMove
+CheckTurn = beforeMove
+BattleCommand_Critical = checkCriticalHit
+BattleCommand_Stab = adjustDamage
+BattleCommand_DamageVariation = randomizeDamage
+BattleCommand_CheckHit = checkHit
+BattleCommand_ApplyDamage = applyDamage
+BattleCommand_CheckFaint
+BattleCommand_BuildOpponentRage = buildRage
+BattleCommand_DamageCalc (PlayerAttackDamage / EnemyAttackDamage) = calcDamage
+BattleCommand_ConstantDamage = specialDamage
+DoEnemyDamage / DoPlayerDamage / DoSubstituteDamage
+
 ==**TODO**==
 
 ## Protocol
@@ -227,62 +303,7 @@ padding](https://en.wikipedia.org/wiki/Data_structure_alignment) and
 TODO
 
 ```txt
--activate: _, damage, move, name, number, of
--anim: _
--block: _
--boost: _, from, silent
--clearallboost: _
--copyboost: from
--crit: _
--curestatus: msg
--cureteam: from
--damage: _, from, of, partiallytrapped
--end: _, from, of, partiallytrapped, silent
--enditem: _, eat
--fail: _, block, weak
--fieldactivate: _
--heal: _, from, of, silent
--hint: _
--hitcount: _
--immune: _, ohko
--item: from, of
--miss: _
--mustrecharge: _
--ohko: _
--prepare: _
--resisted: _
--setboost: from
--sethp: from, silent
--sideend: _, from, of
--sidestart: _
--singlemove: _
--singleturn: _
--start: _, of, silent
--status: _, from, silent
--supereffective: _
--transform: _
--unboost: _
--weather: _, upkeep
-cant: _
-debug: _
-done: _
-drag: _
-faint: _
-gametype: _
-gen: _
-move: _, from, miss, still
-player: _
-request: _
-rule: _
-start: _
-switch: _, from
-t:: _
-teamsize: _
-tie: _
-tier: _
-turn: _
-upkeep: _
-win: _
+-activate: _,  move, name, number
 ```
 
 ## Bugs

package/src/lib/gen2/calc.zig

@@ -0,0 +1,143 @@
+const std = @import("std");
+
+const pkmn = @import("../pkmn.zig");
+
+const common = @import("../common/data.zig");
+const util = @import("../common/util.zig");
+
+const chance = @import("chance.zig");
+
+const assert = std.debug.assert;
+
+const enabled = pkmn.options.calc;
+
+const Player = common.Player;
+
+const PointerType = util.PointerType;
+
+const Actions = chance.Actions;
+const Action = chance.Action;
+
+/// Information relevant to damage calculation that occured during a Generation II battle `update`.
+pub const Summaries = extern struct {
+    /// Relevant information for Player 1.
+    p1: Summary = .{},
+    /// Relevant information for Player 2.
+    p2: Summary = .{},
+
+    comptime {
+        assert(@sizeOf(Summaries) == 12);
+    }
+
+    /// Returns the `Summary` for the given `player`.
+    pub inline fn get(self: anytype, player: Player) PointerType(@TypeOf(self), Summary) {
+        assert(@typeInfo(@TypeOf(self)).Pointer.child == Summaries);
+        return if (player == .P1) &self.p1 else &self.p2;
+    }
+};
+
+/// Information relevant to damage calculation that occured during a Generation II battle `update`
+/// for a single player.
+pub const Summary = extern struct {
+    /// The computed raw damage values.
+    damage: Damage = .{},
+
+    /// Intermediate raw damage values computed during a calculation.
+    pub const Damage = extern struct {
+        /// The base computed damage before the damage roll is applied.
+        base: u16 = 0,
+        /// The final computed damage that gets applied to the Pokémon. May exceed the target's HP
+        // (to determine the *actual* damage done compare the target's stored HP before and after).
+        final: u16 = 0,
+        /// Whether higher damage will saturate / result in the same outcome (e.g. additional damage
+        /// gets ignored due to it already breaking a Substitute or causing the target to faint).
+        capped: bool = false,
+
+        // NOTE: 15 bits padding
+
+        comptime {
+            assert(@sizeOf(Damage) == 6);
+        }
+    };
+
+    comptime {
+        assert(@sizeOf(Summary) == 6);
+    }
+};
+
+/// TODO
+pub const Overrides = extern struct {
+    /// TODO
+    actions: Actions = .{},
+};
+
+/// Allows for forcing the value of specific RNG events during a Generation II 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 = .{},
+    /// Information relevant to damage calculation.
+    summaries: Summaries = .{},
+
+    pub fn overridden(
+        self: Calc,
+        player: Player,
+        comptime field: Action.Field,
+    ) ?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));
+        return if (switch (@typeInfo(@TypeOf(val))) {
+            .Enum => val != .None,
+            .Int => val != 0,
+            else => unreachable,
+        }) val else null;
+    }
+
+    pub fn base(self: *Calc, player: Player, val: u16) void {
+        if (!enabled) return;
+
+        self.summaries.get(player).damage.base = val;
+    }
+
+    pub fn final(self: *Calc, player: Player, val: u16) void {
+        if (!enabled) return;
+
+        self.summaries.get(player).damage.final = val;
+    }
+
+    pub fn capped(self: *Calc, player: Player) void {
+        if (!enabled) return;
+
+        self.summaries.get(player).damage.capped = true;
+    }
+};
+
+/// Null object pattern implementation of Generation II `Calc` which does nothing, though damage
+/// calculator support should additionally be turned off entirely via `options.calc`.
+pub const NULL: Null = .{};
+
+const Null = struct {
+    pub fn overridden(
+        self: Null,
+        player: Player,
+        comptime field: Action.Field,
+    ) ?std.meta.FieldType(Action, field) {
+        _ = .{ self, player };
+        return null;
+    }
+
+    pub fn base(self: Null, player: Player, val: u16) void {
+        _ = .{ self, player, val };
+    }
+
+    pub fn final(self: Null, player: Player, val: u16) void {
+        _ = .{ self, player, val };
+    }
+
+    pub fn capped(self: Null, player: Player) void {
+        _ = .{ self, player };
+    }
+};