forge-master/README.md

# Forge Master Strategy Optimizer

A small browser-only webpage for planning Forge Master gear upgrades and sacrifice decisions.

Forge Master characters can equip:

- 8 items
- 1 mount
- 3 pets

Each equipped piece has:

- A base stat: `damage` or `health`
- A base stat value
- 0, 1, or 2 effects depending on rarity

Effects start at `1%` and can be upgraded up to their cap.

## Fixed item base stats

The 8 core item slots are fixed and cannot be renamed or have their base stat edited in the app:

| 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.

## 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 recommends:

1. **What to increase next**
   - Prioritizes effects by actual DPS gain for the selected combat style.
   - Accounts for each effect's remaining room to grow before cap.
   - Shows the DPS gain from the next `+1%` and from upgrading to cap.
   - Crit damage has no DPS value until crit chance is above `0%`.

2. **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 missing effects, low base stat, or low-impact effects.

3. **Overall build summary**
   - Totals base damage and health.
   - Totals effect percentages across all items, mount, and pets.
   - Shows calculated DPS and a defensive score to compare save slots.

## 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%)
  * (1 + double chance%)
  * (1 + crit chance% * crit damage%)
  * skill cooldown multiplier, only for Skill style
```

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 and the marginal DPS gain from the next `+1%` upgrade.

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 first version includes an adjustable strategy profile:

- Balanced
- Damage focused
- Survivability focused
- Skill focused

Each profile changes effect weights used for recommendations. These weights are intentionally transparent in the code so they can be tuned as better Forge Master formulas become known.

## Save slots

All data is saved in `localStorage` only. No server is used.

Features:

- Multiple named save slots
- Save current build to a slot
- Load an existing slot
- Delete a slot
- Automatic draft saving for the current unsaved work

## Import and export

The current build can be backed up or shared as JSON:

- Generate JSON in the text box and copy it.
- Download the current build as a `.json` file.
- Import by pasting JSON into the text box.
- Import by uploading a `.json` file.

Imports accept both the app's wrapped export format and the raw build object. Imported builds are normalized, rendered immediately, and autosaved as the current draft.

## Running locally

Open `index.html` in a browser.

No build step is required.

If serving from a local web server is preferred:

```bash
python3 -m http.server 8080
```

Then open:

```text
http://localhost:8080
```

## Implementation notes

This project is intentionally dependency-free:

- `index.html` contains the page structure.
- `styles.css` contains responsive styling.
- `app.js` contains state management, localStorage persistence, scoring, and recommendations.

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.