# CoH Enhancement Optimizer

A web app to help optimize character enhancement slotting for **City of Heroes: Homecoming**.

## Vision

Rather than just checking a hand-built slotting (like Mids' Reborn does), this app should ultimately let you state a goal — "softcap ranged defense with the fewest slots," "perma-Hasten plus S/L resist cap," "max sustained ST DPS under a 300M influence budget" — and have it search the space of valid IO slottings/sets and propose a build.

## Key decisions so far

- **Core focus:** auto-optimizer/solver (not just a calculator) — the differentiated, hard part.
- **Platform:** web app.
- **Build import:** support importing builds in Mids' Reborn's format, so people can bring in builds they already have instead of re-entering a whole build by hand.

## Project layout

- `docs/` — research notes.
- `data-pipeline/` — Python scripts that convert Mids Reborn's `.mhd` database files into JSON. See `data-pipeline/README.md`.
- `data/` — the generated JSON (gzip-compressed), current as of Homecoming database version `2026.1.1242` (Page 3 / Issue 28). See `data/README.md` for what's in each file. Regenerate via `data-pipeline/build_all.py` whenever Homecoming patches.
- `calc-engine/` — the enhancement/set-bonus/proc-rate math layer, ported from Mids Reborn's C# source and validated against the data above. See `calc-engine/README.md`.
- `build-model/` — internal build representation + the MBD import/export codec, so a real Mids' Reborn build can be loaded and fed straight into the calculation engine. See `build-model/README.md`.
- `optimizer/` — the actual solver: goal presets + simulated annealing search over slottings (and optionally power picks), using the calculation engine as its fitness function. See `optimizer/README.md`.
- `webapp/` — the web UI: a Flask backend (with a self-contained copy of the engine) plus a single-page vanilla HTML/CSS/JS frontend. See `webapp/README.md`.

## Status (updated 2026-09-26)

**Data layer: done.** The full Homecoming power/enhancement database — 61 archetypes, 3,672 powersets, 10,986 powers (each with its full effect list), 1,345 enhancements, 227 enhancement sets with their tiered bonus tables, the Enhancement Diversification schedule tables, and the per-archetype/per-level AttribMod scaling tables — has been converted from Mids Reborn's binary `.mhd` files to clean JSON. Output spot-checked against known game values (ED breakpoints, the Luck of the Gambler set's famous 5-piece recharge bonus, Blaster caps, Fire Blast's stats) and all matched. Full technical detail in `docs/research-data-sources.md`.

**Calculation engine: done.** Given enhancement UIDs slotted into a power, it computes ED-adjusted enhancement values (schedule + relative level + Superior bonus, then the ED diminishing-returns curve); given enhancement UIDs across a whole build, it aggregates set bonuses (tiered piece-count thresholds and Luck-of-the-Gambler-style special/per-piece bonuses) with the Rule of Five enforced; and it computes PPM (procs-per-minute) proc chance including the AoE modifier and the global-recharge-exclusion rule. All validated against real Homecoming data and known community facts (Decimation's +6.25% recharge at 5 pieces, Luck of the Gambler's +7.5% unique recharge, etc.) — see `calc-engine/README.md` for the validation scripts and their results.

**Build model + MBD import/export: done.** An internal build representation (archetype, chosen powersets/powers, per-slot enhancements) that round-trips losslessly through Mids Reborn's `|MBD;...;|` build-share format (Brotli + base64 + a line-wrapped header) — both decode (import) and encode (export) directions work. A synthetic build made of real archetype/powerset/power/enhancement identifiers survives an encode→decode round trip byte-for-byte, every one of its references resolves against the actual parsed database, and it feeds straight into the calculation engine, producing the correct Decimation and Luck of the Gambler set bonuses. See `build-model/README.md` for the validation details and known gaps (legacy MxDz format, pet sub-powers not yet wired up).

**Optimizer: done.** A metaheuristic solver (simulated annealing) that takes a goal (softcap defense, perma-Hasten, max DPS under a slot/budget constraint, etc.) and searches the space of valid slottings, using the calculation engine as its fitness function. See `optimizer/README.md` for the goal presets and validation results.

**Web UI: first version done (build viewer + live stats).** A Flask backend (`webapp/backend/`, with a self-contained copy of the engine under `webapp/backend/engine/`) serves a single-page vanilla HTML/CSS/JS frontend (`webapp/frontend/`). Paste a Mids' Reborn build export and the page shows the build's powers/slotting and its computed Defense/Resistance/MezResist/recharge/regen/recovery stats and active set bonuses (with Rule-of-Five capping flagged), all rendered live from the same calculation engine validated in the earlier phases. Deliberately scoped to import-and-view only for this first version — no slot editor and no "optimize" button yet, so the core loop (import → resolve → compute → render) could be proven end to end before adding search on top of it. See `webapp/README.md` for the Flask-over-FastAPI substitution reasoning (PyPI is unreachable from the dev sandbox) and known gaps.

**Next up:** wire the optimizer into the web UI — a slot editor so slotting can be changed from the page, and an "optimize" button that invokes the solver against a chosen goal and renders the proposed build through the same viewer.

## Roadmap

1. ~~**Data layer**~~ ✅ — parse/convert the `.mhd` database into clean JSON (powers, enhancement sets, set-bonus tables, ED breakpoints, proc PPM rules).
2. ~~**Build model + import**~~ ✅ — internal build representation; MBD codec (both import and export) validated against real database identifiers end to end.
3. ~~**Calculation engine**~~ ✅ — given a build, compute ED-adjusted values, summed set bonuses (with the Rule of Five enforced), and proc rates. Validated against known Homecoming set-bonus/ED facts; a full field-for-field diff against a live Mids Reborn export is still worth doing if a real exported build string ever becomes available to test against.
4. ~~**Optimizer**~~ ✅ — goal presets (softcap defense, perma-Hasten/Dom, max DPS under budget, etc.) via a metaheuristic (simulated annealing) calling the calculation engine as its fitness function.
5. **Web UI** *(current)* — ~~build view, live stat panel~~ ✅; slot editor and "optimize" button still to come; import/export exists in the engine but isn't exposed in the UI yet.
6. **Stretch:** auction-house price integration for budget-constrained optimization; build sharing; "explain this slot" annotations.