@pkmn/engine 0.1.0-dev.e5b5a998 → 0.1.0-dev.f918c3bd

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +53 -42
  2. package/build/pkg/addon.js +3 -2
  3. package/build/pkg/addon.js.map +1 -1
  4. package/build/pkg/data/layout.json +24 -2
  5. package/build/pkg/data/protocol.json +69 -12
  6. package/build/pkg/gen1.js +13 -16
  7. package/build/pkg/gen1.js.map +1 -1
  8. package/build/pkg/protocol.js +56 -37
  9. package/build/pkg/protocol.js.map +1 -1
  10. package/build.zig +82 -57
  11. package/package.json +33 -15
  12. package/src/bin/install-pkmn-engine +10 -5
  13. package/src/lib/binding/node.zig +46 -141
  14. package/src/lib/binding/wasm.zig +4 -2
  15. package/src/lib/common/battle.zig +17 -0
  16. package/src/lib/common/data.zig +15 -27
  17. package/src/lib/common/debug.zig +20 -11
  18. package/src/lib/common/js.zig +118 -0
  19. package/src/lib/common/optional.zig +60 -0
  20. package/src/lib/common/options.zig +9 -0
  21. package/src/lib/common/protocol.zig +643 -138
  22. package/src/lib/common/rational.zig +353 -0
  23. package/src/lib/common/rng.zig +15 -15
  24. package/src/lib/common/util.zig +12 -0
  25. package/src/lib/gen1/README.md +257 -177
  26. package/src/lib/gen1/calc.zig +426 -0
  27. package/src/lib/gen1/chance.zig +1058 -0
  28. package/src/lib/gen1/data/moves.zig +168 -170
  29. package/src/lib/gen1/data/types.zig +2 -2
  30. package/src/lib/gen1/data.zig +61 -51
  31. package/src/lib/gen1/helpers.zig +588 -17
  32. package/src/lib/gen1/mechanics.zig +776 -502
  33. package/src/lib/gen2/README.md +102 -83
  34. package/src/lib/gen2/data/items.zig +1 -1
  35. package/src/lib/gen2/data/moves.zig +634 -562
  36. package/src/lib/gen2/data/types.zig +1 -1
  37. package/src/lib/gen2/data.zig +100 -67
  38. package/src/lib/gen2/helpers.zig +15 -21
  39. package/src/lib/gen2/mechanics.zig +1147 -11
  40. package/src/lib/pkmn.zig +61 -2
package/src/lib/gen1/README.md CHANGED
@@ -6,11 +6,13 @@ document](../../../docs/DESIGN.md). The Generation I engine is implemented and t
6
6
  following files:
7
7
 
8
8
  - [`data.zig`](data.zig) ([`data`](data)): contains definitions of all of the data structures used
9
- by the engine, described in detail [below](#data-structures)
9
+ to implement the core mechanics of the engine, described in detail [below](#data-structures)
10
+ - [`chance.zig`](chance.zig): TODO
11
+ - [`calc.zig`](calc.zig): TODO
10
12
  - [`helpers.zig`](helpers.zig): helpers used to construct complex data types with
11
13
  sensible defaults (internally used by tests and tools)
12
- - [`mechanics.zig`](mechanics.zig): code which manipulates the data structures in order to implement
13
- the mechanics of the game
14
+ - [`mechanics.zig`](mechanics.zig): code which manipulates the data structures to implement the
15
+ mechanics of the game
14
16
  - [`test.zig`](test.zig): unit tests for `mechanics.zig` (the code is also tested by [integration
15
17
  tests](../../../docs/TESTING.md) at a higher level)
16
18
 
@@ -28,70 +30,68 @@ list of additional reference [**resources**](#resources).
28
30
 
29
31
  The following information is required to simulate a Generation I Pokémon battle:
30
32
 
31
- | pkmn | Pokémon Red (pret) | Pokémon Showdown |
32
- | --------------------------------------- | ---------------------------------- | -------------------------------------- |
33
- | `battle.seed` | `Random{Add,Sub}` | `battle.seed` |
34
- | `battle.turn` | - | `battle.turn` |
35
- | `battle.last_damage` | `Damage` | `battle.lastDamage` |
36
- | `side.{active,pokemon}` | `PlayerMonNumber`/`BattleMon` | `side.active` |
37
- | `side.team` | `PartyMons` | `side.pokemon` |
38
- | `side.last_used_move` | `PlayerUsedMove` | `pokemon.lastMove` |
39
- | `side.last_selected_move` | `PlayerSelectedMove` | `side.lastSelectedMove` |
40
- | `battle.last_moves.{p1,p2}_index` | `PlayerMoveListIndex` | - |
41
- | `battle.last_moves.{p1,p2}_counterable` | - | `side.lastMove` |
42
- | `side.order` | - | `pokemon.position` |
43
- | `{pokemon,active}.moves` | `{party,battle}_struct.{Moves,PP}` | `pokemon.{baseMoveSlots,moveSlots}` |
44
- | `pokemon.hp` | `{party,battle}_struct.HP` | `pokemon.hp` |
45
- | `{pokemon,active}.status` | `{party,battle}_struct.Status` | `pokemon.status` |
46
- | `{pokemon,active}.level` | `PlayerMonUnmodifiedLevel` | `pokemon.level` |
47
- | `pokemon.species` | `party_struct.Species` | `pokemon.baseSpecies` |
48
- | `pokemon.stats` | `box_struct.Stats` | `pokemon.baseStoredStats` |
49
- | `active.stats` | `battle_struct.Stats` | `pokemon.modifiedStats` |
50
- | `volatiles.transform` | `PlayerMonUnmodified*` | `pokemon.storedStats` |
51
- | `active.species` | `battle_struct.Species` | `pokemon.species` |
52
- | `{pokemon,active}.types` | `{party,battle}_struct.Type` | `pokemon.types` |
53
- | `active.boosts` | `PlayerMon*Mod` | `pokemon.boosts` |
54
- | `active.volatiles` | `PlayerBattleStatus{1,2,3}` | `pokemon.volatiles` |
55
- | `volatiles.state` | `PlayerBideAccumulatedDamage` | `volatiles.bide.totalDamage` |
56
- | `volatiles.attacks` | `PlayerNumAttacksLeft` | `volatiles.{bide,lockedmove}.duration` |
57
- | `volatiles.confusion` | `PlayerConfusedCounter` | `volatiles.confusion.duration` |
58
- | `volatiles.toxic` | `PlayerToxicCounter` | `volatiles.residualdmg.counter` |
59
- | `volatiles.substitute` | `PlayerSubstituteHP` | `volatiles.substitute.hp` |
60
- | `volatiles.disabled_{move,duration}` | `PlayerDisabledMove{,Number}` | `volatiles.disable.{move,time}` |
61
-
62
- - Pokémon Showdown [does not implement the correct Generation I RNG](#rng) and as such its `seed` is
33
+ | pkmn | Pokémon Red (pret) | Pokémon Showdown |
34
+ | ------------------------------------ | ---------------------------------- | -------------------------------------- |
35
+ | `battle.seed` | `Random{Add,Sub}` | `battle.seed` |
36
+ | `battle.turn` | - | `battle.turn` |
37
+ | `battle.last_damage` | `Damage` | `battle.lastDamage` |
38
+ | `side.{active,pokemon}` | `PlayerMonNumber`/`BattleMon` | `side.active` |
39
+ | `side.team` | `PartyMons` | `side.pokemon` |
40
+ | `side.last_used_move` | `PlayerUsedMove` | `pokemon.lastMove` |
41
+ | `side.last_selected_move` | `PlayerSelectedMove` | `side.lastSelectedMove` |
42
+ | `battle.last_moves.index` | `PlayerMoveListIndex` | - |
43
+ | `battle.last_moves.counterable` | - | `side.lastMove` |
44
+ | `side.order` | - | `pokemon.position` |
45
+ | `{pokemon,active}.moves` | `{party,battle}_struct.{Moves,PP}` | `pokemon.{baseMoveSlots,moveSlots}` |
46
+ | `pokemon.hp` | `{party,battle}_struct.HP` | `pokemon.hp` |
47
+ | `{pokemon,active}.status` | `{party,battle}_struct.Status` | `pokemon.status` |
48
+ | `{pokemon,active}.level` | `PlayerMonUnmodifiedLevel` | `pokemon.level` |
49
+ | `pokemon.species` | `party_struct.Species` | `pokemon.baseSpecies` |
50
+ | `pokemon.stats` | `box_struct.Stats` | `pokemon.baseStoredStats` |
51
+ | `active.stats` | `battle_struct.Stats` | `pokemon.modifiedStats` |
52
+ | `volatiles.transform` | `PlayerMonUnmodified*` | `pokemon.storedStats` |
53
+ | `active.species` | `battle_struct.Species` | `pokemon.species` |
54
+ | `{pokemon,active}.types` | `{party,battle}_struct.Type` | `pokemon.types` |
55
+ | `active.boosts` | `PlayerMon*Mod` | `pokemon.boosts` |
56
+ | `active.volatiles` | `PlayerBattleStatus{1,2,3}` | `pokemon.volatiles` |
57
+ | `volatiles.state` | `PlayerBideAccumulatedDamage` | `volatiles.bide.totalDamage` |
58
+ | `volatiles.attacks` | `PlayerNumAttacksLeft` | `volatiles.{bide,lockedmove}.duration` |
59
+ | `volatiles.confusion` | `PlayerConfusedCounter` | `volatiles.confusion.duration` |
60
+ | `volatiles.toxic` | `PlayerToxicCounter` | `volatiles.residualdmg.counter` |
61
+ | `volatiles.substitute` | `PlayerSubstituteHP` | `volatiles.substitute.hp` |
62
+ | `volatiles.disabled_{move,duration}` | `PlayerDisabledMove{,Number}` | `volatiles.disable.{move,time}` |
63
+
64
+ - Pokémon Showdown [doesn't implement the correct Generation I RNG](#rng) and as such its `seed` is
63
65
  different
64
- - `battle.turn` only needs to be tracked in order to be compatible with the Pokémon Showdown
65
- protocol
66
+ - `battle.turn` only needs to be tracked to be compatible with the Pokémon Showdown protocol
66
67
  - Pokémon Showdown tracks several last used move variables (`Battle.lastMove`, `Side.lastMove`, and
67
68
  `Pokemon.lastMove`), none of which accurately match the `PlayerUsedMove` variable from the
68
- cartridge (`Side.lastMove` should be what is used, but is used by Pokémon Showdown only for
69
- Counter and is not set and cleared in the correct locations. `Pokemon.lastMove` matches
70
- `PlayerUsedMove` more often so is what the engine attempts to model, despite the implications for
71
- Counter)
72
- - `battle.last_moves` doesn't map precisely to cartridge concepts because it is used to track desyncs
73
- which instead are represented on the cartridge as discrepancies between the two separate battle states
74
- that exist in the link battle.
75
- - Pokémon Showdown does not implement the [partial-trapping move Mirror Move
69
+ cartridge (`Side.lastMove` should be what's used, but is used by Pokémon Showdown only for Counter
70
+ and isn't set and cleared in the correct locations. `Pokemon.lastMove` matches `PlayerUsedMove`
71
+ more often so is what the engine attempts to model, despite the implications for Counter)
72
+ - `battle.last_moves` doesn't map precisely to cartridge concepts because it's used to track desyncs
73
+ which instead are represented on the cartridge as discrepancies between the two separate battle
74
+ states that exist in the link battle.
75
+ - Pokémon Showdown doesn't implement the [partial-trapping move Mirror Move
76
76
  glitch](https://glitchcity.wiki/Partial_trapping_move_Mirror_Move_link_battle_glitch) and as such
77
- does not need to keep track of a player's last selected move index (`PlayerMoveListIndex`)
77
+ doesn't need to keep track of a player's last selected move index (`PlayerMoveListIndex`)
78
78
  - Battle results (win, lose, draw) and request states are communicated via the return value of
79
79
  `Battle.update`
80
- - Nicknames (`BattleMonNick`/`pokemon.name`) are not handled by the pkmn engine as they are expected
80
+ - Nicknames (`BattleMonNick`/`pokemon.name`) aren't handled by the pkmn engine as they're expected
81
81
  to be handled by driver code if required
82
82
  - Pokémon Red's `LastSwitchInEnemyMonHP`, `InHandlePlayerMonFainted`, `PlayerNumHits`,
83
83
  `PlayerMonMinimized`, and `Move{DidntMiss,Missed}` are relevant for messaging/UI only
84
84
  - Pokémon Red's `TransformedEnemyMonOriginalDVs` is only relevant for the [Transform DV manipulation
85
85
  glitch](https://pkmn.cc/bulba/Transform_glitches#Transform_DV_manipulation_glitch)
86
- - Pokémon Red's `PlayerMove*` tracks information that is stored in the `Move` class
86
+ - Pokémon Red's `PlayerMove*` tracks information that's stored in the `Move` class
87
87
  - Pokémon Red's `PlayerStatsToDouble`/`PlayerStatsToHalve` are constants which are always 0
88
- - pkmn does not store the DVs/stat experience of Pokémon as they are expected to already be
89
- accounted for in the `Pokemon` `stats` and never need to be referenced in-battle (though a `DVs`
90
- struct exists to simplify generating legal test data)
88
+ - pkmn doesn't store the DVs/stat experience of Pokémon as they're expected to already be accounted
89
+ for in the `Pokemon` `stats` and never need to be referenced in-battle (though a `DVs` struct
90
+ exists to simplify generating legal test data)
91
91
  - Instead of storing unmodified stats like Pokémon Red or Pokémon Showdown, pkmn simply tracks the
92
92
  identity of the Pokémon that has been transformed into in the `active.volatiles.transform` field
93
93
  - pkmn uses `volatiles.state` for total accumulated damage for Bide but also for implementing
94
- accuracy overwrite mechanics for certain moves (this glitch is present on the device but is not
94
+ accuracy overwrite mechanics for certain moves (this glitch is present on the device but isn't
95
95
  correctly implemented by Pokémon Showdown currently)
96
96
 
97
97
  ### `Battle` / `Side`
@@ -103,13 +103,13 @@ store general information about the battle. Unlike in Pokémon Showdown there is
103
103
  between the data structure for the "active" Pokémon and its party members (see below).
104
104
 
105
105
  Due to layout constraints, details about the last moves for a side are stored in what would
106
- otherwise be the padding bytes of`Battle` (the `last_moves` field) instead of in `Side`.
106
+ otherwise be the padding bytes of `Battle` (the `last_moves` field) instead of in `Side`.
107
107
 
108
108
  ### `Pokemon` / `ActivePokemon`
109
109
 
110
- Similar to the cartridge, in order to save space different information is stored depending on
111
- whether a [Pokémon](https://pkmn.cc/bulba/Pok%c3%a9mon_data_structure_%28Generation_I%29) is
112
- actively participating in battle vs. is switched out (pret's [`battle_struct` vs.
110
+ Similar to the cartridge, to save space different information is stored depending on whether a
111
+ [Pokémon](https://pkmn.cc/bulba/Pok%c3%a9mon_data_structure_%28Generation_I%29) is actively
112
+ participating in battle vs. is switched out (pret's [`battle_struct` vs.
113
113
  `party_struct`](https://pkmn.cc/pokered/macros/ram.asm)). In Pokémon Showdown, all the Pokémon in a
114
114
  battle are represented by the same
115
115
  [`Pokemon`](https://github.com/smogon/pokemon-showdown/blob/master/sim/pokemon.ts) class, and static
@@ -121,14 +121,14 @@ A `MoveSlot` is a data-type for a `(move, current pp)` pair. A pared down versio
121
121
  Showdown's `Pokemon.moveSlot`, it also stores data from the cartridge's `battle_struct::Move` macro
122
122
  and can be used to replace the `PlayerMove*` data. Move PP is stored as a full byte instead of how
123
123
  the cartridge (`battle_struct::PP`) stores it (6 bits for current PP and the remaining 2 bits used
124
- to store the number of applied PP Ups). PP Up bits do not actually need to be stored on move slot
124
+ to store the number of applied PP Ups). PP Up bits don't actually need to be stored on move slot
125
125
  as max PP is never relevant in Generation I.
126
126
 
127
127
  #### `Status`
128
128
 
129
129
  Bitfield representation of a Pokémon's major [status
130
- condition](https://pkmn.cc/bulba/Status_condition), mirroring how it is stored on the cartridge. A
131
- value of `0x00` means that the Pokémon is not affected by any major status, otherwise the lower 3
130
+ condition](https://pkmn.cc/bulba/Status_condition), mirroring how it's stored on the cartridge. A
131
+ value of `0x00` means that the Pokémon isn't affected by any major status, otherwise the lower 3
132
132
  bits represent the remaining duration for Sleep. Other status are denoted by the presence of
133
133
  individual bits - at most one status should be set at any given time.
134
134
 
@@ -137,10 +137,10 @@ below), so the upper most bit of `Status` is instead used to track state require
137
137
  quirks:
138
138
 
139
139
  - when combined with a valid sleep duration (or 0), it indicates that the `SLP` status was
140
- self-inflicted (required in order to implement Pokémon Showdown's "Sleep Clause Mod")
140
+ self-inflicted (required to implement Pokémon Showdown's "Sleep Clause Mod")
141
141
  - when combined with `PSN` it indicates that the Pokémon is actually badly poisoned (required in
142
142
  order to send the same incorrect protocol messages as Pokémon Showdown - the Toxic volatile
143
- alone is not sufficient in compatibility mode because it gets lost on switch)
143
+ alone isn't sufficient in compatibility mode because it gets lost on switch)
144
144
 
145
145
  #### `Volatiles`
146
146
 
@@ -176,17 +176,16 @@ boolean flags that are cleared when the Pokémon faints or switches out:
176
176
  [Toxic](https://pkmn.cc/bulba/Toxic_(move)) (counter),
177
177
  [Transform](https://pkmn.cc/bulba/Transform_(move)) (identity), and
178
178
  [Disable](https://pkmn.cc/bulba/Disable_(move)) (move and duration), and multi-hit attacks all
179
- require additional information that is also stored in the `Volatiles` structure. `MultiHit` is not
180
- strictly required to be stored as it should always be 0 after updates barring errors, however it is
179
+ require additional information that's also stored in the `Volatiles` structure. `MultiHit` isn't
180
+ strictly required to be stored as it should always be 0 after updates barring errors, however it's
181
181
  convenient to maintain as it maps neatly to the cartridge and is effectively "free" space-wise due
182
182
  to padding.
183
183
 
184
184
  The `state` field of `Volatiles` is effectively treated as a union:
185
185
 
186
186
  - if `volatiles.Bide` is set, `volatiles.data.state` reflects the total accumulated Bide damage
187
- - otherwise, `volatiles.data.state` reflects the last computed move accuracy (required in order to
188
- implement the [Rage and Thrash / Petal Dance accuracy
189
- bug](https://www.youtube.com/watch?v=NC5gbJeExbs))
187
+ - otherwise, `volatiles.data.state` reflects the last computed move accuracy (required to implement
188
+ the [Rage and Thrash / Petal Dance accuracy bug](https://www.youtube.com/watch?v=NC5gbJeExbs))
190
189
 
191
190
  #### `Stats` / `Boosts`
192
191
 
@@ -198,8 +197,8 @@ boosts should always range from `-6`...`6` instead of `1`...`13` as on the cartr
198
197
 
199
198
  `Move` serves as an identifier for a unique [Pokémon move](https://pkmn.cc/bulba/Move) that can be
200
199
  used to retrieve `Move.Data` with information regarding base power, accuracy, and type. As covered
201
- above, PP information isn't strictly necessary in Generation I so is dropped. `Move.None` exists as
202
- a special sentinel value to indicate `null`. Move PP data is only included for testing and is not
200
+ earlier, PP information isn't strictly necessary in Generation I so is dropped. `Move.None` exists
201
+ as a special sentinel value to indicate `null`. Move PP data is only included for testing and isn't
203
202
  necessary for the actual engine implementation.
204
203
 
205
204
  In order to workaround various [Pokémon Showdown bugs](#bugs) and to support its protocol in logs,
@@ -221,11 +220,11 @@ places to determine which protocol messages to print.
221
220
  ### `Species` / `Species.Data`
222
221
 
223
222
  `Species` just serves as an identifier for a unique [Pokémon
224
- species](https://pkmn.cc/bulba/Pokémon_species_data_structure_(Generation_I)) as the base stats
225
- of a species are already accounted for in the computed stats in the `Pokemon` structure and nothing
226
- in battle requires these to be recomputed. Similarly, Type is unnecessary to include as it is also
223
+ species](https://pkmn.cc/bulba/Pokémon_species_data_structure_(Generation_I)) as the base stats of a
224
+ species are already accounted for in the computed stats in the `Pokemon` structure and nothing in
225
+ battle requires these to be recomputed. Similarly, Type is unnecessary to include as it's also
227
226
  already present in the `Pokemon` struct. `Species.None` exists as a special sentinel value to
228
- indicate `null`. `Species.Data` is only included for testing and is not necessary for the actual
227
+ indicate `null`. `Species.Data` is only included for testing and isn't necessary for the actual
229
228
  engine implementation, outside of `Species.CHANCES` which is required as the base speed / 2 of the
230
229
  species is necessary for computing critical hit probability.
231
230
 
@@ -238,19 +237,27 @@ effectiveness - like the cartridge, effectiveness is stored as `0`, `5`, `10`, a
238
237
  (technically only a 2-bit value is required, but as with `Types` Zig only allows a minimum of a byte
239
238
  to be stored at each address of an array).
240
239
 
241
- The 'precedence' of the various type matchups matters beyond just the [dual-type damage
240
+ The 'precedence' of the various type match-ups matters beyond just the [dual-type damage
242
241
  misinformation
243
242
  glitch](https://pkmn.cc/bulba/List_of_glitches_(Generation_I)#Dual-type_damage_misinformation) -
244
243
  type effectiveness modifiers are applied based on the (haphazard) ordering of the effectiveness
245
244
  table as opposed to first applying modifiers for a species's first type and then second type. The
246
- engine maintains a `Type.PRECEDENCE` table with just the matchups that are relevant in game (certain
247
- type combinations cannot crop up with the limited Generation I species pool and as such are pruned
248
- for efficiency) and only looks up precedence when necessary to minimize expensive searches. Pokémon
249
- Showdown does not implement type precedence.
245
+ engine maintains a `Type.PRECEDENCE` table with just the match-ups that are relevant in game
246
+ (certain type combinations can't crop up with the limited Generation I species pool and as such are
247
+ pruned for efficiency) and only looks up precedence when necessary to minimize expensive searches.
248
+ Pokémon Showdown doesn't implement type precedence.
249
+
250
+ ### `Chance` / `Actions` / `Action` / `Durations` / `Duration`
251
+
252
+ TODO
253
+
254
+ ### `Calc` / `Overrides` / `Summaries` / `Summary`
255
+
256
+ TODO
250
257
 
251
258
  ## Information
252
259
 
253
- The information of each field (in terms of [bits of
260
+ The information of each field required for mechanics (in terms of [bits of
254
261
  entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory))) is as follows:
255
262
 
256
263
  | Data | Range | Bits | | Data | Range | Bits |
@@ -272,8 +279,8 @@ entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory))) is as foll
272
279
  | **crit chance** | 7..65 | 6 | | **transform** | 0..15 | 4 |
273
280
  | **target** | 0..4 | 3 | | | | |
274
281
 
275
- From this we can determine the minimum bits[^1] required to store each data structure to determine
276
- how much overhead the representations above have after taking into consideration [alignment &
282
+ From this one can determine the minimum bits[^1] required to store each data structure to determine
283
+ how much overhead the preceding representations have after taking into consideration [alignment &
277
284
  padding](https://en.wikipedia.org/wiki/Data_structure_alignment) and
278
285
  [denormalization](https://en.wikipedia.org/wiki/Denormalization):
279
286
 
@@ -286,9 +293,9 @@ padding](https://en.wikipedia.org/wiki/Data_structure_alignment) and
286
293
  - the active Pokémon's level and current and max HP can always be referred to the `Pokemon`
287
294
  struct
288
295
  - **`Side`**: `ActivePokemon` + 6× `Pokemon` + active (`3`) + last used (`8`) + last selected
289
- (`8`)
290
- - `order` does not need to be stored as the party can always be rearranged as switches occur
291
- - **`Battle`**: 6× `Side` + seed (10× `8` + `4`) + turn (`10`) + last damage (`10`)
296
+ (`8`) + counterable (`1`) + last move index (`3`)
297
+ - `order` doesn't need to be stored as the party can always be rearranged as switches occur
298
+ - **`Battle`**: 6× `Side` + seed (9× `8` + `4`) + turn (`10`) + last damage (`10`)
292
299
  - **`Type.CHART`**: attacking types (`15`) × defending types (`15`) × effectiveness (`2`)[^2]
293
300
  - **`Type.PRECEDENCE`**: 29× attacking type (`4`) + defending type (`4`) pairs
294
301
  - **`Moves.DATA`**: 165× base power (`6`) + effect (`7`) + accuracy (`4`) + type (`4`) + target
@@ -299,8 +306,8 @@ padding](https://en.wikipedia.org/wiki/Data_structure_alignment) and
299
306
  | ----------------- | ----------- | ------------ | -------- |
300
307
  | `Pokemon` | 192 | 147 | 30.6% |
301
308
  | `ActivePokemon` | 256 | 202 | 26.7% |
302
- | `Side` | 1472 | 1056 | 33.5% |
303
- | `Battle` | 3088 | 2216 | 33.7% |
309
+ | `Side` | 1472 | 1107 | 33.0% |
310
+ | `Battle` | 3088 | 2310 | 33.7% |
304
311
  | `Type.CHART` | 1800 | 450 | 300.0% |
305
312
  | `Type.PRECEDENCE` | 232 | 232 | 0.0% |
306
313
  | `Moves.DATA` | 5280 | 3960 | 33.3% |
@@ -313,25 +320,25 @@ consideration the worst case all Pokémon types are required and 48 moves. The `
313
320
  could be eliminated and instead the `Move` data actually required by each `Pokemon` could be placed
314
321
  beside the `MoveSlot`, though this is both less general and adds unnecessary complexity.
315
322
 
316
- [^1]: For data with lower cardinality it is possible to save memory by ordinalizing the values and
323
+ [^1]: For data with lower cardinality it's possible to save memory by ordinalizing the values and
317
324
  turning them into indices into a lookup table (e.g. encode all possible move base powers in a lookup
318
325
  table and store the index into that table instead of the actual base power). While this approach may
319
326
  minimize the absolute memory used, performance is more likely to suffer as the goal is to minimize
320
- uncached memory lookups, not total memory usage.
327
+ un-cached memory lookups, not total memory usage.
321
328
 
322
329
  [^2]: Instead of storing as a sparse multi-dimensional array the type chart could instead only
323
330
  [store values which are not normal
324
331
  effectiveness](https://github.com/pret/pokered/blob/master/data/types/type_matchups.asm) in 820 bits
325
332
  as 82× attacking type (`4`) + defending type (`4`) + non-Normal effectiveness (`2`). This would
326
333
  avoid having to do two memory lookups at the cost of a longer time scanning, but the second lookup
327
- should already be fast due to locality of reference meaning it will likely already be in the cache.
334
+ should already be fast due to locality of reference meaning it's likely to already be in the cache.
328
335
  This approach would also render `Type.PRECEDENCE` unnecessary.
329
336
 
330
337
  ## Layout
331
338
 
332
339
  The precise layout of the engine's data structures is important to those implementing driver code,
333
340
  as clients must directly probe the engine's state through these structures (i.e. the pkmn engine
334
- does not produce an equivalent to Pokémon Showdown's `|request|` protocol message, this information
341
+ doesn't produce an equivalent to Pokémon Showdown's `|request|` protocol message, this information
335
342
  must be gleaned through the `Battle` state). Useful size and offset information can be found in
336
343
  the [`layout.json`](../../data/layout.json) which exists to simplify writing driver code.
337
344
 
@@ -342,14 +349,14 @@ data in the browser for ease of debugging.
342
349
 
343
350
  ### `Battle`
344
351
 
345
- | Start | End | Data | Description |
346
- | ------- | ------- | ------------------- | ------------------------------------------------------- |
347
- | 0 | 184 | [`sides[0]`](#side) | Player 1's side |
348
- | 184 | 368 | [`sides[1]`](#side) | Player 2's side |
349
- | 368 | 370 | `turn` | The current turn number |
350
- | 370 | 372 | `last_damage` | The last damage dealt by either side |
351
- | 372 | 373-376 | `last_moves` | The slot index of the last selected moves for each side |
352
- | 373-376 | 384 | `rng` | The RNG state |
352
+ | Start | End | Data | Description |
353
+ | ------- | ------- | ------------------- | ------------------------------------------------------ |
354
+ | 0 | 184 | [`sides[0]`](#side) | Player 1's side |
355
+ | 184 | 368 | [`sides[1]`](#side) | Player 2's side |
356
+ | 368 | 370 | `turn` | The current turn number |
357
+ | 370 | 372 | `last_damage` | The last damage dealt by either side |
358
+ | 372 | 374-376 | `last_moves` | Details about the last move selected/used by each side |
359
+ | 374-376 | 384 | `rng` | The RNG state |
353
360
 
354
361
  - the current `turn` is 2 bytes, written in native-endianness
355
362
  - `last_moves` layout depends on whether or not Pokémon Showdown compatibility mode is enabled
@@ -359,13 +366,13 @@ data in the browser for ease of debugging.
359
366
  - if `showdown` is enabled byte 372 is used to store the last selected move index of `side[0]` and
360
367
  byte 373 is used to store whether or not the side's last executed move would have been considered
361
368
  "counterable"; and bytes 374 and 375 store the same information for `side[1]`
362
- - otherwise the first 3 bits of byte 372 stores the last selected move index of `side[0]` and the
363
- next bit stores whether that side's last executed move would have been considered "counterable",
364
- with the same information for `side[1]`'s being stored in the second 4 bits
369
+ - otherwise the first 4 bits of byte 372 stores the last selected move index of `side[0]` and the
370
+ next 4 bits store whether that side's last executed move would have been considered
371
+ "counterable", with the same information for `side[1]`'s being stored in the second byte
365
372
  - the `rng` depends on whether or not Pokémon Showdown compatibility mode is enabled (`-Dshowdown`):
366
373
  - if `showdown` is enabled, the RNG state begins on byte 376 and consists of a 64-bit seed,
367
374
  written in native-endianness
368
- - otherwise the RNG state begins on byte 373 and consists of the 10 bytes of the seed followed by
375
+ - otherwise the RNG state begins on byte 374 and consists of the 9 bytes of the seed followed by
369
376
  the index pointing to which byte of the seed is currently being used
370
377
 
371
378
  ### `Side`
@@ -384,9 +391,9 @@ data in the browser for ease of debugging.
384
391
  | 183 | 184 | `last_used_move` | The last move the player used |
385
392
 
386
393
  - `order` is a 6 byte array where `order[i]` represents the "slot" of `pokemon[i]`, where the slot
387
- is usually a unique value from 1-6 but can be 0 in situations where a player brings less than six
394
+ is usually a unique value from 1 to 6 but can be 0 in situations where a player brings less than six
388
395
  Pokémon to battle (note however that if `order[i]` is 0 than for all j > 0 `order[i+j]` **must**
389
- equal 0).
396
+ equal 0)
390
397
 
391
398
  ### `ActivePokemon`
392
399
 
@@ -411,7 +418,7 @@ data in the browser for ease of debugging.
411
418
  | 28 | 29 | `moves[2].id` | The active Pokémon's third move |
412
419
  | 29 | 30 | `moves[2].pp` | The PP of the active Pokémon's third move |
413
420
  | 30 | 31 | `moves[3].id` | The active Pokémon's fourth move |
414
- | 31 | 32 | `moves[3].pp` | The PP of the active Pokémon's fourth moe |
421
+ | 31 | 32 | `moves[3].pp` | The PP of the active Pokémon's fourth move |
415
422
 
416
423
  - the active Pokémon's `stats.hp` is always identical to the corresponding stored Pokémon's `stats.hp`
417
424
  - `boosts` and `types` includes bytes which store two 4-bit fields each
@@ -446,7 +453,7 @@ data in the browser for ease of debugging.
446
453
  | 40 | 48 | `substitute` | The remaining HP of the Substitute |
447
454
  | 48 | 52 | `transform` | The identity of whom the active Pokémon is transformed into |
448
455
  | 52 | 56 | `disabled_duration` | The remaining turns the move is disabled |
449
- | 56 | 59 | `disabled_move` | The move slot (1-4) that is disabled |
456
+ | 56 | 59 | `disabled_move` | The move slot (1-4) that's disabled |
450
457
  | 59 | 64 | `toxic` | The number of turns toxic damage has been accumulating |
451
458
 
452
459
  ### `Pokemon`
@@ -472,6 +479,76 @@ data in the browser for ease of debugging.
472
479
  | 22 | 23 | `type1`/`type2` | The Pokémon's stored types |
473
480
  | 23 | 24 | `level` | The Pokémon's level |
474
481
 
482
+
483
+ ### `Action`
484
+
485
+ `Actions` consist of an `Action` for Player 1 followed by an `Action` for Player 2.
486
+
487
+ > **NOTE:** The offsets in the following table represent *bits* and **not** bytes.
488
+
489
+ | Start | End | Data | Description |
490
+ | ----- | --- | ------------------------ | ------------------------------------------------------------------------------- |
491
+ | 0 | 8 | `damage` | The roll to be returned damage (217-255). |
492
+ | 8 | 10 | `hit` | The roll to be returned for accuracy (1 for miss, 2 for hit). |
493
+ | 10 | 12 | `critical_hit` | The roll to be returned for critical hits (1 for no, 2 for yes). |
494
+ | 12 | 14 | `secondary_chance` | The roll to be returned for secondary chance rolls (1 for no-proc, 2 for proc). |
495
+ | 14 | 16 | `speed_tie` | The player to return for speed ties (1 for Player 1, 2 for Player 2). |
496
+ | 16 | 18 | `confused` | The roll to be returned for confusion self-hits (1 for no-proc, 2 for proc). |
497
+ | 18 | 20 | `paralyzed` | The roll to be returned for full paralysis (1 for no-proc, 2 for proc). |
498
+ | 20 | 24 | `duration` | The roll to be returned for the duration (including for binding moves). |
499
+ | 24 | 40 | [`durations`](#duration) | Values of various durations. |
500
+ | 40 | 44 | `move_slot` | The roll to be returned for the move slot (1-4, invalid values ignored). |
501
+ | 44 | 48 | `move_slot` | The roll to be returned for a multi-hit move distribution (2-5). |
502
+ | 48 | 56 | `psywave` | One greater than the roll to be returned for Psywave damage. |
503
+ | 56 | 64 | `metronome` | The move to return for Metronome. |
504
+
505
+ - for any field a value of 0 is considered to be unset
506
+ - **both Player 1 and Player 2 must set the same value for `speed_tie`.**
507
+ - `duration` determines the roll for any effect which lasts over multiple turns, whereas `durations` can either be used to
508
+ track how long these effects have lasted (for the purposes of computing probablities with `-Dchance`) or can be used to
509
+ [override](#overrides) (extend or end) the duration of specfic effects with `-Dcalc`.
510
+
511
+ #### `Duration`
512
+
513
+ > **NOTE:** The offsets in the following table represent *bits* and **not** bytes.
514
+
515
+ | Start | End | Data |
516
+ | ----- | --- | ----------- |
517
+ | 0 | 3 | `sleep` |
518
+ | 3 | 6 | `confusion` |
519
+ | 4 | 10 | `disable` |
520
+ | 10 | 13 | `attacking` |
521
+ | 13 | 16 | `binding` |
522
+
523
+ - the meaning of each field depends on the context in which `Duration` appears:
524
+ - within `Chance` `actions`, the durations tracked refer to the number of turns a Pokémon has been
525
+ observed to be under an effect
526
+ - within `Overrides` `actions`, the durations refer to the value the next `Chance` `actions`
527
+ should be made to take on
528
+ - within `Overrides` `durations`, the durations serve as a mask to determine to whether or not the
529
+ durations in `Overrides` `actions` should be considered to be set or not
530
+ ◊
531
+ ### `Overrides`
532
+
533
+ | Start | End | Data | Description |
534
+ | ----- | --- | --------------------------- | ------------------------------------------------------------------------------------- |
535
+ | 0 | 8 | [`action.p1`](#action) | Rolls to force Player 1's RNG to return for specific events. |
536
+ | 8 | 16 | [`action.p2`](#action) | Rolls to force Player 2's RNG to return for specific events. |
537
+ | 16 | 18 | [`durations.p1`](#duration) | Whether or not to modify Player 1's effect durations to match `actions.p1.durations`. |
538
+ | 18 | 20 | [`durations.p2`](#duration) | Whether or not to modify Player 2's effect durations to match `actions.p1.durations`. |
539
+ | 20 | 24 | - | *Zero padding* |
540
+
541
+ ### `Summaries`
542
+
543
+ | Start | End | Data | Description |
544
+ | ----- | --- | ------------------ | ------------------------------------------------------------------------------- |
545
+ | 0 | 2 | `p1.damage.base` | Player 1's base computed damage before the damage roll is applied. |
546
+ | 2 | 4 | `p1.damage.final` | Player 1's final computed damage that gets applied to the Pokémon. |
547
+ | 4 | 6 | `p1.damage.capped` | Whether higher damage from Player 1 will saturate / result in the same outcome. |
548
+ | 6 | 8 | `p2.damage.base` | Player 2's base computed damage before the damage roll is applied. |
549
+ | 8 | 10 | `p2.damage.final` | Player 2's final computed damage that gets applied to the Pokémon. |
550
+ | 10 | 12 | `p2.damage.capped` | Whether higher damage from Player 2 will saturate / result in the same outcome. |
551
+
475
552
  ## Bugs
476
553
 
477
554
  In addition to its alternative [RNG semantics](#rng), Pokémon Showdown's implementation of the first
@@ -480,31 +557,31 @@ Smogon](https://www.smogon.com/forums/posts/5933177/show):
480
557
 
481
558
  - moves on Pokémon Showdown can do 0 damage instead of failing or causing a [division-by-zero
482
559
  freeze](https://pkmn.cc/bulba-glitch-1#Division_by_0).
483
- - Pokémon Showdown does not implement type effectiveness precedence correctly.
560
+ - Pokémon Showdown doesn't implement type effectiveness precedence correctly.
484
561
  - Pokémon Showdown checks for type and OHKO immunity before accuracy.
485
562
  - Confusion self-hits use the wrong damage formula resulting in off-by-one errors (and also fail to
486
- account for an opponent's Reflect). Furthermore, the confusion self-hit damage will erroneously be
487
- inflicted to the confused user's substitute if the confused user had been attempting to use a
563
+ account for an opponent's Reflect). Furthermore, the confusion self-hit damage erroneously gets
564
+ inflicted on the confused user's substitute if the confused user had been attempting to use a
488
565
  self-targeting move. Finally, Pokémon Showdown erroneously considers the *uncapped* self-hit
489
566
  damage for the purposes of tracking the battle's last damage.
490
567
 
491
- Beyond the general bugs listed above, several move effects are implemented incorrectly by Pokémon
492
- Showdown. Some of these moves are [too fundamentally broken to be implemented](#unimplementable) by
493
- the pkmn engine, but the following moves have their broken behavior preserved in `-Dshowdown` mode:
568
+ Beyond these general bugs, several move effects are implemented incorrectly by Pokémon Showdown.
569
+ Some of these moves are [too fundamentally broken to be implemented](#unimplementable) by the pkmn
570
+ engine, but the following moves have their broken behavior preserved in `-Dshowdown` mode:
494
571
 
495
572
  - **Bide**: Bide's damage can overflow if OHKO moves are involved because OHKO moves work by setting
496
573
  the damage to 65535 - Pokémon Showdown doesn't implement this overflow and instead lets Bide's
497
574
  damage grow unbounded. Additionally, if the opponent faints after Bide inflicts damage on Pokémon
498
575
  Showdown residual damage incorrectly still gets applied to Bide's user.
499
- - **Counter**: On Pokémon Showdown choices made while sleeping (which should not have been
576
+ - **Counter**: On Pokémon Showdown choices made while sleeping (which shouldn't have been
500
577
  registered) can erroneously cause Counter to trigger Desync Clause Mod behavior. Additionally,
501
578
  because Pokémon Showdown neglects to zero the last battle damage if a move misses due to immunity
502
- or invulnerability Counter will occasionally work on Pokémon Showdown when it should fail.
579
+ or invulnerability Counter occasionally works on Pokémon Showdown when it should fail.
503
580
  - **Leech Seed**: Leech Seed fails to heal its source side if a seeded target faints due to
504
581
  recoil/crash damage on Pokémon Showdown.
505
582
  - **Pay Day**: Pay Day should still scatter coins if it hits (but doesn't break) and opponent's
506
583
  Substitute but doesn't on Pokémon Showdown.
507
- - **Flinch**: Flinching does not get cleared during move selection on Pokémon Showdown and is
584
+ - **Flinch**: Flinching doesn't get cleared during move selection on Pokémon Showdown and is
508
585
  instead cleared in Pokémon Showdown's "residual" phase, meaning the flinch status gets erroneously
509
586
  preserved across fainting (as fainting triggers Pokémon Showdown's "instaswitch" behavior which
510
587
  skips end-of-turn residuals).
@@ -515,48 +592,50 @@ the pkmn engine, but the following moves have their broken behavior preserved in
515
592
  Petal Dance accuracy bug]( https://www.youtube.com/watch?v=NC5gbJeExbs) incorrectly, as the
516
593
  accuracy only gets written when the volatile is present which can lead to incorrect accuracy
517
594
  values on turns where Rage is used on the same turn as a move which modifies accuracy or evasion.
518
- - **Thrash** / **Petal Dance**: once a Pokémon is locked into a thrashing move they will lose all
519
- speed ties on Pokémon Showdown (due to the fact that if they win the speed tie their action will
520
- then get "changed" and inserted back into the queue after their opponent's action). Pokémon
521
- Showdown also implements accuracy incorrectly, as covered above.
595
+ - **Thrash** / **Petal Dance**: once a Pokémon is locked into a thrashing move they lose all speed
596
+ ties on Pokémon Showdown (due to the fact that if they win the speed tie their action then gets
597
+ "changed" and inserted back into the queue after their opponent's action). Pokémon Showdown also
598
+ implements accuracy incorrectly, as covered earlier.
522
599
  - **Freeze** / **Sleep**: Pokémon Showdown requires a move to be selected when a Pokémon is frozen
523
600
  or sleeping and uses that in the event that the status is removed while on the cartridge no
524
601
  selection is possible and no turn exists for the thawed/woken Pokémon to act except in the case of
525
602
  a Fire-type move thawing a slower Pokémon (which should result in the [Freeze top move selection
526
- glitch](https://glitchcity.wiki/Freeze_top_move_selection_glitch), which is not implemented and
603
+ glitch](https://glitchcity.wiki/Freeze_top_move_selection_glitch), which isn't implemented and
527
604
  would also likely be incorrect if it were to be implemented due to how Pokémon Showdown
528
605
  incorrectly saves arbitrary moves with its choice selection semantics). Furthermore, thrashing
529
- volatiles should not be cleared if the user misses a turn due to freeze / sleep.
606
+ volatiles shouldn't be cleared if the user misses a turn due to freeze / sleep.
530
607
  - **Hyper Beam**: due to improperly implemented selection mechanics, the [Hyper Beam
531
608
  automatic-selection glitch](https://glitchcity.wiki/Hyper_Beam_automatic_selection_glitch) does
532
609
  not exist on Pokémon Showdown. Additionally, Hyper Beam being able to cause [Freeze permanent
533
- helplessness](https://pkmn.cc/bulba-glitch-1#Hyper_Beam_.2B_Freeze_permanent_helplessness) is not
610
+ helplessness](https://pkmn.cc/bulba-glitch-1#Hyper_Beam_.2B_Freeze_permanent_helplessness) isn't
534
611
  implement by Pokémon Showdown.
535
612
  - **Roar** / **Whirlwind**: these moves can miss on Pokémon Showdown (and advance the RNG when
536
- checking) which is incorrect (these moves should always fail, but do not check accuracy or advance
613
+ checking) which is incorrect (these moves should always fail, but don't check accuracy or advance
537
614
  the RNG). More importantly, these moves should *not* cause the tracked last battle damage to be
538
- zeroed, but on Pokémon Showdown they do.
615
+ zeroed, but on Pokémon Showdown they do. These should also `|-fail|...|[still]` instead of doing
616
+ nothing.
539
617
  - **Substitute**: in addition to the [Substitute + Confusion
540
618
  glitch](https://pkmn.cc/bulba-glitch-1#Substitute_.2B_Confusion_glitch) not being implemented
541
- correctly (covered above), the [Substitute 1/4
619
+ correctly (covered earlier), the [Substitute 1/4
542
620
  glitch](https://glitchcity.wiki/Substitute_%C2%BC_HP_glitch) also fails in many cases due to
543
621
  Pokémon Showdown implementing the health check based on floating point division instead of integer
544
- divison like on the cartridge (meaning the Substitute 1/4 glitch will only occur if the Pokémon's
622
+ division like on the cartridge (meaning the Substitute 1/4 glitch only occurs if the Pokémon's
545
623
  maximum HP is evenly divisible by 4). Substitute also incorrectly blocks Dream Eater on
546
- Pokémon Showdown and will incorrectly still heal 1 HP for any draining moves if the attack does 0
624
+ Pokémon Showdown and incorrectly still heals 1 HP for any draining moves if the attack does 0
547
625
  damage. Finally, Pokémon Showdown uses a `subFainted` field to track whether a Substitute was
548
- broken in order to know when to nullify a move's effect, only it doesn't get cleared at the end of
626
+ broken to know when to nullify a move's effect, only it doesn't get cleared at the end of
549
627
  the turn and can result in incorrect behavior on subsequent turns with the moves Mirror Move and
550
628
  Metronome that invoke `runMove` (which is where `subFainted` gets cleared) on the user but skips
551
629
  calling it for the eventual true target.
552
630
 
553
631
  In addition to numerous cases where Pokémon Showdown uses the wrong type of message (e.g. `|-fail`
554
- vs. `|-miss|` vs. `|-immune|`, e.g. in the case of Leech Seed) which are not documented here, Pokémon
555
- Showdown sometimes gets message ordering incorrect (which does not effect the outcome
556
- of the battle, only pedantic UI correctness):
632
+ vs. `|-miss|` vs. `|-immune|`, e.g. in the case of Leech Seed) which aren't documented here, Pokémon
633
+ Showdown sometimes gets message ordering incorrect (which doesn't effect the outcome of the battle,
634
+ only pedantic UI correctness):
557
635
 
558
636
  - **Rage**: Rage should report the `|-boost|` before the Disable `|-miss|`, not after.
559
637
  - **Haze**: Haze clears the status/volatiles in an incorrect order.
638
+ - **Teleport**: Teleport should `|-fail|...|[still]` instead of doing nothing.
560
639
  - **Twineedle**: the `|-hitcount|` ("Hit 2 times") should come before the `|-status|` message, not
561
640
  after.
562
641
  - **Thrash** / **Petal Dance**: confusion should silently get applied before the `|move|` message,
@@ -566,21 +645,21 @@ Pokémon Showdown also implements a number of modifications to the cartridge (us
566
645
  called out in the `|rule|` section at the beginning of a battle's log):
567
646
 
568
647
  - **Sleep Clause Mod**: players are prevented from putting more than one of their opponent's Pokémon
569
- to sleep at a time (usage of the move will fail).
648
+ to sleep at a time (usage of the move fails).
570
649
  - **Freeze Clause Mod**: players are prevented from freezing more than one of their opponent's
571
- Pokémon at a time (usage of the move will fail).
572
- - **Desync Clause Mod**: If the usage of a move would cause a desync it instead causes a
573
- failure. However, this mod does not trigger for [**division by
650
+ Pokémon at a time (usage of the move fails).
651
+ - **Desync Clause Mod**: If the usage of a move would cause a desync it instead causes a failure.
652
+ However, this mod doesn't trigger for [**division by
574
653
  zero**](https://pkmn.cc/bulba/List_of_glitches_(Generation_I)#Division_by_0) - instead of failing,
575
654
  Pokémon Showdown silently patches the damage calculation to divide by 1 instead of 0. The
576
655
  definition of the Desync Clause Mod should be extended or the code should be changed to fail
577
656
  instead of succeeding in these cases.
578
657
  - **Endless Battle Clause**: Prematurely ends the battle in a tie after 1000 turns or in certain
579
- situations where it is trivially detectable that no progress can be made.
658
+ situations where it's trivially detectable that no progress can be made.
580
659
  - **Switch Priority Clause Mod**: When both player switch out their Pokémon at the same time the
581
660
  faster Pokémon switches first. This mod is **not broadcast at the start of the battle in the
582
- `|rule|` section** in Generation I (or II) as the actual order of switches here does not have
583
- competitive implications like it does in Generation III, but it is still contrary to how the games
661
+ `|rule|` section** in Generation I (or II) as the actual order of switches here doesn't have
662
+ competitive implications like it does in Generation III, but it's still contrary to how the games
584
663
  work where the [host (Player 1)'s Pokemon would switch
585
664
  first](https://www.smogon.com/forums/posts/5989318/show).
586
665
 
@@ -622,35 +701,35 @@ the correct control flow):
622
701
  Pokémon using Rage/Bide or Thrashing/Charging moves being incorrectly forced to skip a turn when
623
702
  the Pokémon using the Binding move switches.
624
703
  - **Mimic**: Pokémon Showdown checks that the user of Mimic has Mimic in one of their move slots,
625
- which means Mimic legally called via Metronome or Mirror Move will only work if the user also has
626
- Mimic (and the moved mimicked by Mimic called via Metronome / Mirror Move will erroneously
627
- override the Mimic move slot instead of the Metronome / Mirror Move move slot). Furthermore,
628
- because Pokémon Showdown deducts PP based on a move's name instead of slot, if Mimic copies a move
629
- the Pokémon already knows, PP deduction for using either the original move of the mimicked move
630
- will instead deduct PP for whichever appears at the lower move slot index and the PP will be
631
- allowed to go negative (effectively allowing for infinite PP use). Pokémon Showdown also doesn't
632
- deduct PP from using Transform if it was copied by Mimic.
633
- - **Mirror Move**: As covered above, both Substitute and Binding moves misbehave when used via
634
- Mirror Move (though Pokémon Showdown has its own weird behavior and does not implement the
635
- [partial trapping move Mirror Move
704
+ which means Mimic legally called via Metronome or Mirror Move only works if the user also has
705
+ Mimic (and the moved mimicked by Mimic called via Metronome / Mirror Move erroneously overrides
706
+ the Mimic move slot instead of the Metronome / Mirror Move move slot). Furthermore, because
707
+ Pokémon Showdown deducts PP based on a move's name instead of slot, if Mimic copies a move the
708
+ Pokémon already knows, PP deduction for using either the original move of the mimicked move
709
+ instead deducts PP for whichever appears at the lower move slot index and the PP is allowed to go
710
+ negative (effectively allowing for infinite PP use). Pokémon Showdown also doesn't deduct PP from
711
+ using Transform if it was copied by Mimic.
712
+ - **Mirror Move**: As covered earlier, both Substitute and Binding moves misbehave when used via
713
+ Mirror Move (though Pokémon Showdown has its own weird behavior and doesn't implement the [partial
714
+ trapping move Mirror Move
636
715
  glitch](https://glitchcity.wiki/Partial_trapping_move_Mirror_Move_link_battle_glitch) that exists
637
716
  on the cartridge). Additionally, Pokémon Showdown sets the last used move every turn a Pokémon is
638
- Thrashing instead of just on the turn it is actually selected meaning Mirror Move will sometimes
639
- successfully mirror a Thrashing move when it should fail. Finally, if Mirror Move copies
640
- Struggle it should not deduct PP but on Pokémon Showdown it does.
717
+ Thrashing instead of just on the turn it's actually selected meaning Mirror Move sometimes
718
+ successfully mirrors a Thrashing move when it should fail. Finally, if Mirror Move copies Struggle
719
+ it shouldn't deduct PP but on Pokémon Showdown it does.
641
720
  - **Metronome**: In addition to the issues with binding moves and Substitute, Metronome and Mirror
642
- Move cannot mutually call each other more than 3 times in a row without causing the Pokémon
643
- Showdown simulator to crash due to defensive safety checks that do not exist on the cartridge.
721
+ Move can't mutually call each other more than 3 times in a row without causing the Pokémon
722
+ Showdown simulator to crash due to defensive safety checks that don't exist on the cartridge.
644
723
  - **Transform**: Transform screws up the effect of Disable, because on Pokémon Showdown, Disable
645
724
  prevents moves of a given *name* from being used (e.g. "Water Gun") as opposed to moves in a
646
- specific *slot* (e.g. the 2nd move slot), and a Pokémon's moves can change after Transform (this
647
- is not an issue with Disable + Mimic because Mimic happens to replace the same slot). Transform
648
- also has a bad interaction with Pokémon Showdown's buggy Haze implementation, as Haze on Pokémon
649
- Showdown does not copy unmodified stats, leaving the Transformed Pokémon with incorrect stats.
650
- Furthermore, transforming and then using Mirror Move / Metronome can result in [glitchy behavior
651
- and
725
+ specific *slot* (e.g. the second move slot), and a Pokémon's moves can change after Transform
726
+ (this isn't an issue with Disable + Mimic because Mimic happens to replace the same slot).
727
+ Transform also has a bad interaction with Pokémon Showdown's buggy Haze implementation, as Haze on
728
+ Pokémon Showdown doesn't copy unmodified stats, leaving the Transformed Pokémon with incorrect
729
+ stats. Furthermore, transforming and then using Mirror Move / Metronome can result in [glitchy
730
+ behavior and
652
731
  softlocks](https://pkmn.cc/bulba/Transform_glitches#Transform_.2B_Mirror_Move.2FMetronome_PP_error)
653
- which Pokémon Showdown does not implement.
732
+ which Pokémon Showdown doesn't implement.
654
733
 
655
734
  Importantly, Pokémon Showdown's **speed tie RNG mechanics are unimplementable** in the pkmn engine
656
735
  as they rely on internal implementation decisions made by Pokémon Showdown that are impossible to
@@ -661,13 +740,13 @@ below).
661
740
 
662
741
  **The pkmn engine aims to match the cartridge's RNG frame-accurately**, in that provided with the
663
742
  same initial seed and inputs it should produce the same battle playout as the Pokémon Red cartridge.
664
- **Pokémon Showdown does not correctly implement frame-accurate RNG in any generation**, and along
665
- with the [bugs](#bugs) discussed above this results in large differences in the codebase. Because
743
+ **Pokémon Showdown doesn't correctly implement frame-accurate RNG in any generation**, and along
744
+ with the [bugs](#bugs) discussed earlier this results in large differences in the codebase. Because
666
745
  the pkmn engine aims to be as compatible with Pokémon Showdown as possible when in `-Dshowdown`
667
746
  compatibility mode, the implications of these differences are outlined below:
668
747
 
669
748
  - **RNG**: Pokémon Showdown uses the RNG from Generation V & VI in every generation, despite
670
- the seeds and algorithm being different. Pokémon Red uses a simple 8-bit RNG with 10 distinct
749
+ the seeds and algorithm being different. Pokémon Red uses a simple 8-bit RNG with 9 distinct
671
750
  seeds generated when the link connection is established, whereas Pokémon Showdown uses a 64-bit
672
751
  RNG with a 32-bit output.
673
752
  - **Algorithm**: As detailed in the table below, the algorithm used by Pokémon Showdown in the
@@ -680,15 +759,15 @@ compatibility mode, the implications of these differences are outlined below:
680
759
  sampling to ensure uniformity as is done on the cartridge. This means that certain values are
681
760
  fractionally more likely to be chosen than others, though this bias is usually quite small (e.g.
682
761
  in the case of Metronome instead of selecting moves with an equal $1\over163$ chance, Pokémon
683
- Showdown will select some with a $1\over2^{32}$ greater chance than others).
762
+ Showdown selects some with a $1\over2^{32}$ greater chance than others).
684
763
  - **Order of operations**: RNG calls effectively introduce something similar to a ["memory
685
764
  barrier"](https://en.wikipedia.org/wiki/Memory_barrier) in that they must be sequenced correctly
686
765
  (though operations which occur between them may happen in any order). Pokémon Showdown violates
687
766
  this by introducing additional operations (see below) and changing up the order of existing
688
767
  operations (e.g. choosing to check for hit/miss, determine the number of hits for moves with
689
768
  multiple hits, determine if a move hit critically and then the damage instead of checking for
690
- hit/miss and determining number of hits *after* the other two). While it is often desirable to
691
- rearrange code for performance or to improve readability this can only be done if it does not
769
+ hit/miss and determining number of hits *after* the other two). While it's often desirable to
770
+ rearrange code for performance or to improve readability this can only be done if it doesn't
692
771
  affect accuracy.
693
772
  - **Speed-ties**: In addition to [breaking switch-in speed ties with an RNG
694
773
  call](https://www.smogon.com/forums/threads/adv-switch-priority.3622189/), speed ties in Pokémon
@@ -699,16 +778,16 @@ compatibility mode, the implications of these differences are outlined below:
699
778
  ties proves impossible, and thus the reference Pokémon Showdown implementation pkmn engine aims to
700
779
  match has been [patched](../../../docs/TESTING.md#patches) to change this behavior.
701
780
  - **Effects**: Pokémon Showdown occasionally incorrectly inserts RNG calls in move effect handlers
702
- when they are not relevant:
781
+ when they're not relevant:
703
782
  - Roar / Whirlwind roll to hit and can "miss" as opposed to simply failing
704
783
 
705
- Finally, the **initial 10-byte seed for link battles on Pokémon Red cannot include bytes larger than
784
+ Finally, the **initial 9-byte seed for link battles on Pokémon Red can't include bytes larger than
706
785
  the `SERIAL_PREAMBLE_BYTE`**, so must be in the range $\left[0, 252\right]$. This has implications
707
- on the first 10 random numbers generated during the battle and has [**non-trivial competitive
786
+ on the first 9 random numbers generated during the battle and has [**non-trivial competitive
708
787
  implications**](https://www.smogon.com/forums/posts/9068411/show) (at the start of the battle move
709
788
  effects become more likely, the ["1/256-miss" glitch](https://glitchcity.wiki/1/256_miss_glitch)
710
- cannot happen, Player 1 is more likely to win speed ties, etc) that Pokémon Showdown cannot
711
- replicate due to everything described above.
789
+ can't happen, Player 1 is more likely to win speed ties, etc) that Pokémon Showdown can't replicate
790
+ due to everything described earlier.
712
791
 
713
792
  All of places in the link battle code where randomness is required are outlined below:
714
793
 
@@ -728,19 +807,19 @@ All of places in the link battle code where randomness is required are outlined
728
807
  | **Paralysis** (full) | `beforeMove` | Trigger if $X < 63$ |
729
808
  | **Poison** (chance) | `Effects.poison` | Trigger if $X < 52$ ($103$ for Smog / Sludge) |
730
809
  | **Sleep** (duration) | `Effects.sleep` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X \land 7 \neq 0$</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[1, 8\right)$</dd></dl> |
731
- | **Bide** (duration) | `Effects.bide` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 1\right) + 2$ turns</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \left[2, 4\right)$ turns</dd></dl> |
810
+ | **Bide** (duration) | `Effects.bide` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 1\right) + 2$ turns</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \left[2, 4\right)$ turns</dd></dl> |
732
811
  | **Disable** (move) | `Effects.disable` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X \land 3$ is the index of a non-empty move slot</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[0, \|movesSlots\|\right)$</dd></dl> |
733
812
  | **Disable** (duration) | `Effects.disable` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 7\right) + 1$ turns</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \left[1, 9\right)$ turns</dd></dl> |
734
- | **Metronome** (move) | `metronome` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X$ matches the index of a move which is not Struggle or Metronome</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[0, \|validMoves\|\right)$, where $validMoves$ is ordered set of moves with Struggle and Metronome removed <i>(indexes of moves > Metronome will be shifted down)</i></dd></dl> |
813
+ | **Metronome** (move) | `metronome` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X$ matches the index of a move which isn't Struggle or Metronome</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[0, \|validMoves\|\right)$, where $validMoves$ is ordered set of moves with Struggle and Metronome removed <i>(indexes of moves > Metronome are shifted down)</i></dd></dl> |
735
814
  | **Mimic** (move) | `Effects.mimic` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X \land 3$ is the index of a non-empty move slot</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[0, \|movesSlots\|\right)$</dd></dl> |
736
815
  | **Psywave** (power) | `specialDamage` | <dl><dt>Pokémon Red</dt><dd>Continue generating until $X < {3\over2} \cdot level$</dd><dt>Pokémon Showdown</dt><dd>Generate $X \in \left[0, {3\over2} \cdot level\right)$</dd></dl> |
737
816
  | **Thrash** (rampage) | `Effects.thrash` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 1\right) + 2$ turns</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \left[2, 4\right)$ turns</dd></dl> |
738
817
  | **Thrash** (confusion) | `beforeMove` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 3\right) + 2$ turns</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \left[2, 6\right)$ turns</dd></dl> |
739
- | **Binding** (duration) | `Effects.binding` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 3\right) + 1$ further turns if $\left(X \land 3\right) < 2$<br /> otherwise last for $\left(Y \land 3\right) + 1$ further turns (reroll)</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \{2, 2, 3, 3, 4, 5\} - 1$ further turns</dd></dl> |
818
+ | **Binding** (duration) | `Effects.binding` | <dl><dt>Pokémon Red</dt><dd>Last for $\left(X \land 3\right) + 1$ further turns if $\left(X \land 3\right) < 2$<br /> otherwise last for $\left(Y \land 3\right) + 1$ further turns (reroll)</dd><dt>Pokémon Showdown</dt><dd>Last for $X \in \{2, 2, 2, 3, 3, 3, 4, 5\} - 1$ further turns</dd></dl> |
740
819
  | **Multi-Hit** (hits) | `Effects.multiHit` | *Ibid.* |
741
820
  | **Unboost** (chance) | `Effects.unboost` | Trigger if $X < 85$ |
742
821
 
743
- *In the table above,* $X$ *is always in the range* $\left[0, 256\right)$ *for Pokémon Red and for
822
+ *In the preceding table,* $X$ *is always in the range* $\left[0, 256\right)$ *for Pokémon Red and for
744
823
  Pokémon Showdown is always **scaled** from the 32-bit output range of the RNG to either be in that
745
824
  range or to whichever range is specified by the description.*
746
825
 
@@ -783,7 +862,8 @@ table provides a rough mapping between pkmn and Pokémon Red methods:
783
862
  | `handleResidual` | `HandlePoisonBurnLeechSeed` |
784
863
  | `endTurn` / `checkEBC` | - |
785
864
 
786
- Pokémon Red groups move effect handlers together into several groups, these have also been renamed for clarification in the pkmn engine:
865
+ Pokémon Red groups move effect handlers together into several groups, these have also been renamed
866
+ for clarification in the pkmn engine:
787
867
 
788
868
  | pkmn | Pokémon Red (pret) |
789
869
  | --------------- | ------------------------- |
@@ -799,7 +879,7 @@ The pkmn engine attempts to adhere to certain naming conventions:
799
879
  - **`p1`** & **`p2`** always correspond to the `Side` of `Player.P1` and `Player.P2` respectively
800
880
  - **`player`** is the executing turn `Player` (`hWhoseTurn`) and **`player.foe()`** is their
801
881
  opponent
802
- - if `player` (executing turn player) is present then **`side`** will always correspond to their
882
+ - if `player` (executing turn player) is present then **`side`** always corresponds to their
803
883
  `Side` and **`foe`** the opposing `Side`, however `side` can refer to an arbitrary `Side` object
804
884
  if there is no `player` in scope (e.g. in helper functions)
805
885
  - **`target_player`** is a target `Player` whose corresponding `Side` is **`target`**