phenom/healer-man
1
0 Fork 1
Code Issues 9 Pull Requests 4 Actions Packages Projects Releases 53 Wiki Activity

Update Healer Man server

Browse Source
This commit is contained in:
phenom committed 2026-09-19 21:01:51 -04:00
1 parent f8314e7de1
commit 1fedb9368d
76 files changed
+20556 -2523
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/BALANCE_LAB.md
+163 -5
View File
@@ -50,7 +50,29 @@ build is duplicated inside one party.
The active member is driven by the shared benchmark policy while the other four
use the live companion AI. The healer is the default active member. Use
`--active-slot` to change it.
`--active-slot` to change it. Use `--seat-sweep` to run the same composition
five times with each seat active exactly once. Seat sweeps produce dedicated
`npc_class_specs_across_parties.csv` and
`npc_class_abilities_across_parties.csv` artifacts, so companion comparisons
exclude the active benchmark controller.
Classic specializations expose two named, non-destructive talent profiles: the
default PvE build translated from the pinned AzerothCore Playerbots
configuration at commit `531282e`, and the prior Healer Man executable-first
build. Each profile has a stable generated character name and unique build ID.
Adding another profile therefore does not overwrite either existing build.
Random parties and unselected filler seats use the declared default profile;
named alternatives remain available to specific selection and full coverage.
Run `npm run talents:generate` after intentionally changing the Playerbots
mapping or source; the checked-in snapshot keeps production independent from
the historical checkout. Runtime selection mirrors PlayerbotFactory: it starts
with the closest configured link at or below the tested level (or the first
future link at low levels), then consumes later links if talent points remain;
level 80 starts from the level-80 link. Profile metadata records the applicable
source point count, ranks retained after mapping to the imported Healer Man
talent catalog, and legal fallback points at the tested level. This makes
patched-tree mismatch visible instead of presenting the translation as a
literal Blizzard build.
## GM app and server execution
@@ -62,6 +84,9 @@ category, and a searchable multi-boss picker. The bracket schedules cover level
1 plus every 10 levels, level 1 plus every 5 levels, or every level from 1
through 80. Random mode exposes the requested parties per source; coverage
modes show the derived minimum party count before submission.
The optional **NPC seat audit** multiplies each generated composition across all
five active-seat assignments and makes in-app class/ability analysis prefer the
NPC-only report tables.
**Run on server** sends one allow-listed configuration to the authenticated GM
API. **Run all level brackets** submits the complete schedule atomically and
@@ -161,8 +186,135 @@ deployment exhausts the host watcher limit, the job now reports that specific
startup failure instead of only the subprocess exit code; deploy the no-watch
runtime fix rather than increasing the host's watcher allowance.
## Local graphical runs
On Windows, double-click `scripts/Launch Balance Lab GUI.cmd`. The launcher
starts the local Balance Lab service, opens the existing Balance Lab screen in
the default browser, and keeps the worker service alive in its command window.
Leave that window open until queued simulations finish. The equivalent terminal
command is:
```powershell
npm run balance:gui
```
This development-only mode binds Vite to `127.0.0.1`, accepts API requests only
from the loopback interface, and does not require an online account or GM login.
It uses the same Python controller, TypeScript combat runtime, configuration
form, progress UI, report dashboard, and artifact downloads as the server GM
tool. Job history and reports persist beneath
`artifacts/balance-lab-gui-runtime`; closing the browser does not stop work, but
closing the launcher does. Production and ordinary development modes do not
expose these unauthenticated local routes.
Use **All brackets** in the GUI for every-10-level, every-5-level, or every-level
runs. Use **Run locally** for one level. The runtime status at the top confirms
that Python is available before a run is submitted.
## Repeatable command-line runs
Run the same every-10-level schedule used by the GM screen entirely on the
local development machine:
```powershell
npm run balance:lab:brackets
```
The bracket runner launches the existing Python controller and live TypeScript
runtime; it does not contain a second combat implementation. By default it
tests every WoW specialization at levels 1, 10, 20, and so on through 80, uses
three seeds, allows 80 seconds per fight, and runs up to four level processes
concurrently. Normal Balance Lab options can narrow the run:
```powershell
npm run balance:lab:brackets -- `
--levels 40,50,60,70,80 `
--simulations-per-party 5 `
--boss "stormwind-stockade/entry-1717" `
--boss "stormwind-stockade/entry-1663"
```
Use `--step 5` or `--step 1` for the other GM schedules, `--jobs 1` when the
machine should remain responsive, and `--output-dir <path>` for a stable
comparison location. `npm run balance:lab:regression -- <options>` runs the
same suite but returns a failing exit code when configured pressure or
durability limits are exceeded. The default checks flag boss durability below
20 or above 70 boss-damage seconds, bracket-to-bracket boss-health growth more
than 1.5 times party boss-DPS growth once the preceding bracket reaches that
minimum window, missing incoming damage, and local raw runs where healers are
not required often enough or answer fewer than 60% of five-second pressure
windows.
The bracket root contains `bracket-summary.json`, `.csv`, and `.md`. These show
boss health beside direct boss DPS, incoming DTPS, effective healer HPS,
mitigation, healing coverage, five-second pressure windows answered by healer
throughput, outcomes, and growth relative to the previous tested level.
`heirloom-summary.json` and `.csv` record the resolved item level,
slot count, attributes, ratings, armor, and weapon DPS for every tested build.
Existing reports can be re-analyzed without rerunning combat:
```powershell
python scripts/balance_lab_brackets.py --analyze-existing artifacts/balance-lab-brackets/<run>
```
Balance Lab builds use the `virtual-heirloom` preset. Empty persisted inventory
and equipment assignments mean that no earned drops override the virtual set;
they do not mean that the character is ungeared. Virtual heirlooms fill every
compatible slot with specialization-specific synthetic stats, scale through
level 79, and remain at item level 79 for every party member at level 80. They
are not literal Blizzard heirloom item templates: their custom stat budget is
normalized slightly above the best compatible same-level item in the authored
WotLK-derived loot catalog. The saved catalog and heirloom summary make that
resolved loadout explicit for each local run.
Run selected brackets as a companion-only seat audit:
```powershell
npm run balance:lab:npc-audit -- --levels 20,40,60,80 --simulations-per-party 1
```
NPC raw rows include the named talent build and character, selected rotation
profile/rule/reason counts, profile priority for every available ability,
missing profile actions, GCD uptime, and sampled resource starvation/capping.
Use these diagnostics before changing class coefficients.
## Companion cooldown policy
GM Tools includes a revisioned **Companion cooldown policy** editor. Generic
rules control normal defensive, emergency defensive, healer mitigation, and
major offensive cooldown thresholds. Mechanic rules bind an authored boss
attack to tank-only or party-wide pre-emptive mitigation with configurable lead
time and minimum defensive cooldown length.
Clients load the published policy from `/api/companion-cooldown-policy`; GM
reads/writes use `/api/gm/companion-cooldown-policy`. Server Balance Lab jobs
snapshot the published policy before launch. Local runs use built-in defaults
unless `--cooldown-policy` points to a JSON policy file.
## Companion specialization readiness
The shared revisioned readiness policy classifies all 31 WoW specializations
as Ready, Beta, or Needs Testing. Shipped defaults certify only Protection
Warrior/Aldren, Discipline Priest/Quorin, Marksmanship Hunter/Liora, Fire
Mage/Xavian, and Assassination Rogue/Orin. The main menu, Dungeon setup, and
Balance Lab link to the full Companion Readiness catalog. Players can inspect
it; authenticated GMs can edit and atomically publish the complete policy.
Published policies must retain at least one Ready tank, one Ready healer, and
three distinct Ready damage specializations.
Random and all-eligible WoW runs use Ready specs by default. **Include Beta
Specs** adds Beta specs and is saved per device; explicit targeted runs may
still select a Needs Testing spec, but their filler seats come only from the
eligible Ready/Beta pool. CoA and RoM Balance Lab catalogs are unchanged.
Server jobs snapshot the published policy and beta choice. Local GUI runs use
the revisioned loopback policy saved under
`artifacts/balance-lab-gui-runtime`; corrupt or missing policy files fall back
to shipped defaults.
CLI parity is available through `--include-beta-specs` and
`--companion-readiness-policy <json>`. The JSON may be the published envelope
or its policy config.
List exact party build IDs at a level:
```powershell
@@ -274,6 +426,8 @@ under `parties/<party-id>/` and adds these suite-level files:
| `party_configurations.csv` | Every generated party, its full composition, party DPS, DTPS, deaths, and outcomes. |
| `class_specs_across_parties.csv` | Every class/spec observed across every configuration, compared with its source/role median. |
| `class_abilities_across_parties.csv` | Every learned/available and observed class/spec ability, including unused rows, usage frequency, damage contribution, healing, and absorbs. |
| `npc_class_specs_across_parties.csv` | NPC-only class/spec results, excluding each run's active benchmark-controlled seat. |
| `npc_class_abilities_across_parties.csv` | NPC-only ability, rotation-priority, decision-count, and missing-profile-action results. |
| `class_spec_by_boss.csv` | Every observed class/spec broken down against every boss it fought. |
| `bosses_across_parties.csv` | Every boss aggregated across all generated parties. |
| `boss_by_party.csv` | Every boss and party-configuration pairing. |
@@ -380,16 +534,19 @@ combat tick while retaining their own attack cadence.
- `scripts/balance-lab/runtime.ts`: live headless fight setup, controlled clock,
exact party construction, boss execution, and lossless event attribution.
- `src/ui/BalanceLabScreen.tsx`: GM form, searchable boss selection, persistent
run-history selection, progress display, report loading, and authenticated
run-history selection, progress display, report loading, and server or local
artifact opening/downloading.
- `src/ui/BalanceLabResults.tsx`: in-app graphs, report filters, sorting, summary
cards, and complete boss/class-spec/party tables. Add new dashboard metrics
here only after they exist in `suite-report.json`.
- `src/app/balanceLabClient.ts`: typed GM Balance Lab API client.
- `src/app/balanceLabClient.ts`: typed Balance Lab API client with authenticated
server and loopback-local execution targets.
- `server/balance-lab-jobs.mjs`: validated single and batch job specifications,
bounded parallel process queue, progress parsing, `job.json`
persistence/startup restoration, report-summary extraction, and artifact
allow-list.
- `server/local-balance-lab-api.mjs`: loopback-only, no-login development API
that owns the local job service and persists GUI runs under `artifacts/`.
- `server/server.mjs`: GM-authenticated runtime-preflight, job, status, and
artifact HTTP routes.
- `src/game/benchmark/benchmarkBuilds.ts`: selectable spec builds and legal
@@ -410,8 +567,9 @@ For tool changes, run at minimum:
```powershell
python -m py_compile scripts/balance_lab.py
python -m unittest scripts.test_balance_lab
node --test server/balance-lab-jobs.test.mjs server/server.test.mjs
python -m py_compile scripts/balance_lab_brackets.py
python -m unittest scripts.test_balance_lab scripts.test_balance_lab_brackets
node --test server/local-balance-lab-api.test.mjs server/balance-lab-jobs.test.mjs server/server.test.mjs
python scripts/balance_lab.py --source wow --level 20 --party-mode automatic --party-configurations 2 --boss "gundrak/entry-29932" --simulations-per-party 1 --duration 5 --output-dir artifacts/balance-lab-smoke
npm test -- --run src/game/benchmark src/game/partyStore.test.ts src/game/partyRuntime.test.ts
npm run build
docs/COMBAT_ROTATION_MATRIX.md
+25 -6
View File
@@ -18,7 +18,7 @@ The most useful upstream starting points are `src/Ai/Class/<Class>/Strategy/` fo
| Combo points | Builders run below four points; finishers require at least four points on the current target. |
| Major cooldowns | Offensive cooldowns of 60 seconds or longer are held for bosses or durable targets. |
`playerbots-inspired-v4` also generates legal level-scaled talent plans for all
`playerbots-inspired-v5-ready-five` also generates legal level-scaled talent plans for all
31 classic specializations. Each level-80 plan spends 51 points in the selected
tree and 20 in a compatible secondary tree, prefers executable active talents
and their prerequisites, and sanitizes obsolete imported prerequisite links.
@@ -36,17 +36,17 @@ The leftmost available action wins after reactive rules, learned-talent gating,
| --- | --- | --- |
| Warrior | Arms | Battle Stance; Bloodrage; Rend; Mortal Strike; Bladestorm; Overpower; Execute; Slam; Heroic Strike |
| Warrior | Fury | Berserker/Battle Stance; Bloodrage; Bloodthirst; Whirlwind; Execute; Sunder Armor; Heroic Strike |
| Warrior | Protection | Defensive/Battle Stance; Bloodrage; Shield Slam; Revenge; Devastate; Thunder Clap; Sunder Armor; Heroic Strike |
| Warrior | Protection | Defensive Stance; Shield Block/Last Stand/Shield Wall/Enraged Regeneration; Taunt; Shield Bash; Bloodrage; Shield Slam; Revenge; Devastate; Thunder Clap; Sunder Armor; Heroic Strike |
| Paladin | Holy | Concentration Aura; Blessing of Might; Holy Shock; Flash of Light; Holy Light; Sacred Shield; Judgement of Light |
| Paladin | Protection | Devotion Aura; Blessing of Might; Hammer of the Righteous; Shield of Righteousness; Holy Shield; Consecration; Judgement of Wisdom |
| Paladin | Retribution | Retribution Aura; Blessing of Might; Divine Storm; Crusader Strike; Judgement of Wisdom; Consecration; Exorcism; Hammer of Wrath |
| Hunter | Beast Mastery | Aspect of the Dragonhawk/Hawk; Call Pet; Kill Command; Bestial Wrath; Serpent Sting; Arcane Shot; Multi-Shot; Steady Shot |
| Hunter | Marksmanship | Aspect of the Dragonhawk/Hawk; Call Pet; Kill Shot; Chimera Shot; Aimed Shot; Serpent Sting; Arcane Shot; Steady Shot |
| Hunter | Marksmanship | Aspect of the Dragonhawk/Hawk; Call Pet; Misdirection; Rapid Fire; Readiness; Kill Shot; Chimera Shot; Aimed Shot; Serpent Sting; Arcane Shot; Steady Shot; Silencing Shot; Disengage; Feign Death |
| Hunter | Survival | Aspect of the Dragonhawk/Hawk; Call Pet; Kill Shot; Explosive Shot; Black Arrow; Serpent Sting; Aimed Shot; Arcane Shot; Steady Shot |
| Rogue | Assassination | Envenom; Rupture; Mutilate; Eviscerate; Sinister Strike |
| Rogue | Assassination | Deadly/Instant Poison; Tricks of the Trade; Cold Blood; Envenom; Rupture; Mutilate; Eviscerate; Sinister Strike; Kick; Evasion; Cloak of Shadows; Vanish |
| Rogue | Combat | Killing Spree; Blade Flurry; Eviscerate; Sinister Strike |
| Rogue | Subtlety | Shadow Dance; Rupture; Eviscerate; Hemorrhage; Backstab |
| Priest | Discipline | Inner Fire; Penance; Power Word: Shield; Flash Heal; Greater Heal; Renew |
| Priest | Discipline | Inner Fire; Pain Suppression; Inner Focus; Power Infusion; Shadowfiend; Divine Hymn; Penance; Power Word: Shield; Flash/Greater Heal; Renew; Dispel Magic; Cure Disease; Resurrection |
| Priest | Holy | Inner Fire; Circle of Healing; Prayer of Mending; Flash Heal; Greater Heal; Renew |
| Priest | Shadow | Shadowform; Inner Fire; Vampiric Touch; Devouring Plague; Shadow Word: Pain; Mind Blast; Mind Flay; Shadow Word: Death |
| Death Knight | Blood | Frost Presence (Blood Presence fallback); Heart Strike; Death Strike; Icy Touch; Plague Strike; Death Coil |
@@ -56,7 +56,7 @@ The leftmost available action wins after reactive rules, learned-talent gating,
| Shaman | Enhancement | Windfury Weapon (Rockbiter fallback); Lightning Shield; Feral Spirit; Stormstrike; Lava Lash; Earth Shock; Lightning Bolt |
| Shaman | Restoration | Water Shield; Rockbiter Weapon; Lightning Shield; Riptide; Chain Heal; Lesser Healing Wave; Healing Wave; Earth Shield |
| Mage | Arcane | Mage Armor; Arcane Barrage; Arcane Blast; Arcane Missiles |
| Mage | Fire | Molten Armor; Living Bomb; Pyroblast; Fireball; Scorch; Fire Blast |
| Mage | Fire | Molten Armor; Combustion; Mirror Image; Living Bomb; Fireball; Scorch; Fire Blast; Counterspell; Blink; Ice Block; Fire/Frost Ward |
| Mage | Frost | Frost Armor; Deep Freeze; Frostbolt; Ice Lance; Cone of Cold |
| Warlock | Affliction | Fel Armor; Felhunter; Haunt; Unstable Affliction; Corruption; Curse of Agony; Drain Soul; Shadow Bolt |
| Warlock | Demonology | Fel Armor; Felguard; Metamorphosis; Immolate; Corruption; Shadow Bolt |
@@ -73,3 +73,22 @@ Active abilities fall into one of three audit buckets:
- **Conditional:** executable but selected only by a semantic trigger, such as interrupts, dispels, resurrection, threat control, movement, crowd control, executes, defensives, and long cooldowns.
- **Unsupported:** the catalog has only `unsupported`, `scripted`, or noncombat `utility` payloads, or represents a noncombat summon such as a scouting eye, ritual object, portal, or mount. These remain player-visible when valid but are deliberately excluded from autonomous rotations.
- **Rotation defect:** an executable learned ability with combat semantics that cannot be selected in its valid state. Profile-reference tests, shared-policy scenario tests, party damage audits, and the expanded-class audit treat these as failures.
## Companion readiness gate
The shared WoW NPC policy begins with Protection Warrior (Aldren), Discipline
Priest (Quorin), Marksmanship Hunter (Liora), Fire Mage (Xavian), and
Assassination Rogue (Orin) as Ready. Every other WoW specialization begins as
Needs Testing; Beta is an explicit GM-published opt-in. Readiness filters only
NPC seats. Player character choices, RoM parties, and CoA/RoM Balance Lab
catalogs are unrestricted.
Ready is a certification result, not a tuning label. Its profile must resolve a
legal Playerbots-derived talent allocation and learned ability ranks at each
level bracket; preserve its generated identity, resources, gear, and precombat
setup; execute every conditionally required action; react correctly to threat,
healing, dispels, interrupts, movement, and boss mechanics; and demonstrate
major offensive and defensive cooldown decisions without unexplained idle
windows. Stock abilities whose Talent.dbc node was removed by the patched
client (currently Devastate, Shadowstep, and Lava Lash) use their retained
Spell.dbc source level rather than an impossible dangling talent gate.
package.json
+6
View File
@@ -25,6 +25,7 @@
"coa:icons": "node scripts/export-spell-icons.mjs",
"ascension:talents": "node scripts/generate-wow335-talents.mjs ../wow335a/Interface/AddOns/PlayerBotManager/PBM/PBM_TalentData.lua ../LadiksMPQEditor/client-current/area-52/patch-D/DBFilesClient/Spell.dbc src/game/wow335Talents.generated.ts ../LadiksMPQEditor/client-current/area-52/patch-D/DBFilesClient/Talent.dbc",
"catalogs:shard": "vite-node scripts/generate-catalog-shards.ts",
"talents:generate": "vite-node scripts/generate-party-runtime-talents.ts",
"ascension:sync": "npm run coa:sync && npm run wow335:abilities && npm run ascension:talents && npm run coa:icons && npm run catalogs:shard",
"manastorm:import": "node scripts/manastorm-import/cli.mjs",
"manastorm:forensics": "node scripts/manastorm-import/forensics-cli.mjs",
@@ -117,7 +118,12 @@
"assets:performance:audit": "node scripts/asset-pipeline/audit-environment-performance.mjs",
"balance:benchmark": "vite-node scripts/combat-benchmark/run.ts",
"balance:lab": "python scripts/balance_lab.py",
"balance:lab:brackets": "python scripts/balance_lab_brackets.py",
"balance:lab:npc-audit": "python scripts/balance_lab_brackets.py --seat-sweep",
"balance:gui": "vite --mode balance-lab-gui --host 127.0.0.1 --open",
"balance:lab:regression": "python scripts/balance_lab_brackets.py --check",
"balance:lab:playtest": "node scripts/playtest-balance-lab.cjs",
"readiness:playtest": "node scripts/playtest-companion-readiness.cjs",
"balance:smoke": "vite-node scripts/combat-benchmark/run.ts --class mage --role damage --scenario damage-single-burst --seeds 1 --duration-scale 0.2",
"prebuild": "npm run loot:generate && npm run web:prepare && npm run assets:ktx2:audit && npm run assets:performance:audit",
"build": "node --max-old-space-size=8192 node_modules/typescript/bin/tsc -b && node --max-old-space-size=8192 node_modules/vite/bin/vite.js build",
scripts/Launch Balance Lab GUI.cmd
+3
View File
@@ -0,0 +1,3 @@
@echo off
cd /d "%~dp0\.."
call npm run balance:gui
scripts/balance-lab/runtime.ts
+163 -4
View File
@@ -13,16 +13,23 @@ import {
abilitiesForCharacter,
learnedAbilityForBuild,
preloadAbilityCatalogsForClasses,
type ResourceType,
} from "../../src/game/abilityCatalog";
import { aiHintsForAbility } from "../../src/game/abilityRules";
import { PLAYER_AGGRO_ID } from "../../src/game/aggro";
import { installCombatClock } from "../../src/game/combatClock";
import { companionResourceMaximum } from "../../src/game/combatActorAuthority";
import { subscribeCombatEvents } from "../../src/game/combatEvents";
import { subscribeCombatPresentation } from "../../src/game/combatPresentation";
import { resetCombatSpatialProvider } from "../../src/game/combatSpatial";
import { useCombatStore } from "../../src/game/combatStore";
import { dungeonEnemyScaling } from "../../src/game/dungeonBossScaling";
import { requireDungeonDefinition } from "../../src/game/dungeonRegistry";
import {
resolvedAverageItemLevel,
resolvedEquipmentItems,
resolvedEquipmentStats,
} from "../../src/game/heirloomEquipment";
import {
BOSS_TESTING_CATALOG,
createBossTestingRoom,
@@ -46,10 +53,18 @@ import {
} from "../../src/game/partyStore";
import { specializationsForClass } from "../../src/game/specializationCatalog";
import { BENCHMARK_POLICY_ID, BenchmarkController } from "../../src/game/benchmark/benchmarkController";
import { COMBAT_ROTATION_VERSION } from "../../src/game/combatRotation";
import { COMBAT_ROTATION_VERSION, rotationProfileFor } from "../../src/game/combatRotation";
import { subscribeRotationDecisions } from "../../src/game/rotationTelemetry";
import {
DEFAULT_COMPANION_COOLDOWN_POLICY,
installCompanionCooldownPolicy,
type CompanionCooldownPolicy,
} from "../../src/game/companionCooldownPolicy";
import {
CANONICAL_BENCHMARK_GEAR_PRESET_ID,
loadSelectableBenchmarkBuilds,
selectableBenchmarkBuildCatalog,
type SelectableBenchmarkBuildCatalogEntry,
} from "../../src/game/benchmark/benchmarkBuilds";
import type {
BenchmarkBuildDefinition,
@@ -69,6 +84,7 @@ interface BalanceLabConfig {
readonly activeSlot: number;
readonly bossCategory: BossCategory;
readonly bossKeys?: readonly string[];
readonly cooldownPolicy?: CompanionCooldownPolicy;
}
interface MutableAbilityMetrics {
@@ -101,6 +117,16 @@ interface MutableMemberMetrics {
casts: number;
minimumHealthPercent: number;
readonly abilities: Map<string, MutableAbilityMetrics>;
readonly rotationDecisions: Map<string, {
profileId: string;
ruleId: string;
reason: string;
abilityId: string;
decisions: number;
}>;
gcdObservedMs: number;
gcdBusyMs: number;
readonly resourceSamples: Map<string, { samples: number; starved: number; capped: number }>;
}
const scenario = (durationMs: number): BenchmarkScenarioDefinition => ({
@@ -149,6 +175,28 @@ function bossCatalogRows() {
}));
}
function resolvedGearSummary(build: SelectableBenchmarkBuildCatalogEntry) {
const specialization = specializationsForClass(build.classId)
.find((definition) => definition.displayName === build.orientation);
const context = {
ownerId: `balance-lab-catalog:${build.id}`,
ownerKind: "player" as const,
classId: build.classId,
specializationId: specialization?.id ?? null,
role: build.role,
level: build.level,
};
const items = resolvedEquipmentItems({}, [], context);
return {
presetId: CANONICAL_BENCHMARK_GEAR_PRESET_ID,
model: "synthetic-specialization-heirloom-v1",
itemCount: items.length,
averageItemLevel: resolvedAverageItemLevel({}, [], context),
itemLevels: [...new Set(items.map((item) => item.itemLevel))].sort((left, right) => left - right),
stats: resolvedEquipmentStats({}, [], context),
};
}
async function writeJson(path: string, value: unknown): Promise<void> {
const absolute = resolve(path);
await mkdir(dirname(absolute), { recursive: true });
@@ -171,7 +219,18 @@ function catalogPayload(source: PartyCatalogSource, level: number) {
className: classById(build.classId).name,
role: build.role,
specialization: build.orientation,
label: `${classById(build.classId).name} — ${build.orientation} (${build.role})`,
specializationId: build.specializationId ?? null,
readinessStatus: build.readinessStatus ?? null,
characterName: build.characterName ?? null,
talentBuildId: build.talentBuildId ?? null,
talentBuildName: build.talentBuildName ?? null,
talentBuildSource: build.talentBuildSource ?? null,
talentBuildSourcePointCount: build.talentBuildSourcePointCount ?? null,
talentBuildSourcePointsRetained: build.talentBuildSourcePointsRetained ?? null,
talentBuildFallbackPointCount: build.talentBuildFallbackPointCount ?? null,
defaultTalentBuild: build.defaultTalentBuild ?? true,
label: `${classById(build.classId).name} — ${build.orientation} (${build.role})${build.talentBuildName ? ` — ${build.talentBuildName}` : ""}`,
gear: resolvedGearSummary(build),
})),
bosses: bossCatalogRows(),
};
@@ -207,7 +266,7 @@ function configuredCompanion(
const specialization = specializationsForClass(build.classId)
.find((definition) => definition.displayName === build.orientation);
return createConfiguredPartyMember({
name: `${classById(build.classId).name} ${build.orientation}`,
name: build.characterName ?? `${classById(build.classId).name} ${build.orientation}`,
classId: build.classId,
secondaryClassId: build.secondaryClassId,
specialization: build.orientation,
@@ -255,18 +314,30 @@ function currentHealth(actorId: string): readonly [number, number] {
}
function availableAbilities(build: BenchmarkBuildDefinition) {
const specialization = specializationsForClass(build.classId)
.find((definition) => definition.displayName === build.orientation);
const profile = rotationProfileFor(build.classId, specialization?.id, build.orientation);
return abilitiesForCharacter(build.classId, build.secondaryClassId)
.filter((ability) => !ability.passive)
.map((ability) => {
const ranked = learnedAbilityForBuild(ability, build.level, build.talentRanks);
if (!ranked) return null;
if (ranked.effects.every((effect) => effect.kind === "unsupported" || effect.kind === "scripted")) return null;
const hints = aiHintsForAbility(ranked);
const rotationPriority = profile?.abilityPriority.indexOf(ranked.name) ?? -1;
const conditional = hints.categories.some((category) => [
"area-damage", "control", "dispel", "emergency-heal", "execute", "interrupt",
"mitigation", "resurrection", "taunt",
].includes(category));
return {
abilityId: ranked.id,
abilityName: ranked.name,
icon: ranked.icon,
categories: aiHintsForAbility(ranked).categories,
categories: hints.categories,
cooldownSeconds: ranked.cooldownMs / 1_000,
rotationProfileId: profile?.id ?? null,
rotationPriority: rotationPriority >= 0 ? rotationPriority + 1 : null,
expectedUsage: conditional ? "conditional" : rotationPriority >= 0 ? "profile" : "available",
};
})
.filter((ability) => ability !== null)
@@ -283,6 +354,13 @@ function serializedMember(
activePlayer: metrics.actorId === PLAYER_AGGRO_ID,
actorId: metrics.actorId,
buildId: metrics.build.id,
characterName: metrics.build.characterName ?? null,
talentBuildId: metrics.build.talentBuildId ?? null,
talentBuildName: metrics.build.talentBuildName ?? null,
talentBuildSource: metrics.build.talentBuildSource ?? null,
talentBuildSourcePointCount: metrics.build.talentBuildSourcePointCount ?? null,
talentBuildSourcePointsRetained: metrics.build.talentBuildSourcePointsRetained ?? null,
talentBuildFallbackPointCount: metrics.build.talentBuildFallbackPointCount ?? null,
classId: metrics.build.classId,
className: classById(metrics.build.classId).name,
specialization: metrics.build.orientation,
@@ -309,6 +387,18 @@ function serializedMember(
maxHealth,
minimumHealthPercent: metrics.minimumHealthPercent,
casts: metrics.casts,
gcdUptimePercent: metrics.gcdObservedMs > 0 ? metrics.gcdBusyMs / metrics.gcdObservedMs * 100 : null,
resources: [...metrics.resourceSamples.entries()].map(([resource, samples]) => ({
resource,
samples: samples.samples,
starvedPercent: samples.starved / Math.max(1, samples.samples) * 100,
cappedPercent: samples.capped / Math.max(1, samples.samples) * 100,
})).sort((left, right) => left.resource.localeCompare(right.resource)),
rotationDecisions: [...metrics.rotationDecisions.values()]
.sort((left, right) => right.decisions - left.decisions
|| left.profileId.localeCompare(right.profileId)
|| left.ruleId.localeCompare(right.ruleId)
|| left.abilityId.localeCompare(right.abilityId)),
availableAbilities: availableAbilities(metrics.build),
abilities: [...metrics.abilities.entries()]
.map(([abilityId, ability]) => ({ abilityId, ...ability }))
@@ -377,10 +467,31 @@ async function runBoss(
casts: 0,
minimumHealthPercent: 1,
abilities: new Map(),
rotationDecisions: new Map(),
gcdObservedMs: 0,
gcdBusyMs: 0,
resourceSamples: new Map(),
}));
const byActorId = new Map(memberMetrics.map((metrics) => [metrics.actorId, metrics]));
const actorAlive = new Map<string, boolean>();
const bossAbilities = new Map<string, MutableAbilityMetrics>();
const pressureWindows = new Set<number>();
const healerThroughputWindows = new Set<number>();
const combatWindow = (occurredAt: number) => Math.max(0, Math.floor((occurredAt - 1_000_000) / 5_000));
const stopRotationDecisions = subscribeRotationDecisions((event) => {
const member = byActorId.get(event.actorId);
if (!member) return;
const key = `${event.profileId}\u0000${event.ruleId}\u0000${event.abilityId}`;
const current = member.rotationDecisions.get(key);
if (current) current.decisions += 1;
else member.rotationDecisions.set(key, {
profileId: event.profileId,
ruleId: event.ruleId,
reason: event.reason,
abilityId: event.abilityId,
decisions: 1,
});
});
// Instant resource, aura, pet, and summon actions do not produce the damage,
// healing, absorb, or cast events used by the original report collector.
// Count their completed release once so Balance Lab does not label working
@@ -420,6 +531,7 @@ async function runBoss(
ability.absorbs += event.absorbed;
ability.hits += 1;
bossAbilities.set(key, ability);
if (event.effectiveAmount > 0) pressureWindows.add(combatWindow(event.occurredAt));
}
} else if (event.kind === "healing") {
if (source) {
@@ -431,11 +543,17 @@ async function runBoss(
ability.effectiveHealing += event.effectiveAmount;
ability.overheal += event.overheal;
ability.hits += 1;
if (source.build.role === "healer" && event.effectiveAmount > 0) {
healerThroughputWindows.add(combatWindow(event.occurredAt));
}
}
if (target) target.healingReceived += event.effectiveAmount;
} else if (event.kind === "absorb" && source) {
source.absorbs += event.effectiveAmount;
abilityMetrics(source, event.abilityId).absorbs += event.effectiveAmount;
if (source.build.role === "healer" && event.effectiveAmount > 0) {
healerThroughputWindows.add(combatWindow(event.occurredAt));
}
}
});
@@ -500,6 +618,29 @@ async function runBoss(
combat.advanceMobCombat(now);
advanceDungeonPartyCombat(now);
controller.act(now, activeBuild.role, runScenario, false);
for (const member of usePartyStore.getState().members) {
const metrics = byActorId.get(member.id);
if (!metrics) continue;
// Dead companions cannot act or gain/spend resources. Sampling them until
// the fight ends makes an early death look like an idle/resource deadlock.
if (currentHealth(member.id)[0] <= 0) continue;
metrics.gcdObservedMs += 100;
if (member.globalCooldownEndsAt > now || member.activeCast) metrics.gcdBusyMs += 100;
const resources = new Set<ResourceType>([
...(Object.keys(member.resourcePools) as ResourceType[]),
member.resourceType,
]);
for (const resource of resources) {
const maximum = companionResourceMaximum(member, resource);
if (maximum <= 0) continue;
const value = member.resourcePools[resource] ?? (resource === member.resourceType ? member.resource : 0);
const sample = metrics.resourceSamples.get(resource) ?? { samples: 0, starved: 0, capped: 0 };
sample.samples += 1;
if (value / maximum <= 0.1) sample.starved += 1;
if (value / maximum >= 0.95) sample.capped += 1;
metrics.resourceSamples.set(resource, sample);
}
}
for (const metrics of memberMetrics) {
const [health, maxHealth] = currentHealth(metrics.actorId);
const alive = health > 0;
@@ -527,6 +668,11 @@ async function runBoss(
const rawIncomingDamage = members.reduce((total, member) => total + member.rawDamageTaken, 0);
const partyDamage = members.reduce((total, member) => total + member.damage, 0);
const bossDamage = members.reduce((total, member) => total + member.bossDamage, 0);
const healerResponseWindows = [...pressureWindows].filter((window) => (
healerThroughputWindows.has(window - 1)
|| healerThroughputWindows.has(window)
|| healerThroughputWindows.has(window + 1)
)).length;
return {
bossKey: boss.key,
bossName: boss.name,
@@ -547,6 +693,10 @@ async function runBoss(
incomingDamage,
rawIncomingDamage,
incomingDtps: incomingDamage / Math.max(0.1, activeSeconds),
pressureWindows: pressureWindows.size,
healerThroughputWindows: healerThroughputWindows.size,
healerResponseWindows,
healerResponseRate: healerResponseWindows / Math.max(1, pressureWindows.size),
deaths: members.filter((member) => !member.alive).length,
deathEvents: members.reduce((total, member) => total + member.deathEvents, 0),
bossAttacks: mob?.attackRevision ?? 0,
@@ -557,6 +707,7 @@ async function runBoss(
|| left.abilityId.localeCompare(right.abilityId)),
};
} finally {
stopRotationDecisions();
stopPresentation();
stopEvents();
restoreClock();
@@ -574,6 +725,7 @@ async function simulateConfig(config: BalanceLabConfig, output: string): Promise
throw new Error("activeSlot must be an integer from 0 through 4.");
}
if (!config.seeds.length) throw new Error("At least one simulation seed is required.");
installCompanionCooldownPolicy(config.cooldownPolicy ?? DEFAULT_COMPANION_COOLDOWN_POLICY);
const catalog = selectableBenchmarkBuildCatalog(config.level, classIdsForSource(config.source));
const catalogById = new Map(catalog.map((build) => [build.id, build]));
const selectedClassIds = [...new Set(config.partyBuildIds.map((id) => {
@@ -616,6 +768,13 @@ async function simulateConfig(config: BalanceLabConfig, output: string): Promise
slot,
activePlayer: slot === config.activeSlot,
buildId: build.id,
characterName: build.characterName ?? null,
talentBuildId: build.talentBuildId ?? null,
talentBuildName: build.talentBuildName ?? null,
talentBuildSource: build.talentBuildSource ?? null,
talentBuildSourcePointCount: build.talentBuildSourcePointCount ?? null,
talentBuildSourcePointsRetained: build.talentBuildSourcePointsRetained ?? null,
talentBuildFallbackPointCount: build.talentBuildFallbackPointCount ?? null,
classId: build.classId,
className: classById(build.classId).name,
specialization: build.orientation,
scripts/balance_lab.py
+164 -16
View File
@@ -118,7 +118,7 @@ def build_aliases(build: dict[str, Any]) -> set[str]:
class_name = build["className"]
role = build["role"]
specialization = build["specialization"]
return {
aliases = {
normalized(build["id"]),
normalized(f"{class_id}:{specialization}"),
normalized(f"{class_name}:{specialization}"),
@@ -126,6 +126,11 @@ def build_aliases(build: dict[str, Any]) -> set[str]:
normalized(f"{class_name}:{role}:{specialization}"),
normalized(build["label"]),
}
for value in (build.get("characterName"), build.get("talentBuildId"), build.get("talentBuildName")):
if value:
aliases.add(normalized(str(value)))
aliases.add(normalized(f"{class_id}:{specialization}:{value}"))
return aliases
def resolve_build(selector: str, builds: Sequence[dict[str, Any]]) -> dict[str, Any]:
@@ -135,6 +140,9 @@ def resolve_build(selector: str, builds: Sequence[dict[str, Any]]) -> dict[str,
return matches[0]
if not matches:
raise SystemExit(f"No party member matches '{selector}'. Use --list-members to see valid choices.")
defaults = [match for match in matches if match.get("defaultTalentBuild")]
if len(defaults) == 1:
return defaults[0]
labels = ", ".join(match["label"] for match in matches)
raise SystemExit(f"Party member selector '{selector}' is ambiguous: {labels}")
@@ -156,6 +164,11 @@ def resolve_boss(selector: str, bosses: Sequence[dict[str, Any]]) -> dict[str, A
def random_party(builds: Sequence[dict[str, Any]], seed: int) -> list[dict[str, Any]]:
generator = random.Random(seed)
# Named alternatives remain directly selectable and are covered by "all",
# but ordinary random/filler seats should use the declared default profile.
defaults = [build for build in builds if build.get("defaultTalentBuild")]
if defaults:
builds = defaults
by_role: dict[str, list[dict[str, Any]]] = defaultdict(list)
for build in builds:
by_role[build["role"]].append(build)
@@ -165,6 +178,27 @@ def random_party(builds: Sequence[dict[str, Any]], seed: int) -> list[dict[str,
return [generator.choice(by_role["tank"]), generator.choice(by_role["healer"]), *damage]
def readiness_eligible_builds(
builds: Sequence[dict[str, Any]],
policy: dict[str, Any] | None,
include_beta_specs: bool,
) -> list[dict[str, Any]]:
"""Filter only WoW NPC builds; CoA and RoM catalogs remain unchanged."""
published = policy or {}
config = published.get("config", published)
statuses = config.get("statuses", {}) if isinstance(config, dict) else {}
eligible: list[dict[str, Any]] = []
for build in builds:
if build.get("source") != "wow":
eligible.append(build)
continue
specialization_id = build.get("specializationId")
status = statuses.get(specialization_id, build.get("readinessStatus", "needs-testing"))
if status == "ready" or (include_beta_specs and status == "beta"):
eligible.append(build)
return eligible
def automatic_parties(
builds: Sequence[dict[str, Any]],
sources: Sequence[str],
@@ -206,6 +240,7 @@ def coverage_parties(
sources: Sequence[str],
selected_build_ids: Sequence[str] | None,
seed: int,
filler_builds: Sequence[dict[str, Any]] | None = None,
) -> list[dict[str, Any]]:
"""Build the minimum deterministic party set that covers every requested build."""
requested = set(selected_build_ids) if selected_build_ids is not None else None
@@ -220,7 +255,9 @@ def coverage_parties(
continue
available_by_role: dict[str, list[dict[str, Any]]] = defaultdict(list)
targets_by_role: dict[str, list[dict[str, Any]]] = defaultdict(list)
for build in source_builds:
source_fillers = [build for build in (filler_builds or builds) if build["source"] == source]
default_builds = [build for build in source_fillers if build.get("defaultTalentBuild")]
for build in default_builds or source_fillers:
available_by_role[build["role"]].append(build)
for build in targets:
targets_by_role[build["role"]].append(build)
@@ -794,7 +831,8 @@ def create_reports(raw_path: Path, output_dir: Path) -> dict[str, Any]:
"policyId", "rotationVersion", "bossKey", "bossName", "bossCategory", "dungeonId", "dungeonTitle", "seed", "outcome",
"elapsedSeconds", "timeToDefeatSeconds", "bossLevel", "bossMaxHealth", "bossRemainingHealth",
"partyDamage", "bossDamage", "partyDps", "bossDpsTaken", "incomingDamage", "rawIncomingDamage",
"incomingDtps", "deaths", "deathEvents", "bossAttacks",
"incomingDtps", "pressureWindows", "healerThroughputWindows", "healerResponseWindows",
"healerResponseRate", "deaths", "deathEvents", "bossAttacks",
))
member_abilities = flattened_abilities(raw, "members")
write_csv(output_dir / "member_abilities.csv", member_abilities, (
@@ -822,6 +860,13 @@ def aggregate_class_specs(
"className": class_name,
"specialization": specialization,
"role": role,
"characterName": observations[0].get("characterName"),
"talentBuildId": observations[0].get("talentBuildId"),
"talentBuildName": observations[0].get("talentBuildName"),
"talentBuildSource": observations[0].get("talentBuildSource"),
"talentBuildSourcePointCount": observations[0].get("talentBuildSourcePointCount"),
"talentBuildSourcePointsRetained": observations[0].get("talentBuildSourcePointsRetained"),
"talentBuildFallbackPointCount": observations[0].get("talentBuildFallbackPointCount"),
"partyConfigurations": len({row["partyConfigurationId"] for row in observations}),
"runs": len(observations),
"dps": weighted_rate(observations, "damage"),
@@ -829,6 +874,10 @@ def aggregate_class_specs(
"hps": weighted_rate(observations, "healing"),
"hpsReceived": weighted_rate(observations, "healingReceived"),
"dtps": weighted_rate(observations, "damageTaken"),
"gcdUptimePercent": mean(
float(row["gcdUptimePercent"]) for row in observations
if row.get("gcdUptimePercent") is not None
),
"totalDamage": sum(row["damage"] for row in observations),
"totalDamageTaken": sum(row["damageTaken"] for row in observations),
"totalHealing": sum(row["healing"] for row in observations),
@@ -878,9 +927,19 @@ def aggregate_class_abilities(
available_runs = sum(bool(row["available"]) for row in observations)
class_damage = sum(float(row["damage"]) for row in class_observations)
metadata = next((row for row in observations if row["available"]), observations[0])
rotation_decisions = sum(int(row.get("rotationDecisions", 0)) for row in observations)
effective_healing = sum(float(row["effectiveHealing"]) for row in observations)
absorbs = sum(float(row["absorbs"]) for row in observations)
if active_runs == 0 and available_runs > 0:
# A profile entry is often an alternative, execute, or lower-priority
# fallback and is not required to appear in every short fight. Flag it
# only when the AI repeatedly selected it without any committed cast or
# effect; one terminal decision per run may simply be interrupted by
# the boss dying or the duration limit.
if (active_runs == 0 and available_runs > 0
and rotation_decisions > available_runs
and metadata.get("expectedUsage") == "profile"):
status = "missing-profile-action"
elif active_runs == 0 and available_runs > 0:
status = "unused"
elif effective_damage > 0:
status = "damage"
@@ -900,6 +959,10 @@ def aggregate_class_abilities(
"icon": metadata.get("icon") or "",
"categories": ", ".join(metadata.get("categories") or []),
"cooldownSeconds": metadata.get("cooldownSeconds"),
"rotationProfileId": metadata.get("rotationProfileId"),
"rotationPriority": metadata.get("rotationPriority"),
"expectedUsage": metadata.get("expectedUsage", "available"),
"rotationDecisions": rotation_decisions,
"partyConfigurations": len({row["partyConfigurationId"] for row in class_observations}),
"bosses": len({row["bossKey"] for row in class_observations}),
"runs": len(class_observations),
@@ -920,7 +983,8 @@ def aggregate_class_abilities(
"overheal": sum(float(row["overheal"]) for row in observations),
"absorbs": absorbs,
"status": status,
"unusedAvailable": status == "unused" and available_runs > 0,
"unusedAvailable": status in {"unused", "missing-profile-action"} and available_runs > 0,
"missingProfileAction": status == "missing-profile-action",
})
rows.sort(key=lambda row: (
row["source"], row["className"], row["specialization"],
@@ -1107,6 +1171,8 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
class_groups: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
class_boss_groups: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
class_ability_groups: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
npc_class_groups: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
npc_class_ability_groups: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
policy_ids: set[str] = set()
rotation_versions: set[str] = set()
for entry in entries:
@@ -1157,10 +1223,15 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
)
class_groups[key].append(observation)
class_boss_groups[(*key, run["bossKey"], run["bossName"], run["dungeonTitle"])].append(observation)
if not member.get("activePlayer"):
npc_class_groups[key].append(observation)
available = {
ability["abilityId"]: ability for ability in member.get("availableAbilities", [])
}
observed = {ability["abilityId"]: ability for ability in member.get("abilities", [])}
decisions_by_ability: dict[str, int] = defaultdict(int)
for decision in member.get("rotationDecisions", []):
decisions_by_ability[decision["abilityId"]] += int(decision.get("decisions", 0))
for ability_id in sorted((set(available) | set(observed)) - {"balance-lab-pull"}):
expected = available.get(ability_id, {})
metrics = observed.get(ability_id, {})
@@ -1168,7 +1239,7 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"casts", "hits", "rawDamage", "effectiveDamage", "rawHealing",
"effectiveHealing", "overheal", "absorbs",
))
class_ability_groups[(*key, ability_id)].append({
ability_observation = {
"partyConfigurationId": entry["id"],
"bossKey": run["bossKey"],
"elapsedSeconds": run["elapsedSeconds"],
@@ -1176,6 +1247,10 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"icon": expected.get("icon"),
"categories": expected.get("categories", []),
"cooldownSeconds": expected.get("cooldownSeconds"),
"rotationProfileId": expected.get("rotationProfileId"),
"rotationPriority": expected.get("rotationPriority"),
"expectedUsage": expected.get("expectedUsage", "available"),
"rotationDecisions": decisions_by_ability[ability_id],
"available": ability_id in available,
"used": used,
"casts": metrics.get("casts", 0),
@@ -1186,10 +1261,15 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"effectiveHealing": metrics.get("effectiveHealing", 0),
"overheal": metrics.get("overheal", 0),
"absorbs": metrics.get("absorbs", 0),
})
}
class_ability_groups[(*key, ability_id)].append(ability_observation)
if not member.get("activePlayer"):
npc_class_ability_groups[(*key, ability_id)].append(ability_observation)
bosses, pressure_median = aggregate_boss_runs(compact_runs)
class_specs = aggregate_class_specs(class_groups)
class_abilities = aggregate_class_abilities(class_ability_groups, class_groups)
npc_class_specs = aggregate_class_specs(npc_class_groups)
npc_class_abilities = aggregate_class_abilities(npc_class_ability_groups, npc_class_groups)
class_spec_by_boss = []
for key, observations in class_boss_groups.items():
source, build_id, class_id, class_name, specialization, role, boss_key, boss_name, dungeon_title = key
@@ -1233,10 +1313,14 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"runs": len(compact_runs),
"classSpecs": len(class_specs),
"classAbilities": len(class_abilities),
"npcClassSpecs": len(npc_class_specs),
"npcClassAbilities": len(npc_class_abilities),
"bossPressureMedianDtps": pressure_median,
},
"classSpecs": class_specs,
"classAbilities": class_abilities,
"npcClassSpecs": npc_class_specs,
"npcClassAbilities": npc_class_abilities,
"partyConfigurations": party_rows,
"bosses": bosses,
"bossByParty": boss_by_party,
@@ -1250,16 +1334,34 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"defeatRate", "wipeRate", "averageDeaths", "reportPath",
))
write_csv(output_dir / "class_specs_across_parties.csv", class_specs, (
"source", "buildId", "classId", "className", "specialization", "role", "partyConfigurations",
"runs", "dps", "bossDps", "hps", "hpsReceived", "dtps", "damageVsSourceRoleMedian", "damageFlag",
"source", "buildId", "characterName", "talentBuildId", "talentBuildName", "talentBuildSource",
"talentBuildSourcePointCount", "talentBuildSourcePointsRetained", "talentBuildFallbackPointCount",
"classId", "className", "specialization", "role", "partyConfigurations",
"runs", "dps", "bossDps", "hps", "hpsReceived", "dtps", "gcdUptimePercent", "damageVsSourceRoleMedian", "damageFlag",
"totalDamage", "totalDamageTaken", "totalHealing", "totalHealingReceived", "totalAbsorbs", "deathEvents",
))
write_csv(output_dir / "class_abilities_across_parties.csv", class_abilities, (
"source", "buildId", "classId", "className", "specialization", "role", "abilityId",
"abilityName", "categories", "cooldownSeconds", "partyConfigurations", "bosses", "runs",
"abilityName", "categories", "cooldownSeconds", "rotationProfileId", "rotationPriority",
"expectedUsage", "rotationDecisions", "partyConfigurations", "bosses", "runs",
"availableRuns", "activeRuns", "usageRate", "casts", "castsPerMinute", "hits", "hitsPerRun",
"rawDamage", "effectiveDamage", "dps", "damageShare", "averageDamagePerHit", "rawHealing",
"effectiveHealing", "overheal", "absorbs", "status", "unusedAvailable",
"effectiveHealing", "overheal", "absorbs", "status", "unusedAvailable", "missingProfileAction",
))
write_csv(output_dir / "npc_class_specs_across_parties.csv", npc_class_specs, (
"source", "buildId", "characterName", "talentBuildId", "talentBuildName", "talentBuildSource",
"talentBuildSourcePointCount", "talentBuildSourcePointsRetained", "talentBuildFallbackPointCount",
"classId", "className", "specialization", "role", "partyConfigurations",
"runs", "dps", "bossDps", "hps", "hpsReceived", "dtps", "gcdUptimePercent", "damageVsSourceRoleMedian", "damageFlag",
"totalDamage", "totalDamageTaken", "totalHealing", "totalHealingReceived", "totalAbsorbs", "deathEvents",
))
write_csv(output_dir / "npc_class_abilities_across_parties.csv", npc_class_abilities, (
"source", "buildId", "classId", "className", "specialization", "role", "abilityId",
"abilityName", "categories", "cooldownSeconds", "rotationProfileId", "rotationPriority",
"expectedUsage", "rotationDecisions", "partyConfigurations", "bosses", "runs",
"availableRuns", "activeRuns", "usageRate", "casts", "castsPerMinute", "hits", "hitsPerRun",
"rawDamage", "effectiveDamage", "dps", "damageShare", "averageDamagePerHit", "rawHealing",
"effectiveHealing", "overheal", "absorbs", "status", "unusedAvailable", "missingProfileAction",
))
write_csv(output_dir / "bosses_across_parties.csv", bosses, (
"bossKey", "bossName", "category", "dungeonId", "dungeonTitle", "runs", "incomingDtps",
@@ -1282,7 +1384,8 @@ def create_suite_reports(entries: Sequence[dict[str, Any]], output_dir: Path, le
"dungeonTitle", "seed", "outcome",
"elapsedSeconds", "timeToDefeatSeconds", "bossLevel", "bossMaxHealth", "bossRemainingHealth",
"partyDamage", "bossDamage", "partyDps", "bossDpsTaken", "incomingDamage", "rawIncomingDamage",
"incomingDtps", "deaths", "deathEvents", "bossAttacks",
"incomingDtps", "pressureWindows", "healerThroughputWindows", "healerResponseWindows",
"healerResponseRate", "deaths", "deathEvents", "bossAttacks",
))
return report
@@ -1300,12 +1403,20 @@ def parser() -> argparse.ArgumentParser:
result.add_argument("--party-configurations", type=int, default=10, help="automatic parties per selected source")
result.add_argument("--member", action="append", default=[], help="manual build ID or class:spec selector; repeat five times")
result.add_argument("--active-slot", type=int, help="1-based member controlled by the benchmark policy; defaults to healer")
result.add_argument("--seat-sweep", action="store_true",
help="run every party five times so each member is active once and an NPC four times")
result.add_argument("--boss-category", choices=("all", "wow", "rom"), default="all")
result.add_argument("--boss", action="append", default=[], help="boss key/name selector; repeat as needed; default is every boss")
result.add_argument("--simulations-per-party", type=int, default=3,
help="deterministic runs for each party/boss pairing")
result.add_argument("--seeds", type=parse_seeds, help="explicit comma-separated seeds; overrides --simulations-per-party")
result.add_argument("--duration", type=int, default=60, help="maximum fight duration in seconds")
result.add_argument("--cooldown-policy", type=Path,
help="JSON companion cooldown policy; defaults to the built-in generic rules")
result.add_argument("--companion-readiness-policy", type=Path,
help="published companion readiness policy JSON; defaults to shipped catalog statuses")
result.add_argument("--include-beta-specs", action="store_true",
help="include Beta WoW specs in automatic, random, and filler NPC seats")
result.add_argument("--output-dir", type=Path, help="report directory")
result.add_argument("--list-members", action="store_true")
result.add_argument("--list-bosses", action="store_true")
@@ -1349,14 +1460,32 @@ def main(argv: Sequence[str] | None = None) -> int:
if args.simulations_per_party < 1:
session.close()
raise SystemExit("--simulations-per-party must be at least 1")
if args.seat_sweep and args.active_slot is not None:
session.close()
raise SystemExit("--seat-sweep and --active-slot cannot be used together")
seeds = args.seeds or list(range(1, args.simulations_per_party + 1))
cooldown_policy = None
if args.cooldown_policy:
try:
cooldown_policy = json.loads(args.cooldown_policy.resolve().read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as error:
session.close()
raise SystemExit(f"Could not read --cooldown-policy: {error}") from error
readiness_policy = None
if args.companion_readiness_policy:
try:
readiness_policy = json.loads(args.companion_readiness_policy.resolve().read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as error:
session.close()
raise SystemExit(f"Could not read --companion-readiness-policy: {error}") from error
eligible_builds = readiness_eligible_builds(builds, readiness_policy, args.include_beta_specs)
if args.party_mode == "automatic":
sources = ("wow", "coa", "rom") if args.source == "all" else (args.source,)
if args.spec_selection != "specific" and args.spec:
session.close()
raise SystemExit("--spec values require --spec-selection specific")
if args.spec_selection == "random":
configurations = automatic_parties(builds, sources, args.party_configurations, args.party_seed)
configurations = automatic_parties(eligible_builds, sources, args.party_configurations, args.party_seed)
selected_build_ids: list[str] = []
else:
if args.spec_selection == "specific" and not args.spec:
@@ -1366,10 +1495,11 @@ def main(argv: Sequence[str] | None = None) -> int:
resolve_build(selector, builds)["id"] for selector in args.spec
))
configurations = coverage_parties(
builds,
eligible_builds if args.spec_selection == "all" else builds,
sources,
None if args.spec_selection == "all" else selected_build_ids,
args.party_seed,
eligible_builds,
)
if args.active_slot is not None:
if not 1 <= args.active_slot <= 5:
@@ -1387,7 +1517,7 @@ def main(argv: Sequence[str] | None = None) -> int:
configurations = [{"id": f"{args.source}-party-001", "source": args.source,
"party": party, "activeSlot": active_slot - 1}]
else:
party = random_party(builds, args.party_seed)
party = random_party(eligible_builds, args.party_seed)
active_slot = args.active_slot or next(
(index + 1 for index, build in enumerate(party) if build["role"] == "healer"), 1
)
@@ -1396,6 +1526,17 @@ def main(argv: Sequence[str] | None = None) -> int:
if any(not 0 <= configuration["activeSlot"] < 5 for configuration in configurations):
session.close()
raise SystemExit("--active-slot must be from 1 through 5")
if args.seat_sweep:
configurations = [
{
**configuration,
"id": f"{configuration['id']}-seat-{slot + 1}",
"seatSweepGroupId": configuration["id"],
"activeSlot": slot,
}
for configuration in configurations
for slot in range(5)
]
bosses = [resolve_boss(selector, catalog["bosses"]) for selector in args.boss]
boss_count = len(bosses) if bosses else sum(
args.boss_category == "all" or boss["category"] == args.boss_category for boss in catalog["bosses"]
@@ -1406,13 +1547,16 @@ def main(argv: Sequence[str] | None = None) -> int:
f"x {len(seeds)} runs per party/boss)..."
)
entries = []
automatic = args.party_mode == "automatic"
automatic = args.party_mode == "automatic" or args.seat_sweep
if automatic:
write_json(output_dir / "suite-config.json", {
"schemaVersion": 1,
"policyId": catalog["policyId"],
"rotationVersion": catalog["rotationVersion"],
"mode": "automatic",
"seatSweep": args.seat_sweep,
"includeBetaSpecs": args.include_beta_specs,
"companionReadinessPolicy": readiness_policy,
"specSelection": args.spec_selection,
"selectedBuildIds": selected_build_ids,
"source": args.source,
@@ -1428,6 +1572,7 @@ def main(argv: Sequence[str] | None = None) -> int:
"parties": [{
"id": configuration["id"],
"source": configuration["source"],
"seatSweepGroupId": configuration.get("seatSweepGroupId"),
"activeSlot": configuration["activeSlot"],
"partyBuildIds": [build["id"] for build in configuration["party"]],
} for configuration in configurations],
@@ -1445,6 +1590,9 @@ def main(argv: Sequence[str] | None = None) -> int:
"partyBuildIds": [build["id"] for build in party],
"activeSlot": configuration["activeSlot"],
"bossCategory": args.boss_category,
**({"cooldownPolicy": cooldown_policy} if cooldown_policy else {}),
**({"seatSweepGroupId": configuration["seatSweepGroupId"]}
if configuration.get("seatSweepGroupId") else {}),
**({"bossKeys": [boss["key"] for boss in bosses]} if bosses else {}),
}
config_path = party_dir / "config.json"
scripts/balance_lab_brackets.py
+533
View File
@@ -0,0 +1,533 @@
#!/usr/bin/env python3
"""Run and compare repeatable local Balance Lab level brackets."""
from __future__ import annotations
import argparse
import csv
import json
import math
import os
import subprocess
import sys
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime
from pathlib import Path
from typing import Any, Iterable, Sequence
ROOT = Path(__file__).resolve().parents[1]
BALANCE_LAB = ROOT / "scripts" / "balance_lab.py"
def write_text(path: Path, value: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(value.rstrip() + "\n", encoding="utf-8", newline="\n")
def write_json(path: Path, value: Any) -> None:
write_text(path, json.dumps(value, indent=2, ensure_ascii=False))
def write_csv(path: Path, rows: Sequence[dict[str, Any]], fields: Sequence[str]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("w", encoding="utf-8", newline="") as stream:
writer = csv.DictWriter(stream, fieldnames=fields, extrasaction="ignore", lineterminator="\n")
writer.writeheader()
writer.writerows(rows)
def bracket_levels(step: int) -> list[int]:
if step not in (1, 5, 10):
raise ValueError("Bracket step must be 1, 5, or 10.")
if step == 1:
return list(range(1, 81))
return [1, *range(step, 81, step)]
def parse_levels(value: str) -> list[int]:
try:
levels = sorted({int(part.strip()) for part in value.split(",") if part.strip()})
except ValueError as error:
raise argparse.ArgumentTypeError("Levels must be comma-separated integers.") from error
if not levels or levels[0] < 1 or levels[-1] > 80:
raise argparse.ArgumentTypeError("Levels must be between 1 and 80.")
return levels
def build_balance_lab_command(args: argparse.Namespace, level: int, output_dir: Path) -> list[str]:
command = [
sys.executable,
str(BALANCE_LAB),
"--source", args.source,
"--level", str(level),
"--party-mode", "automatic",
"--spec-selection", args.spec_selection,
"--party-seed", str(args.party_seed),
"--party-configurations", str(args.party_configurations),
"--simulations-per-party", str(args.simulations_per_party),
"--duration", str(args.duration),
"--boss-category", args.boss_category,
"--output-dir", str(output_dir),
]
if args.seeds:
command.extend(("--seeds", args.seeds))
if args.active_slot is not None:
command.extend(("--active-slot", str(args.active_slot)))
if getattr(args, "seat_sweep", False):
command.append("--seat-sweep")
if getattr(args, "cooldown_policy", None):
command.extend(("--cooldown-policy", str(args.cooldown_policy.resolve())))
if getattr(args, "companion_readiness_policy", None):
command.extend(("--companion-readiness-policy", str(args.companion_readiness_policy.resolve())))
if getattr(args, "include_beta_specs", False):
command.append("--include-beta-specs")
for selector in args.spec:
command.extend(("--spec", selector))
for selector in args.boss:
command.extend(("--boss", selector))
return command
def run_level(args: argparse.Namespace, level: int, output_dir: Path) -> tuple[int, subprocess.CompletedProcess[str]]:
result = subprocess.run(
build_balance_lab_command(args, level, output_dir),
cwd=ROOT,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
check=False,
)
return level, result
def weighted_mean(rows: Iterable[dict[str, Any]], field: str, weight: str = "runs") -> float:
materialized = list(rows)
total_weight = sum(float(row.get(weight, 0)) for row in materialized)
if total_weight <= 0:
return 0.0
return sum(float(row.get(field, 0) or 0) * float(row.get(weight, 0)) for row in materialized) / total_weight
def raw_run_totals(report_path: Path) -> dict[str, Any] | None:
raw_paths = sorted(report_path.parent.glob("parties/*/raw-runs.json"))
if not raw_paths:
return None
totals: dict[str, Any] = {
"runs": 0,
"seconds": 0.0,
"partyDamage": 0.0,
"bossDamage": 0.0,
"incomingDamage": 0.0,
"rawIncomingDamage": 0.0,
"defeats": 0,
"wipes": 0,
"incomingRuns": 0,
"healingRequiredRuns": 0,
"minimumHealthPercent": 0.0,
"pressureWindows": 0,
"healerThroughputWindows": 0,
"healerResponseWindows": 0,
"windowMetricsAvailable": False,
}
minimums = []
for raw_path in raw_paths:
raw = json.loads(raw_path.read_text(encoding="utf-8"))
for run in raw["runs"]:
totals["runs"] += 1
totals["seconds"] += float(run["elapsedSeconds"])
totals["partyDamage"] += float(run["partyDamage"])
totals["bossDamage"] += float(run["bossDamage"])
totals["incomingDamage"] += float(run["incomingDamage"])
totals["rawIncomingDamage"] += float(run["rawIncomingDamage"])
totals["defeats"] += run["outcome"] == "defeated"
totals["wipes"] += run["outcome"] == "wipe"
totals["incomingRuns"] += float(run["incomingDamage"]) > 0
healer_throughput = sum(
float(member.get("healing", 0)) + float(member.get("absorbs", 0))
for member in run["members"] if member["role"] == "healer"
)
totals["healingRequiredRuns"] += healer_throughput > 0
if "pressureWindows" in run:
totals["windowMetricsAvailable"] = True
totals["pressureWindows"] += int(run["pressureWindows"])
totals["healerThroughputWindows"] += int(run["healerThroughputWindows"])
totals["healerResponseWindows"] += int(run["healerResponseWindows"])
minimums.append(min(float(member["minimumHealthPercent"]) for member in run["members"]))
totals["minimumHealthPercent"] = sum(minimums) / len(minimums) if minimums else 1.0
return totals
def csv_run_totals(report_path: Path) -> dict[str, Any] | None:
candidates = [
report_path.with_name("suite_runs.csv"),
report_path.parent / f"level-{json.loads(report_path.read_text(encoding='utf-8'))['level']}-suite_runs.csv",
]
run_path = next((path for path in candidates if path.exists()), None)
if run_path is None:
return None
with run_path.open("r", encoding="utf-8", newline="") as stream:
rows = list(csv.DictReader(stream))
return {
"runs": len(rows),
"seconds": sum(float(row["elapsedSeconds"]) for row in rows),
"partyDamage": sum(float(row["partyDamage"]) for row in rows),
"bossDamage": sum(float(row["bossDamage"]) for row in rows),
"incomingDamage": sum(float(row["incomingDamage"]) for row in rows),
"rawIncomingDamage": sum(float(row["rawIncomingDamage"]) for row in rows),
"defeats": sum(row["outcome"] == "defeated" for row in rows),
"wipes": sum(row["outcome"] == "wipe" for row in rows),
"incomingRuns": None,
"healingRequiredRuns": None,
"minimumHealthPercent": None,
"pressureWindows": None,
"healerThroughputWindows": None,
"healerResponseWindows": None,
"windowMetricsAvailable": False,
}
def summarize_report(report_path: Path) -> dict[str, Any]:
report = json.loads(report_path.read_text(encoding="utf-8"))
bosses = report["bosses"]
totals = raw_run_totals(report_path) or csv_run_totals(report_path)
if totals is None:
raise ValueError(f"No raw-runs.json or suite_runs.csv found for {report_path}")
seconds = max(0.1, float(totals["seconds"]))
runs = max(1, int(totals["runs"]))
healers = [row for row in report["classSpecs"] if row["role"] == "healer"]
healer_healing = sum(float(row["totalHealing"]) for row in healers)
healer_absorbs = sum(float(row["totalAbsorbs"]) for row in healers)
party_dps = float(totals["partyDamage"]) / seconds
boss_dps = float(totals["bossDamage"]) / seconds
incoming_dtps = float(totals["incomingDamage"]) / seconds
raw_incoming_dtps = float(totals["rawIncomingDamage"]) / seconds
boss_health = weighted_mean(bosses, "bossMaxHealth")
defeated_runs = sum(float(row["runs"]) * float(row["defeatRate"]) for row in bosses)
defeated_seconds = sum(
float(row["runs"]) * float(row["defeatRate"]) * float(row["averageTimeToDefeat"] or 0)
for row in bosses
)
return {
"level": int(report["level"]),
"reportPath": str(report_path),
"partyConfigurations": int(report["summary"]["partyConfigurations"]),
"bosses": int(report["summary"]["bosses"]),
"runs": int(totals["runs"]),
"bossHealth": boss_health,
"partyDps": party_dps,
"bossDps": boss_dps,
"healthToDpsSeconds": boss_health / max(0.1, boss_dps),
"incomingDtps": incoming_dtps,
"rawIncomingDtps": raw_incoming_dtps,
"mitigationRate": 1 - incoming_dtps / raw_incoming_dtps if raw_incoming_dtps > 0 else 0,
"healerHps": healer_healing / seconds,
"healerAbsorbsPerSecond": healer_absorbs / seconds,
"healingCoverageRate": (healer_healing + healer_absorbs) / max(0.1, float(totals["incomingDamage"])),
"incomingRunRate": (
float(totals["incomingRuns"]) / runs if totals["incomingRuns"] is not None else None
),
"healingRequiredRunRate": (
float(totals["healingRequiredRuns"]) / runs if totals["healingRequiredRuns"] is not None else None
),
"healerResponseRate": (
float(totals["healerResponseWindows"]) / max(1, int(totals["pressureWindows"]))
if totals["windowMetricsAvailable"] else None
),
"healerWindowsPerPressureWindow": (
float(totals["healerThroughputWindows"]) / max(1, int(totals["pressureWindows"]))
if totals["windowMetricsAvailable"] else None
),
"averageMinimumHealthPercent": totals["minimumHealthPercent"],
"defeatRate": float(totals["defeats"]) / runs,
"wipeRate": float(totals["wipes"]) / runs,
"averageTimeToDefeat": defeated_seconds / defeated_runs if defeated_runs > 0 else None,
}
def add_growth_metrics(rows: list[dict[str, Any]]) -> None:
rows.sort(key=lambda row: row["level"])
previous = None
for row in rows:
if previous is None:
row["previousHealthToDpsSeconds"] = None
row["bossHealthGrowth"] = None
row["partyDpsGrowth"] = None
row["durabilityGrowthVsDps"] = None
else:
row["previousHealthToDpsSeconds"] = previous["healthToDpsSeconds"]
health_growth = row["bossHealth"] / max(0.1, previous["bossHealth"])
dps_growth = row["bossDps"] / max(0.1, previous["bossDps"])
row["bossHealthGrowth"] = health_growth
row["partyDpsGrowth"] = dps_growth
row["durabilityGrowthVsDps"] = health_growth / max(0.01, dps_growth)
previous = row
def evaluate_rows(rows: Sequence[dict[str, Any]], args: argparse.Namespace) -> bool:
passed = True
for row in rows:
flags = []
if row["healthToDpsSeconds"] < args.min_health_to_dps_seconds:
flags.append("boss durability below limit")
if row["healthToDpsSeconds"] > args.max_health_to_dps_seconds:
flags.append("boss durability above limit")
growth = row["durabilityGrowthVsDps"]
if (
growth is not None
and growth > args.max_durability_growth
and row["previousHealthToDpsSeconds"] >= args.min_health_to_dps_seconds
):
flags.append("boss health outgrew party DPS")
if row["incomingDtps"] <= 0:
flags.append("boss dealt no effective damage")
if row["healerHps"] <= 0 and row["incomingDtps"] > 0:
flags.append("healer produced no effective healing")
if row["incomingRunRate"] is not None and row["incomingRunRate"] < args.min_incoming_run_rate:
flags.append("too many runs had no incoming damage")
if (
row["healingRequiredRunRate"] is not None
and row["healingRequiredRunRate"] < args.min_healing_required_run_rate
):
flags.append("too many runs required no healer throughput")
if (
row.get("healerResponseRate") is not None
and row["healerResponseRate"] < args.min_healer_response_rate
):
flags.append("healer did not answer enough pressure windows")
row["flags"] = flags
row["passed"] = not flags
passed = passed and not flags
return passed
def discover_reports(directory: Path) -> list[Path]:
candidates = [*directory.glob("level-*/suite-report.json"), *directory.glob("level-*.json")]
reports = []
for path in sorted(set(candidates)):
try:
value = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError):
continue
if "level" in value and "bosses" in value and "classSpecs" in value:
reports.append(path)
return reports
def weapon_dps(weapon: dict[str, Any] | None) -> float:
if not weapon:
return 0.0
return (float(weapon["damageMin"]) + float(weapon["damageMax"])) / 2 / max(
0.1, float(weapon["speedMs"]) / 1_000
)
def collect_heirlooms(report_paths: Sequence[Path]) -> list[dict[str, Any]]:
rows = []
for report_path in report_paths:
catalog_path = report_path.parent / "catalog.json"
if not catalog_path.exists():
continue
catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
for build in catalog["builds"]:
gear = build.get("gear")
if not gear:
continue
stats = gear["stats"]
melee_weapon_dps = weapon_dps(stats.get("meleeWeapon"))
ranged_weapon_dps = weapon_dps(stats.get("rangedWeapon"))
rows.append({
"level": catalog["level"],
"source": build["source"],
"classId": build["classId"],
"className": build["className"],
"specialization": build["specialization"],
"role": build["role"],
"presetId": gear["presetId"],
"model": gear["model"],
"itemCount": gear["itemCount"],
"averageItemLevel": gear["averageItemLevel"],
"strength": stats["strength"],
"agility": stats["agility"],
"stamina": stats["stamina"],
"intellect": stats["intellect"],
"spirit": stats["spirit"],
"attackPower": stats["attackPower"],
"rangedAttackPower": stats["rangedAttackPower"],
"spellPower": stats["spellPower"],
"criticalStrikeRating": stats["criticalStrikeRating"],
"hitRating": stats["hitRating"],
"hasteRating": stats["hasteRating"],
"expertiseRating": stats["expertiseRating"],
"armorPenetrationRating": stats["armorPenetrationRating"],
"defenseRating": stats["defenseRating"],
"dodgeRating": stats["dodgeRating"],
"parryRating": stats["parryRating"],
"blockRating": stats["blockRating"],
"blockValue": stats["blockValue"],
"mp5": stats["mp5"],
"armor": stats["armor"],
"meleeWeaponDps": melee_weapon_dps,
"rangedWeaponDps": ranged_weapon_dps,
"weaponDps": max(melee_weapon_dps, ranged_weapon_dps),
})
return rows
def percent(value: Any) -> str:
return "—" if value is None else f"{float(value) * 100:.1f}%"
def ratio(value: Any) -> str:
return "—" if value is None else f"{float(value):.2f}×"
def markdown_report(rows: Sequence[dict[str, Any]]) -> str:
lines = [
"# Balance Lab local bracket comparison",
"",
"| Level | Boss HP | Boss DPS taken | HP / DPS | Incoming DTPS | Healer HPS | Heal coverage | Pressure windows answered | Defeat | Wipe | HP growth / DPS growth | Result |",
"| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |",
]
for row in rows:
result = "pass" if row["passed"] else "; ".join(row["flags"])
lines.append(
f"| {row['level']} | {row['bossHealth']:.0f} | {row['bossDps']:.1f} | "
f"{row['healthToDpsSeconds']:.1f}s | {row['incomingDtps']:.1f} | {row['healerHps']:.1f} | "
f"{percent(row['healingCoverageRate'])} | {percent(row['healerResponseRate'])} | {percent(row['defeatRate'])} | "
f"{percent(row['wipeRate'])} | {ratio(row['durabilityGrowthVsDps'])} | {result} |"
)
lines.extend([
"",
"`HP / DPS` uses damage applied directly to the boss. `Heal coverage` is effective healer healing plus absorbs divided by effective incoming party damage. Pressure-window response counts a five-second incoming-damage window when healer throughput occurs in that window or an adjacent one. Growth compares each row with the preceding tested level.",
])
return "\n".join(lines)
SUMMARY_FIELDS = (
"level", "partyConfigurations", "bosses", "runs", "bossHealth", "partyDps", "bossDps",
"healthToDpsSeconds", "incomingDtps", "rawIncomingDtps", "mitigationRate", "healerHps",
"healerAbsorbsPerSecond", "healingCoverageRate", "incomingRunRate", "healingRequiredRunRate",
"healerResponseRate", "healerWindowsPerPressureWindow", "averageMinimumHealthPercent",
"defeatRate", "wipeRate", "averageTimeToDefeat",
"previousHealthToDpsSeconds", "bossHealthGrowth",
"partyDpsGrowth", "durabilityGrowthVsDps", "passed", "flags", "reportPath",
)
HEIRLOOM_FIELDS = (
"level", "source", "classId", "className", "specialization", "role", "presetId", "model",
"itemCount", "averageItemLevel", "strength", "agility", "stamina", "intellect", "spirit",
"attackPower", "rangedAttackPower", "spellPower", "criticalStrikeRating", "hitRating",
"hasteRating", "expertiseRating", "armorPenetrationRating", "defenseRating", "dodgeRating",
"parryRating", "blockRating", "blockValue", "mp5", "armor", "meleeWeaponDps",
"rangedWeaponDps", "weaponDps",
)
def parser() -> argparse.ArgumentParser:
result = argparse.ArgumentParser(description="Run and compare local Balance Lab level brackets.")
result.add_argument("--step", type=int, choices=(1, 5, 10), default=10,
help="level bracket step; includes level 1 (default: 10)")
result.add_argument("--levels", type=parse_levels, help="explicit comma-separated levels; overrides --step")
result.add_argument("--source", choices=("wow", "coa", "rom", "all"), default="wow")
result.add_argument("--spec-selection", choices=("random", "all", "specific"), default="all")
result.add_argument("--spec", action="append", default=[])
result.add_argument("--party-seed", type=int, default=1)
result.add_argument("--party-configurations", type=int, default=10)
result.add_argument("--simulations-per-party", type=int, default=3)
result.add_argument("--seeds", help="explicit comma-separated seeds")
result.add_argument("--duration", type=int, default=80)
result.add_argument("--active-slot", type=int)
result.add_argument("--seat-sweep", action="store_true",
help="run every party with each of its five active-seat assignments")
result.add_argument("--cooldown-policy", type=Path)
result.add_argument("--companion-readiness-policy", type=Path)
result.add_argument("--include-beta-specs", action="store_true")
result.add_argument("--boss-category", choices=("all", "wow", "rom"), default="all")
result.add_argument("--boss", action="append", default=[])
result.add_argument("--jobs", type=int, default=min(4, os.cpu_count() or 1),
help="level processes to run concurrently (default: up to 4)")
result.add_argument("--output-dir", type=Path)
result.add_argument("--analyze-existing", type=Path,
help="skip simulations and compare reports already under this directory")
result.add_argument("--check", action="store_true", help="exit nonzero when a regression limit is exceeded")
result.add_argument("--min-health-to-dps-seconds", type=float, default=20)
result.add_argument("--max-health-to-dps-seconds", type=float, default=70)
result.add_argument("--max-durability-growth", type=float, default=1.5)
result.add_argument("--min-incoming-run-rate", type=float, default=0.95)
result.add_argument("--min-healing-required-run-rate", type=float, default=0.8)
result.add_argument("--min-healer-response-rate", type=float, default=0.6)
return result
def main(argv: Sequence[str] | None = None) -> int:
args = parser().parse_args(argv)
if args.spec_selection == "specific" and not args.spec:
raise SystemExit("--spec-selection specific requires at least one --spec value")
if args.jobs < 1:
raise SystemExit("--jobs must be at least 1")
timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
output_dir = (args.analyze_existing or args.output_dir
or ROOT / "artifacts" / "balance-lab-brackets" / timestamp).resolve()
output_dir.mkdir(parents=True, exist_ok=True)
if args.analyze_existing is None:
levels = args.levels or bracket_levels(args.step)
print(f"Running {len(levels)} local brackets with up to {args.jobs} concurrent level processes...")
failures = []
with ThreadPoolExecutor(max_workers=min(args.jobs, len(levels))) as executor:
futures = {
executor.submit(run_level, args, level, output_dir / f"level-{level}"): level
for level in levels
}
for future in as_completed(futures):
level, result = future.result()
if result.returncode == 0:
print(f" level {level}: complete")
else:
failures.append(level)
print(f" level {level}: failed", file=sys.stderr)
if result.stdout.strip():
print(result.stdout.rstrip(), file=sys.stderr)
if result.stderr.strip():
print(result.stderr.rstrip(), file=sys.stderr)
if failures:
raise SystemExit(f"Balance Lab failed at levels: {', '.join(map(str, sorted(failures)))}")
report_paths = discover_reports(output_dir)
if not report_paths:
raise SystemExit(f"No suite reports found under {output_dir}")
rows = [summarize_report(path) for path in report_paths]
add_growth_metrics(rows)
passed = evaluate_rows(rows, args)
serializable_rows = [{**row, "flags": list(row["flags"])} for row in rows]
write_json(output_dir / "bracket-summary.json", {
"schemaVersion": 1,
"generatedAt": datetime.now().astimezone().isoformat(),
"passed": passed,
"levels": [row["level"] for row in rows],
"thresholds": {
"minHealthToDpsSeconds": args.min_health_to_dps_seconds,
"maxHealthToDpsSeconds": args.max_health_to_dps_seconds,
"maxDurabilityGrowth": args.max_durability_growth,
"minIncomingRunRate": args.min_incoming_run_rate,
"minHealingRequiredRunRate": args.min_healing_required_run_rate,
"minHealerResponseRate": args.min_healer_response_rate,
},
"brackets": serializable_rows,
})
write_csv(output_dir / "bracket-summary.csv", [
{**row, "flags": "; ".join(row["flags"])} for row in rows
], SUMMARY_FIELDS)
write_text(output_dir / "bracket-summary.md", markdown_report(rows))
heirlooms = collect_heirlooms(report_paths)
if heirlooms:
write_json(output_dir / "heirloom-summary.json", heirlooms)
write_csv(output_dir / "heirloom-summary.csv", heirlooms, HEIRLOOM_FIELDS)
print(f"Comparison: {output_dir / 'bracket-summary.md'}")
if heirlooms:
print(f"Resolved heirlooms: {output_dir / 'heirloom-summary.csv'}")
return 0 if passed or not args.check else 1
if __name__ == "__main__":
raise SystemExit(main())
scripts/combat-benchmark/run.ts
+1 -1
View File
@@ -151,7 +151,7 @@ async function main(): Promise<void> {
appVersion: packageJson.version,
cohort: {
level: options.level,
gearPresetId: builds[0]?.gearPresetId ?? "coefficient-empty",
gearPresetId: builds[0]?.gearPresetId ?? "virtual-heirloom",
seeds: options.seeds,
durationScale: options.durationScale,
policyId: BENCHMARK_POLICY_ID,
scripts/generate-party-runtime-talents.ts
+265 -9
View File
@@ -1,22 +1,278 @@
import { mkdirSync, writeFileSync } from "node:fs";
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import type { BaseClassId } from "../src/app/characterCatalog";
import {
PARTY_TALENT_SPECIALIZATIONS,
partyTalentAllocationPlan,
} from "../src/game/partyTalents";
import {
allocateTalentPoint,
talentNodesForTree,
talentTreesForClass,
type TalentNodeDefinition,
type TalentRanks,
} from "../src/game/talentCatalog";
const outputPath = resolve("src/game/generated/partyTalentRuntimePlans.json");
const plans = Object.fromEntries(PARTY_TALENT_SPECIALIZATIONS.map(({ classId, specialization }) => [
`${classId}:${specialization}`,
partyTalentAllocationPlan(classId, specialization).map((selection) => selection.nodeId),
const playerbotsConfigPath = resolve(
"../wow-pvt-server-backups-2/azerothcore-wotlk/modules/mod-playerbots/conf/playerbots.conf.dist",
);
const PLAYERBOTS_COMMIT = "531282e";
interface PlayerbotsSpecReference {
readonly classId: BaseClassId;
readonly classNumber: number;
readonly specNumber: number;
readonly specialization: string;
}
interface PlayerbotsMilestone {
readonly level: number;
readonly link: string;
}
interface GeneratedLevelPlan {
readonly minimumLevel: number;
readonly sourceLevels: readonly number[];
readonly sourcePointCount: number;
readonly sourcePointFlags: readonly boolean[];
readonly plan: readonly string[];
}
const PLAYERBOTS_PVE_SPECS: readonly PlayerbotsSpecReference[] = [
["warrior", 1, 0, "Arms"], ["warrior", 1, 1, "Fury"], ["warrior", 1, 2, "Protection"],
["paladin", 2, 0, "Holy"], ["paladin", 2, 1, "Protection"], ["paladin", 2, 2, "Retribution"],
["hunter", 3, 0, "Beast Mastery"], ["hunter", 3, 1, "Marksmanship"], ["hunter", 3, 2, "Survival"],
["rogue", 4, 0, "Assassination"], ["rogue", 4, 1, "Combat"], ["rogue", 4, 2, "Subtlety"],
["priest", 5, 0, "Discipline"], ["priest", 5, 1, "Holy"], ["priest", 5, 2, "Shadow"],
["death-knight", 6, 0, "Blood"], ["death-knight", 6, 1, "Frost"], ["death-knight", 6, 2, "Unholy"],
["shaman", 7, 0, "Elemental"], ["shaman", 7, 1, "Enhancement"], ["shaman", 7, 2, "Restoration"],
["mage", 8, 0, "Arcane"], ["mage", 8, 1, "Fire"], ["mage", 8, 2, "Frost"],
["warlock", 9, 0, "Affliction"], ["warlock", 9, 1, "Demonology"], ["warlock", 9, 2, "Destruction"],
["druid", 11, 0, "Balance"], ["druid", 11, 1, "Feral (Bear)"], ["druid", 11, 2, "Restoration"], ["druid", 11, 3, "Feral (Cat)"],
].map(([classId, classNumber, specNumber, specialization]) => ({
classId: classId as BaseClassId,
classNumber: classNumber as number,
specNumber: specNumber as number,
specialization: specialization as string,
}));
// Stable identities make a build recognizable in logs and leave room for
// multiple builds of the same class/spec without silently replacing one.
const CHARACTER_NAMES = [
"Aldren", "Briala", "Caelen", "Darian", "Elowen", "Faelar", "Gavran", "Helia",
"Ilyra", "Jorren", "Kaelis", "Liora", "Marek", "Nerys", "Orin", "Phaela",
"Quorin", "Rielle", "Soren", "Talia", "Ulric", "Vaela", "Wrenna", "Xavian",
"Ysara", "Zoren", "Arwyn", "Brenna", "Corvin", "Delia", "Edrin", "Fiora",
"Galen", "Hestia", "Isolde", "Jarek", "Kiera", "Lucan", "Mira", "Nolan",
"Oriana", "Perrin", "Quilla", "Ronan", "Selene", "Theron", "Una", "Varen",
"Willow", "Xara", "Yorin", "Zella", "Ansel", "Brynn", "Cyrus", "Dessa",
"Evren", "Freya", "Garrick", "Halen", "Ilara", "Jessa",
] as const;
function specKey(classId: BaseClassId, specialization: string): string {
return `${classId}:${specialization}`;
}
function slug(value: string): string {
return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
}
function parsePlayerbotsConfig(source: string): {
names: ReadonlyMap<string, string>;
links: ReadonlyMap<string, readonly PlayerbotsMilestone[]>;
} {
const names = new Map<string, string>();
const links = new Map<string, PlayerbotsMilestone[]>();
for (const rawLine of source.split(/\r?\n/)) {
const line = rawLine.trim();
const name = /^AiPlayerbot\.PremadeSpecName\.(\d+)\.(\d+)\s*=\s*(.+)$/.exec(line);
if (name) names.set(`${name[1]}:${name[2]}`, name[3].trim());
const link = /^AiPlayerbot\.PremadeSpecLink\.(\d+)\.(\d+)\.(\d+)\s*=\s*([0-9-]+)$/.exec(line);
if (!link) continue;
const key = `${link[1]}:${link[2]}`;
const existing = links.get(key) ?? [];
existing.push({ level: Number(link[3]), link: link[4] });
links.set(key, existing);
}
for (const milestones of links.values()) milestones.sort((left, right) => left.level - right.level);
return { names, links };
}
function orderedTreeNodes(treeId: string): readonly TalentNodeDefinition[] {
return [...talentNodesForTree(treeId)].sort((left, right) => (
left.row - right.row || left.column - right.column || left.index - right.index
));
}
function ranksFromPlayerbotsLink(classId: BaseClassId, link: string): TalentRanks {
const ranks: Record<string, number> = {};
const treeLinks = link.split("-");
for (const [treeIndex, tree] of talentTreesForClass(classId).entries()) {
const digits = treeLinks[treeIndex] ?? "";
for (const [nodeIndex, node] of orderedTreeNodes(tree.id).entries()) {
const digit = Number(digits[nodeIndex] ?? "0");
if (Number.isInteger(digit) && digit > 0) ranks[node.id] = Math.min(node.maxRank, digit);
}
}
return ranks;
}
function desiredNodeOrder(classId: BaseClassId, target: TalentRanks): readonly string[] {
const trees = talentTreesForClass(classId);
const treeScore = new Map(trees.map((tree) => [
tree.id,
orderedTreeNodes(tree.id).filter((node) => (target[node.id] ?? 0) > 0).length,
]));
const treeIndex = new Map(trees.map((tree, index) => [tree.id, index]));
return trees.flatMap((tree) => orderedTreeNodes(tree.id))
.filter((node) => (target[node.id] ?? 0) > 0)
.sort((left, right) => (
(treeScore.get(right.treeId) ?? 0) - (treeScore.get(left.treeId) ?? 0)
|| (treeIndex.get(left.treeId) ?? 0) - (treeIndex.get(right.treeId) ?? 0)
|| left.row - right.row
|| left.column - right.column
|| left.index - right.index
))
.map((node) => node.id);
}
function playerbotsAllocationPlan(
reference: PlayerbotsSpecReference,
milestones: readonly PlayerbotsMilestone[],
): {
readonly plan: readonly string[];
readonly sourcePointCount: number;
readonly sourcePointsRetained: number;
readonly fallbackPointCount: number;
readonly levelPlans: readonly GeneratedLevelPlan[];
} {
if (milestones.length === 0) throw new Error(`No Playerbots links for ${specKey(reference.classId, reference.specialization)}.`);
const targets = milestones.map((milestone) => ({
...milestone,
ranks: ranksFromPlayerbotsLink(reference.classId, milestone.link),
}));
const fallback = partyTalentAllocationPlan(reference.classId, reference.specialization).map((entry) => entry.nodeId);
const levelPlans = targets.map((_, startIndex): GeneratedLevelPlan => {
// PlayerbotFactory walks backward to the closest configured link, then
// applies that link and each later link until the bot runs out of points.
// Level 80 starts at the 80 link directly. A plan variant per configured
// starting link preserves that behavior without storing 80 duplicate plans.
const appliedTargets = targets.slice(startIndex);
const sourceCapacity: Record<string, number> = {};
for (const target of appliedTargets) {
for (const [nodeId, rank] of Object.entries(target.ranks)) {
sourceCapacity[nodeId] = Math.max(sourceCapacity[nodeId] ?? 0, rank);
}
}
const plan: string[] = [];
const sourcePointFlags: boolean[] = [];
let ranks: TalentRanks = {};
for (let point = 1; point <= 71; point += 1) {
const level = point + 9;
let allocated = false;
for (const target of appliedTargets) {
for (const nodeId of desiredNodeOrder(reference.classId, target.ranks)) {
if ((ranks[nodeId] ?? 0) >= (target.ranks[nodeId] ?? 0)) continue;
const result = allocateTalentPoint(ranks, reference.classId, nodeId, level);
if (!result.ok) continue;
ranks = result.ranks;
plan.push(nodeId);
sourcePointFlags.push(true);
allocated = true;
break;
}
if (allocated) break;
}
if (!allocated) {
for (const nodeId of fallback) {
const result = allocateTalentPoint(ranks, reference.classId, nodeId, level);
if (!result.ok) continue;
ranks = result.ranks;
plan.push(nodeId);
sourcePointFlags.push(false);
allocated = true;
break;
}
}
if (!allocated) throw new Error(`Could not allocate Playerbots point ${point} for ${specKey(reference.classId, reference.specialization)}.`);
}
return {
minimumLevel: startIndex === 0 ? 1 : targets[startIndex].level,
sourceLevels: appliedTargets.map((target) => target.level),
sourcePointCount: Object.values(sourceCapacity).reduce((total, rank) => total + rank, 0),
sourcePointFlags,
plan,
};
});
const final = levelPlans[levelPlans.length - 1];
const sourcePointsRetained = final.sourcePointFlags.filter(Boolean).length;
return {
plan: final.plan,
sourcePointCount: final.sourcePointCount,
sourcePointsRetained,
fallbackPointCount: Math.max(0, 71 - sourcePointsRetained),
levelPlans,
};
}
const config = parsePlayerbotsConfig(readFileSync(playerbotsConfigPath, "utf8"));
const playerbotsBySpec = new Map(PLAYERBOTS_PVE_SPECS.map((reference) => [
specKey(reference.classId, reference.specialization),
reference,
]));
const profiles = PARTY_TALENT_SPECIALIZATIONS.flatMap(({ classId, specialization }, index) => {
const key = specKey(classId, specialization);
const reference = playerbotsBySpec.get(key);
if (!reference) throw new Error(`No Playerbots PvE mapping for ${key}.`);
const configKey = `${reference.classNumber}:${reference.specNumber}`;
const milestones = config.links.get(configKey) ?? [];
const specSlug = `${classId}-${slug(specialization)}`;
const playerbotsPlan = playerbotsAllocationPlan(reference, milestones);
return [
{
id: `playerbots-pve-${PLAYERBOTS_COMMIT}:${specSlug}`,
classId,
specialization,
name: `${specialization} Playerbots PvE`,
characterName: CHARACTER_NAMES[index],
source: "azerothcore-playerbots",
sourceVersion: PLAYERBOTS_COMMIT,
defaultForSpecialization: true,
playerbotsSpecName: config.names.get(configKey) ?? null,
milestones,
...playerbotsPlan,
},
{
id: `healer-man-executable-v1:${specSlug}`,
classId,
specialization,
name: `${specialization} Executable`,
characterName: CHARACTER_NAMES[index + PARTY_TALENT_SPECIALIZATIONS.length],
source: "healer-man-generated",
sourceVersion: "v1",
defaultForSpecialization: false,
playerbotsSpecName: null,
milestones: [],
sourcePointCount: null,
sourcePointsRetained: null,
fallbackPointCount: 0,
plan: partyTalentAllocationPlan(classId, specialization).map((selection) => selection.nodeId),
levelPlans: [],
},
];
});
const output = {
schemaVersion: 1,
generatedFrom: "src/game/partyTalents.ts",
plans,
schemaVersion: 2,
generatedFrom: [
"src/game/partyTalents.ts",
"../wow-pvt-server-backups-2/azerothcore-wotlk/modules/mod-playerbots/conf/playerbots.conf.dist",
],
playerbotsCommit: PLAYERBOTS_COMMIT,
profiles,
};
mkdirSync(dirname(outputPath), { recursive: true });
writeFileSync(outputPath, `${JSON.stringify(output, null, 2)}\n`, "utf8");
console.log(`Wrote ${Object.keys(plans).length} party talent plans to ${outputPath}`);
console.log(`Wrote ${profiles.length} named party talent profiles to ${outputPath}`);
scripts/playtest-companion-readiness.cjs
+103
View File
@@ -0,0 +1,103 @@
const { chromium } = require('C:/Users/phenom/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const directory = path.resolve(process.env.COMPANION_READINESS_PLAYTEST_DIR || 'playtest-artifacts/companion-readiness');
const port = Number(process.env.COMPANION_READINESS_PLAYTEST_PORT || 4192);
const base = `http://127.0.0.1:${port}`;
fs.mkdirSync(directory, { recursive: true });
const runtimeData = fs.mkdtempSync(path.join(os.tmpdir(), 'healer-man-readiness-ui-'));
(async () => {
const { createGameServer } = await import('../server/server.mjs');
const runtime = createGameServer({ dataDir: runtimeData, enableShelvedModes: false });
await new Promise((resolve) => runtime.server.listen(port, '127.0.0.1', resolve));
const browser = await chromium.launch({ channel: 'msedge', headless: true });
const context = await browser.newContext({ viewport: { width: 1440, height: 1000 } });
const page = await context.newPage();
page.setDefaultTimeout(120_000);
const pageErrors = [];
page.on('pageerror', (error) => pageErrors.push(error.message));
const capture = async (name, fullPage = true) => {
await page.screenshot({ path: path.join(directory, `${name}.png`), fullPage });
console.log(`Captured ${name}`);
};
try {
await page.goto(base, { waitUntil: 'domcontentloaded' });
await page.getByLabel('Username').fill('Phenom');
await page.getByLabel('Password').fill('readiness-playtest');
await page.getByRole('button', { name: /Create account/ }).click();
await page.locator('.character-select-screen').waitFor();
await page.getByRole('button', { name: /Create character/ }).click();
await page.getByRole('button', { name: /Customize & name/ }).click();
await page.getByLabel('Character name').fill('ReadinessQA');
await page.getByRole('button', { name: /Create character/ }).click();
await page.getByRole('button', { name: /Continue/ }).first().click();
await page.locator('.main-menu-screen').waitFor();
await page.getByRole('button', { name: /Companion Readiness/ }).click();
await page.locator('.companion-readiness').waitFor();
const totals = page.getByLabel('Readiness totals');
assert.match(await totals.innerText(), /5\s+Ready/);
assert.match(await totals.innerText(), /0\s+Beta/);
assert.match(await totals.innerText(), /26\s+Needs Testing/);
assert.equal(await page.locator('.companion-readiness__spec').count(), 31);
assert.match(await page.locator('.companion-readiness__spec').filter({ hasText: 'Aldren' }).innerText(), /Protection/);
assert.match(await page.locator('.companion-readiness__spec').filter({ hasText: 'Quorin' }).innerText(), /Discipline/);
await capture('01-readiness-desktop');
await page.setViewportSize({ width: 480, height: 900 });
await page.waitForTimeout(250);
assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), true);
await page.getByLabel('Status').selectOption('ready');
assert.equal(await page.locator('.companion-readiness__spec').count(), 5);
await capture('02-readiness-narrow');
await page.setViewportSize({ width: 1440, height: 1000 });
await page.getByLabel('Status').selectOption('all');
await page.getByLabel('Arms readiness').selectOption('beta');
await page.getByRole('button', { name: 'Publish policy' }).click();
await page.getByText('Published policy is active').waitFor();
assert.match(await totals.innerText(), /1\s+Beta/);
assert.match(await totals.innerText(), /25\s+Needs Testing/);
await page.getByRole('button', { name: 'Back' }).click();
await page.locator('.main-menu-screen').waitFor();
await page.getByRole('button', { name: /Dungeons/ }).click();
await page.locator('.dungeon-select-screen').waitFor();
const beta = page.getByRole('checkbox', { name: /Include Beta Specs/ });
assert.equal(await beta.isDisabled(), false);
assert.equal(await beta.isChecked(), false);
assert.match(await page.locator('.companion-pool-controls').innerText(), /1 beta spec available/);
await page.locator('.dungeon-select-row').filter({ hasText: 'Wailing Caverns' }).click();
await page.locator('.dungeon-select-copy h2').getByText('Wailing Caverns', { exact: true }).waitFor();
await capture('03-dungeon-ready-pool');
await page.getByRole('button', { name: /Choose role/ }).click();
const roleButton = page.locator('.dungeon-role-option').first();
await roleButton.click();
await page.locator('.party-frames').waitFor({ timeout: 180_000 });
await page.locator('.party-frame').nth(4).waitFor();
await page.locator('.loading-screen').waitFor({ state: 'detached', timeout: 180_000 });
assert.equal(await page.locator('.party-frame').count(), 5);
const npcFrames = await page.locator('.party-frame:not(.party-frame--player):not(.party-frame--online)').allInnerTexts();
assert.equal(npcFrames.length, 4);
for (const frame of npcFrames) {
assert.match(frame, /Protection|Discipline|Marksmanship|Fire|Assassination/i);
assert.doesNotMatch(frame, /Arms/i);
}
await capture('04-live-dungeon-ready-party', false);
assert.deepEqual(pageErrors, []);
console.log(`Companion Readiness playtest passed with NPCs: ${npcFrames.map((frame) => frame.split('\n')[0]).join(', ')}`);
} finally {
await browser.close();
await new Promise((resolve) => runtime.server.close(resolve));
fs.rmSync(runtimeData, { recursive: true, force: true });
}
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});
scripts/test_balance_lab.py
+78
View File
@@ -6,6 +6,8 @@ from scripts.balance_lab import (
automatic_parties,
coverage_parties,
random_party,
readiness_eligible_builds,
resolve_build,
runtime_session_command,
search_bosses,
tuning_label,
@@ -13,6 +15,15 @@ from scripts.balance_lab import (
class BalanceLabControllerTests(unittest.TestCase):
def test_class_spec_selector_prefers_the_named_default_build(self) -> None:
builds = [
{"id": "fire-default", "classId": "mage", "className": "Mage", "role": "damage",
"specialization": "Fire", "label": "Mage Fire Playerbots", "defaultTalentBuild": True},
{"id": "fire-alt", "classId": "mage", "className": "Mage", "role": "damage",
"specialization": "Fire", "label": "Mage Fire Executable", "defaultTalentBuild": False},
]
self.assertEqual(resolve_build("mage:fire", builds)["id"], "fire-default")
def test_headless_runtime_uses_the_no_watch_vite_mode(self) -> None:
command = runtime_session_command("wow", 40)
self.assertEqual(command[1:3], ["--mode", "balance-lab"])
@@ -34,6 +45,20 @@ class BalanceLabControllerTests(unittest.TestCase):
])
self.assertEqual(len({member["id"] for member in first[2:]}), 3)
def test_random_party_uses_named_default_profiles(self) -> None:
builds = [
{"id": "tank-default", "role": "tank", "defaultTalentBuild": True},
{"id": "tank-alt", "role": "tank", "defaultTalentBuild": False},
{"id": "healer-default", "role": "healer", "defaultTalentBuild": True},
{"id": "healer-alt", "role": "healer", "defaultTalentBuild": False},
*({"id": f"damage-default-{index}", "role": "damage", "defaultTalentBuild": True}
for index in range(3)),
*({"id": f"damage-alt-{index}", "role": "damage", "defaultTalentBuild": False}
for index in range(3)),
]
party = random_party(builds, 17)
self.assertTrue(all(member["defaultTalentBuild"] for member in party))
def test_tuning_flags_keep_both_sides_of_the_median(self) -> None:
self.assertEqual(tuning_label(1.51), "very high")
self.assertEqual(tuning_label(1.25), "high")
@@ -102,6 +127,43 @@ class BalanceLabControllerTests(unittest.TestCase):
self.assertTrue(set(selected).issubset(covered))
self.assertTrue(all(observed.count(build_id) == 1 for build_id in selected))
def test_readiness_filters_only_wow_and_beta_requires_opt_in(self) -> None:
builds = [
{"id": "ready-tank", "source": "wow", "specializationId": "warrior:protection"},
{"id": "beta-damage", "source": "wow", "specializationId": "paladin:retribution"},
{"id": "testing-damage", "source": "wow", "specializationId": "priest:shadow"},
{"id": "rom-damage", "source": "rom", "specializationId": "mage:primary"},
]
policy = {"config": {"statuses": {
"warrior:protection": "ready",
"paladin:retribution": "beta",
"priest:shadow": "needs-testing",
}}}
self.assertEqual(
[build["id"] for build in readiness_eligible_builds(builds, policy, False)],
["ready-tank", "rom-damage"],
)
self.assertEqual(
[build["id"] for build in readiness_eligible_builds(builds, policy, True)],
["ready-tank", "beta-damage", "rom-damage"],
)
def test_targeted_needs_testing_build_uses_ready_fillers(self) -> None:
builds = [
{"id": "ready-tank", "source": "wow", "role": "tank", "specializationId": "warrior:protection", "readinessStatus": "ready", "defaultTalentBuild": True},
{"id": "ready-healer", "source": "wow", "role": "healer", "specializationId": "priest:discipline", "readinessStatus": "ready", "defaultTalentBuild": True},
{"id": "ready-hunter", "source": "wow", "role": "damage", "specializationId": "hunter:marksmanship", "readinessStatus": "ready", "defaultTalentBuild": True},
{"id": "ready-mage", "source": "wow", "role": "damage", "specializationId": "mage:fire", "readinessStatus": "ready", "defaultTalentBuild": True},
{"id": "ready-rogue", "source": "wow", "role": "damage", "specializationId": "rogue:assassination", "readinessStatus": "ready", "defaultTalentBuild": True},
{"id": "testing-shadow", "source": "wow", "role": "damage", "specializationId": "priest:shadow", "readinessStatus": "needs-testing", "defaultTalentBuild": True},
]
eligible = readiness_eligible_builds(builds, None, False)
parties = coverage_parties(builds, ("wow",), ["testing-shadow"], 13, eligible)
self.assertEqual(len(parties), 1)
ids = [member["id"] for member in parties[0]["party"]]
self.assertIn("testing-shadow", ids)
self.assertTrue(all(build_id == "testing-shadow" or build_id.startswith("ready-") for build_id in ids))
def test_boss_search_matches_name_dungeon_key_and_source(self) -> None:
bosses = [
{"key": "gundrak/eck", "name": "Eck the Ferocious", "dungeonTitle": "Gundrak", "category": "wow"},
@@ -164,6 +226,22 @@ class BalanceLabControllerTests(unittest.TestCase):
self.assertEqual(by_id["mage-fireball"]["damageShare"], 0.5)
self.assertTrue(by_id["mage-unused-blast"]["unusedAvailable"])
def test_missing_profile_action_requires_repeated_uncommitted_decisions(self) -> None:
class_key = ("wow", "mage-fire", "mage", "Mage", "Fire", "damage")
class_runs = [{"partyConfigurationId": "party-1", "bossKey": "boss-1", "elapsedSeconds": 10, "damage": 0}]
base = {
"abilityName": "Fireball", "icon": "", "categories": ["damage"],
"cooldownSeconds": 0, "rotationProfileId": "mage:fire", "rotationPriority": 5,
"expectedUsage": "profile", "available": True, "used": False,
"casts": 0, "hits": 0, "rawDamage": 0, "effectiveDamage": 0,
"rawHealing": 0, "effectiveHealing": 0, "overheal": 0, "absorbs": 0,
"partyConfigurationId": "party-1", "bossKey": "boss-1", "elapsedSeconds": 10,
}
once = aggregate_class_abilities({(*class_key, "fireball"): [{**base, "rotationDecisions": 1}]}, {class_key: class_runs})[0]
repeated = aggregate_class_abilities({(*class_key, "fireball"): [{**base, "rotationDecisions": 3}]}, {class_key: class_runs})[0]
self.assertEqual(once["status"], "unused")
self.assertEqual(repeated["status"], "missing-profile-action")
if __name__ == "__main__":
unittest.main()
scripts/test_balance_lab_brackets.py
+103
View File
@@ -0,0 +1,103 @@
import argparse
import json
import sys
import tempfile
import unittest
from pathlib import Path
from scripts.balance_lab_brackets import (
add_growth_metrics,
bracket_levels,
build_balance_lab_command,
evaluate_rows,
summarize_report,
)
class BalanceLabBracketTests(unittest.TestCase):
def test_bracket_levels_match_the_gm_schedules(self) -> None:
self.assertEqual(bracket_levels(10), [1, 10, 20, 30, 40, 50, 60, 70, 80])
self.assertEqual(bracket_levels(5)[:4], [1, 5, 10, 15])
self.assertEqual(bracket_levels(1), list(range(1, 81)))
def test_command_uses_the_existing_live_balance_lab_controller(self) -> None:
args = argparse.Namespace(
source="wow", spec_selection="all", party_seed=7, party_configurations=10,
simulations_per_party=3, duration=80, boss_category="wow", seeds="1,2,3",
active_slot=None, spec=[], boss=["stormwind-stockade/entry-1717"],
seat_sweep=True, cooldown_policy=None,
companion_readiness_policy=Path("policy.json"), include_beta_specs=True,
)
command = build_balance_lab_command(args, 40, Path("output/level-40"))
self.assertEqual(command[0], sys.executable)
self.assertTrue(command[1].endswith("scripts\\balance_lab.py") or command[1].endswith("scripts/balance_lab.py"))
self.assertIn("automatic", command)
self.assertEqual(command[command.index("--level") + 1], "40")
self.assertEqual(command[command.index("--seeds") + 1], "1,2,3")
self.assertIn("--seat-sweep", command)
self.assertIn("--include-beta-specs", command)
self.assertEqual(
command[command.index("--companion-readiness-policy") + 1],
str(Path("policy.json").resolve()),
)
def test_summary_measures_healer_requirement_from_raw_runs(self) -> None:
with tempfile.TemporaryDirectory() as temporary:
root = Path(temporary)
report_path = root / "suite-report.json"
report = {
"level": 20,
"summary": {"partyConfigurations": 1, "bosses": 1},
"bosses": [{
"runs": 1, "bossMaxHealth": 1000, "defeatRate": 1,
"averageTimeToDefeat": 10,
}],
"classSpecs": [{
"role": "healer", "totalHealing": 150, "totalAbsorbs": 25,
}],
}
report_path.write_text(json.dumps(report), encoding="utf-8")
raw_path = root / "parties" / "wow-party-001" / "raw-runs.json"
raw_path.parent.mkdir(parents=True)
raw_path.write_text(json.dumps({"runs": [{
"elapsedSeconds": 10, "partyDamage": 1200, "bossDamage": 1000,
"incomingDamage": 200, "rawIncomingDamage": 250, "outcome": "defeated",
"pressureWindows": 2, "healerThroughputWindows": 2, "healerResponseWindows": 2,
"members": [
{"role": "healer", "healing": 150, "absorbs": 25, "minimumHealthPercent": 0.6},
{"role": "tank", "healing": 0, "absorbs": 0, "minimumHealthPercent": 0.4},
],
}]}), encoding="utf-8")
summary = summarize_report(report_path)
self.assertEqual(summary["healthToDpsSeconds"], 10)
self.assertEqual(summary["incomingDtps"], 20)
self.assertEqual(summary["healerHps"], 15)
self.assertEqual(summary["healingCoverageRate"], 0.875)
self.assertEqual(summary["incomingRunRate"], 1)
self.assertEqual(summary["healingRequiredRunRate"], 1)
self.assertEqual(summary["healerResponseRate"], 1)
self.assertEqual(summary["averageMinimumHealthPercent"], 0.4)
def test_growth_check_flags_health_that_outpaces_damage(self) -> None:
rows = [
{"level": 10, "bossHealth": 1000, "bossDps": 100},
{"level": 20, "bossHealth": 2500, "bossDps": 150},
]
for row in rows:
row.update({
"healthToDpsSeconds": row["bossHealth"] / row["bossDps"],
"incomingDtps": 10, "healerHps": 8, "incomingRunRate": 1,
"healingRequiredRunRate": 1,
})
add_growth_metrics(rows)
args = argparse.Namespace(
min_health_to_dps_seconds=5, max_health_to_dps_seconds=70, max_durability_growth=1.4,
min_incoming_run_rate=0.95, min_healing_required_run_rate=0.8,
min_healer_response_rate=0.6,
)
self.assertFalse(evaluate_rows(rows, args))
self.assertIn("boss health outgrew party DPS", rows[1]["flags"])
if __name__ == "__main__":
unittest.main()
server/balance-lab-jobs.mjs
+32 -2
View File
@@ -27,6 +27,8 @@ const ARTIFACTS = new Map([
["party_configurations.csv", "text/csv; charset=utf-8"],
["class_specs_across_parties.csv", "text/csv; charset=utf-8"],
["class_abilities_across_parties.csv", "text/csv; charset=utf-8"],
["npc_class_specs_across_parties.csv", "text/csv; charset=utf-8"],
["npc_class_abilities_across_parties.csv", "text/csv; charset=utf-8"],
["class_spec_by_boss.csv", "text/csv; charset=utf-8"],
["bosses_across_parties.csv", "text/csv; charset=utf-8"],
["boss_by_party.csv", "text/csv; charset=utf-8"],
@@ -55,6 +57,9 @@ export function normalizeBalanceLabJobSpec(input) {
if (!SPEC_SELECTIONS.has(specSelection)) {
throw new GameDatabaseError("Class/spec selection must be random, all, or specific.", 400, "invalid_balance_lab_job");
}
if (input?.includeBetaSpecs !== undefined && typeof input.includeBetaSpecs !== "boolean") {
throw new GameDatabaseError("Include Beta Specs must be boolean.", 400, "invalid_balance_lab_job");
}
const rawBossKeys = Array.isArray(input?.bossKeys) ? input.bossKeys : [];
if (rawBossKeys.length > 500) {
throw new GameDatabaseError("Select no more than 500 bosses.", 400, "invalid_balance_lab_job");
@@ -85,6 +90,8 @@ export function normalizeBalanceLabJobSpec(input) {
partySeed: integer(input?.partySeed ?? 1, "Party seed", -2_147_483_648, 2_147_483_647),
bossCategory,
bossKeys: Object.freeze(bossKeys),
seatSweep: input?.seatSweep === true,
includeBetaSpecs: input?.includeBetaSpecs === true,
});
const sourceCount = spec.source === "all" ? 3 : 1;
const bossEstimate = Math.max(1, spec.bossKeys.length || (spec.bossCategory === "all" ? 500 : 300));
@@ -93,7 +100,7 @@ export function normalizeBalanceLabJobSpec(input) {
: spec.specSelection === "specific"
? Math.max(spec.partyConfigurations, spec.selectedBuildIds.length)
: Math.max(spec.partyConfigurations, spec.source === "all" ? 100 : 50);
const estimatedRuns = partyEstimate * spec.simulationsPerParty * bossEstimate;
const estimatedRuns = partyEstimate * (spec.seatSweep ? 5 : 1) * spec.simulationsPerParty * bossEstimate;
if (estimatedRuns > 250_000) {
throw new GameDatabaseError(
"That job is too large for one server request. Reduce parties, simulations, or selected bosses.",
@@ -136,6 +143,10 @@ export function balanceLabCommand(spec, outputDir, options = {}) {
];
for (const buildId of spec.selectedBuildIds) args.push("--spec", buildId);
for (const bossKey of spec.bossKeys) args.push("--boss", bossKey);
if (spec.seatSweep) args.push("--seat-sweep");
if (spec.includeBetaSpecs) args.push("--include-beta-specs");
if (options.cooldownPolicyPath) args.push("--cooldown-policy", options.cooldownPolicyPath);
if (options.readinessPolicyPath) args.push("--companion-readiness-policy", options.readinessPolicyPath);
return { executable, args, cwd: projectRoot };
}
@@ -198,6 +209,8 @@ function reportSummary(outputDir) {
runs: Number(summary.runs) || 0,
classSpecs: Number(summary.classSpecs) || 0,
classAbilities: Number(summary.classAbilities) || 0,
npcClassSpecs: Number(summary.npcClassSpecs) || 0,
npcClassAbilities: Number(summary.npcClassAbilities) || 0,
bossPressureMedianDtps: Number(summary.bossPressureMedianDtps) || 0,
};
} catch {
@@ -206,9 +219,10 @@ function reportSummary(outputDir) {
}
function expectedPartyConfigurations(spec) {
return spec.specSelection === "random"
const parties = spec.specSelection === "random"
? spec.partyConfigurations * (spec.source === "all" ? 3 : 1)
: spec.partyConfigurations;
return parties * (spec.seatSweep ? 5 : 1);
}
function lineCollector(onLine) {
@@ -249,6 +263,8 @@ export function createBalanceLabJobService(options = {}) {
? Math.min(200, Math.floor(configuredQueueLimit))
: 100;
const launch = options.spawnProcess ?? spawn;
const cooldownPolicyProvider = options.cooldownPolicyProvider;
const readinessPolicyProvider = options.readinessPolicyProvider;
const pythonExecutable = String(options.pythonExecutable
?? process.env.BALANCE_LAB_PYTHON
?? (process.platform === "win32" ? "python" : "python3"));
@@ -390,6 +406,8 @@ export function createBalanceLabJobService(options = {}) {
const command = balanceLabCommand(job.spec, job.outputDir, {
projectRoot,
pythonExecutable,
cooldownPolicyPath: job.cooldownPolicyPath,
readinessPolicyPath: job.readinessPolicyPath,
});
const child = launch(command.executable, command.args, {
cwd: command.cwd,
@@ -467,6 +485,16 @@ export function createBalanceLabJobService(options = {}) {
const id = randomUUID();
const outputDir = path.join(jobsDir, id);
mkdirSync(outputDir, { recursive: true });
const cooldownPolicyPath = path.join(outputDir, "companion-cooldown-policy.json");
if (cooldownPolicyProvider) {
const published = cooldownPolicyProvider();
writeFileSync(cooldownPolicyPath, `${JSON.stringify(published.config ?? published, null, 2)}\n`, "utf8");
}
const readinessPolicyPath = path.join(outputDir, "companion-spec-readiness.json");
if (readinessPolicyProvider) {
const published = readinessPolicyProvider();
writeFileSync(readinessPolicyPath, `${JSON.stringify(published, null, 2)}\n`, "utf8");
}
const totalParties = expectedPartyConfigurations(spec);
const job = {
id,
@@ -488,6 +516,8 @@ export function createBalanceLabJobService(options = {}) {
logTail: [],
summary: null,
outputDir,
cooldownPolicyPath: cooldownPolicyProvider ? cooldownPolicyPath : null,
readinessPolicyPath: readinessPolicyProvider ? readinessPolicyPath : null,
};
jobs.set(id, job);
persistJob(job);
server/balance-lab-jobs.test.mjs
+56 -1
View File
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import { EventEmitter } from "node:events";
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { PassThrough } from "node:stream";
@@ -20,6 +20,12 @@ test("disables public assets and filesystem watching in Balance Lab Vite mode",
assert.deepEqual(config.server.watch?.ignored, ["**/*"]);
});
test("enables the local Balance Lab GUI without watching its generated reports", async () => {
const config = await resolveConfig({}, "serve", "balance-lab-gui");
assert.equal(config.define["import.meta.env.VITE_LOCAL_BALANCE_LAB_GUI"], '"true"');
assert.ok(config.server.watch?.ignored?.includes("**/artifacts/balance-lab-gui-runtime/**"));
});
test("normalizes and bounds server Balance Lab requests", () => {
const spec = normalizeBalanceLabJobSpec({
source: "ALL",
@@ -30,6 +36,8 @@ test("normalizes and bounds server Balance Lab requests", () => {
simulationsPerParty: 3,
durationSeconds: 45,
partySeed: 17,
seatSweep: true,
includeBetaSpecs: true,
bossCategory: "all",
bossKeys: ["gundrak/entry-29932", "gundrak/entry-29932"],
});
@@ -37,6 +45,8 @@ test("normalizes and bounds server Balance Lab requests", () => {
assert.equal(spec.specSelection, "specific");
assert.deepEqual(spec.selectedBuildIds, ["balance-wow-priest-healer-holy-level-40"]);
assert.deepEqual(spec.bossKeys, ["gundrak/entry-29932"]);
assert.equal(spec.seatSweep, true);
assert.equal(spec.includeBetaSpecs, true);
assert.throws(
() => normalizeBalanceLabJobSpec({ source: "wow", level: 81 }),
/Level must be a whole number/,
@@ -69,6 +79,8 @@ test("builds an argument-array command without a shell", () => {
const spec = normalizeBalanceLabJobSpec({
source: "rom", level: 60, partyConfigurations: 4, simulationsPerParty: 2,
durationSeconds: 30, partySeed: 9, bossCategory: "rom", bossKeys: ["abbey/boss-1"],
seatSweep: true,
includeBetaSpecs: true,
specSelection: "specific", selectedBuildIds: ["balance-rom-mage-damage-primary-level-60"],
});
const command = balanceLabCommand(spec, "C:/reports/job", {
@@ -81,6 +93,8 @@ test("builds an argument-array command without a shell", () => {
assert.equal(command.args.includes("specific"), true);
assert.equal(command.args.includes("balance-rom-mage-damage-primary-level-60"), true);
assert.equal(command.args.includes("abbey/boss-1"), true);
assert.equal(command.args.includes("--seat-sweep"), true);
assert.equal(command.args.includes("--include-beta-specs"), true);
assert.equal(command.cwd, path.resolve("C:/app"));
});
@@ -162,6 +176,47 @@ test("queues a job, reports progress, and exposes only allow-listed artifacts",
}
});
test("snapshots the published companion readiness policy for each server job", async () => {
const directory = mkdtempSync(path.join(os.tmpdir(), "healer-man-balance-readiness-"));
try {
let launchedArgs = [];
const spawnProcess = (_executable, args) => {
launchedArgs = args;
const child = new EventEmitter();
child.stdout = new PassThrough();
child.stderr = new PassThrough();
child.kill = () => child.emit("close", null);
return child;
};
const policy = {
revision: 7,
updatedAt: 123,
updatedBy: "Phenom",
config: { schemaVersion: 1, statuses: { "warrior:protection": "ready" } },
};
const service = createBalanceLabJobService({
dataDir: directory,
projectRoot: directory,
spawnProcess,
pythonExecutable: "python-test",
readinessPolicyProvider: () => policy,
});
const job = service.start({
source: "wow", level: 40, partyConfigurations: 1, simulationsPerParty: 1,
durationSeconds: 5, partySeed: 1, bossCategory: "all", bossKeys: ["gundrak/entry-29932"],
includeBetaSpecs: true,
}, { username: "Phenom" });
const policyPath = path.join(directory, "balance-lab", "jobs", job.id, "companion-spec-readiness.json");
assert.equal(JSON.parse(readFileSync(policyPath, "utf8")).revision, 7);
assert.equal(launchedArgs.includes("--companion-readiness-policy"), true);
assert.equal(launchedArgs.includes(policyPath), true);
assert.equal(launchedArgs.includes("--include-beta-specs"), true);
service.close();
} finally {
rmSync(directory, { recursive: true, force: true });
}
});
test("reports exhausted file watchers as a specific startup failure", async () => {
const directory = mkdtempSync(path.join(os.tmpdir(), "healer-man-balance-watchers-"));
try {
server/companion-cooldown-policy.mjs
+87
View File
@@ -0,0 +1,87 @@
export const DEFAULT_COMPANION_COOLDOWN_POLICY = Object.freeze({
schemaVersion: 1,
generic: Object.freeze({
defensiveHealthPercent: 55,
emergencyHealthPercent: 35,
healerMitigationHealthPercent: 80,
offensiveMajorCooldownSeconds: 60,
conserveOffensiveCooldownsForDurableTargets: true,
}),
mechanics: Object.freeze([]),
});
function invalid(message) {
const error = new Error(message);
error.code = "invalid_companion_cooldown_policy";
return error;
}
function number(value, label, minimum, maximum) {
if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
throw invalid(`${label} must be a number from ${minimum} through ${maximum}.`);
}
return value;
}
function string(value, label, allowEmpty = false) {
if (typeof value !== "string" || (!allowEmpty && !value.trim()) || value.length > 256) {
throw invalid(`${label} must be ${allowEmpty ? "a" : "a non-empty"} string no longer than 256 characters.`);
}
return value.trim();
}
export function normalizeCompanionCooldownPolicy(value) {
if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1) {
throw invalid("Companion cooldown policy schemaVersion must be 1.");
}
const generic = value.generic;
if (!generic || typeof generic !== "object" || Array.isArray(generic)) throw invalid("generic rules are required.");
if (typeof generic.conserveOffensiveCooldownsForDurableTargets !== "boolean") {
throw invalid("generic.conserveOffensiveCooldownsForDurableTargets must be boolean.");
}
if (!Array.isArray(value.mechanics) || value.mechanics.length > 1_000) throw invalid("mechanics must be an array of at most 1,000 rules.");
const seen = new Set();
const mechanics = value.mechanics.map((rule, index) => {
if (!rule || typeof rule !== "object" || Array.isArray(rule)) throw invalid(`mechanics[${index}] must be an object.`);
const id = string(rule.id, `mechanics[${index}].id`);
if (seen.has(id)) throw invalid(`mechanic rule id ${id} is duplicated.`);
seen.add(id);
if (typeof rule.enabled !== "boolean") throw invalid(`mechanics[${index}].enabled must be boolean.`);
if (!new Set(["tank", "party"]).has(rule.scope)) throw invalid(`mechanics[${index}].scope is invalid.`);
const serverEntry = rule.bossServerEntry;
if (serverEntry !== null && (!Number.isInteger(serverEntry) || serverEntry <= 0)) {
throw invalid(`mechanics[${index}].bossServerEntry must be null or a positive integer.`);
}
const bossName = string(rule.bossName, `mechanics[${index}].bossName`, true);
if (serverEntry === null && !bossName) {
throw invalid(`mechanics[${index}].bossName is required when bossServerEntry is null.`);
}
return {
id,
enabled: rule.enabled,
bossKey: string(rule.bossKey, `mechanics[${index}].bossKey`, true),
bossName,
bossServerEntry: serverEntry,
attackId: string(rule.attackId, `mechanics[${index}].attackId`),
attackName: string(rule.attackName, `mechanics[${index}].attackName`),
scope: rule.scope,
leadTimeMs: number(rule.leadTimeMs, `mechanics[${index}].leadTimeMs`, 0, 15_000),
minimumCooldownSeconds: number(rule.minimumCooldownSeconds, `mechanics[${index}].minimumCooldownSeconds`, 0, 600),
};
});
return {
schemaVersion: 1,
generic: {
defensiveHealthPercent: number(generic.defensiveHealthPercent, "generic.defensiveHealthPercent", 1, 100),
emergencyHealthPercent: number(generic.emergencyHealthPercent, "generic.emergencyHealthPercent", 1, 100),
healerMitigationHealthPercent: number(generic.healerMitigationHealthPercent, "generic.healerMitigationHealthPercent", 1, 100),
offensiveMajorCooldownSeconds: number(generic.offensiveMajorCooldownSeconds, "generic.offensiveMajorCooldownSeconds", 0, 600),
conserveOffensiveCooldownsForDurableTargets: generic.conserveOffensiveCooldownsForDurableTargets,
},
mechanics,
};
}
export function cloneDefaultCompanionCooldownPolicy() {
return JSON.parse(JSON.stringify(DEFAULT_COMPANION_COOLDOWN_POLICY));
}
server/companion-cooldown-policy.test.mjs
+44
View File
@@ -0,0 +1,44 @@
import assert from "node:assert/strict";
import test from "node:test";
import {
DEFAULT_COMPANION_COOLDOWN_POLICY,
normalizeCompanionCooldownPolicy,
} from "./companion-cooldown-policy.mjs";
test("normalizes valid generic and boss-mechanic cooldown rules", () => {
const policy = normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
generic: { ...DEFAULT_COMPANION_COOLDOWN_POLICY.generic, defensiveHealthPercent: 62 },
mechanics: [{
id: "tank-buster", enabled: true, bossKey: "test/boss", bossName: "Test Boss",
bossServerEntry: 123, attackId: "heavy-strike", attackName: "Heavy Strike",
scope: "tank", leadTimeMs: 2_500, minimumCooldownSeconds: 20,
}],
});
assert.equal(policy.generic.defensiveHealthPercent, 62);
assert.equal(policy.mechanics[0].attackId, "heavy-strike");
});
test("rejects duplicate mechanic ids and out-of-range thresholds", () => {
const rule = {
id: "duplicate", enabled: true, bossKey: "", bossName: "Boss", bossServerEntry: null,
attackId: "attack", attackName: "Attack", scope: "party", leadTimeMs: 1_000,
minimumCooldownSeconds: 20,
};
assert.throws(() => normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
mechanics: [rule, rule],
}), /duplicated/);
assert.throws(() => normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
generic: { ...DEFAULT_COMPANION_COOLDOWN_POLICY.generic, defensiveHealthPercent: 101 },
}), /1 through 100/);
assert.throws(() => normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
generic: { ...DEFAULT_COMPANION_COOLDOWN_POLICY.generic, conserveOffensiveCooldownsForDurableTargets: "yes" },
}), /must be boolean/);
assert.throws(() => normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
mechanics: [{ ...rule, id: "missing-boss", bossName: "" }],
}), /bossName is required/);
});
server/companion-spec-readiness.mjs
+61
View File
@@ -0,0 +1,61 @@
const WOW_SPECIALIZATIONS = Object.freeze([
["warrior:arms", "damage"], ["warrior:fury", "damage"], ["warrior:protection", "tank"],
["paladin:holy", "healer"], ["paladin:protection", "tank"], ["paladin:retribution", "damage"],
["hunter:beast-mastery", "damage"], ["hunter:marksmanship", "damage"], ["hunter:survival", "damage"],
["rogue:assassination", "damage"], ["rogue:combat", "damage"], ["rogue:subtlety", "damage"],
["priest:discipline", "healer"], ["priest:holy", "healer"], ["priest:shadow", "damage"],
["death-knight:blood", "tank"], ["death-knight:frost", "damage"], ["death-knight:unholy", "damage"],
["shaman:elemental", "damage"], ["shaman:enhancement", "damage"], ["shaman:restoration", "healer"],
["mage:arcane", "damage"], ["mage:fire", "damage"], ["mage:frost", "damage"],
["warlock:affliction", "damage"], ["warlock:demonology", "damage"], ["warlock:destruction", "damage"],
["druid:balance", "damage"], ["druid:feral-bear", "tank"], ["druid:feral-cat", "damage"], ["druid:restoration", "healer"],
]);
const READY_IDS = new Set([
"warrior:protection",
"priest:discipline",
"hunter:marksmanship",
"mage:fire",
"rogue:assassination",
]);
const SPECIALIZATION_ROLE = new Map(WOW_SPECIALIZATIONS);
const VALID_STATUSES = new Set(["ready", "beta", "needs-testing"]);
export const DEFAULT_COMPANION_SPEC_READINESS_POLICY = Object.freeze({
schemaVersion: 1,
statuses: Object.freeze(Object.fromEntries(WOW_SPECIALIZATIONS.map(([id]) => [
id,
READY_IDS.has(id) ? "ready" : "needs-testing",
]))),
});
function invalid(message) {
const error = new Error(message);
error.code = "invalid_companion_spec_readiness";
return error;
}
export function normalizeCompanionSpecReadinessPolicy(value) {
if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1) {
throw invalid("Companion readiness policy schemaVersion must be 1.");
}
if (!value.statuses || typeof value.statuses !== "object" || Array.isArray(value.statuses)) {
throw invalid("Companion readiness statuses are required.");
}
for (const [id, status] of Object.entries(value.statuses)) {
if (!SPECIALIZATION_ROLE.has(id)) throw invalid(`Unknown WoW specialization: ${id}.`);
if (!VALID_STATUSES.has(status)) throw invalid(`Invalid readiness status for ${id}.`);
}
const statuses = Object.fromEntries(WOW_SPECIALIZATIONS.map(([id]) => [id, value.statuses[id] ?? "needs-testing"]));
const ready = WOW_SPECIALIZATIONS.filter(([id]) => statuses[id] === "ready");
if (!ready.some(([, role]) => role === "tank")) throw invalid("At least one tank specialization must be Ready.");
if (!ready.some(([, role]) => role === "healer")) throw invalid("At least one healer specialization must be Ready.");
if (ready.filter(([, role]) => role === "damage").length < 3) {
throw invalid("At least three distinct damage specializations must be Ready.");
}
return { schemaVersion: 1, statuses };
}
export function cloneDefaultCompanionSpecReadinessPolicy() {
return JSON.parse(JSON.stringify(DEFAULT_COMPANION_SPEC_READINESS_POLICY));
}
server/companion-spec-readiness.test.mjs
+25
View File
@@ -0,0 +1,25 @@
import assert from "node:assert/strict";
import test from "node:test";
import {
cloneDefaultCompanionSpecReadinessPolicy,
normalizeCompanionSpecReadinessPolicy,
} from "./companion-spec-readiness.mjs";
test("default companion readiness policy certifies the five focused specs", () => {
const policy = normalizeCompanionSpecReadinessPolicy(cloneDefaultCompanionSpecReadinessPolicy());
assert.deepEqual(Object.entries(policy.statuses).filter(([, status]) => status === "ready").map(([id]) => id), [
"warrior:protection",
"hunter:marksmanship",
"rogue:assassination",
"priest:discipline",
"mage:fire",
]);
});
test("companion readiness validation rejects invalid coverage and unknown specs", () => {
assert.throws(() => normalizeCompanionSpecReadinessPolicy({ schemaVersion: 1, statuses: {} }), /tank specialization/);
assert.throws(() => normalizeCompanionSpecReadinessPolicy({
schemaVersion: 1,
statuses: { ...cloneDefaultCompanionSpecReadinessPolicy().statuses, "future:spec": "ready" },
}), /Unknown WoW specialization/);
});
server/database.mjs
+128
View File
@@ -8,6 +8,14 @@ import {
normalizeManastormAdminConfig,
stampManastormReviewMetadata,
} from "./manastorm-config.mjs";
import {
cloneDefaultCompanionCooldownPolicy,
normalizeCompanionCooldownPolicy,
} from "./companion-cooldown-policy.mjs";
import {
cloneDefaultCompanionSpecReadinessPolicy,
normalizeCompanionSpecReadinessPolicy,
} from "./companion-spec-readiness.mjs";
import { arenaRatingBand, calculateArenaRating, clampArenaRating } from "./arena-rules.mjs";
import { arenaRoleForSpecialization } from "./arena-specializations.mjs";
import { createDungeonReportRepository } from "./dungeon-reports.mjs";
@@ -93,6 +101,24 @@ export function openGameDatabase(options = {}) {
updated_by_username TEXT,
updated_at INTEGER
) STRICT;
CREATE TABLE IF NOT EXISTS companion_cooldown_policy (
id INTEGER PRIMARY KEY CHECK (id = 1),
schema_version INTEGER NOT NULL,
revision INTEGER NOT NULL,
config_json TEXT NOT NULL,
updated_by_account_id TEXT REFERENCES accounts(id) ON DELETE SET NULL,
updated_by_username TEXT,
updated_at INTEGER
) STRICT;
CREATE TABLE IF NOT EXISTS companion_spec_readiness (
id INTEGER PRIMARY KEY CHECK (id = 1),
schema_version INTEGER NOT NULL,
revision INTEGER NOT NULL,
config_json TEXT NOT NULL,
updated_by_account_id TEXT REFERENCES accounts(id) ON DELETE SET NULL,
updated_by_username TEXT,
updated_at INTEGER
) STRICT;
CREATE TABLE IF NOT EXISTS online_groups (
id TEXT PRIMARY KEY,
leader_account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
@@ -184,6 +210,16 @@ export function openGameDatabase(options = {}) {
id, schema_version, revision, config_json, updated_by_account_id, updated_by_username, updated_at
) VALUES (1, 1, 0, ?, NULL, NULL, NULL)
`).run(JSON.stringify(cloneDefaultManastormAdminConfig()));
database.prepare(`
INSERT OR IGNORE INTO companion_cooldown_policy (
id, schema_version, revision, config_json, updated_by_account_id, updated_by_username, updated_at
) VALUES (1, 1, 0, ?, NULL, NULL, NULL)
`).run(JSON.stringify(cloneDefaultCompanionCooldownPolicy()));
database.prepare(`
INSERT OR IGNORE INTO companion_spec_readiness (
id, schema_version, revision, config_json, updated_by_account_id, updated_by_username, updated_at
) VALUES (1, 1, 0, ?, NULL, NULL, NULL)
`).run(JSON.stringify(cloneDefaultCompanionSpecReadinessPolicy()));
const statements = {
accountByUsername: database.prepare("SELECT * FROM accounts WHERE username_key = ?"),
@@ -215,6 +251,22 @@ export function openGameDatabase(options = {}) {
WHERE id = 1 AND revision = ?
RETURNING revision, updated_at
`),
companionCooldownPolicy: database.prepare("SELECT * FROM companion_cooldown_policy WHERE id = 1"),
updateCompanionCooldownPolicy: database.prepare(`
UPDATE companion_cooldown_policy
SET schema_version = 1, revision = revision + 1, config_json = ?,
updated_by_account_id = ?, updated_by_username = ?, updated_at = ?
WHERE id = 1 AND revision = ?
RETURNING revision, updated_at
`),
companionSpecReadiness: database.prepare("SELECT * FROM companion_spec_readiness WHERE id = 1"),
updateCompanionSpecReadiness: database.prepare(`
UPDATE companion_spec_readiness
SET schema_version = 1, revision = revision + 1, config_json = ?,
updated_by_account_id = ?, updated_by_username = ?, updated_at = ?
WHERE id = 1 AND revision = ?
RETURNING revision, updated_at
`),
arenaLoadouts: database.prepare(`
SELECT * FROM arena_loadouts WHERE account_id = ? AND character_id = ? ORDER BY slot
`),
@@ -364,6 +416,74 @@ export function openGameDatabase(options = {}) {
};
}
function getCompanionCooldownPolicy() {
const row = statements.companionCooldownPolicy.get();
try {
return {
revision: Number(row?.revision ?? 0),
updatedAt: row?.updated_at == null ? null : Number(row.updated_at),
updatedBy: row?.updated_by_username ?? null,
config: normalizeCompanionCooldownPolicy(JSON.parse(row?.config_json ?? "null")),
};
} catch (error) {
console.error("Healer Man companion cooldown policy is corrupt; using safe defaults", error);
return { revision: 0, updatedAt: null, updatedBy: null, config: cloneDefaultCompanionCooldownPolicy() };
}
}
function putCompanionCooldownPolicy(account, expectedRevision, config) {
if (!isGameMaster(account)) throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
if (!Number.isInteger(expectedRevision) || expectedRevision < 0) {
throw new GameDatabaseError("A valid expected revision is required.", 400, "invalid_revision");
}
let normalized;
try {
normalized = normalizeCompanionCooldownPolicy(config);
} catch (error) {
throw new GameDatabaseError(error instanceof Error ? error.message : "Invalid companion cooldown policy.", 400, "invalid_companion_cooldown_policy");
}
const now = Date.now();
const row = statements.updateCompanionCooldownPolicy.get(
JSON.stringify(normalized), account.id, account.username, now, expectedRevision,
);
if (!row) throw new GameDatabaseError("The companion cooldown policy changed. Reload and try again.", 409, "revision_conflict");
return { revision: Number(row.revision), updatedAt: Number(row.updated_at), updatedBy: account.username, config: normalized };
}
function getCompanionSpecReadiness() {
const row = statements.companionSpecReadiness.get();
try {
return {
revision: Number(row?.revision ?? 0),
updatedAt: row?.updated_at == null ? null : Number(row.updated_at),
updatedBy: row?.updated_by_username ?? null,
config: normalizeCompanionSpecReadinessPolicy(JSON.parse(row?.config_json ?? "null")),
};
} catch (error) {
console.error("Healer Man companion readiness policy is corrupt; using shipped defaults", error);
return { revision: 0, updatedAt: null, updatedBy: null, config: cloneDefaultCompanionSpecReadinessPolicy() };
}
}
function putCompanionSpecReadiness(account, expectedRevision, config) {
if (!isGameMaster(account)) throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
if (!Number.isInteger(expectedRevision) || expectedRevision < 0) {
throw new GameDatabaseError("A valid expected revision is required.", 400, "invalid_revision");
}
let normalized;
try {
normalized = normalizeCompanionSpecReadinessPolicy(config);
} catch (error) {
throw new GameDatabaseError(error instanceof Error ? error.message : "Invalid companion readiness policy.", 400, "invalid_companion_spec_readiness");
}
const now = Date.now();
const row = statements.updateCompanionSpecReadiness.get(
JSON.stringify(normalized), account.id, account.username, now, expectedRevision,
);
if (!row) throw new GameDatabaseError("The companion readiness policy changed. Reload and try again.", 409, "revision_conflict");
return { revision: Number(row.revision), updatedAt: Number(row.updated_at), updatedBy: account.username, config: normalized };
}
function pruneExpiredGroupInvites() {
database.prepare(`
UPDATE online_group_invites SET status = 'expired'
@@ -620,6 +740,9 @@ export function openGameDatabase(options = {}) {
throw new GameDatabaseError("Every player must select a character and party role before the group can start.", 409, "group_not_ready");
}
const fillWithAi = input?.fillWithAi !== false;
if (input?.includeBetaSpecs !== undefined && typeof input.includeBetaSpecs !== "boolean") {
throw new GameDatabaseError("includeBetaSpecs must be boolean.", 400, "invalid_beta_preference");
}
const requestedSize = Math.max(1, Math.min(5, Math.trunc(Number(input?.partySize) || 5)));
const partySize = fillWithAi ? Math.max(members.length, requestedSize) : members.length;
const activity = {
@@ -628,6 +751,7 @@ export function openGameDatabase(options = {}) {
contentId,
...(type === "dungeon" ? { difficultyId: input?.difficultyId, bossDifficulty: input?.bossDifficulty ?? 1 } : {}),
fillWithAi,
includeBetaSpecs: input?.includeBetaSpecs === true,
partySize,
startingLevel: type === "manastorm"
? Math.max(1, Math.trunc(Number(input?.startingLevel) || 1))
@@ -921,6 +1045,10 @@ export function openGameDatabase(options = {}) {
isGameMaster,
getManastormConfig,
putManastormConfig,
getCompanionCooldownPolicy,
putCompanionCooldownPolicy,
getCompanionSpecReadiness,
putCompanionSpecReadiness,
onlineGroupState,
inviteOnlineGroupMember,
respondToOnlineGroupInvite,
server/database.test.mjs
+61 -1
View File
@@ -142,6 +142,65 @@ test("persists revisioned Manastorm GM configuration and rejects stale or unauth
}), (error) => error instanceof GameDatabaseError && error.status === 400);
}));
test("persists revisioned companion cooldown policy and rejects stale or unauthorized writes", () => withDatabase(async (database) => {
const gm = await database.register("Phenom", "cooldown-admin");
const player = await database.register("Ordinary", "cooldown-player");
const initial = database.getCompanionCooldownPolicy();
const configured = {
...initial.config,
generic: { ...initial.config.generic, defensiveHealthPercent: 61 },
mechanics: [{
id: "tank-buster", enabled: true, bossKey: "test/boss", bossName: "Test Boss",
bossServerEntry: 123, attackId: "heavy-strike", attackName: "Heavy Strike",
scope: "tank", leadTimeMs: 2_500, minimumCooldownSeconds: 20,
}],
};
const saved = database.putCompanionCooldownPolicy(database.authenticate(gm.token), 0, configured);
assert.equal(saved.revision, 1);
assert.equal(database.getCompanionCooldownPolicy().config.generic.defensiveHealthPercent, 61);
assert.throws(() => database.putCompanionCooldownPolicy(database.authenticate(gm.token), 0, configured), (error) => (
error instanceof GameDatabaseError && error.status === 409
));
assert.throws(() => database.putCompanionCooldownPolicy(database.authenticate(player.token), 1, configured), (error) => (
error instanceof GameDatabaseError && error.status === 403
));
}));
test("persists validated companion readiness with authorization, revisions, and corrupt-data fallback", () => withDatabase(async (database) => {
const gm = await database.register("Phenom", "readiness-admin");
const player = await database.register("ReadinessPlayer", "readiness-player");
const initial = database.getCompanionSpecReadiness();
assert.equal(initial.revision, 0);
assert.equal(initial.config.statuses["warrior:protection"], "ready");
assert.equal(Object.values(initial.config.statuses).filter((status) => status === "ready").length, 5);
const configured = {
...initial.config,
statuses: { ...initial.config.statuses, "paladin:retribution": "beta" },
};
const account = database.authenticate(gm.token);
const saved = database.putCompanionSpecReadiness(account, 0, configured);
assert.equal(saved.revision, 1);
assert.equal(database.getCompanionSpecReadiness().config.statuses["paladin:retribution"], "beta");
assert.throws(() => database.putCompanionSpecReadiness(account, 0, configured), (error) => (
error instanceof GameDatabaseError && error.status === 409
));
assert.throws(() => database.putCompanionSpecReadiness(database.authenticate(player.token), 1, configured), (error) => (
error instanceof GameDatabaseError && error.status === 403
));
assert.throws(() => database.putCompanionSpecReadiness(account, 1, {
schemaVersion: 1,
statuses: { ...configured.statuses, "warrior:protection": "needs-testing" },
}), (error) => error instanceof GameDatabaseError && error.status === 400);
const raw = new DatabaseSync(database.databasePath);
raw.prepare("UPDATE companion_spec_readiness SET config_json = ? WHERE id = 1").run("{not-json");
raw.close();
const fallback = database.getCompanionSpecReadiness();
assert.equal(fallback.revision, 0);
assert.equal(fallback.config.statuses["warrior:protection"], "ready");
}));
test("stores GM simulation replays and gates exact-hash route approval", () => withDatabase(async (database) => {
const gmAuth = await database.register("Phenom", "storm-admin");
const playerAuth = await database.register("RoutePlayer", "route-player");
@@ -288,10 +347,11 @@ test("launches players-only and AI-filled group activities only when every membe
assert.equal(playersOnly.group.activity.fillWithAi, false);
const filled = database.startOnlineGroupActivity(leader.id, {
type: "manastorm", contentId: "manastorm", fillWithAi: true, partySize: 5, startingLevel: 10,
type: "manastorm", contentId: "manastorm", fillWithAi: true, includeBetaSpecs: true, partySize: 5, startingLevel: 10,
});
assert.equal(filled.group.activity.partySize, 5);
assert.equal(filled.group.activity.startingLevel, 10);
assert.equal(filled.group.activity.includeBetaSpecs, true);
assert.throws(() => database.startOnlineGroupActivity(member.id, {
type: "dungeon", contentId: "wailing-caverns",
}), (error) => error instanceof GameDatabaseError && error.status === 403);
server/local-balance-lab-api.mjs
+164
View File
@@ -0,0 +1,164 @@
import { createReadStream, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { createBalanceLabJobService } from "./balance-lab-jobs.mjs";
import { cloneDefaultCompanionCooldownPolicy } from "./companion-cooldown-policy.mjs";
import {
cloneDefaultCompanionSpecReadinessPolicy,
normalizeCompanionSpecReadinessPolicy,
} from "./companion-spec-readiness.mjs";
import { GameDatabaseError } from "./database.mjs";
const API_ROOT = "/api/local/balance-lab";
function json(response, status, body) {
const content = Buffer.from(JSON.stringify(body));
response.writeHead(status, {
"Content-Type": "application/json; charset=utf-8",
"Content-Length": content.length,
"Cache-Control": "no-store",
});
response.end(content);
}
async function readJson(request, limit) {
const chunks = [];
let size = 0;
for await (const chunk of request) {
size += chunk.length;
if (size > limit) throw new GameDatabaseError("Request body is too large.", 413, "body_too_large");
chunks.push(chunk);
}
if (size === 0) return {};
try {
return JSON.parse(Buffer.concat(chunks).toString("utf8"));
} catch {
throw new GameDatabaseError("Request body must be valid JSON.", 400, "invalid_json");
}
}
function isLoopback(address) {
return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
}
export function createLocalBalanceLabApi(options = {}) {
const projectRoot = path.resolve(options.projectRoot ?? fileURLToPath(new URL("..", import.meta.url)));
const dataDir = path.resolve(options.dataDir ?? path.join(projectRoot, "artifacts", "balance-lab-gui-runtime"));
const readinessPath = path.join(dataDir, "companion-spec-readiness.json");
mkdirSync(dataDir, { recursive: true });
let readiness = { revision: 0, updatedAt: null, updatedBy: null, config: cloneDefaultCompanionSpecReadinessPolicy() };
try {
const stored = JSON.parse(readFileSync(readinessPath, "utf8"));
readiness = {
revision: Number.isInteger(stored.revision) ? stored.revision : 0,
updatedAt: Number.isFinite(stored.updatedAt) ? stored.updatedAt : null,
updatedBy: typeof stored.updatedBy === "string" ? stored.updatedBy : null,
config: normalizeCompanionSpecReadinessPolicy(stored.config),
};
} catch { /* missing or corrupt local policy falls back to shipped defaults */ }
const persistReadiness = () => {
const temporaryPath = `${readinessPath}.tmp`;
writeFileSync(temporaryPath, `${JSON.stringify(readiness, null, 2)}\n`, "utf8");
renameSync(temporaryPath, readinessPath);
};
const service = createBalanceLabJobService({
dataDir,
projectRoot,
pythonExecutable: options.pythonExecutable,
spawnProcess: options.spawnProcess,
runtimeProbe: options.runtimeProbe,
maxConcurrent: options.maxConcurrent,
maxQueued: options.maxQueued,
cooldownPolicyProvider: () => ({ config: cloneDefaultCompanionCooldownPolicy() }),
readinessPolicyProvider: () => readiness,
});
const account = Object.freeze({ username: "Local GUI" });
return {
service,
async handle(request, response) {
const url = new URL(request.url ?? "/", "http://127.0.0.1");
if (url.pathname !== API_ROOT && !url.pathname.startsWith(`${API_ROOT}/`)) return false;
if (!isLoopback(request.socket?.remoteAddress)) {
json(response, 403, { error: "The local Balance Lab API accepts loopback requests only.", code: "loopback_required" });
return true;
}
try {
if (url.pathname === `${API_ROOT}/companion-spec-readiness` && request.method === "GET") {
json(response, 200, readiness);
return true;
}
if (url.pathname === `${API_ROOT}/companion-spec-readiness` && request.method === "PUT") {
const body = await readJson(request, 256 * 1024);
if (!Number.isInteger(body.expectedRevision) || body.expectedRevision !== readiness.revision) {
throw new GameDatabaseError("The companion readiness policy changed. Reload and try again.", 409, "revision_conflict");
}
let config;
try {
config = normalizeCompanionSpecReadinessPolicy(body.config);
} catch (error) {
throw new GameDatabaseError(
error instanceof Error ? error.message : "Invalid companion readiness policy.",
400,
"invalid_companion_spec_readiness",
);
}
readiness = {
revision: readiness.revision + 1,
updatedAt: Date.now(),
updatedBy: "Local GUI",
config,
};
persistReadiness();
json(response, 200, readiness);
return true;
}
if (url.pathname === `${API_ROOT}/jobs` && request.method === "GET") {
json(response, 200, { jobs: service.list() });
return true;
}
if (url.pathname === `${API_ROOT}/runtime` && request.method === "GET") {
json(response, 200, { runtime: service.runtime() });
return true;
}
if (url.pathname === `${API_ROOT}/jobs/batch` && request.method === "POST") {
json(response, 202, { jobs: service.startMany(await readJson(request, 4 * 1024 * 1024), account) });
return true;
}
if (url.pathname === `${API_ROOT}/jobs` && request.method === "POST") {
json(response, 202, { job: service.start(await readJson(request, 32 * 1024), account) });
return true;
}
const artifactMatch = new RegExp(`^${API_ROOT}/jobs/([0-9a-f-]{36})/artifacts/([A-Za-z0-9._-]+)$`).exec(url.pathname);
if (artifactMatch && request.method === "GET") {
const artifact = service.artifact(artifactMatch[1], artifactMatch[2]);
response.writeHead(200, {
"Content-Type": artifact.contentType,
"Content-Length": artifact.size,
"Cache-Control": "no-store",
"Content-Disposition": `inline; filename="${artifactMatch[2]}"`,
"X-Content-Type-Options": "nosniff",
});
createReadStream(artifact.filePath).pipe(response);
return true;
}
const jobMatch = new RegExp(`^${API_ROOT}/jobs/([0-9a-f-]{36})$`).exec(url.pathname);
if (jobMatch && request.method === "GET") {
json(response, 200, { job: service.get(jobMatch[1]) });
return true;
}
json(response, 404, { error: "Local Balance Lab route not found.", code: "not_found" });
} catch (error) {
const known = error instanceof GameDatabaseError;
json(response, known ? error.status : 500, {
error: known ? error.message : "The local Balance Lab request failed.",
code: known ? error.code : "internal_error",
});
}
return true;
},
close() {
service.close();
},
};
}
server/local-balance-lab-api.test.mjs
+143
View File
@@ -0,0 +1,143 @@
import assert from "node:assert/strict";
import { EventEmitter } from "node:events";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { createServer } from "node:http";
import os from "node:os";
import path from "node:path";
import { PassThrough } from "node:stream";
import test from "node:test";
import { createLocalBalanceLabApi } from "./local-balance-lab-api.mjs";
test("serves loopback-only local Balance Lab jobs without account authentication", async () => {
const directory = mkdtempSync(path.join(os.tmpdir(), "healer-man-local-balance-gui-"));
const spawnProcess = (_executable, args) => {
const child = new EventEmitter();
child.stdout = new PassThrough();
child.stderr = new PassThrough();
child.kill = () => child.emit("close", null);
const outputDir = args[args.indexOf("--output-dir") + 1];
setImmediate(() => {
mkdirSync(outputDir, { recursive: true });
writeFileSync(path.join(outputDir, "suite-report.json"), JSON.stringify({
summary: { partyConfigurations: 1, bosses: 1, runs: 1, classSpecs: 5, classAbilities: 5 },
}));
child.stdout.write("Party 1/1: wow-party-001\n");
child.stdout.end();
child.stderr.end();
child.emit("close", 0);
});
return child;
};
const api = createLocalBalanceLabApi({
dataDir: directory,
projectRoot: directory,
spawnProcess,
runtimeProbe: () => ({ available: true, executable: "python-test", version: "Python 3.test", error: null }),
});
const server = createServer((request, response) => {
void api.handle(request, response).then((handled) => {
if (!handled) response.writeHead(404).end();
});
});
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
const origin = `http://127.0.0.1:${server.address().port}`;
try {
const runtime = await (await fetch(`${origin}/api/local/balance-lab/runtime`)).json();
assert.equal(runtime.runtime.available, true);
const startedResponse = await fetch(`${origin}/api/local/balance-lab/jobs`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
source: "wow", level: 20, partyConfigurations: 1, simulationsPerParty: 1,
durationSeconds: 5, partySeed: 1, bossCategory: "all",
bossKeys: ["stormwind-stockade/entry-1717"],
}),
});
assert.equal(startedResponse.status, 202);
const started = (await startedResponse.json()).job;
assert.equal(started.requestedBy, "Local GUI");
await new Promise((resolve) => setImmediate(resolve));
const jobs = await (await fetch(`${origin}/api/local/balance-lab/jobs`)).json();
assert.equal(jobs.jobs[0].status, "complete");
const artifact = await fetch(`${origin}/api/local/balance-lab/jobs/${started.id}/artifacts/suite-report.json`);
assert.equal(artifact.status, 200);
assert.equal((await artifact.json()).summary.runs, 1);
assert.equal((await fetch(`${origin}/api/not-local-balance-lab`)).status, 404);
} finally {
await new Promise((resolve) => server.close(resolve));
api.close();
rmSync(directory, { recursive: true, force: true });
}
});
test("persists revisioned local companion readiness and recovers from a corrupt policy file", async () => {
const directory = mkdtempSync(path.join(os.tmpdir(), "healer-man-local-readiness-"));
const open = async () => {
const api = createLocalBalanceLabApi({
dataDir: directory,
projectRoot: directory,
runtimeProbe: () => ({ available: true, executable: "python-test", version: "Python 3.test", error: null }),
});
const server = createServer((request, response) => {
void api.handle(request, response).then((handled) => {
if (!handled) response.writeHead(404).end();
});
});
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
return {
api,
server,
origin: `http://127.0.0.1:${server.address().port}`,
close: async () => {
await new Promise((resolve) => server.close(resolve));
api.close();
},
};
};
try {
const first = await open();
const initial = await (await fetch(`${first.origin}/api/local/balance-lab/companion-spec-readiness`)).json();
const configured = {
...initial.config,
statuses: { ...initial.config.statuses, "paladin:retribution": "beta" },
};
const savedResponse = await fetch(`${first.origin}/api/local/balance-lab/companion-spec-readiness`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ expectedRevision: 0, config: configured }),
});
assert.equal(savedResponse.status, 200);
assert.equal((await savedResponse.json()).revision, 1);
const staleResponse = await fetch(`${first.origin}/api/local/balance-lab/companion-spec-readiness`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ expectedRevision: 0, config: configured }),
});
assert.equal(staleResponse.status, 409);
const invalidResponse = await fetch(`${first.origin}/api/local/balance-lab/companion-spec-readiness`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
expectedRevision: 1,
config: { ...configured, statuses: { ...configured.statuses, "warrior:protection": "needs-testing" } },
}),
});
assert.equal(invalidResponse.status, 400);
await first.close();
const second = await open();
const restored = await (await fetch(`${second.origin}/api/local/balance-lab/companion-spec-readiness`)).json();
assert.equal(restored.revision, 1);
assert.equal(restored.config.statuses["paladin:retribution"], "beta");
await second.close();
writeFileSync(path.join(directory, "companion-spec-readiness.json"), "{not-json");
const third = await open();
const fallback = await (await fetch(`${third.origin}/api/local/balance-lab/companion-spec-readiness`)).json();
assert.equal(fallback.revision, 0);
assert.equal(fallback.config.statuses["warrior:protection"], "ready");
await third.close();
} finally {
rmSync(directory, { recursive: true, force: true });
}
});
server/server.mjs
+58
View File
@@ -183,6 +183,8 @@ export function createGameServer(options = {}) {
dataDir: options.dataDir ?? path.dirname(gameDatabase.databasePath),
projectRoot: options.projectRoot,
pythonExecutable: options.pythonExecutable,
cooldownPolicyProvider: () => gameDatabase.getCompanionCooldownPolicy(),
readinessPolicyProvider: () => gameDatabase.getCompanionSpecReadiness(),
});
const onlineSessions = createOnlineSessionManager();
const arenaService = createArenaService({ database: gameDatabase, autoPump: enableShelvedModes });
@@ -498,6 +500,62 @@ export function createGameServer(options = {}) {
json(response, 200, result);
return;
}
if (url.pathname === "/api/companion-cooldown-policy" && request.method === "GET") {
const current = gameDatabase.getCompanionCooldownPolicy();
json(response, 200, {
revision: current.revision,
updatedAt: current.updatedAt,
config: current.config,
});
return;
}
if (url.pathname === "/api/gm/companion-cooldown-policy" && request.method === "GET") {
const account = gameDatabase.authenticate(bearerToken(request));
if (!gameDatabase.isGameMaster(account)) {
throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
}
json(response, 200, gameDatabase.getCompanionCooldownPolicy());
return;
}
if (url.pathname === "/api/gm/companion-cooldown-policy" && request.method === "PUT") {
const account = gameDatabase.authenticate(bearerToken(request));
if (!gameDatabase.isGameMaster(account)) {
throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
}
const body = await readJson(request, bodyLimit);
const result = gameDatabase.putCompanionCooldownPolicy(account, body.expectedRevision, body.config);
console.info(`Companion cooldown policy revision ${result.revision} published by ${account.username}`);
json(response, 200, result);
return;
}
if (url.pathname === "/api/companion-spec-readiness" && request.method === "GET") {
const current = gameDatabase.getCompanionSpecReadiness();
json(response, 200, {
revision: current.revision,
updatedAt: current.updatedAt,
config: current.config,
});
return;
}
if (url.pathname === "/api/gm/companion-spec-readiness" && request.method === "GET") {
const account = gameDatabase.authenticate(bearerToken(request));
if (!gameDatabase.isGameMaster(account)) {
throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
}
json(response, 200, gameDatabase.getCompanionSpecReadiness());
return;
}
if (url.pathname === "/api/gm/companion-spec-readiness" && request.method === "PUT") {
const account = gameDatabase.authenticate(bearerToken(request));
if (!gameDatabase.isGameMaster(account)) {
throw new GameDatabaseError("Game Master access is required.", 403, "gm_required");
}
const body = await readJson(request, bodyLimit);
const result = gameDatabase.putCompanionSpecReadiness(account, body.expectedRevision, body.config);
console.info(`Companion readiness revision ${result.revision} published by ${account.username}`);
json(response, 200, result);
return;
}
if (url.pathname === "/api/gm/balance-lab/jobs" && request.method === "GET") {
const account = gameDatabase.authenticate(bearerToken(request));
if (!gameDatabase.isGameMaster(account)) {
server/server.test.mjs
+50
View File
@@ -87,6 +87,20 @@ test("serves the game and authenticated cloud-save API", async () => {
headers: { Authorization: `Bearer ${auth.token}` },
});
assert.equal(deniedRead.status, 403);
const publicCooldownPolicy = await (await fetch(`${origin}/api/companion-cooldown-policy`)).json();
assert.equal(publicCooldownPolicy.revision, 0);
assert.equal(publicCooldownPolicy.config.generic.defensiveHealthPercent, 55);
const deniedCooldownPolicy = await fetch(`${origin}/api/gm/companion-cooldown-policy`, {
headers: { Authorization: `Bearer ${auth.token}` },
});
assert.equal(deniedCooldownPolicy.status, 403);
const publicReadiness = await (await fetch(`${origin}/api/companion-spec-readiness`)).json();
assert.equal(publicReadiness.revision, 0);
assert.equal(publicReadiness.config.statuses["warrior:protection"], "ready");
const deniedReadiness = await fetch(`${origin}/api/gm/companion-spec-readiness`, {
headers: { Authorization: `Bearer ${auth.token}` },
});
assert.equal(deniedReadiness.status, 403);
const memberRegistration = await fetch(`${origin}/api/auth/register`, {
method: "POST",
@@ -237,6 +251,42 @@ test("serves the game and authenticated cloud-save API", async () => {
assert.equal(gmRegistration.status, 201);
const gmAuth = await gmRegistration.json();
assert.deepEqual(gmAuth.account.roles, ["gm"]);
const publishedCooldownPolicy = await fetch(`${origin}/api/gm/companion-cooldown-policy`, {
method: "PUT",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${gmAuth.token}` },
body: JSON.stringify({
expectedRevision: publicCooldownPolicy.revision,
config: {
...publicCooldownPolicy.config,
generic: { ...publicCooldownPolicy.config.generic, defensiveHealthPercent: 61 },
},
}),
});
assert.equal(publishedCooldownPolicy.status, 200);
const publishedCooldownPolicyPayload = await publishedCooldownPolicy.json();
assert.equal(publishedCooldownPolicyPayload.revision, 1);
assert.equal(publishedCooldownPolicyPayload.config.generic.defensiveHealthPercent, 61);
const playerCooldownPolicy = await (await fetch(`${origin}/api/companion-cooldown-policy`)).json();
assert.equal(playerCooldownPolicy.config.generic.defensiveHealthPercent, 61);
const publishedReadiness = await fetch(`${origin}/api/gm/companion-spec-readiness`, {
method: "PUT",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${gmAuth.token}` },
body: JSON.stringify({
expectedRevision: publicReadiness.revision,
config: {
...publicReadiness.config,
statuses: { ...publicReadiness.config.statuses, "paladin:retribution": "beta" },
},
}),
});
assert.equal(publishedReadiness.status, 200);
assert.equal((await publishedReadiness.json()).config.statuses["paladin:retribution"], "beta");
const staleReadiness = await fetch(`${origin}/api/gm/companion-spec-readiness`, {
method: "PUT",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${gmAuth.token}` },
body: JSON.stringify({ expectedRevision: 0, config: publicReadiness.config }),
});
assert.equal(staleReadiness.status, 409);
const deniedBalanceLab = await fetch(`${origin}/api/gm/balance-lab/jobs`, {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: `Bearer ${auth.token}` },
src/App.tsx
+7
View File
@@ -13,6 +13,8 @@ import {
loadGameRuntime,
preloadSharedGameplayResources,
} from "./ui/gameplayResources";
import { useCompanionCooldownPolicyStore } from "./game/companionCooldownPolicyStore";
import { useCompanionSpecReadinessStore } from "./game/companionSpecReadinessStore";
const GameRuntime = lazy(loadGameRuntime);
const CharacterCreateScreen = lazy(() => import("./ui/CharacterCreateScreen").then((module) => ({ default: module.CharacterCreateScreen })));
@@ -72,6 +74,11 @@ export default function App() {
const phase = useShellStore((state) => state.phase);
const session = useShellStore((state) => state.session);
const PreloadedGameRuntime = getLoadedGameRuntime();
const refreshCooldownPolicy = useCompanionCooldownPolicyStore((state) => state.refresh);
const refreshSpecReadiness = useCompanionSpecReadinessStore((state) => state.refresh);
useEffect(() => { void refreshCooldownPolicy(session); }, [refreshCooldownPolicy, session]);
useEffect(() => { void refreshSpecReadiness(session); }, [refreshSpecReadiness, session]);
useEffect(() => {
if (!SHELVED_MODES_ENABLED && isShelvedShellPhase(phase)) {
src/app/balanceLabClient.ts
+91 -27
View File
@@ -4,6 +4,28 @@ export type BalanceLabPartySource = "wow" | "coa" | "rom" | "all";
export type BalanceLabBossCategory = "all" | "wow" | "rom";
export type BalanceLabSpecSelection = "random" | "all" | "specific";
export type BalanceLabJobStatus = "queued" | "running" | "complete" | "failed";
export type BalanceLabExecutionTarget = "server" | "local";
function balanceLabApiPath(target: BalanceLabExecutionTarget, suffix: string): string {
const root = target === "local" ? "/api/local/balance-lab" : "/api/gm/balance-lab";
return `${root}${suffix}`;
}
async function requestBalanceLabJson<T>(
pathname: string,
init: RequestInit,
token: string,
target: BalanceLabExecutionTarget,
): Promise<T> {
if (target === "server") return requestOnlineJson<T>(pathname, init, token);
const headers = new Headers(init.headers);
headers.set("Accept", "application/json");
if (init.body !== undefined) headers.set("Content-Type", "application/json");
const response = await fetch(pathname, { ...init, headers });
const body = await response.json().catch(() => ({})) as T & { error?: string };
if (!response.ok) throw new Error(body.error ?? `Local Balance Lab request failed (${response.status}).`);
return body;
}
export interface BalanceLabRuntimeStatus {
readonly available: boolean;
@@ -27,6 +49,8 @@ export interface BalanceLabJobSpec {
readonly partySeed: number;
readonly bossCategory: BalanceLabBossCategory;
readonly bossKeys: readonly string[];
readonly seatSweep?: boolean;
readonly includeBetaSpecs?: boolean;
}
export interface BalanceLabJob {
@@ -56,6 +80,8 @@ export interface BalanceLabReportSummary {
readonly runs: number;
readonly classSpecs: number;
readonly classAbilities: number;
readonly npcClassSpecs?: number;
readonly npcClassAbilities?: number;
readonly bossPressureMedianDtps: number;
}
@@ -82,6 +108,13 @@ export interface BalanceLabBossResult {
export interface BalanceLabClassSpecResult {
readonly source: string;
readonly buildId: string;
readonly characterName?: string | null;
readonly talentBuildId?: string | null;
readonly talentBuildName?: string | null;
readonly talentBuildSource?: string | null;
readonly talentBuildSourcePointCount?: number | null;
readonly talentBuildSourcePointsRetained?: number | null;
readonly talentBuildFallbackPointCount?: number | null;
readonly classId: string;
readonly className: string;
readonly specialization: string;
@@ -93,6 +126,7 @@ export interface BalanceLabClassSpecResult {
readonly hps: number;
readonly hpsReceived?: number;
readonly dtps: number;
readonly gcdUptimePercent?: number;
readonly totalDamage: number;
readonly totalDamageTaken: number;
readonly totalHealing: number;
@@ -128,6 +162,10 @@ export interface BalanceLabClassAbilityResult {
readonly icon: string;
readonly categories: string;
readonly cooldownSeconds: number | null;
readonly rotationProfileId?: string | null;
readonly rotationPriority?: number | null;
readonly expectedUsage?: "profile" | "conditional" | "available";
readonly rotationDecisions?: number;
readonly partyConfigurations: number;
readonly bosses: number;
readonly runs: number;
@@ -147,7 +185,7 @@ export interface BalanceLabClassAbilityResult {
readonly effectiveHealing: number;
readonly overheal: number;
readonly absorbs: number;
readonly status: "unused" | "damage" | "support" | "used";
readonly status: "unused" | "missing-profile-action" | "damage" | "support" | "used";
readonly unusedAvailable: boolean;
}
@@ -160,64 +198,90 @@ export interface BalanceLabSuiteReport {
readonly bosses: readonly BalanceLabBossResult[];
readonly classSpecs: readonly BalanceLabClassSpecResult[];
readonly classAbilities?: readonly BalanceLabClassAbilityResult[];
readonly npcClassSpecs?: readonly BalanceLabClassSpecResult[];
readonly npcClassAbilities?: readonly BalanceLabClassAbilityResult[];
readonly partyConfigurations: readonly BalanceLabPartyResult[];
}
export async function listBalanceLabJobs(token: string): Promise<readonly BalanceLabJob[]> {
return (await requestOnlineJson<{ jobs: BalanceLabJob[] }>(
"/api/gm/balance-lab/jobs",
export async function listBalanceLabJobs(
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<readonly BalanceLabJob[]> {
return (await requestBalanceLabJson<{ jobs: BalanceLabJob[] }>(
balanceLabApiPath(target, "/jobs"),
{},
token,
token, target,
)).jobs;
}
export async function getBalanceLabRuntime(token: string): Promise<BalanceLabRuntimeStatus> {
return (await requestOnlineJson<{ runtime: BalanceLabRuntimeStatus }>(
"/api/gm/balance-lab/runtime",
export async function getBalanceLabRuntime(
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<BalanceLabRuntimeStatus> {
return (await requestBalanceLabJson<{ runtime: BalanceLabRuntimeStatus }>(
balanceLabApiPath(target, "/runtime"),
{},
token,
token, target,
)).runtime;
}
export async function startBalanceLabJob(spec: BalanceLabJobSpec, token: string): Promise<BalanceLabJob> {
return (await requestOnlineJson<{ job: BalanceLabJob }>(
"/api/gm/balance-lab/jobs",
export async function startBalanceLabJob(
spec: BalanceLabJobSpec,
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<BalanceLabJob> {
return (await requestBalanceLabJson<{ job: BalanceLabJob }>(
balanceLabApiPath(target, "/jobs"),
{ method: "POST", body: JSON.stringify(spec) },
token,
token, target,
)).job;
}
export async function startBalanceLabJobs(
specs: readonly BalanceLabJobSpec[],
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<readonly BalanceLabJob[]> {
return (await requestOnlineJson<{ jobs: BalanceLabJob[] }>(
"/api/gm/balance-lab/jobs/batch",
return (await requestBalanceLabJson<{ jobs: BalanceLabJob[] }>(
balanceLabApiPath(target, "/jobs/batch"),
{ method: "POST", body: JSON.stringify({ specs }) },
token,
token, target,
)).jobs;
}
export async function getBalanceLabJob(id: string, token: string): Promise<BalanceLabJob> {
return (await requestOnlineJson<{ job: BalanceLabJob }>(
`/api/gm/balance-lab/jobs/${encodeURIComponent(id)}`,
export async function getBalanceLabJob(
id: string,
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<BalanceLabJob> {
return (await requestBalanceLabJson<{ job: BalanceLabJob }>(
balanceLabApiPath(target, `/jobs/${encodeURIComponent(id)}`),
{},
token,
token, target,
)).job;
}
export async function getBalanceLabReport(id: string, token: string): Promise<BalanceLabSuiteReport> {
return requestOnlineJson<BalanceLabSuiteReport>(
`/api/gm/balance-lab/jobs/${encodeURIComponent(id)}/artifacts/suite-report.json`,
export async function getBalanceLabReport(
id: string,
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<BalanceLabSuiteReport> {
return requestBalanceLabJson<BalanceLabSuiteReport>(
balanceLabApiPath(target, `/jobs/${encodeURIComponent(id)}/artifacts/suite-report.json`),
{},
token,
token, target,
);
}
export async function fetchBalanceLabArtifact(id: string, name: string, token: string): Promise<Blob> {
export async function fetchBalanceLabArtifact(
id: string,
name: string,
token: string,
target: BalanceLabExecutionTarget = "server",
): Promise<Blob> {
const response = await fetch(
`${onlineApiOrigin()}/api/gm/balance-lab/jobs/${encodeURIComponent(id)}/artifacts/${encodeURIComponent(name)}`,
{ headers: { Authorization: `Bearer ${token}` } },
`${target === "local" ? "" : onlineApiOrigin()}${balanceLabApiPath(target, `/jobs/${encodeURIComponent(id)}/artifacts/${encodeURIComponent(name)}`)}`,
{ headers: token ? { Authorization: `Bearer ${token}` } : undefined },
);
if (!response.ok) {
const body = await response.json().catch(() => ({})) as { error?: string };
src/app/onlineGroupTypes.ts
+2
View File
@@ -28,6 +28,7 @@ export interface OnlineGroupActivity {
readonly type: "dungeon" | "manastorm";
readonly contentId: string;
readonly fillWithAi: boolean;
readonly includeBetaSpecs?: boolean;
readonly partySize: number;
readonly startingLevel: number | null;
readonly startedAt: number;
@@ -63,6 +64,7 @@ export interface StartOnlineGroupActivityInput {
readonly type: OnlineGroupActivity["type"];
readonly contentId: string;
readonly fillWithAi: boolean;
readonly includeBetaSpecs?: boolean;
readonly partySize: number;
readonly startingLevel?: number;
}
src/game/PartyBridge.tsx
+14 -2
View File
@@ -7,6 +7,8 @@ import { useGameStore } from "./store";
import { useManastormStore } from "./manastormStore";
import { onlineGroupAiPartySize, useOnlineGroupStore } from "../app/onlineGroupStore";
import { useDungeonSimulationStore } from "./dungeonSimulationStore";
import { useCompanionSpecReadinessStore } from "./companionSpecReadinessStore";
import { useCompanionPartyPreferences } from "./companionPartyPreferences";
/** Owns party lifecycle; the combat interval itself remains in CombatBridge. */
export function PartyBridge() {
@@ -19,6 +21,9 @@ export function PartyBridge() {
const simulationMode = useDungeonSimulationStore((state) => state.sessionMode);
const simulationSeed = useDungeonSimulationStore((state) => state.seed);
const resetRevision = useGameStore((state) => state.resetRevision);
const readinessPolicy = useCompanionSpecReadinessStore((state) => state.config);
const readinessPolicyRevision = useCompanionSpecReadinessStore((state) => state.revision);
const deviceIncludeBetaSpecs = useCompanionPartyPreferences((state) => state.includeBetaSpecs);
const mountedResetRevision = useRef(resetRevision);
useEffect(() => {
@@ -30,6 +35,12 @@ export function PartyBridge() {
&& onlineActivity.type === (gameMode === "manastorm" ? "manastorm" : "dungeon")
? onlineGroupAiPartySize(onlineActivity.partySize)
: requestedPartySize;
const companionOptions = {
readinessPolicy,
readinessPolicyRevision,
includeBetaSpecs: onlineActivity?.includeBetaSpecs ?? deviceIncludeBetaSpecs,
excludedPlayerSpecializationId: character.specializationId,
};
if (simulationMode === "play") {
party.initializeParty(
character.id,
@@ -38,16 +49,17 @@ export function PartyBridge() {
playerRole,
aiPartySize,
character.categoryId ?? "wow",
companionOptions,
);
} else {
party.initializeSpectatorParty(simulationSeed, combat.level, character.categoryId ?? "wow");
party.initializeSpectatorParty(simulationSeed, combat.level, character.categoryId ?? "wow", companionOptions);
}
usePartyStore.getState().syncEquipment(combat.equipment, combat.inventory);
combat.synchronizeActors();
combat.applyDefaultPartyBuffs();
combat.applyPrecombatPreparation();
resetPartyRuntimeClock();
}, [character?.id, gameMode, manastormPartySize, onlineActivity?.id, playerRole, simulationMode, simulationSeed]);
}, [character?.id, deviceIncludeBetaSpecs, gameMode, manastormPartySize, onlineActivity?.id, onlineActivity?.includeBetaSpecs, playerRole, readinessPolicy, readinessPolicyRevision, simulationMode, simulationSeed]);
useEffect(() => {
const party = usePartyStore.getState();
src/game/abilityCatalog.ts
+50
View File
@@ -486,6 +486,56 @@ const HUNTER = [
] as const;
const ROGUE = [
defineAbility({
id: "rogue-instant-poison", classId: "rogue", dbcSpellId: 57965, name: "Instant Poison",
unlockLevel: 20,
icon: spellIcon("Ability_Poisons"), sigil: "IP", target: "self", range: self,
castTimeMs: 0, cooldownMs: 0, gcdMs: 0, cost: { resource: "energy", amount: 0 },
description: "Coats the main-hand weapon with poison that can deal Nature damage on hit.",
effects: [{
kind: "apply-aura",
aura: {
id: "rogue-instant-poison-main-hand",
name: "Instant Poison",
disposition: "buff",
durationMs: 3_600_000,
exclusiveGroup: "rogue-main-hand-poison",
utilityTags: ["weapon-enchant"],
procs: [{ id: "rogue-instant-poison-proc", triggers: "hit", chance: 0.2,
action: { kind: "damage", amount: 18, school: "nature", target: "event-other" } }],
},
recipient: "caster",
sourceEffectType: 6,
sourceAuraType: 42,
miscValue: 0,
triggerSpellId: 0,
}],
}),
defineAbility({
id: "rogue-deadly-poison", classId: "rogue", dbcSpellId: 57970, name: "Deadly Poison",
unlockLevel: 30,
icon: spellIcon("Ability_Rogue_DualWeild"), sigil: "DP", target: "self", range: self,
castTimeMs: 0, cooldownMs: 0, gcdMs: 0, cost: { resource: "energy", amount: 0 },
description: "Coats the off-hand weapon with a stacking damage-over-time poison.",
effects: [{
kind: "apply-aura",
aura: {
id: "rogue-deadly-poison-off-hand",
name: "Deadly Poison",
disposition: "buff",
durationMs: 3_600_000,
exclusiveGroup: "rogue-off-hand-poison",
utilityTags: ["weapon-enchant"],
procs: [{ id: "rogue-deadly-poison-proc", triggers: "hit", chance: 0.3,
action: { kind: "damage", amount: 12, school: "nature", target: "event-other" } }],
},
recipient: "caster",
sourceEffectType: 6,
sourceAuraType: 42,
miscValue: 0,
triggerSpellId: 0,
}],
}),
defineAbility({
id: "rogue-sinister-strike", classId: "rogue", dbcSpellId: 1752, name: "Sinister Strike",
icon: spellIcon("Spell_Shadow_RitualOfSacrifice"), sigil: "SS", target: "hostile", range: melee,
src/game/benchmark/balanceLabBuilds.test.ts
+33 -1
View File
@@ -1,5 +1,8 @@
import { describe, expect, it } from "vitest";
import { abilitiesForClass } from "../abilityCatalog";
import { rotationProfileFor } from "../combatRotation";
import { createConfiguredPartyMember } from "../partyStore";
import { specializationsForClass } from "../specializationCatalog";
import { runtimeNormalizeTalentRanks } from "../talentRuntimeCatalog";
import {
loadSelectableBenchmarkBuilds,
@@ -12,7 +15,15 @@ describe("balance-lab selectable builds", () => {
"warrior", "paladin", "hunter", "rogue", "priest", "death-knight",
"shaman", "mage", "warlock", "druid",
]);
expect(catalog).toHaveLength(31);
const specializations = new Map<string, typeof catalog>();
for (const build of catalog) {
const key = `${build.classId}:${build.orientation}:${build.role}`;
specializations.set(key, [...(specializations.get(key) ?? []), build]);
}
expect(specializations.size).toBe(31);
expect([...specializations.values()].every((profiles) => profiles.length >= 2)).toBe(true);
expect(catalog.filter((build) => build.defaultTalentBuild)).toHaveLength(31);
expect(catalog.every((build) => build.talentBuildId && build.talentBuildName && build.characterName)).toBe(true);
expect(catalog).toEqual(expect.arrayContaining([
expect.objectContaining({ classId: "hunter", orientation: "Beast Mastery", role: "damage" }),
expect.objectContaining({ classId: "priest", orientation: "Discipline", role: "healer" }),
@@ -29,6 +40,27 @@ describe("balance-lab selectable builds", () => {
expect(Object.keys(beastMastery?.talentRanks ?? {})).not.toHaveLength(0);
});
it("gives every selectable WoW specialization an executable priority rotation", () => {
const catalog = selectableBenchmarkBuildCatalog(80, [
"warrior", "paladin", "hunter", "rogue", "priest", "death-knight",
"shaman", "mage", "warlock", "druid",
]);
const checked = new Set<string>();
for (const build of catalog) {
const key = `${build.classId}:${build.orientation}`;
if (checked.has(key)) continue;
checked.add(key);
const specialization = specializationsForClass(build.classId)
.find((candidate) => candidate.displayName === build.orientation);
const profile = rotationProfileFor(build.classId, specialization?.id, build.orientation);
expect(profile, key).not.toBeNull();
expect(profile!.abilityPriority.length, key).toBeGreaterThan(0);
const abilityNames = new Set(abilitiesForClass(build.classId).map((ability) => ability.name));
expect(profile!.abilityPriority.some((name) => abilityNames.has(name)), key).toBe(true);
}
expect(checked.size).toBe(31);
});
it("keeps each CoA specialization tree selectable", async () => {
const builds = await loadSelectableBenchmarkBuilds(20, ["witch-doctor"]);
expect(builds.map((build) => `${build.orientation}:${build.role}`)).toEqual([
src/game/benchmark/benchmarkBuilds.test.ts
+21 -2
View File
@@ -2,7 +2,11 @@ import { describe, expect, it } from "vitest";
import { CLASSES } from "../../app/characterCatalog";
import { partyRolesForClass } from "../partyRoles";
import { runtimeNormalizeTalentRanks } from "../talentRuntimeCatalog";
import { loadCanonicalBenchmarkBuilds } from "./benchmarkBuilds";
import {
loadCanonicalBenchmarkBuilds,
loadSelectableBenchmarkBuilds,
selectableBenchmarkBuildCatalog,
} from "./benchmarkBuilds";
describe("canonical benchmark builds", () => {
it("covers every declared class-role pair exactly once with legal ranks", async () => {
@@ -17,7 +21,7 @@ describe("canonical benchmark builds", () => {
expect(new Set(actualPairs)).toEqual(new Set(expectedPairs));
for (const build of builds) {
expect(build.level).toBe(60);
expect(build.gearPresetId).toBe("coefficient-empty");
expect(build.gearPresetId).toBe("virtual-heirloom");
expect(build.inventory).toEqual([]);
expect(build.equipment).toEqual({});
expect(runtimeNormalizeTalentRanks(build.classId, build.level, build.talentRanks)).toEqual(build.talentRanks);
@@ -33,4 +37,19 @@ describe("canonical benchmark builds", () => {
"rom-priest:damage",
]);
});
it("keeps both named classic talent builds and marks Playerbots as the default", async () => {
const catalog = selectableBenchmarkBuildCatalog(60, ["mage"]);
const builds = await loadSelectableBenchmarkBuilds(60, ["mage"]);
expect(catalog).toHaveLength(6);
expect(builds).toHaveLength(6);
expect(new Set(builds.map((build) => build.characterName)).size).toBe(6);
for (const specialization of ["Arcane", "Fire", "Frost"]) {
const variants = builds.filter((build) => build.orientation === specialization);
expect(variants).toHaveLength(2);
expect(variants.filter((build) => build.defaultTalentBuild)).toHaveLength(1);
expect(variants.find((build) => build.defaultTalentBuild)?.talentBuildSource)
.toBe("azerothcore-playerbots@531282e");
}
}, 30_000);
});
src/game/benchmark/benchmarkBuilds.ts
+105 -15
View File
@@ -20,7 +20,13 @@ import {
import { aiHintsForAbility } from "../abilityRules";
import type { EquipmentAssignments } from "../equipment";
import { partyRolesForClass, type PartyRole } from "../partyRoles";
import { runtimePartyTalentRanksForLevel } from "../partyTalentRuntime";
import {
runtimeDefaultPartyTalentProfile,
runtimePartyTalentProvenanceForLevel,
runtimePartyTalentProfiles,
runtimePartyTalentRanksForLevel,
type PartyTalentRuntimeProfile,
} from "../partyTalentRuntime";
import { clampPlayerLevel } from "../progression";
import {
specializationsForClass,
@@ -38,9 +44,13 @@ import {
type TalentUiTree,
} from "../talentUiCatalog";
import type { BenchmarkBuildDefinition } from "./benchmarkTypes";
import {
readinessStatusFor,
type CompanionSpecReadinessStatus,
} from "../companionSpecReadiness";
export const CANONICAL_BENCHMARK_LEVEL = 60;
export const CANONICAL_BENCHMARK_GEAR_PRESET_ID = "coefficient-empty";
export const CANONICAL_BENCHMARK_GEAR_PRESET_ID = "virtual-heirloom";
const EMPTY_INVENTORY: readonly never[] = Object.freeze([]);
const EMPTY_EQUIPMENT: EquipmentAssignments = Object.freeze({});
@@ -164,9 +174,13 @@ function benchmarkVariantBuildId(
role: PartyRole,
orientation: string,
level: number,
talentProfile?: PartyTalentRuntimeProfile,
): string {
const variant = orientation.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
return `balance-${contentCategoryForClass(classId)}-${classId}-${role}-${variant}-level-${level}`;
const base = `balance-${contentCategoryForClass(classId)}-${classId}-${role}-${variant}-level-${level}`;
if (!talentProfile || talentProfile.defaultForSpecialization) return base;
const profile = talentProfile.id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
return `${base}--${profile}`;
}
function commonBuildFields(classId: ClassId, role: PartyRole, level: number) {
@@ -192,10 +206,20 @@ function wowBuild(
if (!orientation) {
throw new Error(`No canonical WoW talent orientation exists for ${classId}:${role}.`);
}
const talentProfile = runtimeDefaultPartyTalentProfile(classId, orientation);
const talentProvenance = runtimePartyTalentProvenanceForLevel(talentProfile, level);
return Object.freeze({
...commonBuildFields(classId, role, level),
orientation,
talentRanks: runtimePartyTalentRanksForLevel(classId, orientation, level),
characterName: talentProfile.characterName,
talentBuildId: talentProfile.id,
talentBuildName: talentProfile.name,
talentBuildSource: `${talentProfile.source}@${talentProfile.sourceVersion}`,
talentBuildSourcePointCount: talentProvenance.sourcePointCount,
talentBuildSourcePointsRetained: talentProvenance.sourcePointsRetained,
talentBuildFallbackPointCount: talentProvenance.fallbackPointCount,
defaultTalentBuild: talentProfile.defaultForSpecialization,
talentRanks: runtimePartyTalentRanksForLevel(classId, orientation, level, talentProfile.id),
});
}
@@ -435,11 +459,18 @@ function selectableClassicBuild(
specialization: SpecializationDefinition,
level: number,
catalog: TalentUiCatalog | null,
talentProfile: PartyTalentRuntimeProfile,
): BenchmarkBuildDefinition {
const classId = specialization.classId as BaseClassId;
const talentProvenance = runtimePartyTalentProvenanceForLevel(talentProfile, level);
let talentRanks: RuntimeTalentRanks;
try {
talentRanks = runtimePartyTalentRanksForLevel(classId, specialization.displayName, level);
talentRanks = runtimePartyTalentRanksForLevel(
classId,
specialization.displayName,
level,
talentProfile.id,
);
} catch {
if (!catalog) throw new Error(`No talent catalog was loaded for ${classId}.`);
talentRanks = allocateSingleTreeTalentRanks(
@@ -451,8 +482,22 @@ function selectableClassicBuild(
}
return Object.freeze({
...commonBuildFields(classId, specialization.role, level),
id: benchmarkVariantBuildId(classId, specialization.role, specialization.displayName, level),
id: benchmarkVariantBuildId(
classId,
specialization.role,
specialization.displayName,
level,
talentProfile,
),
orientation: specialization.displayName,
characterName: talentProfile.characterName,
talentBuildId: talentProfile.id,
talentBuildName: talentProfile.name,
talentBuildSource: `${talentProfile.source}@${talentProfile.sourceVersion}`,
talentBuildSourcePointCount: talentProvenance.sourcePointCount,
talentBuildSourcePointsRetained: talentProvenance.sourcePointsRetained,
talentBuildFallbackPointCount: talentProvenance.fallbackPointCount,
defaultTalentBuild: talentProfile.defaultForSpecialization,
talentRanks,
});
}
@@ -486,7 +531,17 @@ export interface SelectableBenchmarkBuildCatalogEntry {
readonly classId: ClassId;
readonly role: PartyRole;
readonly orientation: string;
readonly specializationId?: string;
readonly readinessStatus?: CompanionSpecReadinessStatus;
readonly level: number;
readonly characterName?: string;
readonly talentBuildId?: string;
readonly talentBuildName?: string;
readonly talentBuildSource?: string;
readonly talentBuildSourcePointCount?: number | null;
readonly talentBuildSourcePointsRetained?: number | null;
readonly talentBuildFallbackPointCount?: number;
readonly defaultTalentBuild?: boolean;
}
/** Cheap metadata-only roster used by interactive tools before a build is selected. */
@@ -508,14 +563,42 @@ export function selectableBenchmarkBuildCatalog(
orientation: "Primary",
level: safeLevel,
}));
return specializationsForClass(classId).map((specialization) => ({
id: benchmarkVariantBuildId(classId, specialization.role, specialization.displayName, safeLevel),
source: contentCategoryForClass(classId),
classId,
role: specialization.role,
orientation: specialization.displayName,
level: safeLevel,
}));
return specializationsForClass(classId).flatMap((specialization) => {
const profiles = isBaseClassId(classId)
? runtimePartyTalentProfiles(classId, specialization.displayName)
: [undefined];
return profiles.map((talentProfile) => {
const talentProvenance = talentProfile
? runtimePartyTalentProvenanceForLevel(talentProfile, safeLevel)
: null;
return {
id: benchmarkVariantBuildId(
classId,
specialization.role,
specialization.displayName,
safeLevel,
talentProfile,
),
source: contentCategoryForClass(classId),
classId,
role: specialization.role,
orientation: specialization.displayName,
specializationId: isBaseClassId(classId) ? specialization.id : undefined,
readinessStatus: isBaseClassId(classId) ? readinessStatusFor(specialization.id) : undefined,
level: safeLevel,
characterName: talentProfile?.characterName,
talentBuildId: talentProfile?.id,
talentBuildName: talentProfile?.name,
talentBuildSource: talentProfile
? `${talentProfile.source}@${talentProfile.sourceVersion}`
: undefined,
talentBuildSourcePointCount: talentProvenance?.sourcePointCount,
talentBuildSourcePointsRetained: talentProvenance?.sourcePointsRetained,
talentBuildFallbackPointCount: talentProvenance?.fallbackPointCount,
defaultTalentBuild: talentProfile?.defaultForSpecialization,
};
});
});
});
}
@@ -561,7 +644,14 @@ export async function loadSelectableBenchmarkBuilds(
}
for (const specialization of specializationsForClass(classId)) {
if (isBaseClassId(classId)) {
builds.push(selectableClassicBuild(specialization, safeLevel, catalogs.get(classId) ?? null));
for (const talentProfile of runtimePartyTalentProfiles(classId, specialization.displayName)) {
builds.push(selectableClassicBuild(
specialization,
safeLevel,
catalogs.get(classId) ?? null,
talentProfile,
));
}
} else if (isCoaClassId(classId)) {
const catalog = catalogs.get(classId);
if (!catalog) throw new Error(`No loaded CoA talent catalog exists for ${classId}.`);
src/game/benchmark/benchmarkController.ts
+1
View File
@@ -231,6 +231,7 @@ export class BenchmarkController {
health: member.health,
maxHealth: member.maxHealth,
fallen: member.health <= 0,
role: member.role,
})),
],
hostileCount: scenario.hostileTargets,
src/game/benchmark/benchmarkTypes.ts
+8
View File
@@ -51,6 +51,14 @@ export interface BenchmarkBuildDefinition {
readonly role: PartyRole;
readonly level: number;
readonly orientation: string;
readonly characterName?: string;
readonly talentBuildId?: string;
readonly talentBuildName?: string;
readonly talentBuildSource?: string;
readonly talentBuildSourcePointCount?: number | null;
readonly talentBuildSourcePointsRetained?: number | null;
readonly talentBuildFallbackPointCount?: number;
readonly defaultTalentBuild?: boolean;
readonly talentRanks: Readonly<Record<string, number>>;
readonly inventory: readonly never[];
readonly equipment: EquipmentAssignments;
src/game/bossTesting.test.ts
+11
View File
@@ -99,6 +99,17 @@ describe("Boss Testing", () => {
expect(nativeHealth).toBeLessThan(100);
expect(testing).toMatchObject({ level: 2, maxHealth: 540 });
const level80 = dungeonEnemyScaling(
room.definition,
entity,
zereketh.spawn.id,
80,
room.definition.defaultDifficultyId,
1,
);
expect(level80.maxHealth).toBeGreaterThanOrEqual(26_400);
expect(level80.maxHealth).toBeLessThanOrEqual(59_400);
expect(level80.damageMultiplier).toBeCloseTo((entity.combat?.damageMultiplier ?? 1) * 0.75);
});
it("omits the campaign finale bonus even when testing the source dungeon's final boss", () => {
src/game/combatRotation.test.ts
+142
View File
@@ -143,6 +143,33 @@ describe("shared combat rotations", () => {
expect(abilityIsPrecombatPreparation(temporaryPet)).toBe(false);
});
it("uses an eligible defensive before a configured incoming boss mechanic", () => {
const defensive = ability("paladin", "Divine Protection");
const decision = evaluateCombatRotation(context({
classId: "paladin",
specializationId: "paladin:protection",
role: "tank",
primaryResource: "mana",
resources: { mana: 10_000 },
maximumResources: { mana: 10_000 },
abilities: [defensive],
incomingDefensiveMechanic: {
id: "tank-buster",
enabled: true,
bossKey: "test/boss",
bossName: "Test Boss",
bossServerEntry: 1,
attackId: "heavy-strike",
attackName: "Heavy Strike",
scope: "tank",
leadTimeMs: 2_500,
minimumCooldownSeconds: 20,
},
}));
expect(decision?.ability.name).toBe("Divine Protection");
expect(decision?.ruleId).toBe("preemptive-tank-buster");
});
it("gates representative signature abilities from every class by their exact talent node", () => {
for (const [classId, name] of Object.entries(SIGNATURES)) {
const signature = ability(classId as RotationContext["classId"], name);
@@ -178,6 +205,67 @@ describe("shared combat rotations", () => {
}
});
it("keeps every required Ready-spec mechanic in its learned Playerbots profile", () => {
const contracts = [
{ classId: "warrior" as const, specialization: "Protection", id: "warrior:protection", actions: ["Defensive Stance", "Taunt", "Shield Bash", "Shield Slam", "Revenge", "Devastate", "Thunder Clap", "Shield Block", "Shield Wall", "Last Stand", "Enraged Regeneration"] },
{ classId: "priest" as const, specialization: "Discipline", id: "priest:discipline", actions: ["Penance", "Power Word: Shield", "Flash Heal", "Greater Heal", "Renew", "Dispel Magic", "Cure Disease", "Resurrection", "Pain Suppression", "Inner Focus", "Power Infusion", "Shadowfiend"] },
{ classId: "hunter" as const, specialization: "Marksmanship", id: "hunter:marksmanship", actions: ["Call Pet", "Aspect of the Dragonhawk", "Serpent Sting", "Chimera Shot", "Aimed Shot", "Arcane Shot", "Steady Shot", "Kill Shot", "Rapid Fire", "Readiness", "Misdirection", "Feign Death", "Silencing Shot", "Disengage"] },
{ classId: "mage" as const, specialization: "Fire", id: "mage:fire", actions: ["Molten Armor", "Living Bomb", "Fireball", "Scorch", "Fire Blast", "Combustion", "Mirror Image", "Counterspell", "Fire Ward", "Frost Ward", "Ice Block", "Blink"] },
{ classId: "rogue" as const, specialization: "Assassination", id: "rogue:assassination", actions: ["Instant Poison", "Deadly Poison", "Mutilate", "Rupture", "Envenom", "Cold Blood", "Kick", "Tricks of the Trade", "Evasion", "Cloak of Shadows", "Vanish"] },
];
for (const contract of contracts) {
const profile = rotationProfileFor(contract.classId, contract.id)!;
const talents = runtimePartyTalentRanksForLevel(contract.classId, contract.specialization, 80);
for (const name of contract.actions) {
expect(profile.abilityPriority, `${contract.id}:${name} priority`).toContain(name);
expect(learnedAbilityForBuild(ability(contract.classId, name), 80, talents), `${contract.id}:${name} learned`)
.not.toBeNull();
}
}
});
it("executes Ready-spec taunts, dispels, resurrection, interrupts, threat redirects, and movement reactively", () => {
const warriorTalents = runtimePartyTalentRanksForLevel("warrior", "Protection", 80);
const taunt = learnedAbilityForBuild(ability("warrior", "Taunt"), 80, warriorTalents)!;
expect(evaluateCombatRotation(context({ classId: "warrior", specializationId: "warrior:protection", role: "tank", primaryResource: "rage", resources: { rage: 100 }, maximumResources: { rage: 100 }, abilities: [taunt], targetIsLoose: true }))?.ability.name)
.toBe("Taunt");
const priestTalents = runtimePartyTalentRanksForLevel("priest", "Discipline", 80);
const dispel = learnedAbilityForBuild(ability("priest", "Dispel Magic"), 80, priestTalents)!;
const resurrection = learnedAbilityForBuild(ability("priest", "Resurrection"), 80, priestTalents)!;
const priest = context({ classId: "priest", specializationId: "priest:discipline", role: "healer", primaryResource: "mana", resources: { mana: 10_000 }, maximumResources: { mana: 10_000 } });
expect(evaluateCombatRotation({ ...priest, abilities: [dispel], friendlyTargets: [{ id: "ally", health: 500, maxHealth: 1_000, needsDispel: true }] })?.ability.name)
.toBe("Dispel Magic");
expect(evaluateCombatRotation({ ...priest, abilities: [resurrection], friendlyTargets: [{ id: "ally", health: 0, maxHealth: 1_000, fallen: true }] })?.ability.name)
.toBe("Resurrection");
for (const row of [
{ classId: "hunter" as const, specializationId: "hunter:marksmanship", specialization: "Marksmanship", name: "Silencing Shot", resource: "mana" as const },
{ classId: "mage" as const, specializationId: "mage:fire", specialization: "Fire", name: "Counterspell", resource: "mana" as const },
{ classId: "rogue" as const, specializationId: "rogue:assassination", specialization: "Assassination", name: "Kick", resource: "energy" as const },
]) {
const learned = learnedAbilityForBuild(ability(row.classId, row.name), 80,
runtimePartyTalentRanksForLevel(row.classId, row.specialization, 80))!;
expect(evaluateCombatRotation(context({
classId: row.classId,
specializationId: row.specializationId,
primaryResource: row.resource,
resources: { [row.resource]: 10_000 },
maximumResources: { [row.resource]: 10_000 },
abilities: [learned],
hostileTarget: { id: "caster", health: 10_000, maxHealth: 10_000, activeCast: { interruptible: true } },
}))?.ability.name).toBe(row.name);
}
const hunterTalents = runtimePartyTalentRanksForLevel("hunter", "Marksmanship", 80);
const misdirection = learnedAbilityForBuild(ability("hunter", "Misdirection"), 80, hunterTalents)!;
const disengage = learnedAbilityForBuild(ability("hunter", "Disengage"), 80, hunterTalents)!;
const hunter = context({ classId: "hunter", specializationId: "hunter:marksmanship", primaryResource: "mana", resources: { mana: 10_000 }, maximumResources: { mana: 10_000 }, friendlyTargets: [{ id: "tank", health: 1_000, maxHealth: 1_000, role: "tank" }] });
expect(evaluateCombatRotation({ ...hunter, abilities: [misdirection], hostileTarget: { id: "boss", health: 100_000, maxHealth: 100_000, boss: true } }))
.toMatchObject({ ability: { name: "Misdirection" }, targetId: "tank" });
expect(evaluateCombatRotation({ ...hunter, abilities: [disengage], moving: true })?.ability.name).toBe("Disengage");
});
it("keeps specialization talent actions isolated", () => {
const furyTalents = runtimePartyTalentRanksForLevel("warrior", "Fury", 80);
const armsTalents = runtimePartyTalentRanksForLevel("warrior", "Arms", 80);
@@ -189,6 +277,60 @@ describe("shared combat rotations", () => {
expect(learnedAbilityForBuild(bloodthirst, 80, armsTalents)).toBeNull();
});
it("certifies major offensive and defensive cooldown decisions for the Ready five", () => {
const cases = [
{ classId: "warrior" as const, specialization: "Protection", specializationId: "warrior:protection", offensive: null, defensive: "Shield Wall", role: "tank" as const },
{ classId: "priest" as const, specialization: "Discipline", specializationId: "priest:discipline", offensive: "Power Infusion", defensive: "Pain Suppression", role: "healer" as const },
{ classId: "hunter" as const, specialization: "Marksmanship", specializationId: "hunter:marksmanship", offensive: "Rapid Fire", defensive: "Feign Death", role: "damage" as const },
{ classId: "mage" as const, specialization: "Fire", specializationId: "mage:fire", offensive: "Combustion", defensive: "Ice Block", role: "damage" as const },
{ classId: "rogue" as const, specialization: "Assassination", specializationId: "rogue:assassination", offensive: "Cold Blood", defensive: "Evasion", role: "damage" as const },
];
for (const row of cases) {
const talents = runtimePartyTalentRanksForLevel(row.classId, row.specialization, 80);
const learned = (name: string) => learnedAbilityForBuild(ability(row.classId, name), 80, talents)!;
const primaryResource = resourceProfileForClass(row.classId).type;
const shared = context({
classId: row.classId,
specializationId: row.specializationId,
specialization: row.specialization,
role: row.role,
primaryResource,
resources: { [primaryResource]: 100_000 },
maximumResources: { [primaryResource]: 100_000 },
hostileTarget: { id: "boss", health: 100_000, maxHealth: 100_000, boss: true },
friendlyTargets: [{ id: "tank", health: 1_000, maxHealth: 1_000, role: "tank" }],
});
if (row.offensive) {
const offensive = learned(row.offensive);
expect(offensive, `${row.specializationId}:${row.offensive}`).toBeDefined();
expect(evaluateCombatRotation({ ...shared, abilities: [offensive] })?.ability.name)
.toBe(row.offensive);
}
const defensive = learned(row.defensive);
expect(defensive, `${row.specializationId}:${row.defensive}`).toBeDefined();
const defensiveContext = row.defensive === "Feign Death"
? { ...shared, abilities: [defensive], hasDangerousThreat: true }
: { ...shared, abilities: [defensive], health: 250 };
expect(evaluateCombatRotation(defensiveContext)?.ability.name).toBe(row.defensive);
}
});
it("uses Marksmanship Readiness only on a durable target", () => {
const talents = runtimePartyTalentRanksForLevel("hunter", "Marksmanship", 80);
const readiness = learnedAbilityForBuild(ability("hunter", "Readiness"), 80, talents)!;
const base = context({
classId: "hunter",
specializationId: "hunter:marksmanship",
primaryResource: "mana",
resources: { mana: 10_000 },
maximumResources: { mana: 10_000 },
abilities: [readiness],
});
expect(evaluateCombatRotation(base)).toBeNull();
expect(evaluateCombatRotation({ ...base, hostileTarget: { id: "boss", health: 100_000, maxHealth: 100_000, boss: true } })?.ability.name)
.toBe("Readiness");
});
it("uses combo builders before finishers and actual combo points for the decision", () => {
const builder = ability("rogue", "Sinister Strike");
const finisher = ability("rogue", "Eviscerate");
src/game/combatRotation.ts
+72 -15
View File
@@ -6,8 +6,13 @@ import { channelAmountEffects } from "./combatChannelAmounts";
import { spendDeathKnightRunes } from "./combatResources";
import { healingAbilityCanAidOthers } from "./healingAbilityRules";
import type { PartyRole } from "./partyRoles";
import {
currentCompanionCooldownPolicy,
type CompanionCooldownMechanicRule,
type CompanionCooldownPolicy,
} from "./companionCooldownPolicy";
export const COMBAT_ROTATION_VERSION = "playerbots-inspired-v4";
export const COMBAT_ROTATION_VERSION = "playerbots-inspired-v5-ready-five";
export interface RotationProfile {
readonly id: string;
@@ -22,6 +27,7 @@ export interface RotationFriendlyTarget {
readonly maxHealth: number;
readonly needsDispel?: boolean;
readonly fallen?: boolean;
readonly role?: PartyRole;
}
export interface RotationHostileTarget {
@@ -67,6 +73,8 @@ export interface RotationContext {
/** Proc/state-gated actions that the caller has positively made available. */
readonly availableConditionalAbilityNames?: ReadonlySet<string>;
readonly canUseAbility?: (ability: AbilityDefinition) => boolean;
readonly cooldownPolicy?: CompanionCooldownPolicy;
readonly incomingDefensiveMechanic?: CompanionCooldownMechanicRule | null;
}
export interface RotationDecision {
@@ -92,17 +100,17 @@ const profile = (
export const CLASSIC_ROTATION_PROFILES: readonly RotationProfile[] = Object.freeze([
profile("warrior:arms", "warrior", ["Battle Stance", "Bloodrage", "Rend", "Mortal Strike", "Bladestorm", "Overpower", "Execute", "Slam", "Heroic Strike"]),
profile("warrior:fury", "warrior", ["Berserker Stance", "Battle Stance", "Bloodrage", "Bloodthirst", "Whirlwind", "Execute", "Sunder Armor", "Heroic Strike"]),
profile("warrior:protection", "warrior", ["Defensive Stance", "Battle Stance", "Bloodrage", "Shield Slam", "Revenge", "Devastate", "Thunder Clap", "Sunder Armor", "Heroic Strike"]),
profile("warrior:protection", "warrior", ["Defensive Stance", "Shield Block", "Last Stand", "Shield Wall", "Enraged Regeneration", "Taunt", "Shield Bash", "Bloodrage", "Shield Slam", "Revenge", "Devastate", "Thunder Clap", "Sunder Armor", "Heroic Strike"]),
profile("paladin:holy", "paladin", ["Concentration Aura", "Devotion Aura", "Blessing of Might", "Seal of Wisdom", "Seal of Light", "Seal of Righteousness", "Holy Shock", "Flash of Light", "Holy Light", "Sacred Shield", "Judgement of Light"]),
profile("paladin:protection", "paladin", ["Devotion Aura", "Blessing of Might", "Seal of Vengeance", "Seal of Corruption", "Seal of Wisdom", "Seal of Righteousness", "Hammer of the Righteous", "Shield of Righteousness", "Holy Shield", "Consecration", "Judgement of Wisdom"]),
profile("paladin:retribution", "paladin", ["Retribution Aura", "Devotion Aura", "Blessing of Might", "Seal of Command", "Seal of Vengeance", "Seal of Corruption", "Seal of Righteousness", "Divine Storm", "Crusader Strike", "Judgement of Wisdom", "Consecration", "Exorcism", "Hammer of Wrath"]),
profile("hunter:beast-mastery", "hunter", ["Aspect of the Dragonhawk", "Aspect of the Hawk", "Call Pet", "Kill Command", "Bestial Wrath", "Serpent Sting", "Arcane Shot", "Multi-Shot", "Steady Shot"]),
profile("hunter:marksmanship", "hunter", ["Aspect of the Dragonhawk", "Aspect of the Hawk", "Call Pet", "Kill Shot", "Chimera Shot", "Aimed Shot", "Serpent Sting", "Arcane Shot", "Steady Shot"]),
profile("hunter:marksmanship", "hunter", ["Aspect of the Dragonhawk", "Aspect of the Hawk", "Call Pet", "Misdirection", "Rapid Fire", "Readiness", "Kill Shot", "Chimera Shot", "Aimed Shot", "Serpent Sting", "Arcane Shot", "Steady Shot", "Silencing Shot", "Disengage", "Feign Death"]),
profile("hunter:survival", "hunter", ["Aspect of the Dragonhawk", "Aspect of the Hawk", "Call Pet", "Kill Shot", "Explosive Shot", "Black Arrow", "Serpent Sting", "Aimed Shot", "Arcane Shot", "Steady Shot"]),
profile("rogue:assassination", "rogue", ["Envenom", "Rupture", "Mutilate", "Eviscerate", "Sinister Strike"]),
profile("rogue:assassination", "rogue", ["Deadly Poison", "Instant Poison", "Tricks of the Trade", "Cold Blood", "Envenom", "Rupture", "Mutilate", "Eviscerate", "Sinister Strike", "Kick", "Evasion", "Cloak of Shadows", "Vanish"]),
profile("rogue:combat", "rogue", ["Killing Spree", "Blade Flurry", "Eviscerate", "Sinister Strike"]),
profile("rogue:subtlety", "rogue", ["Shadow Dance", "Rupture", "Eviscerate", "Hemorrhage", "Backstab"]),
profile("priest:discipline", "priest", ["Inner Fire", "Penance", "Power Word: Shield", "Flash Heal", "Greater Heal", "Renew"]),
profile("priest:discipline", "priest", ["Inner Fire", "Pain Suppression", "Inner Focus", "Power Infusion", "Shadowfiend", "Divine Hymn", "Penance", "Power Word: Shield", "Flash Heal", "Greater Heal", "Renew", "Dispel Magic", "Cure Disease", "Resurrection"]),
profile("priest:holy", "priest", ["Inner Fire", "Circle of Healing", "Prayer of Mending", "Flash Heal", "Greater Heal", "Renew"]),
profile("priest:shadow", "priest", ["Shadowform", "Inner Fire", "Vampiric Touch", "Devouring Plague", "Shadow Word: Pain", "Mind Blast", "Mind Flay", "Shadow Word: Death"]),
profile("death-knight:blood", "death-knight", ["Frost Presence", "Blood Presence", "Heart Strike", "Death Strike", "Icy Touch", "Plague Strike", "Death Coil"]),
@@ -112,7 +120,7 @@ export const CLASSIC_ROTATION_PROFILES: readonly RotationProfile[] = Object.free
profile("shaman:enhancement", "shaman", ["Windfury Weapon", "Rockbiter Weapon", "Lightning Shield", "Feral Spirit", "Stormstrike", "Lava Lash", "Earth Shock", "Lightning Bolt"]),
profile("shaman:restoration", "shaman", ["Water Shield", "Rockbiter Weapon", "Lightning Shield", "Riptide", "Chain Heal", "Lesser Healing Wave", "Healing Wave", "Earth Shield"]),
profile("mage:arcane", "mage", ["Mage Armor", "Ice Armor", "Frost Armor", "Arcane Barrage", "Arcane Blast", "Arcane Missiles"]),
profile("mage:fire", "mage", ["Molten Armor", "Mage Armor", "Ice Armor", "Frost Armor", "Living Bomb", "Fireball", "Scorch", "Fire Blast"]),
profile("mage:fire", "mage", ["Molten Armor", "Combustion", "Mirror Image", "Living Bomb", "Fireball", "Scorch", "Fire Blast", "Counterspell", "Blink", "Ice Block", "Fire Ward", "Frost Ward"]),
profile("mage:frost", "mage", ["Frost Armor", "Ice Armor", "Mage Armor", "Deep Freeze", "Frostbolt", "Ice Lance", "Cone of Cold"]),
profile("warlock:affliction", "warlock", ["Fel Armor", "Demon Armor", "Demon Skin", "Summon Felhunter", "Summon Voidwalker", "Summon Imp", "Haunt", "Unstable Affliction", "Corruption", "Curse of Agony", "Drain Soul", "Shadow Bolt"]),
profile("warlock:demonology", "warlock", ["Fel Armor", "Demon Armor", "Demon Skin", "Summon Felguard", "Summon Voidwalker", "Summon Imp", "Metamorphosis", "Immolate", "Corruption", "Shadow Bolt"]),
@@ -133,6 +141,14 @@ const CONDITIONAL_ABILITY_NAMES = new Set([
"Victory Rush",
]);
const DEFENSIVE_COOLDOWN_NAMES = new Set([
"Shield Block", "Last Stand", "Shield Wall", "Enraged Regeneration",
"Pain Suppression", "Ice Block", "Fire Ward", "Frost Ward",
"Evasion", "Cloak of Shadows", "Vanish",
]);
const THREAT_REDIRECT_NAMES = new Set(["Misdirection", "Tricks of the Trade"]);
const TARGET_HEALTH_GATES = new Map<string, number>([
["Drain Soul", 0.25],
["Hammer of Wrath", 0.2],
@@ -275,6 +291,10 @@ function targetForAbility(
lowest: RotationFriendlyTarget | null,
): string | null {
const categories = new Set(aiHintsForAbility(ability).categories);
if (THREAT_REDIRECT_NAMES.has(ability.name)) {
return context.friendlyTargets?.find((target) => target.role === "tank" && !target.fallen)?.id
?? context.selfId ?? null;
}
const casterOnly = ability.target === "self" || (ability.effects.some((effect) => (
"recipient" in effect && effect.recipient === "caster"
)) && !ability.effects.some((effect) => (
@@ -337,9 +357,12 @@ function scoreAbility(
const damaging = categories.has("damage") || categories.has("execute")
|| channelAmounts.some(({ effect }) => effect.kind === "damage" || effect.kind === "dot");
const healingCategory = categories.has("heal") || categories.has("emergency-heal") || categories.has("area-heal");
const defensive = categories.has("mitigation") || categories.has("heal");
const offensiveMajorCooldown = ability.cooldownMs >= 60_000 && !defensive
&& (damaging || categories.has("buff") || categories.has("summon") || categories.has("pet"));
const namedDefensiveCooldown = DEFENSIVE_COOLDOWN_NAMES.has(ability.name);
const defensive = categories.has("mitigation") || categories.has("heal") || namedDefensiveCooldown;
const cooldownPolicy = context.cooldownPolicy ?? currentCompanionCooldownPolicy();
const offensiveMajorCooldown = ability.cooldownMs >= cooldownPolicy.generic.offensiveMajorCooldownSeconds * 1_000 && !defensive
&& (damaging || categories.has("buff") || categories.has("summon") || categories.has("pet")
|| ability.effects.some((effect) => effect.kind === "cooldown-reset"));
const durableTarget = Boolean(
context.hostileTarget?.boss
|| (context.hostileTarget?.healthMultiplier ?? 1) > 1
@@ -374,7 +397,7 @@ function scoreAbility(
if (categories.has("dispel")) {
const dispel = (context.friendlyTargets ?? []).find((target) => target.needsDispel);
if (dispel) return { ability, score: 1_019_000, ruleId: "reactive-dispel", reason: "ally needs dispel", targetId: dispel.id };
if (!damaging) return null;
if (!damaging && !namedDefensiveCooldown) return null;
}
if (categories.has("interrupt")) {
if (!context.hostileTarget?.activeCast?.interruptible) {
@@ -388,6 +411,15 @@ function scoreAbility(
return { ability, score: 1_017_000, ruleId: "reactive-taunt", reason: "loose hostile target", targetId: context.hostileTarget?.id ?? null };
}
if (categories.has("threat") && !damaging && !maintenanceBuff) {
if (THREAT_REDIRECT_NAMES.has(ability.name) && context.role !== "tank" && durableTarget) {
return {
ability,
score: 1_015_500,
ruleId: "preemptive-threat-redirect",
reason: "redirect opening threat to the tank",
targetId: targetForAbility(ability, context, lowest),
};
}
if (context.role === "tank" || !context.hasDangerousThreat) return null;
return {
ability,
@@ -398,6 +430,25 @@ function scoreAbility(
};
}
if (categories.has("control") && !context.requiredControl && !damaging) return null;
if (namedDefensiveCooldown && context.incomingDefensiveMechanic) {
return {
ability,
score: 1_014_500 + (hints.priority ?? 0),
ruleId: `preemptive-${context.incomingDefensiveMechanic.id}`,
reason: `pre-empt ${context.incomingDefensiveMechanic.attackName}`,
targetId: targetForAbility(ability, context, lowest),
};
}
if (categories.has("mitigation") && context.incomingDefensiveMechanic
&& ability.cooldownMs >= context.incomingDefensiveMechanic.minimumCooldownSeconds * 1_000) {
return {
ability,
score: 1_014_000 + (hints.priority ?? 0),
ruleId: `preemptive-${context.incomingDefensiveMechanic.id}`,
reason: `pre-empt ${context.incomingDefensiveMechanic.attackName}`,
targetId: targetForAbility(ability, context, lowest),
};
}
// A friendly heal without an injured recipient must never fall through to
// the hostile target. Hybrid damage builds otherwise refresh HoTs on enemies
// forever because those auras also look like maintenance buffs.
@@ -426,7 +477,11 @@ function scoreAbility(
if (context.requiredControl && categories.has("control")) {
return { ability, score: 1_016_000, ruleId: "reactive-control", reason: "encounter requested control", targetId: context.hostileTarget?.id ?? null };
}
if (offensiveMajorCooldown && !durableTarget) return null;
if (offensiveMajorCooldown && cooldownPolicy.generic.conserveOffensiveCooldownsForDurableTargets && !durableTarget) return null;
if (namedDefensiveCooldown && !context.incomingDefensiveMechanic) {
const threshold = cooldownPolicy.generic.defensiveHealthPercent / 100;
if (selfHealth >= threshold && lowestHealth >= threshold) return null;
}
if (maintained && (categories.has("debuff") || categories.has("buff"))) return null;
if (activeSummon && (categories.has("summon") || categories.has("pet"))) return null;
if (rotationProfile && profileIndex < 0 && !damaging && (maintenanceBuff || petSummon || offensiveSummon)) return null;
@@ -455,7 +510,6 @@ function scoreAbility(
ruleId = `profile-${slug(ability.name)}`;
reason = `${rotationProfile!.specializationId} priority ${profileIndex + 1}`;
}
if (context.role === "healer") {
const healing = actionableHealing
&& (healingAbilityCanAidOthers(ability) || lowest?.id === context.selfId);
@@ -468,7 +522,8 @@ function scoreAbility(
if (categories.has("area-heal")) score += injured.length >= 3 ? 6_500 : -1_200;
score += Math.min(500, throughput(ability, context.comboPoints) * 10);
} else if (categories.has("mitigation")) {
if (lowestHealth >= 0.8 && selfHealth >= 0.8) return null;
const threshold = cooldownPolicy.generic.healerMitigationHealthPercent / 100;
if (lowestHealth >= threshold && selfHealth >= threshold) return null;
score += 2_500;
} else if (maintenanceBuff) {
score += context.maintainedAbilityIds === undefined ? 1_600 : maintenanceScore;
@@ -483,8 +538,10 @@ function scoreAbility(
}
} else {
if (categories.has("mitigation")) {
if (!maintenanceBuff && selfHealth >= 0.55) return null;
if (selfHealth < 0.55) score += selfHealth < 0.35 ? 180_000 : 140_000;
const defensiveThreshold = cooldownPolicy.generic.defensiveHealthPercent / 100;
const emergencyThreshold = cooldownPolicy.generic.emergencyHealthPercent / 100;
if (!maintenanceBuff && selfHealth >= defensiveThreshold) return null;
if (selfHealth < defensiveThreshold) score += selfHealth < emergencyThreshold ? 180_000 : 140_000;
}
if (categories.has("execute")) {
if (targetHealth > 0.2) return null;
src/game/combatStore.test.ts
+26 -2
View File
@@ -741,6 +741,30 @@ describe("combat store", () => {
expect(useCombatStore.getState().mobs["party-victim"].targetActorId).toBe(target.id);
});
it("grants companion Warriors Rage when enemy attacks land", () => {
const tank = usePartyStore.getState().members.find((member) => member.resourcePools.rage !== undefined)!;
usePartyStore.setState((state) => ({
members: state.members.map((member) => member.id === tank.id
? { ...member, resource: 0, resourcePools: { ...member.resourcePools, rage: 0 } }
: member),
}));
registerPartyRuntimePosition(tank.id, [0, 0, 0]);
useCombatStore.getState().registerMob("rage-attacker", {
name: "Rage attacker",
maxHealth: 200,
xpReward: 0,
});
setMobPosition("rage-attacker", [2, 0, 0]);
useCombatStore.getState().damageMob("rage-attacker", 5, 1_000, {
actorId: tank.id,
role: "tank",
});
expect(useCombatStore.getState().advanceMobCombat(1_450)).toBeGreaterThan(0);
expect(usePartyStore.getState().members.find((member) => member.id === tank.id)?.resourcePools.rage)
.toBe(7);
});
it("clears all aggro state on encounter reset", () => {
registerTarget("reset-threat", [2, 0, 0], 100, 0);
useCombatStore.getState().damageMob("reset-threat", 1, 1_000);
@@ -949,9 +973,9 @@ describe("combat store", () => {
it("tracks rogue combo points and consumes them with Eviscerate", () => {
useCombatStore.getState().initializeCharacter({ classId: "rogue" });
registerTarget("fang", [2, 0, 0], 100);
expect(useCombatStore.getState().castSlot(0, undefined, 1000).ok).toBe(true);
expect(useCombatStore.getState().castAbility("rogue-sinister-strike", undefined, 1000).ok).toBe(true);
expect(useCombatStore.getState().comboPoints).toBe(1);
expect(useCombatStore.getState().castSlot(1, undefined, 2000).ok).toBe(true);
expect(useCombatStore.getState().castAbility("rogue-eviscerate", undefined, 2000).ok).toBe(true);
expect(useCombatStore.getState().comboPoints).toBe(0);
expect(useCombatStore.getState().mobs.fang.health).toBeLessThan(100);
expect(useCombatStore.getState().lastCombatResult).not.toBeNull();
src/game/combatStore.ts
+15 -5
View File
@@ -990,8 +990,8 @@ function clamp(value: number, min: number, max: number): number {
}
const ROM_RAGE_CLASSES = new Set<ClassId>(["rom-warrior", "rom-champion"]);
const ROM_RAGE_PER_AUTO_ATTACK = 6;
const ROM_RAGE_PER_HIT_TAKEN = 7;
const RAGE_PER_AUTO_ATTACK = 6;
const RAGE_PER_HIT_TAKEN = 7;
const ROM_CHAMPION_RAGE_PER_SECOND = 6;
const PLAYER_AUTO_ATTACK_RANGE = 5;
@@ -6526,7 +6526,7 @@ export const useCombatStore = create<CombatState>((set, get) => ({
hasRomWarriorRagePool(state.classId, state.secondaryClassId)
|| (!hasRomRagePool(state.classId, state.secondaryClassId) && state.maxResourcePools.rage !== undefined)
)
? ROM_RAGE_PER_HIT_TAKEN
? RAGE_PER_HIT_TAKEN
: 0,
state.resource,
state.maxResource,
@@ -7554,7 +7554,7 @@ export const useCombatStore = create<CombatState>((set, get) => ({
hasRomWarriorRagePool(current.classId, current.secondaryClassId)
|| (!hasRomRagePool(current.classId, current.secondaryClassId) && current.maxResourcePools.rage !== undefined)
)
? ROM_RAGE_PER_HIT_TAKEN
? RAGE_PER_HIT_TAKEN
: 0,
current.resource,
current.maxResource,
@@ -7823,11 +7823,21 @@ export const useCombatStore = create<CombatState>((set, get) => ({
};
}
}
const ragePool = authoritativeActor.resources.rage;
const nextActor: CombatActorState = {
...authoritativeActor,
health: authoritativeActor.health - damaged,
alive: authoritativeActor.health - damaged > 0,
cast: authoritativeActor.health - damaged > 0 ? nextCast : null,
resources: damaged > 0 && ragePool
? {
...authoritativeActor.resources,
rage: {
...ragePool,
current: Math.min(ragePool.maximum, ragePool.current + RAGE_PER_HIT_TAKEN),
},
}
: authoritativeActor.resources,
};
mirrorCompanionActor(nextActor);
if (redirected > 0) {
@@ -8114,7 +8124,7 @@ export const useCombatStore = create<CombatState>((set, get) => ({
const rage = gainRomRage(
state.classId,
state.secondaryClassId,
ROM_RAGE_PER_AUTO_ATTACK,
RAGE_PER_AUTO_ATTACK,
work.resource,
work.maxResource,
work.resourcePools,
src/game/companionCooldownPolicy.test.ts
+46
View File
@@ -0,0 +1,46 @@
import { describe, expect, it } from "vitest";
import {
DEFAULT_COMPANION_COOLDOWN_POLICY,
imminentCooldownMechanic,
normalizeCompanionCooldownPolicy,
} from "./companionCooldownPolicy";
const policy = normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
mechanics: [{
id: "tank-buster", enabled: true, bossKey: "test/boss", bossName: "Test Boss",
bossServerEntry: 123, attackId: "heavy-strike", attackName: "Heavy Strike",
scope: "tank", leadTimeMs: 2_500, minimumCooldownSeconds: 20,
}],
});
describe("companion cooldown policy", () => {
it("matches configured cooldown windows only for the selected boss and role", () => {
const mob = { serverEntry: 123, abilityReadyAt: { "heavy-strike": 3_000 } };
expect(imminentCooldownMechanic(mob, "tank", 1_000, policy)?.id).toBe("tank-buster");
expect(imminentCooldownMechanic(mob, "damage", 1_000, policy)).toBeNull();
expect(imminentCooldownMechanic({ ...mob, serverEntry: 456 }, "tank", 1_000, policy)).toBeNull();
expect(imminentCooldownMechanic(mob, "tank", 6_000, policy)).toBeNull();
});
it("matches an active cast inside the configured lead time", () => {
expect(imminentCooldownMechanic({
serverEntry: 123,
activeCast: { attackId: "heavy-strike", completesAt: 3_000 },
}, "tank", 1_000, policy)?.attackName).toBe("Heavy Strike");
});
it("uses the authored boss name when an encounter has no server entry", () => {
const namePolicy = normalizeCompanionCooldownPolicy({
...DEFAULT_COMPANION_COOLDOWN_POLICY,
mechanics: [{
id: "name-only", enabled: true, bossKey: "test/name-only", bossName: "Named Boss",
bossServerEntry: null, attackId: "heavy-strike", attackName: "Heavy Strike",
scope: "party", leadTimeMs: 2_500, minimumCooldownSeconds: 20,
}],
});
const window = { name: "Named Boss", abilityReadyAt: { "heavy-strike": 3_000 } };
expect(imminentCooldownMechanic(window, "healer", 1_000, namePolicy)?.id).toBe("name-only");
expect(imminentCooldownMechanic({ ...window, name: "Other Boss" }, "healer", 1_000, namePolicy)).toBeNull();
});
});
src/game/companionCooldownPolicy.ts
+123
View File
@@ -0,0 +1,123 @@
import type { PartyRole } from "./partyRoles";
export interface CompanionCooldownGenericRules {
readonly defensiveHealthPercent: number;
readonly emergencyHealthPercent: number;
readonly healerMitigationHealthPercent: number;
readonly offensiveMajorCooldownSeconds: number;
readonly conserveOffensiveCooldownsForDurableTargets: boolean;
}
export interface CompanionCooldownMechanicRule {
readonly id: string;
readonly enabled: boolean;
readonly bossKey: string;
readonly bossName: string;
readonly bossServerEntry: number | null;
readonly attackId: string;
readonly attackName: string;
readonly scope: "tank" | "party";
readonly leadTimeMs: number;
readonly minimumCooldownSeconds: number;
}
export interface CompanionCooldownPolicy {
readonly schemaVersion: 1;
readonly generic: CompanionCooldownGenericRules;
readonly mechanics: readonly CompanionCooldownMechanicRule[];
}
export interface CooldownPolicyMobState {
readonly name?: string;
readonly serverEntry?: number | null;
readonly activeCast?: { readonly attackId: string; readonly completesAt: number } | null;
readonly abilityReadyAt?: Readonly<Record<string, number>>;
}
export const DEFAULT_COMPANION_COOLDOWN_POLICY: CompanionCooldownPolicy = Object.freeze({
schemaVersion: 1,
generic: Object.freeze({
defensiveHealthPercent: 55,
emergencyHealthPercent: 35,
healerMitigationHealthPercent: 80,
offensiveMajorCooldownSeconds: 60,
conserveOffensiveCooldownsForDurableTargets: true,
}),
mechanics: Object.freeze([]),
});
let installedPolicy = DEFAULT_COMPANION_COOLDOWN_POLICY;
function bounded(value: unknown, fallback: number, minimum: number, maximum: number): number {
const number = Number(value);
return Number.isFinite(number) ? Math.max(minimum, Math.min(maximum, number)) : fallback;
}
export function normalizeCompanionCooldownPolicy(value: unknown): CompanionCooldownPolicy {
const input = value && typeof value === "object" ? value as Partial<CompanionCooldownPolicy> : {};
const generic: Partial<CompanionCooldownGenericRules> = input.generic && typeof input.generic === "object"
? input.generic
: {};
const defaults = DEFAULT_COMPANION_COOLDOWN_POLICY.generic;
const mechanics = Array.isArray(input.mechanics) ? input.mechanics.flatMap((candidate, index) => {
if (!candidate || typeof candidate !== "object") return [];
const rule = candidate as Partial<CompanionCooldownMechanicRule>;
const attackId = typeof rule.attackId === "string" ? rule.attackId.trim() : "";
if (!attackId) return [];
return [{
id: typeof rule.id === "string" && rule.id.trim() ? rule.id.trim() : `mechanic-${index + 1}`,
enabled: rule.enabled !== false,
bossKey: typeof rule.bossKey === "string" ? rule.bossKey : "",
bossName: typeof rule.bossName === "string" ? rule.bossName : "",
bossServerEntry: rule.bossServerEntry !== null && rule.bossServerEntry !== undefined
&& Number.isFinite(Number(rule.bossServerEntry))
? Math.trunc(Number(rule.bossServerEntry))
: null,
attackId,
attackName: typeof rule.attackName === "string" ? rule.attackName : attackId,
scope: rule.scope === "party" ? "party" as const : "tank" as const,
leadTimeMs: bounded(rule.leadTimeMs, 2_500, 0, 15_000),
minimumCooldownSeconds: bounded(rule.minimumCooldownSeconds, 20, 0, 600),
}];
}) : [];
return Object.freeze({
schemaVersion: 1,
generic: Object.freeze({
defensiveHealthPercent: bounded(generic.defensiveHealthPercent, defaults.defensiveHealthPercent, 1, 100),
emergencyHealthPercent: bounded(generic.emergencyHealthPercent, defaults.emergencyHealthPercent, 1, 100),
healerMitigationHealthPercent: bounded(generic.healerMitigationHealthPercent, defaults.healerMitigationHealthPercent, 1, 100),
offensiveMajorCooldownSeconds: bounded(generic.offensiveMajorCooldownSeconds, defaults.offensiveMajorCooldownSeconds, 0, 600),
conserveOffensiveCooldownsForDurableTargets: generic.conserveOffensiveCooldownsForDurableTargets !== false,
}),
mechanics: Object.freeze(mechanics),
});
}
export function installCompanionCooldownPolicy(value: unknown): CompanionCooldownPolicy {
installedPolicy = normalizeCompanionCooldownPolicy(value);
return installedPolicy;
}
export function currentCompanionCooldownPolicy(): CompanionCooldownPolicy {
return installedPolicy;
}
export function imminentCooldownMechanic(
mob: CooldownPolicyMobState | null,
role: PartyRole,
now: number,
policy = installedPolicy,
): CompanionCooldownMechanicRule | null {
if (!mob) return null;
return policy.mechanics.find((rule) => {
if (!rule.enabled || (rule.scope === "tank" && role !== "tank")) return false;
if (rule.bossServerEntry !== null && mob.serverEntry !== rule.bossServerEntry) return false;
if (rule.bossServerEntry === null && rule.bossName && mob.name !== rule.bossName) return false;
if (mob.activeCast?.attackId === rule.attackId) {
const remaining = mob.activeCast.completesAt - now;
return remaining >= 0 && remaining <= rule.leadTimeMs;
}
const readyAt = mob.abilityReadyAt?.[rule.attackId];
return readyAt !== undefined && readyAt >= now && readyAt - now <= rule.leadTimeMs;
}) ?? null;
}
src/game/companionCooldownPolicyStore.ts
+96
View File
@@ -0,0 +1,96 @@
import { create } from "zustand";
import type { PlayerSession } from "../app/types";
import { requestOnlineJson } from "../app/onlineAccountClient";
import {
DEFAULT_COMPANION_COOLDOWN_POLICY,
installCompanionCooldownPolicy,
normalizeCompanionCooldownPolicy,
type CompanionCooldownPolicy,
} from "./companionCooldownPolicy";
interface PublishedCompanionCooldownPolicy {
readonly revision: number;
readonly updatedAt: number | null;
readonly updatedBy?: string | null;
readonly config: CompanionCooldownPolicy;
}
interface CompanionCooldownPolicyState extends PublishedCompanionCooldownPolicy {
readonly draft: CompanionCooldownPolicy;
readonly loading: boolean;
readonly saving: boolean;
readonly dirty: boolean;
readonly error: string | null;
refresh: (session?: PlayerSession | null) => Promise<void>;
replaceDraft: (draft: CompanionCooldownPolicy) => void;
resetDraft: () => void;
publish: (session: PlayerSession | null) => Promise<boolean>;
}
const CACHE_KEY = "healer-man.companion-cooldown-policy.v1";
function cached(): PublishedCompanionCooldownPolicy {
try {
const value = JSON.parse(window.localStorage.getItem(CACHE_KEY) ?? "null") as Partial<PublishedCompanionCooldownPolicy> | null;
if (!value || !Number.isInteger(value.revision)) throw new Error("missing");
return { revision: value.revision!, updatedAt: value.updatedAt ?? null, config: normalizeCompanionCooldownPolicy(value.config) };
} catch {
return { revision: 0, updatedAt: null, config: DEFAULT_COMPANION_COOLDOWN_POLICY };
}
}
function cache(payload: PublishedCompanionCooldownPolicy): void {
try { window.localStorage.setItem(CACHE_KEY, JSON.stringify(payload)); } catch { /* optional cache */ }
}
const initial = cached();
installCompanionCooldownPolicy(initial.config);
export const useCompanionCooldownPolicyStore = create<CompanionCooldownPolicyState>((set, get) => ({
...initial,
draft: initial.config,
loading: false,
saving: false,
dirty: false,
error: null,
refresh: async (session = null) => {
set({ loading: true, error: null });
try {
const gm = Boolean(session?.accessToken && session.roles?.includes("gm"));
const payload = await requestOnlineJson<PublishedCompanionCooldownPolicy>(
gm ? "/api/gm/companion-cooldown-policy" : "/api/companion-cooldown-policy",
{},
gm ? session?.accessToken : undefined,
);
const normalized = { ...payload, config: normalizeCompanionCooldownPolicy(payload.config) };
cache(normalized);
installCompanionCooldownPolicy(normalized.config);
set({ ...normalized, draft: normalized.config, loading: false, dirty: false });
} catch (error) {
set({ loading: false, error: error instanceof Error ? error.message : "Could not load companion cooldown policy." });
}
},
replaceDraft: (draft) => set({ draft: normalizeCompanionCooldownPolicy(draft), dirty: true, error: null }),
resetDraft: () => set((state) => ({ draft: state.config, dirty: false, error: null })),
publish: async (session) => {
if (!session?.accessToken || !session.roles?.includes("gm")) {
set({ error: "Game Master access is required." });
return false;
}
set({ saving: true, error: null });
try {
const payload = await requestOnlineJson<PublishedCompanionCooldownPolicy>("/api/gm/companion-cooldown-policy", {
method: "PUT",
body: JSON.stringify({ expectedRevision: get().revision, config: get().draft }),
}, session.accessToken);
const normalized = { ...payload, config: normalizeCompanionCooldownPolicy(payload.config) };
cache(normalized);
installCompanionCooldownPolicy(normalized.config);
set({ ...normalized, draft: normalized.config, saving: false, dirty: false });
return true;
} catch (error) {
set({ saving: false, error: error instanceof Error ? error.message : "Could not publish companion cooldown policy." });
return false;
}
},
}));
src/game/companionPartyPreferences.ts
+20
View File
@@ -0,0 +1,20 @@
import { create } from "zustand";
const STORAGE_KEY = "healer-man.include-beta-companion-specs.v1";
function loadPreference(): boolean {
try { return window.localStorage.getItem(STORAGE_KEY) === "true"; } catch { return false; }
}
interface CompanionPartyPreferencesState {
includeBetaSpecs: boolean;
setIncludeBetaSpecs: (include: boolean) => void;
}
export const useCompanionPartyPreferences = create<CompanionPartyPreferencesState>((set) => ({
includeBetaSpecs: loadPreference(),
setIncludeBetaSpecs: (includeBetaSpecs) => {
try { window.localStorage.setItem(STORAGE_KEY, String(includeBetaSpecs)); } catch { /* optional preference */ }
set({ includeBetaSpecs });
},
}));
src/game/companionSpecReadiness.test.ts
+43
View File
@@ -0,0 +1,43 @@
import { describe, expect, it } from "vitest";
import {
DEFAULT_COMPANION_SPEC_READINESS_POLICY,
READY_COMPANION_SPECIALIZATION_IDS,
WOW_COMPANION_SPECIALIZATIONS,
normalizeCompanionSpecReadinessPolicy,
readinessStatusFor,
} from "./companionSpecReadiness";
describe("companion specialization readiness", () => {
it("ships exactly five Ready profiles and 26 Needs Testing profiles", () => {
expect(WOW_COMPANION_SPECIALIZATIONS).toHaveLength(31);
expect(new Set(WOW_COMPANION_SPECIALIZATIONS.filter((definition) => (
readinessStatusFor(definition.id) === "ready"
)).map((definition) => definition.id))).toEqual(new Set(READY_COMPANION_SPECIALIZATION_IDS));
expect(Object.values(DEFAULT_COMPANION_SPEC_READINESS_POLICY.statuses).filter((status) => status === "needs-testing")).toHaveLength(26);
});
it("fills newly introduced or missing entries as Needs Testing", () => {
const normalized = normalizeCompanionSpecReadinessPolicy({
schemaVersion: 1,
statuses: Object.fromEntries(READY_COMPANION_SPECIALIZATION_IDS.map((id) => [id, "ready"])),
});
expect(normalized.statuses["warrior:arms"]).toBe("needs-testing");
expect(readinessStatusFor("future:new-spec", normalized)).toBe("needs-testing");
});
it("rejects policies without certified role coverage", () => {
expect(() => normalizeCompanionSpecReadinessPolicy({
schemaVersion: 1,
statuses: { "warrior:protection": "ready" },
})).toThrow("healer specialization");
expect(() => normalizeCompanionSpecReadinessPolicy({
schemaVersion: 1,
statuses: {
"warrior:protection": "ready",
"priest:discipline": "ready",
"hunter:marksmanship": "ready",
"mage:fire": "ready",
},
})).toThrow("three distinct damage");
});
});
src/game/companionSpecReadiness.ts
+130
View File
@@ -0,0 +1,130 @@
import { BASE_CLASS_IDS } from "../app/characterCatalog";
import type { PartyRole } from "./partyRoles";
import {
SPECIALIZATION_DEFINITIONS,
type SpecializationDefinition,
} from "./specializationCatalog";
export type CompanionSpecReadinessStatus = "ready" | "beta" | "needs-testing";
export interface CompanionSpecReadinessPolicy {
readonly schemaVersion: 1;
readonly statuses: Readonly<Record<string, CompanionSpecReadinessStatus>>;
}
export interface PublishedCompanionSpecReadinessPolicy {
readonly revision: number;
readonly updatedAt: number | null;
readonly updatedBy?: string | null;
readonly config: CompanionSpecReadinessPolicy;
}
export const READY_COMPANION_SPECIALIZATION_IDS = Object.freeze([
"warrior:protection",
"priest:discipline",
"hunter:marksmanship",
"mage:fire",
"rogue:assassination",
] as const);
const CLASSIC_CLASS_IDS = new Set<string>(BASE_CLASS_IDS);
const READY_IDS = new Set<string>(READY_COMPANION_SPECIALIZATION_IDS);
const VALID_STATUSES = new Set<CompanionSpecReadinessStatus>(["ready", "beta", "needs-testing"]);
export const WOW_COMPANION_SPECIALIZATIONS: readonly SpecializationDefinition[] = Object.freeze(
SPECIALIZATION_DEFINITIONS.filter((definition) => CLASSIC_CLASS_IDS.has(definition.classId)),
);
const WOW_SPECIALIZATION_IDS = new Set(WOW_COMPANION_SPECIALIZATIONS.map((definition) => definition.id));
export const DEFAULT_COMPANION_SPEC_READINESS_POLICY: CompanionSpecReadinessPolicy = Object.freeze({
schemaVersion: 1,
statuses: Object.freeze(Object.fromEntries(
WOW_COMPANION_SPECIALIZATIONS.map((definition) => [
definition.id,
(READY_IDS.has(definition.id) ? "ready" : "needs-testing") as CompanionSpecReadinessStatus,
]),
)),
});
function invalid(message: string): Error {
return new Error(message);
}
export function readinessStatusFor(
specializationId: string | null | undefined,
policy: CompanionSpecReadinessPolicy = DEFAULT_COMPANION_SPEC_READINESS_POLICY,
): CompanionSpecReadinessStatus {
if (!specializationId || !WOW_SPECIALIZATION_IDS.has(specializationId)) return "needs-testing";
return policy.statuses[specializationId] ?? "needs-testing";
}
export function validateReadyRoleCoverage(policy: CompanionSpecReadinessPolicy): void {
const readyByRole = (role: PartyRole) => WOW_COMPANION_SPECIALIZATIONS.filter((definition) => (
definition.role === role && readinessStatusFor(definition.id, policy) === "ready"
));
if (readyByRole("tank").length < 1) throw invalid("At least one tank specialization must be Ready.");
if (readyByRole("healer").length < 1) throw invalid("At least one healer specialization must be Ready.");
if (new Set(readyByRole("damage").map((definition) => definition.id)).size < 3) {
throw invalid("At least three distinct damage specializations must be Ready.");
}
}
export function normalizeCompanionSpecReadinessPolicy(value: unknown): CompanionSpecReadinessPolicy {
if (!value || typeof value !== "object" || Array.isArray(value)) {
throw invalid("Companion readiness policy must be an object.");
}
const input = value as Partial<CompanionSpecReadinessPolicy>;
if (input.schemaVersion !== 1) throw invalid("Companion readiness policy schemaVersion must be 1.");
if (!input.statuses || typeof input.statuses !== "object" || Array.isArray(input.statuses)) {
throw invalid("Companion readiness statuses are required.");
}
for (const [specializationId, status] of Object.entries(input.statuses)) {
if (!WOW_SPECIALIZATION_IDS.has(specializationId)) {
throw invalid(`Unknown WoW specialization: ${specializationId}.`);
}
if (!VALID_STATUSES.has(status as CompanionSpecReadinessStatus)) {
throw invalid(`Invalid readiness status for ${specializationId}.`);
}
}
const policy: CompanionSpecReadinessPolicy = Object.freeze({
schemaVersion: 1,
statuses: Object.freeze(Object.fromEntries(WOW_COMPANION_SPECIALIZATIONS.map((definition) => [
definition.id,
(input.statuses as Readonly<Record<string, CompanionSpecReadinessStatus>>)[definition.id] ?? "needs-testing",
]))),
});
validateReadyRoleCoverage(policy);
return policy;
}
export function companionSpecializationsForPolicy(
policy: CompanionSpecReadinessPolicy,
includeBetaSpecs: boolean,
role?: PartyRole,
): readonly SpecializationDefinition[] {
return WOW_COMPANION_SPECIALIZATIONS.filter((definition) => {
if (role && definition.role !== role) return false;
const status = readinessStatusFor(definition.id, policy);
return status === "ready" || (includeBetaSpecs && status === "beta");
});
}
export function cloneDefaultCompanionSpecReadinessPolicy(): CompanionSpecReadinessPolicy {
return JSON.parse(JSON.stringify(DEFAULT_COMPANION_SPEC_READINESS_POLICY)) as CompanionSpecReadinessPolicy;
}
export function companionSpecReadinessFromCache(value: string | null): PublishedCompanionSpecReadinessPolicy {
try {
const parsed = JSON.parse(value ?? "null") as Partial<PublishedCompanionSpecReadinessPolicy> | null;
if (!parsed || !Number.isInteger(parsed.revision)) throw new Error("missing cache");
return {
revision: parsed.revision!,
updatedAt: parsed.updatedAt ?? null,
updatedBy: parsed.updatedBy ?? null,
config: normalizeCompanionSpecReadinessPolicy(parsed.config),
};
} catch {
return { revision: 0, updatedAt: null, updatedBy: null, config: DEFAULT_COMPANION_SPEC_READINESS_POLICY };
}
}
src/game/companionSpecReadinessStore.test.ts
+33
View File
@@ -0,0 +1,33 @@
import { describe, expect, it } from "vitest";
import { companionSpecReadinessFromCache } from "./companionSpecReadiness";
describe("companion readiness offline cache", () => {
it("falls back to shipped defaults when the cached policy is corrupt", () => {
const cached = companionSpecReadinessFromCache("{not-json");
expect(cached.revision).toBe(0);
expect(cached.config.statuses["warrior:protection"]).toBe("ready");
expect(Object.values(cached.config.statuses).filter((status) => status === "ready")).toHaveLength(5);
});
it("retains the last valid published policy for offline play", () => {
const cached = companionSpecReadinessFromCache(JSON.stringify({
revision: 4,
updatedAt: 123,
updatedBy: "Phenom",
config: {
schemaVersion: 1,
statuses: {
"warrior:protection": "ready",
"priest:discipline": "ready",
"hunter:marksmanship": "ready",
"mage:fire": "ready",
"rogue:assassination": "ready",
"paladin:retribution": "beta",
},
},
}));
expect(cached.revision).toBe(4);
expect(cached.config.statuses["paladin:retribution"]).toBe("beta");
expect(cached.config.statuses["druid:balance"]).toBe("needs-testing");
});
});
src/game/companionSpecReadinessStore.ts
+104
View File
@@ -0,0 +1,104 @@
import { create } from "zustand";
import type { PlayerSession } from "../app/types";
import { requestOnlineJson } from "../app/onlineAccountClient";
import {
companionSpecReadinessFromCache,
normalizeCompanionSpecReadinessPolicy,
type CompanionSpecReadinessPolicy,
type PublishedCompanionSpecReadinessPolicy,
} from "./companionSpecReadiness";
interface CompanionSpecReadinessState extends PublishedCompanionSpecReadinessPolicy {
readonly draft: CompanionSpecReadinessPolicy;
readonly loading: boolean;
readonly saving: boolean;
readonly dirty: boolean;
readonly error: string | null;
refresh: (session?: PlayerSession | null) => Promise<void>;
setStatus: (specializationId: string, status: "ready" | "beta" | "needs-testing") => void;
resetDraft: () => void;
publish: (session?: PlayerSession | null) => Promise<boolean>;
}
const CACHE_KEY = "healer-man.companion-spec-readiness.v1";
const LOCAL_GUI = import.meta.env.VITE_LOCAL_BALANCE_LAB_GUI === "true";
const LOCAL_PATH = "/api/local/balance-lab/companion-spec-readiness";
function cached(): PublishedCompanionSpecReadinessPolicy {
return companionSpecReadinessFromCache(typeof window === "undefined" ? null : window.localStorage.getItem(CACHE_KEY));
}
function cache(payload: PublishedCompanionSpecReadinessPolicy): void {
try { window.localStorage.setItem(CACHE_KEY, JSON.stringify(payload)); } catch { /* optional offline cache */ }
}
async function request<T>(pathname: string, init: RequestInit, session?: PlayerSession | null): Promise<T> {
if (!LOCAL_GUI) return requestOnlineJson<T>(pathname, init, session?.accessToken);
const headers = new Headers(init.headers);
headers.set("Accept", "application/json");
if (init.body !== undefined) headers.set("Content-Type", "application/json");
const response = await fetch(LOCAL_PATH, { ...init, headers });
const body = await response.json().catch(() => ({})) as T & { error?: string };
if (!response.ok) throw new Error(body.error ?? `Local readiness request failed (${response.status}).`);
return body;
}
const initial = cached();
export const useCompanionSpecReadinessStore = create<CompanionSpecReadinessState>((set, get) => ({
...initial,
draft: initial.config,
loading: false,
saving: false,
dirty: false,
error: null,
refresh: async (session = null) => {
set({ loading: true, error: null });
try {
const gm = Boolean(session?.accessToken && session.roles?.includes("gm"));
const pathname = gm ? "/api/gm/companion-spec-readiness" : "/api/companion-spec-readiness";
const payload = await request<PublishedCompanionSpecReadinessPolicy>(pathname, {}, session);
const normalized = { ...payload, config: normalizeCompanionSpecReadinessPolicy(payload.config) };
cache(normalized);
set({ ...normalized, draft: normalized.config, loading: false, dirty: false });
} catch (error) {
set({ loading: false, error: error instanceof Error ? error.message : "Could not load companion readiness." });
}
},
setStatus: (specializationId, status) => set((state) => ({
draft: {
schemaVersion: 1,
statuses: { ...state.draft.statuses, [specializationId]: status },
},
dirty: true,
error: null,
})),
resetDraft: () => set((state) => ({ draft: state.config, dirty: false, error: null })),
publish: async (session = null) => {
if (!LOCAL_GUI && (!session?.accessToken || !session.roles?.includes("gm"))) {
set({ error: "Game Master access is required." });
return false;
}
set({ saving: true, error: null });
try {
const draft = normalizeCompanionSpecReadinessPolicy(get().draft);
const payload = await request<PublishedCompanionSpecReadinessPolicy>(
"/api/gm/companion-spec-readiness",
{ method: "PUT", body: JSON.stringify({ expectedRevision: get().revision, config: draft }) },
session,
);
const normalized = { ...payload, config: normalizeCompanionSpecReadinessPolicy(payload.config) };
cache(normalized);
set({ ...normalized, draft: normalized.config, saving: false, dirty: false });
return true;
} catch (error) {
set({ saving: false, error: error instanceof Error ? error.message : "Could not publish companion readiness." });
return false;
}
},
}));
export function currentCompanionSpecReadinessPolicy(): PublishedCompanionSpecReadinessPolicy {
const state = useCompanionSpecReadinessStore.getState();
return { revision: state.revision, updatedAt: state.updatedAt, updatedBy: state.updatedBy, config: state.config };
}
src/game/dungeonBossScaling.test.ts
+3 -1
View File
@@ -114,7 +114,9 @@ describe("dungeon boss durability and difficulty", () => {
const ordinary = fight(stockadesBoss.id, level, 1, seed, false, false, "wow", stockades);
const last = fight(finalDungeonBoss(stockades)!.id, level, 1, seed, false, false, "wow", stockades);
samples.push({ level, seed, boss: ordinary, final: last });
expect(ordinary.seconds ?? 240, JSON.stringify({ level, seed, ordinary, last })).toBeGreaterThanOrEqual(25);
// Combat advances in 100 ms ticks and the first action cadence varies by
// generated party. Keep a half-second tolerance around the 25s design floor.
expect(ordinary.seconds ?? 240, JSON.stringify({ level, seed, ordinary, last })).toBeGreaterThanOrEqual(24.5);
expect(last.seconds ?? 240, JSON.stringify({ level, seed, ordinary, last })).toBeGreaterThanOrEqual(45);
}
}, 30000);
src/game/dungeonBossScaling.ts
+24 -3
View File
@@ -14,6 +14,7 @@ const WOW_BOSS_HEALTH_FLOOR: readonly (readonly [level: number, health: number])
[9, 7_000],
[21, 11_000],
[41, 23_000],
[51, 39_000],
[80, 180_000],
];
const WOW_BOSS_TEST_HEALTH_FLOOR: readonly (readonly [level: number, health: number])[] = [
@@ -22,7 +23,18 @@ const WOW_BOSS_TEST_HEALTH_FLOOR: readonly (readonly [level: number, health: num
[9, 7_000],
[21, 11_000],
[41, 23_000],
[80, 180_000],
// Isolated test fights are normalized to the certified companion curve.
// Native expansion-2 template health grows much faster than the party's
// observed level-80 DPS and previously pushed the average fight above 170s.
[80, 44_000],
];
const WOW_BOSS_TEST_DAMAGE_SCALE: readonly (readonly [level: number, scale: number])[] = [
[1, 1],
[50, 1],
// Level-80 source creature weapon damage grows faster than the certified
// healer's throughput. This keeps test-room pressure sustained without
// turning roughly a third of catalog coverage runs into early wipes.
[80, 0.75],
];
const BOSS_TEST_HEALTH_FLOOR_MULTIPLIER = 0.6;
const FINAL_BOSS_HEALTH_FLOOR_MULTIPLIER = 1.9;
@@ -73,9 +85,18 @@ export function dungeonEnemyScaling(dungeon: DungeonDefinition, entity: Populati
// finale. A reduced floor still prevents high-level source creatures with
// tiny extrapolated level-two health from dying before mechanics can run.
const testingBossFloor = partyHealthFloor * BOSS_TEST_HEALTH_FLOOR_MULTIPLIER;
const testingBossCeiling = characterSource === "wow"
? partyHealthFloor * 0.9 * Math.max(1, Math.min(1.5, authoredHealth))
: Number.POSITIVE_INFINITY;
const scaledHealth = boss
? Math.max(originalHealth, testing ? testingBossFloor : bossFloor)
? testing
? Math.max(Math.min(originalHealth, testingBossCeiling), testingBossFloor)
: Math.max(originalHealth, bossFloor)
: originalHealth;
const testingDamageScale = testing && characterSource === "wow"
? interpolatedFloor(level, WOW_BOSS_TEST_DAMAGE_SCALE)
: 1;
return { level, maxHealth: scaledHealth * multipliers.health,
healthMultiplier: authoredHealth * multipliers.health, damageMultiplier: authoredDamage * multipliers.damage };
healthMultiplier: authoredHealth * multipliers.health,
damageMultiplier: authoredDamage * multipliers.damage * testingDamageScale };
}
src/game/generated/partyTalentRuntimePlans.json
+15989 -2267
View File
File diff suppressed because it is too large. Load diff
src/game/heirloomEquipment.test.ts
+2 -2
View File
@@ -58,10 +58,10 @@ function compatibleItems(classId: ClassId, level: number): InventoryItem[] {
}
describe("specialization-aware heirlooms", () => {
it("caps player heirlooms at 79 and party heirlooms at 80", () => {
it("caps player and party heirlooms at 79", () => {
const profile = SPECIALIZATION_DEFINITIONS.find((definition) => definition.id === "priest:holy")!;
expect(new Set(resolvedEquipmentItems({}, [], context(profile, 80)).map((item) => item.itemLevel))).toEqual(new Set([79]));
expect(new Set(resolvedEquipmentItems({}, [], context(profile, 80, "party")).map((item) => item.itemLevel))).toEqual(new Set([80]));
expect(new Set(resolvedEquipmentItems({}, [], context(profile, 80, "party")).map((item) => item.itemLevel))).toEqual(new Set([79]));
expect(resolvedAverageItemLevel({}, [], context(profile, 40))).toBe(40);
});
src/game/heirloomEquipment.ts
+1 -1
View File
@@ -31,7 +31,7 @@ import {
} from "./specializationCatalog";
export const PLAYER_HEIRLOOM_LEVEL_CAP = 79;
export const PARTY_HEIRLOOM_LEVEL_CAP = 80;
export const PARTY_HEIRLOOM_LEVEL_CAP = 79;
export const FIRST_ENDGAME_ITEM_LEVEL = 85;
export type HeirloomOwnerKind = "player" | "party";
src/game/partyAbilityAi.test.ts
+19
View File
@@ -112,6 +112,25 @@ describe("catalog-driven party rotations", () => {
.toBe("Mortal Strike");
});
it("uses Bloodrage to break a Protection Warrior zero-Rage state", () => {
const talents = runtimePartyTalentRanksForLevel("warrior", "Protection", 80);
const member = {
...memberFor("warrior", "tank"),
specialization: "Protection",
specializationId: "warrior:protection" as const,
talentRanks: talents,
resource: 0,
resourcePools: { rage: 0 },
};
const stance = abilitiesForClass("warrior").find((ability) => ability.name === "Defensive Stance")!;
const target = { ...useCombatStore.getState().mobs.caster, activeCast: null };
expect(choosePartyAbility(member, {
now: 2_000,
target,
maintainedAbilityIds: new Set([stance.id]),
})?.name).toBe("Bloodrage");
});
it("opens Arcane combat with the learned Arcane Barrage signature", () => {
const member = {
...memberFor("mage", "damage"),
src/game/partyAbilityAi.ts
+4
View File
@@ -17,6 +17,7 @@ import { equipmentAdjustedCombatAmount, type MobCombatState } from "./combatStor
import type { PartyMember } from "./partyStore";
import { baseResourcesFor } from "./wotlkStats";
import { companionResourceMaximum } from "./combatActorAuthority";
import { currentCompanionCooldownPolicy, type CompanionCooldownMechanicRule } from "./companionCooldownPolicy";
export interface PartyAbilityContext {
readonly now: number;
@@ -35,6 +36,7 @@ export interface PartyAbilityContext {
readonly activeSummonAbilityIds?: ReadonlySet<string>;
readonly hasActivePet?: boolean;
readonly canUseAbility?: (ability: AbilityDefinition) => boolean;
readonly incomingDefensiveMechanic?: CompanionCooldownMechanicRule | null;
}
function currentResource(member: PartyMember, type: ResourceType): number {
@@ -155,6 +157,8 @@ export function choosePartyRotationDecision(
activeSummonAbilityIds: context.activeSummonAbilityIds,
hasActivePet: context.hasActivePet,
canUseAbility: context.canUseAbility,
cooldownPolicy: currentCompanionCooldownPolicy(),
incomingDefensiveMechanic: context.incomingDefensiveMechanic,
});
return decision && shouldReserveForHigherPriority(member, learned, decision, context.now)
? null
src/game/partyDamageAudit.test.ts
+4 -4
View File
@@ -20,12 +20,12 @@ function partyTemplates(level: number): PartyMember[] {
}
describe("NPC sustained damage audit", () => {
it("lets Garrick swing immediately with no Rage, and keeps swinging during the GCD", () => {
it("lets the Ready Protection Warrior swing immediately with no Rage, and keeps swinging during the GCD", () => {
clearMobRuntimeRegistry();
clearPartyRuntimeRegistry();
resetPartyRuntimeClock();
useCombatStore.getState().initializeCharacter({ classId: "priest", level: 3 });
const garrick = partyTemplates(3).find((member) => member.name === "Garrick")!;
const garrick = partyTemplates(3).find((member) => member.specializationId === "warrior:protection")!;
usePartyStore.getState().initializeParty("short-pull", 3, useCombatStore.getState().health);
usePartyStore.setState({ members: [{ ...garrick, globalCooldownEndsAt: 10_000 }] });
useCombatStore.getState().synchronizeActors();
@@ -55,7 +55,7 @@ describe("NPC sustained damage audit", () => {
clearPartyRuntimeRegistry();
resetPartyRuntimeClock();
useCombatStore.getState().initializeCharacter({ classId: "priest", level: 5 });
const garrick = partyTemplates(5).find((member) => member.name === "Garrick")!;
const garrick = partyTemplates(5).find((member) => member.specializationId === "warrior:protection")!;
usePartyStore.getState().initializeParty("area-pull", 5, useCombatStore.getState().health);
usePartyStore.setState({ members: [{ ...garrick, resource: 100, resourcePools: { rage: 100 },
cooldowns: Object.fromEntries(abilitiesForClass("warrior").filter((ability) => ability.id !== "warrior-thunder-clap")
@@ -224,7 +224,7 @@ describe("NPC sustained damage audit", () => {
for (const level of [1, 3, 5, 20, 80]) {
it(`executes damaging abilities for every party template at level ${level}`, () => {
const templates = partyTemplates(level);
expect(templates).toHaveLength(26);
expect(templates).toHaveLength(5);
for (const member of templates) {
clearMobRuntimeRegistry();
clearPartyRuntimeRegistry();
src/game/partyRuntime.ts
+20
View File
@@ -57,6 +57,8 @@ import {
commitPartyAbilityUse,
partyAbilityAmount,
} from "./partyAbilityAi";
import { emitRotationDecision } from "./rotationTelemetry";
import { imminentCooldownMechanic } from "./companionCooldownPolicy";
import { normalizeActorResourcePool } from "./combatActors";
import { enemyControlPreventsActions } from "./enemyAttacks";
import { advanceCombatResourcePool } from "./combatResources";
@@ -1568,7 +1570,14 @@ export function advanceDungeonPartyCombat(now = Date.now()): void {
target: targetMob ?? null,
targetIsLoose: member.role === "tank" && targetMob?.targetActorId !== member.id,
hasDangerousThreat: member.role !== "tank" && targetMob?.targetActorId === member.id,
incomingDefensiveMechanic: imminentCooldownMechanic(targetMob ?? null, member.role, now),
hostileCount: Object.values(currentCombat.mobs).filter((mob) => mob.engaged && !mob.dead).length,
friendlyTargets: nextMembers.filter((candidate) => candidate.health > 0).map((candidate) => ({
id: candidate.id,
health: candidate.health,
maxHealth: candidate.maxHealth,
role: candidate.role,
})),
maintainedAbilityIds: new Set([
...currentCombat.effects.filter((effect) => effect.sourceActorId === member.id && effect.remainingTicks > 0)
.map((effect) => effect.sourceAbilityId),
@@ -1632,6 +1641,17 @@ export function advanceDungeonPartyCombat(now = Date.now()): void {
nextMembers[index] = { ...runtimeMember, status: desiredStatus, nextActionAt: now + 250 };
continue;
}
if (selectedDecision) {
emitRotationDecision({
occurredAt: now,
actorId: member.id,
abilityId: selectedAbility.id,
targetId: abilityTargetId,
profileId: selectedDecision.profileId,
ruleId: selectedDecision.ruleId,
reason: selectedDecision.reason,
});
}
if (selectedAbility.castTimeMs > 0) {
nextMembers[index] = {
...committed,
src/game/partyStore.test.ts
+48
View File
@@ -16,6 +16,7 @@ import {
import { spentTalentPoints, talentPointsForLevel, talentTreeById } from "./talentCatalog";
import type { InventoryItem } from "./lootTypes";
import { EMPTY_ITEM_STATS } from "./itemStats";
import { DEFAULT_COMPANION_SPEC_READINESS_POLICY } from "./companionSpecReadiness";
describe("dungeon party composition", () => {
beforeEach(() => usePartyStore.setState({
@@ -46,6 +47,53 @@ describe("dungeon party composition", () => {
}
});
it("uses only the five Ready Playerbots identities by default", () => {
const party = createDungeonParty("ready-only", 80, "damage");
expect(party.map((member) => member.name)).toEqual(expect.arrayContaining(["Aldren", "Quorin"]));
expect(party.every((member) => ["Aldren", "Quorin", "Liora", "Xavian", "Orin"].includes(member.name))).toBe(true);
expect(new Set(party.filter((member) => member.role === "damage").map((member) => member.specializationId)).size)
.toBe(party.filter((member) => member.role === "damage").length);
});
it("adds Beta specs only when opted in and still excludes Needs Testing", () => {
const policy = {
schemaVersion: 1 as const,
statuses: {
...DEFAULT_COMPANION_SPEC_READINESS_POLICY.statuses,
"mage:arcane": "beta" as const,
},
};
const defaultNames = new Set<string>();
const betaNames = new Set<string>();
for (let seed = 0; seed < 40; seed += 1) {
for (const member of createDungeonParty(`beta-${seed}`, 80, "damage", 5, "wow", { readinessPolicy: policy })) {
defaultNames.add(member.specializationId ?? "");
}
for (const member of createDungeonParty(`beta-${seed}`, 80, "damage", 5, "wow", { readinessPolicy: policy, includeBetaSpecs: true })) {
betaNames.add(member.specializationId ?? "");
}
}
expect(defaultNames.has("mage:arcane")).toBe(false);
expect(betaNames.has("mage:arcane")).toBe(true);
expect(betaNames.has("mage:frost")).toBe(false);
});
it("avoids the player's damage specialization when two alternatives can fill the NPC seats", () => {
const party = createDungeonParty("exclude-player", 80, "damage", 5, "wow", {
excludedPlayerSpecializationId: "mage:fire",
});
expect(party.filter((member) => member.role === "damage").map((member) => member.specializationId).sort())
.toEqual(["hunter:marksmanship", "rogue:assassination"]);
});
it("keeps RoM generation unchanged when WoW readiness is restrictive", () => {
const baseline = createDungeonParty("rom-readiness", 40, "damage", 5, "rom");
const filtered = createDungeonParty("rom-readiness", 40, "damage", 5, "rom", {
readinessPolicy: DEFAULT_COMPANION_SPEC_READINESS_POLICY,
});
expect(filtered).toEqual(baseline);
});
it("fills a dedicated healer when the player chooses tank or damage", () => {
for (const playerRole of ["tank", "damage"] as const) {
for (const seed of ["role-a", "role-b", "role-c", "role-d"]) {
src/game/partyStore.ts
+81 -60
View File
@@ -26,7 +26,16 @@ import {
deriveCharacterStats,
} from "./wotlkStats";
import type { InventoryItem } from "./lootTypes";
import { runtimePartyTalentRanksForLevel } from "./partyTalentRuntime";
import {
runtimeDefaultPartyTalentProfile,
runtimePartyTalentRanksForLevel,
} from "./partyTalentRuntime";
import {
DEFAULT_COMPANION_SPEC_READINESS_POLICY,
WOW_COMPANION_SPECIALIZATIONS,
companionSpecializationsForPolicy,
type CompanionSpecReadinessPolicy,
} from "./companionSpecReadiness";
import type { RuntimeTalentRanks as TalentRanks } from "./talentRuntimeCatalog";
import type { EnemyControlMechanic } from "./enemyAttacks";
import type { ContentCategoryId } from "../app/contentCategories";
@@ -62,6 +71,7 @@ export interface PartyMember {
readonly specialization: string;
readonly specializationId: string | null;
readonly talentTreeId: string;
readonly talentProfileId: string | null;
readonly talentRanks: TalentRanks;
readonly role: PartyRole;
readonly level: number;
@@ -94,6 +104,7 @@ interface PartyTemplate {
readonly classId: ClassId;
readonly specialization: string;
readonly talentTreeId: string;
readonly talentProfileId?: string | null;
}
export interface ConfiguredPartyMemberSeed {
@@ -103,45 +114,43 @@ export interface ConfiguredPartyMemberSeed {
readonly specialization: string;
readonly specializationId?: string | null;
readonly talentTreeId?: string;
readonly talentProfileId?: string | null;
readonly talentRanks?: TalentRanks;
readonly role: PartyRole;
}
const TANK_TEMPLATES: readonly PartyTemplate[] = Object.freeze([
{ name: "Garrick", classId: "warrior", specialization: "Protection", talentTreeId: "warrior-protection" },
{ name: "Morvane", classId: "death-knight", specialization: "Blood", talentTreeId: "death-knight-blood" },
{ name: "Seraphin", classId: "paladin", specialization: "Protection", talentTreeId: "paladin-protection" },
]);
export interface CompanionPartyGenerationOptions {
readonly readinessPolicy?: CompanionSpecReadinessPolicy;
readonly readinessPolicyRevision?: number;
readonly includeBetaSpecs?: boolean;
readonly excludedPlayerSpecializationId?: string | null;
}
const HEALER_TEMPLATES: readonly PartyTemplate[] = Object.freeze([
{ name: "Elowen", classId: "priest", specialization: "Holy", talentTreeId: "priest-holy" },
{ name: "Lucian", classId: "paladin", specialization: "Holy", talentTreeId: "paladin-holy" },
{ name: "Nym", classId: "druid", specialization: "Restoration", talentTreeId: "druid-restoration" },
{ name: "Tala", classId: "shaman", specialization: "Restoration", talentTreeId: "shaman-restoration" },
]);
function companionTemplateFor(specializationId: string): PartyTemplate {
const definition = specializationsForClass(specializationId.split(":", 1)[0] as ClassId)
.find((candidate) => candidate.id === specializationId);
if (!definition) throw new Error(`Unknown companion specialization ${specializationId}.`);
const profile = runtimeDefaultPartyTalentProfile(definition.classId, definition.displayName);
return Object.freeze({
name: profile.characterName,
classId: definition.classId,
specialization: definition.displayName,
talentTreeId: `${definition.classId}-${definition.talentTree.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
talentProfileId: profile.id,
});
}
/** Every entry is a Wrath damage specialization; tank and healer specs are excluded. */
const DAMAGE_TEMPLATES: readonly PartyTemplate[] = Object.freeze([
{ name: "Brynn", classId: "warrior", specialization: "Arms", talentTreeId: "warrior-arms" },
{ name: "Kael", classId: "warrior", specialization: "Fury", talentTreeId: "warrior-fury" },
{ name: "Aurelia", classId: "paladin", specialization: "Retribution", talentTreeId: "paladin-retribution" },
{ name: "Tamsin", classId: "hunter", specialization: "Marksmanship", talentTreeId: "hunter-marksmanship" },
{ name: "Fen", classId: "hunter", specialization: "Survival", talentTreeId: "hunter-survival" },
{ name: "Vale", classId: "rogue", specialization: "Combat", talentTreeId: "rogue-combat" },
{ name: "Nyx", classId: "rogue", specialization: "Assassination", talentTreeId: "rogue-assassination" },
{ name: "Selene", classId: "priest", specialization: "Shadow", talentTreeId: "priest-shadow" },
{ name: "Varek", classId: "death-knight", specialization: "Frost", talentTreeId: "death-knight-frost" },
{ name: "Thorne", classId: "death-knight", specialization: "Unholy", talentTreeId: "death-knight-unholy" },
{ name: "Korra", classId: "shaman", specialization: "Enhancement", talentTreeId: "shaman-enhancement" },
{ name: "Orin", classId: "shaman", specialization: "Elemental", talentTreeId: "shaman-elemental" },
{ name: "Mira", classId: "mage", specialization: "Arcane", talentTreeId: "mage-arcane" },
{ name: "Ember", classId: "mage", specialization: "Fire", talentTreeId: "mage-fire" },
{ name: "Ilyra", classId: "mage", specialization: "Frost", talentTreeId: "mage-frost" },
{ name: "Malric", classId: "warlock", specialization: "Affliction", talentTreeId: "warlock-affliction" },
{ name: "Sable", classId: "warlock", specialization: "Demonology", talentTreeId: "warlock-demonology" },
{ name: "Rowan", classId: "druid", specialization: "Balance", talentTreeId: "druid-balance" },
{ name: "Ash", classId: "druid", specialization: "Feral (Cat)", talentTreeId: "druid-feral-combat" },
]);
function wowTemplates(
role: PartyRole,
options: CompanionPartyGenerationOptions,
seats: number,
): readonly PartyTemplate[] {
const policy = options.readinessPolicy ?? DEFAULT_COMPANION_SPEC_READINESS_POLICY;
const definitions = companionSpecializationsForPolicy(policy, options.includeBetaSpecs === true, role);
const withoutPlayer = definitions.filter((definition) => definition.id !== options.excludedPlayerSpecializationId);
const candidates = withoutPlayer.length >= seats ? withoutPlayer : definitions;
return candidates.map((definition) => companionTemplateFor(definition.id));
}
const ROM_TANK_TEMPLATES: readonly PartyTemplate[] = Object.freeze([
{ name: "Aldric", classId: "rom-warrior", specialization: "Primary", talentTreeId: "" },
@@ -160,22 +169,19 @@ const ROM_DAMAGE_TEMPLATES: readonly PartyTemplate[] = Object.freeze([
{ name: "Roran", classId: "rom-knight", specialization: "Primary", talentTreeId: "" },
]);
export const TANK_SPECIALIZATIONS = Object.freeze(new Set([
"warrior:Protection",
"death-knight:Blood",
"paladin:Protection",
]));
export const TANK_SPECIALIZATIONS = Object.freeze(new Set(
WOW_COMPANION_SPECIALIZATIONS.filter((definition) => definition.role === "tank")
.map((definition) => `${definition.classId}:${definition.displayName}`),
));
export function isTankSpecialization(classId: ClassId, specialization: string): boolean {
return TANK_SPECIALIZATIONS.has(`${classId}:${specialization}`);
}
export const HEALER_SPECIALIZATIONS = Object.freeze(new Set([
"priest:Holy",
"paladin:Holy",
"druid:Restoration",
"shaman:Restoration",
]));
export const HEALER_SPECIALIZATIONS = Object.freeze(new Set(
WOW_COMPANION_SPECIALIZATIONS.filter((definition) => definition.role === "healer")
.map((definition) => `${definition.classId}:${definition.displayName}`),
));
export function isHealerSpecialization(classId: ClassId, specialization: string): boolean {
return HEALER_SPECIALIZATIONS.has(`${classId}:${specialization}`);
@@ -338,9 +344,10 @@ function createMember(
specialization: template.specialization,
specializationId,
talentTreeId: template.talentTreeId,
talentProfileId: template.talentProfileId ?? null,
talentRanks: configuredTalentRanks ?? (isRomClassId(template.classId)
? Object.freeze({})
: runtimePartyTalentRanksForLevel(template.classId, template.specialization, level)),
: runtimePartyTalentRanksForLevel(template.classId, template.specialization, level, template.talentProfileId ?? undefined)),
role,
level: Math.max(1, Math.trunc(level)),
health: maxHealth,
@@ -380,6 +387,7 @@ export function createConfiguredPartyMember(
classId: configuration.classId,
specialization: configuration.specialization,
talentTreeId: configuration.talentTreeId ?? configuration.specializationId ?? "",
talentProfileId: configuration.talentProfileId ?? null,
}, configuration.role, level, index, seed, configuration.talentRanks);
return Object.freeze(withMemberAbilityResourcePools({
...member,
@@ -399,11 +407,13 @@ export function createDungeonParty(
playerRole: PartyRole = "healer",
partySize: PartySize = 5,
categoryId: ContentCategoryId = "wow",
options: CompanionPartyGenerationOptions = {},
): readonly PartyMember[] {
const random = { value: hashSeed(seed || "healer-man") };
const tankTemplates = categoryId === "rom" ? ROM_TANK_TEMPLATES : TANK_TEMPLATES;
const healerTemplates = categoryId === "rom" ? ROM_HEALER_TEMPLATES : HEALER_TEMPLATES;
const damageTemplates = categoryId === "rom" ? ROM_DAMAGE_TEMPLATES : DAMAGE_TEMPLATES;
const tankTemplates = categoryId === "rom" ? ROM_TANK_TEMPLATES : wowTemplates("tank", options, 1);
const healerTemplates = categoryId === "rom" ? ROM_HEALER_TEMPLATES : wowTemplates("healer", options, 1);
const damageSeats = playerRole === "damage" ? 2 : 3;
const damageTemplates = categoryId === "rom" ? ROM_DAMAGE_TEMPLATES : wowTemplates("damage", options, damageSeats);
const tank = tankTemplates[Math.floor(nextRandom(random) * tankTemplates.length)] ?? tankTemplates[0];
const damagePool = [...damageTemplates];
for (let index = damagePool.length - 1; index > 0; index -= 1) {
@@ -436,11 +446,12 @@ export function createSpectatorDungeonParty(
seed: string,
level: number,
categoryId: ContentCategoryId = "wow",
options: CompanionPartyGenerationOptions = {},
): readonly PartyMember[] {
const random = { value: hashSeed(seed || "healer-man-spectator") };
const tankTemplates = categoryId === "rom" ? ROM_TANK_TEMPLATES : TANK_TEMPLATES;
const healerTemplates = categoryId === "rom" ? ROM_HEALER_TEMPLATES : HEALER_TEMPLATES;
const damagePool = [...(categoryId === "rom" ? ROM_DAMAGE_TEMPLATES : DAMAGE_TEMPLATES)];
const tankTemplates = categoryId === "rom" ? ROM_TANK_TEMPLATES : wowTemplates("tank", options, 1);
const healerTemplates = categoryId === "rom" ? ROM_HEALER_TEMPLATES : wowTemplates("healer", options, 1);
const damagePool = [...(categoryId === "rom" ? ROM_DAMAGE_TEMPLATES : wowTemplates("damage", options, 3))];
for (let index = damagePool.length - 1; index > 0; index -= 1) {
const swapIndex = Math.floor(nextRandom(random) * (index + 1));
[damagePool[index], damagePool[swapIndex]] = [damagePool[swapIndex], damagePool[index]];
@@ -467,6 +478,7 @@ export interface PartyState {
playerRole: PartyRole;
partySize: PartySize;
categoryId: ContentCategoryId;
companionOptions: CompanionPartyGenerationOptions;
members: readonly PartyMember[];
command: PartyCommand;
selectedMemberId: string | null;
@@ -483,8 +495,14 @@ export interface PartyState {
playerRole?: PartyRole,
partySize?: PartySize,
categoryId?: ContentCategoryId,
companionOptions?: CompanionPartyGenerationOptions,
) => void;
initializeSpectatorParty: (
seed: string,
level: number,
categoryId?: ContentCategoryId,
companionOptions?: CompanionPartyGenerationOptions,
) => void;
initializeSpectatorParty: (seed: string, level: number, categoryId?: ContentCategoryId) => void;
resetCombat: (level: number, playerHealth: number) => void;
syncLevel: (level: number) => void;
syncEquipment: (equipment: EquipmentAssignments, inventory: readonly InventoryItem[]) => void;
@@ -532,6 +550,7 @@ export const usePartyStore = create<PartyState>((set, get) => ({
playerRole: "healer",
partySize: 5,
categoryId: "wow",
companionOptions: Object.freeze({}),
members: [],
command: "defend",
selectedMemberId: null,
@@ -542,13 +561,14 @@ export const usePartyStore = create<PartyState>((set, get) => ({
objectiveBossId: null,
memberTargetIds: {},
initializeParty: (seed, level, playerHealth, playerRole = "healer", partySize = 5, categoryId = "wow") => set({
initializeParty: (seed, level, playerHealth, playerRole = "healer", partySize = 5, categoryId = "wow", companionOptions = {}) => set({
seed,
spectatorParty: false,
playerRole,
partySize,
categoryId,
members: createDungeonParty(seed, level, playerRole, partySize, categoryId),
companionOptions,
members: createDungeonParty(seed, level, playerRole, partySize, categoryId, companionOptions),
command: "defend",
selectedMemberId: null,
selfSelected: false,
@@ -558,13 +578,14 @@ export const usePartyStore = create<PartyState>((set, get) => ({
memberTargetIds: {},
}),
initializeSpectatorParty: (seed, level, categoryId = "wow") => set({
initializeSpectatorParty: (seed, level, categoryId = "wow", companionOptions = {}) => set({
seed,
spectatorParty: true,
playerRole: "healer",
partySize: 5,
categoryId,
members: createSpectatorDungeonParty(seed, level, categoryId),
companionOptions,
members: createSpectatorDungeonParty(seed, level, categoryId, companionOptions),
command: "attack",
selectedMemberId: null,
selfSelected: false,
@@ -577,8 +598,8 @@ export const usePartyStore = create<PartyState>((set, get) => ({
resetCombat: (level, playerHealth) => set((state) => {
return {
members: state.spectatorParty
? createSpectatorDungeonParty(state.seed ?? "healer-man-spectator", level, state.categoryId)
: createDungeonParty(state.seed ?? "healer-man", level, state.playerRole, state.partySize, state.categoryId),
? createSpectatorDungeonParty(state.seed ?? "healer-man-spectator", level, state.categoryId, state.companionOptions)
: createDungeonParty(state.seed ?? "healer-man", level, state.playerRole, state.partySize, state.categoryId, state.companionOptions),
command: state.spectatorParty ? "attack" : "defend",
selectedMemberId: null,
selfSelected: false,
@@ -623,7 +644,7 @@ export const usePartyStore = create<PartyState>((set, get) => ({
resourcePools: Object.freeze({ ...member.resourcePools, [member.resourceType]: resource }),
talentRanks: isRomClassId(member.classId)
? Object.freeze({})
: runtimePartyTalentRanksForLevel(member.classId, member.specialization, safeLevel),
: runtimePartyTalentRanksForLevel(member.classId, member.specialization, safeLevel, member.talentProfileId ?? undefined),
});
}),
};
src/game/partyTalentRuntime.test.ts
+42 -3
View File
@@ -3,16 +3,55 @@ import {
PARTY_TALENT_SPECIALIZATIONS,
partyTalentRanksForLevel,
} from "./partyTalents";
import { runtimePartyTalentRanksForLevel } from "./partyTalentRuntime";
import {
runtimePartyTalentProvenanceForLevel,
runtimePartyTalentProfiles,
runtimePartyTalentRanksForLevel,
} from "./partyTalentRuntime";
describe("generated party talent runtime plans", () => {
it("match the catalog-validated authoring plans at every player level", () => {
it("keeps the prior catalog-validated authoring plans as named profiles", () => {
for (const { classId, specialization } of PARTY_TALENT_SPECIALIZATIONS) {
const executable = runtimePartyTalentProfiles(classId, specialization)
.find((profile) => profile.source === "healer-man-generated");
expect(executable).toBeDefined();
for (let level = 1; level <= 80; level += 1) {
expect(runtimePartyTalentRanksForLevel(classId, specialization, level)).toEqual(
expect(runtimePartyTalentRanksForLevel(classId, specialization, level, executable!.id)).toEqual(
partyTalentRanksForLevel(classId, specialization, level),
);
}
}
}, 15_000);
it("provides a default Playerbots profile and a distinct character for every build", () => {
const names = new Set<string>();
for (const { classId, specialization } of PARTY_TALENT_SPECIALIZATIONS) {
const profiles = runtimePartyTalentProfiles(classId, specialization);
expect(profiles).toHaveLength(2);
const playerbots = profiles.find((profile) => profile.defaultForSpecialization);
expect(playerbots?.source).toBe("azerothcore-playerbots");
expect(playerbots?.sourceVersion).toBe("531282e");
expect(playerbots?.milestones.length).toBeGreaterThan(0);
expect(playerbots?.levelPlans.length).toBe(playerbots?.milestones.length);
expect(playerbots?.levelPlans[0]?.minimumLevel).toBe(1);
expect(playerbots!.sourcePointsRetained).toBeLessThanOrEqual(playerbots!.sourcePointCount!);
expect(playerbots!.sourcePointsRetained! + playerbots!.fallbackPointCount).toBe(71);
const level79 = runtimePartyTalentProvenanceForLevel(playerbots!, 79);
const level80 = runtimePartyTalentProvenanceForLevel(playerbots!, 80);
expect(level79.sourceLevels[0]).toBeLessThanOrEqual(79);
expect(level80.sourceLevels).toEqual([80]);
expect(level79.sourcePointsRetained! + level79.fallbackPointCount).toBe(70);
expect(level80.sourcePointsRetained! + level80.fallbackPointCount).toBe(71);
for (const profile of profiles) {
expect(names.has(profile.characterName)).toBe(false);
names.add(profile.characterName);
for (const level of [1, 10, 20, 40, 60, 70, 79, 80]) {
const ranks = runtimePartyTalentRanksForLevel(classId, specialization, level, profile.id);
expect(Object.values(ranks).reduce((total, rank) => total + rank, 0))
.toBe(Math.max(0, level - 9));
}
}
}
expect(names.size).toBe(PARTY_TALENT_SPECIALIZATIONS.length * 2);
});
});
src/game/partyTalentRuntime.ts
+111 -6
View File
@@ -3,12 +3,52 @@ import generated from "./generated/partyTalentRuntimePlans.json";
type TalentRanks = Readonly<Record<string, number>>;
export interface PartyTalentRuntimeMilestone {
readonly level: number;
readonly link: string;
}
export interface PartyTalentRuntimeLevelPlan {
readonly minimumLevel: number;
readonly sourceLevels: readonly number[];
readonly sourcePointCount: number;
readonly sourcePointFlags: readonly boolean[];
readonly plan: readonly string[];
}
export interface PartyTalentRuntimeProfile {
readonly id: string;
readonly classId: ClassId;
readonly specialization: string;
readonly name: string;
readonly characterName: string;
readonly source: "azerothcore-playerbots" | "healer-man-generated";
readonly sourceVersion: string;
readonly defaultForSpecialization: boolean;
readonly playerbotsSpecName: string | null;
readonly milestones: readonly PartyTalentRuntimeMilestone[];
readonly sourcePointCount: number | null;
readonly sourcePointsRetained: number | null;
readonly fallbackPointCount: number;
readonly plan: readonly string[];
readonly levelPlans: readonly PartyTalentRuntimeLevelPlan[];
}
export interface PartyTalentRuntimeProvenance {
readonly sourcePointCount: number | null;
readonly sourcePointsRetained: number | null;
readonly fallbackPointCount: number;
readonly sourceLevels: readonly number[];
}
interface PartyTalentRuntimeSnapshot {
readonly schemaVersion: 1;
readonly plans: Readonly<Record<string, readonly string[]>>;
readonly schemaVersion: 2;
readonly playerbotsCommit: string;
readonly profiles: readonly PartyTalentRuntimeProfile[];
}
const snapshot = generated as PartyTalentRuntimeSnapshot;
const profileById = new Map(snapshot.profiles.map((profile) => [profile.id, profile]));
function planKey(classId: ClassId, specialization: string): string {
return `${classId}:${specialization}`;
@@ -17,10 +57,73 @@ function planKey(classId: ClassId, specialization: string): string {
export function runtimePartyTalentPlan(
classId: ClassId,
specialization: string,
profileId?: string,
): readonly string[] {
const plan = snapshot.plans[planKey(classId, specialization)];
if (!plan) throw new Error(`Unsupported party specialization: ${classId}:${specialization}`);
return plan;
return runtimePartyTalentProfile(classId, specialization, profileId).plan;
}
export function runtimePartyTalentProfiles(
classId: ClassId,
specialization: string,
): readonly PartyTalentRuntimeProfile[] {
const key = planKey(classId, specialization);
return snapshot.profiles.filter((profile) => planKey(profile.classId, profile.specialization) === key);
}
export function runtimePartyTalentProfile(
classId: ClassId,
specialization: string,
profileId?: string,
): PartyTalentRuntimeProfile {
const profiles = runtimePartyTalentProfiles(classId, specialization);
const profile = profileId
? profileById.get(profileId)
: profiles.find((candidate) => candidate.defaultForSpecialization);
if (!profile || profile.classId !== classId || profile.specialization !== specialization) {
throw new Error(`Unsupported party talent profile: ${classId}:${specialization}:${profileId ?? "default"}`);
}
return profile;
}
export function runtimeDefaultPartyTalentProfile(
classId: ClassId,
specialization: string,
): PartyTalentRuntimeProfile {
return runtimePartyTalentProfile(classId, specialization);
}
function levelPlanFor(
profile: PartyTalentRuntimeProfile,
level: number,
): PartyTalentRuntimeLevelPlan | null {
const safeLevel = Number.isFinite(level) ? Math.max(1, Math.min(80, Math.trunc(level))) : 1;
return [...profile.levelPlans]
.reverse()
.find((candidate) => candidate.minimumLevel <= safeLevel) ?? null;
}
export function runtimePartyTalentProvenanceForLevel(
profile: PartyTalentRuntimeProfile,
level: number,
): PartyTalentRuntimeProvenance {
const selected = levelPlanFor(profile, level);
if (!selected) {
return {
sourcePointCount: profile.sourcePointCount,
sourcePointsRetained: profile.sourcePointsRetained,
fallbackPointCount: profile.fallbackPointCount,
sourceLevels: [],
};
}
const safeLevel = Number.isFinite(level) ? Math.max(1, Math.min(80, Math.trunc(level))) : 1;
const points = Math.max(0, safeLevel - 9);
const sourcePointsRetained = selected.sourcePointFlags.slice(0, points).filter(Boolean).length;
return {
sourcePointCount: selected.sourcePointCount,
sourcePointsRetained,
fallbackPointCount: Math.max(0, points - sourcePointsRetained),
sourceLevels: selected.sourceLevels,
};
}
/** Runtime-only projection of the catalog-validated 71-point party plans. */
@@ -28,9 +131,11 @@ export function runtimePartyTalentRanksForLevel(
classId: ClassId,
specialization: string,
level: number,
profileId?: string,
): TalentRanks {
const plan = runtimePartyTalentPlan(classId, specialization);
const safeLevel = Number.isFinite(level) ? Math.max(1, Math.min(80, Math.trunc(level))) : 1;
const profile = runtimePartyTalentProfile(classId, specialization, profileId);
const plan = levelPlanFor(profile, safeLevel)?.plan ?? profile.plan;
const points = Math.max(0, safeLevel - 9);
const ranks: Record<string, number> = {};
for (const nodeId of plan.slice(0, points)) ranks[nodeId] = (ranks[nodeId] ?? 0) + 1;
src/game/partyTalentUi.test.ts
+4 -11
View File
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { partyTalentAllocationPlan } from "./partyTalents";
import { runtimePartyTalentPlan } from "./partyTalentRuntime";
import { partyTalentSelections } from "./partyTalentUi";
import { loadTalentUiCatalog } from "./talentUiCatalog";
@@ -7,17 +7,10 @@ describe("party talent UI projection", () => {
it("reconstructs the generated runtime plan from one class shard", async () => {
const catalog = await loadTalentUiCatalog("warrior");
const projected = partyTalentSelections(catalog, "warrior", "Protection");
const source = partyTalentAllocationPlan("warrior", "Protection");
const source = runtimePartyTalentPlan("warrior", "Protection");
expect(projected).toHaveLength(71);
expect(projected.map((selection) => ({
nodeId: selection.nodeId,
rank: selection.rank,
description: selection.description,
}))).toEqual(source.map((selection) => ({
nodeId: selection.nodeId,
rank: selection.rank,
description: selection.description,
})));
expect(projected.map((selection) => selection.nodeId)).toEqual(source);
expect(projected.every((selection) => selection.rank >= 1 && selection.description.length > 0)).toBe(true);
});
});
src/game/rotationTelemetry.ts
+23
View File
@@ -0,0 +1,23 @@
export interface RotationDecisionTelemetryEvent {
readonly occurredAt: number;
readonly actorId: string;
readonly abilityId: string;
readonly targetId: string | null;
readonly profileId: string;
readonly ruleId: string;
readonly reason: string;
}
type RotationDecisionListener = (event: RotationDecisionTelemetryEvent) => void;
const listeners = new Set<RotationDecisionListener>();
export function subscribeRotationDecisions(listener: RotationDecisionListener): () => void {
listeners.add(listener);
return () => listeners.delete(listener);
}
/** Observational only: listeners cannot alter or delay the selected action. */
export function emitRotationDecision(event: RotationDecisionTelemetryEvent): void {
for (const listener of listeners) listener(event);
}
src/game/wow335AbilityCatalog.ts
+58 -4
View File
@@ -21,6 +21,7 @@ import type {
} from "./combatAuras";
import generatedData from "./wow335AbilityData.generated.json";
import { playerCombatPower } from "./progression";
import { talentNodeById } from "./talentCatalog";
import { baseResourcesFor } from "./wotlkStats";
export const BASE_CLASS_STARTER_SOURCE_LEVEL = 10;
@@ -787,6 +788,7 @@ function classScriptEffects(
case "hunter:Disengage": return [{ kind: "movement", movement: "leap", toward: "away" }];
case "hunter:Freezing Arrow": return [{ kind: "status", status: "freeze", durationMs: 10_000 }];
case "hunter:Feign Death": return [{ kind: "threat", mode: "percent", amount: -100 }];
case "hunter:Readiness": return [{ kind: "cooldown-reset", mode: "reset" }];
case "rogue:Shiv": return [{ kind: "damage", coefficient: 1 }];
case "rogue:Killing Spree": return [{
kind: "dot", coefficient: 0.5, ticks: 5, intervalMs: 500, tag: "killing-spree",
@@ -795,15 +797,60 @@ function classScriptEffects(
// not player-facing SkillLine records. The DBC combo award remains intact.
case "rogue:Mutilate": return [{ kind: "damage", coefficient: 2 }];
case "rogue:Garrote": return [{ kind: "status", status: "silence", durationMs: 3_000 }];
case "rogue:Cloak of Shadows": return [{
kind: "dispel", mode: "cleanse", relationship: "friendly", categories: ["magic"], maxCount: 10,
case "rogue:Cold Blood": return [{
kind: "apply-aura",
aura: {
id: `wow335:${rank.spellId}:cold-blood`,
name: abilityName,
disposition: "buff",
durationMs: rank.durationMs > 0 ? rank.durationMs : 20_000,
maxStacks: 1,
stackBehavior: "refresh",
modifiers: [{ kind: "stat", stat: "critical-strike", operation: "flat", value: 1 }],
},
recipient: "caster",
sourceEffectType: 6,
sourceAuraType: 4,
miscValue: 0,
triggerSpellId: 0,
}];
case "rogue:Cloak of Shadows": return [
{
kind: "dispel", mode: "cleanse", relationship: "friendly", categories: ["magic"], maxCount: 10,
},
{
kind: "apply-aura",
aura: {
id: `wow335:${rank.spellId}:cloak-of-shadows`,
name: abilityName,
disposition: "buff",
durationMs: rank.durationMs > 0 ? rank.durationMs : 5_000,
maxStacks: 1,
stackBehavior: "refresh",
modifiers: schoolsFromMask(126).map((school) => ({
kind: "damage" as const,
direction: "taken" as const,
school,
operation: "percent" as const,
value: -0.9,
})),
},
recipient: "caster",
sourceEffectType: 6,
sourceAuraType: 4,
miscValue: 126,
triggerSpellId: 0,
},
];
// Both spells place a channel aura whose actual pulses live in non-player
// trigger spells. Keep the imported cast/cost/rank data and supply only the
// missing executable payload.
case "priest:Mind Flay": return [{ kind: "damage", coefficient: 0.9 }];
case "priest:Penance": return [{ kind: "heal", coefficient: 1.8 }];
case "priest:Shadowfiend": return [{ kind: "summon", creatureId: 19668, coefficient: 0.5, durationMs: 15_000 }];
case "priest:Shadowfiend": return [
{ kind: "summon", creatureId: 19668, coefficient: 0.5, durationMs: 15_000 },
{ kind: "resource", resource: "mana", amount: 30, percentage: true },
];
case "priest:Prayer of Mending": return [{
kind: "apply-aura",
aura: {
@@ -1359,7 +1406,14 @@ function abilityDefinition(classId: BaseClassId, chain: Wow335Chain): AbilityDef
effects: first.effects,
passive: chain.passive,
source: "wow335-progression",
talentNodeId: chain.talentNodeId,
// Some stock WotLK active talents remain in Spell.dbc after Ascension's
// patched Talent.dbc removes their nodes (Devastate, Shadowstep, Lava
// Lash). They cannot be allocated by any legal local build, so expose
// those retained class actions at their source level instead of making
// them permanently unlearnable behind a dangling talent ID.
talentNodeId: chain.talentNodeId && talentNodeById(chain.talentNodeId)
? chain.talentNodeId
: undefined,
ranks,
};
}
src/main.tsx
+9 -3
View File
@@ -11,6 +11,8 @@ import "./ui/dungeonReports.css";
import "./ui/thorUi.css";
const BottomDisplayApp = lazy(() => import("./platform/BottomDisplayApp").then((module) => ({ default: module.BottomDisplayApp })));
const BalanceLabScreen = lazy(() => import("./ui/BalanceLabScreen").then((module) => ({ default: module.BalanceLabScreen })));
const LOCAL_BALANCE_LAB_GUI = import.meta.env.VITE_LOCAL_BALANCE_LAB_GUI === "true";
const params = new URLSearchParams(window.location.search);
const displayMode = params.get("display");
@@ -22,15 +24,19 @@ if (Capacitor.isNativePlatform() && (displayMode === "top" || displayMode === "b
if (Capacitor.isNativePlatform() || nativeLayoutRequested) document.documentElement.classList.add("native-platform");
if (displayMode === "top" || displayMode === "bottom") document.documentElement.dataset.displaySurface = displayMode;
document.documentElement.dataset.displayLayout = currentDisplayLayout();
startControllerInput();
void initializeContentSystem();
if (!LOCAL_BALANCE_LAB_GUI) {
startControllerInput();
void initializeContentSystem();
}
// React's development StrictMode replays effect cleanup immediately after the
// first mount. The installed R3F Canvas cleanup schedules a forced WebGL
// context loss 500 ms later, even after the live canvas has been reactivated.
// Keep the game root single-mounted so that teardown cannot blank a live scene.
createRoot(document.getElementById("root")!).render(
displayMode === "bottom"
LOCAL_BALANCE_LAB_GUI
? <Suspense fallback={null}><BalanceLabScreen executionTarget="local" onClose={() => window.close()} /></Suspense>
: displayMode === "bottom"
? <Suspense fallback={null}><BottomDisplayApp /></Suspense>
: <App />,
);
src/styles.css
+46
View File
@@ -1906,6 +1906,52 @@ html[data-display-layout="thor-preview"], html[data-display-layout="thor-preview
.front-button--quiet { border-color: transparent; background: rgba(255, 255, 255, 0.025); }
.front-button--danger { border-color: rgba(209, 103, 90, 0.35); background: rgba(148, 54, 44, 0.18); }
.front-button:disabled { cursor: not-allowed; filter: saturate(0.2); opacity: 0.45; }
.companion-readiness { display: grid; grid-template-rows: auto auto auto minmax(0, 1fr) auto; gap: 12px; }
.companion-readiness__header { display: flex; align-items: center; gap: 14px; padding-bottom: 10px; border-bottom: 1px solid var(--front-line); }
.companion-readiness__header > div:nth-child(2) { display: flex; min-width: 0; flex: 1; flex-direction: column; }
.companion-readiness__header span { color: var(--front-dim); font-size: 8px; letter-spacing: .13em; text-transform: uppercase; }
.companion-readiness__header strong { font: 20px Georgia, serif; }
.companion-readiness__intro { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 20px; align-items: center; }
.companion-readiness__intro p:last-child { max-width: 760px; margin: 5px 0 0; color: var(--front-dim); font-size: 10px; line-height: 1.5; }
.companion-readiness__totals { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 6px; }
.readiness-badge { display: inline-flex; align-items: center; gap: 4px; padding: 4px 7px; border: 1px solid var(--front-line); border-radius: 999px; font-size: 8px; font-style: normal; white-space: nowrap; }
.readiness-badge--ready { border-color: rgba(140,191,120,.5); background: rgba(79,129,65,.22); color: var(--front-green-bright); }
.readiness-badge--beta { border-color: rgba(216,174,87,.5); background: rgba(152,108,30,.2); color: #f0cb76; }
.readiness-badge--needs-testing { color: var(--front-dim); }
.companion-readiness__filters { display: grid; grid-template-columns: minmax(170px, 1fr) 150px 170px auto; gap: 8px; align-items: end; }
.companion-readiness__filters label { display: grid; gap: 3px; color: var(--front-dim); font-size: 8px; text-transform: uppercase; }
.companion-readiness__filters input, .companion-readiness__filters select, .companion-readiness__spec select { min-height: 34px; padding: 6px 8px; border: 1px solid var(--front-line); border-radius: 6px; background: #0a1812; color: var(--front-cream); }
.companion-readiness__filters > small { padding-bottom: 9px; color: var(--front-dim); font-size: 8px; }
.companion-readiness__catalog { min-height: 0; padding-right: 5px; overflow: auto; scrollbar-gutter: stable; }
.companion-readiness__class { display: grid; grid-template-columns: 120px minmax(0, 1fr); gap: 10px; padding: 8px 0; border-top: 1px solid rgba(204,224,180,.1); }
.companion-readiness__class h2 { margin: 7px 0; font: 16px Georgia, serif; }
.companion-readiness__class > div { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px; }
.companion-readiness__spec { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 8px; padding: 8px; border: 1px solid var(--front-line); border-radius: 8px; background: rgba(255,255,255,.025); }
.companion-readiness__spec > div { min-width: 0; }
.companion-readiness__spec strong, .companion-readiness__spec small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.companion-readiness__spec strong { font-size: 10px; }
.companion-readiness__spec small { margin-top: 3px; color: var(--front-dim); font-size: 7px; text-transform: capitalize; }
.companion-readiness__spec select { width: 118px; min-height: 30px; font-size: 8px; }
.companion-readiness__actions { display: flex; align-items: center; justify-content: flex-end; gap: 8px; padding-top: 9px; border-top: 1px solid var(--front-line); }
.companion-readiness__actions > span { margin-right: auto; color: var(--front-dim); font-size: 9px; }
.companion-readiness__actions > strong { color: #e58b7e; font-size: 8px; }
.companion-pool-controls { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 8px 10px; border: 1px solid var(--front-line); border-radius: 8px; background: rgba(255,255,255,.025); }
.companion-pool-controls label { display: flex; align-items: center; gap: 7px; color: var(--front-cream); cursor: pointer; }
.companion-pool-controls label:has(input:disabled) { cursor: not-allowed; opacity: .55; }
.companion-pool-controls input { accent-color: var(--front-green); }
.companion-pool-controls strong, .companion-pool-controls small { display: block; }
.companion-pool-controls strong { font-size: 9px; }
.companion-pool-controls small { margin-top: 2px; color: var(--front-dim); font-size: 7px; }
.companion-pool-controls--compact { padding: 5px 7px; }
@media (max-width: 760px) {
.companion-readiness__intro { grid-template-columns: 1fr; }
.companion-readiness__totals { justify-content: flex-start; }
.companion-readiness__filters { grid-template-columns: 1fr 1fr; }
.companion-readiness__filters label:first-child { grid-column: 1 / -1; }
.companion-readiness__class { grid-template-columns: 1fr; }
.companion-readiness__class > div { grid-template-columns: 1fr; }
.companion-readiness__actions { flex-wrap: wrap; }
}
.text-action { border: 0; background: transparent; color: var(--front-green-bright); cursor: pointer; font-size: 10px; text-decoration: underline; text-underline-offset: 3px; }
.text-action--danger { color: #cf8176; }
.front-notice {
src/ui/BalanceLabResults.tsx
+9 -4
View File
@@ -105,21 +105,26 @@ export function BalanceLabResults({ report }: { readonly report: BalanceLabSuite
const [partySort, setPartySort] = useState<keyof BalanceLabPartyResult>("partyDps");
const [ascending, setAscending] = useState(false);
const query = search.trim().toLowerCase();
const reportedClasses = report.npcClassSpecs?.length ? report.npcClassSpecs : report.classSpecs;
const reportedAbilities = report.npcClassAbilities?.length
? report.npcClassAbilities
: report.classAbilities ?? [];
const npcOnly = Boolean(report.npcClassSpecs?.length);
const bosses = useMemo(() => report.bosses.filter((boss) => (
(bossSource === "all" || boss.category === bossSource)
&& (!query || `${boss.bossName} ${boss.dungeonTitle} ${boss.bossKey} ${boss.pressureFlag}`.toLowerCase().includes(query))
)), [bossSource, query, report.bosses]);
const classes = useMemo(() => report.classSpecs.filter((row) => (
const classes = useMemo(() => reportedClasses.filter((row) => (
(partySource === "all" || row.source === partySource)
&& (role === "all" || row.role === role)
&& (!query || `${row.className} ${row.specialization} ${row.role} ${row.source} ${row.damageFlag}`.toLowerCase().includes(query))
)), [partySource, query, report.classSpecs, role]);
)), [partySource, query, reportedClasses, role]);
const parties = useMemo(() => report.partyConfigurations.filter((row) => (
(partySource === "all" || row.source === partySource)
&& (!query || `${row.partyConfigurationId} ${row.source} ${row.members}`.toLowerCase().includes(query))
)), [partySource, query, report.partyConfigurations]);
const allAbilities = report.classAbilities ?? [];
const allAbilities = reportedAbilities;
const abilityBuildOptions = useMemo(() => {
const unique = new Map<string, BalanceLabClassAbilityResult>();
for (const row of allAbilities) unique.set(`${row.source}/${row.buildId}`, row);
@@ -205,7 +210,7 @@ export function BalanceLabResults({ report }: { readonly report: BalanceLabSuite
<div>
<p className="front-kicker">Run analysis</p>
<h2>Level {report.level} balance report</h2>
<p>{new Date(report.generatedAt).toLocaleString()} · {report.summary.runs.toLocaleString()} simulations · every filtered row remains available below.</p>
<p>{new Date(report.generatedAt).toLocaleString()} · {report.summary.runs.toLocaleString()} simulations · {npcOnly ? "class and ability views use NPC-only observations" : "every filtered row remains available below"}.</p>
</div>
<div className="balance-results__filters">
<label><span>Find anything</span><input type="search" value={search} onChange={(event) => setSearch(event.currentTarget.value)} placeholder="Boss, dungeon, class, spec, party…" /></label>
src/ui/BalanceLabScreen.tsx
+77 -37
View File
@@ -9,6 +9,7 @@ import {
startBalanceLabJob,
startBalanceLabJobs,
type BalanceLabBossCategory,
type BalanceLabExecutionTarget,
type BalanceLabJob,
type BalanceLabPartySource,
type BalanceLabRuntimeStatus,
@@ -27,6 +28,10 @@ import {
} from "../game/benchmark/benchmarkBuilds";
import { BalanceLabResults } from "./BalanceLabResults";
import { BrandMark, FrontSurface } from "./FrontSurface";
import { CompanionPoolControls } from "./CompanionPoolControls";
import { CompanionReadinessScreen } from "./CompanionReadinessScreen";
import { useCompanionPartyPreferences } from "../game/companionPartyPreferences";
import { useCompanionSpecReadinessStore } from "../game/companionSpecReadinessStore";
type BossScope = BalanceLabBossCategory | "specific";
type LevelCoverage = "single" | "brackets";
@@ -38,6 +43,8 @@ const ARTIFACT_LABELS: Readonly<Record<string, string>> = {
"party_configurations.csv": "Party configurations CSV",
"class_specs_across_parties.csv": "Class/spec totals CSV",
"class_abilities_across_parties.csv": "Class/spec ability breakdown CSV",
"npc_class_specs_across_parties.csv": "NPC-only class/spec totals CSV",
"npc_class_abilities_across_parties.csv": "NPC-only rotation and ability CSV",
"class_spec_by_boss.csv": "Class/spec by boss CSV",
"bosses_across_parties.csv": "Boss totals CSV",
"boss_by_party.csv": "Boss by party CSV",
@@ -58,9 +65,9 @@ function progressPercent(job: BalanceLabJob): number {
return Math.max(0, Math.min(99, ((job.progress.partiesCompleted + currentFraction) / job.progress.partiesTotal) * 100));
}
function describeJob(job: BalanceLabJob): string {
if (job.status === "queued") return "Waiting for an available server worker.";
if (job.status === "failed") return job.error ?? "The server job failed.";
function describeJob(job: BalanceLabJob, local = false): string {
if (job.status === "queued") return `Waiting for an available ${local ? "local" : "server"} worker.`;
if (job.status === "failed") return job.error ?? `The ${local ? "local" : "server"} job failed.`;
if (job.status === "complete") return job.summary
? `Completed ${job.summary.runs.toLocaleString()} simulations across ${job.summary.bosses.toLocaleString()} bosses and ${job.summary.partyConfigurations.toLocaleString()} party configurations.`
: `Completed ${job.progress.partiesTotal} party configurations.`;
@@ -83,12 +90,19 @@ function coveragePartyCount(builds: readonly SelectableBenchmarkBuildCatalogEntr
}
function buildIdentity(build: SelectableBenchmarkBuildCatalogEntry): string {
return `${build.source}:${build.classId}:${build.role}:${build.orientation}`;
return `${build.source}:${build.classId}:${build.role}:${build.orientation}:${build.talentBuildId ?? "default"}`;
}
export function BalanceLabScreen({ onClose }: { readonly onClose: () => void }) {
export function BalanceLabScreen({
onClose,
executionTarget = "server",
}: {
readonly onClose: () => void;
readonly executionTarget?: BalanceLabExecutionTarget;
}) {
const session = useShellStore((state) => state.session);
const token = session?.accessToken ?? "";
const local = executionTarget === "local";
const token = local ? "" : session?.accessToken ?? "";
const [source, setSource] = useState<BalanceLabPartySource>("all");
const [specSelection, setSpecSelection] = useState<BalanceLabSpecSelection>("random");
const [specSearch, setSpecSearch] = useState("");
@@ -99,6 +113,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
const [partyConfigurations, setPartyConfigurations] = useState(10);
const [simulationsPerParty, setSimulationsPerParty] = useState(3);
const [durationSeconds, setDurationSeconds] = useState(60);
const [seatSweep, setSeatSweep] = useState(false);
const [partySeed, setPartySeed] = useState(1);
const [bossScope, setBossScope] = useState<BossScope>("all");
const [bossSearch, setBossSearch] = useState("");
@@ -114,6 +129,9 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
const [loading, setLoading] = useState(true);
const [submitting, setSubmitting] = useState(false);
const [error, setError] = useState("");
const [readinessOpen, setReadinessOpen] = useState(false);
const includeBetaSpecs = useCompanionPartyPreferences((state) => state.includeBetaSpecs);
const readinessPolicy = useCompanionSpecReadinessStore((state) => state.config);
const selectedJob = jobs.find((job) => job.id === selectedJobId) ?? jobs[0] ?? null;
const selectedReport = selectedJob ? reports[selectedJob.id] ?? null : null;
@@ -137,6 +155,11 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
|| left.role.localeCompare(right.role)
)), [catalogLevel, source]);
const selectedBuildSet = useMemo(() => new Set(selectedBuildIds), [selectedBuildIds]);
const automaticBuilds = useMemo(() => availableBuilds.filter((build) => {
if (build.source !== "wow" || !build.specializationId) return true;
const status = readinessPolicy.statuses[build.specializationId] ?? "needs-testing";
return status === "ready" || (includeBetaSpecs && status === "beta");
}), [availableBuilds, includeBetaSpecs, readinessPolicy]);
const selectedBuilds = useMemo(() => availableBuilds.filter((build) => selectedBuildSet.has(build.id)), [
availableBuilds,
selectedBuildSet,
@@ -154,20 +177,23 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
const bossCount = bossScope === "specific"
? selectedBossKeys.length
: BOSS_TESTING_CATALOG.filter((boss) => bossScope === "all" || boss.category === bossScope).length;
const coverageBuilds = specSelection === "all" ? availableBuilds : selectedBuilds;
const coverageBuilds = specSelection === "all" ? automaticBuilds : selectedBuilds;
const partyCount = specSelection === "random"
? partyConfigurations * (source === "all" ? 3 : 1)
: coveragePartyCount(coverageBuilds);
const coveredSpecCount = specSelection === "all" ? availableBuilds.length : selectedBuilds.length;
const estimatedRunsPerLevel = partyCount * bossCount * simulationsPerParty;
const coveredSpecCount = specSelection === "all" ? automaticBuilds.length : selectedBuilds.length;
const estimatedRunsPerLevel = partyCount * (seatSweep ? 5 : 1) * bossCount * simulationsPerParty;
const estimatedRuns = estimatedRunsPerLevel * targetLevels.length;
const hasPendingJobs = jobs.some((job) => job.status === "queued" || job.status === "running");
useEffect(() => {
if (!token) return;
if (!local && !token) return;
let cancelled = false;
setLoading(true);
void Promise.all([listBalanceLabJobs(token), getBalanceLabRuntime(token)]).then(([nextJobs, runtime]) => {
void Promise.all([
listBalanceLabJobs(token, executionTarget),
getBalanceLabRuntime(token, executionTarget),
]).then(([nextJobs, runtime]) => {
if (cancelled) return;
setJobs(nextJobs);
setRuntimeStatus(runtime);
@@ -179,13 +205,16 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
if (!cancelled) setLoading(false);
});
return () => { cancelled = true; };
}, [token]);
}, [executionTarget, local, token]);
useEffect(() => {
if (!token || !hasPendingJobs) return;
if ((!local && !token) || !hasPendingJobs) return;
let cancelled = false;
const timer = window.setInterval(() => {
void Promise.all([listBalanceLabJobs(token), getBalanceLabRuntime(token)]).then(([nextJobs, runtime]) => {
void Promise.all([
listBalanceLabJobs(token, executionTarget),
getBalanceLabRuntime(token, executionTarget),
]).then(([nextJobs, runtime]) => {
if (cancelled) return;
setJobs(nextJobs);
setRuntimeStatus(runtime);
@@ -194,15 +223,15 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
});
}, 1_500);
return () => { cancelled = true; window.clearInterval(timer); };
}, [hasPendingJobs, token]);
}, [executionTarget, hasPendingJobs, local, token]);
useEffect(() => {
if (!token || !selectedJob || selectedJob.status !== "complete" || selectedReport
if ((!local && !token) || !selectedJob || selectedJob.status !== "complete" || selectedReport
|| !selectedJob.artifacts.includes("suite-report.json")) return;
let cancelled = false;
setReportLoadingId(selectedJob.id);
setReportError("");
void getBalanceLabReport(selectedJob.id, token).then((report) => {
void getBalanceLabReport(selectedJob.id, token, executionTarget).then((report) => {
if (!cancelled) setReports((current) => ({ ...current, [selectedJob.id]: report }));
}).catch((reason) => {
if (!cancelled) setReportError(errorMessage(reason));
@@ -210,9 +239,9 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
if (!cancelled) setReportLoadingId((current) => current === selectedJob.id ? null : current);
});
return () => { cancelled = true; };
}, [selectedJob, selectedReport, token]);
}, [executionTarget, local, selectedJob, selectedReport, token]);
if (!sessionCanUseGmTools(session)) {
if (!local && !sessionCanUseGmTools(session)) {
return (
<FrontSurface className="gm-admin-screen" ariaLabel="Balance Lab access denied">
<section className="gm-admin-denied">
@@ -224,6 +253,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
</FrontSurface>
);
}
if (readinessOpen) return <CompanionReadinessScreen onClose={() => setReadinessOpen(false)} />;
const toggleBoss = (key: string) => {
setSelectedBossKeys((current) => current.includes(key)
@@ -239,7 +269,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
const run = async () => {
if (!runtimeStatus?.available) {
setError(runtimeStatus?.error ?? "The server Balance Lab runtime is unavailable.");
setError(runtimeStatus?.error ?? `The ${local ? "local" : "server"} Balance Lab runtime is unavailable.`);
return;
}
if (bossScope === "specific" && selectedBossKeys.length === 0) {
@@ -274,11 +304,13 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
partySeed,
bossCategory: bossScope === "specific" ? "all" as const : bossScope,
bossKeys: bossScope === "specific" ? selectedBossKeys : [],
seatSweep,
includeBetaSpecs,
};
});
const submittedJobs = specs.length === 1
? [await startBalanceLabJob(specs[0], token)]
: await startBalanceLabJobs(specs, token);
? [await startBalanceLabJob(specs[0], token, executionTarget)]
: await startBalanceLabJobs(specs, token, executionTarget);
const submittedIds = new Set(submittedJobs.map((job) => job.id));
setJobs((current) => [...submittedJobs, ...current.filter((job) => !submittedIds.has(job.id))]);
setSelectedJobId(submittedJobs[0]?.id ?? null);
@@ -293,7 +325,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
const preview = name.endsWith(".html") ? window.open("", "_blank") : null;
setError("");
try {
const blob = await fetchBalanceLabArtifact(job.id, name, token);
const blob = await fetchBalanceLabArtifact(job.id, name, token, executionTarget);
const url = URL.createObjectURL(blob);
if (preview) preview.location.href = url;
else {
@@ -310,24 +342,29 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
};
return (
<FrontSurface className="balance-lab-screen" ariaLabel="GM Balance Lab">
<FrontSurface className="balance-lab-screen" ariaLabel={local ? "Local Balance Lab" : "GM Balance Lab"}>
<header className="gm-admin-header">
<BrandMark compact />
<div><span>Server-authorized GM tool</span><strong>Balance Lab</strong></div>
<div><span>{local ? "Local development tool" : "Server-authorized GM tool"}</span><strong>Balance Lab</strong></div>
<div className="gm-admin-header__actions">
<button className="front-button" type="button" onClick={onClose}>Main menu</button>
{!local && <button className="front-button" type="button" onClick={onClose}>Main menu</button>}
</div>
</header>
<main className="balance-lab-layout">
<section className="balance-lab-config">
<p className="front-kicker">New automatic sweep</p>
<h2>Simulation setup</h2>
<p className="balance-lab-help">This mode runs on the game server. The browser submits the job and may be closed while the server continues.</p>
<p className="balance-lab-help">{local
? "This mode runs simulations on this computer. The browser may be closed, but keep the local launcher open while jobs are running."
: "This mode runs on the game server. The browser submits the job and may be closed while the server continues."}</p>
<CompanionPoolControls onOpenReadiness={() => setReadinessOpen(true)} />
{runtimeStatus && <div className={`balance-lab-runtime ${runtimeStatus.available ? "is-ready" : "is-unavailable"}`} role={runtimeStatus.available ? undefined : "alert"}>
<strong>{runtimeStatus.available ? "Server runtime ready" : "Server runtime unavailable"}</strong>
<strong>{runtimeStatus.available ? `${local ? "Local" : "Server"} runtime ready` : `${local ? "Local" : "Server"} runtime unavailable`}</strong>
<span>{runtimeStatus.available
? `${runtimeStatus.version} · ${runtimeStatus.running}/${runtimeStatus.maxConcurrent} workers active · ${runtimeStatus.queued} queued`
: `${runtimeStatus.error} Install Python 3 in the server container, set BALANCE_LAB_PYTHON=python3, and restart the app.`}</span>
: local
? `${runtimeStatus.error} Install Python 3 or set BALANCE_LAB_PYTHON, then restart the local GUI.`
: `${runtimeStatus.error} Install Python 3 in the server container, set BALANCE_LAB_PYTHON=python3, and restart the app.`}</span>
</div>}
<div className="balance-lab-form-grid">
<label><span>Party source</span><select value={source} onChange={(event) => {
@@ -359,6 +396,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
<label><span>Runs per party/boss</span><input type="number" min={1} max={100} value={simulationsPerParty} onChange={(event) => setSimulationsPerParty(event.currentTarget.valueAsNumber)} /></label>
<label><span>Fight limit (seconds)</span><input type="number" min={5} max={600} value={durationSeconds} onChange={(event) => setDurationSeconds(event.currentTarget.valueAsNumber)} /></label>
<label><span>Party seed</span><input type="number" value={partySeed} onChange={(event) => setPartySeed(event.currentTarget.valueAsNumber)} /></label>
<label className="balance-lab-form-grid__wide"><input type="checkbox" checked={seatSweep} onChange={(event) => setSeatSweep(event.currentTarget.checked)} /><span>NPC seat audit: run each party with every member active once</span></label>
<label className="balance-lab-form-grid__wide"><span>Bosses</span><select value={bossScope} onChange={(event) => setBossScope(event.currentTarget.value as BossScope)}>
<option value="all">Every boss</option><option value="wow">Every WoW boss</option><option value="rom">Every RoM boss</option><option value="specific">Pick specific bosses</option>
</select></label>
@@ -380,7 +418,7 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
<div role="listbox" aria-label="Balance Lab class specs" aria-multiselectable="true">
{filteredBuilds.map((build) => <label key={build.id} role="option" aria-selected={selectedBuildSet.has(build.id)} className={selectedBuildSet.has(build.id) ? "is-selected" : ""}>
<input type="checkbox" checked={selectedBuildSet.has(build.id)} onChange={() => toggleBuild(build.id)} />
<span><strong>{classById(build.classId).name} · {build.orientation}</strong><small>{build.source.toUpperCase()} · {build.role}</small></span>
<span><strong>{classById(build.classId).name} · {build.orientation}</strong><small>{build.source.toUpperCase()} · {build.role}{build.readinessStatus ? ` · ${readinessPolicy.statuses[build.specializationId ?? ""] ?? build.readinessStatus}` : ""}{build.talentBuildName ? ` · ${build.talentBuildName}` : ""}{build.characterName ? ` · ${build.characterName}` : ""}</small></span>
</label>)}
</div>
</section>
@@ -397,17 +435,19 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
</section>
)}
<div className="balance-lab-estimate"><span>Level jobs <b>{targetLevels.length.toLocaleString()}</b></span><span>Parties / level <b>{partyCount.toLocaleString()}</b></span><span>Bosses / level <b>{bossCount.toLocaleString()}</b></span><span>Total simulations <b>{estimatedRuns.toLocaleString()}</b></span></div>
<button className="front-button front-button--primary balance-lab-run" type="button" disabled={submitting || !runtimeStatus?.available || !Number.isFinite(estimatedRuns) || estimatedRuns < 1} onClick={() => void run()}>{submitting ? `Queuing ${targetLevels.length} job${targetLevels.length === 1 ? "" : "s"}…` : runtimeStatus && !runtimeStatus.available ? "Server runtime unavailable" : targetLevels.length === 1 ? "Run on server" : `Queue ${targetLevels.length} level jobs`}</button>
<p className="balance-lab-local-note">To spend this device's CPU instead, run <code>npm run balance:lab</code> from the project checkout.</p>
<button className="front-button front-button--primary balance-lab-run" type="button" disabled={submitting || !runtimeStatus?.available || !Number.isFinite(estimatedRuns) || estimatedRuns < 1} onClick={() => void run()}>{submitting ? `Queuing ${targetLevels.length} job${targetLevels.length === 1 ? "" : "s"}…` : runtimeStatus && !runtimeStatus.available ? `${local ? "Local" : "Server"} runtime unavailable` : targetLevels.length === 1 ? `Run ${local ? "locally" : "on server"}` : `Queue ${targetLevels.length} ${local ? "local " : ""}level jobs`}</button>
<p className="balance-lab-local-note">{local
? "Reports and run history are stored under artifacts/balance-lab-gui-runtime."
: <>To open the local GUI instead, run <code>npm run balance:gui</code> or double-click <code>scripts/Launch Balance Lab GUI.cmd</code>.</>}</p>
{error && <p className="front-notice" role="alert">{error}</p>}
</section>
<section className="balance-lab-jobs">
<header><div><p className="front-kicker">Saved on server</p><h2>Run history</h2></div><button type="button" disabled={loading} onClick={() => {
<header><div><p className="front-kicker">Saved {local ? "on this computer" : "on server"}</p><h2>Run history</h2></div><button type="button" disabled={loading} onClick={() => {
setLoading(true);
void Promise.all([listBalanceLabJobs(token), getBalanceLabRuntime(token)]).then(([nextJobs, runtime]) => { setJobs(nextJobs); setRuntimeStatus(runtime); }).catch((reason) => setError(errorMessage(reason))).finally(() => setLoading(false));
void Promise.all([listBalanceLabJobs(token, executionTarget), getBalanceLabRuntime(token, executionTarget)]).then(([nextJobs, runtime]) => { setJobs(nextJobs); setRuntimeStatus(runtime); }).catch((reason) => setError(errorMessage(reason))).finally(() => setLoading(false));
}}>Refresh</button></header>
<div className="balance-lab-history-filters"><input type="search" aria-label="Search Balance Lab run history" placeholder="Find source, level, GM…" value={jobSearch} onChange={(event) => setJobSearch(event.currentTarget.value)} /><select aria-label="Filter Balance Lab run status" value={jobStatus} onChange={(event) => setJobStatus(event.currentTarget.value as "all" | BalanceLabJob["status"])}><option value="all">All statuses</option><option value="complete">Complete</option><option value="running">Running</option><option value="queued">Queued</option><option value="failed">Failed</option></select></div>
<div className="balance-lab-history-filters"><input type="search" aria-label="Search Balance Lab run history" placeholder={`Find source, level, ${local ? "run" : "GM"}…`} value={jobSearch} onChange={(event) => setJobSearch(event.currentTarget.value)} /><select aria-label="Filter Balance Lab run status" value={jobStatus} onChange={(event) => setJobStatus(event.currentTarget.value as "all" | BalanceLabJob["status"])}><option value="all">All statuses</option><option value="complete">Complete</option><option value="running">Running</option><option value="queued">Queued</option><option value="failed">Failed</option></select></div>
<div className="balance-lab-job-list">
{visibleJobs.map((job) => <button key={job.id} type="button" className={job.id === selectedJob?.id ? "is-selected" : ""} onClick={() => setSelectedJobId(job.id)}>
<span><strong>{job.spec.source.toUpperCase()} level {job.spec.level}</strong><small>{new Date(job.createdAt).toLocaleString()} · {job.requestedBy} · {job.spec.specSelection ?? "random"} specs</small>{job.summary && <small>{job.summary.bosses.toLocaleString()} bosses · {job.summary.runs.toLocaleString()} simulations</small>}</span><em className={`is-${job.status}`}>{job.status}</em>
@@ -419,13 +459,13 @@ export function BalanceLabScreen({ onClose }: { readonly onClose: () => void })
<aside className="balance-lab-detail">
{selectedJob ? <>
<p className="front-kicker">Selected job</p><h2>{selectedJob.spec.source.toUpperCase()} level {selectedJob.spec.level}</h2>
<p>{describeJob(selectedJob)}</p>
<p>{describeJob(selectedJob, local)}</p>
<div className="balance-lab-progress" aria-label={`${progressPercent(selectedJob).toFixed(0)} percent complete`}><span style={{ width: `${progressPercent(selectedJob)}%` }} /></div>
<dl>
<div><dt>Status</dt><dd>{selectedJob.status}</dd></div><div><dt>Parties</dt><dd>{selectedJob.progress.partiesTotal}</dd></div><div><dt>Spec selection</dt><dd>{selectedJob.spec.specSelection ?? "random"}{selectedJob.spec.specSelection === "specific" ? ` · ${selectedJob.spec.selectedBuildIds?.length ?? 0} selected` : ""}</dd></div><div><dt>Runs per pairing</dt><dd>{selectedJob.spec.simulationsPerParty}</dd></div><div><dt>Boss filter</dt><dd>{selectedJob.spec.bossKeys.length ? `${selectedJob.spec.bossKeys.length} selected` : selectedJob.spec.bossCategory}</dd></div><div><dt>Fight limit</dt><dd>{selectedJob.spec.durationSeconds}s</dd></div>
</dl>
{selectedJob.status === "complete" && <div className="balance-lab-artifacts"><button type="button" className="front-button front-button--primary" onClick={() => document.getElementById("balance-lab-analysis")?.scrollIntoView({ behavior: "smooth", block: "start" })}>View graphs and filterable data</button>{selectedJob.artifacts.map((name) => <button key={name} type="button" className="front-button" onClick={() => void openArtifact(selectedJob, name)}>{ARTIFACT_LABELS[name] ?? name}</button>)}</div>}
{selectedJob.logTail.length > 0 && <details className="balance-lab-log"><summary>Server progress log</summary><pre>{selectedJob.logTail.slice(-20).join("\n")}</pre></details>}
{selectedJob.logTail.length > 0 && <details className="balance-lab-log"><summary>{local ? "Local" : "Server"} progress log</summary><pre>{selectedJob.logTail.slice(-20).join("\n")}</pre></details>}
</> : <p className="balance-lab-empty">Select a job to inspect its progress and reports.</p>}
</aside>
{selectedJob?.status === "complete" && <div className="balance-lab-analysis" id="balance-lab-analysis">
src/ui/BossTestingScreen.tsx
+5
View File
@@ -12,6 +12,8 @@ import { FrontSurface, BrandMark, ControllerLegend } from "./FrontSurface";
import { ControllerButton } from "./ControllerButton";
import { LazyLocalCompanionPanel } from "./LazyLocalCompanionPanel";
import "./bossTesting.css";
import { CompanionPoolControls } from "./CompanionPoolControls";
import { CompanionReadinessScreen } from "./CompanionReadinessScreen";
export function BossTestingScreen({ onClose }: { readonly onClose: () => void }) {
const character = useShellStore(selectedCharacter);
@@ -27,6 +29,7 @@ export function BossTestingScreen({ onClose }: { readonly onClose: () => void })
const [prepared, setPrepared] = useState(false);
const [error, setError] = useState("");
const [role, setRole] = useState<PartyRole>(character ? defaultPartyRoleForClass(character.classId) : "damage");
const [readinessOpen, setReadinessOpen] = useState(false);
const busy = useRef(false);
const alive = useRef(true);
const bosses = useMemo(() => BOSS_TESTING_CATALOG.filter((boss) =>
@@ -88,12 +91,14 @@ export function BossTestingScreen({ onClose }: { readonly onClose: () => void })
const button = (controlId: string, label: string, run: () => void, disabled = false) =>
<ControllerButton controlId={controlId} selectedId={controller.selectedId} select={controller.select}
className="front-button" type="button" onClick={run} disabled={disabled}>{label}</ControllerButton>;
if (readinessOpen) return <CompanionReadinessScreen onClose={() => setReadinessOpen(false)} />;
return <DualDisplayFrame contextLabel="Boss Testing" top={
<FrontSurface className="boss-testing-screen" ariaLabel="Boss Testing selection">
<header className="boss-testing-header"><BrandMark compact /><div><span>Main menu / Mechanics laboratory</span><h1>Boss Testing</h1></div>
{button("boss-testing-back", "Back to main menu", onClose)}</header>
<main className="boss-testing-main">
<p>Choose a boss to test with your party in an empty room. Missing content downloads automatically when you select a boss.</p>
<CompanionPoolControls onOpenReadiness={() => setReadinessOpen(true)} compact />
<div className="boss-testing-filters">
<label>Search bosses<input type="search" value={query} onChange={(event) => setQuery(event.target.value)} placeholder="Boss or dungeon name" disabled={preparing} /></label>
<label>Game<select {...selectProps("boss-testing-category")} value={category} onChange={(event) => setCategory(event.target.value)}>
src/ui/CompanionPoolControls.tsx
+19
View File
@@ -0,0 +1,19 @@
import { useCompanionPartyPreferences } from "../game/companionPartyPreferences";
import { useCompanionSpecReadinessStore } from "../game/companionSpecReadinessStore";
export function CompanionPoolControls({ onOpenReadiness, compact = false }: {
readonly onOpenReadiness: () => void;
readonly compact?: boolean;
}) {
const policy = useCompanionSpecReadinessStore((state) => state.config);
const includeBetaSpecs = useCompanionPartyPreferences((state) => state.includeBetaSpecs);
const setIncludeBetaSpecs = useCompanionPartyPreferences((state) => state.setIncludeBetaSpecs);
const betaCount = Object.values(policy.statuses).filter((status) => status === "beta").length;
return <div className={`companion-pool-controls ${compact ? "companion-pool-controls--compact" : ""}`}>
<label title={betaCount ? "Allow certified beta specializations in random NPC seats." : "No beta specs available"}>
<input type="checkbox" checked={includeBetaSpecs && betaCount > 0} disabled={betaCount === 0} onChange={(event) => setIncludeBetaSpecs(event.target.checked)} />
<span><strong>Include Beta Specs</strong><small>{betaCount ? `${betaCount} beta ${betaCount === 1 ? "spec" : "specs"} available` : "No beta specs available"}</small></span>
</label>
<button className="text-action" type="button" onClick={onOpenReadiness}>View companion readiness</button>
</div>;
}
src/ui/CompanionReadinessScreen.tsx
+106
View File
@@ -0,0 +1,106 @@
import { useMemo, useState } from "react";
import { classById } from "../app/characterCatalog";
import { sessionCanUseGmTools } from "../app/releaseFeatures";
import { useShellStore } from "../app/shellStore";
import {
WOW_COMPANION_SPECIALIZATIONS,
type CompanionSpecReadinessStatus,
} from "../game/companionSpecReadiness";
import { useCompanionSpecReadinessStore } from "../game/companionSpecReadinessStore";
import { runtimeDefaultPartyTalentProfile } from "../game/partyTalentRuntime";
import { BrandMark, FrontSurface } from "./FrontSurface";
const STATUS_LABELS: Readonly<Record<CompanionSpecReadinessStatus, string>> = {
ready: "Ready",
beta: "Beta",
"needs-testing": "Needs Testing",
};
export function CompanionReadinessScreen({ onClose }: { readonly onClose: () => void }) {
const session = useShellStore((state) => state.session);
const localEditor = import.meta.env.VITE_LOCAL_BALANCE_LAB_GUI === "true";
const editable = localEditor || sessionCanUseGmTools(session);
const policy = useCompanionSpecReadinessStore((state) => state.config);
const draft = useCompanionSpecReadinessStore((state) => state.draft);
const revision = useCompanionSpecReadinessStore((state) => state.revision);
const updatedBy = useCompanionSpecReadinessStore((state) => state.updatedBy);
const dirty = useCompanionSpecReadinessStore((state) => state.dirty);
const saving = useCompanionSpecReadinessStore((state) => state.saving);
const error = useCompanionSpecReadinessStore((state) => state.error);
const setStatus = useCompanionSpecReadinessStore((state) => state.setStatus);
const resetDraft = useCompanionSpecReadinessStore((state) => state.resetDraft);
const publish = useCompanionSpecReadinessStore((state) => state.publish);
const [query, setQuery] = useState("");
const [role, setRole] = useState("all");
const [status, setStatusFilter] = useState("all");
const active = editable ? draft : policy;
const rows = useMemo(() => WOW_COMPANION_SPECIALIZATIONS.filter((definition) => {
const className = classById(definition.classId).name;
const search = `${className} ${definition.displayName}`.toLowerCase();
return (!query.trim() || search.includes(query.trim().toLowerCase()))
&& (role === "all" || definition.role === role)
&& (status === "all" || active.statuses[definition.id] === status);
}), [active, query, role, status]);
const groups = useMemo(() => [...new Set(rows.map((definition) => definition.classId))].map((classId) => ({
classId,
definitions: rows.filter((definition) => definition.classId === classId),
})), [rows]);
const totals = Object.values(active.statuses).reduce<Record<CompanionSpecReadinessStatus, number>>((result, value) => {
result[value] += 1;
return result;
}, { ready: 0, beta: 0, "needs-testing": 0 });
return (
<FrontSurface className="companion-readiness" ariaLabel="Companion readiness">
<header className="companion-readiness__header">
<BrandMark compact />
<div><span>NPC certification</span><strong>Companion Readiness</strong></div>
<button className="front-button front-button--quiet" type="button" onClick={onClose}>Back</button>
</header>
<section className="companion-readiness__intro">
<div>
<p className="front-kicker">Certification standard</p>
<p>Ready companions have a legal Playerbots talent build at every bracket, verified gear and resources, a complete priority rotation, role reactions, and proven offensive and defensive cooldown use without unexplained idle windows.</p>
</div>
<div className="companion-readiness__totals" aria-label="Readiness totals">
{(["ready", "beta", "needs-testing"] as const).map((value) => (
<span key={value} className={`readiness-badge readiness-badge--${value}`}><b>{totals[value]}</b> {STATUS_LABELS[value]}</span>
))}
</div>
</section>
<section className="companion-readiness__filters" aria-label="Readiness filters">
<label>Search<input type="search" value={query} onChange={(event) => setQuery(event.target.value)} placeholder="Class or specialization" /></label>
<label>Role<select value={role} onChange={(event) => setRole(event.target.value)}><option value="all">All roles</option><option value="tank">Tank</option><option value="healer">Healer</option><option value="damage">Damage</option></select></label>
<label>Status<select value={status} onChange={(event) => setStatusFilter(event.target.value)}><option value="all">All statuses</option><option value="ready">Ready</option><option value="beta">Beta</option><option value="needs-testing">Needs Testing</option></select></label>
<small>Published revision {revision}{updatedBy ? ` · ${updatedBy}` : ""}</small>
</section>
<main className="companion-readiness__catalog">
{groups.map(({ classId, definitions }) => (
<section key={classId} className="companion-readiness__class">
<h2 style={{ color: classById(classId).color }}>{classById(classId).name}</h2>
<div>
{definitions.map((definition) => {
const profile = runtimeDefaultPartyTalentProfile(definition.classId, definition.displayName);
const value = active.statuses[definition.id] ?? "needs-testing";
return <article key={definition.id} className="companion-readiness__spec">
<div><strong>{definition.displayName}</strong><small>{definition.role} · {profile.characterName} · {profile.playerbotsSpecName ?? profile.id}</small></div>
{editable ? <select aria-label={`${definition.displayName} readiness`} value={value} onChange={(event) => setStatus(definition.id, event.target.value as CompanionSpecReadinessStatus)}>
<option value="ready">Ready</option><option value="beta">Beta</option><option value="needs-testing">Needs Testing</option>
</select> : <span className={`readiness-badge readiness-badge--${value}`}>{STATUS_LABELS[value]}</span>}
</article>;
})}
</div>
</section>
))}
{!rows.length && <p className="front-notice">No specializations match those filters.</p>}
</main>
{editable && <footer className="companion-readiness__actions">
<span>{dirty ? "Unpublished changes" : "Published policy is active"}</span>
{error && <strong role="alert">{error}</strong>}
<button className="front-button front-button--quiet" type="button" disabled={!dirty || saving} onClick={resetDraft}>Discard</button>
<button className="front-button front-button--primary" type="button" disabled={!dirty || saving} onClick={() => void publish(session)}>{saving ? "Publishing…" : "Publish policy"}</button>
</footer>}
</FrontSurface>
);
}
src/ui/DungeonSelectScreen.tsx
+8
View File
@@ -33,6 +33,9 @@ import { DUNGEON_RELEASE_STAGE_LABELS } from "../game/dungeonReleaseStage";
import { useDungeonReports } from "./useDungeonReports";
import { DungeonDifficultySlider } from "./DungeonDifficultySlider";
import { bossDifficultyLabel } from "../game/dungeonDifficulty";
import { useCompanionPartyPreferences } from "../game/companionPartyPreferences";
import { CompanionPoolControls } from "./CompanionPoolControls";
import { CompanionReadinessScreen } from "./CompanionReadinessScreen";
installDungeonShellRuntime();
@@ -85,7 +88,9 @@ export function DungeonSelectScreen() {
const [clearFilter, setClearFilter] = useState<DungeonClearFilter>("final");
const [difficultyId, setDifficultyId] = useState("");
const [bossDifficulty, setBossDifficulty] = useState(1);
const includeBetaSpecs = useCompanionPartyPreferences((state) => state.includeBetaSpecs);
const [expandedRuns, setExpandedRuns] = useState<ReadonlySet<string>>(new Set());
const [readinessOpen, setReadinessOpen] = useState(false);
const leaderboardDifficulty = selectedDefinition?.difficultyVariants.find((variant) => variant.id === difficultyId)
?? selectedDefinition?.difficultyVariants.find((variant) => variant.id === selectedDefinition.defaultDifficultyId);
const leaderboard = useDungeonLeaderboard(selectedDungeon?.id ?? "", leaderboardDifficulty?.id ?? "normal", clearFilter, bossDifficulty);
@@ -138,6 +143,7 @@ export function DungeonSelectScreen() {
difficultyId: leaderboardDifficulty?.id,
bossDifficulty,
partySize: 5,
includeBetaSpecs,
});
};
@@ -236,6 +242,7 @@ export function DungeonSelectScreen() {
const race = character ? raceById(character.raceId) : null;
const characterClass = character ? classById(character.classId) : null;
if (readinessOpen) return <CompanionReadinessScreen onClose={() => setReadinessOpen(false)} />;
return (
<DualDisplayFrame
contextLabel="Dungeon details"
@@ -342,6 +349,7 @@ export function DungeonSelectScreen() {
<p className="front-notice" role="status">Select this expedition to download its required files.</p>
)}
<OnlineGroupPanel />
<CompanionPoolControls onOpenReadiness={() => setReadinessOpen(true)} compact />
{rolePickerOpen && characterClass ? (
<section className="dungeon-role-picker" aria-labelledby="dungeon-role-title">
<header>
src/ui/DungeonSimulationAdminScreen.tsx
+88
View File
@@ -12,6 +12,9 @@ import { sessionCanUseGmTools } from "../app/releaseFeatures";
import { useShellStore } from "../app/shellStore";
import { DUNGEON_CATALOG } from "../game/dungeonCatalog";
import { DUNGEON_ROUTE_CATALOG } from "../game/dungeonRoutes";
import { BOSS_TESTING_CATALOG } from "../game/bossTesting";
import { requireDungeonDefinition } from "../game/dungeonRegistry";
import { useCompanionCooldownPolicyStore } from "../game/companionCooldownPolicyStore";
import type {
DungeonReplaySummary,
DungeonRouteReview,
@@ -20,6 +23,21 @@ import type {
DungeonSimulationReportV1,
} from "../game/dungeonSimulationTypes";
import { BrandMark, FrontSurface } from "./FrontSurface";
import { CompanionPoolControls } from "./CompanionPoolControls";
import { CompanionReadinessScreen } from "./CompanionReadinessScreen";
const COOLDOWN_MECHANICS = BOSS_TESTING_CATALOG.flatMap((boss) => {
const entity = requireDungeonDefinition(boss.dungeonId).entities[boss.entityId];
return (entity?.combat?.attacks ?? []).map((attack) => ({
key: `${boss.key}\u0000${attack.id}`,
bossKey: boss.key,
bossName: boss.name,
bossServerEntry: entity.combat?.serverEntry ?? null,
attackId: attack.id,
attackName: attack.name,
label: `${boss.dungeonTitle} — ${boss.name}: ${attack.name}`,
}));
});
function saveReport(report: DungeonSimulationReportV1): void {
const url = URL.createObjectURL(new Blob([JSON.stringify(report, null, 2)], { type: "application/json" }));
@@ -43,6 +61,16 @@ export function DungeonSimulationAdminScreen() {
const [overrideNote, setOverrideNote] = useState("");
const [busy, setBusy] = useState(false);
const [message, setMessage] = useState("");
const [readinessOpen, setReadinessOpen] = useState(false);
const [selectedCooldownMechanic, setSelectedCooldownMechanic] = useState(COOLDOWN_MECHANICS[0]?.key ?? "");
const cooldownDraft = useCompanionCooldownPolicyStore((state) => state.draft);
const cooldownRevision = useCompanionCooldownPolicyStore((state) => state.revision);
const cooldownDirty = useCompanionCooldownPolicyStore((state) => state.dirty);
const cooldownSaving = useCompanionCooldownPolicyStore((state) => state.saving);
const cooldownError = useCompanionCooldownPolicyStore((state) => state.error);
const replaceCooldownDraft = useCompanionCooldownPolicyStore((state) => state.replaceDraft);
const resetCooldownDraft = useCompanionCooldownPolicyStore((state) => state.resetDraft);
const publishCooldownPolicy = useCompanionCooldownPolicyStore((state) => state.publish);
const route = DUNGEON_ROUTE_CATALOG.routes.find((candidate) => candidate.dungeonId === selectedDungeonId)
?? DUNGEON_ROUTE_CATALOG.routes[0];
const dungeon = DUNGEON_CATALOG.find((candidate) => candidate.id === route?.dungeonId);
@@ -152,6 +180,39 @@ export function DungeonSimulationAdminScreen() {
}
};
const updateGenericCooldown = (key: keyof typeof cooldownDraft.generic, value: number | boolean) => {
replaceCooldownDraft({
...cooldownDraft,
generic: { ...cooldownDraft.generic, [key]: value },
});
};
const addCooldownMechanic = () => {
const mechanic = COOLDOWN_MECHANICS.find((candidate) => candidate.key === selectedCooldownMechanic);
if (!mechanic) return;
const idBase = `${mechanic.bossKey}-${mechanic.attackId}`.toLowerCase().replace(/[^a-z0-9]+/g, "-");
const existingIds = new Set(cooldownDraft.mechanics.map((rule) => rule.id));
let id = idBase;
for (let suffix = 2; existingIds.has(id); suffix += 1) id = `${idBase}-${suffix}`;
replaceCooldownDraft({
...cooldownDraft,
mechanics: [...cooldownDraft.mechanics, {
id,
enabled: true,
bossKey: mechanic.bossKey,
bossName: mechanic.bossName,
bossServerEntry: mechanic.bossServerEntry,
attackId: mechanic.attackId,
attackName: mechanic.attackName,
scope: "tank",
leadTimeMs: 2_500,
minimumCooldownSeconds: 20,
}],
});
};
if (readinessOpen) return <CompanionReadinessScreen onClose={() => setReadinessOpen(false)} />;
return (
<FrontSurface className="dungeon-sim-admin" ariaLabel="Dungeon simulation route review">
<header className="dungeon-sim-admin__header">
@@ -188,6 +249,7 @@ export function DungeonSimulationAdminScreen() {
<fieldset>
<legend>Launch live simulation</legend>
<CompanionPoolControls onOpenReadiness={() => setReadinessOpen(true)} compact />
<label><span>Mode</span><select value={mode} onChange={(event) => setMode(event.target.value as DungeonSimulationMode)}>
<option value="navigation-only">Navigation only</option>
<option value="full-combat">Full combat</option>
@@ -200,6 +262,32 @@ export function DungeonSimulationAdminScreen() {
onClick={() => route && enterDungeonSimulation(route.dungeonId, mode, seed)}
>Launch spectate mode</button>
</fieldset>
<fieldset>
<legend>Companion cooldown policy · revision {cooldownRevision}</legend>
<label><span>Use defensive below health %</span><input type="number" min="1" max="100" value={cooldownDraft.generic.defensiveHealthPercent} onChange={(event) => updateGenericCooldown("defensiveHealthPercent", Number(event.target.value))} /></label>
<label><span>Emergency defensive below health %</span><input type="number" min="1" max="100" value={cooldownDraft.generic.emergencyHealthPercent} onChange={(event) => updateGenericCooldown("emergencyHealthPercent", Number(event.target.value))} /></label>
<label><span>Healer mitigation below health %</span><input type="number" min="1" max="100" value={cooldownDraft.generic.healerMitigationHealthPercent} onChange={(event) => updateGenericCooldown("healerMitigationHealthPercent", Number(event.target.value))} /></label>
<label><span>Major offensive cooldown seconds</span><input type="number" min="0" max="600" value={cooldownDraft.generic.offensiveMajorCooldownSeconds} onChange={(event) => updateGenericCooldown("offensiveMajorCooldownSeconds", Number(event.target.value))} /></label>
<label><input type="checkbox" checked={cooldownDraft.generic.conserveOffensiveCooldownsForDurableTargets} onChange={(event) => updateGenericCooldown("conserveOffensiveCooldownsForDurableTargets", event.target.checked)} /><span>Save major offensive cooldowns for durable targets</span></label>
<label><span>Pre-empt boss mechanic</span><select value={selectedCooldownMechanic} onChange={(event) => setSelectedCooldownMechanic(event.target.value)}>
{COOLDOWN_MECHANICS.map((mechanic) => <option key={mechanic.key} value={mechanic.key}>{mechanic.label}</option>)}
</select></label>
<button className="front-button" type="button" disabled={!selectedCooldownMechanic} onClick={addCooldownMechanic}>Add mechanic rule</button>
{cooldownDraft.mechanics.map((rule, index) => (
<article key={rule.id} className="dungeon-sim-admin__route-meta">
<strong>{rule.bossName}: {rule.attackName}</strong>
<label><span>Scope</span><select value={rule.scope} onChange={(event) => replaceCooldownDraft({ ...cooldownDraft, mechanics: cooldownDraft.mechanics.map((candidate, candidateIndex) => candidateIndex === index ? { ...candidate, scope: event.target.value === "party" ? "party" : "tank" } : candidate) })}><option value="tank">Tank</option><option value="party">Party</option></select></label>
<label><span>Lead time ms</span><input type="number" min="0" max="15000" step="100" value={rule.leadTimeMs} onChange={(event) => replaceCooldownDraft({ ...cooldownDraft, mechanics: cooldownDraft.mechanics.map((candidate, candidateIndex) => candidateIndex === index ? { ...candidate, leadTimeMs: Number(event.target.value) } : candidate) })} /></label>
<label><span>Minimum defensive cooldown seconds</span><input type="number" min="0" max="600" value={rule.minimumCooldownSeconds} onChange={(event) => replaceCooldownDraft({ ...cooldownDraft, mechanics: cooldownDraft.mechanics.map((candidate, candidateIndex) => candidateIndex === index ? { ...candidate, minimumCooldownSeconds: Number(event.target.value) } : candidate) })} /></label>
<button className="front-button" type="button" onClick={() => replaceCooldownDraft({ ...cooldownDraft, mechanics: cooldownDraft.mechanics.filter((_, candidateIndex) => candidateIndex !== index) })}>Remove</button>
</article>
))}
<div className="dungeon-sim-admin__header-actions">
<button className="front-button front-button--primary" type="button" disabled={!cooldownDirty || cooldownSaving} onClick={() => void publishCooldownPolicy(session)}>Publish cooldown rules</button>
<button className="front-button" type="button" disabled={!cooldownDirty || cooldownSaving} onClick={resetCooldownDraft}>Discard</button>
</div>
{cooldownError && <p className="front-notice" role="alert">{cooldownError}</p>}
</fieldset>
<fieldset>
<legend>Exact-hash review</legend>
src/ui/MainMenuScreen.tsx
+12 -3
View File
@@ -15,6 +15,7 @@ import { MainMenuCharacterEditor, type MainMenuEditor } from "./MainMenuCharacte
const BossCardCollectionScreen = lazy(() => import("./BossCardCollection"));
const BossTestingScreen = lazy(() => import("./BossTestingScreen").then((module) => ({ default: module.BossTestingScreen })));
const BalanceLabScreen = lazy(() => import("./BalanceLabScreen").then((module) => ({ default: module.BalanceLabScreen })));
const CompanionReadinessScreen = lazy(() => import("./CompanionReadinessScreen").then((module) => ({ default: module.CompanionReadinessScreen })));
const GAME_MODES = [
{
@@ -73,22 +74,25 @@ export function MainMenuScreen() {
const [cardsOpen, setCardsOpen] = useState(false);
const [bossTestingOpen, setBossTestingOpen] = useState(false);
const [balanceLabOpen, setBalanceLabOpen] = useState(false);
const [readinessOpen, setReadinessOpen] = useState(false);
const [editor, setEditor] = useState<MainMenuEditor | null>(null);
if (editor) return <MainMenuCharacterEditor editor={editor} onClose={() => setEditor(null)} />;
if (bossTestingOpen) return <Suspense fallback={<p role="status">Opening Boss Testing…</p>}><BossTestingScreen onClose={() => setBossTestingOpen(false)} /></Suspense>;
if (balanceLabOpen) return <Suspense fallback={<p role="status">Opening Balance Lab…</p>}><BalanceLabScreen onClose={() => setBalanceLabOpen(false)} /></Suspense>;
if (readinessOpen) return <Suspense fallback={<p role="status">Opening Companion Readiness…</p>}><CompanionReadinessScreen onClose={() => setReadinessOpen(false)} /></Suspense>;
if (cardsOpen) return <Suspense fallback={<p role="status">Opening collection log…</p>}><BossCardCollectionScreen onClose={() => setCardsOpen(false)} /></Suspense>;
if (contentManagerOpen) return <ContentManagerScreen onClose={() => setContentManagerOpen(false)} />;
if (reportsOpen) return <DungeonReportsScreen onClose={() => setReportsOpen(false)} />;
return <MainMenuDestinations onOpenDownloads={() => setContentManagerOpen(true)} onOpenReports={() => setReportsOpen(true)} onOpenCards={() => setCardsOpen(true)} onOpenBossTesting={() => setBossTestingOpen(true)} onOpenBalanceLab={() => setBalanceLabOpen(true)} onOpenEditor={setEditor} />;
return <MainMenuDestinations onOpenDownloads={() => setContentManagerOpen(true)} onOpenReports={() => setReportsOpen(true)} onOpenCards={() => setCardsOpen(true)} onOpenBossTesting={() => setBossTestingOpen(true)} onOpenBalanceLab={() => setBalanceLabOpen(true)} onOpenReadiness={() => setReadinessOpen(true)} onOpenEditor={setEditor} />;
}
function MainMenuDestinations({ onOpenDownloads, onOpenReports, onOpenCards, onOpenBossTesting, onOpenBalanceLab, onOpenEditor }: {
function MainMenuDestinations({ onOpenDownloads, onOpenReports, onOpenCards, onOpenBossTesting, onOpenBalanceLab, onOpenReadiness, onOpenEditor }: {
readonly onOpenDownloads: () => void;
readonly onOpenReports: () => void;
readonly onOpenCards: () => void;
readonly onOpenBossTesting: () => void;
readonly onOpenBalanceLab: () => void;
readonly onOpenReadiness: () => void;
readonly onOpenEditor: (editor: MainMenuEditor) => void;
}) {
const activeCharacter = useShellStore((state) => state.activeCharacter);
@@ -143,7 +147,8 @@ function MainMenuDestinations({ onOpenDownloads, onOpenReports, onOpenCards, onO
{ id: "mode-reports", run: onOpenReports },
{ id: "mode-cards", run: onOpenCards },
{ id: "mode-boss-testing", run: onOpenBossTesting },
], [character, isGm, onOpenBalanceLab, onOpenBossTesting, onOpenCards, onOpenDownloads, onOpenEditor, onOpenReports, openArenas, openClassHall, openDungeons, openGmAdmin, openManastorms, returnToCharacters]);
{ id: "mode-companion-readiness", run: onOpenReadiness },
], [character, isGm, onOpenBalanceLab, onOpenBossTesting, onOpenCards, onOpenDownloads, onOpenEditor, onOpenReadiness, onOpenReports, openArenas, openClassHall, openDungeons, openGmAdmin, openManastorms, returnToCharacters]);
const controller = useMenuController(actions, {
initialId: "mode-dungeons",
onBack: returnToCharacters,
@@ -199,6 +204,10 @@ function MainMenuDestinations({ onOpenDownloads, onOpenReports, onOpenCards, onO
</header>
<OnlineGroupPanel />
<nav className="main-menu-mode-grid" aria-label="Main menu destinations">
<ControllerButton controlId="mode-companion-readiness" selectedId={controller.selectedId} select={controller.select}
className="front-button main-menu-mode main-menu-mode--available" type="button" onClick={onOpenReadiness}>
<b aria-hidden="true">CR</b><span><strong>Companion Readiness</strong><small>Review the certified NPC specialization pool and Playerbots identities.</small></span><em>Open</em>
</ControllerButton>
<ControllerButton controlId="mode-boss-testing" selectedId={controller.selectedId} select={controller.select}
className="front-button main-menu-mode main-menu-mode--available" type="button" onClick={onOpenBossTesting}>
<b aria-hidden="true">BT</b><span><strong>Boss Testing</strong><small>Choose a boss or fight a random encounter in an empty testing room.</small></span><em>Open</em>
src/ui/ManastormSelectScreen.tsx
+17
View File
@@ -42,6 +42,10 @@ import { BrandMark, ControllerLegend, FrontSurface } from "./FrontSurface";
import { OnlineGroupPanel } from "./OnlineGroupPanel";
import { useOnlineGroupStore } from "../app/onlineGroupStore";
import { specializationById } from "../game/specializationCatalog";
import { useCompanionPartyPreferences } from "../game/companionPartyPreferences";
import { useCompanionSpecReadinessStore } from "../game/companionSpecReadinessStore";
import { CompanionPoolControls } from "./CompanionPoolControls";
import { CompanionReadinessScreen } from "./CompanionReadinessScreen";
installManastormShellRuntime();
@@ -71,6 +75,9 @@ export function ManastormSelectScreen() {
? character.categoryId === "rom" ? partyRolesForClass(character.classId) : savedSpecialization ? [savedSpecialization.role] : []
: [];
const [partySize, setPartySize] = useState<ManastormPartySize>(5);
const includeBetaSpecs = useCompanionPartyPreferences((state) => state.includeBetaSpecs);
const readinessPolicy = useCompanionSpecReadinessStore((state) => state.config);
const readinessPolicyRevision = useCompanionSpecReadinessStore((state) => state.revision);
const groupHumanCount = onlineGroup?.members.length ?? 1;
const effectivePartySize = onlineGroup
? (fillWithAi ? Math.max(partySize, groupHumanCount) : groupHumanCount) as ManastormPartySize
@@ -145,6 +152,7 @@ export function ManastormSelectScreen() {
const [pendingDownloadRole, setPendingDownloadRole] = useState<PartyRole | null>(null);
const [downloading, setDownloading] = useState(false);
const [downloadError, setDownloadError] = useState("");
const [readinessOpen, setReadinessOpen] = useState(false);
useEffect(() => {
setSelectedSpellIds(persistedSpellIds);
@@ -170,6 +178,12 @@ export function ManastormSelectScreen() {
role,
effectivePartySize,
character.categoryId ?? "wow",
{
readinessPolicy,
readinessPolicyRevision,
includeBetaSpecs,
excludedPlayerSpecializationId: character.specializationId,
},
);
void preloadAvatarModels([character, ...party]).catch((error) => {
console.warn("Selected party avatar preloading could not be completed", error);
@@ -192,6 +206,7 @@ export function ManastormSelectScreen() {
contentId: "manastorm",
partySize: effectivePartySize,
startingLevel,
includeBetaSpecs,
});
};
@@ -273,6 +288,7 @@ export function ManastormSelectScreen() {
const race = character ? raceById(character.raceId) : null;
const characterClass = character ? classById(character.classId) : null;
if (readinessOpen) return <CompanionReadinessScreen onClose={() => setReadinessOpen(false)} />;
return (
<DualDisplayFrame
@@ -339,6 +355,7 @@ export function ManastormSelectScreen() {
<small>Progress and first clears are tracked separately for every party size.</small>
</header>
<OnlineGroupPanel />
<CompanionPoolControls onOpenReadiness={() => setReadinessOpen(true)} compact />
<div className="manastorm-setup-block">
<strong>Party size</strong>
src/vite-env.d.ts
Vendored
+1
View File
@@ -6,6 +6,7 @@ interface ImportMetaEnv {
readonly VITE_CONTENT_MODE: "bundled" | "downloadable";
readonly VITE_APP_VERSION: string;
readonly VITE_SHELVED_MODES_ENABLED: "true" | "false";
readonly VITE_LOCAL_BALANCE_LAB_GUI: "true" | "false";
}
interface ImportMeta {
vite.config.ts
+17
View File
@@ -4,6 +4,8 @@ import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
// @ts-expect-error Shared Node HTTP middleware also serves production bundles.
import { createBundledContentHandler } from "./server/bundled-content.mjs";
// @ts-expect-error Local-only Node middleware is activated only in balance-lab-gui mode.
import { createLocalBalanceLabApi } from "./server/local-balance-lab-api.mjs";
const packageVersion = (JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")) as { version: string }).version;
@@ -11,9 +13,22 @@ export default defineConfig(({ mode }) => {
const androidBuild = mode === "android";
const shelvedModesEnabled = mode === "shelved";
const balanceLabRuntime = mode === "balance-lab";
const localBalanceLabGui = mode === "balance-lab-gui";
const downloadableBuild = androidBuild || mode === "production" || shelvedModesEnabled;
return {
plugins: [react(), {
name: "local-balance-lab-api",
configureServer(server) {
if (!localBalanceLabGui) return;
const api = createLocalBalanceLabApi();
server.httpServer?.once("close", () => api.close());
server.middlewares.use((request, response, next) => {
void api.handle(request, response).then((handled: boolean) => {
if (!handled) next();
}).catch(next);
});
},
}, {
name: "bundled-content-preview",
configurePreviewServer(server) {
const serve = createBundledContentHandler(path.resolve(androidBuild ? "dist-android" : "dist"));
@@ -46,6 +61,7 @@ export default defineConfig(({ mode }) => {
"import.meta.env.VITE_APP_VERSION": JSON.stringify(packageVersion),
"import.meta.env.VITE_CONTENT_MODE": JSON.stringify(downloadableBuild ? "downloadable" : "bundled"),
"import.meta.env.VITE_SHELVED_MODES_ENABLED": JSON.stringify(shelvedModesEnabled ? "true" : "false"),
"import.meta.env.VITE_LOCAL_BALANCE_LAB_GUI": JSON.stringify(localBalanceLabGui ? "true" : "false"),
},
resolve: {
alias: {
@@ -90,6 +106,7 @@ export default defineConfig(({ mode }) => {
: [
"**/dungeon-pipeline/**",
"**/playtest-artifacts/**",
...(localBalanceLabGui ? ["**/artifacts/balance-lab-gui-runtime/**"] : []),
],
},
},