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
- 1 skill base-stat entry

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

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.