github-mirrors/pokerogue
1
0
Fork 0
mirror of https://github.com/pagefaultgames/pokerogue.git synced 2025-06-27 17:05:22 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

[Docs] Added changes to markdown files + comment fixes (#5682)

Browse source 
* Added changes to markdown files, reworked test boilerplate code + comment fixes

* Update comments.md

Removed references to jsdoc.
Removed mention of @extends which doesn't even exist in tsdoc
Increased clarity of documenting `args` parameter.
Moved to using active voice instead of passive voice

* Fix truncated sentence in returns example

* fix create-test-boilerplate.js

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update gameManager.ts

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update comments.md

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update gameManager.ts

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update gameManager.ts

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update gameManager.ts

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Update gameManager.ts

* Fixed doc thing

* Fixed the things

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* Fixde boilerplate to use snake case

* Update .gitignore to include workspace files

* Update linting.md, fix lefthook etc.

* Fix tpyo

* Update create-test-boilerplate.js

Co-authored-by: Dean <69436131+emdeann@users.noreply.github.com>

* Update create-test-boilerplate.js

Co-authored-by: Dean <69436131+emdeann@users.noreply.github.com>

* Update create-test-boilerplate.js

Co-authored-by: Dean <69436131+emdeann@users.noreply.github.com>

* Reverted boilerplate code fixes and applied review comments

Will now be handled by milkmaiden

* Fixed up documentation for comments.md and linting.md

Comments.md added info pertaining to Kev's review
linting.md i just stopped spouting misinformation

* Update `biome.jsonc` comments

Update `comments.md`

Update docs for `AddSubstituteAttr` in `move.ts` to match example

* Apply suggestions to the suggestions

---------

Co-authored-by: Sirz Benjie <142067137+SirzBenjie@users.noreply.github.com>
Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>
Co-authored-by: Dean <69436131+emdeann@users.noreply.github.com>
This commit is contained in:
Bertie690 2025-05-01 20:24:37 -04:00 • committed by GitHub
parent bee06410dd
commit da3b2e0edd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 265 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -13,7 +13,8 @@ dist-ssr
*.local
# Editor directories and files
.vscode/*
.vscode
*.code-workspace
.idea
.DS_Store
*.suo

4
biome.jsonc
View file

@ -105,10 +105,10 @@
"linter": {
"rules": {
"performance": {
"noDelete": "off"
"noDelete": "off" // TODO: evaluate if this is necessary for the test(s) to function
},
"style": {
"noNamespaceImport": "off"
"noNamespaceImport": "off" // this is required for `vi.spyOn` to work in some tests
}
}
}

117
docs/comments.md
View file

@ -1,64 +1,107 @@
## How do I comment my code?
# Commenting code
### While we're not enforcing a strict standard, there are some things to keep in mind:
People spend more time reading code than writing it (sometimes substantially more so). As such, comments and documentation are **vital** for any large codebase like this.
## General Guidelines
While we're not enforcing a strict standard, here are some things to keep in mind:
- Make comments meaningful
- Comments should be explaining why a line or block of code exists and what the reason behind it is
- Comments should not be repeating chunks of code or explaining what 'true' and 'false' means in typescript
- Comments should **NOT** repeat _what_ code _does_[^1] or explain concepts obvious to someone with a basic understanding of the language at hand. Instead, focus on explaining _why_ a line or block of code exists.
- Anyone with basic reading comprehension and a good IDE can figure out what code does; gaining a _post hoc_ understanding of the _reasons_ behind its existence takes a lot more digging, effort and bloodshed.
- Keep comments readable
- A comment's verbosity should roughly scale with the complexity of its subject matter. Some people naturally write shorter or longer comments as a personal style, but summarizing a 300 line function with "does a thing" is about as good as writing nothing. Conversely, writing a paragraph-level response where a basic one-liner would suffice is no less undesirable.
- Long comments should ideally be broken into multiple lines at around the 100-120 character mark. This isn't _mandatory_, but avoids unnecessary scrolling in terminals and IDEs.
- Make sure comments exist on Functions, Classes, Methods, and Properties
- This may be the most important things to comment. When someone goes to use a function/class/method/etc., having a comment reduces the need to flip back and forth between files to figure out how something works. Peek Definition is great until you're three nested functions deep.
- The best example of this is JSDoc-style comments as seen below:
- When formatted this way, the comment gets shown by intellisense in VS Code or similar IDEs just by hovering over the text!
- Functions also show each the comment for parameter as you type them, making keeping track of what each one does in lengthy functions much more clear
```js
/**
* Changes the type-based weather modifier if this move's power would be reduced by it
* @param user {@linkcode Pokemon} using this move
* @param target {@linkcode Pokemon} target of this move
* @param move {@linkcode Move} being used
* @param args [0] {@linkcode Utils.NumberHolder} for arenaAttackTypeMultiplier
* @returns true if the function succeeds
*/
apply(user: Pokemon, target: Pokemon, move: Move, args: any[]): boolean {
}
- These may be the most important things to comment. When someone goes to use a function/class/method/etc., having a comment reduces the need to flip back and forth between files to figure out what XYZ does. Peek Definition is great until you're three nested levels deep.
/** Set to true when experimental animated sprites from Gen6+ are used */
public experimentalSprites: boolean = false;
[^1]: With exceptions for extremely long, convoluted or unintuitive methods (though an over-dependency on said comments is likely a symptom of poorly structured code).
# TSDoc
The codebase makes extensive use of [TSDoc](https://tsdoc.org), which is a TypeScript-specific version of [JSDoc](https://jsdoc.app/about-getting-started)
that uses similar syntax and attaches to functions, classes, etc.
When formatted correctly, these comments are shown within VS Code or similar IDEs just by hovering over the function or object.
- Functions also show the comment for each parameter as you type them, making keeping track of arguments inside lengthy functions much more clear.
They can also be used to generate a commentated overview of the codebase. There is a GitHub action that automatically updates [this docs site](https://pagefaultgames.github.io/pokerogue/main/index.html)
and you can generate it locally as well via `npm run docs` which will generate into the `typedoc/` directory.
## Syntax
For an example of how TSDoc comments work, here are some TSDoc comments taken from `src/data/moves/move.ts`:
```ts
/**
* Cures the user's party of non-volatile status conditions, ie. Heal Bell, Aromatherapy
* @extends MoveAttr
* @see {@linkcode apply}
* Attribute to put in a {@link https://bulbapedia.bulbagarden.net/wiki/Substitute_(doll) | Substitute Doll} for the user.
*/
export class DontHealThePartyPlsAttr extends MoveAttr {
export class AddSubstituteAttr extends MoveEffectAttr {
/** The ratio of the user's max HP that is required to apply this effect */
private hpCost: number;
/** Whether the damage taken should be rounded up (Shed Tail rounds up) */
private roundUp: boolean;
constructor(hpCost: number, roundUp: boolean) {
// code removed
}
/**
* Removes 1/4 of the user's maximum HP (rounded down) to create a substitute for the user
* @param user - The {@linkcode Pokemon} that used the move.
* @param target - n/a
* @param move - The {@linkcode Move} with this attribute.
* @param args - n/a
* @returns `true` if the attribute successfully applies, `false` otherwise
*/
apply(user: Pokemon, target: Pokemon, move: Move, args: any[]): boolean {
// code removed
}
getUserBenefitScore(user: Pokemon, target: Pokemon, move: Move): number {
// code removed
}
getCondition(): MoveConditionFunc {
// code removed
}
/**
* Get the substitute-specific failure message if one should be displayed.
* @param user - The pokemon using the move.
* @returns The substitute-specific failure message if the conditions apply, otherwise `undefined`
*/
getFailedText(user: Pokemon, _target: Pokemon, _move: Move): string | undefined {
// code removed
}
}
```
You'll notice this contains an `{@linkcode Object}` tag for each parameter. This provides an easy type denomination and hyperlink to that type using VS Code's Intellisense. `@linkcode` is used instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.
If you're interested in going more in depth, you can find a reference guide for how comments like these work [here](https://jsdoc.app)
Looking at the example given, you'll notice this contains an `{@linkcode XYZ}` tag in some of the parameters. This provides a clickable hyperlink to that type or object in most modern IDEs. (`@linkcode` is used here instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.) \
Also note the dashes (` - `) between the parameter names and descriptions - these are **mandatory** under the TSDoc spec[^2].
If you're interested in going more in depth, you can find a reference guide for how comments like these work [on the TSDoc website](https://tsdoc.org).
The [playground page](https://tsdoc.org/play/) there can also be used for live testing of examples.
[^2]: Incidentally, this is also the only place dashes are explicitly _required_.
### What not to do:
- Don't leave comments for code you don't understand
- Incorrect information is worse than no information. If you aren't sure how something works, don't make something up to explain it. Ask for help instead.
- Incorrect information is worse than no information. If you aren't sure how something works, don't make something up to explain it - ask for help and/or mark it as TODO.
- Don't over-comment
- Not everything needs an explanation. Try to summarize blocks of code instead of singular lines where possible. Single line comments should call out specific oddities.
- Not everything needs a comment. Try to summarize blocks of code instead of singular lines where possible, always preferring giving a reason over stating a fact. Single line comments should call out specific oddities or features.
## How do Abilities and Moves differ from other classes?
While other classes should be fully documented, Abilities and Moves heavily incoperate inheritance (i.e. the `extends` keyword). Because of this, much of the functionality in these classes is duplicated or only slightly changed between classes.
### With this in mind, there's a few more things to keep in mind for these:
- Do not document any parameters if the function mirrors the one they extend.
- Keep this in mind for functions that are not the `apply` function as they are usually sparce and mostly reused
- The class itself must be documented
- This must include the `@extends BaseClass` and `@see {@linkcode apply}` tags
- Keep this in mind for functions that are not the `apply` function as they are usually sparse and mostly reused
- Class member variables must be documented
- You can use a single line documentation comment for these `/** i.e. a comment like this */`
- `args` parameters must be documented if used
- This should look something like this when there are multiple:
- This should look something vaguely like this when there are multiple:
```ts
/**
...
* @param args [0] {@linkcode Utils.NumberHolder} of arenaAttackTypeMultiplier
* [1] {@linkcode Utils.BooleanHolder} of cancelled
* [2] {@linkcode Utils.BooleanHolder} of rWeDoneYet
* @param args -
* `[0]` The {@linkcode Move} being used
* `[1]` A {@linkcode BooleanHolder} used to track XYZ
* `[2]` {@linkcode BooleanHolder} `paramC` - paramC description here
...
*/
```
```

125
docs/enemy-ai.md
View file

@ -37,12 +37,12 @@ The `EnemyCommandPhase` follows this process to determine whether or not an enem
1. If the Pokémon has a move already queued (e.g. they are recharging after using Hyper Beam), or they are trapped (e.g. by Bind or Arena Trap), skip to resolving a `FIGHT` command (see next section).
2. For each Pokémon in the enemy's party, [compute their matchup scores](#calculating-matchup-scores) against the active player Pokémon. If there are two active player Pokémon in the battle, add their matchup scores together.
3. Take the party member with the highest matchup score and apply a multiplier to the score that reduces the score based on how frequently the enemy trainer has switched Pokémon in the current battle.
- The multiplier scales off of a counter that increments when the enemy trainer chooses to switch a Pokémon and decrements when they choose to use a move.
- The multiplier scales off of a counter that increments when the enemy trainer chooses to switch a Pokémon and decrements when they choose to use a move.
4. Compare the result of Step 3 with the active enemy Pokémon's matchup score. If the party member's matchup score is at least three times that of the active Pokémon, switch to that party member.
- "Boss" trainers only require the party member's matchup score to be at least two times that of the active Pokémon, so they are more likely to switch than other trainers. The full list of boss trainers in the game is as follows:
- All gym leaders, Elite 4 members, and Champions
- All Evil Team leaders
- The last three Rival Fights (on waves 95, 145, and 195)
- "Boss" trainers only require the party member's matchup score to be at least two times that of the active Pokémon, so they are more likely to switch than other trainers. The full list of boss trainers in the game is as follows:
- All gym leaders, Elite 4 members, and Champions
- All Evil Team leaders
- The last three Rival Fights (on waves 95, 145, and 195)
5. If the enemy decided to switch, send a switch `turnCommand` and end this `EnemyCommandPhase`; otherwise, move on to resolving a `FIGHT` enemy command.
## Step 2: Selecting a Move
@ -54,28 +54,35 @@ At this point, the enemy (a wild or trainer Pokémon) has decided against switch
In `getNextMove()`, the enemy Pokémon chooses a move to use in the following steps:
1. If the Pokémon has a move in its Move Queue (e.g. the second turn of a charging move), and the queued move is still usable, use that move against the given target.
2. Filter out any moves it can't use within its moveset. The remaining moves make up the enemy's **move pool** for the turn.
1. A move can be unusable if it has no PP left or it has been disabled by another move or effect
2. If the enemy's move pool is empty, use Struggle.
1. A move can be unusable if it has no PP left or it has been disabled by another move or effect.
2. If the enemy's move pool is empty, use Struggle.
3. Calculate the **move score** of each move in the enemy's move pool.
1. A move's move score is equivalent to the move's maximum **target score** among all of the move's possible targets on the field ([more on this later](#calculating-move-and-target-scores)).
2. A move's move score is set to -20 if at least one of these conditions are met:
- The move is unimplemented (or, more precisely, the move's name ends with "&nbsp;(N)").
- Conditions for the move to succeed are not met (unless the move is Sucker Punch, Upper Hand, or Thunderclap, as those moves' conditions can't be resolved before the turn starts).
- The move's target scores are 0 or `NaN` for each target. In this case, the game assumes the target score calculation for that move is unimplemented.
1. A move's move score is equivalent to the move's maximum **target score** among all of the move's possible targets on the field ([more on this later](#calculating-move-and-target-scores)).
2. A move's move score is set to -20 if at least one of these conditions are met:
- The move is unimplemented (or, more precisely, the move's name ends with "(N)").
- Conditions for the move to succeed are not met (unless the move is Sucker Punch, Upper Hand or Thunderclap, as those moves' conditions can't be resolved until after the turn starts).
- The move's target scores are 0 or `NaN` for each target. In this case, the game assumes the target score calculation for that move is unimplemented.
4. Sort the move pool in descending order of move scores.
5. From here, the enemy's move selection varies based on its `aiType`. If the enemy is a Boss Pokémon or has a Trainer, it uses the `SMART` AI type; otherwise, it uses the `SMART_RANDOM` AI type.
1. Let $m_i$ be the *i*-th move in the sorted move pool $M$:
- If `aiType === SMART_RANDOM`, the enemy has a 5/8 chance of selecting $m_0$ and a 3/8 chance of advancing to the next best move $m_1$, where it then repeats this roll. This process stops when a move is selected or the last move in the move pool is reached.
- If `aiType === SMART`, a similar loop is used to decide between selecting the move $m_i$ and advancing to the next iteration with the move $m_{i+1}$. However, instead of using a flat probability, the following conditions need to be met to advance from selecting $m_i$ to $m_{i+1}$:
- $\text{sign}(s_i) = \text{sign}(s_{i+1})$, where $s_i$ is the move score of $m_i$.
- $\text{randInt}(0, 100) < \text{round}(\frac{s_{i+1}}{s_i}\times 50)$. In other words: if the scores of $m_i$ and $m_{i+1}$ have the same sign, the chance to advance to the next iteration with $m_{i+1}$ is proportional to how close the scores are to each other. The probability to advance to the next iteration is at most 50 percent (when $s_i$ and $s_{i+1}$ are equal).
1. Let $m_i$ be the *i*-th move in the sorted move pool $M$:
- If `aiType === SMART_RANDOM`, the enemy has a 5/8 chance of selecting $m_0$ and a 3/8 chance of advancing to the next best move $m_1$, where it then repeats this roll. This process stops when a move is selected or the last move in the move pool is reached.
- If `aiType === SMART`, a similar loop is used to decide between selecting the move $m_i$ and advancing to the next iteration with the move $m_{i+1}$. However, instead of using a flat probability, the following conditions need to be met to advance from selecting $m_i$ to $m_{i+1}$:
- $\text{sign}(s_i) = \text{sign}(s_{i+1})$, where $s_i$ is the move score of $m_i$.
- $\text{randInt}(0, 100) < \text{round}(\frac{s_{i+1}}{s_i}\times 50)$. In other words: if the scores of $m_i$ and $m_{i+1}$ have the same sign, the chance to advance to the next iteration with $m_{i+1}$ is proportional to how close the scores are to each other. The probability to advance to the next iteration is at most 50 percent (when $s_i$ and $s_{i+1}$ are equal).
6. The enemy will use the move selected in Step 5 against the target(s) with the highest [**target selection score (TSS)**](#choosing-targets-with-getnexttargets)
### Calculating Move and Target Scores
As part of the move selection process, the enemy Pokémon must compute a **target score (TS)** for each legal target for each move in its move pool. The base target score for all moves is a combination of the move's **user benefit score (UBS)** and **target benefit score (TBS)**.
As part of the move selection process, the enemy Pokémon must compute a **target score (TS)** for each legal target for each move in its move pool. The base target score is a combination of the move's **user benefit score (UBS)** and **target benefit score (TBS)**, representing how much the move helps or hinders the user and/or its target(s).
![equation](https://latex.codecogs.com/png.image?%5Cinline%20%5Cdpi%7B100%7D%5Cbg%7Bwhite%7D%5Ctext%7BTS%7D=%5Ctext%7BUBS%7D&plus;%5Ctext%7BTBS%7D%5Ctimes%5Cleft%5C%7B%5Cbegin%7Bmatrix%7D-1&%5Ctext%7Bif%20target%20is%20an%20opponent%7D%5C%5C1&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
$$
\text{TS} = \text{UBS} + \left( \text{TBS} \times
\begin{cases}
-1 & \text{if target is an opponent} \\
1 & \text{otherwise}
\end{cases}
\right)
$$
A move's UBS and TBS are computed with the respective functions in the `Move` class:
@ -96,19 +103,38 @@ In addition to the base score from `Move.getTargetBenefitScore()`, attack moves
- The move's category (Physical/Special), and whether the user has a higher Attack or Special Attack stat.
More specifically, the following steps are taken to compute the move's `attackScore`:
1. Compute a multiplier based on the move's type effectiveness:
1. Compute a multiplier based on the move's type effectiveness:
![typeMultEqn](https://latex.codecogs.com/png.image?%5Cdpi%7B110%7D%5Cbg%7Bwhite%7D%5Ctext%7BtypeMult%7D=%5Cleft%5C%7B%5Cbegin%7Bmatrix%7D2&&%5Ctext%7Bif%20move%20is%20super%20effective(or%20better)%7D%5C%5C-2&&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
$$
\text{typeMult} =
\begin{cases}
2 & \text{if move is super effective (or better)} \\
-2 & \text{otherwise}
\end{cases}
$$
2. Compute a multiplier based on the move's category and the user's offensive stats:
1. Compute the user's offensive stat ratio:
![statRatioEqn](https://latex.codecogs.com/png.image?%5Cinline%20%5Cdpi%7B100%7D%5Cbg%7Bwhite%7D%5Ctext%7BstatRatio%7D=%5Cleft%5C%7B%5Cbegin%7Bmatrix%7D%5Cfrac%7B%5Ctext%7BuserSpAtk%7D%7D%7B%5Ctext%7BuserAtk%7D%7D&%5Ctext%7Bif%20move%20is%20physical%7D%5C%5C%5Cfrac%7B%5Ctext%7BuserAtk%7D%7D%7B%5Ctext%7BuserSpAtk%7D%7D&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
2. Compute the stat-based multiplier:
1. Compute the user's offensive stat ratio:
![statMultEqn](https://latex.codecogs.com/png.image?%5Cinline%20%5Cdpi%7B100%7D%5Cbg%7Bwhite%7D%5Ctext%7BstatMult%7D=%5Cleft%5C%7B%5Cbegin%7Bmatrix%7D2&%5Ctext%7Bif%20statRatio%7D%5Cle%200.75%5C%5C1.5&%5Ctext%7Bif%5C;%7D0.75%5Cle%5Ctext%7BstatRatio%7D%5Cle%200.875%5C%5C1&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
$$
\text{statRatio} =
\begin{cases}
\frac{\text{userSpAtk}}{\text{userAtk}} & \text{if move is physical} \\
\frac{\text{userAtk}}{\text{userSpAtk}} & \text{otherwise}
\end{cases}
$$
2. Compute the stat-based multiplier:
$$
\text{statMult} =
\begin{cases}
2 & \text{if statRatio} \leq 0.75 \\
1.5 & \text{if } 0.75 \leq \text{statRatio} \leq 0.875 \\
1 & \text{otherwise}
\end{cases}
$$
3. Calculate the move's `attackScore`:
$\text{attackScore} = (\text{typeMult}\times \text{statMult})+\lfloor \frac{\text{power}}{5} \rfloor$
$\text{attackScore} = (\text{typeMult}\times \text{statMult})+\lfloor \frac{\text{power}}{5} \rfloor$
The maximum total multiplier in `attackScore` ($\text{typeMult}\times \text{statMult}$) is 4, which occurs for attacks that are super effective against the target and are categorically aligned with the user's offensive stats (e.g. the move is physical, and the user has much higher Attack than Sp. Atk). The minimum total multiplier of -4 occurs (somewhat confusingly) for attacks that are not super effective but are categorically aligned with the user's offensive stats.
@ -125,18 +151,31 @@ The final step to calculate an attack move's target score (TS) is to multiply th
The enemy's target selection for single-target moves works in a very similar way to its move selection. Each potential target is given a **target selection score (TSS)** which is based on the move's [target benefit score](#calculating-move-and-target-scores) for that target:
![TSSEqn](https://latex.codecogs.com/png.image?%5Cinline%20%5Cdpi%7B100%7D%5Cbg%7Bwhite%7D%5Ctext%7BTSS%7D=%5Ctext%7BTBS%7D%5Ctimes%5Cleft%5C%7B%5Cbegin%7Bmatrix%7D-1&%5Ctext%7Bif%20target%20is%20an%20opponent%7D%5C%5C1&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
$$
\text{TSS} = \text{TBS} \times
\begin{cases}
-1 & \text{if target is an opponent} \\
1 & \text{otherwise}
\end{cases}
$$
Once the TSS is calculated for each target, the target is selected as follows:
1. Sort the targets (indexes) in decreasing order of their target selection scores (or weights). Let $t_i$ be the index of the *i*-th target in the sorted list, and let $w_i$ be that target's corresponding TSS.
2. Normalize the weights. Let $w_n$ be the lowest-weighted target in the sorted list, then:
![normWeightEqn](https://latex.codecogs.com/png.image?%5Cinline%20%5Cdpi%7B100%7D%5Cbg%7Bwhite%7DW_i=%5Cleft%5C%7B%5Cbegin%7Bmatrix%7Dw_i&plus;%7Cw_n%7C&%5Ctext%7Bif%5C;%7Dw_n%5C;%5Ctext%7Bis%20negative%7D%5C%5Cw_i&%5Ctext%7Botherwise%7D%5C%5C%5Cend%7Bmatrix%7D%5Cright.)
$$
W_i =
\begin{cases}
w_i + |w_n| & \text{if } w_n \text{ is negative} \\
w_i & \text{otherwise}
\end{cases}
$$
3. Remove all weights from the list such that $W_i < \frac{W_0}{2}$
4. Generate a random integer $R=\text{rand}(0, W_{\text{total}})$ where $W_{\text{total}}$ is the sum of all the remaining weights after Step 3.
5. For each target $(t_i, W_i)$,
1. if $R \le \sum_{j=0}^{i} W_i$, or if $t_i$ is the last target in the list, **return** $t_i$
2. otherwise, advance to the next target $t_{i+1}$ and repeat this check.
1. if $R \le \sum_{j=0}^{i} W_i$, or if $t_i$ is the last target in the list, **return** $t_i$
2. otherwise, advance to the next target $t_{i+1}$ and repeat this check.
Once the target is selected, the enemy has successfully determined its next action for the turn, and its corresponding `EnemyCommandPhase` ends. From here, the `TurnStartPhase` processes the enemy's commands alongside the player's commands and begins to resolve the turn.
@ -145,15 +184,15 @@ Once the target is selected, the enemy has successfully determined its next acti
Suppose you enter a single battle against an enemy trainer with the following Pokémon in their party:
1. An [Excadrill](https://bulbapedia.bulbagarden.net/wiki/Excadrill_(Pok%C3%A9mon)) with the Ability Sand Force and the following moveset
1. Earthquake
2. Iron Head
3. Crush Claw
4. Swords Dance
1. Earthquake
2. Iron Head
3. Crush Claw
4. Swords Dance
2. A [Heatmor](https://bulbapedia.bulbagarden.net/wiki/Heatmor_(Pok%C3%A9mon)) with the Ability Flash Fire and the following moveset
1. Fire Lash
2. Inferno
3. Hone Claws
4. Shadow Claw
1. Fire Lash
2. Inferno
3. Hone Claws
4. Shadow Claw
The enemy trainer leads with their Heatmor, and you lead with a [Dachsbun](https://bulbapedia.bulbagarden.net/wiki/Dachsbun_(Pok%C3%A9mon)) with the Ability Well-Baked Body. We'll cover the enemy's behavior over the next two turns.
@ -172,13 +211,13 @@ Based on the enemy party's matchup scores, whether or not the trainer switches o
Now that the enemy Pokémon with the best matchup score is on the field (assuming it survives Dachsbun's attack on the last turn), the enemy will now decide to have Excadrill use one of its moves. Assuming all of its moves are usable, we'll go through the target score calculations for each move:
- **Earthquake**: In a single battle, this move is just a 100-power Ground-type physical attack with no additional effects. With no additional benefit score from attributes, the move's base target score against the player's Dachsbun is just the `attackScore` from `AttackMove.getTargetBenefitScore()`. In this case, Earthquake's `attackScore` is given by
$\text{attackScore}=(\text{typeMult}\times \text{statMult}) + \lfloor \frac{\text{power}}{5} \rfloor = -2\times 2 + 20 = 16$
Here, `typeMult` is -2 because the move is not super effective, and `statMult` is 2 because Excadrill's Attack is significantly higher than its Sp. Atk. Accounting for STAB thanks to Excadrill's typing, the final target score for this move is **24**
- **Iron Head**: This move is an 80-power Steel-type physical attack with an additional chance to cause the target to flinch. With these properties, Iron Head has a user benefit score of 0 and a target benefit score given by
$\text{TBS}=\text{getTargetBenefitScore(FlinchAttr)}-\text{attackScore}$
Under its current implementation, the target benefit score of `FlinchAttr` is -5. Calculating the move's `attackScore`, we get:
@ -198,7 +237,7 @@ Now that the enemy Pokémon with the best matchup score is on the field (assumin
where `levels` is the number of stat stages added by the attribute (in this case, +2). The final score for this move is **6** (Note: because this move is self-targeted, we don't flip the sign of TBS when computing the target score).
- **Crush Claw**: This move is a 75-power Normal-type physical attack with a 50 percent chance to lower the target's Defense by one stage. The additional effect is implemented by the same `StatStageChangeAttr` as Swords Dance, so we can use the same formulas from before to compute the total TBS and base target score.
$\text{TBS}=\text{getTargetBenefitScore(StatStageChangeAttr)}-\text{attackScore}$
$\text{TBS}=(-4 + 2)-(-2\times 2 + \lfloor \frac{75}{5} \rfloor)=-2-11=-13$

71
docs/linting.md
View file

@ -1,34 +1,65 @@
# Biome
# Linting & Formatting
## Key Features
> "Any fool can write code that a computer can understand. Good programmers write code that humans can understand."
>
> — Martin Fowler
1. **Automation**:
- A pre-commit hook has been added to automatically run Biome on the added or modified files, ensuring code quality before commits.
Writing clean, readable code is important, and linters and formatters are an integral part of ensuring code quality and readability.
It is for this reason we are using [Biome](https://biomejs.dev), an opinionated linter/formatter (akin to Prettier) with a heavy focus on speed and performance.
2. **Manual Usage**:
- If you prefer not to use the pre-commit hook, you can manually run biome to automatically fix issues using the command:
### Installation
You probably installed Biome already without noticing it - it's included inside `package.json` and should've been downloaded when you ran `npm install` after cloning the repo (assuming you followed proper instructions, that is). If you haven't done that yet, go do it.
```sh
npx @biomejs/biome --write
```
# Using Biome
- Running this command will lint all files in the repository.
For the most part, Biome attempts to stay "out of your hair", letting you write code while enforcing a consistent formatting standard and only notifying for errors it can't automatically fix.\
On the other hand, if Biome complains about a piece of code, **there's probably a good reason why**. Disable comments should be used sparingly or when readabilty demands it - your first instinct should be to fix the code in question, not disable the rule.
3. **GitHub Action**:
- A GitHub Action has been added to automatically run Biome on every push and pull request, ensuring code quality in the CI/CD pipeline.
## Editor Integration
Biome has integration with many popular code editors. See [these](https://biomejs.dev/guides/editors/first-party-extensions/) [pages](https://biomejs.dev/guides/editors/third-party-extensions/) for information about enabling Biome in your editor of choice.
If you are getting linting errors from biome and want to see which files they are coming from, you can find that out by running biome in a way that is configured to only show the errors for that specific rule: ``npx @biomejs/biome lint --only=category/ruleName``
## Automated Runs
Generally speaking, most users shouldn't need to run Biome directly; in addition to editor integration, [pre-commit hook](../lefthook.yml) will periodically run Biome before each commit.
You will **not** be able to push code with `error`-level linting problems - fix them beforehand.
## Summary of Biome Rules
We also have a [Github Action](../.github/workflows/quality.yml) to verify code quality each time a PR is updated, preventing bad code from inadvertently making its way upstream.
We use the [recommended ruleset](https://biomejs.dev/linter/rules/) for Biome, with some customizations to better suit our project's needs.
### Why am I getting errors for code I didn't write?
<!-- TODO: Remove this if/when we perform a project wide linting spree -->
To save time and minimize friction with existing code, both the pre-commit hook and workflow run will only check files **directly changed** by a given PR or commit.
As a result, changes to files not updated since Biome's introduction can cause any _prior_ linting errors in them to resurface and get flagged.
This should occur less and less often as time passes and more files are updated to the new standard.
For a complete list of rules and their configurations, refer to the `biome.jsonc` file in the project root.
## Running Biome via CLI
If you want Biome to check your files manually, you can run it from the command line like so:
```sh
npx biome check --[flags]
```
A full list of flags and options can be found on [their website](https://biomejs.dev/reference/cli/), but here's a few useful ones to keep in mind:
- `--write` will cause Biome to write all "safe" fixes and formatting changes directly to your files (rather than just complaining and doing nothing).
- `--changed` and `--staged` will only perform checks on all changed or staged files respectively. Biome sources this info from the relevant version control system (in this case Git).
- `diagnostic-level=XXX` will only show diagnostics with at least the given severity level (`info/warn/error`). Useful to only focus on errors causing a failed workflow run or similar.
## Linting Rules
We primarily use Biome's [recommended ruleset](https://biomejs.dev/linter/rules/) for linting JS/TS, with some customizations to better suit our project's needs[^1].
Some things to consider:
- We have disabled rules that prioritize style over performance, such as `useTemplate`
- Some rules are currently marked as warnings (`warn`) to allow for gradual refactoring without blocking development. Do not write new code that triggers these warnings.
- The linter is configured to ignore specific files and folders, such as large or complex files that are pending refactors, to improve performance and focus on actionable areas.
- We have disabled rules that prioritize style over performance, such as `useTemplate`.
- Some rules are currently disabled or marked as warnings (`warn`) to allow for gradual refactoring without blocking development. **Do not write new code that triggers these warnings.**
- The linter is configured to ignore specific files and folders (such as excessively large files or ones in need of refactoring) to improve performance and focus on actionable areas.
Formatting is also handled by Biome. You should not have to worry about manually formatting your code.
Any questions about linting rules should be brought up in the `#dev-corner` channel in the discord.
[^1]: A complete list of rules can be found in the `biome.jsonc` file in the project root.
## What about ESLint?
<!-- Remove if/when we finally ditch eslint for good -->
Our project migrated away from ESLint around March 2025 due to it simply not scaling well enough with the codebase's ever-growing size. The [existing eslint rules](../eslint.config.js) are considered _deprecated_, only kept due to Biome lacking the corresponding rules in its current ruleset.
No additional ESLint rules should be added under any circumstances - even the few currently in circulation take longer to run than the entire Biome formatting/linting suite combined.

5
lefthook.yml
View file

@ -2,13 +2,12 @@ pre-commit:
parallel: true
commands:
biome-lint:
glob: "*.{js,jsx,ts,tsx}"
run: npx @biomejs/biome check --write --reporter=summary {staged_files} --no-errors-on-unmatched
run: npx biome check --write --reporter=summary --staged --no-errors-on-unmatched
stage_fixed: true
skip:
- merge
- rebase
post-merge:
commands:
update-submodules:

20
src/data/moves/move.ts
View file

@ -122,7 +122,6 @@ import { MoveFlags } from "#enums/MoveFlags";
import { MoveEffectTrigger } from "#enums/MoveEffectTrigger";
import { MultiHitType } from "#enums/MultiHitType";
import { invalidAssistMoves, invalidCopycatMoves, invalidMetronomeMoves, invalidMirrorMoveMoves, invalidSleepTalkMoves } from "./invalid-moves";
import { TrainerVariant } from "#app/field/trainer";
import { SelectBiomePhase } from "#app/phases/select-biome-phase";
type MoveConditionFunc = (user: Pokemon, target: Pokemon, move: Move) => boolean;
@ -1803,10 +1802,7 @@ export class HalfSacrificialAttr extends MoveEffectAttr {
}
/**
* Attribute to put in a {@link https://bulbapedia.bulbagarden.net/wiki/Substitute_(doll) | Substitute Doll}
* for the user.
* @extends MoveEffectAttr
* @see {@linkcode apply}
* Attribute to put in a {@link https://bulbapedia.bulbagarden.net/wiki/Substitute_(doll) | Substitute Doll} for the user.
*/
export class AddSubstituteAttr extends MoveEffectAttr {
/** The ratio of the user's max HP that is required to apply this effect */
@ -1823,11 +1819,11 @@ export class AddSubstituteAttr extends MoveEffectAttr {
/**
* Removes 1/4 of the user's maximum HP (rounded down) to create a substitute for the user
* @param user the {@linkcode Pokemon} that used the move.
* @param target n/a
* @param move the {@linkcode Move} with this attribute.
* @param args n/a
* @returns true if the attribute successfully applies, false otherwise
* @param user - The {@linkcode Pokemon} that used the move.
* @param target - n/a
* @param move - The {@linkcode Move} with this attribute.
* @param args - n/a
* @returns `true` if the attribute successfully applies, `false` otherwise
*/
apply(user: Pokemon, target: Pokemon, move: Move, args: any[]): boolean {
if (!super.apply(user, target, move, args)) {
@ -1848,12 +1844,12 @@ export class AddSubstituteAttr extends MoveEffectAttr {
}
getCondition(): MoveConditionFunc {
return (user, target, move) => !user.getTag(SubstituteTag) && user.hp > (this.roundUp ? Math.ceil(user.getMaxHp() * this.hpCost) : Math.floor(user.getMaxHp() * this.hpCost)) && user.getMaxHp() > 1;
return (user, _target, _move) => !user.getTag(SubstituteTag) && user.hp > (this.roundUp ? Math.ceil(user.getMaxHp() * this.hpCost) : Math.floor(user.getMaxHp() * this.hpCost)) && user.getMaxHp() > 1;
}
/**
* Get the substitute-specific failure message if one should be displayed.
* @param user The pokemon using the move.
* @param user - The pokemon using the move.
* @returns The substitute-specific failure message if the conditions apply, otherwise `undefined`
*/
getFailedText(user: Pokemon, _target: Pokemon, _move: Move): string | undefined {

16
src/utils/common.ts
View file

@ -515,8 +515,8 @@ export function capitalizeString(str: string, sep: string, lowerFirstChar = true
return null;
}
export function isNullOrUndefined(object: any): object is undefined | null {
return null === object || undefined === object;
export function isNullOrUndefined(object: any): object is null | undefined {
return object === null || object === undefined;
}
/**
@ -550,14 +550,14 @@ export function getLocalizedSpriteKey(baseKey: string) {
}
/**
* Check if a number is **inclusive** between two numbers
* @param num the number to check
* @param min the minimum value (included)
* @param max the maximum value (included)
* @returns `true` if number is **inclusive** between min and max
* Check if a number is **inclusively** between two numbers
* @param num - the number to check
* @param min - the minimum value (inclusive)
* @param max - the maximum value (inclusive)
* @returns Whether num is no less than min and no greater than max
*/
export function isBetween(num: number, min: number, max: number): boolean {
return num >= min && num <= max;
return min <= num && num <= max;
}
/**

55
test/testUtils/gameManager.ts
View file

@ -310,8 +310,8 @@ export default class GameManager {
/**
* Emulate a player's target selection after a move is chosen, usually called automatically by {@linkcode MoveHelper.select}.
* Will trigger during the next {@linkcode SelectTargetPhase}
* @param {BattlerIndex} targetIndex The index of the attack target, or `undefined` for multi-target attacks
* @param movePosition The index of the move in the pokemon's moveset array
* @param targetIndex - The {@linkcode BattlerIndex} of the attack target, or `undefined` for multi-target attacks
* @param movePosition - The 0-indexed position of the move in the pokemon's moveset array
*/
selectTarget(movePosition: number, targetIndex?: BattlerIndex) {
this.onNextPrompt(
@ -347,7 +347,7 @@ export default class GameManager {
}
}
/** Emulate selecting a modifier (item) */
/** Queue up button presses to skip taking an item on the next {@linkcode SelectModifierPhase} */
doSelectModifier() {
this.onNextPrompt(
"SelectModifierPhase",
@ -380,8 +380,9 @@ export default class GameManager {
/**
* Forces the next enemy selecting a move to use the given move in its moveset against the
* given target (if applicable).
* @param moveId {@linkcode Moves} the move the enemy will use
* @param target {@linkcode BattlerIndex} the target on which the enemy will use the given move
* @param moveId - The {@linkcode Moves | move} the enemy will use
* @param target - The {@linkcode BattlerIndex} of the target against which the enemy will use the given move;
* will use normal target selection priorities if omitted.
*/
async forceEnemyMove(moveId: Moves, target?: BattlerIndex) {
// Wait for the next EnemyCommandPhase to start
@ -421,7 +422,10 @@ export default class GameManager {
await this.phaseInterceptor.to(CommandPhase);
}
/** Emulate selecting a modifier (item) and transition to the next upcoming {@linkcode CommandPhase} */
/**
* Queue up button presses to skip taking an item on the next {@linkcode SelectModifierPhase},
* and then transition to the next {@linkcode CommandPhase}.
*/
async toNextWave() {
this.doSelectModifier();
@ -439,8 +443,8 @@ export default class GameManager {
}
/**
* Checks if the player has won the battle.
* @returns True if the player has won, otherwise false.
* Check if the player has won the battle.
* @returns whether the player has won the battle (all opposing Pokemon have been fainted)
*/
isVictory() {
return this.scene.currentBattle.enemyParty.every(pokemon => pokemon.isFainted());
@ -449,7 +453,7 @@ export default class GameManager {
/**
* Checks if the current phase matches the target phase.
* @param phaseTarget - The target phase.
* @returns True if the current phase matches the target phase, otherwise false.
* @returns Whether the current phase matches the target phase
*/
isCurrentPhase(phaseTarget) {
const targetName = typeof phaseTarget === "string" ? phaseTarget : phaseTarget.name;
@ -458,8 +462,8 @@ export default class GameManager {
/**
* Checks if the current mode matches the target mode.
* @param mode - The target mode.
* @returns True if the current mode matches the target mode, otherwise false.
* @param mode - The target {@linkcode UiMode} to check.
* @returns Whether the current mode matches the target mode.
*/
isCurrentMode(mode: UiMode) {
return this.scene.ui?.getMode() === mode;
@ -499,7 +503,7 @@ export default class GameManager {
/**
* Faints a player or enemy pokemon instantly by setting their HP to 0.
* @param pokemon The player/enemy pokemon being fainted
* @param pokemon - The player/enemy pokemon being fainted
* @returns A promise that resolves once the fainted pokemon's FaintPhase finishes running.
*/
async killPokemon(pokemon: PlayerPokemon | EnemyPokemon) {
@ -512,8 +516,9 @@ export default class GameManager {
}
/**
* Command an in-battle switch to another Pokemon via the main battle menu.
* @param pokemonIndex the index of the pokemon in your party to switch to
* Command an in-battle switch to another {@linkcode Pokemon} via the main battle menu.
* @param pokemonIndex - The 0-indexed position of the party pokemon to switch to.
* Should never be called with 0 as that will select the currently active pokemon and freeze.
*/
doSwitchPokemon(pokemonIndex: number) {
this.onNextPrompt("CommandPhase", UiMode.COMMAND, () => {
@ -526,7 +531,7 @@ export default class GameManager {
/**
* Revive pokemon, currently players only.
* @param pokemonIndex the index of the pokemon in your party to revive
* @param pokemonIndex - The 0-indexed position of the pokemon in your party to revive
*/
doRevivePokemon(pokemonIndex: number) {
const party = this.scene.getPlayerParty();
@ -536,13 +541,12 @@ export default class GameManager {
}
/**
* Select a pokemon from the party menu. Only really handles the basic cases
* of the party UI, where you just need to navigate to a party slot and press
* Action twice - navigating any menus that come up after you select a party member
* is not supported.
* @param slot the index of the pokemon in your party to switch to
* @param inPhase Which phase to expect the selection to occur in. Typically
* non-command switch actions happen in SwitchPhase.
* Select a pokemon from the party menu during the given phase.
* Only really handles the basic case of "navigate to party slot and press Action twice" -
* any menus that come up afterwards are ignored and must be handled separately by the caller.
* @param slot - The 0-indexed position of the pokemon in your party to switch to
* @param inPhase - Which phase to expect the selection to occur in. Defaults to `SwitchPhase`
* (which is where the majority of non-command switch operations occur).
*/
doSelectPartyPokemon(slot: number, inPhase = "SwitchPhase") {
this.onNextPrompt(inPhase, UiMode.PARTY, () => {
@ -557,7 +561,7 @@ export default class GameManager {
/**
* Select the BALL option from the command menu, then press Action; in the BALL
* menu, select a pokéball type and press Action again to throw it.
* @param ballIndex the index of the pokeball to throw
* @param ballIndex - The index of the pokeball to throw
*/
public doThrowPokeball(ballIndex: number) {
this.onNextPrompt("CommandPhase", UiMode.COMMAND, () => {
@ -575,8 +579,9 @@ export default class GameManager {
/**
* Intercepts `TurnStartPhase` and mocks {@linkcode TurnStartPhase.getSpeedOrder}'s return value.
* Used to manually modify Pokemon turn order.
* Note: This *DOES NOT* account for priority, only speed.
* @param {BattlerIndex[]} order The turn order to set
* Note: This *DOES NOT* account for priority.
* @param order - The turn order to set
* @example
* ```ts
* await game.setTurnOrder([BattlerIndex.PLAYER, BattlerIndex.ENEMY, BattlerIndex.ENEMY_2, BattlerIndex.PLAYER_2]);