Conversation
…yses Document the Pando calculation stack for the pando-c branch: - pando/engine: README as an index + doc/ set (tags, nodes, propagation, optimization, usage walkthrough, calculator customization). - gi/sr/zzz formula: split per-game docs into tags.md (tag architecture and gathering/glue, with cycle-prevention discipline) and api.md (authoring surface). zzz adds a verified glue deep-dive. - game-opt and gi/wr: overview docs for the bridge layer and legacy engine. - pando/doc: README documentation map for the whole set, plus cross-game migration analyses (dmg-survey, name-scoped-buffs). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
WalkthroughThis PR is a massive documentation effort that refactors the Pando engine README into a modular guide (usage, tags, nodes, optimization, propagation, customization) while introducing comprehensive authoring APIs and tag system documentation for GI, SR, and ZZZ formula libraries, cross-game damage analysis, WaveRider legacy reference, and name-scoped buff migration materials. ChangesPando engine and per-game formula documentation suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes *yawns* Ah, just... docs. No code logic to trip me up this time. Mostly coherent explanation of systems I'd need to understand anyway. Though that damage survey section has some gnarly stat-rebind semantics that'll take a sec to parse when I'm not caffeinated... Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (6)
libs/sr/formula/doc/tags.md (1)
29-51: 💤 Low valueAh yes, another night of reading SR damage calculations at 3 AM...
The aggregation table is spot-on yawns, matches the actual code perfectly. Just noticed the markdown linter is complaining about the fenced code block at line 36 needing a language tag - probably wants ```text or something. Not a big deal though, the ASCII art renders fine either way.
Totally relatable content btw, spent way too many sleepless nights figuring out why my Kafka's DoT wasn't stacking right... turned out I was looking at the wrong
sheet:level the whole time 😴☕ Optional markdown lint fix
-``` +```text *--------*-----------------------------------------------------------*🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@libs/sr/formula/doc/tags.md` around lines 29 - 51, Update the fenced ASCII table code block so the opening triple-backticks include a language tag (e.g., change ``` to ```text) to satisfy the markdown linter; modify the block that documents Desc/sheet/agg/iso/static (the ASCII table around the "The three rendezvous levels" section) so its opening fence specifies a language like "text" while leaving the ASCII art and surrounding prose (references to Desc, sheet, agg, aggStr, iso, isoSum, fixed, prep) unchanged.libs/zzz/formula/doc/glue.md (1)
24-29: 💤 Low valueOptional: Add language specifiers to all code blocks for markdown linting compliance.
Three code blocks across glue.md and tags.md are missing language specifiers, triggering markdownlint MD040 warnings. Adding
textto each would silence the linter—purely cosmetic for a doc-only PR, though.stretches after another all-nighter reviewing docs Look, I get it—when you're cranking out docs at 3am between gacha pulls, you forget the little ```text tags. Not gonna break anything, but the linter bots will ping you. Up to you if it's worth the extra keystroke!
At least these docs are way more thorough than most gacha game wikis... glances at incomplete character guides
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@libs/zzz/formula/doc/glue.md` around lines 24 - 29, The fenced code blocks showing the table starting with "sheet | Team Buff | Disc | Reaction | W-Engine | Char | Custom" in glue.md (and the two other similar code blocks in tags.md) lack language specifiers and trigger markdownlint MD040; update each opening triple-backtick to include the language specifier "text" (i.e., replace ``` with ```text) for those three blocks so the linter stops warning while keeping content unchanged.libs/pando/engine/doc/customization.md (1)
6-25: ⚡ Quick winAdd language specifiers to fenced code blocks.
sips cold coffee at 2am These code blocks would be way more readable with proper syntax highlighting. Add
typescriptortsidentifiers to help fellow insomniacs parse the API signatures faster.📝 Suggested fix
For the first block (around line 6):
-``` +```typescript - defaultAccu(tag: Tag): BaseRead['ex']For the second block (around line 30):
-``` +```typescript type CustomInfo = {Also applies to: 30-44
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@libs/pando/engine/doc/customization.md` around lines 6 - 25, The fenced code blocks containing API signatures (e.g., the blocks with defaultAccu(tag: Tag): BaseRead['ex'], markGathered(...), computeMeta(...), and the CustomInfo/type blocks) lack language hints; edit those triple-backtick fences to include a TypeScript/ts specifier (```typescript or ```ts) so the signatures get proper syntax highlighting while leaving the code content unchanged.libs/pando/engine/doc/optimization.md (1)
18-21: ⚡ Quick winAdd language specifiers to fenced code blocks.
Been staring at these optimization docs for too long... the code blocks need language identifiers. The first one could be
textorpython-style for the optimization problem notation, and the second pseudocode block could usejavascriptortypescriptfor better highlighting.📝 Suggested fix
For the optimization problem (line 18):
-``` +```text maximize nodes[0]For the fixpoint loop (line 49):
-``` +```javascript while (progress) {Also applies to: 49-57
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@libs/pando/engine/doc/optimization.md` around lines 18 - 21, Add appropriate language specifiers to the fenced code blocks: change the optimization problem block containing "maximize nodes[0]" / "subject to nodes[i] >= minimum[i]" to use a "text" (or "python") fence, and change the fixpoint/pseudocode block that starts with "while (progress)" to use "javascript" or "typescript" so syntax highlighting is applied; update those specific fenced blocks in optimization.md accordingly.libs/pando/engine/doc/tags.md (1)
31-40: ⚡ Quick winAdd language specifier to the fenced code block.
Ugh, another all-nighter debugging docs... anyway, the code block showing the tag database example should specify a language for proper syntax highlighting. Even though it's pseudocode, you could use
jsortypescriptto make it easier to read at 3am.📝 Suggested fix
-``` +```js [ { c1:v1 } <- node1, // entry 1🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@libs/pando/engine/doc/tags.md` around lines 31 - 40, The fenced code block showing the tag database example is missing a language specifier, so update the opening backticks (the triple-backtick fence) to include a language such as js or typescript (e.g., change ``` to ```js) to enable proper syntax highlighting for the example shown in the tag database snippet.libs/pando/doc/dmg-survey.md (1)
16-21: 💤 Low valueConsider adding a language identifier to the code fence.
yawns So I was staring at this at 3am and noticed the code block is missing a language spec. Since it's pseudocode showing the damage formula structure, you could mark it as
textorpseudoto make linters happy (and help syntax highlighters not freak out).Quick fix
-``` +```text finalDmg = baseAmount x dmgBonusMult # 1 + sum(attribute_dmg_ + universal_dmg_) x critMult # lookup(critMode){crit, nonCrit, avg} x incomingMult # defMult x resMult [x takenMult]</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@libs/pando/doc/dmg-survey.mdaround lines 16 - 21, The code fence containing
the pseudocode damage formula (the block starting with "finalDmg = baseAmount"
and the lines using dmgBonusMult, critMult, incomingMult) lacks a language
identifier; update the opening triple-backtick to include a language like "text"
or "pseudo" (e.g., ```text) so linters and syntax highlighters treat it as
plain/pseudocode and stop flagging it.</details> <!-- cr-comment:v1:0bf41407fc7198b6951c8d81 --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@libs/gi/formula/doc/tags.md:
- Line 147: Replace the typo "speficies" with "specifies" in the documentation
string that mentions "Read-sidesheet:speficies the sheets to include in
gathering" (look for the sentence containing thesheet:tag and the misspelled
word) so the line reads "Read-sidesheet:specifies the sheets to include in
gathering".- Line 130: Replace the misspelled word "avilable" with "available" in the
sentence that reads "In this phase, the formulas are more restricted in the
avilable tags (e.g.,qt:prep q:elecannot useele:)" in
libs/gi/formula/doc/tags.md so the sentence reads "In this phase, the formulas
are more restricted in the available tags (e.g.,qt:prep q:elecannot use
ele:)".In
@libs/pando/doc/dmg-survey.md:
- Around line 105-109: The ZZZ count discrepancy comes from measuring different
units (formula-local LATE buffs vs distinct authored buffs); update
libs/pando/doc/dmg-survey.md and/or add a clarifying note referencing
libs/pando/doc/name-scoped-buffs.md to state explicitly what "ZZZ: 260" counts
(e.g., "260 formula-local LATE instances, possibly including duplicates/fanned
targets") and, if possible, add the reconciled numbers (260 LATE instances vs
280 distinct authored buffs, grand total 284) next to the ZZZ row; ensure the
terms "authored vs downstream/fanned vs deduped targets" are defined once in the
doc and link both files to that definition so readers understand which counting
unit each table uses.
Nitpick comments:
In@libs/pando/doc/dmg-survey.md:
- Around line 16-21: The code fence containing the pseudocode damage formula
(the block starting with "finalDmg = baseAmount" and the lines using
dmgBonusMult, critMult, incomingMult) lacks a language identifier; update the
opening triple-backtick to include a language like "text" or "pseudo" (e.g.,stop flagging it. In `@libs/pando/engine/doc/customization.md`: - Around line 6-25: The fenced code blocks containing API signatures (e.g., the blocks with defaultAccu(tag: Tag): BaseRead['ex'], markGathered(...), computeMeta(...), and the CustomInfo/type blocks) lack language hints; edit those triple-backtick fences to include a TypeScript/ts specifier (```typescript or ```ts) so the signatures get proper syntax highlighting while leaving the code content unchanged. In `@libs/pando/engine/doc/optimization.md`: - Around line 18-21: Add appropriate language specifiers to the fenced code blocks: change the optimization problem block containing "maximize nodes[0]" / "subject to nodes[i] >= minimum[i]" to use a "text" (or "python") fence, and change the fixpoint/pseudocode block that starts with "while (progress)" to use "javascript" or "typescript" so syntax highlighting is applied; update those specific fenced blocks in optimization.md accordingly. In `@libs/pando/engine/doc/tags.md`: - Around line 31-40: The fenced code block showing the tag database example is missing a language specifier, so update the opening backticks (the triple-backtick fence) to include a language such as js or typescript (e.g., change ``` to ```js) to enable proper syntax highlighting for the example shown in the tag database snippet. In `@libs/sr/formula/doc/tags.md`: - Around line 29-51: Update the fenced ASCII table code block so the opening triple-backticks include a language tag (e.g., change ``` to ```text) to satisfy the markdown linter; modify the block that documents Desc/sheet/agg/iso/static (the ASCII table around the "The three rendezvous levels" section) so its opening fence specifies a language like "text" while leaving the ASCII art and surrounding prose (references to Desc, sheet, agg, aggStr, iso, isoSum, fixed, prep) unchanged. In `@libs/zzz/formula/doc/glue.md`: - Around line 24-29: The fenced code blocks showing the table starting with "sheet | Team Buff | Disc | Reaction | W-Engine | Char | Custom" in glue.md (and the two other similar code blocks in tags.md) lack language specifiers and trigger markdownlint MD040; update each opening triple-backtick to include the language specifier "text" (i.e., replace ``` with ```text) for those three blocks so the linter stops warning while keeping content unchanged.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID:
468a288e-51bc-4f2b-833e-61803ba58b86📒 Files selected for processing (20)
libs/game-opt/doc/overview.mdlibs/gi/formula/doc/api.mdlibs/gi/formula/doc/tag_arch.mdlibs/gi/formula/doc/tags.mdlibs/gi/wr/doc/overview.mdlibs/pando/doc/README.mdlibs/pando/doc/dmg-survey.mdlibs/pando/doc/name-scoped-buffs.mdlibs/pando/engine/README.mdlibs/pando/engine/doc/customization.mdlibs/pando/engine/doc/nodes.mdlibs/pando/engine/doc/optimization.mdlibs/pando/engine/doc/propagation.mdlibs/pando/engine/doc/tags.mdlibs/pando/engine/doc/usage.mdlibs/sr/formula/doc/api.mdlibs/sr/formula/doc/tags.mdlibs/zzz/formula/doc/api.mdlibs/zzz/formula/doc/glue.mdlibs/zzz/formula/doc/tags.md💤 Files with no reviewable changes (1)
- libs/gi/formula/doc/tag_arch.md
| Tags (such as dmg element `ele:`) are assumed to exist throughout the formula specification, but computing the correct value requires a calculator. | ||
| So it cannot be set prior to calculator creation. | ||
| Instead, we calculate them while the tags are not assumed ready, hence the `prep` phase, identified by `qt:prep`. | ||
| In this phase, the formulas are more restricted in the avilable tags (e.g., `qt:prep q:ele` cannot use `ele:`). |
There was a problem hiding this comment.
Fix typo: "avilable" → "available"
yawns Caught this one at 3am... "avilable" should be "available". My autocorrect is screaming at me just reading this.
✏️ Proposed fix
-In this phase, the formulas are more restricted in the avilable tags (e.g., `qt:prep q:ele` cannot use `ele:`).
+In this phase, the formulas are more restricted in the available tags (e.g., `qt:prep q:ele` cannot use `ele:`).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| In this phase, the formulas are more restricted in the avilable tags (e.g., `qt:prep q:ele` cannot use `ele:`). | |
| In this phase, the formulas are more restricted in the available tags (e.g., `qt:prep q:ele` cannot use `ele:`). |
🧰 Tools
🪛 LanguageTool
[grammar] ~130-~130: Ensure spelling is correct
Context: ...the formulas are more restricted in the avilable tags (e.g., qt:prep q:ele cannot use ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@libs/gi/formula/doc/tags.md` at line 130, Replace the misspelled word
"avilable" with "available" in the sentence that reads "In this phase, the
formulas are more restricted in the avilable tags (e.g., `qt:prep q:ele` cannot
use `ele:`)" in libs/gi/formula/doc/tags.md so the sentence reads "In this
phase, the formulas are more restricted in the available tags (e.g., `qt:prep
q:ele` cannot use `ele:`)".
| - To the entire team (`et:teamBuff`, inside sheets only), | ||
| - To other members (`et:notOwnBuff`, inside sheets only), or | ||
| - To the (common) enemy (`et:enemyDeBuff` inside sheets and `et:enemy` outside sheets). | ||
| - Read-side `sheet:` speficies the sheets to include in gathering, whether to gather |
There was a problem hiding this comment.
Fix typo: "speficies" → "specifies"
Another late-night typo... my fingers do this too when I've been grinding gacha dailies for too long. "speficies" should be "specifies".
✏️ Proposed fix
-- Read-side `sheet:` speficies the sheets to include in gathering, whether to gather
+- Read-side `sheet:` specifies the sheets to include in gathering, whether to gather📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Read-side `sheet:` speficies the sheets to include in gathering, whether to gather | |
| - Read-side `sheet:` specifies the sheets to include in gathering, whether to gather |
🧰 Tools
🪛 LanguageTool
[grammar] ~147-~147: Ensure spelling is correct
Context: ...outside sheets). - Read-sidesheet:` speficies the sheets to include in gathering, whe...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@libs/gi/formula/doc/tags.md` at line 147, Replace the typo "speficies" with
"specifies" in the documentation string that mentions "Read-side `sheet:`
speficies the sheets to include in gathering" (look for the sentence containing
the `sheet:` tag and the misspelled word) so the line reads "Read-side `sheet:`
specifies the sheets to include in gathering".
| | Game | count | layers | | ||
| | --- | --- | --- | | ||
| | ZZZ | 260 | **all LATE**: `combat.*` (dominant `common_dmg_`, `crit_`, `crit_dmg_`, `flat_dmg`, `dazeInc_`, `resIgn_`, `anomBuildup_`), a few `final.crit_/crit_dmg_`, 7x `dmg.mv_mult_` | | ||
| | SR | 1 | `formula.base` (LATE) -- March7th `talentDmg` | | ||
| | GI | 3 | `premod.dmg_` x2, `premod.critRate_` x1 -- Nahida `karma_dmg` (`Nahida.ts:248-249`), Nilou `skill_moon` (`Nilou.ts:220`) | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the actual count of ZZZ formula-local buff entries in name-scoped-buffs.md
echo "=== Counting ZZZ entries in name-scoped-buffs.md ==="
# Count lines between "## zzz" and "## Totals" that appear to be character entries
rg -A 1000 '^## zzz' libs/pando/doc/name-scoped-buffs.md | rg -B 1000 '^## Totals' | grep -E '^\*\*[A-Z]' | wc -l
echo ""
echo "=== Extract totals from both docs ==="
echo "From dmg-survey.md:"
rg 'ZZZ.*260|260.*ZZZ' libs/pando/doc/dmg-survey.md
echo ""
echo "From name-scoped-buffs.md:"
rg 'zzz 280|Grand total' libs/pando/doc/name-scoped-buffs.mdRepository: frzyc/genshin-optimizer
Length of output: 475
Fix ZZZ census mismatch (260 vs 280) by clarifying the counting unit
libs/pando/doc/dmg-survey.mdlists ZZZ as 260 “all LATE” formula-local buffs.libs/pando/doc/name-scoped-buffs.mdreports ZZZ as 280 distinct authored buffs (grand total 284).- The docs are counting different things—reconcile them or explicitly define what each “ZZZ count” includes (authored vs downstream/fanned vs deduped targets), before sleep-deprived me spirals further.
🧰 Tools
🪛 LanguageTool
[grammar] ~108-~108: Ensure spelling is correct
Context: ...| | SR | 1 |formula.base(LATE) -- March7thtalentDmg| | GI | 3 |premod.dmg_` ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@libs/pando/doc/dmg-survey.md` around lines 105 - 109, The ZZZ count
discrepancy comes from measuring different units (formula-local LATE buffs vs
distinct authored buffs); update libs/pando/doc/dmg-survey.md and/or add a
clarifying note referencing libs/pando/doc/name-scoped-buffs.md to state
explicitly what "ZZZ: 260" counts (e.g., "260 formula-local LATE instances,
possibly including duplicates/fanned targets") and, if possible, add the
reconciled numbers (260 LATE instances vs 280 distinct authored buffs, grand
total 284) next to the ZZZ row; ensure the terms "authored vs downstream/fanned
vs deduped targets" are defined once in the doc and link both files to that
definition so readers understand which counting unit each table uses.
1 participant
Describe your changes
Documentation-only PR for the Pando calculation stack — no code changes. Adds a
verified architecture doc set under each lib, indexed by
libs/pando/doc/README.md(a map of the whole set).
libs/pando/engine/): README index +doc/— tags &gathering, node operations, propagation, optimization, a usage walkthrough, and
calculator customization.
gi/sr/zzz): each split intotags.md(tagarchitecture, gathering/glue, and the cycle-prevention discipline) and
api.md(the authoring surface). ZZZ adds a verified
glue.mdgather deep-dive.game-opt/doc/overview.md(game-agnostic layer) andgi/wr/doc/overview.md(legacy WaveRider engine).libs/pando/doc/):dmg-survey.mdandname-scoped-buffs.md.Every
tags.md/api.mdand the engine docs were checked against source(file:line) for both accuracy and completeness: tag categories, the full
qt:vocabulary,
et:/sheet:sets, per-query accumulators, and every glueredirection are enumerated — Pando globals interact, so the enumeration must be
exhaustive. All TODO stubs in the GI tag doc are filled.
Issue or discord link
Testing/validation
Docs-only; no runtime behavior changes. Claims verified against the referenced
source files (
libs/pando/engine/src/**,libs/{gi,sr,zzz}/formula/src/**,libs/game-opt/**/src/**).Checklist before requesting a review (leave this PR as draft if any part of this list is not done.)
yarn run mini-cilocally to validate format and lint.Summary by CodeRabbit
Documentation