C_NamePlate API + nameplateN unit tokens

[brues-code]

Summary

Vanilla 1.12.1 backport of the modern C_NamePlate.* API, including the nameplateN unit-token family that makes every Script_Unit* accept nameplate-anchored tokens transparently.

C_NamePlate.* functions (docs/API.md#nameplate):

• C_NamePlate.GetNamePlates() — table of nameplate Frames
• C_NamePlate.GetNamePlateGUIDs() — universal enumerator (catches default vanilla plates that aren't Lua-registered)
• C_NamePlate.GetNamePlateForUnit(token) — token → frame, works for distant party/raid members
• C_NamePlate.GetNamePlateForGUID(guidString) — GUID → frame

Unit tokens (docs/API.md#unit-tokens-nameplaten):

• nameplate1..nameplateN accepted by every UnitX function — UnitName, UnitGUID, UnitClass, UnitHealth, UnitExists, UnitIsPlayer, etc. (~30 functions)
• Suffix chains compose: nameplate1target, nameplate1targettarget
• Creation-order semantics matching modern WoW; OOB returns nil cleanly (no "Unknown unit name" error)

Events (payloads match modern WoW exactly):

• NAME_PLATE_CREATED — first sighting of a nameplate frame pointer, arg1 is the Frame itself (achieved via pre-set _G.arg1 + empty format trick on the engine's printf-style dispatcher)
• NAME_PLATE_UNIT_ADDED / NAME_PLATE_UNIT_REMOVED — arg1 is the "nameplateN" unit token, formatted from the plate's index in the ordered list at fire time. For _REMOVED, the token is computed before the slot shifts out so the handler can still resolve it to the leaving unit.

Implementation notes

• Enumeration: walks the local-player-anchored object hash table for TYPEMASK_UNIT entries with non-null unit + 0xE60.
• Frame wrappers delegate to the engine's FrameScript_Object::ScriptRegister (0x00701BD0). First push for a never-seen nameplate calls it once, the engine builds a {[0] = lightuserdata} table with the framescript metatable, luaL_refs it into the registry, and writes the refkey to nameplate + 0x08. Every push thereafter — ours via rawgeti, addons' CreateFrame(parent) extraction, the engine's own internal pushers — funnels through the same registry slot and returns the same Lua table. Addon-set fields (pfUI: plate.nameplate = styledButton during NAME_PLATE_CREATED) survive every roundtrip because there's a single source of truth. The refcount-pinning caveat in CLAUDE.md is benign for pool-managed nameplates (never destroyed during a session).
• Events: per-frame poll + diff (subscribed via Tick::WorldTick), not engine hooks — the engine's transient hide/reshow cycle (~7 callers of FUN_00608A10) is absorbed because we compare snapshots, not raw +0xE60 writes.
• nameplateN tokens: single hook on FUN_TOKEN_TO_GUID (0x00515970). SStrCmpI prefix-gates "nameplate"; non-nameplate tokens fall straight through to the unmodified resolver. Suffix walker mirrors the engine's own LAB_005159d3 walker instruction-for-instruction (SStrCmpI "target" + ObjectByGUID + read UNIT_FIELD_TARGET at m_objectFields + 0x28).
• /reload safety: diff state (g_seenPlates, g_lastTickPlates, g_orderedGUIDs) is cleared in FrameScript_Initialize_h ahead of the engine's Lua teardown so currently-visible plates refire CREATED + UNIT_ADDED for the reloaded UI. The engine handles its own wrapper registry teardown — nothing per-module to invalidate.

Pitfalls hit (documented in code comments)

• m_objectFields is a pointer at obj + 0x110, not an inline byte offset — two deref's, not one. Mistaking this read function-pointer bytes as GUIDs.
• SStrCmpI (0x0064A4C0) is __stdcall, not __cdecl — declaring it cdecl makes MSVC emit a redundant add esp, 12 on top of the callee's own cleanup, drifting ESP +12 per call and crashing somewhere deep in lua_pushnil once L lands in .text.
• An earlier attempt kept our own wrapper alongside the engine's, but pfUI's CreateFrame("Button", "name", parent) inside NAME_PLATE_CREATED makes the engine register the parent itself — diverging from our wrapper and orphaning addon fields. Single-source-of-truth via ScriptRegister is the only stable shape.
• LUA_REF_REF / LUA_REF_UNREF offset provenance verified via Ghidra (canonical luaL_ref/unref shapes with FREELIST_REF chaining + LUA_NOREF/REFNIL sentinels).

Test plan

• GetNamePlates() returns Frame tables; methods like :GetWidth() work
• GetNamePlateGUIDs() returns GUIDs for both pfUI and default vanilla plates
• GetNamePlateForUnit("target") matches GetNamePlateForGUID(UnitGUID("target"))
• Events fire only on real transitions; event volume reasonable during movement (10-15/sec, matches modern WoW)
• UnitName("nameplate1"), UnitClass("nameplate1") resolve correctly
• UnitName("nameplate1target") resolves via suffix walker (mirrors engine's own targettarget behavior)
• UnitName("nameplate99") returns nil silently (no "Unknown unit name" error)
• NAME_PLATE_UNIT_ADDED arg1 is the "nameplateN" token, UnitName(arg1) resolves to the unit's name in the handler
• NAME_PLATE_UNIT_REMOVED arg1 still resolves to the leaving unit during the handler
• With pfUI: plate.nameplate decoration survives across pool recycle — same engine CGNamePlateFrame reused for a new unit returns the same wrapper-table identity, with the decoration intact
• Without pfUI: ({plate:GetRegions()})[3]:GetText() still returns the vanilla name string (the engine's bare wrapper has the framescript metatable and methods work)