jacob1123/forge-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure project documentation

Browse Source
This commit is contained in:
Jan Bader
2026-06-16 20:54:02 +02:00
parent f9b56674aa
commit 75fa957981
3 changed files with 296 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+110
View File
@@ -0,0 +1,110 @@
# Agent Handoff Notes
This file is for future coding agents continuing work on the Forge Master Strategy Optimizer.
Do not duplicate game rules, formulas, stat caps, or gameplay assumptions here. Use [GAME.md](GAME.md) as the source of truth for those details. Use [README.md](README.md) for the player-facing overview.
## Project shape
This is a dependency-free static web app:
- `index.html`: page markup and templates.
- `styles.css`: responsive styling.
- `app.js`: all state, rendering, calculations, import/export, save slots, and comparison logic.
- `README.md`: concise player guide.
- `GAME.md`: game mechanics and formulas.
There is no build system, package manager, or test runner currently configured.
## Development workflow
1. Read `GAME.md` before changing calculations.
2. Keep `README.md` player-facing. Avoid implementation or formula detail there unless linking to `GAME.md`.
3. Keep `AGENTS.md` implementation-focused. Avoid repeating game mechanics from `GAME.md`.
4. Prefer small, self-contained commits.
5. Validate with headless Firefox after UI changes:
```bash
firefox --headless --screenshot /tmp/forge-master-check.png file://$PWD/index.html
```
6. Also grep for accidental debug markers:
```bash
grep -R "TO[D]O\|FIX[M]E\|console[.]log" -n . --exclude-dir=.git
```
## State and persistence
The app stores state in browser `localStorage`:
- named save slots use `forgeMasterOptimizer.v1`,
- the autosaved current draft uses `forgeMasterOptimizer.draft.v1`.
Import/export uses a wrapped JSON payload with `app`, `version`, `exportedAt`, and `build`. Raw build objects are also accepted. Keep import normalization backward-compatible when changing state shape.
Important state paths in `app.js`:
- `createDefaultState()` defines new blank state.
- `normalizeState()` handles imported/draft/saved state migration.
- `createDefaultPiece()` defines normal equipment entries.
- `createDefaultNewItem()` defines the New item comparison entry.
## Rendering structure
Rendering is manual DOM construction, not a framework.
Important functions:
- `render()` orchestrates full rendering.
- `renderControls()` updates strategy and combat-style controls.
- `renderGear()` renders current equipment cards.
- `renderNewItemComparison()` renders the replacement comparison card.
- `renderEffectTotals()` renders the total effect tags and marginal max-roll values.
- `renderSacrifices()` renders sacrifice candidates.
Event binding is centralized in `bindEvents()`. Current equipment edits go through `handleGearInput()`. New item edits go through `handleNewItemInput()`.
## Calculation entry points
Use the function names below rather than adding duplicate calculation logic:
- `calculateTotals()` sums base stats and effects.
- `calculateDamageDetails()` returns single hit, crit hit, and DPS.
- `calculateDps()` returns DPS only.
- `calculateRegenDetails()` returns health-regen healing, lifesteal healing, and total Regen.
- `calculateSurvivability()` is used for defensive marginal effect comparison.
- `replacePieceInTotals()` creates totals after replacing one piece.
- `renderReplacementComparison()` displays New item DPS/Regen deltas.
If a calculation changes, update `GAME.md` first or in the same commit.
## Replacement comparison behavior
The New item panel compares one hypothetical roll against a selected current target.
Target behavior is implemented by:
- `getReplacementOptions()`
- `getFixedReplacementTarget()`
- `getReplacementTargetPiece()`
- `createNewItemCandidate()`
When the target is `Pet`, `getReplacementTargetPiece()` chooses the lowest-scoring current pet.
## Validation expectations
Before reporting completion:
- load the page with headless Firefox,
- confirm no obvious render errors in stderr,
- run the debug-marker grep from the workflow section,
- check `git diff --stat`,
- commit changes unless explicitly asked not to.
## Style constraints
- Keep the app dependency-free unless the user explicitly approves adding tooling.
- Keep controls usable in narrow cards and small screens.
- Prefer readable helper functions over inline formula duplication.
- Preserve backward compatibility for saved/imported JSON whenever practical.
GAME.md
+149
View File
@@ -0,0 +1,149 @@
# Forge Master Game Model
This document is the source of truth for game-specific rules, stat assumptions, formulas, and known limitations used by the optimizer.
## Equipment model
A build contains:
- 8 fixed core items
- 1 mount
- 3 pets
- 1 skill base-stat entry
Core item names and base stat types are fixed. Their base values are currently hardcoded from the player's known setup:
| Slot | Item | Base stat |
| --- | --- | ---: |
| Item 1 | Helmet | 1,930,000 health |
| Item 2 | Armor | 1,890,000 health |
| Item 3 | Gloves | 237,000 damage |
| Item 4 | Collar | 237,000 damage |
| Item 5 | Ring | 244,000 damage |
| Item 6 | Weapon | 398,000 damage |
| Item 7 | Boots | 1,850,000 health |
| Item 8 | Belt | 1,150,000 health |
Mounts and pets provide both damage and health base stats. Skill provides damage and health base stats only and has no effects.
## Effects
Items, mounts, and pets may have zero, one, or two effects depending on rarity. Effects start at `1%` and roll up to their cap.
| Effect | Maximum | Optimizer id |
| --- | ---: | --- |
| Crit chance | 12% | `critChance` |
| Crit damage | 80% | `critDamage` |
| Block chance | 5% | `blockChance` |
| Health regen | 4% | `healthRegen` |
| Lifesteal | 20% | `lifesteal` |
| Double chance | 20% | `doubleChance` |
| Damage | 15% | `damage` |
| Melee damage | 50% | `meleeDamage` |
| Ranged damage | 15% | `rangedDamage` |
| Attack speed | 40% | `attackSpeed` |
| Skill damage | 30% | `skillDamage` |
| Skill cooldown reduction | 7% | `skillCooldown` |
| Health | 15% | `health` |
Effects stack additively within their own effect type, then each type contributes as a multiplier in the formulas below.
## DPS formula
The current DPS model is:
```text
single hit = base damage
* (1 + damage%)
* (1 + selected style damage%)
crit hit = single hit * (1 + crit damage%)
DPS = single hit
* ((1 + attack speed%) / 2)
* (1 + double chance%)
* (1 + crit chance% * crit damage%)
* skill cooldown multiplier, only for Skill style
```
Attack speed assumption: base `100%` attack speed means about one hit every two seconds, or `0.5` hits per second. Therefore the attack-rate term is `(1 + attack speed%) / 2`.
Crit damage has no effect until crit chance is above `0%` because the crit multiplier is `1 + crit chance% * crit damage%`.
The selected combat style controls which specialized damage bonus is used:
- Melee uses melee damage.
- Ranged uses ranged damage.
- Skill uses skill damage and skill cooldown reduction.
Skill cooldown multiplier:
```text
1 / max(0.05, 1 - skill cooldown reduction%)
```
The `0.05` floor prevents division by zero or unrealistic infinite DPS if future inputs exceed known caps.
## Regen formula
The Regen metric estimates healing from health regen and lifesteal:
```text
max health = base health * (1 + health%)
health regen healing = max health * health regen%
lifesteal healing = DPS * lifesteal%
regen = health regen healing + lifesteal healing
```
The metric is a comparison estimate, not a full combat simulator.
## Survivability estimate
Some effect-total comparisons still use an estimated survivability value:
```text
survivability = max health
* (1 / max(0.05, 1 - block chance%))
* (1 + health regen%)
* (1 + lifesteal%)
```
This is used only to compare marginal defensive effects in the effect totals panel.
## Additive stacking examples
If a build already has `+100% melee damage`, adding a max `+50% melee damage` changes the melee multiplier from `2.0x` to `2.5x`.
```text
2.5 / 2.0 - 1 = +25% DPS
```
That is why the optimizer displays marginal value, not raw roll value.
## Replacement model
Players cannot directly increment or adjust an existing effect. They roll replacement items and decide whether to swap.
The app models this with the New item comparison panel:
- Select what the new roll would replace.
- Enter the new roll's base stat and effects.
- The app shows DPS and Regen change separately.
- If `Pet` is selected, the app chooses the current worst pet by piece score as the replacement target.
## Profiles
Profiles change sacrifice scoring and tie-breaking weights:
- Lifesteal: prioritizes DPS and lifesteal-based healing.
- Regen: prioritizes health and health-regeneration based healing.
DPS and Regen calculations themselves do not change by profile.
## Known limitations
- Exact Forge Master combat internals are not fully known.
- Enemy defense, uptime, overkill, proc timing, animation locks, and fight length are not modeled.
- Block chance is represented as effective-health style mitigation in survivability estimates only.
- Health regen timing is assumed to be comparable as a per-second-style value.
- Lifesteal assumes all displayed DPS can convert into healing.
README.md
+37 -127
View File
@@ -1,140 +1,52 @@
# Forge Master Strategy Optimizer # Forge Master Strategy Optimizer
A small browser-only webpage for planning Forge Master gear upgrades and sacrifice decisions. A browser-only helper for Forge Master players who want to decide whether a newly rolled item, mount, or pet is worth keeping.
Forge Master characters can equip: Instead of guessing from raw percentages, enter your current build and the app shows how each roll affects the things you care about most:
- 8 items - calculated DPS
- 1 mount - single-hit and crit-hit damage
- 3 pets - estimated Regen from health regen and lifesteal
- 1 skill base-stat entry - marginal value of max-roll effects at your current stat totals
- weakest current sacrifice candidates
- DPS/Regen change if a new roll replaces an existing piece
Each equipped piece has: For the game rules, stat caps, formulas, assumptions, and known limitations used by this app, see [GAME.md](GAME.md).
- A base stat: `damage` or `health` ## How to use it
- A base stat value
- 0, 1, or 2 effects depending on rarity
Effects start at `1%` and can be upgraded up to their cap. 1. Open the page.
2. Enter your current item, mount, pet, and skill base stats/effects.
3. Choose your combat style: Melee, Ranged, or Skill.
4. Choose a strategy profile:
- Lifesteal: DPS plus lifesteal-oriented comparisons.
- Regen: health plus health-regen-oriented comparisons.
5. Check the summary cards for DPS, hit damage, crit damage, and Regen.
6. Use **New item comparison** when you roll a new piece:
- choose what it would replace,
- enter the new roll's value and effects,
- compare DPS and Regen changes before swapping.
7. Use **Best sacrifice candidates** as a quick shortlist of low-value pieces.
## Fixed item base stats When comparing a new pet, choose `Pet`; the app automatically compares against your currently weakest pet.
The 8 core item slots are fixed and cannot be renamed or have their base stat edited in the app. The UI shows the item name directly instead of generic item numbers:
| Slot | Item | Base stat |
| --- | --- | ---: |
| Item 1 | Helmet | 1,930,000 health |
| Item 2 | Armor | 1,890,000 health |
| Item 3 | Gloves | 237,000 damage |
| Item 4 | Collar | 237,000 damage |
| Item 5 | Ring | 244,000 damage |
| Item 6 | Weapon | 398,000 damage |
| Item 7 | Boots | 1,850,000 health |
| Item 8 | Belt | 1,150,000 health |
Mount and pet base stats remain editable, and each has separate damage and health base values because they can provide both stats at once. Skill base stats are entered separately as damage and health and do not have effects.
## Supported effects
| Effect | Maximum |
| --- | ---: |
| Crit chance | 12% |
| Crit damage | 80% |
| Block chance | 5% |
| Health regen | 4% |
| Lifesteal | 20% |
| Double chance | 20% |
| Damage | 15% |
| Melee damage | 50% |
| Ranged damage | 15% |
| Attack speed | 40% |
| Skill damage | 30% |
| Skill cooldown reduction | 7% |
| Health | 15% |
## Optimizer goals
The app lets you enter the current state of all equipment and then evaluates:
1. **What is best to sacrifice instead**
- Scores every equipped piece from its base stat and effects.
- Identifies the lowest-value pieces as likely sacrifice candidates.
- Explains why a piece is weak, such as low base stat or low-impact effects.
2. **Overall build summary**
- Totals base damage and health.
- Totals effect percentages across all items, mount, and pets.
- Shows calculated DPS and estimated regen to compare save slots.
3. **New item replacement comparison**
- Enter a newly rolled item and select what it would replace.
- Shows separate DPS and regen improvement percentages.
- Selecting `Pet` automatically compares against the worst current pet.
## DPS model
The app calculates DPS from entered base damage and offensive effects:
```text
DPS = base damage
* (1 + damage%)
* (1 + selected style damage%)
* ((1 + attack speed%) / 2)
* (1 + double chance%)
* (1 + crit chance% * crit damage%)
* skill cooldown multiplier, only for Skill style
```
The attack speed term assumes the base `100%` attack speed is about one hit every two seconds, or `0.5` hits per second.
The selected combat style controls which specialized damage bonus is used:
- Melee uses melee damage.
- Ranged uses ranged damage.
- Skill uses skill damage and skill cooldown reduction.
All additive bonuses are evaluated against the current total. For example, if the build already has `+100% melee damage`, adding another `+50% melee damage` increases the melee multiplier from `2.0x` to `2.5x`, which is an actual `+25%` DPS increase rather than `+50%`.
Each item effect row displays its actual current DPS contribution. Direct effect upgrading is not modeled because players roll replacement items rather than adjust an existing effect in-place.
The effect totals panel also shows what adding one more maximum-roll effect would do right now. For example, if the build already has `+100% melee damage`, another max `+50% melee damage` changes the multiplier from `2.0x` to `2.5x`, so it displays `+25% DPS`.
Defensive effect totals use an estimated survivability value based on health, block chance, health regen, and lifesteal. This is meant for comparison between effects, not as an exact combat simulator.
## Strategy profile
The app includes two adjustable strategy profiles:
- Lifesteal: prioritizes DPS and lifesteal-based healing.
- Regen: prioritizes health and health-regeneration based healing.
Each profile changes effect weights used for sacrifice scoring and tie-breaking. DPS-based upgrade recommendations still use the current build math directly.
## Regen metric
The Regen card estimates healing from both sources:
```text
regen = max health * health regen% + DPS * lifesteal%
```
The displayed breakdown separates health regen from lifesteal healing.
## Save slots ## Save slots
All data is saved in `localStorage` only. No server is used. All data stays in your browser through `localStorage`. Nothing is uploaded.
Features: You can:
- Multiple named save slots - keep multiple named save slots,
- Save current build to a slot - save the current build,
- Load an existing slot - load an existing slot,
- Delete a slot - delete a slot,
- Automatic draft saving for the current unsaved work - rely on automatic draft saving while editing.
## Import and export ## Import and export
The current build can be backed up or shared as JSON: The Import / Export panel is collapsed by default. Expand it when you want to back up or share a build.
Supported actions:
- Generate JSON in the text box and copy it. - Generate JSON in the text box and copy it.
- Download the current build as a `.json` file. - Download the current build as a `.json` file.
@@ -161,12 +73,10 @@ Then open:
http://localhost:8080 http://localhost:8080
``` ```
## Implementation notes ## Project files
This project is intentionally dependency-free:
- `index.html` contains the page structure. - `index.html` contains the page structure.
- `styles.css` contains responsive styling. - `styles.css` contains responsive styling.
- `app.js` contains state management, localStorage persistence, scoring, and recommendations. - `app.js` contains state management, localStorage persistence, scoring, and calculations.
- `GAME.md` documents game mechanics and formulas.
The optimizer is heuristic, not a perfect simulator. It is designed to be useful immediately and easy to tune once exact Forge Master combat formulas are known. - `AGENTS.md` documents implementation handoff notes for future agents.