Feature: --class / --spec CLI flags to set simulated player class+spec (wrap A_Admin)

[claytonkimber]

Summary

Add first-class CLI flags to set the simulated player's class and spec (and optionally a convenience for character context), wrapping the existing A_Admin calls. Today the capability exists but is only reachable through --exec-lua with magic integer indices and a manually-fired event, which is error-prone for the common "render/inspect an addon as class X spec Y" workflow.

Motivation

Many UIs (action-bar/class addons especially) render completely differently per class/spec/role — Wise, for example, rebuilds its whole bar layout on PLAYER_SPECIALIZATION_CHANGED. To screenshot/dump-tree such an addon for a given class+spec, the current path is:

wow-sim --screen game --delay 400 \
  --exec-lua 'A_Admin.SetPlayerClass(11); A_Admin.SetSpec(4); A_Admin.FireEvent("PLAYER_SPECIALIZATION_CHANGED"); A_Admin.FireEvent("PLAYER_ENTERING_WORLD")' \
  screenshot -o out.webp

This requires the caller to:

• know the 1-based class index table by heart (CLASS_LABELS in src/lua_api/game_data.rs: 1 Warrior … 8 Mage … 11 Druid …),
• know the spec order_index → 1-based mapping (data/specializations.rs),
• remember to fire PLAYER_SPECIALIZATION_CHANGED (and usually PLAYER_ENTERING_WORLD) so addons actually react,
• get the ordering right (class before spec before event).

It's a lot of ceremony for what is conceptually --class Druid --spec Restoration.

Proposed

New top-level flags on Args (src/bin/wow_sim/main.rs), accepting names (case-insensitive), wrapping the existing admin functions:

--class <NAME>      e.g. Druid, "Death Knight", "Demon Hunter"   (or numeric index, for power users)
--spec  <NAME|N>    e.g. Restoration, Shadow  (or 1-based index)

Behavior:

1. Resolve --class name → class index via CLASS_LABELS; call the equivalent of A_Admin.SetPlayerClass(idx).
2. Resolve --spec name (within the chosen class) → spec index via data/specializations.rs; call A_Admin.SetSpec(idx).
3. After setting both, auto-fire PLAYER_SPECIALIZATION_CHANGED (and PLAYER_ENTERING_WORLD) so addons re-evaluate — applied at the same point --exec-lua runs (after startup events, before screenshot/dump-tree capture).
4. On an unknown class/spec name, print the valid set and exit non-zero (clap-style), rather than silently rendering a wrong/default context.

This is pure ergonomics over existing capability — no new state model. It just maps friendly names to the A_Admin.SetPlayerClass/SetSpec/FireEvent functions that already exist (src/lua_api/globals/admin.rs:98,104,389), so it can largely reuse the --exec-lua plumbing.

Optional, lower priority

The character context is already selectable via the WOW_SIM_WTF_ACCOUNT / WOW_SIM_WTF_REALM / WOW_SIM_WTF_CHARACTER env vars (src/paths.rs), but that isn't discoverable from --help. A thin --character <name> (and/or --realm, --account) flag that sets those same env values would round this out — and these are worth a mention in the README's CLI section regardless.

Note: selecting a WTF character sets which SavedVariables/config load; it does not change UnitClass("player") (that stays the sim default). So --class/--spec and --character are complementary, not redundant — both are needed to fully pin "this addon, this saved config, as this class/spec."

Why it belongs upstream

A_Admin is documented as the intended state-control API (README: "exposes an A_Admin Lua namespace for controlling state in tests (player identity, combat, party, buffs, zone, economy, etc.)"), and --screen already promotes one common pre-render state choice to a flag. Class/spec is the next most common one for any class/spec-aware UI, and it currently has no flag (confirmed: no class/spec arg on Args).