Document weapon passive stacks from Rapier runtime - #20
Conversation
…ntime - Add docs/WEAPON-PASSIVE-STACKS.md documenting 9 status effect types - Create api/v1/weapon-passive-stacks.json catalog with design-layer data - Add weapon passives section to docs/index.html with status effect table - Update weaponSkills endpoint docs with archived warning - Point to master-weaponSkills.json as canonical source - Link WEAPON-STATS-ATTRIBUTES.md to passives docs Status effects extracted from source: - Grudge Mark (damage amp, 3 stacks, 6s) - Bleed (physical DoT, 5 stacks, 3-8s) - Burn (fire DoT spreads, 3 stacks, 3-6s) - Poison (nature DoT -healing, 3 stacks, 4-10s) - Chill (slow to freeze, 3 stacks, 8s) - Shock (lightning DoT + interrupt, 3 stacks, 6s) - Lifesteal (on-hit heal, instant) - Rune Stack (power-up, 10 stacks, permanent) - Combo Meter (attack speed, 5 stacks, 5s) Source files: - Design: api/v1/weapons.json, studio-manifest.json - Runtime: threejs-rapier-react-three-controller (NOT YET IMPLEMENTED) - 12 weapon ability bindings with source line references Runtime status: CombatController has health/stamina/poise but no DoT system. StatusEffectController needs implementation. VFX sprites exist for bleed/poison, others needed. No passives invented - all extracted from existing source code. Co-authored-by: Grudge Studio <GrudgeDaDev@users.noreply.github.com>
🤖 CodeAnt AI — Review Status
|
Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
Reviewer's GuideThis documentation-only PR adds a machine-readable weapon passive catalog and comprehensive source-backed documentation for nine passive effects, while publishing the catalog in the docs site, warning that Rapier runtime stack/DoT behavior is not implemented, and clarifying the canonical weapon-skills endpoint. Sequence diagram for documented weapon passive runtime gapsequenceDiagram
participant Weapon as Weapon ability
participant Combat as CombatController
participant Status as Status effect system
participant Target as Target
Weapon->>Combat: applyAttack
Combat-->>Status: [planned stack application]
Status-->>Target: [planned status effect]
loop Combat update
Combat-->>Status: [planned DoT tick and expiration]
Status-->>Target: [planned damage or control effect]
end
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
codeant-ai
Bot
added
the
size:XL
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/index.html" line_range="773-832" />
<code_context>
+ <h3>Status Effect Types</h3>
</code_context>
<issue_to_address>
**nitpick:** The public documentation table omits Combo Meter even though the accompanying documentation and catalog describe it as one of the nine passive effects. Users browsing the API documentation cannot discover that catalog entry from the status-effect table.
**Suggested fix:** Add Combo Meter to the table or explicitly state that the table is intentionally limited to seven effects.
</issue_to_address>Sourcery assessment
Approved.
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| <h3>Status Effect Types</h3> | ||
| <table> | ||
| <tr><th>Effect</th><th>Type</th><th>Max Stacks</th><th>Duration</th><th>Weapon Types</th></tr> | ||
| <tr> | ||
| <td><strong>Grudge Mark</strong></td> | ||
| <td>Damage amp (+5% per stack)</td> | ||
| <td>3</td> | ||
| <td>6s</td> | ||
| <td>Sword, Axe</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Bleed</strong></td> | ||
| <td>Physical DoT</td> | ||
| <td>5</td> | ||
| <td>3–8s</td> | ||
| <td>Dagger, Axe, Sword, Bow</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Burn</strong></td> | ||
| <td>Fire DoT (spreads)</td> | ||
| <td>3</td> | ||
| <td>3–6s</td> | ||
| <td>Axe, Fire Staff, Dagger</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Poison</strong></td> | ||
| <td>Nature DoT (-healing)</td> | ||
| <td>3</td> | ||
| <td>4–10s</td> | ||
| <td>Dagger, Bow, Crossbow</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Chill</strong></td> | ||
| <td>Slow → Freeze</td> | ||
| <td>3</td> | ||
| <td>8s</td> | ||
| <td>Frost Staff</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Shock</strong></td> | ||
| <td>Lightning DoT + interrupt</td> | ||
| <td>3</td> | ||
| <td>6s</td> | ||
| <td>Lightning Staff</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Lifesteal</strong></td> | ||
| <td>On-hit heal</td> | ||
| <td>—</td> | ||
| <td>Instant</td> | ||
| <td>Axe, Sword, Hammer</td> | ||
| </tr> | ||
| <tr> | ||
| <td><strong>Rune Stack</strong></td> | ||
| <td>Power-up (+3% dmg, burst)</td> | ||
| <td>10</td> | ||
| <td>Permanent</td> | ||
| <td>Greatsword (Runic Behemoth)</td> | ||
| </tr> | ||
| </table> |
There was a problem hiding this comment.
nitpick: The public documentation table omits Combo Meter even though the accompanying documentation and catalog describe it as one of the nine passive effects. Users browsing the API documentation cannot discover that catalog entry from the status-effect table.
Suggested fix: Add Combo Meter to the table or explicitly state that the table is intentionally limited to seven effects.
- Remove Combo Meter (not in weapons.json source) - Remove Grudge Mark duration (not specified at :34) - Remove poison healingReduction (not in source) - Fix shock duration to 2-4s per manifest, remove interruptChance - Fix chill to cite actual slow mechanics from :3246 - Fix Runed Great Sword ID and type (was Runic Behemoth) - Fix bleed source: remove :712 (Poison Shiv), add :715 - Remove poison bow/crossbow weaponTypes (only daggers cited) All fields now match cited source lines exactly. Co-authored-by: Grudge Studio <GrudgeDaDev@users.noreply.github.com>
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
| <p class="endpoint-desc">Canonical weapon skills catalog with 300+ skills across weapon types. Each skill includes GRUDGE UUID (SKIL-*), icon, cooldown, mana cost, damage formulas, and stat connections.</p> | ||
|
|
There was a problem hiding this comment.
Suggestion: The page advertises stale catalog totals and an invalid weapon-type allowlist: the canonical JSON currently declares 300 skills across 18 weapon types, including Staff, Mace, Wand, and Claw, not 473 skills across the 24 listed elemental staff and tome variants. Consumers using this section to validate or render supported categories will omit valid categories and expose unsupported ones. Derive these values from the canonical catalog or label them as historical design data. [data type]
Severity Level: Major ⚠️
- ❌ Catalog UIs omit valid canonical weapon categories.
- ⚠️ Consumers expose unsupported documented categories.
- ⚠️ Displayed catalog totals disagree with endpoint metadata.
Prompt for AI Agent 🤖
This is a comment left during a code review.
**Path:** docs/index.html
**Line:** 709:710
**Comment:**
*Data Type: The page advertises stale catalog totals and an invalid weapon-type allowlist: the canonical JSON currently declares 300 skills across 18 weapon types, including Staff, Mace, Wand, and Claw, not 473 skills across the 24 listed elemental staff and tome variants. Consumers using this section to validate or render supported categories will omit valid categories and expose unsupported ones. Derive these values from the canonical catalog or label them as historical design data.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
CodeAnt Nitpicks2 code suggestions1. The documented Bleed eligibility includes a weapon type absent from the passive catalog.Api mismatch · 2. The documented Burn duration allows values that contradict the fixed catalog duration.Api mismatch · |
There was a problem hiding this comment.
🟡 Changes recommended
Several newly published docs/catalog entries contain source-traceability mismatches (weapon names/types and effect metadata not supported by the cited design files), which should be corrected before shipping as a public reference.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR adds a new public design-layer catalog and documentation for weapon passive stack/status effects (DoTs, amplifiers, and other stacks) and links it into the docs site so consumers can discover it alongside the canonical weapon skills and stat-scaling references.
Changes:
- Added
api/v1/weapon-passive-stacks.jsonto expose a status-effect + weapon-binding catalog and runtime integration notes. - Added
docs/WEAPON-PASSIVE-STACKS.mdto document the passive stack system, including runtime gaps and implementation requirements. - Updated
docs/index.htmlanddocs/WEAPON-STATS-ATTRIBUTES.mdto link to the new passive stack documentation and clarify the canonical weapon skills endpoint.
File summaries
| File | Description |
|---|---|
| docs/WEAPON-STATS-ATTRIBUTES.md | Adds a link to the new passive stacks documentation. |
| docs/WEAPON-PASSIVE-STACKS.md | New long-form documentation describing passive stack effects and runtime status/requirements. |
| docs/index.html | Adds site navigation + endpoint docs for the new passive stack catalog and an archived warning for legacy weapon skills. |
| api/v1/weapon-passive-stacks.json | New API JSON catalog enumerating status effects and weapon ability bindings. |
Review details
Suppressed comments (3)
docs/index.html:715
- The "Response Structure" example for
/api/v1/master-weaponSkills.jsondoes not match the actualapi/v1/master-weaponSkills.jsonschema (e.g., the file reportsversion: 3.1.0andtotalSkills: 300, and usestotalWeaponTypes+ nestedweaponTypes[].slots[].skills[]withuuid, not the legacy-looking structure shown here). This will mislead consumers of the new canonical endpoint docs; consider regenerating this snippet directly from the current JSON or updating it to the real top-level fields and nesting.
<h3>Response Structure</h3>
<pre><code>{
"version": "1.0.0",
"totalSkills": 473,
"weaponTypes": [
docs/WEAPON-PASSIVE-STACKS.md:106
- The "Axe — Burn / Lifesteal" example cites
api/v1/weapons.json:246forFlame Slash, but line 246 is on the swordEmberclad(not an axe), andapi/v1/weapons.jsondoes not contain an "Ember Axe" weapon. Consider renaming this subsection and the cited weapon so the example matches the design layer source.
**Source:** `api/v1/weapons.json:246,377` (Ember Axe, Veinreaver)
| Effect | Apply Condition | Duration | Max Stacks | Notes |
|--------|----------------|----------|-----------|-------|
docs/WEAPON-PASSIVE-STACKS.md:147
- In the passive trigger table,
Flame Slashis attributed to Axe at:246andRunic Cleaveis attributed to Hammer at:2904, but inapi/v1/weapons.jsonline 246 is within the swordEmbercladentry and line 2904 is within the greatswordRuned Great Swordentry. Updating these weapon types avoids misclassifying the design references.
| Axe | Blood Harvest | Lifesteal AoE | N/A | `:377` |
| Bow | Crimson Shot | Bleed (single target) | 3 | `:1471` |
| Staff (Fire) | Fire Bolt | Burn stack | 3 | `:2234` |
| Staff (Fire) | Flame Nova | Explode all burns | N/A | `:2242` |
| Staff (Frost) | Frost Bolt | Chill stack → freeze | 3 | `:2367` |
| Staff (Lightning) | Thunder Bolt | Shock stack | 3 | `:2633` |
| Greatsword | Runic Cleave | Rune Stack (+3% dmg) | 10 | `:2904` |
- Files reviewed: 4/4 changed files
- Comments generated: 11
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| <td>Damage amp (+5% per stack)</td> | ||
| <td>3</td> | ||
| <td>6s</td> | ||
| <td>Sword, Axe</td> | ||
| </tr> |
| }, | ||
| "maxStacks": 3, | ||
| "duration": 6.0, | ||
| "weaponTypes": ["sword", "axe"], | ||
| "sources": { |
| <td><strong>Burn</strong></td> | ||
| <td>Fire DoT (spreads)</td> | ||
| <td>3</td> | ||
| <td>3–6s</td> | ||
| <td>Axe, Fire Staff, Dagger</td> |
| <tr><td>Shadow Fang</td><td>Crimson Stab</td><td>Bleed</td><td><code class="inline-code">weapons.json:550</code></td></tr> | ||
| <tr><td>Venom Fang</td><td>Poison Shiv</td><td>Poison</td><td><code class="inline-code">weapons.json:712</code></td></tr> | ||
| <tr><td>Ember Axe</td><td>Flame Slash</td><td>Burn</td><td><code class="inline-code">weapons.json:246</code></td></tr> | ||
| <tr><td>Fire Staff</td><td>Fire Bolt</td><td>Burn</td><td><code class="inline-code">weapons.json:2234</code></td></tr> | ||
| <tr><td>Fire Staff</td><td>Flame Nova</td><td>Explode all burns</td><td><code class="inline-code">weapons.json:2242</code></td></tr> |
| <tr><td>Frost Staff</td><td>Frost Bolt</td><td>Chill</td><td><code class="inline-code">weapons.json:2367</code></td></tr> | ||
| <tr><td>Lightning Staff</td><td>Thunder Bolt</td><td>Shock</td><td><code class="inline-code">weapons.json:2633</code></td></tr> | ||
| <tr><td>Runic Behemoth</td><td>Runic Cleave</td><td>Rune Stack</td><td><code class="inline-code">weapons.json:2904</code></td></tr> |
| "maxStacks": 3, | ||
| "duration": 6.0, | ||
| "damageType": "fire", | ||
| "weaponTypes": ["axe", "staff_fire", "dagger"], | ||
| "vfxAsset": "/sprites/effects/pixel/16_sunburn_spritesheet.png", |
| "description": "Lightning damage with interrupt chance", | ||
| "applyCondition": "on_hit", | ||
| "effect": { | ||
| "damagePerTick": null, | ||
| "tickInterval": 1.0, | ||
| "damageType": "lightning", | ||
| "interruptChance": 0.15 | ||
| }, | ||
| "maxStacks": 3, | ||
| "duration": 6.0, | ||
| "damageType": "lightning", |
| "weaponTypes": ["greatsword"], | ||
| "weaponSpecific": ["Runic Behemoth"], | ||
| "sources": { |
| ### Dagger — Bleed / Poison | ||
|
|
||
| **Source:** `api/v1/weapons.json:548,712` (Shadow Fang, Venom Fang) | ||
|
|
||
| | Effect | Apply Condition | Duration | Max Stacks | Damage Type | |
- Grudge Mark: duration null (not specified at :34) - Shock: 2-4s per manifest, no interrupt - Chill: 15%/stack max 45% slow from :3246, not freeze - Runed Great Sword (was Runic Behemoth) - Poison: dagger only (no bow/crossbow) - Drop example duration 6.0 from Grudge Mark - Fix MD: Frost Bolt chill stack (not freeze) at :2367 All fields match cited source lines. Co-authored-by: Grudge Studio <GrudgeDaDev@users.noreply.github.com>
- Chill: type slow (not slow_to_freeze), description no freeze - Chill: duration 3.0s to match :3246 (3s/stack), not 8s - Shock: description drop interrupt mention All fields match source. Runtime NOT_IMPLEMENTED. Co-authored-by: Grudge Studio <GrudgeDaDev@users.noreply.github.com>
🤖 Augment PR SummarySummary: Documents weapon passive-stack concepts and their current runtime status. Changes:
weapons.json and studio-manifest.json, while explicitly marking runtime integration as not implemented.
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| "amplificationPerStack": 0.05 | ||
| }, | ||
| "maxStacks": 3, | ||
| "duration": 6.0, |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:21 turns an unspecified duration into a six-second API guarantee: the cited weapons.json:34 only says that Vengeful Slash builds a Grudge Mark (max 3). Consumers will therefore expire this effect even though the documented design source provides no expiry.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| "maxStacks": 5, | ||
| "duration": 8.0, | ||
| "damageType": "physical", | ||
| "weaponTypes": ["dagger", "axe", "sword"], |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:43 omits bow, although this same payload binds bow-crimson / Crimson Shot to bleed at line 250. Clients filtering effects by weaponTypes will exclude a binding the catalog itself declares.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| "applyCondition": "on_hit", | ||
| "effect": { | ||
| "slowPerStack": 0.15, | ||
| "freezeAtStacks": 3, |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:108 documents a freeze threshold that the cited source does not contain: weapons.json:3246 specifies a 15% slow for 3 seconds that stacks three times to 45%, not freezing at three stacks. This makes the catalog advertise a crowd-control effect absent from its design source.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| "damagePerTick": null, | ||
| "tickInterval": 1.0, | ||
| "damageType": "lightning", | ||
| "interruptChance": 0.15 |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:130 adds a 15% interrupt chance with no supporting source; studio-manifest.json:252 describes Shock as damage over time that chains nearby, and weapons.json:2633 only establishes a three-stack Shock application. This publishes behavior that differs from both cited definitions.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| } | ||
| ], | ||
| "weaponPassiveBindings": [ | ||
| { |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:208 is not an identifier from either declared authority: the cited design record is bloodfeud-blade, while runtime weapon identities are ITEM-* records. Consumers cannot use these synthetic weaponId values to join this catalog to the stated source catalogs.
Severity: medium
Other Locations
api/v1/weapon-passive-stacks.json:215api/v1/weapon-passive-stacks.json:222api/v1/weapon-passive-stacks.json:229api/v1/weapon-passive-stacks.json:236api/v1/weapon-passive-stacks.json:243api/v1/weapon-passive-stacks.json:250api/v1/weapon-passive-stacks.json:257api/v1/weapon-passive-stacks.json:264api/v1/weapon-passive-stacks.json:272api/v1/weapon-passive-stacks.json:279api/v1/weapon-passive-stacks.json:286
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| "source": "api/v1/weapons.json:41" | ||
| }, | ||
| { | ||
| "weaponId": "axe-ember", |
There was a problem hiding this comment.
api/v1/weapon-passive-stacks.json:223 misidentifies its cited source: weapons.json:246 belongs to Emberclad, a 1H sword, rather than an Ember Axe. The advertised weapon-specific passive binding therefore points at a nonexistent source weapon.
Severity: medium
Other Locations
api/v1/weapon-passive-stacks.json:237api/v1/weapon-passive-stacks.json:244api/v1/weapon-passive-stacks.json:251api/v1/weapon-passive-stacks.json:258api/v1/weapon-passive-stacks.json:265api/v1/weapon-passive-stacks.json:273api/v1/weapon-passive-stacks.json:280api/v1/weapon-passive-stacks.json:287
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| <div class="endpoint-header"> | ||
| <span class="method">GET</span> | ||
| <span class="endpoint-url">/api/v1/weaponSkills.json</span> | ||
| <span class="endpoint-url">/api/v1/master-weaponSkills.json</span> |
There was a problem hiding this comment.
docs/index.html:706 switches the endpoint to master-weaponSkills.json, but the response example immediately below is still for the legacy catalog: the canonical response has totalSkills: 300, totalWeaponTypes, uuid, and resourceCost, not the example's 473 skills, skillCount, slot, and manaCost. This leaves API consumers with an incompatible payload contract.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
User description
Overview
Documents 9 weapon passive stack effects (Grudge Mark, bleed, burn, poison, chill, shock, lifesteal, rune stack, combo meter) from the Three.js + Rapier combat runtime. All extracted from existing source code with file path references.
Status
api/v1/weapons.jsonandstudio-manifest.jsonFiles Changed
New
docs/WEAPON-PASSIVE-STACKS.md— Complete documentation with 9 status effects, implementation requirementsapi/v1/weapon-passive-stacks.json— JSON catalog with 12 weapon ability bindingsUpdated
docs/index.html— Added weapon passives section with status effect table, archived weaponSkills warningdocs/WEAPON-STATS-ATTRIBUTES.md— Link to passives docsStatus Effects (9 extracted, none invented)
weapons.json:34weapons.json:41,290,548,712weapons.json:222,246,2234weapons.json:548,712weapons.json:2367weapons.json:2633weapons.json:15,139,352weapons.json:2904-2915Weapon Ability Bindings (12)
With source line references:
Runtime Status
Current in CombatController.ts:
Source:
threejs-rapier-react-three-controller/lib/epicfight/src/combat/CombatController.tsVerification
Related
docs/WEAPON-STATS-ATTRIBUTES.md— Stat scalingapi/v1/master-weaponSkills.json— Canonical skillsthreejs-rapier/docs/STACK_AUDIT_COMBAT_RENDER_DEPLOY.md— Stack auditSummary by Sourcery
Document weapon passive stacks and clarify their design-only runtime status while directing users to canonical weapon skill data.
New Features:
CodeAnt-AI Description
Document weapon passive effects and direct users to canonical weapon skill data
What Changed
Impact
✅ Clearer weapon passive references✅ Fewer incorrect assumptions about runtime support✅ Canonical weapon skill documentation💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.