@pkmn/engine 0.1.0-dev.7cd30bd9 → 0.1.0-dev.7f2014fa

package/src/lib/gen1/README.md

@@ -28,35 +28,36 @@ list of additional reference [**resources**](#resources).
 
 The following information is required to simulate a Generation I Pokémon battle:
 
-| pkmn                                 | Pokémon Red (pret)                 | Pokémon Showdown                       |
-| ------------------------------------ | ---------------------------------- | -------------------------------------- |
-| `battle.seed`                        | `Random{Add,Sub}`                  | `battle.seed`                          |
-| `battle.turn`                        | -                                  | `battle.turn`                          |
-| `battle.last_damage`                 | `Damage`                           | `battle.lastDamage`                    |
-| `side.{active,pokemon}`              | `PlayerMonNumber`/`BattleMon`      | `side.active`                          |
-| `side.team`                          | `PartyMons`                        | `side.pokemon`                         |
-| `side.last_used_move`                | `PlayerUsedMove`                   | `pokemon.lastMove`                     |
-| `side.last_selected_move`            | `PlayerSelectedMove`               | `side.lastSelectedMove`                |
-| `battle.last_selected_indexes`       | `PlayerMoveListIndex`              | `side.lastMove`                        |
-| `side.order`                         | -                                  | `pokemon.position`                     |
-| `{pokemon,active}.moves`             | `{party,battle}_struct.{Moves,PP}` | `pokemon.{baseMoveSlots,moveSlots}`    |
-| `pokemon.hp`                         | `{party,battle}_struct.HP`         | `pokemon.hp`                           |
-| `{pokemon,active}.status`            | `{party,battle}_struct.Status`     | `pokemon.status`                       |
-| `{pokemon,active}.level`             | `PlayerMonUnmodifiedLevel`         | `pokemon.level`                        |
-| `pokemon.species`                    | `party_struct.Species`             | `pokemon.baseSpecies`                  |
-| `pokemon.stats`                      | `box_struct.Stats`                 | `pokemon.baseStoredStats`              |
-| `active.stats`                       | `battle_struct.Stats`              | `pokemon.modifiedStats`                |
-| `volatiles.transform`                | `PlayerMonUnmodified*`             | `pokemon.storedStats`                  |
-| `active.species`                     | `battle_struct.Species`            | `pokemon.species`                      |
-| `{pokemon,active}.types`             | `{party,battle}_struct.Type`       | `pokemon.types`                        |
-| `active.boosts`                      | `PlayerMon*Mod`                    | `pokemon.boosts`                       |
-| `active.volatiles`                   | `PlayerBattleStatus{1,2,3}`        | `pokemon.volatiles`                    |
-| `volatiles.state`                    | `PlayerBideAccumulatedDamage`      | `volatiles.bide.totalDamage`           |
-| `volatiles.attacks`                  | `PlayerNumAttacksLeft`             | `volatiles.{bide,lockedmove}.duration` |
-| `volatiles.confusion`                | `PlayerConfusedCounter`            | `volatiles.confusion.duration`         |
-| `volatiles.toxic`                    | `PlayerToxicCounter`               | `volatiles.residualdmg.counter`        |
-| `volatiles.substitute`               | `PlayerSubstituteHP`               | `volatiles.substitute.hp`              |
-| `volatiles.disabled_{move,duration}` | `PlayerDisabledMove{,Number}`      | `volatiles.disable.{move,time}`        |
+| pkmn                                    | Pokémon Red (pret)                 | Pokémon Showdown                       |
+| --------------------------------------- | ---------------------------------- | -------------------------------------- |
+| `battle.seed`                           | `Random{Add,Sub}`                  | `battle.seed`                          |
+| `battle.turn`                           | -                                  | `battle.turn`                          |
+| `battle.last_damage`                    | `Damage`                           | `battle.lastDamage`                    |
+| `side.{active,pokemon}`                 | `PlayerMonNumber`/`BattleMon`      | `side.active`                          |
+| `side.team`                             | `PartyMons`                        | `side.pokemon`                         |
+| `side.last_used_move`                   | `PlayerUsedMove`                   | `pokemon.lastMove`                     |
+| `side.last_selected_move`               | `PlayerSelectedMove`               | `side.lastSelectedMove`                |
+| `battle.last_moves.{p1,p2}_index`       | `PlayerMoveListIndex`              | -                                      |
+| `battle.last_moves.{p1,p2}_counterable` | -                                  | `side.lastMove`                        |
+| `side.order`                            | -                                  | `pokemon.position`                     |
+| `{pokemon,active}.moves`                | `{party,battle}_struct.{Moves,PP}` | `pokemon.{baseMoveSlots,moveSlots}`    |
+| `pokemon.hp`                            | `{party,battle}_struct.HP`         | `pokemon.hp`                           |
+| `{pokemon,active}.status`               | `{party,battle}_struct.Status`     | `pokemon.status`                       |
+| `{pokemon,active}.level`                | `PlayerMonUnmodifiedLevel`         | `pokemon.level`                        |
+| `pokemon.species`                       | `party_struct.Species`             | `pokemon.baseSpecies`                  |
+| `pokemon.stats`                         | `box_struct.Stats`                 | `pokemon.baseStoredStats`              |
+| `active.stats`                          | `battle_struct.Stats`              | `pokemon.modifiedStats`                |
+| `volatiles.transform`                   | `PlayerMonUnmodified*`             | `pokemon.storedStats`                  |
+| `active.species`                        | `battle_struct.Species`            | `pokemon.species`                      |
+| `{pokemon,active}.types`                | `{party,battle}_struct.Type`       | `pokemon.types`                        |
+| `active.boosts`                         | `PlayerMon*Mod`                    | `pokemon.boosts`                       |
+| `active.volatiles`                      | `PlayerBattleStatus{1,2,3}`        | `pokemon.volatiles`                    |
+| `volatiles.state`                       | `PlayerBideAccumulatedDamage`      | `volatiles.bide.totalDamage`           |
+| `volatiles.attacks`                     | `PlayerNumAttacksLeft`             | `volatiles.{bide,lockedmove}.duration` |
+| `volatiles.confusion`                   | `PlayerConfusedCounter`            | `volatiles.confusion.duration`         |
+| `volatiles.toxic`                       | `PlayerToxicCounter`               | `volatiles.residualdmg.counter`        |
+| `volatiles.substitute`                  | `PlayerSubstituteHP`               | `volatiles.substitute.hp`              |
+| `volatiles.disabled_{move,duration}`    | `PlayerDisabledMove{,Number}`      | `volatiles.disable.{move,time}`        |
 
 - Pokémon Showdown [does not implement the correct Generation I RNG](#rng) and as such its `seed` is
   different
@@ -68,6 +69,9 @@ The following information is required to simulate a Generation I Pokémon battle
   Counter and is not set and cleared in the correct locations. `Pokemon.lastMove` matches
   `PlayerUsedMove` more often so is what the engine attempts to model, despite the implications for
   Counter)
+- `battle.last_moves` doesn't map precisely to cartridge concepts because it is used to track desyncs
+  which instead are represented on the cartridge as discrepancies between the two separate battle states
+  that exist in the link battle.
 - Pokémon Showdown does not implement the [partial-trapping move Mirror Move
   glitch](https://glitchcity.wiki/Partial_trapping_move_Mirror_Move_link_battle_glitch) and as such
   does not need to keep track of a player's last selected move index (`PlayerMoveListIndex`)
@@ -98,8 +102,8 @@ The following information is required to simulate a Generation I Pokémon battle
 store general information about the battle. Unlike in Pokémon Showdown there is a distinction
 between the data structure for the "active" Pokémon and its party members (see below).
 
-Due to layout constraints, the index of the last selected move for a side is stored in what would
-otherwise be the padding bytes of`Battle` (the `last_selected_indexes` field) instead of in `Side`.
+Due to layout constraints, details about the last moves for a side are stored in what would
+otherwise be the padding bytes of`Battle` (the `last_moves` field) instead of in `Side`.
 
 ### `Pokemon` / `ActivePokemon`
 
@@ -198,7 +202,7 @@ above, PP information isn't strictly necessary in Generation I so is dropped. `M
 a special sentinel value to indicate `null`. Move PP data is only included for testing and is not
 necessary for the actual engine implementation.
 
-In order to workaround various [Pokémon Showdown bugs](#bugs) and to support its protocol in traces,
+In order to workaround various [Pokémon Showdown bugs](#bugs) and to support its protocol in logs,
 additional information is stored in `Move.Data` (`targets`) about what Pokémon Showdown believes the
 `Move.Target` to be (despite the concept of targeting not existing until Generation III when Double
 battles were introduced). More specifically, a move's "targeting" status is required in various
@@ -331,24 +335,24 @@ does not produce an equivalent to Pokémon Showdown's `|request|` protocol messa
 must be gleaned through the `Battle` state). Useful size and offset information can be found in
 the [`layout.json`](../../data/layout.json) which exists to simplify writing driver code.
 
-Documentation of the wire protocol used for logging traces when `-Dtrace` is enabled can be found in
-[PROTOCOL.md](../../../docs/PROTOCOL.md). Note that the
+Documentation of the wire protocol used for protocol message logging when `-Dlog` is enabled can be
+found in [PROTOCOL.md](../../../docs/PROTOCOL.md). Note that the
 [`pkmn-debug`](../../../README.md#pkmn-debug) tool exists to display the binary protocol and battle
 data in the browser for ease of debugging.
 
 ### `Battle`
 
-| Start   | End     | Data                    | Description                                             |
-| ------- | ------- | ----------------------- | ------------------------------------------------------- |
-| 0       | 184     | [`sides[0]`](#side)     | Player 1's side                                         |
-| 184     | 368     | [`sides[1]`](#side)     | Player 2's side                                         |
-| 368     | 370     | `turn`                  | The current turn number                                 |
-| 370     | 372     | `last_damage`           | The last damage dealt by either side                    |
-| 372     | 373-376 | `last_selected_indexes` | The slot index of the last selected moves for each side |
-| 373-376 | 384     | `rng`                   | The RNG state                                           |
+| Start   | End     | Data                | Description                                             |
+| ------- | ------- | ------------------- | ------------------------------------------------------- |
+| 0       | 184     | [`sides[0]`](#side) | Player 1's side                                         |
+| 184     | 368     | [`sides[1]`](#side) | Player 2's side                                         |
+| 368     | 370     | `turn`              | The current turn number                                 |
+| 370     | 372     | `last_damage`       | The last damage dealt by either side                    |
+| 372     | 373-376 | `last_moves`        | The slot index of the last selected moves for each side |
+| 373-376 | 384     | `rng`               | The RNG state                                           |
 
 - the current `turn` is 2 bytes, written in native-endianness
-- `last_selected_indexes` layout depends on whether or not Pokémon Showdown compatibility mode is
+- `last_moves` layout depends on whether or not Pokémon Showdown compatibility mode is
   enabled (`-Dshowdown`). In either case it stores a move "slot", where 0 is used as an empty value and
   1-4 represent actual moves:
   - if `showdown` is enabled bytes 372 and 373 are used to store the last selected move index of
@@ -485,12 +489,10 @@ Beyond the general bugs listed above, several move effects are implemented incor
 Showdown. Some of these moves are [too fundamentally broken to be implemented](#unimplementable) by
 the pkmn engine, but the following moves have their broken behavior preserved in `-Dshowdown` mode:
 
-- **Bide**: If the opponent faints after Bide inflicts damage on Pokémon Showdown residual damage
-  incorrectly still gets applied to Bide's user.
+- **Counter**: On Pokémon Showdown choices made while sleeping (which should not have been
+  registered) can erroneously cause Counter to trigger Desync Clause Mod behavior.
 - **Leech Seed**: Leech Seed fails to heal its source side if a seeded target faints due to
-  recoil/crash damage on Pokémon Showdown. Pokémon Showdown also updates the battle's last damage
-  field with the uncapped Leech Seed damage if the residual damage is applied which has consequences
-  for Bide and Counter.
+  recoil/crash damage on Pokémon Showdown.
 - **Pay Day**: Pay Day should still scatter coins if it hits (but doesn't break) and opponent's
   Substitute but doesn't on Pokémon Showdown.
 - **Flinch**: Flinching does not get cleared during move selection on Pokémon Showdown and is
@@ -531,9 +533,13 @@ the pkmn engine, but the following moves have their broken behavior preserved in
   glitch](https://glitchcity.wiki/Substitute_%C2%BC_HP_glitch) also fails in many cases due to
   Pokémon Showdown implementing the health check based on floating point division instead of integer
   divison like on the cartridge (meaning the Substitute 1/4 glitch will only occur if the Pokémon's
-  maximum HP is evenly divisible by 4). Finally, Substitute also incorrectly blocks Dream Eater on
+  maximum HP is evenly divisible by 4). Substitute also incorrectly blocks Dream Eater on
   Pokémon Showdown and will incorrectly still heal 1 HP for any draining moves if the attack does 0
-  damage.
+  damage. Finally, Pokémon Showdown uses a `subFainted` field to track whether a Substitute was
+  broken in order to know when to nullify a move's effect, only it doesn't get cleared at the end of
+  the turn and can result in incorrect behavior on subsequent turns with the moves Mirror Move and
+  Metronome that invoke `runMove` (which is where `subFainted` gets cleared) on the user but skips
+  calling it for the eventual true target.
 
 In addition to numerous cases where Pokémon Showdown uses the wrong type of message (e.g. `|-fail`
 vs. `|-miss|` vs. `|-immune|`, e.g. in the case of Leech Seed) which are not documented here, Pokémon
@@ -595,6 +601,10 @@ Showdown's behavior for the following moves (the pkmn engine attempts to reprodu
 behavior that can be reproduced without making data structure changes or dramatically deviating from
 the correct control flow):
 
+- **Bide**: Bide's damage can overflow if OHKO moves are involved because OHKO moves work by setting
+  the damage to 65535 - Pokémon Showdown doesn't implement this overflow and instead lets Bide's
+  damage grow unbounded. Additionally, if the opponent faints after Bide inflicts damage on Pokémon
+  Showdown residual damage incorrectly still gets applied to Bide's user.
 - **Wrap**: Binding moves like Wrap are implemented on Pokémon Showdown with an artificial
   `partialtrappinglock` volatile as opposed to how it works on the cartridge which simply relies on
   the `Binding` volatile of the opponent. This mistake results in choice locking not being reported
@@ -603,9 +613,9 @@ the correct control flow):
   still gets a turn under the [trapping sleep
   glitch](https://glitchcity.wiki/Trapping_move_and_sleep_glitch), Wrap does 0 damage against
   Ghost-type Pokémon instead of properly respecting immunity, and binding effects are handled in the
-  wrong order in the code.
-- **Counter**: On Pokémon Showdown choices made while sleeping (which should not have been
-  registered) can erroneously cause Counter to trigger Desync Clause Mod behavior.
+  wrong order in the code which results in either out of order messaging or, more consequentially,
+  Pokémon using Rage/Bide or Thrashing/Charging moves being incorrectly forced to skip a turn when
+  the Pokémon using the Binding move switches.
 - **Mimic**: Pokémon Showdown checks that the user of Mimic has Mimic in one of their move slots,
   which means Mimic legally called via Metronome or Mirror Move will only work if the user also has
   Mimic (and the moved mimicked by Mimic called via Metronome / Mirror Move will erroneously
@@ -614,18 +624,25 @@ the correct control flow):
   the Pokémon already knows, PP deduction for using either the original move of the mimicked move
   will instead deduct PP for whichever appears at the lower move slot index and the PP will be
   allowed to go negative (effectively allowing for infinite PP use).
-- **Mirror Move**: Binding moves misbehave when used via Mirror Move (though Pokémon Showdown has
-  its own weird behavior and does not implement the [partial trapping move Mirror Move
+- **Mirror Move**: As covered above, both Substitute and Binding moves misbehave when used via
+  Mirror Move (though Pokémon Showdown has its own weird behavior and does not implement the
+  [partial trapping move Mirror Move
   glitch](https://glitchcity.wiki/Partial_trapping_move_Mirror_Move_link_battle_glitch) that exists
-  on the cartridge).
-- **Metronome**: In addition to the issues with binding moves, Metronome and Mirror Move cannot
-  mutually call each other more than 3 times in a row without causing the Pokémon Showdown simulator
-  to crash due to defensive safety checks that do not exist on the cartridge.
-- **Transform**:  Transform screws up the effect of Disable, because on Pokémon Showdown, Disable
+  on the cartridge). Additionally, Pokémon Showdown sets the last used move every turn a Pokémon is
+  Thrashing instead of just on the turn it is actually selected meaning Mirror Move will sometimes
+  successfully mirror a Thrashing move when it should fail. Finally, if Mirror Move copies
+  Struggle it should not deduct PP but on Pokémon Showdown it does.
+- **Metronome**: In addition to the issues with binding moves and Substitute, Metronome and Mirror
+  Move cannot mutually call each other more than 3 times in a row without causing the Pokémon
+  Showdown simulator to crash due to defensive safety checks that do not exist on the cartridge.
+- **Transform**: Transform screws up the effect of Disable, because on Pokémon Showdown, Disable
   prevents moves of a given *name* from being used (e.g. "Water Gun") as opposed to moves in a
   specific *slot* (e.g. the 2nd move slot), and a Pokémon's moves can change after Transform (this
-  is not an issue with Disable + Mimic because Mimic happens to replace the same slot). Furthermore,
-  transforming and then using Mirror Move / Metronome can result in [glitchy behavior and
+  is not an issue with Disable + Mimic because Mimic happens to replace the same slot). Transform
+  also has a bad interaction with Pokémon Showdown's buggy Haze implementation, as Haze on Pokémon
+  Showdown does not copy unmodified stats, leaving the Transformed Pokémon with inccorect stats.
+  Furthermore, transforming and then using Mirror Move / Metronome can result in [glitchy behavior
+  and
   softlocks](https://pkmn.cc/bulba/Transform_glitches#Transform_.2B_Mirror_Move.2FMetronome_PP_error)
   which Pokémon Showdown does not implement.
 

package/src/lib/gen1/data.zig

@@ -55,8 +55,8 @@ pub fn Battle(comptime RNG: anytype) type {
         turn: u16 = 0,
         /// The last damage dealt by either side.
         last_damage: u16 = 0,
-        /// The slot index of the last selected moves for each side
-        last_selected_indexes: MoveIndexes = .{},
+        /// TODO
+        last_moves: MoveDetails = .{},
         /// The pseudo random number generator.
         rng: RNG,
 
@@ -76,7 +76,7 @@ pub fn Battle(comptime RNG: anytype) type {
         }
 
         /// Returns the result of applying Player 1's choice `c1` and Player 2's choice `c2` to the
-        /// battle, optionally writing protocol logs to `log` if `options.trace` is enabled.
+        /// battle, optionally writing protocol message logs to `log` if `options.log` is enabled.
         pub fn update(self: *Self, c1: Choice, c2: Choice, log: anytype) !Result {
             return mechanics.update(self, c1, c2, log);
         }
@@ -201,17 +201,19 @@ pub const MoveSlot = extern struct {
     }
 };
 
-const uindex = if (showdown) u16 else u4;
-
-/// Representation of the move slot indexes for each side in a Generation I Pokémon battle.
-pub const MoveIndexes = packed struct {
-    /// Player 1's move index.
-    p1: uindex = 0,
-    /// Player 1's move index.
-    p2: uindex = 0,
+/// TODO
+pub const MoveDetails = packed struct {
+    /// The move slot index of the last move selected in the battle menu by Player 1
+    p1_index: if (showdown) u8 else u3 = 0,
+    /// Whether the last move executed by Player 1 was counterable.
+    p1_counterable: if (showdown) u8 else u1 = 0,
+    /// The move slot index of the last move selected in the battle menu by Player 2
+    p2_index: if (showdown) u8 else u3 = 0,
+    /// Whether the last move executed by Player 2 was counterable.
+    p2_counterable: if (showdown) u8 else u1 = 0,
 
     comptime {
-        assert(@sizeOf(MoveIndexes) == if (showdown) 4 else 1);
+        assert(@sizeOf(MoveDetails) == if (showdown) 4 else 1);
     }
 };
 

package/src/lib/gen1/helpers.zig

@@ -55,17 +55,12 @@ pub const Battle = struct {
     }
 
     pub fn random(rand: *PSRNG, opt: Options) data.Battle(data.PRNG) {
-        var p1: u4 = 0;
-        var p2: u4 = 0;
-        var battle: data.Battle(data.PRNG) = .{
+        return .{
             .rng = prng(rand),
             .turn = 0,
             .last_damage = 0,
             .sides = .{ Side.random(rand, opt), Side.random(rand, opt) },
         };
-        battle.last_selected_indexes.p1 = p1;
-        battle.last_selected_indexes.p2 = p2;
-        return battle;
     }
 };
 
@@ -211,16 +206,19 @@ pub const Pokemon = struct {
     }
 };
 
-// cat src/test/showdown/blocklist.json | jq '."1".moves'
+// TODO: uncomment once integration tests pass
+// fn blocked(m: Move) bool {
+//     // Binding moves are borked but only via Mirror Move / Metronome which are already blocked
+//     return switch (m) {
+//         .Mimic, .Metronome, .MirrorMove, .Transform => true,
+//         else => false,
+//     };
+// }
+
 fn blocked(m: Move) bool {
     if (Move.get(m).effect == .Binding) return true;
     return switch (m) {
-        .Counter,
-        .Mimic,
-        .Metronome,
-        .MirrorMove,
-        .Transform,
-        => true,
+        .Counter, .Mimic, .Bide, .Metronome, .MirrorMove, .Transform => true,
         else => false,
     };
 }