Commit Graph
26 Commits
Author SHA1 Message Date
brues-code b7a78565f7 docs: an API descriptor for every registration (#144)
* docs(container): describe the C_Container functions

Descriptors for the 17 undocumented C_Container functions and the
ItemQuestInfo structure. SwapItems, MoveItem, AutoStoreItem,
GetContainerItemCharges, GetContainerItemRepairCost and
IsContainerItemOpenable are not in retail's API and are marked as
ClassicAPI extensions.

* docs(aura): describe the C_UnitAuras functions

Descriptors for the 16 undocumented C_UnitAuras functions, plus the
AuraData structure that GetAuraDataByAuraInstanceID already named but
nothing defined. The four positional getters share the Classic Era
UnitAura return list.

* docs(equipmentset): describe the C_EquipmentSet functions

Descriptors for the 18 undocumented C_EquipmentSet functions,
GameTooltip:SetEquipmentSet, and the EQUIPMENT_SETS_CHANGED,
EQUIPMENT_SWAP_PENDING and EQUIPMENT_SWAP_FINISHED events. They
describe what the functions return here, which differs from retail in
places: an icon path, not a file ID; numMissing, not numLost;
GetIgnoredSlots lists slot numbers.

* docs(faction): describe the reputation functions

Descriptors for GetFactionIDByIndex, GetFactionInfoByID,
GetFactionParentID, the 17 undocumented C_Reputation functions, the
FactionData structure, and the FACTION_STANDING_CHANGED event.
C_Reputation.IsFactionInactive and SetFactionInactive mirror stock
globals, but no Blizzard client has them under C_Reputation, so they
are marked as ClassicAPI extensions.

* docs(player): describe the player functions and events

Descriptors for C_PlayerInfo.CanUseItem, GetName, GetClass, GetRace,
GetSex and IsConnected; GetPlayerFacing, GetPlayerInfoByGUID,
UnitNameFromGUID and IsLoggedIn; the four C_PlayerCache functions; and
the PLAYER_EQUIPMENT_CHANGED, UPDATE_INVENTORY_DURABILITY,
HEARTHSTONE_BOUND and six PLAYER_STARTED/STOPPED_MOVING, LOOKING and
TURNING events. They describe what the functions return here: sex is 2
or 3, not the UnitSex enum, and GetPlayerInfoByGUID has no level.
C_PlayerCache is ours, so its functions are marked as extensions.

GetCritChance and GetRangedCritChance move from system "PaperDollInfo"
to "PlayerGlobals": PaperDollInfo is the C_PaperDollInfo namespace's
system, and a global must not share it.

* docs(map): describe the C_Map functions

Descriptors for the 30 undocumented C_Map and C_MapExplorationInfo
functions, the UiMapDetails, UiMapLayerInfo, UiMapPoint,
AreaTriggerInfo, MapOverlayInfo and MapOverlayTile structures, and the
USER_WAYPOINT_UPDATED event. mapType is a plain number because no
Enum.UIMapType is registered, and flags is always 0. GetAreaTriggerInfo,
GetAreaTriggers, GetAreas, GetMapAreaIDs, GetMapOverlays and
GetUnexploredMapTextures are marked as ClassicAPI extensions.

* docs(loot): describe the C_Loot and C_LootHistory functions

Descriptors for the six C_Loot functions and the four C_LootHistory
functions, the LootableUnit, ScannedCorpse and ScannedLootItem
structures, and the LOOT_SCAN_COMPLETED and three LOOT_HISTORY_* events.
Every C_Loot function here and C_LootHistory.Clear are marked as
ClassicAPI extensions; Blizzard's C_Loot has none of them.

* docs(sound): describe the sound functions

Descriptors for the six undocumented C_Sound functions, the PlaySound,
PlaySoundFile, StopSound, MuteSoundFile and UnmuteSoundFile globals, the
PlaySoundParams and RecentSoundFile structures, the ItemSoundType and
Vocalerrorsounds enums, and the SOUNDKIT_FINISHED event.
C_Sound.PlaySound's second argument is documented as the channel name it
takes here, not retail's UISoundSubType. GetRecentSoundFiles is marked as
a ClassicAPI extension.

* docs(console): describe the console functions

Descriptors for ConsoleExec, ConsoleEcho, ConsoleIsActive,
ConsoleGetColorFromType, ConsoleGetFontHeight, SetConsoleKey,
CalculateStringEditDistance, ConsoleGetAllCommands and
ConsolePrintAllMatchingCommands, the ConsoleCommandInfo structure, and
the ConsoleCommandType and ConsoleCategory enums. The game and glue
registrations of each function share one descriptor. ConsoleExec and
ConsoleEcho return nothing here, and SetConsoleKey takes a key code.

* docs(voicechat): describe the text-to-speech functions

Descriptors for the four C_VoiceChat text-to-speech functions, the ten
C_TTSSettings functions, the VoiceTtsVoiceType structure, and the five
VOICE_CHAT_TTS_* events. The event payloads follow the shapes the
client sends here. GetSpeechVoiceID, SetVoiceOptionByName and
RefreshVoices are marked as ClassicAPI extensions.

* docs(api): correct entries that drifted from the code

Fixes entries that the descriptor pass found to differ from what the
functions do: C_PlayerInfo.GetSex never returns 1, the name and race
getters need a visible unit for unit locations too, RememberPlayer
raises on missing arguments, mutes outlive a reload, scan results fill
in during a scan, LootHistory names can be nil and ROLL_CHANGED can
carry playerIndex 0, GetMapRectOnMap's fallback and Kalimdor ID, dungeon
maps have no parent, and GetBestMapForUnit gives zones, not subzones.

HEARTHSTONE_BOUND and the player input-state events now describe only
their behavior; the packet handlers, engine addresses and hook notes
are gone.

* docs(loot): say when LOOT_HISTORY_FULL_UPDATE fires

The comment above the loot-history event names said FULL_UPDATE was
never fired from C++, but FireFullUpdate sends it when a roll opens a
new item, when the 128-item ring evicts the oldest entry, and from
C_LootHistory.Clear.

* docs(api): describe behavior, not implementation

API.md is the contract for addon authors, so it no longer names engine
addresses, struct offsets, internal type and field names, packet
opcodes, hook mechanics, source files or our C++ modules, and drops
provenance notes and remarks about which client version lacks what.
Where that text carried a real behavior, the behavior stays in plain
words: "when the server answers" in place of an opcode, "ignores the
merchant and repair cursor modes" in place of the function it skips.

Also: C_Spell.GetSpellPowerCost no longer calls GetSpellInfo's cost the
base cost (both are the effective cost), the C_Spell cast-info note no
longer calls the functions player-only, the name-cache intro says the
game empties its cache on each world entry, and examples use a generic
realm name.

* docs(item): describe the item functions

Descriptors for the 95 undocumented item registrations: the C_Item
readers, lock, use and equip calls, the GetItemInfo family, the
Get*ItemID companions, the GameTooltip item methods, the ItemData,
ItemSetInfo and ItemEnchantInfo structures, the InventoryType,
ItemClass and ItemQuality enums, and the ITEM_DATA_LOAD_RESULT and
GET_ITEM_INFO_RECEIVED events. They describe what the functions return
here where it differs from retail: GetItemSetInfo returns a table,
GetWeaponEnchantInfo returns twelve values, and RequestLoadItemData
returns whether the request went out. GetItemIDForItemInfo's return is
now optional, since input that names no item returns nothing.

* docs(unit): describe the unit functions

Descriptors for the 49 undocumented unit functions, the PowerType enum,
and the PLAYER_FOCUS_CHANGED and UPDATE_SHAPESHIFT_FORM events. They
describe what the functions do here: UnitHealthMissing has no
usePredicted argument, IsFalling and IsSwimming take no unit,
UnitPowerType returns no color, and UnitPosition keeps its Y-first
return order.

* docs(baselib): describe the Lua library additions

Descriptors for the Lua 5.1 functions added to the game's Lua: select,
unpack with a range, xpcall with arguments, collectgarbage options,
debugstack, the math hyperbolics, fmod and modf, string.match, gmatch,
reverse, byte, split, join and trim with their global aliases, and
strreplace, plus Mixin and CreateFromMixins. strreplace is the one
ClassicAPI extension; retail binds the other aliases itself.

* docs(api): correct entries the item and unit descriptors contradicted

UnitIsMinion, UnitIsPet and UnitIsOtherPlayersPet raise on a string that
is not a unit token; only a token that names no unit, or a non-string,
returns false. GetItemCooldown does not take item names. A full request
queue makes RequestLoadItemData return false. GetInventoryItemID needs a
player, so pets and totems return nil. GetItemNameByID keeps a link's
random suffix. GetInventoryItemRepairCost raises on a non-number slot.
The Get*ItemID intro no longer calls the companions stock functions.

Also settles two entries that contradicted themselves: the summoning
ritual's channel events do fire, and GetSecondsUntilDailyReset counts to
UTC midnight. C_PlayerInfo.UnitPosition gets a line under UnitPosition.

* fix(docs): map the remaining widget method registries to systems

Methods registered on the Button, Slider, StatusBar, MessageFrame,
SimpleHTML, ScrollingMessageFrame, PlayerModel and DressUpModel
registries had descriptors, but the browser listed them as an unmapped
registry. The five Blizzard has use its names (SimpleButtonAPI and so
on); the other three are named the same way.

* docs(ui): describe the frame, texture and input functions

Descriptors for the texture, region, frame, button, editbox and tooltip
methods ClassicAPI adds, the C_Texture atlas, C_XMLUtil, C_ColorUtil,
C_UIColor and C_NamePlate functions, the binding, modifier-key, cursor
and screen globals, the AtlasInfo, XML template and DBColorExport
structures, Enum.UICursorType, and the nameplate, cursor and
MODIFIER_STATE_CHANGED events. IsMouseButtonDown, GetMouseButtonName and
GetCursorDelta move to the InputGlobals system.

* docs(spell): describe the spell, action and creature functions

Descriptors for the remaining spell, spellbook, tracking, action bar,
talent, totem, loss-of-control, macro, combat, tradeskill, targeting,
GUID, class, C_CreatureInfo and C_GameObjectInfo registrations, their
structures, and the LEARNED_SPELL_IN_SKILL_LINE, PLAYER_TOTEM_UPDATE,
LOSS_OF_CONTROL_*, CREATURE_DATA_LOAD_RESULT and
GAMEOBJECT_DATA_LOAD_RESULT events. The IsItemAction,
HasBonusActionBar and IsStackableAction globals move from the
C_ActionBar system to ActionBarGlobals.

* docs(world): describe the gossip, quest, social and vendor functions

Descriptors for C_GossipInfo, the friends and /who functions, C_QuestLog
and the quest globals, C_TaxiMap, C_MerchantFrame, C_AuctionHouse.PostItem,
the mail, group, instance, coin-text, chat, character-order and
expansion globals, their structures, the FlightPath enums, and the
QUEST_DATA_LOAD_RESULT and AUCTION_MULTISELL_* events. Globals that
named a namespaced system (QuestLog, PartyInfo, CurrencyInfo) move to
the matching *Globals system, and GetCoinText gets separate global and
C_CurrencyInfo descriptors.

* docs(lua): describe the cvar, encoding, time, addon and Lua functions

Descriptors for the cvar, C_EncodingUtil, C_DateAndTime, C_Timer,
C_AddOns, coroutine, table, security-account, event, script, clipboard
and hooksecurefunc registrations, the CalendarTime and SavedAccountInfo
structures, and the Base64Variant, CompressionMethod and
AddOnSecurityStatus enums.

* docs(api): correct entries the last descriptor pass contradicted

SelectOption takes an optional password for boxCoded options.
IsWhoQueryPending clears when the answer arrives, not after a timer, and
SendWhoQueryByName raises on a nil or non-string name. SetTalentByID
raises on a nil or non-number talentID. The gossip getters also read the
quest greeting window. GetPoint returns three values for an anchor with
no relative frame. RegisterAtlas's rectangle is optional.
GetSecondsUntilDailyReset returns nothing before login.

CopyToClipboard is a Blizzard function, not an extension, and always
returns the length. ConvertHSLToRGB, DoesTemplateExist,
GetNamePlateForGUID, GetNamePlateGUIDs and SetModernScriptArgs are
labelled as ClassicAPI extensions, and C_AuctionHouse.PostItem is
described as retail's function plus a numStacks argument.
IsAddOnLoadable's descriptor notes the nil reason for an unknown name.

* docs: start every function and event summary with a verb

Function summaries now read "Returns …", "Returns whether …" and so on,
not a bare "Whether …", "The …" or "How many …", and event summaries
read "Fires when …" instead of describing the past ("A cast ended").
A few two-sentence summaries become one sentence, and the two range
check toggles say what they do rather than "Used with …".

* refactor(lua): require a descriptor on every registration

The registrars and Event::Custom::AutoReserve no longer default their
doc argument, so a function, method table, enum, alias or custom event
registered without a descriptor does not compile. The _classicapi_
debug functions, which the documentation export skips, pass nullptr
explicitly.

* docs: stop calling namespaced Blizzard globals extensions

A function is a ClassicAPI extension only when no Blizzard client ships
it under any name. C_XMLUtil.DoesTemplateExist (the global
DoesTemplateExist), C_PlayerInfo.UnitPosition, C_Reputation.
IsFactionInactive and SetFactionInactive, and C_Macro.CreateMacro and
EditMacro are Blizzard globals under a namespace Blizzard never gave
them, so their descriptors and API.md no longer label them extensions.

* refactor(baselib): register newproxy through the registrars

newproxy set its global by hand so its C closure could carry the weak
table of valid metatables as an upvalue, which left it the one global
with no descriptor. The weak table now lives in the registry (made on
first use in each Lua state), so newproxy is a plain C function that
RegisterGlobalFunction and RegisterGlueFunction bind with a descriptor.
Behavior is unchanged.

* docs(api): drop the C++ module name from the aura timing heading

* docs(api): fix descriptor errors found in review

- UnitSpellTargetName is a Blizzard function (Unit system): drop the
  extension flag and file it under UnitGlobals.
- Flag the ClassicAPI-only spell functions as extensions: GetSpellRadius
  (global and C_Spell), GetSpellReagents, GetSpellDispelType,
  IsNextMeleeSpell, ResetsMeleeSwing, GetSpellMechanicByID,
  GetSpellEffectMechanics, GetSpellEffectInfo, GetSpellRequiredTargetLevel,
  GetSpellLevelInfo and C_SpellBook.GetPlayerSpellsByAura. No Blizzard
  client ships any of them.
- Name the Region registry SimpleScriptRegionAPI, as retail does, and
  make the no-counterpart comment cover all three rows it applies to.
- Start the VOICE_CHAT_TTS_SPEAK_TEXT_UPDATE summary with a verb.
- Type GetCurrentChatEvent's guid return as WOWGUID, matching
  GetCurrentChatGUID.
- Say that the itemInfo argument also accepts an item string.

* docs(api): document the methods the source count missed

_classicapi_UndocumentedAPI() still listed 23 names. Each sat in a method
array that already had a partial doc array, so the source count read it
as documented.

- GameTooltip: SetUnitAura, SetUnit, GetUnit, GetUnitGUID, HasUnit.
  GetUnitGUID and HasUnit are extensions; no Blizzard client ships them.
- FontString: GetStringHeight, GetUnboundedStringWidth, GetWrappedWidth,
  GetNumLines, GetLineHeight, IsTruncated, SetMaxLines, GetMaxLines,
  GetFieldSize.
- ModelScene actor: GetObjectType, IsObjectType, GetName, GetParent,
  HasScript, GetScript, SetScript, HookScript, as our object methods
  return them (1/nil, no HookScript result).
- GetAverageItemLevel moves to PaperDollInfoGlobals: PaperDollInfo is the
  C_PaperDollInfo namespace.

The in-game check now reports 0.
2026-11-13 13:52:12 -06:00
brues-code 8c4a9be0dd feat(model): the ModelScene frame type, WMO backdrops, and the Broodwatch game (#138)
* feat(model): add the ModelScene frame type and C_ModelInfo

ModelScene is a 3D stage of model actors with its own camera. 1.12.1's
Model frame is already one: every Model frame owns an M2 scene and a
clock, and its paint (SimpleModelDraw 0x0076D240) animates and draws the
whole scene, each unattached model with its own placement matrix. The
stock frame only ever places one model.

So a ModelScene is a CSimpleModel: the Model factory's allocation plus
our fields, CSimpleModel's constructor (0x0076C8E0), then copies of its
two vtables with the Model half hidden from Lua. Lookup goes to our
method hash and then CSimpleFrame's, the type answers ModelScene, Frame
and Region but not Model, and Model's script names and XML loader give
way to the Frame ones. The layer emit queues our paint on ARTWORK. The
paint repeats SimpleModelDraw call for call: save the device transforms,
project through the frame's camera over its rect, clamp the viewport,
clear depth, place each actor where slot 0x98 would place the one
model, animate the scene from the camera eye, draw passes 0 and 1, and
restore.

The camera is a CCamera made and installed the way the PlayerModel
pane makes its fallback camera (CameraCreate 0x007AC930,
SimpleModelInstallCamera 0x0076CE80). Eye and target come from the
position and forward axis. The yaw and roll properties are solved so
that the view's up vector equals the requested one. The default light is
set the way PlayerModel's constructor sets its own.

An actor is a script object holding one model in the frame's scene. It
is lit through the frame's light callback, placed with
CM2Model::SetBaseTransformTRS (0x00710650), and polled for load and
dressing from the frame's update, never from the paint. A display with
an Extra record is dressed through the engine compositor. The bounding
boxes come from GetSequenceInfo (0x00711A20) and GetBoundingBox
(0x00713640).

C_ModelInfo's getters read the rows of scenes 4, 44 and 596, embedded
from the retail 12.1.7 exports. The four active-scene functions do
nothing, as retail's own documentation says, and live in Compat.lua.

The same calls on Turtle and on retail draw the same picture (scene
4's camera on the Brown Horse, centred on Z, scaled by retail's
normalization).

Frame::Subclass now holds the vtable copy and the per-class method
hash, which Cooldown uses too. Model::DisplayInfo::CreateDisplayModel
builds a display's model for both portraits and actors.

* refactor(coord): push script coordinates through one engine chain

Every script coordinate the engine pushes (GetLeft, GetStringWidth,
GetFont's height, GetCursorPosition, OnCursorChanged) is
DivideByScreenScaleX(GetScaledScreenAspect() * [0x007FFD68] * value):
0x0041AD70, then the 1024.0f read from .rdata, then 0x0041AE40, with
the quotient stored from ST0 as a double.

Game::InternalToPixel did the same arithmetic from the globals in double
precision, while the edit-box caret, the font height getters and texture
tiling each kept a private copy of the engine chain. InternalToPixel now
makes the engine's calls in the engine's order, rounding the float
product once as the engine's fstp dword does, and the three modules use
it. PixelToInternal reads the 1024 from the same .rdata float, so the
UI_COORD_SCALE_UNIT constant is gone.

* feat(model): run retail's ModelScene Lua on the scene frame

Retail's camera registry, camera base, orbit camera, scene mixin and
actor mixin come over verbatim, with their XML templates, so a scene
built with SetFromModelSceneID frames, scales and orbits its actors the
way retail's does. What they need from the client:

Actor templates. 1.12's XML loader registers every virtual top-level
node whatever its tag, so <Actor name="ModelSceneActorTemplate"> is a
template that Xml::Template finds. CreateActor(name, template) loads it
the way an animation group loads its own: the whole inherits chain's
mixins first, then each node from the base up, then OnLoad. The
parentKey, parentArray, <Scripts> and <KeyValues> readers move out of
the animation loader so both use them.

Scene state. Light setters write the frame's M2Light through the
engine's own setters (M2LightSetType 0x0071B620, SetDirection
0x0071B6A0, SetPosition 0x0071B650, SetEnabled 0x0071B780). Fog uses
the Model frame's fields (+0x3A4..+0x3B0), stored as Model's own
SetFogColor, SetFogNear, SetFogFar and ClearFog store them, and starts
at retail's values. The draw layer goes through the engine's layer-name
functions (0x006F18B0, 0x006F1900) and marks both layers changed.
SetPaused keeps the frame update but skips Model's M2SceneAdvance. The
XML loader adds drawLayer, fogNear, fogFar and <FogColor> after the
frame's own loader.

Actor state. A blend operation for PlayAnimation. Spell visual kits use
the routine behind PlayerModel:ApplySpellVisualKit, which now takes a
model instead of a pane; the actor applies a kit once its model loads
and takes the effects off when the kit changes. 1.12 has no animation
kits, so PlayAnimationKit and StopAnimationKit change nothing.

GetCursorDelta, which the orbit camera drags with, samples the top's
cursor (+0x1118) once a frame at the head of the UI render callback and
converts it the way GetCursorPosition (0x0048B820) does, so the delta is
the difference of two GetCursorPosition values. C_PlayerInfo.
GetAlternateFormInfo answers false, false: 1.12 has no alternate forms.

* feat(model): show a unit on a ModelScene actor

ModelSceneActor:SetModelByUnit copies the unit's model the way 1.12.1's
character panes do in AttachUnitModel (0x005059A0): the unit's own
character component is pumped forced (UpdateCharacterComponent 0x00477860),
its model (+0xD8) is copied into the scene's M2 scene with
CreateModelFromModel (0x00707400, which carries the helm, shoulders and
held items), the effect and spell attachments come off
(DetachAllItemModels 0x0047A230), and the hand grips close (CloseHand
0x00479660). What DressUpModel's SetModelInstance (0x00504350) adds comes
next: a clone of the unit's component (CloneCharacterComponent 0x00476CB0,
on a pool component with the model AddRef'd) and the two held-item lanes
from unit vtable +0x98. The actor pumps the clone on every update, as the
DressUpModel paint (0x00504470) pumps its own, so outfit changes show at
once; OnModelLoaded waits for its first composite.

On top: retail's Dress, Undress(includeWeapons), UndressSlot, SetSheathed /
GetSheathed, SetAutoDress / GetAutoDress, IsGeoReady and GetModelUnitGUID.
Undress mirrors ClearModel (0x00504490); sheathing is the unit's
AttachHandItem step (AttachItemModel 0x0047A0C0 with the sheathed flag).

The lane, weapon and undress steps move out of Model::DressUp into
Model::Outfit, which the DressUpModel pane and the actor share. One change
on the pane: UndressSlot on a held slot no longer needs the component.
PumpDresser takes the engine's force argument, which the old typedef
called an unused pointer.

* feat(model): seat the player on a mount in the dressing room

A ModelScene mount actor now seats a rider the way 1.12's world mount
(0x00607A00) does: CM2Model::Attach (0x00712F70) puts the rider's model on
the mount's attachment 0, and the rider plays the seat animation (91).
Attach takes the rider off the scene's animate list and the mount holds a
reference on it, so the actor update no longer re-links a seated rider, a
rider that drops its model detaches first, and a mount that drops its
model unseats the rider through the CM2Model destructor (HandleClose2
0x007103A0 destroys at zero). The seated rider keeps its placement, now
relative to the seat, as the world mount sets the attached rider's base
transform.

CalculateMountScale is the mount display's CreatureModelScale
(CreatureDisplayInfo col 4, OFF_CREATUREDISPLAYINFO_SCALE): the world
seats the rider at +0x98 over that scale, and +0x98 is always 1.0.
DetachFromMount only detaches, leaving the seat animation, unlike the
world's Dismount (0x00607CE0). M2::Attach / M2::Detach wrap the two calls
for the actor and the visual kits; Detach tests the parent first, since
the engine call drops a reference unconditionally.

C_MountJournal.GetMountFromItem returns the mount of an item whose use
spell applies SPELL_AURA_MOUNTED; an uncached item starts its load.
Enum.ModelBlendOperation is registered.

The dressing room gains retail's mount mode: DressUpLink,
DressUpMountLink and DressUpMount show a ModelScene over DressUpFrame's
backdrop, above the button row, in place of DressUpModel (whose scale 2
rect reaches over the buttons). DressUpItem returns to the player model.
A mount whose creature is not cached opens when CREATURE_DATA_LOAD_RESULT
arrives. Control-click previews a mount from a spell link (Turtle-shaped
links too), from a cached item that is not wearable, and from the
spellbook, where a mount spell then never casts.

Retail's ModelSceneControlFrame is ported with its strings in every
locale and GameTooltip_AddBodyLine. Its seven atlases are built in: the
sprites cut from retail's CommonIcons / CommonButtons into one 128x128
palettized BLP2 near their drawn size, since a built-in texture has one
mip. Held rotation counts retail's per-frame 0.05 per 1/60 s, the speed
of 1.12's own rotate buttons, instead of per frame at 1.12's uncapped
frame rates.

* feat(model): project scene points to the frame, store overlapped models

The ModelScene mixin calls two scene methods the frame did not have: OnLoad
calls SetAllowOverlappedModels(true) for StoreModelSceneMixinTemplate, and
Transform3DPointTo2D calls Project3DPointTo2D.

Project3DPointTo2D runs the point through the matrices the paint draws with.
It saves the device projection and view (0x0058B090 / 0x0058B0B0), runs
CameraSetDeviceTransforms (0x007ADA40) over the frame's rect, reads both back
and restores them. The view looks from the origin, so the point goes in
relative to the camera eye. The matrices are row-vector, and the perspective
matrix (0x005C3CC0) puts 1 at m11, so w' is the view depth. A |w'| under
0.001 projects nothing, the rule of the engine's own projector (0x005C4F30).

The result is in the frame's units times its effective scale, from the
bottom-left of the frame, as InternalToPixel gives the rect's extent. A point
behind the camera still projects. Depth is 1 at the near clip and 0 at the
far clip, by distance along the camera's forward axis.

SetAllowOverlappedModels stores its flag (default false). 1.12 draws a model
frame whatever overlaps it, so the flag has nothing to gate.

* feat(model): frame a scene's picture with view insets and translation

SetViewInsets(left, right, top, bottom) and SetViewTranslation(x, y), with
their getters and the XML <ViewInsets left right top bottom> child, frame
the camera's picture inside the ModelScene. Both are in the frame's own
units, with y up.

The paint gives the camera's CameraSetDeviceTransforms (0x007ADA40) the
frame's rect less the insets and moved by the translation, converted to
layout units with PixelToInternal(length * effective scale). The camera
takes its aspect from that rect, as it does from the frame's. The device
projection is then read back (0x0058B090), scaled and shifted in clip space
so that the view rect lands where it lies in the frame, and set again
(0x0058B040). The viewport stays the frame's rect, so drawing still stops
at the frame's edges, and negative insets let the view reach past them.

Project3DPointTo2D keeps projecting over the frame's rect and ignores both
settings, which is what retail does.

* feat(model): pause a ModelScene actor, show a unit's creature display

SetPaused(paused[, affectsGlobalPause]) holds one actor's animation while
the rest of the scene plays on. It uses the engine's own resume: the key
bone's place in its sequence is read once the model has loaded with
CM2Model::GetKeyBoneAnimState (0x00711FE0) and set back each update with
SetKeyBoneAnimTime (0x007127F0). The model stays on the scene's animate
list, so a paused actor still moves, turns and takes the light, and its
sequence never reaches its end. Unpaused, it plays on from that frame.
GetPaused returns the actor's own flag and the global one, set as the
retail probe read them back: the default sets both, and
affectsGlobalPause false sets only the actor's own.

SetModelByUnitCreatureDisplayID(unit) shows the display the unit shows
now (UNIT_FIELD_DISPLAYID) the way SetModelByCreatureDisplayID shows one.
Retail's pet tab calls it with "pet".

* fix(model): end one-shot actor animations, drop a replaced one's end

M2SceneAdvance (0x007074D8) updates only the models on the scene's animate
list, and that update (CM2Model::Update, 0x00719370) is what queues a
sequence's end callback; the paint's animate pass then empties the list.
Actors put their models on the list after the scene frame's clock had
advanced, so no actor model was ever updated: a looping animation still
played (its pose comes from the scene clock), but a one-shot one such as
AttackUnarmed stopped on its last frame and OnAnimFinished never ran. The
scene's update now links every ready actor model (Link) before the clock
runs, the order the Model frame's own clock (0x0076D7F0) uses.

A new animation also drops an end still pending for the one it replaces.
The engine reports a replaced play to the done callback as reason 1, which
the actor ignores; an end queued in the same advance reached the actor as
if the new animation had ended. Two actors whose animations ended in one
advance then saw OnAnimFinished for the animation the other's script had
just given them.

* docs: document the ModelScene frame, its actors and C_ModelInfo

API.md gains a ModelScene section: CreateFrame("ModelScene") and its XML
attributes with the scene's starting camera, light and fog; the camera,
view inset and translation, Project3DPointTo2D, light, fog, draw layer,
pause and overlapped-model methods; every actor method (model sources,
unit dressing, placement, bounding boxes, animation and pause, spell
visual kits, mount seating), the actor scripts and <Actor> templates;
and the four C_ModelInfo getters. C_MountJournal.GetMountFromItem joins
the Mount section and GetCursorDelta the Input section.

README.md adds a Model scenes highlight, the ModelScene, ModelSceneActor,
ModelInfo and Mount rows, GetCursorDelta in the in-game and glue tables,
and Enum.ModelBlendOperation.

* fix(model): UndressSlot does nothing without a character component

Model::Outfit::UndressSlot cleared and detached a held lane even when the
pane or actor had no character component. It called DetachHeldItemSlot
and zeroed the lane on a creature model, or on a pane whose component at
OFF_DRESSUPMODEL_COMPONENT was not built yet. Before the Outfit split,
DressUpModel:UndressSlot returned early in that case.

The check is back in the shared helper, so DressUpModel and the
ModelScene actor both return before they touch a lane or a component
slot. Undress (ClearModel, 0x00504490) still clears both lanes without a
component, as vanilla's own does.

* fix(dressup): keep a pending mount preview until its own creature loads

When a mount's creature is not cached, DressUpMount records the mount and
waits for CREATURE_DATA_LOAD_RESULT. The handler cleared that record on
any creature's result. A failed or successful load of an unrelated
creature (another addon's query, a world creature) consumed it, and the
preview never opened when the mount's creature arrived.

The pending record now holds the creature GetMountInfoExtraByID loads:
the misc value of the mount spell's SPELL_AURA_MOUNTED effect, read with
C_Spell.GetSpellEffectInfo. Only that creature's result clears the
record, and only a successful one opens the preview.

* fix(dressup): look a link's mount up once

DressUpItemLink went on to DressUpMountLink for an item the model cannot
wear, and DressUpLink called DressUpMountLink again when that returned
false. A link that was neither wearable nor a mount ran the mount lookup
twice, and an uncached item started its cache load and wrote the pending
mount twice.

The wearable-item step is now one local function. DressUpItemLink, which
1.12.1's FrameXML (ItemRef, bags, loot, the auction house) calls alone,
tries the item and then the mount. DressUpLink keeps retail's shape: the
item step for item links, then one DressUpMountLink call that gets its
forcedFrame.

* refactor(frame): share the frame-class plumbing in Frame::Subclass

Cooldown and ModelScene each carried their own copy of the parts every
frame class this DLL adds needs: a type id, IsA, IsObjectType,
GetObjectType, GetScriptMethod, the deleting destructor and its layout
thunk, the vtable build, and a factory body that allocates the block with
SMemAlloc (FUN_STORM_SMEM_ALLOC, zero-filled), runs the engine class's
constructor and installs the vtables. The copies had already drifted:
Cooldown compared type names with _stricmp, ModelScene with Storm's
SStrCmpI.

Frame::Subclass::Class now holds a class's name, the engine class it
extends (vtable, layout vtable, constructor), its size and a function that
releases its own fields, plus its type id, method hash and vtable copies.
Templates on that object give the shared overrides, BuildVTables, New and
RegisterFactory (FUN_FRAMEXML_REGISTER_FACTORY). Both classes now answer
IsObjectType through Game::StrCmpI and take CSimpleFrame's script resolver
(+0x0C), which Cooldown's copied vtable already held.

* refactor(frame): one wrapper for each draw-layer invalidate

CSimpleFrame::NotifyLayerChanged (FUN_FRAME_NOTIFY_LAYER_CHANGED,
0x0076A990, __thiscall (frame, layer)) was wrapped by hand in Cooldown,
ModelScene and ClipChildren, and CScriptRegion::NotifyLayerChanged
(FUN_REGION_NOTIFY_LAYER_CHANGED, 0x0077FDF0, __thiscall (region)) in the
inline-texture pool and the texture wrap. Each file carried its own
typedef for the same engine call.

frame/LayerChange.h now holds the two: NotifyFrame and NotifyRegion. All
five files call them.

* refactor(model): share the ModelScene argument checks

Scene.cpp and SceneActor.cpp each had NumberArgs and FloatArg, the same
loop that raises the engine's "Usage: <owner>:<usage>" error when an
argument is not a number, with the frame and actor arguments in a
different order.

One NumberArgs, which takes the owner's display name, and one FloatArg
are now declared in model/Scene.h and used by both files.

* refactor(model): call the M2 tint, alpha and child lookup through M2.h

CM2Model's SetDiffuseColor (FUN_M2MODEL_SET_DIFFUSE_COLOR, 0x00710CF0)
was wrapped by hand in VisualKit and SceneActor, FindChild
(FUN_M2MODEL_FIND_CHILD, 0x00712F00) in Outfit and SceneActor, and
VisualKit called SetAlpha (FUN_M2MODEL_SET_ALPHA, 0x00710CB0) directly
next to the M2::SetAlpha wrapper.

M2.h gains SetDiffuse and FindChild, and the three files call M2::
for all three.

* refactor(model): one copy of a unit's model without its items

The portrait bake and the ModelScene actor's SetModelByUnit both copied a
unit's model with CreateModelFromModel (FUN_M2SCENE_COPY_MODEL,
0x00707400, flags 0) and stripped the copy's helm, shoulders and held
items with DetachAllItemModels (FUN_DETACH_ALL_ITEM_MODELS, 0x0047A230),
each with its own typedefs.

M2::CopyWithoutItems does the two steps; both callers use it.

* refactor(gx): one save and restore of the device transforms

The draws that leave the UI pass's transforms saved and restored the
device projection, view and viewport by hand, each with its own
typedefs: the ModelScene paint (as SimpleModelDraw 0x0076D240 does), the
portrait bake, ClipChildren's ScrollFrame-shaped draw (0x00787220), and
the ModelScene projection, which reads the camera's matrices back.
AlphaGradient read the projection and viewport the same way, and the
scene and the bake each wrapped CameraSetDeviceTransforms
(FUN_CAMERA_SET_DEVICE_TRANSFORMS, 0x007ADA40).

gx/Device.h now wraps FUN_GX_GET/SET_PROJECTION, FUN_GX_GET/SET_VIEW and
FUN_GX_GET/SET_VIEWPORT, and Gx::SavedTransforms saves all three for a
scope and restores them at its end. Model::Camera::SetDeviceTransforms
wraps the camera call. Only AlphaGradient's hooks on the two setters
still name the addresses.

The projection now also puts back the viewport, unchanged. The bake
reads and disables fog just before it saves the transforms; the restore
order is the same as before.

* refactor(frame): one wrapper for the layout sub-object's calls

Every region and frame carries a layout sub-object at +0x24 (4.3.4's
CLayoutFrame; OFF_REGION_ANCHOR, OFF_FRAME_LAYOUT_SUBOBJECT for a frame),
and three engine calls on it were wrapped by hand in sixteen files, each
with its own typedef and often its own AnchorOf / LayoutOf / FrameOf
helper:

- CLayoutFrame::GetRect (FUN_REGION_GET_RECT, 0x00768320), the
  {bottom, left, top, right} rect, false before layout;
- IsResizePending (FUN_REGION_LAYOUT_DIRTY, 0x00768310);
- CLayoutFrame::Resize (FUN_LAYOUT_RESIZE, 0x007680E0), 1 to lay out now,
  0 to mark for the layout pass.

frame/Layout.h now holds them, taking the region or frame itself, with
Of and OwnerOf for the sub-object and back, and GetResolvedRect for the
read the edge getters make (Script GetLeft 0x007A1A19: a pending resize
run now, then the rect). Frame::Subclass::FrameOfLayout is replaced by
OwnerOf.

* refactor(storm): one wrapper for SMemAlloc and SMemFree

Storm's SMemAlloc (FUN_STORM_SMEM_ALLOC, 0x006462E0) and SMemFree
(FUN_STORM_SMEM_FREE, 0x00646430), both __stdcall with four arguments,
were called by hand in thirteen files, through AddOns::EngineIO's
typedefs, local typedefs, Event::Custom's own pair and
Frame::Subclass::Allocate.

storm/Memory.h now holds Storm::Alloc, with a zero-fill option for the
flag bit 3 (Offsets::STORM_SMEM_FLAG_ZERO_FILL), and Storm::Free. Every
caller uses them, with the same file and line labels as before; the
EngineIO typedefs, Custom's pair and Subclass::Allocate are gone.

* docs(model): Project3DPointTo2D ignores the view insets and translation

The ModelScene paint frames the camera over the view rect (the frame's
rect less its insets, moved by its translation), and Project3DPointTo2D
frames it over the whole rect. That looked like a gap, so retail was
probed: a 400x200 scene with its camera at (-10, 0, 0) projected the
origin to (142.22, 71.11) plainly, with SetViewInsets(100, 0, 0, 0) and
with SetViewTranslation(50, 0). The comment above Project now records
this, so the whole-rect framing stays.

* fix(model): register Enum.ModelSceneSetting

OrbitCameraMixin tests the camera row's flags against
Enum.ModelSceneSetting.AlignLightToOrbitDelta on every update
(ShouldAlignLightToOrbitDelta), so a scene with an orbit camera threw
"attempt to index field 'ModelSceneSetting'" each frame. C_ModelInfo's
module now registers the enum with its one value, 1, under the
UIModelInfo system.

* feat(model): ModelSceneActor:TryOn

A scene actor can now put an item on its model, as DressUpModel:TryOn
does on the dressing-room pane. Creature displays carry no weapons (a
creature's are server-side equipment), so this is how an actor holds a
sword, shield or staff.

The pane's worker, TryOnItem (FUN_DRESSUPMODEL_TRY_ON_ITEM, 0x00504540),
has two arms, and Outfit::TryOn now holds both for the pane and the
actor:

- armor: UnequipCharacterSlot (0x00478960), then EquipBodySlotById
  (FUN_CHARCOMP_SET_ITEM, 0x00478AA0) on the inventory type's component
  slot;
- held items: pick the hand, keep the other lane only when CanHoldBoth
  (FUN_DRESSUPMODEL_CAN_HOLD_BOTH, 0x00504BC0) allows the pair, with
  dual wield from FUN_PLAYER_CAN_DUAL_WIELD (0x005EAB70) when the model
  shows the active player, detach the target lane, fill it and attach
  the item model (0x0047A0C0).

The pane takes armor only while its ready byte is set, which is
DISPLAYID == NATIVEDISPLAYID (0x00504450); the actor reads the same two
fields (OFF_UNIT_FIELD_NATIVEDISPLAYID = 0x1F8 added), so a shapeshifted
unit's copy takes held items only. A creature display takes held items
only, as it has no character component.

Model::TryOn holds the shared argument read (item ID, link, recipe link,
carried item name, hand slot name, enchant), the worn-item lookup and
ERR_NOT_EQUIPPABLE. DressUpModel:TryOn now uses it and Outfit::TryOn;
its own copies are gone.

The pane's worker waits for an uncached item record through the item
cache callback. The actor waits for the record and for its model to
load, and puts the waiting items on in Update, before OnModelLoaded
runs. It returns Enum.ItemTryOnReason: DataPending while the record
loads, NotEquippable for a type with no arm or armor on a model that
cannot take it, else Success.

* docs(model): ModelSceneActor:TryOn

API.md gets an entry for the actor's TryOn: which models take armor and
which take held items, the dual-wield rule, the wait for the model and
for the item data (with the hand and enchant kept), and what removes the
items. SetSheathed now says it applies to any actor and to items that
TryOn adds later. The README's ModelSceneActor row lists :TryOn.

* feat(model): ModelSceneActor DressPlayerSlot, IsSlotAllowed, IsSlotVisible

DressPlayerSlot puts one inventory slot of a SetModelByUnit actor back
to what its unit wears. An armor slot copies the unit's own character
component record for the body slot (the dword array at component+0x4A8
that UnequipCharacterSlot 0x00478960 reads and clears) onto the actor's
clone with UnequipCharacterSlot + EquipBodySlotById (0x00478AA0), so a
helm or cloak the unit hides stays off: the unit's component has no
record there. A hand slot re-reads the unit's held-item lane, display
row and enchant glow and hangs only that lane, the other hand untouched.

IsSlotAllowed answers with TryOn's arms: the hands on any model, armor
slots when the actor has a component or a dressed display and is not
shapeshifted. IsSlotVisible gives the same answer; no 1.12 model hides
a slot it allows.

Outfit's slot map is now public (ComponentSlotOf) and HangWeapons hangs
each lane through one HangLane step that DressSlot shares.

* feat(model): ModelSceneActor ItemTransmogInfo methods

GetItemTransmogInfo(slot), GetItemTransmogInfoList() and
SetItemTransmogInfo(info [, slot, ignoreChildItems]) on the actor. On
1.12.1 the appearance is the item ID and the illusion is the
SpellItemEnchantment whose glow a weapon shows.

The actor keeps what each inventory slot 1..19 wears (Outfit::Worn).
SetModelByUnit reads it from the player's visible items
(FUN_UNIT_GET_VISIBLE_ITEM 0x005F0D60, item ID at +0x08), only for slots
the model shows: an armor slot while the unit's character component
holds a record for it (+0x4A8 + slot*4, so a hidden helm or cloak is 0),
a hand while its lane holds an item. A weapon's enchant is the first of
the visible item's 7 enchants (+0x0C) with an ItemVisual, the walk
GetItemDescVisual (0x0062EC70) makes, and only when a glow shows.
Non-player units have no visible items (the table is uninitialized), so
NPCs and creature displays read 0.

Outfit::TryOn now returns the inventory slot it filled; TrimWorn zeroes
every slot the clone component or lanes no longer show after TryOn,
Undress, UndressSlot and DressPlayerSlot, so evictions follow the model.

SetItemTransmogInfo is TryOn on the info's IDs without ERR_NOT_EQUIPPABLE,
which the callers show themselves. An appearanceID of 0 changes nothing.
The list entries are built with ItemUtil.CreateItemTransmogInfo, now
ported with ItemTransmogInfoMixin, and Constants.Transmog is registered.

* feat(model): DressUpModel ItemTransmogInfo methods

DressUpModel:GetItemTransmogInfo(slot), GetItemTransmogInfoList() and
SetItemTransmogInfo(info [, slot, ignoreChildItems]), the same contract as
the ModelSceneActor's: appearanceID is the item ID, illusionID the enchant
whose glow a weapon shows, 19 slots in the list.

The pane keeps its own Outfit::Worn. SetModelInstance reads the unit's
visible items into it after the original clones the unit. Then the engine's
TryOnItem worker (0x00504540) fills it from its own arms: the armor slot of
the component slot it set, the hand that TryOnAttach hangs (with the enchant
only when a glow shows), and nothing for the lane that TryOnEvict detaches,
because the worker leaves that lane's bytes in place. A read trims every slot
the pane no longer shows, which also covers the engine's Undress
(ClearModel 0x00504490).

SetItemTransmogInfo is TryOn without ERR_NOT_EQUIPPABLE. The worker shows
it only in its default arm (DisplayError 0x13), after the record is cached,
so a quiet try-on skips the worker for that arm. An uncached item is
remembered per pane and skipped the same way when the worker's cache
callback runs it again.

The ItemTransmogInfo argument reader and the ItemUtil.CreateItemTransmogInfo
pushers move from SceneActor.cpp to Model::TryOn, so both frame types share
them. Outfit gains InvSlotOfComponent for the armor arm's slot.

* feat(model): DressUpModel IsSlotAllowed and IsSlotVisible

IsSlotAllowed answers from the gates of 1.12.1's DressUpModel::TryOnItem
worker (0x00504540): a hand takes any held item, and an armor slot needs
the pane's character component (+0x3F8) with its ready byte (+0x40C) set.
A shapeshifted unit has neither, so its armor slots are not allowed. The
neck, rings, trinkets and ranged slot have no arm in the worker. A pane
without a model allows nothing. No 1.12 model hides an item in a slot it
takes, so IsSlotVisible gives the same answer.

The slot rule moves into Outfit::SlotAllowed, which the ModelScene actor
now shares, and TryOnResult reads the armor gate through the same
ArmorReady helper.

* feat(model): ModelSceneActor SetSheathedCategory and UseUnitSheatheCategory

SetSheathedCategory(slot, category) picks where a sheathed hand item
hangs: Default (its own place), Back, Side, or Hide. It also adds
Enum.TransmogOutfitSlotOptionSheatheCategory.

1.12.1 finds the sheath attachment from the item's ItemStats sheath
type through GetSheathAttachment (0x0047A070): 1 is the back pair
(26/27), 2 is a large weapon on the back (30/31), 3 is the hip (32/33),
4 is the shield (28), and 0 has no sheath point. AttachItemModel
(0x0047A0C0) and DetachHeldItemSlot (0x0047A310) both use the type they
are given. So a category comes down to a different type for the lane:
Back turns 3 into 1, Side turns 1 or 2 into 3, and Hide gives 0.
Shields and held off-hand items keep their own type.

The lane holds the type it hangs with, so every engine detach (Undress,
UndressSlot, a TryOn that replaces the hand) removes the model from the
place it hangs at. The actor keeps each lane's own type and category,
and re-hangs a lane after each write (SetModelByUnit, TryOn,
DressPlayerSlot). UseUnitSheatheCategory(true) uses every item's own
type, because 1.12.1 units have no category.

* feat(model): ModelSceneActor attachment points and AttachToActor

Three ClassicAPI extensions on the actor:

- GetAttachmentPosition(attachmentID) calls the engine's
  CM2Model::GetAttachmentPosition (0x00712D50). It takes the
  attachment's offset through its bone matrix and then through the
  scene matrix (+0xDC, the inverse of the view the bones were built
  under). The result is in the space of the root's base matrix, which
  is the space of SetPosition. The engine does not check the id, and a
  missing id (lookup 0xFFFF) reads past the attachment table. So the
  method checks HasAttachment (0x00712CB0) first. It also needs every
  model in the parent chain to be loaded, because the call waits for
  the file and animates the parents first (EnsureAnimated, 0x00714000).
- AttachToActor(parent, attachmentID) hangs the actor on any
  attachment through CM2Model::Attach (0x00712F70). It works like
  AttachToMount without the seat animation. An id that the parent does
  not have hangs the child at the parent's origin, which is the
  unresolved-index path of EnsureAnimated.
- DetachFromActor() takes the actor off its parent (CM2Model::Detach,
  0x00713020).

EnsureAnimated recurses through the parent chain, so an attach cycle
never ends. M2::CanAttach now refuses a cycle for both AttachToActor and
AttachToMount. HasAttachment moves into M2.h, and VisualKit uses it.

* feat(model): ModelSceneActor PlaySpellVisual

A ClassicAPI extension. actor:PlaySpellVisual(spellID [, target
[, castTimeMs]]) plays the visual of a spell cast between two actors. It
follows the steps of the world chain between two units. That chain
depends on units, missile objects and world objects, and an actor has
none of them, so model/SceneSpell.cpp repeats each step on actor models:

- The visual comes from GetSpellVisualRecord (0x006EC1E0), which also
  makes the violenceLevel swap. The cast time comes from
  FUN_GET_CAST_TIME, unless the caller gives one. The speed is
  Spell +0x94.
- Precast (0x006EC220): the visual's +0x04 kit loops on the caster for
  the cast time.
- Cast: the +0x08 kit plays once. A visual with a missile (+0x18 set,
  speed above 0, a target other than the caster) makes the +0x1C model,
  or Spells\ErrorCube.mdx, as the launcher 0x0060A3D0 does. Without a
  missile, the impact plays at once (0x006E8BF0).
- Release: at the caster model's $CSL, $CSR or $CST event. The actor
  model gets the engine's event callback (CM2Model::SetEventCallback,
  0x007133A0), as a unit's model does (0x00607800). Without the event,
  the release follows ReleaseMissilesFromHand (0x0060C9B0): it uses the
  first of those events that the model has, else the caster's position.
  The release then happens when the cast kit has no animation, when the
  cast animation ends, or 2000 ms after the queue.
- Flight (0x0061CEB0, 0x0061E2A0): the speed is fitted to the time the
  missile was queued (t = d/speed - queued, capped at 100). The missile
  plays 144 InFlight and turns to its direction of travel. It aims each
  frame at the target's attachment: +0x24 through
  s_spellVisualAttachments (0x00860A18), else 15, else 19, else 0.75 of
  the target's height. The +0x28 sound loops through the 2D loop player
  0x00458900 until arrival, then fades over 0.15 s.
- Arrival (0x0061DC50): the target plays its wound animation, then the
  +0x0C impact kit. A +0x30 impact model stays at the point until it
  has no live particles (the impact list, 0x0061E930).

A kit's animation plays in place of the actor's animation. It does not
fire OnAnimFinished, and SetAnimation cancels it. Kit sounds play
through the by-ID player. Sound::Play gets a small header (PlayKitID,
PlayKitLooped, Stop) so that other modules can start a sound and stop
it safely. M2.h gets the event, particle and attachment helpers, and
VisualKit exposes its loop callback.

* feat(model): ModelSceneActor animation event sounds

ClassicAPI extensions: actor:SetPlayAnimationSounds(enabled) and
scene:SetGroundTerrain([terrainTypeID]), each with its getter.

Each actor model now gets the engine's event callback
(CM2Model::SetEventCallback, 0x007133A0), as a unit's model does
(0x00607800). model/SceneEvents.cpp sorts the events by their
four-character tag, as the unit dispatcher CGUnit_C::OnModelEvent
(0x005FFBD0) does. It receives the $CSL, $CSR and $CST missile
releases, which moved there from SceneSpell.cpp. When the actor opts
in, it also plays the sounds that a unit plays. They come from the
CreatureSoundData of the display: its own row, else its model data's,
as GetSoundData (0x0060AFB0) picks it.

- $FD1 to $FD4: the fidgets at +0x38 (0x006232C0).
- $FDX: the stand vocal at +0x20, with the world's 41-in-101 chance
  and a 10 s limit shared by all actors. It never plays for the
  active player's copy (0x006236B0, 0x00623490).
- $WNG and $WGG: the wing flap at +0x2C and the glide at +0x30. The
  dispatcher plays them as vocal kinds 7 and 10, through slot 34
  (push 7 / push 0xA, call [eax+0x88]).
- $FSD: the engine's GetFootstepSound (0x00458450), by the scene's
  ground terrain, with FootstepSounds on.
- $DTH: the dry thud from the engine's death-thud table (0x00C4E0F4),
  by size class (GetUnitSoundSize 0x00625500) and the ground.
- $CSD: the event's own SoundEntries id, with EmoteSounds on.
- $TRD: the precast sound (SpellVisual +0x38) of a PlaySpellVisual
  that is still preparing (0x0062FAA0).

The sounds are off by default, so stock scenes such as the dressing
room stay silent. They play in 2D through the by-ID player. A scene
without a ground terrain has no footsteps and no death thud. $CSS,
$CAH and $AH0 to $AH3 play nothing: they present a pending swing
(0x006247D0), and an actor never swings at anything. The unit's
display ID is kept on the actor so that its sound data can be found.

* feat(model): ModelSceneActor ApplySpellVisualKit

A ClassicAPI extension with the contract of retail's PlayerModel
(CharacterModelBase) method of the same name. The kit is added next to
the kits that the actor already shows. The actor's SetSpellVisualKit
keeps retail's behaviour: it replaces the actor's one kit.

The kit goes through Model::VisualKit::Apply, the same routine
PlayerModel:ApplySpellVisualKit uses. This is the char-select ghost's
kit step (0x004727F0) for any kit: the effect models hang at their
attachments, and the tint and alpha procedures apply. The model owns
the effects, so a looping kit stays until the model changes, and a
oneShot kit stops when its sequence ends. HasAttachment waits for an
unloaded model file, so a call made before the model has loaded is
held in Actor::pendingKits and applied with SetSpellVisualKit's kit
once the model loads.

* feat(model): ModelScene GetActorAtCursor and OnActorEnter/OnActorLeave

A ClassicAPI extension: scene:GetActorAtCursor() returns the shown actor
under the cursor, and the scene scripts OnActorEnter / OnActorLeave
(self, actor) run when that actor changes while the scene is the mouse
focus.

The pick is the world's own object pick (0x00480A50) on the scene's M2
scene, not a bounding-box test: EnableRayHits (0x007089B0), then
CM2Model::SetHitTestMode(model, 1, 0, actor) (0x00713CB0, ret 0xC) on
each shown actor's model and its children (held items, kit effects), as
0x00480D90 does for a unit; a child that is another actor's model (a
seated rider) is left to that actor. M2SceneRayHit (0x007089C0, ret 0x10,
retry 1 as the world passes) skins each instance animated in the latest
collect on the CPU and returns the value of the nearest triangle. The
ray empties the hit list on every call.

The ray is in view space, where the collect leaves the instance
matrices: the cursor (UI context +0x1118, NDC) in the paint's viewport
(the frame's rect clamped to the screen), unprojected through the
paint's own projection at view depth near and far. The paint's camera
leg is now CameraTransforms, shared with the pick, so view insets and
translation move the pick with the picture. CCamera::SetDeviceTransforms
(0x007AC640) reads only the rect's aspect, so the clamped viewport is
the space the cursor maps into.

The hover runs from the scene's update walk, only while one of the two
scripts is set (Frame::ExtraScripts cells) and the scene is the mouse
focus (UI context +0x7C).

* feat(model): ModelSceneActor SetShadowShown blob shadows

A ClassicAPI extension, off by default: actor:SetShadowShown(shown) /
IsShadowShown() put the world's blob shadow under the actor.

The shadow is 1.12's own (DrawBlobShadow 0x006D7920, reached from the
entity draw through 0x006D78F0): drawn only while shadowLOD
(0x0086F5B4) is 1 and the model is ready; the bounds of sequence (0, 0),
skipped when the x or y extent is under the range epsilon, clamped to
+-5 and multiplied by the length of the base transform's row 0
(GetBaseTransform 0x00710600); the four corners turned by the base
rotation and moved by the base translation. The texture is the one the
unit setup loads (Textures\ShadowBlob.blp, handle 0x00CE9DFC, device
object through 0x0044ACF0), with the decal's states: blend 4
(DST_COLOR / ZERO), lighting, fog and depth write off, combiner preset 5,
and the colour white with the model's alpha (GetAlpha 0x00710CA0;
0x004A2C10 packs that byte on top).

The world lays the shadow onto the ground's batches with a decal
(0x006D7330). A scene has no ground, so the paint draws the turned box
itself as a flat triangle strip on the plane of the base translation,
after the animate pass and before the draw passes, so every model draws
over the shadows. Culling is off, as for the engine's lightning quad
(0x007AFCB0). The decal's height fade and its shadowBias depth test
EQUAL are not drawn: both exist to match real ground. A model hung on
another casts none.

* feat(model): ModelScene WMO backdrops (SetWorldModel)

A ClassicAPI extension: scene:SetWorldModel(path [, x, y, z [, yaw
[, doodadSet]]]), scene:SetWorldModelByMapID(mapID) and
scene:ClearWorldModel() show a WMO around the scene's actors. Both
setters return whether a WMO is shown; a set that fails clears it.
ModelSceneActor:SetModelByPath refuses .wmo paths, which only the scene
shows.

The map object is the world's own. CMapObj::Get (0x006A3230) loads it
into the engine's cache with one reference ours, released by CountDown
(0x006A33F0). Each paint keeps every group alive for 30 s (group
+0x15C) and queues LoadGroup (0x006A4A30) for a group that is neither
parsed (+0x164) nor being read (+0x160), so a group the world frame has
freed comes back. The pools, shaders and cache come from
CMap::Initialize at client start, so a WMO also shows at the glue
screen.

The engine's reader ends the program when a file does not open
(CMap::SafeOpen) and parses the root's chunks in a fixed order without
reading their tags. A root is refused unless MVER and the 16 chunks from
MOHD to MFOG are in that order inside the file, it has at most 384
groups, and each group file opens.

The paint draws the WMO after the animate pass, the way
DrawMapObjectPass (0x00684840) draws one instance:

- render states pushed; world stack 8 = placement x Translate(-eye);
- the frustum stack pushed (0x00682380), a volume of the scene's view
  stored on it (BuildFrustumCorners 0x005C43B0 over the device view
  moved by -eye and the device projection, planes by 0x00686640), then
  moved into the object's space with the inverse placement
  (0x00682ED0), which the drawers cull each batch against;
- a lighting record at the object's bounding sphere
  (M2LightingInitialize 0x0071BC30, the scene's M2 lights for that point
  by 0x0070A0F0, the scene light as the sun by 0x0071BF90, then the fog),
  committed at the eye with fog by 0x0071C730;
- each parsed group: the portal vertex fade once (0x006C43D0), then the
  interior (0x006B5190) or exterior (0x006B4F10) drawer, called directly,
  because the world sets its drawer pointers only in its own frame.

Fog: the world fogs a WMO's insides with its MFOG records only for a WMO
with more than one record (0x0069DE20). With no candidate the fog is
record 0, its end capped at the far clip and its start that record's
fraction of the end. Other WMOs take the scene's own fog, staged with
the scene light by the frame's light callback (0x0076D680).

The drawers read two world globals. The group fog flag (0x00CA7F00)
would replace the fog with the light state's interior fog, so it is 0
while the scene draws. Window materials write the sun's colours through
the sun pointer (0x00C89EF0), which is NULL at the glue screen, so while
the scene draws it points at a copy of the scene light.

SetWorldModelByMapID reads the map's directory from Map.dbc, then the
WDT's MPHD, MAIN, MWMO and MODF. Only a map whose WDT holds one WMO and
no terrain has an answer. The placement is the world's own for a WDT
object: translate (-pos[2], -pos[0], pos[1]), then rotate z by
rot[1] + pi, y by rot[0] and x by rot[2] (degrees by 0x007FFAAC), with
the record's doodad set. Scene positions then are the map's positions,
so a creature's spawn point places its actor in the room.

Not drawn yet: the doodads, the room's light on the actors, liquids and
the camera's fog inside the WMO.

* feat(model): ModelScene WMO doodads and positional scene sounds

A WMO backdrop now shows its doodads the way the world builds them, and
every sound a scene plays is heard from the scene's camera at its distance.

Doodads (model/SceneWorld.cpp). Each parsed group makes its doodads as
CreateGroupDoodads (0x00695AA0) does: the group's MODR indices, kept when
FindDoodadSet (0x006A4FB0) gives set 0 or the instance's set; a doodad two
groups list is one def, sun-lit when any of them is exterior. Each def
mirrors CreateGroupDoodadDef (0x00694E90) and CreateDoodadModel
(0x00695100): the MODD record's translate / quaternion / scale matrix
times the placement, SplitLightColor (0x006A77E0) into the ambient and
directional bytes, the model from the MODN name, SetBaseTransform, the
engine's own done callback (0x006951B0) and PlayAnimation(-1, 0, -1, ...).

Lighting mirrors AddLights (0x006A8050): an exterior doodad takes the
frame's sun (the frame light callback 0x0076D680); an interior one its
ambient bytes and its directional bytes along the fixed direction at
0x00CA816C, then the group's MOLT point lights built as CreateGroupLights
(0x00695C00) and AddMapLight (0x006A7AC0) build them. An interior doodad
in a WMO with more than one MFOG takes MFOG[0], else the scene's fog.

Each frame mirrors DrawDoodadModels (0x00683F80): the world shows every
doodad it draws again (SetAnimated + SetVisible), faded by its sphere
(SetDoodadDefBounds 0x006952A0, CM2Model::GetBoundingSphere 0x00713680)
and the camera's ground distance, with the radius classes, fade ends and
ranges read live from 0x00810188..0x008101A8 and the large end capped by
the far clip.

Doodad sounds are opt-in, scene:SetPlayWorldModelSounds(enabled) /
GetPlayWorldModelSounds (a ClassicAPI extension, off by default): the
$DSO / $DSL / $DSE events of DoodadModelEvent (0x006951E0) through
PlaySoundAt (0x00458870) and the world's loop emitters (0x00461D80 add,
0x00462000 move, 0x00461F80 remove). The emitter pump runs only in the
world, so they play only there. A hidden scene (CSimpleFrame::Hide,
0x0076AD50) drops its loops.

Positional scene sounds (model/SceneSound.cpp). The engine has one
listener, placed by the world camera. A scene point is played where it
lies from the scene camera, its offsets along the camera's forward, up
and side laid along the listener's, read back through
FSOUND_3D_Listener_GetAttributes (0x007FDB50) in the engine's axes. The
engine then applies the row's cutoff, minimum distance and panning as for
a unit that far away. Sound::Play gains the world's 3D players:
PlayKitIDAt (0x0045CF00, RET 0x18, NULL past the cutoff), PlayKitLoopedAt
(0x004589A0) and Move (Sound::SetPosition 0x007A5B10), all owned so
StopSound stops them.

The actors use it: spell kit sounds at the actor, the missile's loop
following the missile (re-mapped each paint) and stopped when the scene
hides, and the animation sounds of SetPlayAnimationSounds at the actor.
actor:PlaySound(soundKitID) is a ClassicAPI extension: a SoundKitID once at
the actor, returning willPlay, soundHandle as PlaySound does.

* feat(model): ModelScene actors take the WMO's light

An actor standing in the scene's WMO is lit the way the world lights a
unit standing in it, instead of by the scene light alone.

Placement (World::Settle, from the scene's update) mirrors PlaceEntity
(0x006A8C10). LinkEntityToMapObject (0x006A8ED0): the model's bounds
through its base matrix give the world box and its centre (SyncLightNode
0x006717D0); the box goes into WMO space (TransformBox 0x006DC540) and is
tested against the WMO (BoxOverlaps 0x006A4670) and each group
(BoxOverlapsGroup 0x006A4830, GetLoadedGroup, GroupBoxAnyHit 0x006A3EE0 or
GroupSegmentAnyHit 0x006A3F10). In each non-exterior group,
TraceGroupMasked (0x006A3A40, mask 0x20) probes 1000 yards down from the
centre (0x008022CC), else 1000 up; t is shared, so the nearest face of all
groups wins, and its point is taken along the down probe as the engine
takes it. SetEntityLightFlags (0x006A87F0): no face, or a group with flag
0x40, means the sun. Else BakeGroupLight's face path (0x006A8410):
SampleGroupColor (0x006A4DC0) reads the face's MOCV colour and
SplitLightColor splits it (directional floor 0xA8, ambient cap 0x60); a
day face blends both toward the sun by the colour's alpha. Every linked
group adds its MOLT lights through AddMapLight (GatherMapObjectLights
0x006A79C0), so torches light the actors near them. The actor is placed
again when its translation moved a squared 0.001 or more (0x00801360),
when its model changed, or when a new group of the WMO was made.

The light (World::ActorLight, the actor model's new lighting callback)
mirrors ApplyMapLighting (0x006A7300): an interior actor gets the WMO fog,
the ambient bytes and the directional bytes along the fixed indoor
direction (0x00CA816C, blended toward the sun's by a day face); a sun-lit
one the frame's light and fog; both then their map lights. The scene light
is the sun throughout. Without a WMO the callback is the frame's own, as
before.

The doodads' map lights move to a per-group list on the backdrop, shared
with the actors, and the interior light slots to one helper.

Not mirrored: AnimateMapEntityLight's ramp (0x0069E770), so the light
changes at once. A model with an M2 parent is not placed.

* docs: ModelScene WMO backdrops, scene sounds and actor:PlaySound

docs/API.md gains the WMO backdrop methods (SetWorldModel,
SetWorldModelByMapID, ClearWorldModel), SetPlayWorldModelSounds /
GetPlayWorldModelSounds, a Scene sounds section on hearing a scene from
its camera, and actor:PlaySound. SetWorldModel covers the props, their
fade, and the light the WMO gives the actors. SetPlayAnimationSounds and
PlaySpellVisual now say where their sounds play. README lists the new
methods.

* feat(model): ModelScene shadows and footsteps on the WMO floor

Actors in a WMO scene now stand on the WMO the way 1.12.1 places a unit.
A unit's world entity is made with factory flags 0 (CGObject_C::CreateNode
0x00613E10 -> 0x00670DB0), so it lacks +0x90 bit 0x2000 (flag bit 3,
0x00670E9C) and ReattachEntity 0x006A86D0 sends it to AttachEntityToGround
0x006A8A20, not PlaceEntity 0x006A8C10 (game objects), which the actor
light mirrored before. Place now follows the unit's path: the probe starts
at the model's collision box centre through its matrix (UpdateNode
0x00613F80, GetCollisionBox 0x00713700) and finds the nearest group face
1000 yards down, else up past the sphere (TraceMapObjectsNearest 0x006A8840:
SegmentHitsGroupBox 0x006A47E0, IntersectSegment 0x006B92B0 mask 4). Only
that group links the actor and adds its MOLT lights. SetEntityLightFlags
picks the sun or interior, TraceGroupFace 0x006A2600 finds the face and
GetFaceTerrainType 0x006A26C0 its material's terrain type.

Footsteps and the death thud use that terrain type when the scene has no
SetGroundTerrain (the unit's +0xC60).

SetShadowShown on a WMO scene lays the blob as the world's decal.
DrawBlobShadow 0x006D7920 is mirrored up to DrawDecal: the box from 5/3 of
the height below the feet to 1 above it (0xCEA610 / 0xCEA60C, ThirdOf
0x006D6E50), the texture matrix, white with the model's alpha, depth
function 1 when shadowBias is 0. DrawDecal's world reads are replaced:
BuildDecalTransforms 0x006D6FA0 runs in its absolute mode, because the
other mode reads the world camera (null at the glue screen), and is moved
to the eye. DrawDecalBatches 0x006D7480 is mirrored with the WMO's own
facets (TestMapObjectBox 0x006AD330 -> CollectBoxFacets 0x006A3B10, mask
0x2F0122) and the engine's vertex, index and draw calls
(0x006D7810, 0x006D78A0, 0x0058A830). A scene without a WMO keeps the flat
quad.

The engine's queries take a map object def but read only its placement
(+0x94), inverse (+0xD4) and object (+0x118); the backdrop keeps a block
with those three.

actor:StopSpellVisual() (an extension) interrupts the casts still being
prepared, the drop a new cast already did (0x0060D1C0 stops the old
spell's kits). Without it a precast that ended after a death played its
cast animation over the death.

* feat(model): ModelScene ranged shots (Auto Shot) and actor ammo

1.12.1 builds a ranged shot from the shooter, not from the spell. Auto
Shot (75) has no SpellVisual; UnitGetSpellVisual (0x0060D450) fills a
ranged spell's (Attributes 0x2) empty visual fields (the precast, cast and
impact kits, the missile flag and model, path, attachment, flight sound
and precast sound) from the SpellVisual of the ranged item's
ItemDisplayInfo (+0x28). A bow's (visual 5) gives LoadBow, AttackBow and
the arrow whoosh 4222. PlaySpellVisual now builds that 64-byte visual per
cast from the actor's ranged lane (INVTYPE_RANGED, THROWN or RANGEDRIGHT),
so it no longer needs the spell to have a visual of its own.

The arrow is the ammo. SMSG_SPELL_START / GO carry an ammo display for a
ranged spell; the launcher (CGUnit_C::LaunchSpellMissile 0x0060A3D0) makes
the missile from the visual's +0x1C when it is at least 1, else from the
ammo through CreateLooseItemModel (0x00479F40, the record's second model
and texture in the body model's scene), else the error cube, and draws a
missile launched during a rifle animation at alpha 0. The launch needs the
visual's missile flag or an ammo display (0x006E8A50). The ammo follows
the server's rule: a thrown weapon is its own ammo; a bow, crossbow or gun
shoots the actor's ammo, else what the server gives an NPC (5996 Rough
Arrow, 5998 Light Shot).

actor:TryOn(ammoItemID) (an extension) sets that ammo. The dress-up
worker refuses INVTYPE_AMMO, so the actor takes it before the worker's
dispatch; Outfit::ArmOf stays the worker's mirror. The held lane's byte 1
is now named subclass (UNIT_VIRTUAL_ITEM_INFO's layout).

$BWR releases a queued missile as the unit's model event does
(0x00600159): from the body's attachment 35 during a bow animation
(IsBowAnimation 0x005FCFB0), 36 during a rifle animation (IsRifleAnimation
0x005FCFD0), else from the event's point.

Not mirrored yet: BowPull and the nocked ammo on $BWP, the bowstring,
arrows stuck in the target, and drawing the ranged weapon at the shot.

* docs: ModelScene floor shadows and footsteps, ranged shots, StopSpellVisual

API.md documents what the last three commits added to ModelScene actors:

- actor:StopSpellVisual(), which interrupts the spells an actor still
  prepares (a cast already made, and its missile, go on).
- actor:PlaySpellVisual for ranged spells: the ranged weapon gives what
  the spell's visual lacks (all of Auto Shot's), the actor's ammo is the
  missile (a plain arrow or bullet without one, a thrown weapon throws
  itself), bullets do not show in flight.
- actor:TryOn of arrows and bullets as the actor's ammo.
- actor:SetShadowShown on a WMO floor: it follows slopes and steps and
  fades with height; no floor, no shadow.
- scene:SetGroundTerrain and actor:SetPlayAnimationSounds: without a set
  ground, the WMO floor under an actor picks its footstep and death thud
  sounds.
- scene:SetWorldModel: only the lights of the part an actor stands on
  light it, and the floor picks its sounds and takes its shadow.

README lists :StopSpellVisual with the other actor methods.

* feat(model): ModelScene WMO group liquid and camera fog

A scene's WMO now draws the liquids of its groups and fogs as the world
fogs a WMO around its camera.

Liquid: the world's group liquid pass (DrawGroupLiquidPass 0x00684CD0)
sets matrix 8 to the placement moved by the camera, commits a lighting
record with fog and calls DrawMapObjectGroupLiquid (0x006B4060). The
scene does the same for each parsed group with flag 0x1000, after its
opaque list and before its translucent one, as the world draws the pass
between its model lists. The engine's drawer gives the animated frames
(0x0068AAC0), the magma scroll and, with BuildGroupDepthRamp (0x006B6B60)
first, the water's depth ramp. A group whose first liquid type is past 8
is not drawn: type 0xF asks GetLiquidFrame for a frame past its table.
The parity flag is 1, the value every group gets from outside the portal
walk (RunGroupCallback 0x006B4160), so all tiles draw.

Camera fog: each scene update traces 1760 down from the scene's camera
as ClaimCameraMapObject (0x006821F0) traces from the world's: the nearest
floor of the groups, then CrossPortals (0x006A3F80) with the fraction
1.05, and no claim for a group whose MOGI flags have 0x8.
GetCameraInteriorFog (0x0069DE20) is mirrored for the claim (it reads the
world camera's globals): record 0 blended with the first group's
candidate fogs, farthest first, by the engine's LightFalloff (0x0069E1C0)
and LerpFogRecord (0x0069EFD0). BuildSceneFog (0x006CEE30) gives the
rest: the target's end is capped at the far clip, the weight moves 0.25
a second (0x008115B0) toward 1 while the camera is over an interior
group and toward 0 otherwise, and the drawn fog is the scene's fog
moved toward the target by it. The WMO, its interior doodads and the
interior actors take the drawn fog (ApplyMapObjectFog 0x006C31E0). This
replaces the fixed record 0 fog. The first update takes the weight as
it stands; the camera's own liquid is not asked.

* docs: ModelScene WMO liquid and camera fog

SetWorldModel: the WMO's own fog holds while the camera is above an
indoor part, fades in and out over 4 seconds, blends nearby fog zones,
comes in from the far clip in a scene without fog, and does not change
for a camera in liquid. The WMO's water, lava and slime show and
animate; outdoor water takes the colors of the player's zone.

* feat(model): ModelScene actors draw the bow and nock the ammo

An actor that casts a ranged spell now poses with its ranged weapon as a
unit does.

At the spell's start (HandleSpellStart 0x006E78A1, for Attributes 0x2 or
the auto-repeat flag), SetAmmoDisplay (0x0060BA30) is mirrored: the ammo
in hand is made with CreateLooseItemModel (kind 0x19 for a thrown
ranged item) and nocked at attachment 35 when the bow is already drawn.

$BWP (OnCombatModelEvent 0x006247D0) with a ranged spell under way runs
PlayBowPull (0x00624CC0): the weapon model, the item AttachItemModel
hung in its lane's hand (attachment 1 or 2), plays 160 BowPull at its
sequence length over the time left in the body's animation, from the
key bone state (hi - ftol(position / speed) - lo; nothing with the latch
set). The ammo then goes on the string unless a gun or crossbow shoots,
and the bow is drawn. $BWR with a missile waiting plays 0 on the weapon
for a bow animation and 161 BowRelease for a rifle one, then takes the
ammo off. EndRangedPose (0x0060F530) runs where the engine runs it, at
the missile release and when an interrupt drops a precast: the bow is no
longer drawn, the ammo leaves the hand and the weapon stands unless it
plays 161.

The models carry $BWP only in 105 LoadBow, so the precast's load must
not repeat. The sequence-end handler's ranged cases (0x005FC3F0) are
mirrored for kit animations: 105 goes on to 109 HoldBow and 106 to 110,
always, and a hold replays while the weapon is held and the spell still
prepares, so a long precast draws once and holds.

* fix(model): ModelScene spell animations do not play over a death

A unit without health plays only death animations: CGUnit_C::
PlayAnimation (0x005FE2F0) returns unless IsDeathAnimation (0x005FDA90,
__stdcall) holds for the animation. An actor had no such gate, so a
missile already in flight when the target died still played its wound
(and its impact kit's animation) on arrival and replaced the death
animation; StopSpellVisual only drops the casts still preparing.

An actor whose own animation is a death animation now takes no kit
animation over it, and setting a death drops the kit animation that
plays. The missiles still land and show their impact effects.

* feat(model): ModelScene arrows stick in their target

A missile shot from a bow, crossbow or thrown weapon now stays in the
actor it hits for 5 seconds, as a unit's does.

The launcher (0x0060A509) flags a ranged spell's missile when the ranged
item is a bow, crossbow or thrown weapon (0x0060A710: class 2, subclass
2, 18 or 16). Launch (0x0061CEB0) settles the target attachment: the
visual's, else 15, else 19, else none; Aim and the stick share that
choice. ArriveHit (0x0061DC50) with the flag, an attachment and a target
model runs StickInUnit (0x0061E7C0): the missile, snapped to the
destination with the turn of its flight (Arrive 0x0061E1D0), plays 191
Impact and is attached at the attachment, its base set to its world pose
times the inverse of GetAttachmentMatrix (0x00712DE0, scene space) at
the target's scale (InvertAffineMatrix). The target's stuck list frees
each one once its 5000 ms pass (object slot 14); a paused actor holds
them, and they go with its model. The wound and the impact kit play
first, as before.

The missile flies at one point, the attachment, as in the world: on a
large model such as Onyxia's (chest 34 at (2.77, 0, 4.20)) the arrows
all stick at that point inside the body.

* feat(model): ModelScene WMO fog follows the camera into liquid

The camera fog now asks the liquid around the camera as the world does.

CameraEnvironment (0x006809C0) probes at the camera's x and y and the
lowest z of the camera and the four near corners of its frustum (a
corner at or below the lowest, or NaN, replaces it); with the claim it
asks LiquidHeight (0x006B9F10) of the claim's first group in model
space, the type starting as 0xF. The scene keeps the drop below the eye
from the frustum volume its WMO draw builds.

BuildSceneFog (0x006CEE30) picks the target from it: water or ocean
take the underwater sub-record (+0x24); magma with fog flag 0x100 and
slime with 0x10 take it too and make the zone fog the target; magma or
slime without the flag take the zone fog as the target. GetCameraInteriorFog
now blends both sub-records and keeps the flags of record 0 or of the
nearest candidate. With the camera in liquid the paint draws the WMO's
liquids after the translucent models, as the frame does (0x004836D6).

Not mirrored: the zone fog the camera's liquid makes the target changes
only the WMO, its doodads and the indoor actors, not every model; a
scene has no terrain, so outside the WMO the camera is always dry.

* feat(model): ModelScene actors draw the ranged weapon and dual wield

A ranged or auto-repeat spell's start now sets the caster's sheathe
state 2 at once, as HandleSpellStart (0x006E78F3) does through
SetSheatheState (0x00611CF0, (2, 1, 1)): the ranged lane hangs in its
hand and the other held item at its sheath point. A unit that is not
the active player keeps state 2 through its later animations
(0x005FDF80 asks for 2 again), so the actor keeps it until SetSheathed,
SetModelByUnit or a new model. Every re-hang (SetSheathed, the sheathe
categories, a try-on) honours it per lane, so a sheathed bow now comes
to hand for the shot and BowPull finds it there.

An actor that shows a creature display or a model file now holds two
one-hand weapons. DressUpModel's TryOnItem asks the active player's
dual-wield skill (0x005EAB70) only when it shows that player and
refuses a second one-hander on any other model; the world draws a
creature's two weapons regardless. An actor that shows a unit keeps the
dressing room's rule.

* docs: ModelScene ranged pose, stuck arrows, camera liquid fog

PlaySpellVisual: the ranged weapon comes to hand at the spell's start;
the arrow in hand, the draw and the release; instant shots do not draw;
arrows and thrown weapons stay in the target for 5 seconds; no spell
animation plays over a death animation. StopSpellVisual lowers a drawn
bow. TryOn: an actor without a unit holds two one-hand weapons.
SetWorldModel: the camera in the WMO's water takes its underwater fog,
in lava or slime the scene's fog unless the WMO has one for it.

* feat(model): ModelScene WMO light eases and lights spell models

An actor's light in the scene's WMO now changes the way a 1.12.1 unit's
entity light does. AnimateMapEntityLight (0x0069E770) moves each byte of
the ambient toward its target by max(1, trunc(2.0 x dt x 255)) per tick.
It moves the intensity, which scales the directional light in
ApplyMapLighting (0x006A7300), by 3.3333 x dt. The bake
(BakeMapEntityGroupLight 0x0069E4C0) writes the ambient target, not the
ambient. The target intensity is 1.0 indoors and 2.5 (0x00810A68) on an
exterior group. A new node starts at 1.0 with the day ambient
(0x00670DB0). Outside, with no channel moving, the ambient follows the
day's. World::Settle now takes the frame's elapsed time and eases each
tick, and places the node again only when the model moved.

A missile in flight gets its own entity light node, as the world gives
one (CreateLightObjectB 0x00671010 from 0x0061E655, placed by
AttachEntityToGround). Impact models left behind get one too. Each model
releases its callback back to the frame's before the light goes.

LightChildren now copies the parent model's own lighting callback pair
(+0x3BC / +0x3C0), so a nocked arrow and a stuck missile are lit like
the actor that holds them, not with the frame's flat light.

* fix(model): ModelScene casts keep their pose through a wound

A wound or an impact animation on a casting actor replaced the precast's
looping animation, and when it ended the actor went back to its script
animation: the hands dropped while the precast glow went on, or a
cowering pose showed through a later cast. A 1.12.1 unit replays its
spell's looping kit animation after a one-shot ends. The actor now keeps
the precast's loop under a one-shot and plays it again when the one-shot
ends. The loop ends with the precast, a death, a new model or a script
animation.

The anim-done callback also took the end of any key bone's track as the
end of the actor's animation, so a finger track ending mid-cast restarted
a loop or cut a cast short. It now makes the character pane's test
(0x005062A0, the same as the unit's 0x005FCA28): only the body track
(key bone -1 or the root, 26) ends the animation. Another bone's track
is stopped when it ends, except HandsClosed (15), which keeps a weapon's
grip.

* fix(model): ModelScene missile landing does not end the next precast

A mage's Fireball is still in flight when the next cast's precast
begins. When the missile landed, its finished cast was dropped through
EndPrecast, which also ends the caster's looping precast animation. That
loop now belonged to the newer cast, so the caster's hands fell to its
sides while the precast glow went on, and the cast threw normally at its
end. A cast ends its own precast once, when its cast phase starts, so
dropping a cast now ends the precast only while the cast still prepares.

* feat(model): ModelScene bows draw their string

A 1.12.1 bow's string is not part of its model. RefreshRangedWeaponModel
(0x00611E10) gives the ranged model of a bow (class 2, subclass 2) the
draw callback DrawBowstring (0x00611FF0) through SetDrawCallback
(0x00710DB0), with the unit as its user data, and sets a null callback
before it closes that model. The M2 draw runs the callback as one of the
model's elements. It draws two lines in the lighting record's colour
from the bow's $WTT event to its $WTB event: through the body's
attachment 35 while the bow is drawn (+0xD58 bit 0x4000, set by $BWP),
else through their midpoint.

The callback reads only the unit's model (+0xD8) and that bit, so an
actor keeps a block shaped like those two unit fields and hands it to
the engine's own DrawBowstring. Each update the actor finds the bow in
its ranged lane where the lane hangs it, in the hand or at the sheath
point the weapon trail's lookup gives (GetSheathAttachment 0x0047A070,
then FindChild), holds a reference on it, and strings it. A bow no
longer hung, or a released model, is unstrung first. The drawn bit
follows the actor's bow pull and release.

* feat(model): ModelScene actors hold a ranged weapon in its own slot

A 1.12.1 unit holds its ranged weapon apart from its two hands: hand 2 of
the held-lane and display virtuals, inventory slot 18, its model at
+0xD24. The model is hung only in the ranged sheathe state.
ApplySheatheChange (0x00611770) entering state 2 moves the melee items to
their sheath points, then RefreshRangedWeaponModel (0x00611E10, arg 0)
empties attachments 1, 2 and 0 and hangs the weapon in hand through
AttachItemModel with body slot 0x11: attachment 1 for INVTYPE_RANGEDRIGHT
and THROWN, else 2. Leaving state 2 for 0 detaches attachment 35 and the
weapon's hand, then opens that hand (OpenHand 0x004796B0); for 1,
RefreshRangedWeaponModel(1) hangs it at its sheath point, which a bow or
gun does not have. Outside state 2 the weapon shows nowhere.

Actors now do the same, as a ClassicAPI extension (retail has no ranged
slot). TryOn puts every bow, gun, crossbow, wand and thrown weapon in the
ranged slot, whatever hand is named, so a hunter can hold two melee
weapons and a bow. A ranged spell draws the weapon (DrawRanged);
SetSheathed puts it away (SheatheRanged). SetModelByUnit reads the unit's
hand 2 (Outfit::ReadRanged), and UndressSlot, DressPlayerSlot,
IsSlotAllowed and the transmog lists know slot 18. Shots, ammo, the bow
pull, stuck missiles and the bowstring use the ranged slot. A bow in it
is strung when hung, and the callback is cleared before its reference
goes, as RefreshRangedWeaponModel does. DressUpModel is unchanged.

* docs: ModelScene ranged slot, bowstring, eased WMO light

TryOn puts ranged weapons in slot 18; the ranged weapon shows only while
the actor shoots, in the hand the world uses. The slot methods, the
transmog lists, SetSheathed, SetSheathedCategory and PlaySpellVisual say
so. A bow has a string. An actor's light in a WMO changes over a short
time, and missiles and impact effects take the light of their place.

* feat(model): ModelScene outdoor WMO water takes its map's light

A 1.12.1 WMO's exterior water colours its vertices from the world's light
table: the deep river colour (colour band 17, table +0x40) in
DrawGroupLiquid's exterior arm, and the river alphas (LightParams columns
5 and 6, +0x68 / +0x6C) that BuildGroupDepthRamp (0x006B6B60) ramps
between. BuildLightTable (0x006D2260) makes that table each frame at the
camera from the current map's light list (0x006D6170: the map's Light
rows, slot 0 the one at the origin, else Light id 1): slot 0 gathered at
the half-minute of the day (GatherLightRecord 0x006D64D0 on the
LightParams of reference 0, or 1 under water), then each area light the
eye is inside of blended in farthest first by its falloff
(BlendAreaLights 0x006D2D00, OverblendLightRecord 0x006D30E0); in magma
LightParams 7, in slime 6. A scene's WMO showed the player's zone.

The backdrop now knows its map: SetWorldModelByMapID's, or a new
optional mapID argument to SetWorldModel. With one, the scene builds
that map's table at its own camera through the engine's gather and blend
(the storm blend, which follows the player's weather, is left out) and
puts its three water fields into the world's table only while its
liquids draw, then puts the world's back.

* fix(model): ModelScene WMOs no longer draw pink outside their own fog

A WMO's exterior group drawer (0x006B4F10), and the interior one too,
turns the device fog on for every material without flag 0x2 and keeps
the fog range the device holds: the world always commits a fog
(M2LightingSetDeviceLights 0x0071C730) just before. A scene without fog,
outside a WMO's own fog, committed a record with none, which turns the
fog off and leaves the range alone, so the drawers fogged with the
device's starting state (0x00593BF0): 0 to 1.0, in 0xFFFF0080. Every
exterior surface past a yard drew solid pink: Onyxia's Lair from
outside, all of Stormwind.

After the commit, a scene without fog now sets the device fog range from
the far clip to 1e10, the fog end of a world without light (the
immediate at 0x006D2301), under a render-state scope around the WMO's
draw and its liquids' draw: the drawers' fog then covers nothing the
scene draws, as its models show none.

* docs: ModelScene SetWorldModel mapID and outdoor water light

SetWorldModel takes an optional mapID: with it, the WMO's outdoor water
takes that map's light at the camera and the world's time of day, with
the nearby zone lights blended in; without it, the light where the
player is. SetWorldModelByMapID's water takes its map's light.

* feat(model): ModelScene TraceSegment and a sound listener actor

scene:TraceSegment(start, end) returns the first face of the scene's WMO
on a segment: the hit point, the face's unit normal turned toward the
start, and the fraction. It is the scene's per-group trace (Nearest,
TraceMapObjectsNearest 0x006A8840 over the one WMO) with face mask 4,
which CMapObjGroup::IntersectSegment (0x006B92B0) widens to 0x84: every
face but the detail faces, the set the world's line of sight and the mover
test (class 0x100111 builds the same mask). The normal is crossed from the
hit triangle as CMapObj::IntersectSegment (0x006A37B0) reads it: facet
batch 0's first three indices into its vertices, read right after the
group's call, then turned into scene space by the placement. Only loaded
groups answer. The class word moves to Offsets.h as WORLD_TRACE_CLASS_LOS,
which LineOfSight.cpp used as a local constant.

scene:SetSoundListenerActor(actor) hears the scene's sounds at an actor.
The world's listener (0x00482EA0) stands at the unit the player drives
while SoundListenerAtCharacter is on: its position raised by scale times
box height (+0x90 * +0xBC), facing the unit's facing with z 0, up
(0, 0, 1); otherwise at the camera. The scene mirrors both branches, with
the listener actor in place of the unit and the scene camera in place of
the world's.

* feat(model): ModelScene TraceSegment camera face set

TraceSegment takes an optional camera flag that traces the faces the
world's camera collides with. The camera solver (0x0050E570) traces with
class 0x100171, whose mask builder (0x006A3839) gives face mask 0x82:
detail faces block it and the no-camera-collision faces (MOPY 0x02) do
not, where the line-of-sight set (0x84) is the other way round. The flag
passes mask 2 to CMapObjGroup::IntersectSegment (0x006B92B0) in place of
4; the call ORs in the visited bit.

With it an orbit camera can do the solver's boom sweep: trace from the
target toward the eye and stop 1/9 yard (0x00808A04) short of the hit.

* feat(model): ModelScene GetLiquidAtPoint

scene:GetLiquidAtPoint(x, y, z) returns the liquid of the scene's WMO at
a point, its type (0 water, 1 ocean, 2 magma, 3 slime) and the height of
its surface, found the way the world finds a unit's. The group is the one
whose face lies nearest below the point, the probe AttachEntityToGround
(0x006A8A20) runs from a unit; CMapObjGroup::LiquidHeight (0x006B9F10)
then answers at the point in WMO space. It reads the MLIQ tile under the
point and answers only below the surface (water 0.01 above it); a group
whose MOGP liquid word is set answers that type everywhere with FLT_MAX,
returned as a nil surface. The type is masked with 3, as the camera's fog
reads the same answer, and the surface goes back to scene space through
the placement.

With it a scene can run the client's swim decision (0x006030C0): swim
once the surface stands more than 0.75 of the collision height over the
feet, stop below that less 1/36 yard.

* feat(model): ModelScene SweepCollider on the client's contact sweep

scene:SweepCollider(feetX, feetY, feetZ, radius, height, moveX, moveY,
moveZ) sweeps a body to its first contact with the scene's WMO and
returns where its feet stop and the normal of the facet it met. It is a
ClassicAPI extension.

The sweep is the client mover's own, transcribed in SceneContact.cpp
one function at a time: CMovement::SweepVolume 0x00632BA0, with the
volume's planes and vertices (0x00631440, 0x00631BE0), the polygon clip
and its 1/720 band (0x006318C0, 0x00631870, 0x00632980), the swept face
prisms (0x00632460, 0x00632F80, PlaneFromTriangle 0x00637480), the
contact distance (0x006329E0, 0x00632830), the nearest facet per face
(0x00632700), the bevel faces and the band rule (0x00632280), and the
facet gather with its cached box (0x00631E70). The arithmetic keeps the
client's 53-bit sums, float stores and operand order, so a body meets a
face where the client's mover would. The body is the client's volume:
a square box over a downward point at the feet, sides at 61.6 degrees.

The facets come from the same WMO box query as the decals (CollectBox,
TestMapObjectBox 0x006AD330, class 0x100111), read out of the facet
batches up to each batch's triangle count (+0x16, the loop bound of the
facet emitter 0x00671CC0). Each facet is built as that emitter builds
it on its SSE path: the vertices through the batch matrix, the normal
(v1 - v0) x (v2 - v0) scaled by rsqrtss, d = -n.v0. So a face blocks
only from its front, as in the world.

Safety: nothing here calls or patches the client's mover. Its facet
lists (0x00C4E52C, 0x00C4E564) and cached box (0x00C4E5A0) are never
read or written; the sweep keeps its own list and box per call. The
swimmer and hover branches of 0x00632BA0 are not taken, since a scene
body has neither flag.

* feat(model): ModelScene actors move with the client's mover

actor:SetMovementEnabled(true) gives a scene actor the client's own
mover: it walks and runs over the scene's WMO, slides along walls, steps
up and down ledges, falls and jumps as a character does. The commands
StartMovingForward/Backward, StopMoving, StartStrafingLeft/Right,
StopStrafing, StartTurningLeft/Right, StopTurning and Jump, and
IsFalling, are ClassicAPI extensions.

SceneMover.cpp transcribes CMovement for a scene body, one client
function per function, with the client's 53-bit sums and float stores:
- the tick (0x00616800, 0x00616620; a 250 ms window), the integrator
  (0x00616DE0, 0x00616CB0), the displacement from the anchors
  (0x007C5360, straight line 0x007C4ED0, turn arc 0x007C52C0), the
  facing (0x007C4F30), the heading basis and direction (0x007C5880,
  0x007C5A20), the anchors (0x007C5CD0) and the speed (0x007C4C90);
- the substep loop 0x00634040 and its swept query 0x00633840;
- the walk resolver 0x006367B0 with the face rise 0x00635C00, the wall
  push-out 0x00635D80, the bevel direction 0x00636610, the triangle
  class tests (0x006333D0, 0x006334A0, 0x006336A0, 0x00633720), the step
  probe 0x00636100 and the fall-away lookahead 0x00635F80;
- the fall step 0x00635B00 and the airborne resolver 0x00635600 with its
  step sweep 0x006351A0, step time 0x00635450, wall push 0x00635090 and
  wall normal 0x00634AE0 (three-plane solve 0x00634FC0 over the 3x3
  determinant and inverse 0x007BE0E0, 0x007BE2A0);
- the fall arc (0x007C5D20 to 0x007C6290: distance, time for a drop,
  apex, start, jump at -7.955547, landing, the far-fall latch 0x00633240,
  the deferred direction latches 0x0061AB20) and the movement commands
  (0x007C6AE0 to 0x007C6DD0, position reset 0x007C69A0, facing
  0x007C6F30, fall gate 0x007C61C0).
Two places follow the binary over benilla-re's transcription: the
fall-away lookahead starts a real fall and sweeps (+0x68, +0x6C, -D)
(0x00635FF7, 0x00636014), and stopping runs the fall gate only on a
step edge, flag 0x4000000 (0x007C6BBD).

The body's box is the one the client gives a unit of the actor's
display (CGUnit_C::UpdateCollisionSize 0x0060B270): CreatureModelData
collision width +0x38 and height +0x3C, now in Offsets.h, at the larger
of the actor's scale and the display's CreatureModelScale. The facets
come from the scene's WMO through World::QueryFacets, which fails before
the WMO has loaded, so the body waits. PointOverFacet (0x006335D0) joins
the contact sweep.

Safety: the client's movers, their manager, its lists (0x00C4E52C) and
its cached box are never read or written; transports, splines, the
event queue, packets, hover and pitch are left out. The substep loops
carry a pass cap the client lacks, so a fault in the port cannot hang
the game. Swimming (the free-move resolver 0x00634640) is not ported.

* feat(model): ModelScene actors swim with the client's mover

A moving actor now swims in the scene WMO's liquids, through the
client's own swim path, transcribed in its order and precision.

The decision is CGUnit_C::UpdateSwimState (0x006030C0), run after each
tick as OnMoverStepped (0x005FAC70) runs it: the depth is the liquid
surface (World::LiquidAt) less the feet's z. The body starts swimming
deeper than 0.75 of its height unless IsRising (0x007C5DE0) holds, and
stops out of liquid or below 0.75 h - 1/36. Swimming on is EnterSwim
(0x007C6E50 with the latches 0x0061AB20), as the active mover's request
applies it; off is 0x007C6E80, which levels the pitch and starts a fall.

A swimmer resolves through the free-move resolver (0x00634640) and its
slide (0x00634300): no gravity, no steps, the solid list swept first and,
until a solid facet stops it, the liquid list for the rest; it re-anchors
at each end but a failed sweep, as the client does. The swept query
(0x00633840) takes its swim box about the move's midpoint (0x00633B5E)
and, for a swimmer, the liquid list in the same box. The contact gather
(0x00631E70) refills that list too, and a sweep of it uses 0.75 of the
height (0x00632C64), so the swimmer meets the surface as a ceiling with
its head above it. The liquid planes are reversed as 0x00633E90 and
0x006320E0 reverse them.

The liquid facets come from the client's own per-group liquid gather:
World::QueryLiquidFacets walks the groups whose MOGI bounds touch the box,
as CollectBoxLiquid (0x006A3C20) does, and for each loaded one resets the
batches and calls CollectLiquidBox (0x006BB170) with the swimmer's class
0x30000 (water and ocean, not magma or slime), then the facet emitter.
Nothing is patched; the client's lists and cached box are not touched.

The pitch: the rate (0x007C5C90), its integration and +-pi/2 clamp
(0x007C4F80), the pitch arc (0x007C5180) and the turn and pitch arc
(0x007C4FD0) with their clamp climb, and every displacement mode of
0x007C5360. Commands StartPitch (0x007C6DF0, only while swimming) and
StopPitch (0x007C6E30). A swimmer moving forward or back is posed by
2pi less its pitch about its y axis, as the unit pose (0x00608560,
0x0060A110) feeds the euler builder 0x007BF4B0; the actor's rotate about
y (0x007BDD60) has the same sense.

New actor methods: StartPitchingUp, StartPitchingDown, StopPitching and
IsSwimming. SetMovementEnabled's description covers swimming and the
pitch.

* feat(model): ModelScene doodads are solid to moving actors

A scene's WMO doodads now block the mover and SweepCollider as the
world's doodads block a character.

The facet query follows the world gather for a map object
(GatherMapObjectFacets 0x006AAAB0) over the scene's one WMO: the
placement's box (CMapObj::GetBoundingBox 0x006A4420 through the
placement) must touch the query box; then the group faces as before;
then each group, in index order as CreateGroupDefs (0x00695960) links
them, whose MOGI bounds through the placement touch the box gives its
doodads by GatherDoodadFacets' rules (0x006ABC40): each doodad once per
query (the s_mapQueryId stamp, advanced by GatherWorldFacets 0x006AA8B0),
its collision box (+0x14C) tested closed. A group not yet parsed or a
doodad whose model file has not loaded fails the query, as in the
client, and the facets gathered so far stay in the list.

The doodad's facets transcribe CM2Model::GatherCollisionFacets
(0x007137C0) into our own code, so the client's facet list and the
model's vertex caches are not touched: the M2 collision mesh (shared
data +0xF0 to +0x100) through the doodad's matrix (0x007BCA80, the same
arithmetic as our 0x007BCC60 transform), a triangle kept unless all
three vertices lie past one face of the box, its plane from the mesh
normal turned by the matrix rows normalized above 2^-22, d = -n.v0.

A doodad's bounds now follow SetDoodadDefBounds (0x006952A0) and are set
when its model file loads (0x007103D0 with 0, 0, as the pending-def
finish 0x00698C50 sets the def's loaded bit): the sphere and the
collision box (0x00713700) through TransformBox (0x006DC540). A shared
doodad sits in each of its groups' lists, as CreateGroupDoodadDef
(0x00694E90) returns the existing def.

* feat(model): ModelScene moving actors turn their body as a unit does

A moving actor's model is now drawn at a body facing that follows the
mover's, through the body pass of CGUnit_C::Update (0x00607ED0), while
the actor's yaw stays the mover's facing.

The actor is the active mover, so its display facing (+0xC98) is the
mover's own (UpdateDisplayFacing 0x00600CD0), with the turning bit 0x1
and the time it last stood still (+0xCB0). The world's camera sets these
at the render (MakeViewAngles 0x0050F7A1), after the units' update, so
the body pass reads the ones the last frame set, and the actor keeps
that order: body pass, then display.

The body facing (+0xC94): a swimmer's is the display's; strafing aims a
quarter turn aside, an eighth when also moving forward or back, the side
by strafe direction and backing up, and closes a quarter of the gap each
frame; moving straight or falling snaps it. Past a quarter turn the body
follows at once, and standing, not turning, it catches up at eight times
the turn rate over the time since the display stood still. Each wrap is
WrapAngleToPi (0x006084F0). The rest turns key bones 4 and 6 about z,
half then what remains, an eighth of a turn each at most, through
SetKeyBoneFlags (0x00711F10), BuildAxisRotation4x4 (0x007BDB00) and
SetKeyBoneOverride (0x00712B00); the bones are marked when the model
loads, as OnModelLoaded (0x0060CE70) marks them with HasKeyBone
(0x00711D20), and touched only on a loaded model. A rider leaves bone 4
to its mount. Turning the mover off clears the overrides.

The shuffle animations the pass would pick standing (11, 12) are the
script's, as the actor's animation is.

* feat(model): ModelScene draws the world's sky behind its WMO

A scene with a WMO backdrop now clears its frame and draws its sky as
DrawWorldScene (0x00681070) does before its terrain and map objects:

- No interior group holds the camera and the camera is dry: clear to
  black (mask 3), then DrawSky (0x006D4940). The pass draws the stars,
  the sun disc, the white moon, moon02, the gradient dome, the clouds
  and the skybox slots, in the depth range [0.975, 0.98] of the device
  viewport, around the eye. The scene's view has no translation, as the
  world's has none, so the same pass fits.
- An interior group holds the camera: clear to the drawn fog's colour
  (light state +0x80) and draw no sky. Under liquid outside: the zone
  fog's colour.

The pass draws the world's sky objects, which BuildLightTable
(0x006D2260, from 0x006D4530 each world frame) makes from the world's
camera and light. The scene makes the light-derived parts again, as the
build makes them, then puts the world's back:

- the light state's heading (+0x30) from the scene camera's forward:
  atan2(y, x), or atan2(z, x) when x*x + y*y is not above the double
  0.0001 (0x00811658), plus the float 2pi (0x0080295C) below 0;
- for a backdrop in a map, that map's light at the scene camera
  (BuildMapLight, as the outdoor water already takes it) in the live
  table (0x00CE9C0C), with no screen tint (+0x44, the player's) and the
  override and slots (+0x54..+0x6B) cleared;
- the dome's colours (ColourSkyDome 0x006D0F50, 5 x columns + 2 at
  [0x00CE99A0+0x14]);
- colour band 9 (record +0x20) into the sun disc and white moon
  (0x00CE9858, +0x0C, 0x20 apart);
- the skybox slots (0x006D2C79): each {LightSkybox id, weight} pair at
  record +0x78 with an id, a weight above 0 and an id below the
  LightSkybox count (0x00CE9DB4) interns its row's path (InternSkybox
  0x006D4640) into slot +0x5C, weight +0x64. A null row, which the
  engine would read through, is skipped.

The pass runs only while the sky flag (+0x198) is set and the dome has
its colours, so a scene at the glue screen keeps a plain clear. World
stack 8 is identity around the pass and the render states are pushed.

The camera claim (ClaimCameraMapObject 0x006821F0) now runs for every
WMO, not only for those with their own fog. The world claims the camera
whatever the fog, and its liquid probe reads the claim.

Not done: the cloud texture stays the world's, because the world builds
it a band at a time from its own light. From inside, the world also
draws the sky when its portal walk (WalkPortals 0x006B41C0) reaches an
exterior group; the scene does not. The sun and moon glares (0x006D48C0)
are not drawn.

* feat(model): ModelScene draws the sky through a WMO's portals

From inside a WMO, the 1.12.1 world draws the sky only when its portal
walk (WalkPortals 0x006B41C0) from the camera's groups reaches an
exterior group: the walk sets the weather byte 0x00CA80C4 for a group
flagged 0x148, and DrawWorldScene (0x00681070) then clears to black and
runs DrawSky. With the byte clear it clears to the drawn fog colour. A
group flagged 0x40000 also puts the WMO's MOSB name into the skybox
state 0x00CA8080, which DrawWorldScene loads into skybox slot 0 at the
camera's WMO fog weight (SetSkyboxSlot 0x006D4810).

The scene now runs the same walks for its WMO from its own camera:

- Inside, the interior seed's (0x006B3B20) walk: a new pass
  (0x00CA8014), the group fog flag set, the liquid-group state cleared,
  object-to-clip = the world stack's slot (0x0058B280) times the
  device's view-projection (0x0058B0C0), and the camera point in model
  space; each claimed group walks over (-1,-1,1,1) at depth 0, passing
  itself as its interior group unless it is flagged 0x48. The backdrop
  now keeps the claimed group indices, not only a flag.
- Outside, the exterior seed's (0x006B3DD0) walk from each MOGI group
  flagged 0x8 and not 0x10000 whose box the view volume does not cull
  (0x00682F60), which can still name a skybox.

Safety: WalkPortals runs with a null group callback (0x00CDE5B0) and
the inside leg (0x00CDE5AC) clear, so it links nothing into the world's
frame and records no windows into the world's 16-entry window array.
Every global it reads or writes (callback, inside leg, camera point,
object-to-clip, fog flag, liquid seen/parity, weather byte, skybox
state) is saved before the walk and restored after it.

The world's second pass, which walks the WMO again through each
recorded window, is not run: it can only name a skybox that the first
walk did not reach, since the weather byte is already set by then.

* feat(model): ModelScene walks a WMO again through its windows

The 1.12.1 interior seed (0x006B3B20) walks in two phases. The first
walk from the camera's groups runs with the inside leg (0x00CDE5AC)
set, so WalkPortals (0x006B41C0) records a window for each portal into
an exterior group it crosses: five floats at 0x00CBE324 + 0x14 * i, the
overlap rectangle mapped to [0, 1] and the portal's reach, counted at
0x00CBE320. The second phase clears the inside leg and, for each
window, builds the window's volume (BuildPortalVolume 0x00682930,
__fastcall(corners, rect), plain ret) and walks from every MOGI group
flagged 0x8 and not 0x10000 whose box that volume shows (0x00682F60),
over the window as (2r - 1). That walk can reach an exterior group that
no portal joins to the camera's groups, and so a group flagged 0x40000
that puts the WMO's MOSB skybox into the skybox state.

The scene now runs both phases from its own camera. The exterior seed
(0x006B3DD0) builds its volume the same way from the rectangle
(0, 0, 1, 1), so the outside walk shares the same code.

BuildPortalVolume lerps the camera corner rays at 0x00C7BCD8, which the
world fills from its own camera (FUN_FRUSTUM_CORNERS at 0x00680E3C);
the call at 0x006B3CA4 passes them in ecx and the record in edx. The
scene writes its own camera's corners there for the walk, from the
same corner builder.

Safety: the corner rays, the window count and the 16 window records
(0x006B37B0 constructs 16) are saved before the walk and restored
after it, with the globals the first walk already kept. The seed's
last loop (RunGroupCallback 0x006B4160 for 0x10000 groups) changes
only the liquid state and calls the callback, which is null here, so
it is not run.

* feat(model): ModelScene actors play a unit's movement animations

An actor with the mover on now picks and plays its animations as the
1.12.1 client does for a unit from its own mover. The chain lives on
CGUnit_C, which an actor is not, so model/SceneLocomotion.cpp is that
chain on the actor:

- The pick, SelectBaseAnimation (0x005FD8B0, mask -1), for what a scene
  body can claim: the airborne hold (falling far, or a fall with a
  start speed that is not 0 or NaN), ResolveMoveAnimation (0x005FD100:
  swim 41 to 45, back 13, sprint 143 from 11 yd/s at 0x0080C484, run 5
  above twice the walk speed, else walk 4), ResolveShuffleAnimation
  (0x005FD3F0) behind CanShuffle (0x005FCE30), and the idle
  (0x005FD830: 41 swimming, else 0, nothing while JumpEnd's +0xD58 0x4
  lock holds).
- The play, CGUnit_C::PlayAnimation (0x005FE2F0): a move animation
  (IsMoveAnimation 0x005FEE80) at GetCurrentSpeed (0x007C4C90) over the
  sequence's speed (GetSequenceInfo 0x00711A20 +0x08), starting at the
  phase of the move animation it replaces, in the client's 32-bit
  arithmetic (the imul and two divs at 0x005FE606); and nothing when
  the track already plays it (PlayTrack 0x005FDBA0).
- The triggers. Each movement command the mover takes animates its
  message, as UpdatePlayerMovement (0x00615C30) sends it through
  ProcessLocalMoveEvent (0x0060E0A0) to AnimateMoveOpcode (0x0060E480):
  starts end the ranged pose and pick, a jump plays 37, stops and turns
  pick. The swim decision's start and stop, and a position reset
  (MSG_MOVE_TELEPORT_ACK), pick too. A new Body::stepped hook runs where
  the substep loop (0x00634040) calls BroadcastStateChange (0x0061A820),
  with the flags before the substep and its jump test: a landing runs
  UpdateLandingAnimation (0x00602C60: 39 standing, 187 ahead or aside
  after a jump or far fall), a fall start or far fall runs
  PlayFallAnimation (0x00602C40), a swim's end picks. The body pass's
  tail (CGUnit_C::Update after 0x006083E6) sets the 0x800 / 0x1000
  shuffle bits from the turn it made and picks when the shuffle should
  start or end. A finished sequence plays PlayFollowOnAnimation's
  (0x005FC3F0) follow-on: 37 and 38 go to 38, 40 to 40, the rest pick.

The gate's animation sets are the engine's own (IsEmoteAnimation
0x005FCED0, IsSpellCastAnimation 0x005FCBB0, IsThrownAnimation
0x005FCF90, IsBowAnimation, IsRifleAnimation), all `int __fastcall(int)`
with a plain ret, read from the bytes. EndRangedPose (0x0060F530) moves
out of the cast module's private namespace for the move starts.

Left out, as an actor has no unit state: the death, special stand,
loot, cast, ready, ranged, stand state and emote resolvers, stealth,
splines and the walk mode. A spell kit's animation stays on top of the
pick, and an actor whose own animation is a death animation is left to
its script.

* feat(model): ModelScene casts report when they reach their target

actor:PlaySpellVisual now returns a cast ID (nil when the spell has no
visual, the actor shows no model or the target is in another scene),
and the caster's new OnSpellVisualImpact script runs with (spellID,
target, castID) when the cast reaches its target. A game can apply a
spell's result at the moment its impact shows, without timing the
flight itself.

The moment is the one the scene's cast chain already plays the impact
at, which follows the 1.12.1 client: a missile's arrival (the frame
whose step passes the remaining distance, as CMissile's update at
0x0061E3E8 tests it, then ArriveHit 0x0061DC50), or the cast itself for
a spell with no missile, a speed of 0, or the caster as target (the
immediate impact 0x006E8BF0). A spell interrupted while it prepares
(StopSpellVisual, or a new cast ending the precast) never arrives, so
its script does not run.

Safety: Impact only queues the event in Actor::spellImpacts. The actor's
update runs the scripts after Casts::Update has stepped every cast, from
a moved-out copy of the queue. A handler that casts or stops a spell
then changes spellCasts outside the step that iterates it (and holds a
reference into it), and an impact it causes waits for the next update.
The script slot is the seventh of the eight an animation object has
(a static_assert holds the list to Animation::kMaxScripts).

docs/API.md describes the cast ID and the script, with an example.

* feat(model): ModelScene actors walk to a point along the client's spline

actor:MoveTo(x, y, z [, facing]) moves an actor with the mover on as a
server's SMSG_MONSTER_MOVE moves a unit, through our own copy of the
1.12.1 client's spline path. The live movers are not touched.

The mover side (SceneMover.cpp), one client function each:
- CGUnit_C::OnMonsterMove 0x006018F0: the ground path from where the body
  stands (a lone point within 1/36 yd is dropped; AnchorSplinePath
  0x006021C0 leaves a path that starts at the body as it is), the guard
  points (0x00601E66 to 0x00601ECA), the length (0x00601EF4), the speed
  capped at 4x the run speed (0x00601F3D) and the fistp duration of at
  least 1 ms (0x00601F9F). A path of 1/6 yd or less stops the body where
  it stands (FlushAndStopSpline 0x00618750). The duration the scene sends
  is the path at the body's own swim, walk or run speed.
- StartSplinePath 0x006187A0: StopAllMotion 0x0061AA70, InitSpline
  0x007C62C0, StartSpline 0x007C6A50 (run mode from spline flag 0x100,
  then StartMove), the final angle (SetSplineFacingAngle 0x006188A0).
- The curve in mode 0 (straight chords by arc length): the segment
  locator 0x00453840, the chord point 0x004541B0 and length 0x00454320,
  the totals 0x004543D0 / 0x00453920, the frame 0x00453480 / 0x00454580.
- FollowSpline 0x007C5490 (progress by fild/fidiv, facing by fpatan, the
  swimmer's pitch by asin), the warp gate GetSplineStep 0x00616AF0 (past
  3 yd or 60 yd/s the point is taken without collision), and SnapIfFar
  0x00616D60 after the substeps (0x00616DE0).
- The arrival in BroadcastStateChange 0x0061A820: stop, snap, final
  facing, CompleteSpline 0x00619DE0. The substep loop 0x00634040 skips
  its speed test while a spline is live, and GetCurrentSpeed 0x007C4C90
  gives the spline's length over its duration.

The actor is the client's active mover, so a finished spline is reported
(CMSG 0x2C9) and freed. That report is the actor's new OnMoveFinished
script. The script plays the server's part, so every other movement
command, SetYaw, SetPosition and the new SetWalking end the move first
(ClearSpline 0x007C6310, as UpdatePlayerMovement 0x00615C30 does for a
move event that is not the player's own). SetWalking / IsWalking set the
run mode (SetRunMode 0x007C71C0); a moving actor re-picks its animation
on the change (MSG_MOVE_SET_RUN_MODE / WALK_MODE in AnimateMoveOpcode
0x0060E480). The arrival plays MSG_MOVE_STOP's pick, and the swim end is
not sent along a spline.

Left out: flying splines (flag 0x200), facing a point or a target at the
end, and the precast clear (UnitClearPrecastSpell 0x0060D040), which an
actor's casts have no part for.

* docs(model): document ModelScene movement, traces, liquids and listener

API.md gets the scene functions that had no entry: TraceSegment (with
its camera faces), GetLiquidAtPoint, SweepCollider and
SetSoundListenerActor / GetSoundListenerActor. Scene sounds now names the
listener actor.

It also gets the actor's movement: SetMovementEnabled /
IsMovementEnabled (the WMO it moves on, a character's speeds, the body
size from the creature display, the drop to the floor, and the
position, yaw, tilt and animations that follow the movement), a table of
the movement commands and their applied result, IsFalling, IsSwimming,
MoveTo with a two-point patrol on OnMoveFinished, and SetWalking /
IsWalking. The actor scripts table gains OnSpellVisualImpact and
OnMoveFinished.

The README's model scene summary and its ModelScene and ModelSceneActor
rows list the same names.

* refactor(model): call the engine's math and read its constants live

The ModelScene mover and contact sweep carried their own copies of engine
code and data. They now use the client's.

Constants: every float the transcribed mover reads from 1.12.1's .rdata
(and the two fall-speed caps in .data, the 2pi the static initializer
fills at 0x00CF5D00) is an Offsets.h entry read where it is used, through
Game::Live<T>. Each value was checked against WoW.exe's bytes. The pooled
floats other modules already named for one use (0x00801360, 0x008026BC,
0x008029D4, 0x00803568, 0x008022CC, 0x00801620, 0x0080306C, 0x00801628)
are renamed by value, since the mover reads them too.

Leaf math: the pure geometry helpers the mover calls are now called, not
copied: DotVector3 0x00602630, PlaneFromTriangle 0x00637480,
PlaneDistanceAlongRay 0x006329E0, ClipPolygonByPlane(s/Except) 0x006318C0
/ 0x00631870 / 0x00632980, IntersectThreePlanes 0x00634FC0 and
PointToLineDistanceSquared 0x00634F40. Each is __fastcall with callee
cleanup and reads only its arguments and .rdata (Ghidra). Two stay
transcribed: FindNearestTriangleEdge 0x00634DA0 reads the client's facet
list at 0x00C4E534, and SelectBevelContactNormal 0x00636610 reads an
unwritten stack slot as an index when three bevels have no odd one out.

Wrappers: engine calls that several files cast themselves get one typed
home: M2.h (key-bone animation state, sequence info, base transform,
scene draw, model lights, the IsXAnimation tests, whose death test is
__stdcall and the rest __fastcall), gx/Matrix.h (the 0x007BxXXX matrix
helpers), gx/Device.h (render-state journal, state setters, transform
stacks, clear), Frame::Layout (DDC/NDC conversion), Texture::DeviceTexture,
Xml::ReadColor and Frame::Subclass's slot types.

* refactor(model): share the compositor calls and call WrapAngleToPi

Outfit declared its own casts of the character compositor's create,
clone, unequip-slot and set-item calls (FUN_CHARCOMP_*), which
DisplayInfo also casts. They are now DisplayInfo's NewDresser,
CloneDresser, UnequipDresserSlot and SetDresserItem, beside the pump and
destroy it already exported.

The actor's body-turn pass copied WrapAngleToPi (0x006084F0). That
function is `double __stdcall(float)`, ret 4, and reads only .rdata and
the CRT's fmod (Ghidra), so the pass calls it; the pi and 2pi constants
it was copied with leave Offsets.h.

Also drops VAR_MOVER_MINUS_SKIN, unused since ClipPolygonByPlane is
called, and two unused locals in Cooldown's AnimateVerts.

* feat(model): FollowCamera, an orbit camera that follows an actor

A camera type in the camera registry, built on OrbitCameraMixin. Its
target is an actor's position plus a height, set each frame before the
orbit camera's own update.

The eye is placed as the world's follow camera places it: the boom
sweep of the solver at 0x0050E570. The sweep is skipped when the
distance is not past the near clip by more than 2^-20 (0x008026BC).
Otherwise a trace of the camera's faces from the target to the eye
(scene:TraceSegment with camera set, the ray query of 0x0050E816)
shortens the distance. A distance shortened by more than 2^-22
(0x008029D4) backs off by 1/9 yard (0x00808A00, 0x0050E871 to
0x0050E8A4), never below 0. The vertical probe and the near box clip
of the solver are left out. The game gives the pivot height.

With no actor to follow, it is a plain orbit camera.

* feat(model): FollowCamera takes the world camera's pivot height

actor:GetCameraPivotHeight(distance) gives the height the world's
follow camera eases to for a unit, read from the actor's model as
CCamera::BuildPivotHeights (0x0050CA90) reads a unit's. The camera's
target setter (0x0050D0F0) rebuilds the presets every frame once the
model has loaded, so the actor's are read at each call:

- base: the unposed offset of attachment 17 (GetAttachmentOffset
  0x00712CF0) plus 7/72 yard (0x00808AB0), or 0.9 (0x00804588) of the
  collision box (0x00713700), times the scale;
- near: lowered by the stand-state animation's sequence bounds top
  under Stand's (0x0050CDDF on);
- swimming: lowered the same way by Swim (42) when the model has both
  (0x0050CCE3 on);
- each kept from 5/6 (0x008089CC) to 15 (0x008089C8).

ArmPivotHeight (0x0050F880) picks swimming for a swimmer, else near
under 1.8315 yards of target distance (0x008089B0), else far. The
constants are read live. An actor has no stand state: the animation it
plays stands in when it is one the jump table at 0x0050D0CC gives, and
cameraHeightIgnoreStandState (its CVar* at 0x00BE0CF4, stored at
0x0050BD9E) ignores it. A mount is left out. Until the model has
loaded the method returns nothing and the camera waits, as the world's
update does (0x0050E900).

FollowCamera drops its height argument and eases to that height as the
camera's height channel does: the first one is taken at once
(BeginHeightTransition 0x00512790), each new one is armed
(ArmHeight 0x005126B0) for |change| / cameraHeightSmoothSpeed seconds
and eased with the cosine curve of 0x0050F160.

M2 gains HasAnimation, GetCollisionBox and GetAttachmentOffset
wrappers; SceneSpell and SceneWorld use them in place of their local
function pointers.

* docs(model): document FollowCamera and GetCameraPivotHeight

API.md gets a Follow camera section (SetFollowActor / GetFollowActor,
the pivot, the smooth height change at cameraHeightSmoothSpeed, the stop
in front of walls, the wait for the model, and how to add the camera to
a ModelSceneMixinTemplate scene) and an actor:GetCameraPivotHeight
entry (the mouth or collision-box base, the stance animations near the
actor, the swim drop, the 5/6 to 15 yard range). README lists both.

* feat(model): scene:GetCursorRay, the world frame's pick ray

The world frame builds its pick ray in ScreenPointToRay (0x004813B0,
called by PickAtCursor 0x00481190): the cursor's fractions across and
up its rect, then UnprojectScreenPoint (0x007AD2C0), which reads the
device view and projection, builds the frustum corners and interpolates
the near and far planes, then the camera's eye added to both points
because the view leaves it out.

The scene does the same with the transforms it paints with: the cursor's
fractions across the paint's viewport (the frame's rect clamped to the
screen), CameraTransforms (the camera's CameraSetDeviceTransforms
0x007ADA40, fitted to the view insets) under SavedTransforms,
UnprojectScreenPoint, then the scene camera's eye. It returns the two
points in scene coordinates, or nothing when the cursor is off the
picture or the frame is hidden.

The world traces that ray with class 0x1000114, whose WMO face mask
(0x006A3839) is 0x84, the mask TraceSegment uses by default, and which
skips doodads as TraceSegment does. So GetCursorRay into TraceSegment is
the world's point pick on a scene.

CursorClip becomes CursorFraction (0 to 1) so both pick paths share it;
GetActorAtCursor maps the fractions into clip space itself, the same
arithmetic as before. Offsets.h gains FUN_UNPROJECT_SCREEN_POINT and
gx/Device.h a wrapper for it.

* docs(model): document scene:GetCursorRay

API.md gets a GetCursorRay entry (the two points, when it returns
nothing, and how TraceSegment finds the WMO point under the cursor, with
a right-click move example). README lists it.

* feat(model): scene:GetActorsInRadius, the nearest-unit collector's test

scene:GetActorsInRadius(x, y, z, radius) returns a table of the scene's
actors near a point, nearest first. It applies the test of the 1.12.1
client's nearest-unit collector (0x00494200, the enumeration callback
behind TargetNearestEnemy and its kin) to the scene's own actor list:

- A unit counts only when its scene node is drawn (0x006704C0: node not
  null and +0x94 clear). The scene's counterpart is a shown actor with
  a model; scene info actors without one (scene 4's "unwrapped",
  "wrapped", "player-rider") do not count.
- The distance is the squared difference of the two positions in all
  three axes, kept when it is not more than the squared radius
  (0x0049435B..0x0049436B: fcompp, test ah,0x41).
- The list is sorted by squared distance ascending, as the collector's
  compare (0x00494450) orders entries of one kind; ties keep creation
  order (stable sort).

Pure reads of the actor vector and positions; no engine call, no state
change.

* docs(model): document scene:GetActorsInRadius

* feat(model): the scene clock, GetSceneTime and scene timers

A ModelScene's M2 scene already keeps a clock: uint32 milliseconds at
scene +0x0C, which SetTime (0x00707490) stores and M2SceneAdvance
(0x007074B0) moves forward. The Model frame's update (slot 14,
0x0076D7F0) advances it by the truncated milliseconds of each frame.
SetPaused already skips that advance, and a hidden frame does not
update, so this is the clock every actor animates by, and it stands
still exactly when they do.

- scene:GetSceneTime() returns the seconds that clock has run since the
  frame was made. OnFrameUpdate reads +0x0C before and after the base
  update and adds the uint32 difference, so the sum starts at 0 and
  never wraps. OFF_M2SCENE_TIME added to Offsets.h.
- scene:After / NewTimer / NewTicker are C_Timer's contract on that
  clock. They share C_Timer's queue, cancel handles and registry
  callbacks: each entry now has an owner (null for C_Timer). The scene
  fires its own entries from OnFrameUpdate right after the clock moves,
  before the actors update. Its destructor drops them (CancelOwned).
  C_Timer's WorldTick fires only owner-null entries, and its next-
  deadline early-out now covers only those. The argument checks of the
  three C_Timer functions moved into the shared Time::Timer::Script.
- SetPaused's descriptor is unchanged; GetSceneTime and the three timer
  methods have descriptors marked as ClassicAPI extensions.

* docs(model): document the scene clock and scene timers

* feat(model): actor highlight, selection circle and the move marker

Three things the 1.12.1 world draws for units, now on scene actors.

actor:SetHighlight(kind, highlighted) / IsHighlighted([kind]) keep the
two light bits of a unit: "target" is bit 0 and "mouseover" bit 1, as
SetLight (0x614550) and ClearLight (0x6144F0) use them. Setting a bit
gives the model the emissive colour through 0x710D40 (__thiscall(model,
float rgb[3])). The world takes it from the ambient band of the light
state; the scene takes it from the scene light's ambient, the light that
stands in for the sun. Clearing makes the model black only when no bit
is left, as ClearLight does. A new model gets the glow again.

actor:SetSelectionCircle(r, g, b [, a]) / ClearSelectionCircle /
GetSelectionCircle replay CGUnit_C::DrawSelectionCircle (0x608E00).
The radius is the one 0x60AEE0 computes at model load (sqrt of half the
xy diagonal of animation 0's bounds, the model bounds without it, 1.2
when flat) times the scale. The box is the feet +-(r, r, 2r). The yaw
matrix (0x615070) turns about z by minus HeadingBetweenPoints (0x47F220)
from the scene eye. The state is SetSelectionCircleState (0x614E00).
The decal is fade 0.5 with flags 0x200122. It is drawn for each actor
before its shadow, as DrawEntityModels draws the circle before the blob.
It is gated by the ObjectSelectionCircle cvar.

scene:SetMoveMarker(x, y, z) / ClearMoveMarker / GetMoveMarker replay
the auto-move marker (0x611400): the box is the point +-s, s = min +
(max - min) * (sin(2pi t / period) + 1) / 2 on the OS clock, from the
static .data values at 0x860AE0..0x860AE8 (500 ms, 0.5, 0.75), colour
0xFFFFFF7F. It uses the same yaw matrix, state and decal.

With a WMO the decals land on its faces through DrawDecal (0x6D7330)'s
transforms and DrawDecalBatches (0x6D7480)'s states. Without one they
land on one flat quad at the feet. The shared decal code in
SceneWorld.cpp is split into WithDecalStates / WithDecalTransforms for
the two paths.

Fog: 0x614E00 turns off lighting (state 0xE), not fog. The world draws
these decals in the fog CWorld::SetFogState sets for the whole pass.
The scene paint has no fog of its own at that point, so the device's
default (0 to 1 in 0xFFFF0080) made every circle pink.
World::CommitDecalFog commits the scene's fog first: the WMO's lighting
record, as the WMO liquids get theirs, or the frame's light and fog
without a WMO.

The decal fade and flags move to Offsets.h, because the soft-target
circle uses them too.

* docs(model): document the actor highlight, selection circle and move marker

* feat(model): a paused scene stops movement and spell visuals too

scene:SetPaused stopped only what runs on the M2 scene clock (scene
+0x0C): the animations, GetSceneTime and the scene timers. The mover
ticked on the OS clock, as the client's does, and the casts stepped by
the frame's elapsed time. A paused scene therefore still moved its
actors in a frozen pose and flew its missiles.

The scene clock is the scene's world time, so the actors now run on
it:

- The mover (Mover::Init, Mover::Tick) and the body-facing stamps
  (the catch-up turn of 0x600CD0) read the scene clock through the new
  Model::Scene::ClockMs. The spline start (b.clock) stays in the same
  base. Mover::Tick does nothing for a zero window, so a paused scene
  holds every body. On unpause the body sees only the time the scene
  ran, so nothing jumps ahead.
- Actor::Update takes the ms the scene clock moved this frame, as
  seconds, for Casts::Update (precasts, missiles, impacts, stuck
  arrows). That is 0 while paused. OnUpdate keeps the frame's elapsed
  time.
- The move marker's pulse (0x611400's sine over 0x860AE0 ms) reads the
  scene clock where the world's reads the OS clock, so it holds too.

FUN_SIMPLEMODEL_GET_SCENE (0x76CFC0) makes the scene on first use, so
a scene frame always has a clock to read. A hidden scene runs no
update, so its clock and its actors stop as before.

* feat(model): names over scene actors, as the world draws a unit's

actor:SetNameText(text [, r, g, b]) / ClearNameText / GetNameText show
a name over the head. It is drawn the way the 1.12.1 world draws a
unit's name (PLAYERNAMEDESC::UpdatePlate, 0x6C6E90):

- It runs from the body model's draw callback, installed with
  SetDrawCallback (0x710DB0, list0 0) as the unit's is at 0x6C7756.
  It draws only when CM2Model::IsReady (0x710450), as
  PlayerNameDrawCallback (0x6C7780) checks.
- The plate scale is 0.2, or d / 4 * 1.5 * 0.2 above 4 yards, where d
  is the name height over the feet (0x6C6F10..0x6C6F3C, reading the
  constants at 0x8112A8, 0x8112AC and 0x80679C).
- The text is made with GxuFontCreateString (0x5C1C30) on the world's
  name font (0xCE8738), with the grammar pass (0x7716F0), a 100000 box,
  justification 2/1, flags 0xC8 and the colour. The block height is
  the extra lines times the scale.
- Each draw adds the string to the world's name batch (0xCE8734,
  0x5C1E60), places it at the name position raised by the block height
  (0x5C2770) and draws the batch (0x5C1EF0). A colour change alone goes
  to GxuStringSetColor (0x5C2750), as the colour refetch does.

A custom draw runs under the scene's rebased view with a zero offset
(0x70D96D). The paint gives the scene its eye as the origin, so the
callback places the name at its absolute scene position, as the world
does.

actor:GetNamePosition() mirrors CGUnit_C::GetNamePosition (0x608640).
It uses attachment 18 on the model. A seated rider counts as mounted,
so it uses attachment 29 on its mount's model. Without the attachment,
the point is 1.25 times the scaled box height above the feet.

The name font and batch exist only in the world: world entry makes them
(0x6C7470), and PlayerNameShutdown (0x6C7630) frees them in
ClientDestroyGame (0x40202F), before CGGameUI::ShutdownGame. Each actor
therefore keeps the font its string was made with, and frees the
string only while that font still exists. At the glue screens no name
draws.

* feat(model): actor movement speeds and spell ground areas

actor:SetMovementSpeed(speedType, speed) / GetMovementSpeed(speedType)
set the walk, run, run back, swim, swim back and turn speeds of an
actor's mover, as a server changes a creature's speed. The client's
spline speed opcodes (0x2FE to 0x303, switch 0x00601360) call the
CMovement setter at once: SetWalkSpeed 0x007C70D0, SetRunSpeed
0x007C7030, SetRunBackSpeed 0x007C7080, SetSwimSpeed 0x007C7120,
SetSwimBackSpeed 0x007C7170, SetTurnRate 0x007C6FF0. Each stores the
value unless it is within 2^-22 of the field ([0x008029D4]; a NaN
stores), re-anchors, and refreshes the current speed except for the
turn rate. Mover::SetSpeed mirrors that. The switch then calls
AnimateMoveOpcode (0x0060E480, nothing for these opcodes) and
UpdateBaseAnimation(-1) (0x005FD9E0), so the actor re-picks its
animation and rate (Locomotion::Repick). The setter leaves a spline
alone, so a MoveTo keeps the speed it started with. Speeds live on the
mover and go back to the defaults when the movement turns off, as the
walk mode does; a speed of 0 or less is a usage error.

actor:SetModelBySpellArea(spellID, radius) shows a spell's ground area
as the world shows a dynamic object (CGDynamicObject_C). The model is
the one slot 10 names (0x005D5890 -> 0x005D57C0): the spell's visual
(GetSpellVisual 0x006EC1E0) must have the area flag (+0x2C), and its
+0x30 SpellVisualEffectName row gives the file. Once loaded, the actor
runs the loaded hook (slot 13, 0x005D52F0): the scale is the radius
over the bounding-sphere radius when that is above 0.001 (the double at
0x00801608), else over the effect row's +0x10 size when that is above
0; a model with animation 158 and none for 0 loops 158, as the done
callback (0x005D5580) replays it. The area's model events follow the
dynamic object's (0x005D58C0): $SND plays its payload at the area,
always; $SHK shakes the world camera, which a scene does not have.
The area kit (+0x34: the kind-9 shard emitter and the looping sound)
is not part of this yet.

* feat(model): the area kit of a spell ground area: shards and loop

An actor that shows a spell's ground area (SetModelBySpellArea) now
runs the area kit, as the world's dynamic object starts it when it is
created (CGDynamicObject_C, 0x005D55C0) and stops it when it is
deactivated or destroyed. Nothing new is exposed to Lua.

The kit is the visual's +0x34 SpellVisualKit, read only with the area
flag +0x2C set. Its first kind-9 procedure (cmp at 0x005D5640) starts
the shard emitter (0x006ECE30 -> 0x006EB930): the shard file is the
type's entry in the char *[7] at 0x00870E24 (the low byte of the bits
of the procedure's first value + 512.0, shifted right 14; read there
with no bound, here bounded), and the rate is the procedure's second
value (+0x5C), scaled by the spell detail record [0x00CEE9A8] +0x28:
x0.33 at 0 ([0x00808300]), x0.66 at 1 ([0x0081199C]).

Each update the emitter adds the scene seconds times the rate and
spawns a shard per whole 1.0 (0x006EBAD0). A shard mirrors 0x006EBB64
to 0x006EBDA9: a draw u in [0, 1) and a unit vector from the client's
own random state (0x004531E0 and 0x0044FD00 on 0x00882664), a point
u * radius out and 16.666666 up ([0x00810E20]), a trace to it from
1/6 over the centre that keeps 0.95 of a hit's fraction ([0x008119A0]),
then a trace 33.333332 down ([0x0080FEE4]) whose hit is the shard's
place, else the area's centre. The traces are the scene WMO's
(World::Trace); without a WMO the shard lands at the area's height.
The shard's model plays its animation once after 2 * b ms, b the byte
of a draw * 255.0 + 512.0, and the done callback's natural end (reason
0, 0x006EBE70) frees it; every fourth event of the shards plays when
it is a $SND (0x006EBE30). The scene clock times them, so they hold
while the scene is paused, and they play out after the area goes.

The kit's sound (+0x34) loops at the area and stops with the 3.0 fade
of 0x005D56D0; a hidden scene silences it and the next update loops it
again.

The entity-light helpers (LightAsEntity, ReleaseLit, SettleLight) move
from SceneSpell.cpp to Scene.h so the shards light as missiles do.

* feat(model): ground-target reticles on actors; quiet areas when paused

actor:SetGroundReticle(radius [, valid]) / ClearGroundReticle() /
GetGroundReticle() show the world's ground-target reticle at the
actor's position. The world draws one at the pointer while a spell
waits for a ground position (WorldFrame, 0x004837B0, the path without
a placement model); any actor can show one here, so a scene can mark
several spots, and an actor with no model serves as a marker.

The recipe is the world's: the box is the point +- the radius in x and
y and +- 2.0 ([0x00801628]) in z, a radius of 0 taking 1.3888889
(0x3FB1C71C, 0x00483858); inside a state push, lighting (0xE) and depth
write (0x12) off and blend 2; the in-range or out-of-range texture at
stage 0x17 (0x00B4B344 / 0x00B4B348, Spell-Shadow-Acceptable and
-Unacceptable, loaded when the world frame is built at 0x00481C00,
bound through 0x0044ACF0); then DrawDecal (0x006D7330) in white, with
no texture matrix and fade 0.5, onto the receiver class 0x200122. The
world draws it after the opaque models and before the water and the
translucent models (0x004836B0), in its fog; the scene draws it after
M2 pass 0, in the scene's fog (World::CommitDecalFog), or flat at the
actor's height without a WMO. The liquid pass (class 0xF0000) is not
mirrored. Before the world frame exists the textures are null and no
reticle draws.

A spell area's loop sound went on while the scene was paused: the
paused scene still runs each actor's update with no time, which the
area kit took for running. The world has no pause; here a paused scene
(SetPaused) or actor silences the loop, which starts again when the
pause ends. The shards already held, on the scene clock.

* feat(model): chain-lightning bolts on scene casts; quiet missiles when paused; docs

The 1.12.1 client draws Chain Lightning's arcs from a spell visual kit
procedure of kind 0 or 12 (0x0060D7FC, through the byte table at
0x0060DC20 to 0x006ECB90). The procedure's values decode, as the area kit
does (bits of value + 512.0, shifted right 14), to a SpellChainEffects id,
a strand count capped at 3 (0x006ECC65) and a persistent flag. Chain
Lightning's cast kit 321 has kind 12, chain 1, one strand; row 1 of
SpellChainEffects.dbc is segment 2.78, width 0.5, jitter 0.04, texture
period 1.0, life 1000 ms, Textures\SpellChainEffects\Lightning.blp.

Each hop of the world's LightningObject gets a bolt from the client's
lightning renderer (Lightning.cpp, a 32-byte __thiscall object): Init
0x007B0760, Destroy 0x007B0780, CreateBolt 0x007B07F0 (ret 0x2C),
MoveBolt 0x007B0950, ShowBolt 0x007B0BD0, DestroyBolt 0x007B0AC0, Update
0x007B0A40 and Render 0x007B0A80. The hop update (0x006EC460) creates the
bolt with the row's shape, then moves it between its ends each frame; the
caster's end is its $CSL event point, else its position raised by 0.75 of
its height (0x006EC6F0), and the target's is the attachment the spell
visual's +0x24 names, else its position (0x006EC780).

A scene now owns one renderer and drives it through those functions
(model/SceneChain.cpp). A scene cast has one target, so a chain is one hop
from the caster to the target, timed on the scene clock for the row's
life, hidden while either actor is hidden. The bolts update after the
actors and draw after the translucent models. The per-bolt draw
(0x007AFCB0) pushes and pops its render states and restores the device
view and the transforms it changes, so the frames drawn after the scene
are not affected. The kit-byte decode is shared with the area emitter as
Model::Scene::DecodeKitByte.

The world has no pause, so a missile's flight loop ran on through a paused
scene. A paused scene or caster now stops the loop at once, and the loop
starts again from the spell visual's missile sound when the pause ends; a
hidden scene's missiles get their sound back the same way.

docs/API.md gains the scene actor methods of this branch that had no
entry: actor:SetModelBySpellArea, actor:SetGroundReticle /
ClearGroundReticle / GetGroundReticle and actor:SetMovementSpeed /
GetMovementSpeed, with the chain bolts and the paused sounds in the
PlaySpellVisual, scene:SetPaused and actor:SetPaused entries.

* feat(model): actor:KnockBack, the client's knockback launch on scene actors

A 1.12.1 server knocks a unit back with SMSG_MOVE_KNOCK_BACK (0xEF, to
its controller) or MSG_MOVE_KNOCK_BACK (0xF1, relayed): a direction
pair, a horizontal speed and a vertical speed that the server negates
into the client's down-positive fall speed. Both paths end in the same
launch on the unit's CMovement, 0x006179C0: swimming ends (0x007C6E80),
a fall starts at the vertical speed (0x007C61F0, which re-anchors with
the old flags), the direction pair overwrites the heading +0x68 and the
direction +0x5C with 0 in z, flag 0x2 clears and 0x8001 sets whatever
the speeds, and the horizontal speed goes to +0x84. Nothing about the
unit refuses it. The direction is world-absolute.

Mover::KnockBack transcribes that launch on a scene body. While the body
falls, the direction is not recomputed (0x007C5A20 returns early), so the
flight keeps its line; the 0x8000 latch, now named FLAG_STOP_ON_LAND,
makes the landing stop the move (ApplyLatches 0x0061AB20), as it does a
knocked-back character's.

actor:KnockBack(fromX, fromY, horizontalSpeed, verticalSpeed) stands in
for the server's KnockBackFrom: the direction from the point to the
actor, or the facing turned half a circle (the client's pi, 0x0081052C)
on the point itself, and the actor's preparing spells stop, as the
server interrupts non-melee spells. As every move event that is not the
player's own, it ends a MoveTo first (ClearSpline). The acknowledgement's
animation follows: AnimateMoveOpcode (0x0060E480) plays 40, Fall, for
0xF0 (0x0060E4FC, PlayAnimation 0x005FE2F0 with 0x28). A dead actor keeps
its death animation, so a corpse flies in its death pose.

docs/API.md documents the method next to MoveTo.

* feat(model): actor:FadeOut, the world's model fade; dead actors lie Dead

When the 1.12.1 client removes an object (deactivate 0x006145E0), it
hands the model to FadeOutModel (0x00672DF0) at its current alpha. A
ready model (0x00710450 with 0, 0) at an alpha of 0.01 or more, or NaN
(fcomp [0x008029D0] at 0x00672E21, test ah,5 / jnp), is kept with the
time and that alpha; any other is released at once. Each frame the pass
0x00672EF0 shows (3 - 2x)x^2 with x = (1 - age x 0.0005) x the alpha,
held to 0..1 (0x00672FD3 to 0x00673025, 3.0 at 0x0080297C), and releases
the model when the age passes 2000 ms (cmp eax,0x7D0; jle at 0x00672F36).

actor:FadeOut applies that curve on top of the actor's alpha in
ApplyAlpha and hides the actor where the world releases the model; an
actor below 0.01 or with no ready model hides at once. The world times
the fade with the OS tick; here it runs on the scene clock, so a paused
scene holds it. Show, Hide and SetShown end it. actor:IsFadingOut
reports it. The 0.0005 is the mover's VAR_MOVER_STALL, named again as
VAR_MODEL_FADE_RATE where FadeOutModel reads it.

A unit's death in the world ends in a hold: PlayFollowOnAnimation
(0x005FC3F0) sends Death (1) and Dead (6) through its byte table
0x005FC848 to 0x005FC52D, and Drown (131) and Drowned (132) to
0x005FC573. While the unit is dead (0x00605F90), each plays Dead or
Drowned through 0x007121A0 in the variation the ended sequence played
(GetKeyBoneAnimState 0x00711FE0); otherwise it picks again. Locomotion's
FollowOn now has that arm for an actor with the mover, which is dead
while it plays a death animation, so it lies where it fell instead of
playing Death again. An actor without the mover repeats its animation,
as before.

docs/API.md documents FadeOut and IsFadingOut, and the death hold under
SetMovementEnabled.

* feat(addons): Broodwatch, a survivors game on the ModelScene backport

Broodwatch holds Onyxia's Lair against an endless brood: the lair is a
scene's WMO (scene:SetWorldModelByMapID(249)), the hero and every whelp
are actors with the client's mover, and spells, items and hits are the
client's own spell visuals. It doubles as a load test and a showcase for
the scene features it uses: MoveTo and SetMovementSpeed for the chase,
PlaySpellVisual with OnSpellVisualImpact for the spells, Chain
Lightning's bolts, SetModelBySpellArea and SetGroundReticle for the
ground areas, KnockBack for the explosions, FadeOut and the Dead hold for
the corpses, Project3DPointTo2D for the hit numbers and item icons, and
Cooldown frames and eased StatusBars for the HUD.

The addon lives at the repository's root AddOns/, outside src/embed, so
it is not embedded in the DLL; the client links to it with a junction
from Interface\AddOns\Broodwatch. /broodwatch starts a run.

The files share the addon table (local _, BW = ...): Data holds the
tuning, Core the shared state and helpers, then Brood, Spells, Hud and
Items, and Broodwatch.lua the run, the keys and the setup.

* feat(model): a kit's world effect on scene actors; lasting effects hold

A 1.12.1 SpellVisualKit has nine effect columns that hang on attachments
(+0x0C to +0x2C) and a tenth, +0x30, that the world plants on the
ground. PlayUnitSpellVisualKit (0x0060EDF0) makes a CEffect for it and
PlantEffect (0x0061FCF0) puts it at the unit's position (the unit's
vtable +0x14) or at the point it is given; with a spell that has a root
aura (26) in one of its three effects the effect gets flag 0x4000 and
follows the unit. Frost Nova's state kit 285 keeps its ice there
(Frost_Nova_state.mdx), so a frozen actor showed only the head glow.

A scene actor's kit now plants that effect: a model of its own in the
scene at the actor's position, lit as an entity like the area shards
(LightAsEntity), shown and animated in the actor's link, placed in its
place pass, its light settled in its update, and released with the
kit. SetSpellVisualKit carries no spell, so the effect stays where it
was planted, as the world's does without flag 0x4000.

A lasting effect also ended up re-forming. The world gives a state
kit's effects (kind 2) KitEffectHoldCallback (0x005FF170): when the
first sequence ends cleanly, a model with animation 158, Hold, plays it
under KitEffectDecayCallback (0x005FF1D0), which plays Hold again until
the effect's end time; a state kit leaves that time at 0, so the effect
holds until its aura goes. Our kits used only the channel kits' loop
(KitEffectLoopCallback 0x0060ED00), which replays the first sequence.
A non-one-shot kit effect now holds Hold when its model has it and
replays its sequence otherwise, so Frost Nova's ice forms once and
stays, while a precast glow without Hold loops as before.

Animation 158 was named ANIM_DYNAMIC_OBJECT_LOOP for the ground areas'
use; it is ANIM_HOLD now, its AnimationData name, with both readers in
its comment. docs/API.md describes the ground effect and the hold under
SetSpellVisualKit.

* feat(broodwatch): eight new spells, rank V masteries, client names

New spells, tanky and fun, each on the scene features it shows off:
Power Word: Shield soaks the bites into a share of your health with its
bubble kit on; Thorns burns the biters each second; Frost Nova freezes
the brood around you in Frost Nova's ice (state kit 285); Psychic Scream
sends it fleeing under its terror kit; Demoralizing Shout softens its
bites; Stoneclaw Totem pulls it onto an earth totem with the Battle
Chicken's taunt; Blast Wave hurls it away with KnockBack; and Summon Imp
brings an imp that follows you and casts the real Firebolt. Brood.lua
gains the holds, fears and weaknesses (Hold, Fear, Weaken, UpdateStates)
with their kits, and elites shrug off half of a hold or a fear.

At rank V every spell masters and does something new: Frostbite,
Shadowburn, Overload, leaps that grow, Corruption that amplifies, Echo,
dazes, an Aftershock, a totem's eruption, Deep Freeze, a second Rain of
Fire, Consecration that follows you, a shield that bursts, Thorns that
heals, Shatter, Terror, a battle cry, a Stoneclaw stun and two imp
bolts. A new spell's card teases its mastery; the rank V card names it.

The level-up cards grow to their text (GetStringHeight) and hang below
the hint, all three at the tallest one's height, so nothing is cut off.
Spell names and the passives named after a spell come from
C_Spell.GetSpellName, and the items from the Item mixin by their real
item IDs, so the client's language shows.

* feat(model): channels, ground-point casts, and a lasting kit's loop sound

Channels. A 1.12.1 spell channels when AttributesEx (+0x1C) has a bit of
0x44. After its cast the server sets UNIT_CHANNEL_SPELL and the client
plays the visual's +0x14 channel kit as a lasting (kind 2) kit
(0x00612A30): its effects hold, its animation is the unit's while it
channels (0x00612990), and its chain procedures (kinds 0 and 12) draw the
beam to the channel object, which a persistent chain (value3) keeps until
0x0060D1C0 ends the channel. PlaySpellVisual now takes a channelTimeMs
after the cast time and adds a Channel phase: the kit lasts the given time,
else the spell's duration from GetSpellDuration (0x006EA000, unmodified),
forever for an endless one. The lightning renderer never expires a bolt
on its own, so a channel's hops are held by its cast ID and Chains::End
drops them. StopSpellVisual takes an optional castID to end one cast.

A lasting kit's loop. The kit player (0x0060EDF0) asks GetSoundDefFlag200
(0x00458830) about the kit's sound; a lasting kit (kinds 2 to 4) whose
sound has the bit plays it as an effect sound, a 3D loop that follows the
unit (AddEffectSound 0x0061FEC0) and stops with the effect (CEffect::Stop
0x006203E0, Sound::Stop2 over 0.15 s). Every channel kit's sound has it,
so Drain Life's drone now lasts the beam rather than its file. A lasting
kit records the loop animation it set and gives the caster's loop back
only while it still owns it, so a newer kit's loop is not cut short.

Ground points. actor:PlaySpellVisualAtPoint(spellID, x, y, z [, castTimeMs
[, channelTimeMs]]) casts at a point of the scene. At the go a visual with
no missile (+0x18 is 0) and a +0x30 model plants that model at the target
block's destination (0x006E8088 to 0x006E8143: a 0x90-byte CEffect built
by 0x0061F490 and placed by PlantEffect 0x0061FCF0), turned by the
caster's facing and scaled by its scale (0x00620A90). It plays its
sequence once; EffectDoneCallback (0x005FBF50) then stops it, hidden while
its particles finish, and the dying list (0x0061F680) frees it once none
lives. Its $SND events play at the event's point and $HIT wounds the
caster, the effect's target (0x0061F6F0). No impact kit plays: the instant
impact returns on an empty hit list (0x006E8BF0). A visual with a missile
flies one missile to the point (0x006E8A50, masks 0x20 and 0x40) and
leaves its +0x30 impact model there. Inferno (1122) is the first user: its
infernal_impact_base meteor. OnSpellVisualImpact runs with a nil target.

* feat(broodwatch): Drain Life, Mind Flay, Inferno, and a steeper late game

Two channels on PlaySpellVisual's channel phase: Drain Life holds its
green beam on the toughest enemy and heals you each second, and its
mastery leaps the beam to the next enemy when the target dies; Mind Flay
flays and slows the toughest enemy in range, and at rank V each tick also
flays the enemies around it. A beam ends with StopSpellVisual(castID) when
its target dies or slips out of reach.

Inferno, on PlaySpellVisualAtPoint: the meteor falls on the thickest pack,
burns it and stuns it for 2 s (Inferno Effect 22703) with the stun swirl
(state kit 349), and an Infernal (display 169) stands in the crater,
rooted for 1.7 s as the server roots it (22707). Then it hunts the
nearest whelp, and its Immolation burns the whelps around it each second
and turns them on it. At rank V a second meteor falls on another enemy.

A strong run reached level 85 and cleared the lair at full health, so
the late game grows steeper: the experience per level gains a cubic term
(5 + 3L + L^3/50), whelp health grows with the cube of 1 + t/300 (x8 at
5:00, x27 at 10:00) while bites keep the square, and the item damage
follows the health.

* feat(model): actor:AddAuraVisual / RemoveAuraVisual, a unit's auras on actors

A 1.12.1 unit shows every aura it carries at once. When an aura slot
fills, 0x005FF350 plays the state kit of the spell's visual (SpellVisual
+0x10, now OFF_SPELLVISUAL_STATE_KIT) as a lasting kind 2 kit through the
kit player (0x0060EDF0): each effect column's model holds at its
attachment (158 Hold at each end, KitEffectHoldCallback 0x005FF170), and
the +0x30 world effect is planted where the unit stands (PlantEffect
0x0061FCF0), turned by its facing and scaled by its scale (0x00620A90),
following it for a spell with a root aura (26: flag 0x4000, re-placed at
the owner each update, 0x006205A5). When the slot clears, 0x005FF290
stops the spell's kits with force (0x00614150): an effect whose model is
loaded and has 159 Decay (ANIM_DECAY) plays it and stops at its end
(0x006141F0, the same test as EffectDoneCallback); any other stops at
once (CEffect::Stop 0x006203E0: hidden, its particles finish).

SetSpellVisualKit holds one kit, so two auras on one actor replaced each
other. model/SceneAura.cpp keeps a list of auras per actor, one per spell
as one slot holds a spell: AddAuraVisual(spellID) shows the state kit
beside the actor's kit, RemoveAuraVisual([spellID]) ends one aura or all.
VisualKit gains Stop (the removal step for an attached effect, through its
dying list), SetsColor (now shared with the cast's precast and channel
tints) and ApplyProcedures, so a removed tint gives the model back the
colors of the kits still on it. Casts::Retire hands a stopped world effect
to the actor's impact list, which frees it once its particles are gone.
The auras survive a model change and show once the new model loads;
ClearModel ends them, as the actor pool releases through it. Not played:
a state kit's animation and sound.

* feat(broodwatch): Lightning Shield, Polymorph, Arcane Missiles, Death Coil

Lightning Shield (324) circles you with its real orbs through
AddAuraVisual, beside Power Word: Shield's bubble; every half second an
orb strikes a whelp biting you with the spell's impact kit (62), and the
shield ends with its last orb. At rank V each strike also hits a second
whelp. Polymorph (118) turns the toughest enemies into the Polymorphed
Sheep (creature 16372, display 856): a sheep wanders and does not bite,
then turns back; at rank V the whelps around each target turn too. One
ApplySpeed now sets an enemy's run speed for sheep and slows alike.
Arcane Missiles (5143) channels its kit (729) and fires the real Arcane
Missile (7268) each second, as the server's periodic trigger does; at
rank V each missile splits into three. Death Coil (6789) harms, heals you
and fears its target for 3 s, at rank V everything around it.

Channels count their ticks now: one each second, the last at the
channel's end as a periodic aura's last tick comes at its expiry. The end
check used to run first and drop the last tick of every channel.

Hovering a spell or passive on the build bar shows its tooltip: the rank,
the blurb, the stats at that rank and the mastery.

* feat(broodwatch): /broodwatch <spell> [rank] starts a run with one spell

A spell key of SPELLS after the command starts the run with that spell
alone, at the rank given (I by default, at most V), so a new spell or its
mastery can be tried at once. An unknown key says so; the bare command
still starts a normal run with Frostbolt.

* feat(model): auras pin their animation; the client's missile release; kit ground effect turns

The stationary pin. CGUnit_C::PlayAnimation (0x005FE2F0) passes every
request but a death through ApplyEffectAnimation (0x005FDE80): while the
unit's movement flags have none of 0x20000F (the four directions and
swimming), the newest effect on its list whose kit animation is positive
and whose flags carry 0x1000 (the kind 2 state kit, 0x0060EECD) plays
that animation with variation -1 instead. Actor::PlayAnimation now does
the same with the newest aura from AddAuraVisual, so a stunned actor
stands stunned and a moving one runs; the mover's path moves set the
forward flag as StartSplinePath (0x006187A0) does. A new aura with an
animation picks again unless the model already plays it (0x0060F383 to
0x0060F399); its end does not, and the pinned animation plays on until its
sequence ends, as on a unit.

The missile release. The unit's sequence-end handler (0x005FC920) asks
0x005FCCB0 about the ended id before it tests the reason (0x005FC9FC), so
a cast animation that ends or that another play replaces releases the
queued missiles (0x0060C9B0 at 0x005FC9A2): the spell casts of 0x005FCBB0
(2, 32, 33, 53, 54, decoded from its jump table at 0x005FCBD8) and 46, 49
and 107. The scene released on the natural end of any kit animation; it
now calls the client's test (FUN_IS_MISSILE_RELEASE_ANIMATION) in the
actor's done callback, for either reason. Arcane Missiles' ChannelCastDirected
(124) is not a cast, so its missile waits for $CSL/$CSR/$CST or the
2000 ms of 0x0060A814, as in the world.

The kit's ground effect. A planted effect is placed by 0x00620A90 as
Translate(point) * Rotate(owner's facing) * Scale(owner's scale), a scale
at or below 0 taken as 1. SetSpellVisualKit's +0x30 effect stood unturned
at scale 1; it now takes the actor's facing and scale when planted, as
the aura visuals' do.

* feat(broodwatch): holds and fears show their spells' auras, stacked

A whelp showed one SpellVisualKit at a time, so a frozen whelp that was
feared lost its ice. Each hold or fear now names the spell whose aura it
is, and the whelp shows it with AddAuraVisual for its own time: Frost
Nova's freezes (122), Psychic Scream's fear (8122), Inferno Effect's stun
(22703), the Thorium Grenade's stun (its use spell 19769, state kit 780),
Stoneclaw's rank V stun as War Stomp (20549), and Death Coil (6789, which
has no state kit, as in the world). The auras stack; a stun or Polymorph
that breaks a fear ends its aura, a death ends them all, and the stun
kits' Stun animation pins while the whelp stands. Power Word: Shield on
the hero is its aura (17) too, so it shows beside Lightning Shield's orbs
and decays when it ends. The kit IDs in Data.lua and every
SetSpellVisualKit call are gone.

* feat(model): aura visuals play their state kit's sound

A 1.12.1 kit plays its sound (+0x34) once per play: the first effect it
makes carries the play's flag word, and PlayUnitSpellVisualKit (0x0060EDF0)
ORs 0x400, "no kit sound", into its own word after that, so only that
effect's one-time arm pass sounds (0x00620C10 to 0x006210B9); a kit that
made no effect plays it at the end of 0x0060EDF0 (0x0060F434 to
0x0060F4BC). For a lasting kit (kinds 2 to 4) whose definition has bit
0x200 (GetSoundDefFlag200 0x00458830) the sound loops on the unit
(AddEffectSound 0x0061FEC0 -> PlaySoundLoop3D) until CEffect::Stop stops
it with a 0.15 s fade (push 0x3E19999A before Sound::Stop2 at
0x006204B6). A definition with bit 0x20 asks every play path for the
duplicate check (0x00458F40, called from InternalPlaySoundAt at
0x0045CF5B and from PlaySoundLoop3D), so it plays once however many units
show it at once.

AddAuraVisual now plays its state kit's sound at the actor when the aura
shows, or loops it there for a 0x200 sound, following the actor, quiet
while the scene or actor is paused and while the scene is hidden, and
fading out with the aura. The loop test and the fade move to the scene's
Sounds module (Sounds::KitLoops, Sounds::kStopFadeSec), which the casts'
channel and missile sounds share.

* feat(broodwatch): Hellfire, a channel on yourself that burns you too

Hellfire (1949) channels on the hero: the scene's channel on the caster
takes it as it is (no beam to itself, no impact kit). Each second its
periodic trigger, Hellfire Effect (5857), bursts around the hero through
PlaySpellVisualAtPoint at the hero's feet (its cast kit 844, no impact on a
target), burns every whelp within reach, and lights the first eight hit
with its impact kit (845). The fire burns the hero for 3 a tick, as the
spell's own damage aura (3) does; at rank V it heals instead. It only
starts with the brood in reach. The burn reaches the hero through a new
pendingHurt, which Power Word: Shield soaks and the red glow shows as a
bite's. A channel without a target (def.self) lasts its time and centres
its tick on the hero.

* feat(model): the scene camera shakes; PlaySpellVisual at a table of targets

Camera shakes. A 1.12.1 kit names a SpellEffectCameraShakes row at +0x38;
the kit player plays it once per play (0x0060EE2E) through
PlaySpellEffectCameraShakes (0x006ECB40), which adds each of the row's
three CameraShakes ids with CameraAddShake (0x00511D40): the row's type,
axis, amplitude times 1/36, frequency, duration, pre-roll and decay, kept
with the position and the clock (0x00511C60). A dynamic object's $SHK
event adds the row its payload names at the event's point (0x005D5920 to
0x005D592B). Each frame the camera's walk (0x00511760) ages them (ms * 0.001
plus the pre-roll, gone at the duration), cuts each by its distance from
the eye (0x005116E0: whole within 9 yards, nothing past 80, times
0.7^((d - 9) / 9) between, the double 0.7 at 0x00808AD0), keeps the
strongest per axis, and evaluates it (0x00511610: A sin(2 pi t f), times
exp(-t k) for type 1; axis 0 along the heading, 1 across, 2 up). The
driver adds the sum to the eye (0x0050EDCC); the view never turns.

model/SceneShake.cpp does this per scene on the scene clock, so a paused
scene holds its shakes. Paint adds the offset to the eye it draws the sky,
world, models, decals and beams from; the projection stays unshaken. The
kits a scene plays (casts, SetSpellVisualKit, ApplySpellVisualKit, aura
visuals) and a spell area's $SHK shake it. The heading is the scene
camera's, the world's being the followed unit's facing. A kit's shake
plays at the actor: the client plays it from the first effect node's
position, which a bone-attached node has not filled yet (read at
0x00620E0E, filled at 0x0062101D), so a kit like Thunder Clap's 356 shakes
at the world origin there and the camera drops it. The footstep (0x005FBF70)
and swing (0x00625C30) shakes stay off; stock scenes would shake.

A table of targets. A spell go carries a hit list: the cast kit plays once,
the launcher makes one missile per hit (0x006E8A50), and without missiles
the instant impact walks the list (0x006E8BF0). PlaySpellVisual now takes a
table of actors as that one cast: the first is the cast's target, each
other gets a sibling cast with the same ID and its own missile, or its
impact at once, and OnSpellVisualImpact runs for each target. The siblings
join the cast list after the step that made them, as a step holds a
reference into it. Each missile still starts its own flight loop through
PlaySoundLoop3D (0x004589A0), as in the world.

* feat(broodwatch): evolutions, one-cast volleys, a quieter grenade stun

A spell at rank V with the passive it needs (any rank) can evolve: every
level-up then offers the evolution first, and it takes the spell's slot
and recharge. Six, each a real spell: Frostbolt and Multishot become
Frostbolt Volley (8398), Shadow Bolt and Might Shadow Bolt Volley (9081),
Corruption and Vampiric Embrace Siphon Life (18265), Power Word: Shield and
Vigor Divine Shield (642), Thunder Clap and Devotion War Stomp (45), and
Rain of Fire and Amplify Flamestrike (2120). An evolution has one rank,
never comes on its own, and shows a purple E on the bar; a rank V card and
a spell's tooltip name its evolution, an evolved spell's tooltip what it
came from.

A volley is one PlaySpellVisual at a table of its targets, so its cast
plays once; each impact comes back with the actor it hit. Frostbolt
Volley fires four bolts every 0.9 s: each missile starts its own flight
loop as in the world, and eight at once roared. Dots carry their spell and
heal (Siphon Life's), a shield the aura it shows (Divine Shield's immunity),
and a missile's slow lands with it.

The Thorium Grenade's stun showed its own aura, whose kit plays Gouge
(3313) on every whelp with no duplicate guard; it shows War Stomp's
silent StunSwirl (20549) now.

* fix(model): PlaySpellVisual at one actor again

a005002c took any table in the target slot for a list of targets. A scene
actor is a Lua table too (its object at index 0), so every single-target
cast read as an empty list and returned nil: no visual, no cast ID, no
OnSpellVisualImpact. A list is now a table that resolves to no object
(ResolveObject); one that does is the one target.

* fix(broodwatch): fractional heals add up

The pending heal was rounded to whole points each frame and the rest
dropped, so Siphon Life's 0.3 a tick never healed. Whole points heal now
and the fraction waits for more.

* feat(broodwatch): chests from elites, opened by walking up

Every elite now drops a chest a little way from its corpse, toward the
hero. Every fifth chest is golden. The chests use the client's own
gameobject models and animations, read from the M2 files:

- TreasureChest01: Closed 147, Open 148 (0.67 s), Opened 149. One pick.
- G_ChestTitan: Closed 147, Open 148 (3.2 s, played at double speed),
  Opened 149. Three picks.

When the hero walks into the ground ring, the chest plays Open and the
ChestOpen sound (SoundEntries 1277). It then holds Opened, gives its
picks, stays 4 seconds and fades out (actor:FadeOut). The open runs on
the scene clock, so a pause holds it.

A chest's picks share the level-up cards. ShowCards now shows the next
waiting pick, a chest's before a level's, and the game stays paused
until the last pick. `/broodwatch chest` and `/broodwatch golden` start
a run with a chest close by.

* feat(broodwatch): dragon egg clutches; kind traits replace kind checks

A clutch of four black dragon eggs (G_DragonEggBlack, Blackwing Lair's)
is laid every 75 seconds from 1:00. An egg hatches after 20 seconds
into four whelps of the kinds spawning by then. A red ground reticle
(SetGroundReticle with valid false) marks it for the last 5 seconds.
An egg is an enemy, so every spell can break it. A broken egg drops a
gem as a whelp does.

The egg ends with its gameobject's Custom0 animation (153) and sound
4785. The client's GameObjectDisplayInfo row 477 has that sound in
sound slot 6 (columns: ID, model, then ten sounds: stand, open, loop,
close, destroy, opened, custom0 to custom3), and the M2 has a 1 s
Custom0 sequence. The cracked egg holds the frame just before the loop
(actor:SetPaused(true, false), the actor's own flag only) while it
fades. Spawn clears the flag.

The kinds now carry their traits as fields, and the code reads the
fields instead of testing for a kind:

- holdShare: the share of a hold's, fear's or polymorph's time. 0 is
  immune, and Polymorph does not pick the enemy.
- knockShare: the share of a knockback. 0 does not move.
- speed 0 never moves, dps 0 never bites.
- path: a model file in place of a creature display.
- crackAnim, crackSound, crackSeconds: the end in place of Death.

The elite's knockback and hold shares move from TUNING onto ELITE, and
the e.kind == ELITE tests in Blast and HoldShare go. Spawn takes an
optional point (SpawnPoint picks one as before), and the shared part of
a death is Retire, so a hatch leaves the fight without a drop.
`/broodwatch eggs` starts a run with a clutch laid.

* feat(broodwatch): land mines and Onyxia's lava vents

Land mines (Mines.lua). Four Goblin Land Mines (creature display 6271:
Stand 0, Despawn 157 of 1.17 s) lie in the lair from the start. A mine
is not an enemy, so no spell aims at it and the hero walks over it
safely. A moving enemy within 1.5 yards sets it off. The mine casts the
Goblin Sapper Charge's visual (13241) at its own point with
PlaySpellVisualAtPoint: the visual's impact model (Bomb_ExplosionA)
plants on the ground and its cast kit plays the fire nova and its
sound. The client's own Land Mine Impact (22498) has only a small
chest-fire impact. Every enemy within 6 yards is hurt and thrown. The
spent mine plays Despawn, hides, and lies again elsewhere 15 seconds
later.

Lava vents (Vents.lua). The vents are the lair's real floor cracks: the
Onyxia encounter's lava-trap gameobjects (177984-178020, display 4392
and its mirror 4472), at AzerothCore's retail spawns on map 249, the 12
within 23 yards of the arena's centre. The 1.12 server data on disk has
the templates but spawns only 2. The crack's mesh lies under the floor
(z -6.13 to -1.32), and its Custom0 (153, 1.57 s) is the eruption.
Onyxia's Eruption (17731) has only a cast kit (4409) with sound 7714,
so a wave plays that sound once, not once per crack. From 2:00, every
8 seconds a wave of cracks shows a red ground reticle for 2 seconds,
then erupts. It burns the brood (and throws it up) and the hero (15%
of maximum health, through Power Word: Shield). Waves grow from one
crack to four.

The cracks fit both clients. Turtle replaces the lair WMO
(kl_onyxiaslair_b, 11 groups against the stock client's 8), but a ray
cast of both at all 12 crack points finds the same floor heights to
0.01 yd. The WMO's local x and y are the world's negated.

RunGrowth (damage that grows as the brood's health does) moves from
Items to Core, for the items and the mines. `/broodwatch vents` starts
a run with the waves from the first second.

* feat(model): actor:PlayLevelUpEffect, the world's level-up glow

CGUnit_C::OnLevelChanged (0x0060CE2F) plays the unit's hard-coded
effect 5 on every level change, through AddHardcodedEffect
(0x0061FAE0). The new actor method plays that effect on the actor:

- The effect row is s_hardcodedEffectIds[5] (0x00C4DF30), which
  start-up (0x0061F5B0, from WowClientInit) fills by name from the
  table at 0x008617B8: "HARDCODED Unit Level Up", row 21,
  Spells\LevelUp\LevelUp.mdl.
- The attachment is s_hardcodedEffectAttachments[5] (0x0080C968), 19,
  the base; 37 means none, and a model without the attachment takes
  19.
- The model is made in the actor's scene (0x00707350, as the world's
  call) and hung once, with EffectDoneCallback's stop, and with the
  effect's events: CEffect::OnModelEvent (0x0061F6F0) plays $SND at the
  event's point and the wound animation on $HIT. The level-up sound is
  the model's own $SND event (888, LEVELUP).

The world first stops the unit's running copy of the row
(StopUnitEffectsAt 0x006208E0); here a second call plays over the
first.

VisualKit::Hang (one effect at one attachment, the caller owning the
model) is split out of Apply, and a stopped kit effect now clears its
event callback too, as CEffect::Stop (0x006203E0) clears the model's
callbacks. The planted effect's event callback is the same
CEffect::OnModelEvent mirror, renamed OnEffectEvent.

* feat(broodwatch): the level-up glow; mines armed by the hero

The hero plays the world's level-up glow (actor:PlayLevelUpEffect) when
the experience bar wraps, once however many levels it gains.

Mines no longer work on their own. A mine lies dormant under a small
reticle until the hero steps within 1.5 yards: that arms it, with Land
Mine Arming's sound (spell 11816's cast kit 259, SoundEntries 3216),
and its reticle grows to the 6-yard blast. Only an armed mine goes off
under a whelp. Before, a mine far away cleared packs by itself and
flooded the floor with gems; now it works where you lead the brood.

* feat(broodwatch): ten spells, combos, fusions, markers, a grace

Off-screen markers (Markers.lua). A closed chest or an egg clutch past
the scene's edge shows a gold arrow (ChatFrameExpandArrow) on the line
from the centre to it, turned with texture:SetRotation, and its icon
(INV_Box_01/02, INV_Egg_01); a clutch also shows the seconds until it
hatches. Each clutch keeps where it was laid, so it shows once.

Ten spells. Kinds.lua holds the new kinds behind an extension point:
Spells.lua's Fire and CastNext defer to BW.kindHandlers[kind].
- Cones (Cone of Cold 120): everything inside a 90-degree arc. The aim
  is the direction that catches the most of the brood; the cast stops
  you 0.4 s facing it, since the cone hangs at the hand (kit 1027) and
  an actor moves the way it faces.
- Turrets (Searing Totem 3599: creature 2523, display 4589) shoot
  Searing Bolt (3606) at the nearest whelps.
- Zones (Earthbind Totem 2484: creature 2630, display 4588) slow the
  brood around them with Earthbind's aura (3600).
- Traps (Freezing Trap 1499, Explosive Trap 13813) use the hunter
  traps' gameobject models: Spawn 145, Closed 147 once armed, and on a
  whelp Custom0 153 with that slot's sound (GameObjectDisplayInfo sound
  6: 6522, 6523, 6524). Freezing Trap Effect (3355) shows its ice
  block; Explosive Trap Effect (13812) its molten impacts and, with the
  mastery, its burning ground (SetModelBySpellArea).
- Charges (Charge 100) rush you into the thickest pack at 28 yards a
  second, Steer held off, and stun what is around where you land
  (Charge Stun 7922).
- Whirlwind (1680) is a nova whose cast kit spins you; Pyroblast
  (11366), Mind Blast (8092) and Moonfire (8921) are missiles.

Combos. Each spell's school comes from GetSpellSchool at load, and
SpellDamage in Brood.lua weighs it against the enemy's state:
- Shatter: a hit but frost on a frozen enemy deals triple damage and
  breaks the ice.
- Dread: shadow on a fleeing enemy deals 1.5 times.
- Detonate: nature on a burning enemy lands the rest of the burn at
  once, and half of it on the enemies around.
- Steam: frost puts out a fire burn and stuns.
- Wildfire: a burning enemy that dies sets its neighbours alight.
Burning is a new status with its school; a fire burn shows Immolate's
aura (348, state kit 235).

Fusions. Two spells both at rank V fuse into one real spell, offered
first, which takes the first one's slot and frees the second:
Fire Nova Totem (1535, display 4683), Frost Trap (13809, with Frost
Trap Aura 13810's icy ground), Intercept (20252, a charge that lands
in a Whirlwind), Starfire (2912), Frost Breath (3129, at the breath)
and Shadow Flame (22539). The cards and the bar's tooltips say what
fuses with what.

A grace when the last level-up or chest card closes: the brood within
6 yards is thrown back and nothing hurts you for 1.5 s (you show at
half alpha). `/broodwatch` now takes several spells with ranks, so a
fusion can be tested: `/broodwatch charge 5 whirlwind 5`.

* fix(broodwatch): traps and totems cast; a smaller XP bar with its text

The trap, turret and zone kinds used QueueOne as their Fire, but Fire is
called with (key, state, def, level) and QueueOne took (key, state,
level): the level that reached the cast was the spell's table, so
Stat read nil and the cast failed ("`for' limit must be a number" at
the trap count). QueueOne now takes the def too; the cone passes it.

The hunter trap models are a yard across, too small from the run's
camera: they show at twice their size, with a ground reticle, small
while the trap arms and as wide as what it catches once armed.

The experience bar no longer spans the top of the screen: it sits on
the health bar, as wide, and shows the level and the experience toward
the next one ("Level 7    12 / 55"), from UpdateXp for a new run and
each gain. The top-left line keeps the clock and the kills.

* feat(broodwatch): strafe through a cone's cast instead of stopping

A cone's cast turned the hero to its aim and stopped them for 0.4 s,
since an actor moves the way it faces. The actor already has the
client's strafe (actor:StartStrafingLeft/Right and StopStrafing, the
mover's StartStrafe 0x007C6C50 and StopStrafe 0x007C6D30), so the pose
now only turns the hero: while it lasts, the way you hold becomes the
nearest of the eight moves a character makes about its facing, ahead,
a strafe, a backpedal (the client's slower back speed) or a diagonal.

BW.Drive (Core.lua) sends the hero forward or back, to the side and its
facing, and only what changed, since each command re-anchors the move.
Steer, the cone pose, Charge and the cards' pause go through it.

* feat(util): the combat log's school colours and SCHOOL_MASK_*

Ports retail's school colouring so an addon can colour a spell's damage
by its school, as the combat log does:

- Util/Constants.lua gains SCHOOL_MASK_NONE..ARCANE (Classic's values,
  0 and 1 << school). GetSpellSchool's 1-based school ID n is the mask
  2^(n-1).
- Util/CombatLogColors.lua is Blizzard_CombatLogBase's Vanilla
  CombatLogColors.lua unchanged: COMBATLOG_DEFAULT_COLORS, keyed by the
  COMBATLOG_FILTER_* masks Constants.lua already defines and by
  SCHOOL_MASK_*.
- Util/CombatLogUtil.lua carries CombatLogUtil's colour functions:
  GetColorBySchool, GetColorByEventType, HighlightColor and
  WrapTextInColor. The rest of that file needs C_CombatLog and the
  retail combat log's strings, which this client does not have.

* feat(broodwatch): Warders, drakes and breathing whelps; school-coloured hits

Enemies with an act (Foes.lua) stand, mark the floor with red ground
reticles where they will strike, then strike:

- Red whelps breathe Flame Breath (16396) in a 6-yard, 60-degree cone,
  marked by three reticles along it. Its visual plays from
  PlaySpellVisualAtPoint at a point ahead, and the cone is checked at
  the cast's impact.
- Onyxian Warders (display 8711) keep 13 yards away and throw Fireball
  (133) at the spot you stand on. The spot stays marked through the cast
  and the flight; the missile's impact (OnSpellVisualImpact, through the
  in-flight entry's onImpact) burns whoever is on it.
- Onyxian Drakes (display 6369) mark a line through you, then run it
  with MoveTo at 24 yards a second and Charge's trail (100). A pass
  within 1.6 yards strikes and knocks you back; the drake then stands
  dazed. The line stops short of the lair's wall, because a MoveTo goes
  through walls.

A strike hurts for a few seconds of the striker's bite, softened as a
bite is, and adds to the step's pending hurt (shield, grace). Holds,
fears, sheep, taunts and knockbacks break a wind-up off
(StopSpellVisual on its cast); what is already thrown still lands.
Kinds gain `max` (the most alive at once) and `keep`. /broodwatch
<kind> starts a run with three of a kind.

Hit numbers take the school's colour from COMBATLOG_DEFAULT_COLORS
(CombatLogUtil.GetColorBySchool), and burns take their own school's;
a spell's own colour stays for the HUD.

* feat(broodwatch): legendary weapons, worn gear and four new pickups

Gear is kept for the run (Gear.lua, Data.lua's GEAR). A golden chest's
first pick, while you hold no weapon, is three of the weapons; every
other chest pick offers a piece of worn gear while you wear fewer than
three. Cards and the build bar's new gear row take the item's quality
colour; names, icons and colours come from the Item mixin.

Weapons go into the hero's hands with actor:TryOn, and a new run puts
the player's own back with DressPlayerSlot(16, 17, 18):

- Thunderfury (19019): a spell hit may loose the item's own proc,
  21992, which leaps from enemy to enemy as Chain Lightning does
  (each leap a PlaySpellVisual from the enemy it hit) and slows.
- Sulfuras (17182): a hit may hurl its proc's Fireball (21162), which
  bursts, burns and throws the brood around where it lands.
- Benediction / Anathema (18608 / 18609): every 20 s the staff turns,
  with Call Benediction (23042) or Call Anathema (23041) and a TryOn of
  the other face; Holy or Shadow hits harder, and Benediction heals.
- Rhok'delar (18713): Auto Shot (75) at the nearest enemy, which draws
  the bow from the ranged slot.

The procs come from SpellDamage (OnSpellHit; a proc's own hits carry
`gear` and never proc again), at most once per weapon's `every`.

Worn: Drakefire Amulet (fire halved), Onyxia Scale Cloak (no harm from
breath), Hand of Justice (a cast may recharge at once), Talisman of
Ephemeral Power and Zandalarian Hero Charm (on-use damage, gone off by
themselves near the brood, with their use spells' visuals 23271 and
24658), Drake Fang Talisman (a share of blows dodged).

All hurt to the hero now goes through Core.lua's HurtHero(amount,
school, breath): bites and charges are Physical; vents, Warder
fireballs, whelp breath and Hellfire's self-burn are Fire. The gear and
the new potions soften it there.

Pickups: Dense Dynamite (23063's throw, sharing the grenade's, whose
numbers move onto the items), Greater Fire Protection Potion (a ward
that soaks fire), Limited Invulnerability Potion (no bites or charges),
and the Goblin Bomb Dispenser's walking bombs (Pet Bomb's display 8189,
the land mine's blast). `/broodwatch <gear> ...` starts a run wearing
that gear.

* fix(broodwatch): a long card name wraps inside the card

"Thunderfury, Blessed Blade of the Windseeker" ran past the card's edges:
the name FontString had no width, so it never wrapped. It is now as wide
as the description (184), and FillCard sizes it to its text as it does
the description (a tall height to measure in, then GetStringHeight), so
the card grows by the second line.

* fix(broodwatch): the health bar shows a pick's health at once

Vigor raises the maximum and heals 25, and Second Wind heals 50, but the
pick changed BW.run.hp without redrawing the bar, so it showed only at
the next hit. The pick now calls UpdateHealth (through BW: the local is
defined below the pick).

* feat(broodwatch): choose your first spell; a clear end banner

A run opens on a pick of its first spell, on the level-up cards (picking
"start", paused like any pick): your class's spell first (UnitClass's
English name into Data.lua's STARTERS: Frostbolt, Shadow Bolt, Lightning
Bolt, Holy Nova, Moonfire, Consecration, Thunder Clap, Explosive Trap),
then two of the other classes'. A class with none there gets three
others. `/broodwatch <spell> [rank] ...` still starts with exactly those
spells and skips the pick.

The end banner said "The lair holds!" for a win, which read as either
outcome. It is now "Victory! You held the lair for 10:00" in green, or
"You fell at m:ss" in red; "Paused" takes NORMAL_FONT_COLOR back.

* fix(model): scene actor scripts that change the model; review cleanups

Fixes from the PR #138 review.

A model script can no longer leave an actor in a broken state.
SetModel ran OnModelCleared through ClearModel, then installed its
model over any fallback that script set; the fallback stayed in the
M2 scene. SetModel then ran OnModelLoading before its callers wrote
the display ID and scale (ShowCreatureDisplay), the spell-area fields
(SetModelBySpellArea) or the unit's display ID and child lighting
(SetUnitModel), so a script that cleared or replaced the model left
stale data, and SetUnitModel walked a model the script had released.
Actor::Vacate now clears the model and releases what OnModelCleared
set; the callers write their fields after it and before SetModel,
which runs OnModelLoading last and lights the model's children itself.

A recipe try-on on a scene actor waited for the item the recipe makes
but warmed the recipe, so an uncached made item never arrived. The
queued request now holds the item it waits for, and a recipe that
arrives swaps in the made item and warms it.

Cleanups:
- The '$SND' event tag (compared at 0x005D58E1 and 0x006EBE42) is one
  value in Offsets.h, M2_EVENT_TAG_SND, instead of three copies.
- Ear() reads the SoundListenerAtCharacter CVar* the world frame
  stores at 0x00B4B2B4 (written at 0x00481BBA, read by its OnRender at
  0x00483118) instead of a name lookup on every sound move.
- VisualKit::Hang lights the one child it attached (LightChild), not
  the model's whole child list once per kit effect.
- Outfit::InvSlotOfLane / LaneOfInvSlot replace six copies of the
  hand-to-slot mapping.
2026-11-11 20:27:54 -06:00
Brues 1cdd443e53 refactor(text): inline icons take their line's fade when its colour changes
The icon textures have no frame, so the frame alpha fold (0x0077FAC0)
skips them and their only alpha is the one copied from their fontstring's
colour (colors[0], OFF_FONTSTRING_COLOR_ARRAY). The tick read that colour
for every fontstring with icons, every frame, and re-coloured the icons
when it changed.

Every change of that colour ends in the fontstring's region slot 8,
CSimpleFontString::OnColorChanged (0x00772180, `ret 4`): SetVertexColor
(0x0077F750) calls it after storing a colour, which is how the chat fader
and SetTextColor reach it, and the frame alpha setter (0x0076A690) calls it
on each region of the frame. It folds the colour (0x0077FAC0) before it
hands it to the built string, so the value is final when it returns.

A co-hook on it now copies the colour onto the line's icons in the same
call. No other loaded DLL refers to that address. The batch reads a
texture's colour through a pointer, so no layer rebuild is needed. The glue
value-follow (FadedColor) is unchanged. The tick only deletes orphaned
textures now; the per-fontstring applied-colour stamp is gone.
2026-11-02 10:26:26 -06:00
Brues ada33825ad refactor(text): inline icons are placed at build and at move only
Inline icons were placed on three paths: the RebuildString refresh, the
paint flush (FUN_TEXT_PAINT co-hook), which recomputed every icon line's
placements after every paint and queued any change, and the tick, which
applied the queue. Measured over normal play, the paint flush never
supplied an icon the rebuild had missed. All it did was re-place icons
that had moved, 456 times: almost all by float noise (1e-5 px), each one
re-anchoring the icon and rebuilding the fontstring's layer; the rest by up
to 0.9 px.

That 0.9 px is a move. A fontstring whose size does not change keeps its
built string: the rect callback (0x00772D40), SetTextOffset (0x00772100)
and the animation translation only move it, through TextBlockSetStringPos
(0x0044D600) -> CGxString::SetPosition (0x005CCB10), which re-finalizes the
node origin (0x005CDF70) before it returns. The origin is floored to whole
render-target pixels, so an icon anchored to the unrounded fontstring rect
drifts off its glyphs by up to a pixel.

The icons are now placed when the string is built (the RebuildString
refresh) and after each TextBlockSetStringPos, from a co-hook on it. No
other loaded DLL refers to that address. The move lays the node out first
(FUN_TEXT_ENSURE_BUILT, as the rebuild does): a colour change can leave the
node unbuilt until the next paint, and with no built lines (+0x9C) the
origin finalize returns early with the raw normalized position in the
origin, which placed those icons at the bottom-left of the screen. The
placement now refuses an unbuilt node. Only nodes with icon records are
laid out early.

Removed: the paint flush's placement queue, the pool's queue and dirty
flag, and the tick's apply. The pool has one entry point, Apply, which
skips an icon set equal to the one applied. The paint flush keeps its
other jobs (the stuck-blockless re-dirty, the stale-record guard and the
baked-alpha mirror); the tick keeps the orphan deletes and the fade mirror.
2026-11-02 10:15:54 -06:00
Brues 5911298acd fix(text): inline icons are drawn by their line, as 4.3.4 does
Inline icons were CSimpleTextures registered on the fontstring's parent
frame, with their visibility copied from the line once per tick, after the
draw. Any line that hid kept its icons for one more frame; once chat lines
moved with their text, a line scrolled off the top flashed its icons above
the chat frame.

4.3.4's CSimpleEmbeddedTexture has no frame, and the fontstring draws it:
CSimpleFontString::Draw queues the string, then QueueTextures. 1.12's
equivalent is CSimpleFontString::Emit (0x00772E50), the only caller of
AppendToBatch (0x00773080). The icon textures are now made with no frame
(SimpleRegionConstruct skips SetRegionParent for a null parent; the
frame-alpha fold 0x0077FAC0 tests the parent), anchored to the fontstring
and given its scale through layout slot 0x10, as AddRegionToLayer does. A
hook on Emit adds a line's icons to the layer batch right after its text,
and only when the text went in (the batch count at +0x4 grew), so an icon
draws exactly when its line does, in the same frame.

The batch copies each texture's handle, blend and colour count when built
(0x00772FD0) and reads vertices, texcoords and colours through pointers, so
a change to a line's icon set marks the fontstring's layer
(NotifyLayerChanged 0x0077FDF0), and moves and fades need no rebuild.

4.3.4 sets the textures up in UpdateString. RebuildString (0x007724A0) now
does the same: when its gate passes (layout flags +0x60 bit 1, `test byte
[esi+0x60],1`) it replaces the built string, so the line's icons are
dropped, the new node is laid out (FUN_TEXT_ENSURE_BUILT) and its
placements applied at once. The paint flush stays the backstop.

Removed: the per-tick visibility mirror, the freshness expiry, region
Show/Hide and re-parenting, and the SMF early apply with its
_classicapi_InlineTexEarly toggle; the rebuild refresh covers what it did,
and it rebuilt every icon line on every layout. The textures are deleted
through their vtable slot 0 (as the frame destructor deletes regions) one
tick after their fontstring dies or a reload, once the batches holding them
were rebuilt.
2026-11-02 00:53:10 -06:00
Brues ead52e79ce fix(editbox): caret, selection and click rows follow tall inline icons
A multi-line edit box places its caret, selection pieces and a click's
cursor by rows of one height (font height + spacing, pixel-aligned), while
the render moves a line holding an icon taller than the font, and every
line after it, down by the overflow, and the box grows to match. Below the
first tall-icon line the caret and highlight sat above their text, and
OnCursorChanged reported that y, so ScrollingEditBoxMixin's scroll-into-
view stopped short (pfUI chat copy with faction emblems).

4.3.4's CSimpleEditBox has the same fault: UpdateVisibleCursor,
UpdateHighlightArea and ConvertCoordinateToIndex are icon-blind too. So
this goes past 4.3.4, as editbox/CharClass does. EditBox::IconRows co-hooks
the three placers and gives each the render's move, from the new
Text::InlineTexture::LineIconShift over the box's own line table: the
click's y is mapped onto the uniform row before the engine reads it; the
selection piece and caret are re-anchored after, with the engine's own x;
the caret's OnCursorChanged is muted for the original call and fired once
with the corrected y through the engine's forwarder, with the same packing
PlaceCaret uses (verified in the disassembly and the binary's constants).

Also fixes the "caret positioner" misnomer for 0x77DE70 (the selection-
piece placer) in Offsets.h and the docs.
2026-10-30 01:15:01 -05:00
Brues 5ab497f2c7 feat(smf): scroll offset, insert mode, display-refreshed callbacks
Retail's ScrollingMessageFrame SetScrollOffset, GetScrollOffset,
GetMaxScrollRange, ScrollByAmount, SetInsertMode / GetInsertMode with the
SCROLLING_MESSAGE_FRAME_INSERT_MODE_* globals, and
AddOnDisplayRefreshedCallback, which ScrollUtil's
InitScrollingMessageFrameWithScrollBar calls.

The offset is the engine's own: SetScrollFromBottom's body (0x00788700)
is 4.3.4's SetScrollOffset step for step, and GetCurrentScroll is
GetScrollOffset under retail's name. The setters clamp to
0..GetNumMessages()-1 first, as retail does; the engine wraps. 1.12's
layout stacks lines bottom-up only, so the insert mode is BOTTOM and
SetInsertMode raises an error for anything else.

The callbacks run after the frame's own update (0x00788460, OnUpdate then
the fader), where retail's OnPostUpdate runs them, for a frame the line
layout, AddMessage or ScrollByAmount marked. The layout hook moves out of
Text::InlineTexture into ScrollingMessageFrame::Layout, which owns it and
fans out to both.
2026-10-29 23:56:24 -05:00
Brues bd02983a08 feat(lua): WowTrimHorizontalScrollBar
Retail's horizontal bar is its vertical one with x and y swapped. Classic
Era has no horizontal bar and this client no horizontal scroll bar art, so
the template is WowClassicScrollBar with every anchor, size and inset
swapped, and retail's horizontal atlas names (UI-ScrollBar-EndCap-Left/
Right, _UI-ScrollBar-Center, UI-ScrollBar-ScrollLeft/RightButton-*, ids
from the 1.15 member table) bind to the Classic art transposed: the top cap
is the left cap, the up arrow the left arrow. Transposing keeps the art's
top-left lighting, which a quarter turn would move. The square knob takes
the swapped crop of the same file.

Atlas entries gain a transposed flag: SetTexCoord composition maps sprite x
down the file rect and y across it. An inline |A icon is one axis-aligned
rect, so a transposed atlas is not drawn there.
2026-10-27 23:01:36 -05:00
SkeewirtandBrues e84496d036 feat(animation): the animation system - AnimationGroup, Animation, Alpha, Scale, Rotation, Translation (#89)
* feat(animation): the animation system - AnimationGroup, Animation, Alpha, Scale, Rotation, Translation

Later clients animate regions in the renderer; vanilla has none of it, and
ported UIs build on it everywhere (Zygor Guides Viewer 2.0: 25 XML groups
plus CreateAnimationGroup in its guide window's OnLoad, which stopped there).

- Util/Animation.lua (bundled addon): the runtime. Groups and animations
  with the later-client API (Play/Stop/Pause/Finish, progress and smooth
  progress, order/startDelay/endDelay/duration timeline, NONE/REPEAT/BOUNCE
  looping, NONE/IN/OUT/IN_OUT smoothing, maxFramerate, the group and
  animation scripts). One driver frame ticks playing groups; effects go
  through the region's own setters and the region's state is restored
  when the group ends, as later clients never persist them.
- animation/Bridge.cpp: CreateAnimationGroup / GetAnimationGroups /
  StopAnimating on the region base registry, forwarding to the runtime the
  bundled addon registers via _classicapi_SetAnimationRuntime.
- xml loaders: an <Animations> child becomes descriptor tables (attributes,
  <Scripts> bodies and function= names, <Origin>) handed to runtime.LoadXML
  before the builder finalizes. Adds OFF_XML_NODE_TEXT. This extends the
  node-loader hooks of the XML attributes change, which it builds on.

Known limits of the 1.12 renderer: Scale pivots on a frame's own anchor
point (exact when anchored by its center) and resizes textures anchored by
one point; Rotation needs texture:SetRotation (textures, font strings).
Group templates (inherits on an AnimationGroup, CreateAnimationGroup's
template argument) are not supported yet and are ignored.

Verified in-game (1.12.1 client via VanillaFixes, Zygor Guides Viewer 2.0):
a probe XML <Animations> group builds with Play(); every AnimationGroup and
animation method exists; a Lua-built group plays through 12 updates to
progress 1.0 and fires OnFinished; Zygor's step flash group (Alpha) plays
and stops, and its guide window finishes its OnLoad. Not checked yet:
Scale, Rotation and Translation on screen (Zygor's own groups with them
load without error, but no one has watched them play), REPEAT and BOUNCE
looping, the smoothing curves, and maxFramerate.

* refactor(animation): port 4.3.4's CSimpleAnimGroup/CSimpleAnim to C++

Replace the Lua animation runtime with a C++ port of the 4.3.4 engine
classes. Groups and animations are real 1.12 script objects (engine
header from ConstructScriptObject, our own vtable), so GetObjectType,
IsObjectType, GetName/$parent globals, SetScript/HookScript and the
shared __index dispatch all go through the engine's mechanisms.

- Group/Anim: the 4.3.4 timeline (orders, delays, looping, cosine
  smoothing, 1/30 s throttle, pause/stop/finish) and every method.
- Region: per-region state ticked from a CSimpleFrame::OnFrameUpdate
  co-hook (shown frames only); 4.3.4's alpha model (store, reset each
  tick, add change, restore when the last alpha group ends, children
  included). CreateAnimationGroup, GetAnimationGroups, StopAnimating.
- Xml: <Animations> with 4.3.4's attribute set, inherits/templates,
  script bodies and function= through SetScriptObjectScript.
- Frame::Destruction: a shared hub over the frame destructor; groups
  die with their frame, and Frame::Alpha moves onto it.

Translation, Scale and Rotation keep their values and timing but do
not move anything yet.

* feat(animation): apply Translation to what regions draw

Port 4.3.4's AddAnimTranslation: a frame hands the offset to every
texture and font string below it (or only the target), a texture moves
the four corners its draw record points at, and a font string moves its
text block's string position. Rects, anchors and mouse areas stay put.

- StoreAnimPosition / PreOnAnimUpdate / ResetPosition mirror 4.3.4,
  with the base taken from the engine's own layout (the corner store
  for textures, inset x layout scale + rect corner for font strings).
- Co-hooks on the texture and font string OnFrameSizeChanged callbacks
  move the base when the layout moves a region mid-animation and keep
  the animation's offset, as 4.3.4's own legs do.
- A frame is marked while it plays a position group, so the end of its
  last one puts everything below it back.

Scale and Rotation still keep their values without drawing.

* feat(animation): apply Scale and Rotation to textures

Port 4.3.4's AddAnimScale / AddAnimRotation with GetOriginOffset,
ApplyScaleAnim and ApplyRotationAnim on the texture's drawn corners: the
origin point on the quad, its offset turned along the bottom edge, and a
counter-clockwise positive angle. Frames hand both to every texture
below them, or only the target. Font strings do not scale or turn yet.

* feat(animation): scale and turn font strings

Port CSimpleFontString's AddAnimScale / AddAnimRotation: the animated
rotation and x scale replace the string's for the update, and the text
is baked again when they change (the engine's node invalidate, as
4.3.4 invalidates the CGxString). After the bake, the glyphs are scaled
and turned about the node origin, where 4.3.4's InitializeTextLine turns
them, with the engine's half-texel UV inset for turned glyphs. The text
is stretched rather than drawn at a larger font size.

* feat(animation): add Path and ControlPoint

Port 4.3.4's CSimplePathAnim and CSimpleControlPoint: a Path moves the
region's drawing through its control points with AddAnimTranslation,
the points spread evenly over the progress, in straight lines (NONE) or
on 4.3.4's Catmull-Rom spline (SMOOTH). ControlPoint is its own script
object with offset, order and SetParent; BuildSpline keeps 4.3.4's
order shuffle when an order is taken. XML reads `curve` and
<ControlPoints>, with templates for CreateControlPoint and `inherits`.

One deviation from the decompiled CreateControlPoint: a point made
without an order takes the highest order + 1 (as SetParent does), so
points made one after another keep their creation order.

* fix(texture): keep shape changes made during a position animation

Texture:SetRotation and SetVertexOffset wrote the drawn corners, which
the next animation update replaced with the corners stored when the
group started. While a position group plays they now write the stored
corners, so the new shape shows with the animation on top and stays
after the group ends. FontString:SetRotation on text an animation has
turned or scaled bakes the glyphs again instead of re-turning them in
place, so the bake applies both.

---------

Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
2026-10-19 20:44:31 -05:00
Brues b9071a37f9 feat(text): render inline icons in edit boxes, as 4.3.4 does
4.3.4's edit box renders |T...|t in its text. Typed markup stays literal
because the edit box stores a typed | as ||, and 1.12 does the same
(0x77c254; Paste goes through InsertChar too). So edit boxes need no
special case once || is read the way both engines read it.

- The span rule is 4.3.4's GxuDetermineQuotedCode CODE_TEXTURESTART
  rule, in one scanner (IconSpanAt). Only |T...|t and |A...|a are spans;
  || is always a literal pipe. The old doubled ||T...||t match is gone.
  Stock 1.12 has no pipe-doubling sanitizer, so the ||T it was built for
  was typed text plus our own marker output.
- The edit-box suppression gates are removed: node bit 6 (really
  non-space-wrap), the focused-buffer test, the render-line content
  compare and the re-entry bracket.
- New co-hook on the fit-to-width function 0x772bc0 (mouse click to
  cursor, single-line visible window), mirroring 4.3.4's
  GxuFontGetMaxCharsWithinWidth.
- Ctrl+C drops icons: GxuStripControlCodes honours 4.3.4's 0x1000
  texture bit, and CopySelection's mask is patched from 0x500 to 4.3.4's
  0x1500. CopyToClipboard(text, true) now calls the same engine strip
  instead of its own parser.
- {rt1} and the other raid tags are expanded in the CHAT_MSG text at the
  event fire, and in the speech bubble after its escape strip (a
  redirected SetText call at 0x4b16c0), as 4.3.4's
  CGChatBubbleFrame::ParseRaidIcons does. The message buffer keeps the
  tags.
- The chat anti-spoof doubles a smuggled |T's pipe, as the edit box does
  for a typed one.
- The tokenizer hook honours the 0x800 all-pipes-literal gate.
2026-10-19 10:11:09 -05:00
Brues 42d037f080 fix(text): lay out inline-icon lines the way 4.3.4 does
Chat lines with icons ran past the frame edge after 47b258a. An icon
now starts at the previous glyph's ink edge, but every measure counts
that glyph by its advance, so a glyph whose cell is wider than its step
("[" in chat) pushed each following icon and the rest of the line past
the wrap budget. Cap the ink edge at the glyph's base advance.

Match 4.3.4's CGxString layout for the rest:

- Every wrap sizes icons with the fontstring's layout scale, as 4.3.4
  passes m_layoutScale to each CalcWrapPoint. The height getter, the
  rebuild's truncation and the break array set a fontstring scope the
  wrap stepper reads (new co-hook on the break array).
- A line whose tallest icon passes the font height moves itself and the
  later lines down by the overflow (InitializeText), and the origin
  finalize justifies the block with the summed extra
  (InitializeViewTranslation), via a co-hook on FUN_005CDF70.
- GetStringHeight sums each wrapped line's overflow
  (GxuFontGetWrappedTextHeight) instead of adding the tallest icon once.
- A link's hit band grows toward where its icon reaches, by the vertical
  justify.
2026-10-18 01:26:55 -05:00
Brues 47b258ad95 fix(text): size, space and align inline icons by the engine's own rules
The inline-texture backport placed icons with hand-tuned constants: a
0.18 x font lead/trail pad, a 0.6 x font vertical centre, a -1px region
nudge, and written sizes taken as raw screen pixels. Replace all of them
with the rules from the 3.3.5 / 4.3.4 clients (decompiled; the size
formula's helpers confirmed against the real 4.3.4 binary):

- A written size multiplies by fontPx / (14 x ddcWidthScale), so it
  follows the text's size, the UI scale and the resolution, and then by
  the fontstring's layout scale, as 3.3.5 does. Size defaults follow
  ParseEmbeddedTexture: ":0:2" is a width ratio, ":20:0" is font-wide.
- An icon starts at the previous glyph's ink edge (bearing + cell width)
  plus the face's outline gap, found by replaying the run's placements
  with the emitter's own glyph helpers; the next glyph starts at the
  rounded icon edge.
- Vertical alignment follows the node's justify-V (node+0x50).
- Offsets move only the drawn icon; a positive offsetY now moves it up.

GetCoinTextureString now matches 3.3.5: default height 14, a space
between denominations, and retail's 2:0 coin offset in the strings.

The four Coordinate statics at 0x00832A40 get their real names
(VAR_COORD_DDC_WIDTH_SCALE and siblings). Known gap: the fs-level wrap
callers can't see the fontstring, so they budget icons at layout scale 1.
2026-10-17 19:14:17 -05:00
Brues c3cf9e6f3a feat(texture): add atlas support — C_Texture, SetAtlas, and |A markup
An atlas names a texture plus a sub-rect inside it, so SetAtlas is the
engine's own SetTexture + SetTexCoord (+ the size setters for
useAtlasSize) driven off one lookup. Every step delegates to the engine's
Lua handlers, so the argument guards and the UI-scale conversion stay in
force and this module only adds the name resolution.

Adds C_Texture.GetAtlasInfo / GetAtlasExists / GetAtlasID /
GetAtlasElementID / GetAtlasElements, the RegisterAtlas extension for
addons that ship their own sprite sheet, texture:SetAtlas / GetAtlas, and
the |A:name:h:w|a inline markup alongside the existing |T form. All five
readers key off one bound set, so GetAtlasExists is true exactly when
GetAtlasInfo returns a table.

The built-in table is five rows on purpose. Measured against Classic Era's
UiTextureAtlas tables and the community listfile: 0 of 868 atlas sheets
exist in this client's art, and while Blizzard kept the original vanilla
filename as the atlas name for 16 members, only 5 have dimensions that
agree — vanilla's own scrollbar template draws a centered 16x16 out of a
32x32 file that the atlas calls 18x16. Texcoords are not derivable from
the two tables, so the rest grow from _classicapi_DumpAtlasMisses()
rather than from guesses. AtlasData.h carries the full derivation.

|A shares every scanner, measure, wrap and placement stage with |T —
ParseAtlasIcon fills the same IconDesc, since an atlas is exactly the
path-plus-sub-rect that struct already holds. That makes the chat
anti-spoof mandatory, not optional: IconFilter now defangs |A too, or a
player could render art by typing it into /say and the speech bubble.

GetAtlas stores the HTEXTURE it installed and clears itself when the
region points elsewhere, which gives the correct nil-after-SetTexture
behavior and avoids a second hook on FUN_SIMPLETEXTURE_CTOR — Texture::Mask
owns that target and MinHook refuses a duplicate, which would abort the
whole hook install.
2026-09-05 00:11:08 -05:00
Brues 0c8468cf2f refactor(reload): auto-register per-/reload cleanup; fix Time::Timer stale refs
Modules that keep reload-fragile file-static state (Lua registry refs,
frame/object-pointer-keyed maps, cached event-slot indices) each expose a
PrepareForReload() that DllMain called from the FrameScript_Initialize hook.
That list was hand-maintained, so a new module could silently forget to wire
itself in -- the failure mode behind the Frame::Attributes stale-ref bug and
Tooltip::SetEvents issue #33.

Add Game::ReloadAutoRegister + Game::RunReloadCleanups(), mirroring the
existing ModuleAutoRegister / HookAutoRegister / WorldTick::AutoSubscribe
patterns. Each module self-registers with one file-scope line after its
PrepareForReload:

    static const Game::ReloadAutoRegister _reloadReg{&PrepareForReload};

DllMain's 11-call manual list collapses to a single RunReloadCleanups(); a
new module can no longer be forgotten. Player::NameCache::Flush stays an
explicit call -- it's a save-before-teardown, not a stale-state clear, and
also runs on the glue-return path.

A sweep of all file-static state found one uncovered module: Time::Timer
pins C_Timer.After/NewTimer/NewTicker callbacks in the Lua registry but never
released them on /reload -- a surviving/stale ref could fire a dead closure.
Add Time::Timer::PrepareForReload (release each pending timer's registry
callback, clear the queue) and self-register it.

- Game.{h,cpp}: ReloadAutoRegister + RunReloadCleanups.
- DllMain.cpp: collapse the manual list to RunReloadCleanups(); drop 6
  now-dead includes.
- 11 existing reload modules + Time::Timer: add the self-register line.

Behavior-preserving (same cleanups, before the Lua teardown); auto-register
order is unspecified across TUs but every callback only clears its own state.
2026-08-25 18:37:44 -05:00
Brues a2c51a1ae6 fix(inline-texture): place chat icons pre-render to remove the one-frame lag
A ScrollingMessageFrame re-SetTexts every visible line on each new message, and
the engine builds each line lazily at paint. The icon regions are separate
objects whose placement is only known once a line builds mid-paint - after the
frame's texture pass already drew - so on a content change the new glyphs
appeared one frame before their icons caught up.

Co-hook the SMF display refresh (FUN_00788750), which runs pre-render from the
frame's own methods. After it, force each icon-bearing line to resolve+build via
the engine's own Realize(0) -> RebuildString -> ensure-built path and apply its
icon placement synchronously, before the frame draws. The placement math
(ComputePlacementsForNode) and the per-fs apply (ApplyDirtyBranch) are shared
with the existing paint-flush / FrameTick pipeline, so the later flush dedups to
a no-op.

Additive and best-effort: any line whose rect is not resolvable in time falls
back to the unchanged paint + tick pipeline (correct, one-frame lagged). Gated by
a new _classicapi_InlineTexEarly toggle (default on) with an SEH latch; the whole
feature keeps its _classicapi_InlineTexEnable kill switch.
2026-08-22 13:40:36 -05:00
Brues 93f3131307 fix(text): drop obsolete 1.5-glyph auto-width wrap bail
The wrap-stepper co-hook special-cased auto-width fontstrings (single-anchor,
no explicit width — pfUI addon-list labels, TwitchEmotes labels): when the whole
line fit within 1.5 glyphs of exactly filling its budget it applied zero shrink,
to avoid a spurious wrap from ~1-glyph drift between the width and wrap hooks'
icon-sum computations. The cost was that real-width frames landing within 1.5
glyphs of their edge also gave up their shrink and let icons overflow instead of
wrapping.

The trailing-icon trim, outline-ink threading, and exact-K measure work have
since tightened that drift under half a glyph, so the existing 0.5-glyph
feasibility tolerance now carries the auto-width case on its own. Verified
in-game: pfUI/TwitchEmotes labels no longer spuriously wrap, and near-full
real-frame lines wrap correctly instead of overflowing.
2026-08-19 22:21:24 -05:00
Brues 87acb70c5b feat(fontstring): add IsTruncated, SetMaxLines/GetMaxLines
Backport three FontString methods, each working WITH the engine's own
text-layout machinery instead of reconstructing it:

- IsTruncated(): did the engine cut the text off with an ellipsis?
  Reads render truth -- the built text node keeps a copy of the string
  it actually laid out (node+0x48), the ellipsized form on truncation
  -- and compares it to the source. Same "displayed vs full" check
  retail does (5.4.8 inner fn 0x0045E001). Re-calling the display-text
  resolver from Lua cannot work: it reads the laid-out rect (fs+0x64),
  which is zero between frames, so it never sees the bound.

- SetMaxLines(n)/GetMaxLines(): cap the fontstring to n wrapped lines,
  ellipsizing the rest. Writes the engine's own per-fontstring maxLines
  field (fs+0x128, already honored by the truncation resolver) and
  re-invalidates the layout the way SetText does (drop caches, release
  node, notify region). Vanilla has no SetWordWrap -- the fs->layout
  flag translator exposes no no-wrap bit -- so SetMaxLines(1) is how you
  make a single-line, ellipsized label.

Also correct a mislabeled bit in the inline-texture notes: fs+0x120 bit
0x1000 (gxu/node bit 0x40) is NON-SPACE-WRAP (what SetNonSpaceWrap
toggles), not a dedicated "editable" flag. The inline-texture code uses
it as an editbox proxy, which works because multi-line editors enable
non-space-wrap while display text does not; the comments now say so,
with the rare-edge-case caveat. Documentation only, no logic change.

Verified in-game: IsTruncated true/false across bounded/unbounded boxes;
SetMaxLines caps of 1/2/9/0 with matching GetNumLines and IsTruncated.
2026-08-19 16:46:55 -05:00
Brues 0ce9d159e9 fix(text): wrap-shrink axis error; substring measure; trailing-icon trim
Three inline-|T measure fixes, the first one load-bearing for chat.

1) Wrap shrink was overscaled by the render aspect. The wrap stepper's
inputs are gxu-normalized PER AXIS -- fontH normalized-Y (x rasterY =
pen px), wrapWidth/outWidth normalized-X (x rasterX = pen px); both
caller flavors land there (the draw builder passes node+0x1C/+0x3C,
pre-normalized at block creation via FUN_0041ae50/ae40, and the
fs-level callers x-normalize inside FUN_0044d670 before gxu, verified
by decompile). The hook converted the pen-x icon sum with fontH/fontHPx
-- a Y-AXIS factor -- overshrinking the wrap budget by rasterX/rasterY:
x1.33 at the 4:3 setups it was calibrated on (subtle, and the
glyph-relative tolerances were inflated by the same factor, masking
it), x2.37 at 2560x1080 -- icon-bearing chat lines wrapped a word or
two early per icon. The correct pen-x -> width-units factor is
1/rasterX; the auto-width bail, feasibility band, escalation step and
bisect threshold now derive from fontHPx/rasterX so a "half glyph"
tolerance is an actual glyph width.

2) The substring measure (FUN_00772AE0, new Offsets entry) is now
icon-aware. An earlier note claimed nothing consumed it; its xrefs
refute that: the GameTooltip auto-size measures each WRAPPED SEGMENT of
a wrap-enabled line through it (breaks from FUN_00772B60, already
icon-aware via the stepper hook) and takes the max as the tooltip width
-- so icon-bearing wrapped tooltip lines undersized their tooltip. Same
pen-exact adjustment as the width hook; the editbox caret/selection
callers (10 of its 11 xrefs) keep measuring raw via the established
editable-bit / focused-buffer gates.

3) A string-final icon now reports its INK edge instead of its full
advance (TrailingIconTrimPen: subtract the trail half-pad + half the
outline ink when the text ends in a well-formed span), matching the
engine's own last-glyph convention -- the measure loop ends on ink, not
advance. Render/justify/wrap keep the full advance (the pen genuinely
moves); only the reported width changes. The visible beneficiary is the
money-string shape ("...|TCoin:0|t"): a right-anchored auto-width money
fs sizes to the coin's drawn edge instead of ~2px past it. Remaining
width residual is sub-pixel (region placement rounding + the base
loop's ~0 payload-0 token contribution).
2026-08-19 14:07:01 -05:00
Brues 23b622acff fix(text): snap inline-icon drawn rects to whole render-target pixels
Icon regions placed at fractional pen positions through the anchor
math, so 1:1-sized art (a 16px emote at :16) sampled between texels and
rendered soft. Snap the drawn rect in the flush, gated on the node's
pixel-snap mode (bit-7 clear -- the same condition the engine's glyphs
snap under): position rounds to whole pen px, and SIZE rounds
independently of position so a :16 icon is exactly 16px, never 15/17
from the two edges rounding apart. Floors at 1px.

An integral pen rect survives to the screen because pen px = render
px, the fsLeft/fsBottom terms cancel exactly through the anchor
round-trip (the engine adds the same rect corner back at resolve), and
the pool's width-convergence multiplier is linear.
2026-08-19 13:48:43 -05:00
Brues f806f17f40 fix(text): snap icon advances to pen pixels; make fs measure hooks render-exact
Two changes to the inline-|T pipeline, both anchored in the engine's
own conventions.

1) Post-icon text rendered on half-pixel positions. Native glyphs
always sit on INTEGER pen pixels -- the origin finalize rounds
(FUN_005cdf70) and every glyph advance is truncated (the emitter's
__ftol when node bit-7 is clear) -- but IconAdvancePen added a
fractional advance (w + 1.5 x fontH x 0.18 + ...), shifting every glyph
AFTER an icon onto half-pixel positions: bilinear-filtered, fuzzy or
ghosted post-icon text, with visibility depending on the machine's
filtering config (the "artifacting only on the text after the icon"
report). IconAdvancePen now truncates when the node snaps, the
centre/right justify pre-shift snaps the same way, and the wrap
stepper's shrink probes carry the real snap flag so the budget matches
the render advance exactly.

2) The fs-level GetStringWidth / GetStringHeight hooks now compute the
icon contribution in TRUE PEN PX -- the exact numbers the emitter
reserves, outline ink and snap truncation included -- and bridge it
into the getter's return space via the font height known in both
spaces (sumPen x fontHInt / fontHPen). ResolveFsPenFont replicates the
render chain hop for hop: nodeFontSize = internal x fs+0x7C /
[0x832A48] (the rebuild feeds internal x 0x7C to FUN_0044d420, which
normalizes it through FUN_0041ae50 -- a hop whose omission on first
flight undersized fontHPen ~40%, growing icon-bearing chat lines with
phantom tall-icon overflow and pushing money-tooltip coins off their
right anchor), floored at [0x801628]/rasterY = 2 pen px (the node
ctor), realized by the emitter's own height helper. The outline ink
resolves through face = [[fs+0xE0]+0x20] -- verified stored verbatim at
node+0x44 by FUN_005c1c30 -> FUN_005cd6d0. fs-built nodes are always in
snap mode (no fs-flag maps to node bit 7 in FUN_0044d420), so the
snapped sums are exact for every fontstring. Replaces the old
SetPoint-push-factor bridge, whose units cancelled for :0 icons but
could not express the truncation or the ink.

New Offsets: OFF_FONTSTRING_FONT_HANDLE (0xE0), OFF_FONT_HANDLE_FACE
(0x20), FUN_TEXT_NODE_INVALIDATE derivation notes extended; the 2.0
outline constant's double duty as the minimum font size is documented.
Remaining measure residual: only the engine's own trailing-icon
ink-vs-advance <=1px.
2026-08-19 13:31:46 -05:00
Brues e9407f6564 fix(text): follow text-colour changes on icon-bearing fontstrings
The glue AddonList greys a disabled addon's title through SetTextColor
RGB alone (gold <-> gray, alpha stays 1.0). An icon-bearing title
followed neither channel: the icons only ever mirrored the colour's
ALPHA byte, and the TEXT was frozen at its bake-time colour -- a
segmented (bit-3) node carries baked per-glyph colours, and the
engine's colour setter (FUN_005CCB40) skips the rebuild-invalidate for
bit-3 nodes because UNIFORM bit-3 text recolours live at paint. Plain
titles swapped fine; icon-bearing ones didn't.

Two mechanisms, matching what each colour channel means:

- Text: re-bake on base-RGB change, everywhere. The emitter stamps the
  node's base colour (node+0x2c) at bake; the flush compares it against
  the live value and, on an RGB divergence, calls the engine's own node
  invalidate (FUN_TEXT_NODE_INVALIDATE = 0x005CDEF0 -- exactly what the
  colour setter does for accumulation nodes: clears the built state and
  frees the page buffers, so the next paint re-emits). The re-bake
  recolours base-coloured glyphs while |c runs keep their own colours
  -- baked per-glyph RGB cannot be patched in place. Alpha-only changes
  still take the cheap in-place alpha mirror (fades animate per frame;
  every baked glyph carries the node alpha, so the byte-patch is safe).

- Icons: brightness-follow on the GLUE screen only. The pool's fade
  signal widens from the colour's alpha byte to the whole folded BGRA
  colors[0] dword (FsColorKey), so a pure-RGB SetTextColor now trips
  the change detector at all; FadedColor then scales the icon by the
  text colour's VALUE (max of R/G/B) when no local player exists.
  Value-follow dims but can never tint -- gold and red titles have a
  255-max channel, factor 1.0 -- and in-world icons keep following
  alpha only (retail semantics: guild-green chat must not tint emotes).

Verified on the glue addon list: toggling now swaps title text AND
icons together (gold + bright <-> gray + dimmed), |c-coloured segments
keep their colours through the re-bake.
2026-08-19 13:10:28 -05:00
Brues 968335debe fix(text): place inline icons with the engine's exact pen conversion
Inline |T icon regions were positioned right only at the resolution the
placement math was calibrated on. Root cause: the pen->anchor scale (K)
was derived EMPIRICALLY (node origin / fs rect justify edge) -- chat
could never derive its own (its rect edge sits near screen x = 0 and
failed the divide-guard), so it rode a global cache seeded by whichever
fontstring derived first and clamped to +/-10% forever. Wrong seed =
icon size and position drifting together, amplified by screen distance
(the skull rendering lines away from its chat message).

The engine's own conversion chain, decompiled end to end this session:

  FUN_0041ade0: block/node positions are stored NORMALIZED -- fs-local
    anchor x / [0x832A44] (screen width in anchor units), y / [0x832A48]
    (its previously unmapped y sibling).
  FUN_005cdf70: node origin (+0x70/+0x74) = round(normalized x
    [0xC2B9A4 / 0xC2B9A0]) -- integer render-target pixel dimensions,
    justify shift and vertical align folded in.
  FUN_005c2b50: writes those raster ints from the live render-target
    rect; every font re-rasterizes when they change.

So pen units are render-target pixels and K = raster / anchorExtent,
per axis, from four live globals -- no calibration, no cache, no fs
scale term. Verified against a live probe: rasterX/anchorW matched the
measured origin/rect-edge quotient to four digits, and icons now land
correctly at 2560x1080 and 1024x768 (previously 1080p-only).

Also fixes the coin-into-digits clip the exact K exposed: outlined
faces (pfUI money bars) draw INK past the glyph advance, which the old
miscalibrated K had been masking with accidental slack. The engine
quantifies that ink itself (emitter prologue: face+0x180 bit 3 -> 4.0
pen px, bit 0 -> 2.0, both .rdata constants); OutlineInkPen reads the
same flags and constants, half leading and half trailing every icon,
threaded through the shared advance helper (emitter advance, justify
pre-shift, wrap-stepper shrink probes). The fs-level GetStringWidth
adjustment passes ink 0 (it cannot cheaply resolve the gxu face) --
outlined icon text measures 2-4px short per icon there; render-side is
exact.

New Offsets: VAR_TEXT_RASTER_X/Y, VAR_UI_ANCHOR_SCREEN_H,
OFF_FONTFACE_FLAGS, FLOAT_OUTLINE_EXTRA_THICK/THIN, each with the
derivation chain.
2026-08-19 12:28:30 -05:00
Brues c54556f6a1 refactor: centralize engine field/global access via Game::Read/Ref/Ptr
Replace the raw `*reinterpret_cast<const T *>(base + Offsets::OFF_X)`
idiom (and its double-cast variant when base wasn't already a byte
pointer) with three typed accessors in Game.h:

  Game::Read<T>(base, offset)  field value read
  Game::Ref<T>(base, offset)   writable field lvalue
  Game::Ptr<T>(base, offset)   pointer to a field (arrays / out-params)
  Game::Read<T>(address) / Ref<T>(address)  fixed-VA globals

Pure mechanical refactor, zero behavior change: ~330 cast sites across
84 files collapse to 651 helper calls. Offsets stay in Offsets.h per the
single-source-of-truth rule — the helpers only remove the cast noise and
fold away the inner `reinterpret_cast<uint8_t*>(obj)` base casts.

Left as raw casts by design: FUN_* function-pointer casts, void*/char*
VA handles passed as arguments (caches, method registries), subobject-
anchor pointers fed to __thiscall helpers, `void *volatile` player-ptr
readiness gates (converting would strip volatile), and VA-as-array-base
captures that are subscripted later.
2026-08-19 11:01:19 -05:00
Brues bd14a93a11 fix(text): keep baked glyph alphas in sync with the fontstring's live opacity
Text with an inline |T...|t icon stopped respecting its parent frame's
alpha: the icon faded, the glyphs stayed fully opaque. Iconless text was
unaffected.

Root cause: a fontstring's live opacity (SetTextColor alpha x the frame
chain's effective alpha, re-folded by FUN_0077fac0 on every alpha
change) lands in the node's uniform colour at node+0x2c, which the
paint consults PER FRAME for uniform text. But a segmented icon line
carries baked PER-GLYPH colours (the emitter hook clears node-flag bit
3), which the paint copy-out FUN_005c8710 uses verbatim with no later
modulation -- and FUN_005ccb40 skips the colour-change rebuild for
bit-3 nodes, so those baked alphas never refreshed. On top of that the
emitter hook force-baked alpha 0xFF: a misdiagnosis of the pfUI-bubble
"black text" bug, where the observed 0x07 was the bubble's live folded
alpha at build time (it built while faded out), not a stale default.

Fix, systemic for both bugs:
- Drop the 0xFF force -- colorState's build-time alpha (a node+0x2c
  copy) is already correct.
- Mirror the node's live alpha byte into every baked glyph colour from
  the flush walk, change-detected per page (a byte compare per frame
  until an actual fade). Same signal and cadence as the icon fade
  mirror; bit-3-clear (chat) nodes excluded -- the engine re-bakes
  those on colour change itself.

Adds OFF_TEXT_PAGE_COLOR_COUNT (0x1C), OFF_TEXT_PAGE_COLORS (0x20) and
OFF_TEXT_NODE_COLOR (0x2C) to Offsets.h with the derivation chain.
2026-08-19 10:17:25 -05:00
Brues 6b13368e65 feat(fontstring): backport FontString:SetRotation / GetRotation
Generalizes the region-transform module (formerly texture-only) to serve
the FontString method registry too, backporting the modern
`fontstring:SetRotation(angle [, cx, cy])` and `GetRotation()`.

Rotation is visual only, matching retail: GetStringWidth/GetStringHeight/
GetRect/SetPoint stay axis-aligned. A positive angle is CCW, same
convention as Texture:SetRotation; the optional cx,cy pivot is a superset
of retail (centre-only).

How it works: the text paint copy-out (FUN_005c8710) is translate-only,
so a rotation baked into the node-local glyph verts survives to screen.
SetRotation rotates the live verts immediately (like the texture path)
around the vert bounding-box centre, idempotently via an axis-aligned
baseline snapshot (restore -> rotate). The baseline is re-captured on
every fresh vertex bake, wired through inline-texture's DrawBuilder
co-hook (gated on g_buildEmitSeq > 0 so clean paints never double-rotate,
since inline-texture owns every text-render hook). Node page-buffer
vertex layout added to Offsets.h (cross-verified across the emitter,
FUN_005c8710, and FUN_005ce0c0).

Known limitation: inline |T icons in a rotated fontstring don't turn with
the text (separate anchored regions). Plain text rotates correctly.
2026-08-18 16:54:42 -05:00
brues-code 76f48de67f Inline |T…|t texture escapes (with coin strings, texture methods, and TextureUtil) (#24)
* feat(text): inline |T...|t texture escapes in chat and display text

Backport modern inline-texture markup to the 1.12 text engine: |Tpath:h|t
renders an icon inline in FontStrings / chat, for BLP and uncompressed TGA.

- Rendering primitive: resolve a path to a resident CGxTexture via FUN_0044acf0
  and draw it as a textured quad through the UI text VB path.
- Positioning: co-hook the per-line glyph emitter (FUN_005ccbe0); render plain
  runs by delegating to the original per segment (threading the pen through
  linkState[4], read as a float), record icon quads at the pen, and flush them
  in the paint pass (FUN_005c8fe0) translated by each node origin. Handles the
  FontString pipe-doubling (|T -> ||T), the bit-3 per-call batch-clear mode,
  multi-icon and multi-line accumulation, and font-relative vertical centering.
- Measure/wrap: co-hook the shared tokenizer (FUN_005c2810) so an inline-texture
  span is one near-zero-width token, so icons no longer force early line wrap.
- Editbox exclusion: read the focused-editbox global (DAT_00cf4dc8) and suppress
  icon recording while an input field is focused, so editboxes show raw,
  editable markup while cached display text keeps its icons.

Diagnostic scaffolding (stats/capture Lua helpers) is still present. Follow-ups:
exact icon width in measure (hover-box accuracy), texcoords for sprite sheets,
vertex color, and the already-built editbox case. See docs/InlineTextureEscapes.md.

* fix(text): exclude editboxes from inline textures via node flag bit 6

Editable text (node flags [+0x5c] bit 6 / 0x40 -- verified in-game: the macro
editbox is 0x4D vs chat display 0x20D and FontStrings 0x0D) now shows raw,
editable |T...|t markup instead of rendered icons, checked per node in the
tokenizer, emitter, and flush. This is the 1.12 analog of 4.3.4's per-render
texture-disable flag (tokenizer bit 0x1000).

Replaces the earlier focus-global-only exclusion, which only caught single-line
inputs that rebuild on each keystroke; bit 6 also covers multi-line editors
(the macro editor) that build once while un-focused. The keyboard-focus global
(DAT_00cf4dc8) is kept as a fallback. Removes the failed monochrome heuristic.

Diagnostic scaffolding remains; a docs update and cleanup pass follow.

* feat(text): inline-texture texcoords + fix vertical flip

- Add the width / offset / texcoord fields to the escape
  (:width:offsetX:offsetY:texW:texH:left:right:top:bottom), so a sprite sheet
  such as UI-RaidTargetingIcons can be cropped to a single cell.
- Fix a vertical flip: the UI device backend is OpenGL (bottom-left texture
  origin), so top screen corners map to v1 and bottom corners to v0. The flip
  was invisible on symmetric icons but obvious on directional ones (raid-target
  markers, swords).

* docs(text): document the completed inline-texture RE map

Fold this session's findings into InlineTextureEscapes.md now that the feature
ships: the frame -> renderNode -> group -> node -> line render hierarchy;
segmented-delegation positioning (the float linkState[4] pen read, the bit-3
per-call batch-clear handling, first-line multi-line accumulation); font-relative
vertical centring; the FontString pipe-doubling (|T arrives as ||T); the shared
tokenizer measure/wrap fix; editbox exclusion via node flag bit 6 (0x40), with
the failed focus-global and monochrome attempts recorded so they aren't retried;
and the texcoord fields plus the OpenGL bottom-left vertical flip.

* chore(text): enable inline textures by default on this branch

* feat(text): inline-texture vertex colour tint (:r:g:b)

Parse the trailing r:g:b (0-255) positional fields of the inline-texture
escape and apply them as the quad's vertex colour, so |T...:r:g:b|t tints
the icon (the font stage's default MODULATE COLOROP does texture.rgb x
tint; white = untinted). The bytes pack to 0xFFrrggbb -- the same
0xAARRGGBB order the tokenizer builds for |cAARRGGBB text, verified from
FUN_005c2810's colour branch -- so the value flows straight into the
existing vertex colour slot. Threaded parse -> IconDesc -> IconRecord ->
DrawTexturedQuad. Verified in-game (red/green/blue/white diamonds).

Also record the hover-accuracy (measure-width) verdict in the docs: the
tokenizer reports an icon as ~zero width, so GetStringWidth/wrap/hit-test
undercount it. Scoped by disassembly (FUN_005c6940 width backend,
FUN_005c6b70 per-glyph advance, FUN_005cdc20/FUN_005c7260 wrap): the token
contract has no width field, there is no single cold choke, and the only
fixes are hot per-glyph hooks (against the MinHook-collision guidance) or
~6 parallel measure-loop hooks -- for a mostly-cosmetic gain. Deferred.

* docs(text): record editbox/measure findings; strip inline-texture debug scaffolding

No behavior change — functionally identical to the shipped inline-texture
feature. This captures what a long investigation established and removes the
temporary debug instrumentation added during it.

Comments (src/text/InlineTexture.cpp):
- The tokenizer's `flags & 0x40` gate is load-bearing for RENDER, not just
  measure: a suppressed editbox delegates to the ORIGINAL emitter, which
  re-enters the tokenizer to lay out glyphs, so bit 0x40 (EDITABLE) must make
  the tokenizer stand down or the macro editor draws BLANK instead of raw.
- bit 6 (NodeEditable) and the focus global (InputFocused) are COMPLEMENTARY,
  not redundant: bit 6 catches the un-focused macro editor; the focus global is
  the only signal for single-line focused inputs (chat box, pfChatCopyBox),
  whose nodes lack bit 6 (0x0D/0x20D, indistinguishable from display).
- Removed the tokenizer call/pipe/span counters and the ZZWIDTH TokCap capture
  (debug-only), and the now-unused g_lastFocused/g_lastMono stats fields.

Docs (docs/InlineTextureEscapes.md):
- Editbox exclusion: two complementary signals, and VERIFIED against retail —
  typing `|T` into a chat box or macro editor shows raw there too; only
  addon/system text renders. Our editbox-raw + display-renders split matches.
- Measure gap: added the focus-time caveat (icon ~0 width unfocused; counts the
  literal path text while an editbox is focused — the editbox-raw tradeoff).
- Vertex-colour tint documented in the descriptor-fields section.

* feat(chat): strip player-injected |T icon spoofs from chat + bubbles

Vanilla neutralizes player-TYPED escapes in chat (a typed |c/|H/|T shows
raw); only trusted text (addon AddMessage, shift-clicked links) renders
them. Our Text::InlineTexture backport broke that parity for |T alone: it
detects the neutralized ||T form and draws the icon anyway, so a player
could /say |Tpath|t and put a real icon in everyone's chat AND the speech
bubble over their head. This restores vanilla behavior for |T while leaving
|c/|r/|H/|h exactly as vanilla.

It can only be done at the chat source, not the text emitter: addon |T and
player |T reach the emitter as byte-identical ||T (vanilla doubles the
unrecognized |T for both), so the only place they differ is provenance --
server chat flows through the chat dispatcher FUN_0049A870, addon print does
not. That one function copies the message into a single buffer fed to BOTH
the chat frame and the say/yell bubble spawn (FUN_00608AC0), so sanitizing
on entry covers both. (ECX is the MESSAGE, not the "sender name" the old
note claimed -- verified from the call site in FUN_0049D560.)

Structure mirrors Net::PacketDispatch (one hook, fanned out), since MinHook
allows only one hook per target and this choke point already had the
GUID-capture concern on it:
  - Chat::Dispatch      -- single owner of the FUN_0049A870 hook; orchestrates
  - Chat::IconFilter    -- pure Sanitize(); no hook, no engine state
  - Chat::CurrentGUID   -- GUID globals + getter + DispatchScope RAII (no
                           longer owns a hook)

Defang detail (the subtle bit): the message arrives doubled (||T). Blanking
the PIPE would leave a lone `|` + space -- an INVALID escape the chat frame
tolerates but the bubble text setter chokes on, producing an empty bubble
that fades instantly. So we keep the `||` (a valid literal-pipe escape) and
blank the `T`; for a lone |T we blank both chars. No dangling `|`, no |T
opener survives. Verified in-game: typed |T shows raw in chat and bubble,
addon icons still render, colours and links untouched.

* feat(text): per-editbox inline-texture suppression

Inline-texture rendering was globally suppressed whenever any editbox held
focus (VAR_FOCUSED_EDITBOX != 0), so opening the chat box flipped every
rendered icon/emote in chat history to raw |T...|t.

Replace the global check with per-editbox buffer correlation: suppress inline
rendering only for text that belongs to the FOCUSED editbox, matched by
pointer range against its own text buffers. Chat history keeps rendering while
you type.

The editbox keeps its text in two buffers (both verified via Ghidra), and both
must be matched or the field desyncs (raw width but a rendered icon):
- INPUT buffer ([fe+0x32C]/[fe+0x334], selected by [fe+0x318]&8) — the
  caret/width MEASURE path reads it in place (FUN_0077da80 -> FUN_00772ae0 ->
  FUN_005c6940, which loops the tokenizer).
- DISPLAY buffer (*([fe+0x328]+0xF0)) — a SStrDup'd copy the editbox actually
  RENDERS from (FUN_00771d80); the emitter node text and the re-entrant render
  tokenizer see this one.

TextInFocusedEditbox() bounds each buffer by a tight strlen (distinct heap
allocations -> no false-match cap) and runs only on pipe-leading tokens after a
null-focus short-circuit, so it stays off the hot path. A display FontString
measured while an editbox is focused matches neither buffer, so its icons now
measure correctly -- an improvement over the old global.

Editbox struct offsets centralized in Offsets.h (OFF_EDITBOX_BUFFER_SELECT /
BUFFER / BUFFER_MASKED / TEXT_FONTSTRING).

* feat(chat): raid-target marker substitutions ({rt1}/{skull}/…)

Expand the modern raid-target marker tokens in chat into inline icons, backported
onto the inline-texture renderer. {rt1}..{rt8} plus the named aliases ({star},
{circle}/{coin}, {diamond}, {triangle}, {moon}, {square}, {cross}/{x}, {skull};
case-insensitive) each become a |T escape cropping Interface\TargetingFrame\
UI-RaidTargetingIcons to the matching 64x64 cell (mapping verified against the
client's UnitPopup.lua: col=(N-1)%4, row=(N-1)/4).

Chat::RaidMarkers::Substitute runs in Chat::Dispatch AFTER the |T anti-spoof
sanitize, so players get the fixed, safe marker icons without a path to inject an
arbitrary texture. It emits the pipe-DOUBLED ||T…||t form: the inline emitter
renders both, but this is what survives into speech bubbles — the vanilla bubble
text builder (FUN_004b1600) truncates a lone |T while preserving ||, and pfUI's
bubble reskin copies the bubble's FontString text into its own FontString, which
then renders the icon through the normal paint path. (This is the form bubbles
rendered before the anti-spoof filter defanged the ||T opener.)

InlineTexture emitter fixes for the standalone-FontString (bit-3, batch-clear)
render path that bubbles/tooltips use — chat lines are unaffected:
- Colour: clearing bit 3 switches the engine to per-glyph colour from
  colorState=[node+0x2c], whose alpha byte is a stale ~0x07; force the glyph
  alpha opaque (keeping RGB) so a FontString coloured via SetTextColor with plain
  text doesn't render near-transparent (which showed only pfUI's dark outline =
  "black text"). |c-coloured text already has full alpha, so it's a no-op for chat.
- Horizontal justify: the engine positions centre/right-justified text using the
  MEASURED width, which counts inline icons as ~zero (the measure gap), so the
  rendered line overflows its box. Pre-sum the line's icon widths and shift the pen
  (half for centre, full for right) so text+icons justify as a unit.
- Default centerFrac 0.5 -> 0.6 (better vertical centring across chat + bubbles).

* fix(text): suppress inline textures in editboxes by content match

The per-editbox suppression missed the chat input box: a pasted `|T…|t` rendered
as an icon instead of raw markup. An in-game probe showed why — the editbox
renders its text through a TRANSIENT copy: same bytes as the input buffer, but a
distinct heap allocation with no pointer link to the editbox in either direction
(every offset/back-pointer scan of fe / its FontString / the render node came back
-1). So the prior pointer/node-identity checks (input buffer, SetText copy,
FontString +0x48, node == *(fe+0x328)) could never match the render.

Match on CONTENT instead:
- Emitter: EmitLineIsFocusedEditbox compares the render line's bytes against the
  focused editbox's input buffer (the emitter is handed the whole line, so a
  bounded strcmp identifies it). Chat-history lines differ, so their icons keep
  rendering while an editbox is focused.
- Measure (caret/GetStringWidth): unchanged pointer path — the tokenizer reads the
  input buffer in place, so TextInFocusedEditbox still matches by range.
- Re-entrant render: the suppressed emitter brackets its delegated raw layout with
  a text range (g_reentryLo/Hi); the tokenizer stands down across the whole span
  via TextInReentry, so `|T` isn't eaten as a zero-width token (which drew BLANK).

Drops the dead node-identity/second-and-third-buffer heuristics. Covers any focused
input (chat box, pfChatCopyBox, macro editor).

* fix(text): drop stale icon records for reused chat line FontStrings

Inline-texture icons could paint as a ghost strip at the bottom of the screen
after chat had been busy for a while. The chat frame reuses its line
FontStrings: when a line is cleared (text set empty) or reused for markup-free
text, the draw builder early-returns on it, so the emitter never runs — and so
never erases that node's old icon record. The paint flush still walked the node
and drew its now-stale record at the FontString's parked position.

Gate the flush draw on the node's LIVE text still containing `|T`: if a node has
an icon record but its current text has no markup, the record is stale — drop it
and skip drawing. Kills the bottom-of-screen ghost.

(The separate scroll-freeze — icons only refreshed on the chat's dirty repaints —
is a different, deeper issue tracked next.)

* fix(text): stop chat icons vanishing — suppress only input boxes, not editable chat display

pfUI renders the chat scrollback through EDITABLE nodes (flags 0x45: bit 6
editable, no bit 3). The inline-texture emitter's blanket NodeEditable gate
suppressed inline rendering for ALL editable nodes, so those chat icons blanked
whenever that display was live — during scroll and as messages arrived, which
read as icons "disappearing/reappearing."

Gate suppression on a true INPUT box instead: editable (bit 6) AND bit 3 (0x08).
Macro editor 0x4D and name/chat input 0xC8 all carry 0x08; the chat scrollback
0x45 does not — so real input boxes still show raw |T markup while the chat
display keeps its icons. Also drop the flush's NodeEditable draw-gate: a
suppressed input box never records, so any record reaching the flush is a real
display line.

Pointer/content match alone can't cover a focused input box because its render
form is pipe-doubled (||T) while the input buffer is single-pipe, so the compare
misses.

* feat(text): inline |T icons as fontstring-anchored engine regions

Port 4.3.4's CSimpleEmbeddedTexture model. Each icon the emitter records
becomes a pooled CSimpleTexture ANCHORED TO ITS OWNING FONTSTRING,
configured off-render on the WorldTick, and drawn by the engine's own
region pipeline. 1.12 chat lines are real CSimpleFontStrings (the
ScrollingMessageFrame display refresh FUN_00788750 drives one per visible
line), so a co-hook on CSimpleFontString::RebuildString (0x7724A0) maps
every text node to its owner and one mechanism covers chat, tooltips, and
standalone FontStrings.

This replaces the raw-GxU-quad renderer and every overlay attempt:
- engine-drawn regions keep their textures resident: no flicker, verified
  across three concurrent clients
- the anchor system moves icons with their lines: scroll costs nothing
- icons mirror the owner's shown state: faded lines hide their icons
- all engine mutation happens outside the render pass: no pending-layout
  corruption, survives /reload (pointers dropped in PrepareForReload)
- placement verified pixel-exact against owner rects

RE landmarks recorded in Offsets.h:
- fs+0xF8 is an HTEXTBLOCK handle; the text node is at handle+8
- Show (0x77FCB0) no-ops unless desired-shown (+0xC4) is set, and
  SetParentAndLayer(show=0) clears it on reparent
- the renderer draws the corner array (+0xD4), stored from the rect by
  SetTexCoord - realize (0x768060) must run between SetPoint and
  SetTexCoord or the corners go stale (the historical invisible-icon and
  frozen-top-left-icon bugs)
- pen coords are y-down from the owner fontstring's BOTTOM edge; anchor
  offsets use Script_SetPoint's pixel scale (LinePool::PixelToInternal)

* refactor(text): inline |T icons = pixel-perfect quads + residency holders

Replace the fontstring-anchored region approach with a hybrid that
decouples position from residency, because the two live in different
coordinate spaces that no single scale could reconcile:

- POSITION: draw each icon as a raw GxU quad in the text engine's own
  render space (pen + node origin), the same coordinate system and
  dynamic VB the glyphs use. Pixel-exact by construction — no anchor/
  layout-space conversion. This is the original quad math; the region
  detour proved pen-space and anchor-space differ by the text paint's
  projection, not a scalar, so region anchoring could never be exact.

- RESIDENCY: a raw quad binds an unowned texture the engine evicts under
  VRAM pressure (the flicker on scroll / blank on a 2nd client). So for
  each distinct texture path, Text::InlineTexturePool creates ONE managed
  CSimpleTexture, draws it every frame (a ~2px, alpha 1/255 corner box),
  and never touches it again — its engine-managed draw is the live
  reference that keeps the texture resident for the quads to bind.

Verified in-game: icons pixel-perfect across chat / bubbles / wrapped
lines / sizes / tint, no flicker on scroll, and two concurrent clients
both render — the residency-holder premise (untested before: the earlier
"disproof" had non-drawing holders) finally validated with a holder that
actually draws. Non-zero holder alpha is load-bearing: a fully
transparent region gets culled and residency is lost.

Diagnostics (probe, perf counters, scale/bias tune knobs) stripped; the
SEH fault guard on the flush stays.

* feat(text): render inline |T icons as engine regions anchored to their fontstring

Replace the raw-quad + residency-holder hybrid as the default renderer with
the 4.3.4 CSimpleEmbeddedTexture model: one pooled CSimpleTexture per visible
icon, anchored RELATIVE TO THE OWNING FONTSTRING. Engine-drawn, so texture
residency (the chat scroll flicker / blank 2nd client) is impossible by
construction; engine-anchored, so icons track their line for free.

The pen<->anchor bridge that unblocked this: RebuildString (0x7724A0)
multiplies every text-unit quantity by fs+0x7C when creating the text node,
and the node origin is the fontstring's justification anchor point mapped by
a single measurable scale K (verified with two-position probes: origin =
rectJustifyRef x K, K ~ 1470 = physical px per anchor unit, both axes, no
drift). Placement pipeline:

- RebuildString co-hook records node -> owning fontstring (a node only
  speaks for its fs while it IS fs+0xF8->block+8, killing the stale-node
  clear race around rebuilds).
- The paint hook converts each icon's pen-space quad through K and queues
  fs-relative placements; regions are keyed BY FONTSTRING (nodes die on
  every SetText - node keying orphaned regions into an accumulating wall).
- Placements apply on WorldTick, never mid-render. SetPoint offsets are
  divided by the region's effective scale (+0x7C; anchor resolution
  multiplies stored offsets by the scale chain - measured 0.0319 stored ->
  0.0290 resolved = x0.91), then converged exactly by a per-region rect
  readback correction each tick (deterministic, self-healing; a same-call
  readback read stale pooled rects and shipped 7.4px crests).
- Engine SetTexCoord (0x770410) takes the 4-float rect Y-FIRST INTERLEAVED
  {v0,u0,v1,u1} (diagnosed in-game: {u,v,u,v} rendered the raid-mark moon
  as the circle cell); it is absolute, and the +0x124 shrink-by-UV-span
  flag stays clear so crops stretch to the rect like modern clients.
- Expired/hidden lines are swept every tick (regions parent to the chat
  frame, not the line, so they cannot inherit the line's own hide).

The quad renderer and residency holders remain behind
_classicapi_InlineTexMode (0 = quads, 1 = regions [default], 2 = overlay
A/B) as the bring-up oracle, plus diagnostics (_classicapi_InlineTexProbeFS
/ RegionDump / RegionCal / HolderCfg). Calibrated residual: RegionCal
(3, -1) pen units.

* fix(text): apply the inline-icon LEAD pad at draw time

The emitter reserves w + 1.5x pad in every inline icon's advance (lead 1x,
trail 0.5x), but FlushLayout drew the icon at the raw pen - all reserved gap
landed AFTER the icon, none before. Mid-text icons looked balanced only
because their surplus trailing gap padded the following text; a string-FINAL
icon (the money-string copper coin) sat jammed against its digits, and the
locale format strings had grown per-coin offsetX hacks to compensate.

Draw at pen + w x iconPadFrac (quads and regions share the cx), matching the
emitter's reservation. The coin formats drop to zero offsets - verified
against the texture itself: the three coin arts in UI-MoneyIcons are
byte-identical in alpha (same bounds, same center of mass, measured from the
exported BLP's DXT3 data), so no coin ever needed a positional nudge.

RegionCal's baked x constant drops 3 -> 0: the +3 calibrated pre-fix was
exactly this missing lead pad (user re-calibrated (0,-1) post-fix). The 1px
y residual remains the pen->anchor map's one true constant.

* fix(text): make inline-icon state lifetime-exact; fix every scroll-landing loss

Chat icons randomly landed shown-or-hidden when lines scrolled, and stale
icons ghosted at parked positions. Root causes, each found by in-game
triangulation (FsDump/Broken/Stats diagnostics, included), all fixed:

- Placements are FS-RELATIVE, computed at PAINT time in one coherent
  snapshot (icon coords + fs rect in the same flush). The old apply-time fs
  rect read raced the chat relayout after SetText and parked icons off
  their line, where the dedup froze them.
- The queue tail gate now matches the per-icon build gate EXACTLY (incl.
  K); any not-ready input skips-and-retries instead of queueing {} - an
  empty queue froze lines iconless via the dedup (early-session K window).
- K (pen->anchor scale) is derived PER NODE from its own fontstring - pen
  space scales with each fs's frame-scale chain, so a global chat-derived K
  mis-sized icons on differently-scaled fontstrings. Global cache kept as a
  +/-10%-clamped fallback.
- Stuck-blockless fontstrings (RebuildString releases the block on a
  SetText that lands on an unresolved rect and never rebuilds; the zombie
  node keeps painting) are re-dirtied so the engine rebuilds - the icon
  pipeline then resumes naturally.
- First-line-of-build detection comes from a draw-builder co-hook
  (FUN_005CDC20) build stamp - exact - with the old text-pointer heuristic
  only as fallback for emitter paths outside the builder.
- THE LIFETIME FIX: co-hook the gxu text-node free (FUN_005CD950, the
  single site where every node dies and its address becomes reusable) and
  erase ALL per-node state there. Anything in the maps now refers to a
  live node by construction: inherited ghost records on recycled nameplate
  fontstrings, orphaned owners (dropNoFs 61k -> 0), and reload leftovers
  lose their mechanism of existence.
- Ghost guard rescans the FONTSTRING's text (fs+0xF0, proven trustworthy),
  not the node text pointer (which lied on pfUI chat lines and made the old
  scan erase LIVE records every frame - the persistent iconless LFG lines).
  False matches can only false-keep, never false-erase.
- Freshness TTL: regions stay only while the paint keeps re-queueing their
  fontstring (deduped touches count); parked/orphaned fs regions expire in
  ~1s. Do NOT build-version records against the builder counter - the
  builder runs every paint but only emits when dirty, so a version check
  erases good records on every clean paint (the all-icons-gone regression).

Diagnostics added (Lua): _classicapi_InlineTexFsDump (pipeline triangulation
with chain classification), _classicapi_InlineTexBroken (names the broken
lines), _classicapi_InlineTexStats gains queued/drop/nudge counters and the
SEH fault address.

Also removes the FrameTick glue-screen attempt (b164d68): hooking the UI
render root regressed in-world chat; glue-screen icon support will be
re-approached without touching the in-world render path. The
FUN_UI_RENDER_ROOT offset stays documented for that retry.

* fix(text): pointer probes must allow Large-Address-Aware heap (>2GB)

LooksReadable capped plausible pointers at 0x7FFF0000. This client is LAA
(VanillaFixes), so heap allocations above 0x80000000 are valid and routine
once the heap grows - and the flush's layout walk BREAKS on an "unreadable"
node, so a single high-heap node silently truncated the walk and every node
AFTER it in the layout list lost its icons. That was the irreducible random
per-ROW missing-chat-icon bug that survived every renderer architecture
since the guard shipped with the first inline-texture commit (aa94ea5): it
fired only when the allocator placed a node/fontstring above 2GB, varying
per session with addon load and uptime. The same check also rejected
high-heap fontstrings (dropNoFs storms, "unreadable" owner chains).

Bound raised to 0xFFFF0000 in both copies.

Diagnosed with the per-node build/emit instrumentation added here: the
smoking-gun Broken() trio was builtKnown=1 (engine built the node),
emitOutcome=8 (emitter recorded its icons), nodeSeenAge=-1 (our walk never
once saw it). _classicapi_InlineTexBroken now reports both new fields.

* feat(text): render inline |T icons on the glue (login) screen

Inline icons never appeared on the login / character-select screens: the
text-pipeline hooks are engine-generic and fire on glue (the |T spans are
consumed there), but InlineTexturePool::Maintain - the step that creates and
shows the icon regions - was driven by Tick::WorldTick, and FUN_WORLD_TICK
(0x0066FD50) is the world-simulation tick, silent on glue. Queued placements
were never applied.

Add Tick::FrameTick, hooked at FUN_UI_RENDER_ROOT (0x00764330) - the
CSimpleTop singleton's per-frame render callback, registered by both the
world-init (FUN_0048FBF0) and glue-boot (FUN_0046A7B0) paths and drained
every frame by the master scene-render pump. Subscribers run at the tail of
the callback (strata walk complete, no frame mid-draw). The pool's Maintain
moves onto FrameTick as its ONLY tick: one driver, fires wherever the UI
renders.

An earlier version of this change was blamed for an in-world chat regression
and reverted. That regression was the Large-Address-Aware pointer-bound bug
(dc61f77) rolling its allocation dice at the moment the tick moved - the
symptom persisted after the revert, which already exonerated the hook.

Glue boot (LoadGlueScriptFunctions_h) now also clears the inline-icon maps:
the world->glue teardown bulk-frees every world fontstring and text node they
reference (glue->world was already covered by FrameScript_Initialize_h, and
the node-free hook covers individual deaths in both states).

WorldTick keeps its world-only subscribers (aura eviction, cast state, raid
targets) - they read world state that is null on glue; the two ticks stay
semantically distinct: WorldTick = "world advanced", FrameTick = "a UI frame
is rendering".

* feat(text): icon-inclusive GetStringWidth + FontString:GetStringHeight backport

GetStringWidth now counts inline |T...|t icons. The old "deliberate
measure gap" analysis was right that the gxu engine has no cold choke
(parallel measure/wrap/hit-test loops, no width field in the token
contract, hot per-glyph helpers) - but the choke sits one level up:
FUN_00772890 = CSimpleFontString::GetStringWidthInternal, a cold,
MinHook-safe funnel for exactly 4 callers (Script_GetStringWidth,
GameTooltip auto-size, editbox caret positioner, effective-width
vmethod). The co-hook calls the original and re-adds the icon advances
the tokenizer hook hid, so measured width matches rendered width - and
tooltips/auto-width layout now size correctly for icon lines.

Shared-source refactor so measure and render can never disagree:
- InlineInterceptActive: the tokenizer's stand-down set factored into
  ONE predicate (tokenizer passes gxu flag 0x40; the width hook passes
  fs+0x120 & 0x1000, the fs-level bit FUN_0044D670 translates into it,
  so editbox carets keep measuring raw markup).
- IconAdvancePen/SumIconAdvances: the emitter's reserved advance
  (w + 1.5*pad + positive offsetX) factored out and shared by the
  emitter loop, the justify pre-shift, and the width hook. Side fix:
  the justify pre-shift previously omitted the positive-offsetX term.

Units (bit us on first flight): escape sizes are UI pixels; convert
px->anchor by the push factor K = [0x832A4C]*1024/[0x832A44] (~1468),
NEVER by fs+0x7C - that's the layout UI scale (~0.68), and dividing by
it measured a 16px icon as +44k px. The hook never writes the fs+0xFC
cache (original may serve cached; the sum is re-added per call).
Verified in-game: delta +19.5 for a 16px icon = 20.32 exact advance
minus the known 0.8 trailing-icon ink-width residual. Wrap-break,
substring measure, and hit-test stay icon-blind (documented).

FontString:GetStringHeight() (2.3.0+ binding) backported in new
src/fontstring/Metrics.cpp: 1.12 already ships the internal wrap-aware
getter FUN_007729B0 (cache fs+0x100, lines*fontH + (lines-1)*spacing,
same wrap engine the render uses, empty -> 0) - it just was never
bound. Registered on the FontString method registry; mirrors
Script_GetStringWidth's resolve + anchor->px push conversion.
Verified in-game: one-line 11.7, wrapped 46.9 (4 lines), empty 0.

* fix(text): wrap lines account for inline icon advances

Wrap decisions measured inline |T icons as ~0 (the tokenizer hook), so
icon-bearing chat lines broke as if the icons weren't there and the
emitter's real advances ran past the frame's right edge.

Choke: FUN_TEXT_WRAP_STEPPER (0x005C7260), the wrap-stepper dispatcher
that lays out one wrapped line per call. Its exactly 4 callers are
every wrap consumer - the draw builder (render breaks), the height
measure (GetStringHeight), the chars-that-fit counter (ellipsis), and
the break-array computer - so one co-hook keeps render, height,
truncation, and break arrays mutually consistent. outBreak and
outNext-text are byte counts (==len means "all fit"); outWidth is the
measured icons-at-zero line width in the caller's units.

The hook shrinks the wrapWidth argument by a minimal feasible shrink,
found by probing the stepper sandboxed (local out-params + a copy of
the p10 first-line state byte): feasible(s) iff the line's icon
advances fit in the shrink plus the spare the break left
(iconSum <= s + probeW - outWidth). s=0 feasible -> no shrink (the
common fits-anyway case); otherwise escalate by the measured deficit,
then bisect the [infeasible, feasible] bracket to a quarter-glyph
(<=8 probes). Never overflows; packs each line to its physical
capacity. Gated on the shared InlineInterceptActive predicate + the
editbox flag bit 0x40 the dispatcher already carries.

Unit trap #2 (cost one flight): each caller passes fontH/wrapWidth in
its OWN space - node text units from the builder, the small
anchor-converted space from the fs-level callers chat wraps through.
px -> caller units = fontH / FUN_TEXT_FONT_HEIGHT(flag, fontH), the
engine's own pixel realization of the fontH param (FUN_005C6940's
final scale proves the convention for every gxu caller).

Rejected en route (documented in docs/InlineTextureEscapes.md): raw-px
subtraction (shredded lines to 2-glyph fragments), whole-remaining-
text sums (8-icon line -> one word per line), icon-count fixed-point
iteration (oscillates - 55-byte zero-width escapes make the
break<->count coupling discontinuous), max/average tiebreaks.

Cross-checked against 4.3.4 (renders |T natively): Blizzard extended
the token contract instead - texture token type 7 + a shared parser
(FUN_00617ba0) called inline by all five layout loops, fontH passed in
for :0 defaults, plain width, no padding. No single-choke trick exists
at source level; the probe search is the 1.12-shaped equivalent.

Diagnostics: _classicapi_InlineTexWrap(n) dumps the last 8
icon-bearing calls (widths, per-probe sums/breaks/raw out-params,
final shrink, floor hits).

* fix(text): wrap-shrink search refinements from in-game shakeout

Three fixes to the minimal-feasible-shrink search (2450522), each from a
live regression the _classicapi_InlineTexWrap diag pinned down:

- Full bracket bisection (<=8 probes, quarter-glyph epsilon). The first
  cut abandoned the [infeasible, feasible] bracket after one stale
  escalation candidate, costing the Marks harness line a whole
  mark+word pair per line (3+5 instead of the optimal 4+4).

- Half-glyph feasibility tolerance. The width hook and the wrap hook
  derive the icon sum through different unit chains (FUN_007727B0xK vs
  FUN_005C6FA0 ratio, OUTLINE extras, the trailing-glyph ink/advance
  quirk); the drift can read "fits exactly" as "1px over" and shrink a
  zero-slack line. Genuine icon overflow is >= a full icon, so half a
  glyph separates drift from real overflow.

- Auto-width bail (all text fits at s=0 AND slack <= 1.5 glyphs). A
  single-anchor, no-width fontstring (pfUI's addon-list labels) wraps
  at its own text-only measure plus a ~1-glyph engine margin (measured
  1.07xfontH), so icons "never fit" its budget - but the box is
  synthetic, icons draw past it harmlessly, and any shrink FABRICATES a
  wrap ("Twitch Emotes" split across two lines). Real frames stay
  covered: overflowing lines break, fitting lines carry frame-sized
  slack (Marks measures ~3.5xfontH). The narrow give-up band - text
  within 1.5 glyphs of exactly filling a real frame - reverts to the
  pre-hook overflow, bounded by the line's icon sum.

Diag reshaped for /dump's ~30-value print cap: 8 numeric headers plus
ONE pass-summary string (shrink candidate, icon sum, line length, raw
outBreak/outNext/outWidth per probe), so no record truncates.

* feat(texture): add Texture:SetRotation via corner-vertex rotation

Backports the modern texture:SetRotation(angle [, cx, cy]) method, which
vanilla 1.12 lacks entirely.

4.3.4's SetRotation (Script FUN_0052cb50) rotates the four texture
COORDINATES around a centre and feeds the 8-arg SetTexCoord, which clips
the corners of an off-axis square. 1.12 can't mirror that — its
CSimpleTexture::SetTexCoord takes only a min/max UV rect.

1.12 has a cleaner seam: a CSimpleTexture stores its drawn quad as four
independent corner positions at +0xD4, and the draw enqueue (FUN_00772fd0)
hands region+0xD4 straight to the vertex batch as four free vertices — no
axis-aligned rect is re-derived. So rotating those four corner positions
draws a truly rotated quad with no corner clipping.

The engine fills the corners axis-aligned from the layout rect via
FUN_REGION_STORE_CORNERS; a co-hook there re-applies rotation right after
each store, so a static rotation is written once and costs nothing per
frame while moves/resizes re-rotate automatically. Angle is radians
(positive = counter-clockwise); optional (cx, cy) is a normalized pivot
in [0,1], default centre; an angle of 0 clears.

Per-region state keys on the raw region pointer and is cleared on /reload
and world->glue (Texture::Rotation::PrepareForReload). A texture freed and
instantly re-pooled mid-session could briefly carry a stale rotation —
accepted; a destructor-evict hook is the later hardening.

New in Offsets.h (all verified against WoW.exe): OFF_SIMPLETEXTURE_CORNERS,
FUN_REGION_TEXCOORD_CROP, FUN_REGION_GET_RECT.

* feat(texture): add Texture:SetVertexOffset, generalize corner transforms

Backports Texture:SetVertexOffset / GetVertexOffset (plus GetRotation),
generalizing the SetRotation module (texture/Rotation.* -> texture/Transform.*)
into one corner-transform primitive that backs both methods.

Both write the four drawn corner POSITIONS at region+0xD4 — the vertices the
draw enqueue FUN_00772fd0 hands straight to the batch; no stock 1.12 function
exposes them. Per-region state widened from an angle to {rotation, four vertex
offsets}, applied through the same FUN_REGION_STORE_CORNERS co-hook: after the
engine writes the axis-aligned corners, rotate about the pivot, then add the
offsets. The two transforms compose (matching retail) and persist across layout
resolve / move / resize / SetTexture with no per-frame cost.

SetVertexOffset offsets are UI coordinate units (like SetPoint x/y), converted
to the engine's internal layout space with the same factor Tooltip::LinePool
uses; +y is up. vertexIndex maps to a corner via VertexSlot; the
UPPER_LEFT_VERTEX / ... constants are defined FrameXML-style in the embedded
addon's Util/Constants.lua.

Non-inverting warps (perspective, skew, trapezoid, wave) are free; a warp that
mirrors the quad past edge-on inverts its winding and the region draw culls it
(documented).

* feat(texture): add Texture:SetColorTexture

Backports the 7.0 SetColorTexture(colorR, colorG, colorB [, a]) as a second
name on the engine's own Script_Texture_SetTexture handler (0x0079BB40): its
numeric branch already clamps r/g/b/a to [0,1] and fills a solid colour via
FUN_00770360 (the string branch loads a path). So SetColorTexture is exactly
vanilla's numeric SetTexture form under the modern name — zero reimplementation,
with the clamp and opaque-alpha default coming straight from the engine.

The alias also accepts a path string (a harmless superset of the retail
contract). SetDesaturated / IsDesaturated are already native (real Desaturate.bls
pixel shader); SetDesaturation is not addable — vanilla desaturation is a fixed
effect handle with no strength constant in the setter, draw command, or effect
table.

* fix(text): correct the emitter's lazy pen read-back; drop quad render mode

The inline-icon emitter hook threaded the pen between text runs by
reading the engine's linkState[4] after each delegated run. That value
is LAZY (verified in FUN_005ccbe0): the engine places each glyph at
pen + pairAdvance(prev, cur) and its final write re-adds the LAST PAIR
as a stand-in for the last glyph's own advance. For a one-glyph run the
stand-in is 0 (no pair exists), so the run read back as zero-width and
the icon drew on top of the digit — the money-string "coin covers the
lone 0/1" bug. For "] 1" the stand-in was the space's advance, ~3px
short: the single-digit clip. "11" matched by luck (same-glyph pair).

Fix (the 4.3.4 model — FUN_0061ea10 case 7 computes the pending last-
glyph advance explicitly instead of trusting a stored pen): drawRun now
token-walks each run with the engine's own tokenizer and, when it ends
in a glyph, replaces the stand-in with the truth:

  pen = linkState[4] - pairAdvance(prev, last)*scale
                     + baseAdvance(last)*scale

using the engine's own advance functions (FUN_005ca240 base,
FUN_005ca2d0/FUN_005ca4b0 pair, per the node's kerning flag) and its
per-placement __ftol snap. Runs ending in a non-glyph token (trailing
|c/|r) need no correction — the trailing iteration already folded the
last glyph's base advance into the write.

Also:
- The per-icon breathing pad is now FONT-relative (fontH * padFrac),
  not icon-width-relative: the gap no longer scales with icon size, so
  a small icon doesn't jam its neighbour while a big one floats.
- Quad render mode is removed entirely (DrawTexturedQuad, residency
  holders, _classicapi_InlineTexMode/_InlineTexHolders/_InlineTexHolderCfg).
  Engine regions (the 4.3.4 CSimpleEmbeddedTexture model) are the only
  render path.

* feat(currency): GetCoinTextureString / C_CurrencyInfo.GetCoinTextureString

The retail coin-icon money string, backported as a C function
(src/currency/CoinText.cpp) the way retail ships it (behaviour from
3.3.5's Script_GetCoinTextureString FUN_00510d00): split copper into
gold/silver/copper, emit only non-zero denominations in that order,
zero shows "0<copper>". Each denomination formats through the
GOLD/SILVER/COPPER_AMOUNT_TEXTURE GlobalStrings, backported in the
embedded addon's locale layer (stock 1.12 doesn't have them), so
locales can override.

1.12 has no per-coin icon textures — the |T markup crops vanilla's
UI-MoneyIcons 4-cell sheet (gold 0:1, silver 1:2, copper 2:3; the
three coin arts are byte-identical in alpha, verified by decoding the
exported BLP's DXT3 data). height/width 0 = size to the display
font's height (the retail default, honoured by the inline-texture
renderer). No offsetX nudges and no separator spaces: correct spacing
comes from the renderer's font-relative pad plus the lazy-pen fix
(550cf5e) — per-coin offsets were compensations for that bug and must
not return.

FormattingUtil.lua comment updates only (GetMoneyString stays the
text-symbol form; the coin form now exists). docs/API.md: new
Currency section.

* docs(readme): list GetCoinTextureString in the API table

* refactor(text): purge the quad-mode leftovers

Follow-through on 550cf5e (quad render mode removed): delete everything
that existed only for the raw-GxU-quad path and no longer has a single
reference.

- Offsets.h: drop the GxU device primitives (dynamic-VB lock/data/
  submit/unlock, texture bind, vertex stride/selector), the standalone
  path->CGxTexture loader trio (FUN_TEXTURE_LOAD_BY_PATH,
  PTR_TEXLOAD_DESC_VTBL, FUN_GX_TEXFLAGS_INIT), the colorop render-state
  and direct-D3D state setters, FUN_TEXTURE_FORCE_DECODE, and
  FUN_TEXTURE_GET_RENDERABLE. All were quad/residency-era scaffolding;
  the VAs stay recorded in docs/InlineTextureEscapes.md and git history.
  FUN_TEXT_PAINT (the flush co-hook site) and VAR_TEXTURE_BLEND_DEFAULT
  (the pool's SetTexture blend arg) remain, with comments rewritten for
  the region path.
- InlineTexture.cpp: drop IconRecord.z / penZ (only the quad draw read
  them); rewrite the paint-flush section comments to describe what the
  flush actually does now (queue fontstring-relative region placements).

* feat(addon): backport TextureUtil.lua (Blizzard_SharedXMLBase)

The non-atlas slice of the Classic Era reference, ported to Lua 5.0
(string.format instead of string-method syntax):

- SetClampedTextureRotation / ClearClampedTextureRotation — the retail
  90-degree-step texcoord shuffle with width/height swap. Works
  unchanged because 1.12's Texture:GetTexCoord() natively returns the
  8-value corner form and SetTexCoord accepts it (both operate on the
  same engine corner array, verified at Script_Texture_GetTexCoord
  0x0079BDF0). One deviation, commented in-file: Clear also nils
  rotationDegrees — the reference leaves 0 behind, which is truthy in
  Lua and breaks the next Set's origTexCoords re-capture.
- GetTexCoordsByGrid — pure math.
- CreateTextureMarkup / CreateSimpleTextureMarkup — |T markup builders;
  output renders via the inline-texture backport.
- TextureUtil = {} for namespace parity.

Omitted: everything atlas-based (CreateAtlasMarkup*, the TextureKit
family, CheckSetAtlas, GetAtlasSize, SetTextureWithAddressModeOptions —
1.12 has no atlas system), the LFG role-icon tables, and
GetTextureInfo (reads the atlas/fileID getters).

* refactor(text): remove the inline-texture bring-up diagnostics

The pool's _classicapi_InlineTexRegionDump / _InlineTexFsDump /
_InlineTexBroken were bring-up triage for the scroll-landing /
ghost-icon bug class, which the node-free lifetime hook ended
(b5df20d) — they have no remaining job. Removing them also kills their
entire support tree, none of which had another consumer:

- the five Debug* chain-state exports on Text::InlineTexture
  (DebugChainState / NodeFlags / NodeSeenAge / NodeBuiltKnown /
  NodeEmitOutcome),
- g_nodeSeen + g_flushSeq (flush visit stamps),
- g_nodeEmit (per-node emitter-outcome tracking — map churn on every
  emitted line, purely diagnostic),
- g_nodeBuilt + g_buildCounter + NodeIcons.builtSeq (write-only: the
  build-version check they were made for was deliberately REJECTED —
  the builder runs every paint but only emits when dirty, so version
  mismatches on clean paints erased live records). g_buildNode /
  g_buildEmitSeq stay — they are the live firstLine detection.

NodeIcons collapses to a plain std::vector<IconRecord> map value, and
the pool drops its Game.h / InlineTexture.h includes (nothing left
uses them). The stale "versioned by build" struct comment is rewritten
to describe the actual invariant (node-free hook + firstLine erase).

Kept: _classicapi_InlineTexEnable / Suppress / Tune / Stats / ProbeFS /
RegionCal / Wrap — the live control surface and field telemetry.

* refactor(text): reduce the inline-texture Lua surface to the kill switch

Only _classicapi_InlineTexEnable remains — the feature toggle the SEH
latch pairs with. Removed with their entire backing state, none of
which had a non-diagnostic consumer:

- _InlineTexSuppress + g_suppressInline (the manual global override —
  editbox exclusion has been per-node/per-buffer for a while) and the
  now-unreferenced InputFocused() helper
- _InlineTexTune: g_vBias / g_sizeScale / g_centerFrac / g_iconPadFrac
  become constexpr (calibrated during bring-up, fixed now)
- _InlineTexRegionCal: g_regionCalX/Y become constexpr (0 / -1)
- _InlineTexStats + the six flush-gate counters (the queue gate
  if/else collapses to the plain condition; the nudge drops its
  counter-guard and just sets the dirty bit — idempotent)
- _InlineTexWrap + the WrapDiag ring and every capture site in the
  wrap-stepper hook (the minimal-feasible-shrink algorithm is
  untouched — it always ran on locals)
- _InlineTexProbeFS (the pen<->anchor bridge verification probe)
- the SEH filter no longer records fault code/address (nothing read
  them); the latch still disables the feature on a flush fault
- the Arg() Lua helper and <cstdio> (last users removed)

* feat(text): inline icons fade with their chat line

The one visible seam left in the region renderer: icon regions parent
to the CHAT FRAME (regions cannot parent regions), so they inherited
the frame's alpha but not the LINE's — a fading chat line's text
dimmed while its inline icons stayed opaque until the end-of-fade
hide.

RE (verified in the 1.12 binary): chat fading is engine-side in the
ScrollingMessageFrame's fader FUN_00788460 — gated on the SetFading
flag (smf+0x360; the 40-method SMF registry's SetFading 0x007939A0
writes it), it counts down each visible line's timeVisible then
fadeDuration ({rgba@+4, shown@+8, timeLeft@+0xC, fadeLeft@+0x10} in
the stride-0x10 line array at smf+0x3A4) and animates the LINE
FONTSTRING's color alpha byte through the fs SetColor (0x0077F750)
every frame, hiding the fs at zero. SetColor stores the dword at
(*(u32**)(fs+0xB8))[0] (count fs+0xB4; alpha = byte 3), and the
per-line setter FUN_00788af0 resets alpha to 0xFF on message reset —
so that byte IS the line's live fade state, whoever wrote it.

The mirror (InlineTexturePool): Maintain reads FsColorAlpha(fs) each
tick and, on change only, rewrites the shown regions' colors with the
markup tint's alpha modulated by the line's alpha (RGB preserved).
ApplyPlacement folds the live alpha in at placement time, so a line
placed mid-fade starts at the right opacity. Composition is exact by
construction: the fs's on-screen alpha is frameAlpha(+0xC8) ×
fsColorAlpha, and the regions share the same parent frame, so
mirroring the fs byte alone makes icon and text alpha identical.
Steady state costs one byte compare per icon-bearing fontstring per
tick; scroll-back/un-fade restores (the SMF resets the line color and
the mirror follows). Verified in-game: fade lockstep, reappear on
scroll.

* feat(text): line-height growth for tall inline icons

An inline icon taller than the font (a 32px TwitchEmotes emote in 15px
chat) used to overlap its neighbouring lines — the line box stayed
fontH-sized. Retail grows the line: 4.3.4's measure and wrap loops
export a max-texture-height out-param (FUN_00618b90 / FUN_00618e40
case 7) and the layout takes it.

1.12 equivalent, one cold co-hook: FUN_FONTSTRING_STRING_HEIGHT
(GetStringHeightInternal, cache fs+0x100) gains the tallest icon's
overflow past the font height (MaxIconOverflowPx — explicit |T heights
only; the :0 default IS the font height). Its three binary consumers
(verified via xrefs) split exactly right:
- FUN_00772A60, the anchor effective-height vmethod — chat line
  fontstrings get only a SetWidth from the ScrollingMessageFrame
  refresh, so their rect height resolves here -> the rect grows;
- FUN_00788750, the SMF display refresh — budgets vertical space and
  anchors each line to the previous line's rect -> the stack spaces by
  the grown height;
- FUN_0077D4D0, the multi-line editbox self-size — excluded by the
  same editbox gate as the width hook (editboxes render raw markup).
Same rules as the width hook: shared InlineInterceptActive predicate,
px->anchor via the push factor (never fs+0x7C), the fs+0x100 cache is
never written (delta re-derived per call — idempotent). The backported
fontstring:GetStringHeight routes through the hooked VA and becomes
icon-inclusive automatically.

Draw side: tall icons CENTRE on the line like any other icon. The text
centres itself inside the grown rect, so the extra space appears half
above and half below — a centred icon fills exactly that, matching
retail. (A bottom-aligned first cut clipped the neighbouring line;
verified in-game against retail's centred, no-clip rendering.)

v1 limit (documented in-code): the delta is the whole text's max
overflow — exact when a message's tall icons share one wrapped line
(the emote case); tall icons on two different wrapped lines of one
message under-grow.

Verified in-game: 32px emotes between normal chat lines each take
their own vertical room, centred, no neighbour overlap.

* fix(text): full-height hyperlink hover for tall inline icons

With line-height growth (49934b0), a tall emote inside a |H...|h link
was only hoverable across its text-high middle band: the hyperlink hit
rect is registered at layout time (FUN_TEXT_LINK_RECT_ADD 0x005CD310,
the GXUFONTHYPERLINKINFO append — record {y,x,y,x} normalized + link
ptr/len pairs) with the TEXT band's y extent, fontH tall.

Consumer geometry (FUN_00788c00 -> FUN_007a3350 decompile + two in-game
experiments): the ScrollingMessageFrame rebuilds a hit-region frame per
record, anchored to the LINE FONTSTRING's top-left with the record's
band as offset/height. The band's y values are Y-UP (numeric max =
screen top — extending the max visibly grew the region into the line
above), and the band is TEXT-relative — but the grown rect's top sits
half the icon overflow above the text (the text centres in the grown
rect), pre-shifting the whole hit band up. Net: the unmodified band
already covered from the icon's top down to textBottom − overflow/2,
and the single correct fix is pushing the screen bottom DOWN by the
full overflow — decreasing the numeric MIN edge.

Co-hook on the append: when the |H...|h escape span contains a |T icon
taller than the line's font (the same MaxIconOverflowPx the
string-height hook grows the line by), decrease the band's min edge by
the overflow before the original stores it. All consumers of the
record (hover, click) inherit the expansion. Gated on the shared
InlineInterceptActive predicate so raw-rendered contexts stay literal.

Known v1 rough edge (commented in-code): a tall icon outside the link
but on the same line grows the line without this hook firing for that
link, leaving its band half-overflow high.

Verified in-game: a 32px emote link hits across its full height, no
bleed into neighbouring lines.

* docs(text): truth-pass on the inline-texture RE docs

InlineTextureEscapes.md and InlineTextureResidency.md described the
removed raw-quad renderer and a bring-up plan as if current. Bring them
in line with the shipped engine-region design.

InlineTextureEscapes.md:
- New "Current design (shipped)" section up front: region renderer, the
  three fs-level measure hooks (width/height/wrap), the lazy-pen fix,
  chat fade, tall-icon line growth + full-height hover, editbox
  exclusion, the payload, and anti-spoof — each with its commit.
- Banner the quad "rendering primitive" section as REMOVED (bring-up
  record; the address log for code deleted in 56c2670).
- Fix the DrawTexturedQuad / quad-flush references to region-queue
  language; vertical centring is g_centerFrac (0.6) with the tall-icon
  grown-rect note; the flip note becomes the region SetTexCoord
  Y-first order.
- "Remaining/optional": diagnostics removed (only InlineTexEnable
  left), measure/height/wrap DONE, animation is addon-side, the TGA
  convert command is -compress none only.
- "Reality check": correct the prediction that we would reimplement the
  emitter — the shipped design segment-delegates and co-hooks instead.

InlineTextureResidency.md: rewritten from a "not-yet-implemented plan"
into an accurate reference. States the region design, records the
CSimpleTexture entry points / layout the pool uses (VAs verified
against Offsets.h), and corrects the root cause honestly — the flicker
was the LAA pointer-bound truncation (dc61f77), NOT texture residency;
regions are kept for 4.3.4 parity and are resident by construction as a
bonus. Keeps the D3D "ruled out" notes as a do-not-re-investigate
record.

* fix(text): stop inline-icon Maintain from dereferencing stale fontstrings

A destroyed chat-line fontstring left a dangling key in the icon pool's
per-fontstring map. Its heap memory was reused as a string buffer, and
Maintain's weak LooksReadable() range check waved the reused pointer
through; reading the "parent" field (fs+0x9C) then yielded string bytes
(ASCII "-Rac"), which the engine's region attach (FUN_0076a750)
dereferenced at *(parent+0x1B4) -> ACCESS_VIOLATION (ERROR #132 at
0x0076A7CE).

Two compounding defects, both in Maintain:
  - the stale-entry expiry was gated on shown > 0, so a scrolled-off line
    (shown == 0) never expired and its dead key was re-dereferenced every
    frame, waiting for its memory to be reused;
  - LooksReadable is a bare VA-range test that a reused buffer passes.

Fix: verify a key is a LIVE fontstring by its object+0x00 vtable before
using it. The vtable is learned at paint time from fontstrings the engine
is actively drawing (QueuePlacements), so every fontstring class -- chat's
internal ScrollingMessageFrame lines, tooltip/CreateFontString lines,
addon fontstrings -- is recognized without hardcoding (one hardcoded value
filtered live chat icons out entirely). Maintain now iterates with erase:
a key whose memory no longer carries a learned fontstring vtable has its
regions hidden (our tex pointers stay valid, parented to the chat frame)
and the entry erased, so dead keys can neither accumulate nor be
dereferenced.

* fix(text): guard inline-icon pool hide loops against short region vector

CreateRegion can fail when the region pool is exhausted, breaking the
apply loop with fewer regions than `want`. The code still set
`np.shown = want`, so a later tick's freshness-expiry and fs-hidden hide
loops indexed np.regions[i] past regions.size() -- an out-of-bounds
std::vector access.

Clamp np.shown to min(want, regions.size()) so it never exceeds the
vector, and add the same i < regions.size() bound the eviction loop
already carries to the other two hide loops so all three self-guard.

* refactor(text): centralize inline-texture offsets and pointer probe

Enforce the single-source-of-truth offset rule on the inline-texture
files:

- Read the fontstring text pointer via Offsets::OFF_FONTSTRING_TEXT
  instead of a raw `fs + 0xF0` in FlushLayout's ghost guard; the symbol
  already existed and is used elsewhere in the same file.
- Add OFF_TEXT_NODE_JUSTIFY (0x54) to Offsets.h with a verification note
  and use it for the two node-justify reads (DeriveK and the emitter
  pre-shift) that previously hardcoded 0x54 in two places.
- Move the LAA-aware LooksReadable probe into a shared text/PtrProbe.h
  (namespace Text) so InlineTexture.cpp and InlineTexturePool.cpp share
  one definition instead of two copies plus a third raw-bounds copy in
  LearnFontStringVtable. The 0xFFFF0000 bound now lives in exactly one
  place -- this is the constant whose earlier 0x7FFF0000 form caused the
  missing-chat-icon bug, so keeping the copies from drifting matters.

No behavior change; full build compiles and links.

* fix(currency): clamp GetCoinTextureString to the uint32 copper ceiling

An amount above INT_MAX gold copper (e.g. 1e15) made `gold =
(int)(amount / 10000)` overflow: the long long division was truncated to
its low 32 bits, so GetCoinTextureString(1e15) printed a garbage gold
count (1215752192). silver/copper were already bounded by the % math.

Vanilla money is a uint32 copper field, so clamp amount to 0xFFFFFFFF
copper (~429,496 gold) -- the most the game can represent -- which keeps
gold within int range for the "%d" GlobalString format. Can't widen the
type instead: the count is formatted through the retail-compatible "%d"
coin GlobalString, and passing a long long to %d is undefined.

* fix(text): SEH-guard the inline-icon Maintain tick; document region leak

#6 (SEH backstop): Maintain's liveness probe dereferences a fontstring
pointer that may have been freed (the documented IsLiveFontString
residual). The paint path already latches off on a fault via SafeFlush,
but Maintain ran bare under the render-root tick, so a fault there was an
uncaught client crash. Split the body into MaintainImpl (holds the C++
objects) and a thin Maintain() SEH wrapper that latches g_maintainDisabled
on fault -- mirroring the paint latch. Re-armed on /reload.

#7 (region leak): document why the stale-key eviction intentionally drops
np.regions without reclaiming the pooled CSimpleTextures. Any reclaim (a
free list or explicit destroy) would touch a region whose parent frame may
already be gone -- a use-after-free on the very path this liveness check
was added to stop crashing. The leak is bounded and near-zero in practice
(chat/tooltip fontstrings are reused, never evicted).

* fix(chat): stop raid-marker expansion from dropping the message tail

A token inflates ~28x ({rtN} -> ~85-byte |T markup), so a marker-dense
message could fill the 0x800 buffer and silently truncate everything after
it -- a DLL user would see a shorter chat line than a non-DLL user (a mild
content-hiding vector).

Reserve room for the literal tail before expanding a token: only iconify a
marker when the expansion plus the whole remaining input (worst case copied
1:1) still fits. Past that point later tokens stay literal {rtN}, so the
full message text is always preserved -- just with fewer icons.

* fix(text): gate eviction Hide on region liveness to avoid a UAF

The stale-key eviction Hid its regions unconditionally, assuming they
outlive the fontstring. They usually do (regions are parented to the
fontstring's parent FRAME, which persists as lines churn) -- but if the
fontstring became non-live because that parent frame was destroyed, the
frame freed the fontstring AND its child regions together. Hiding a region
pointer there wrote to freed/recycled memory: a use-after-free that could
crash.

Learn the pooled CSimpleTexture vtable in CreateRegion and gate each
eviction Hide on IsLiveRegion (the same vtable-liveness technique
IsLiveFontString already uses). A recycled region is skipped (it needs no
hiding -- it's already gone); a live one is still hidden so it can't ghost.
Factored the shared WoW-image-range check into InWowImage so the two Learn*
functions don't duplicate the constant.
2026-08-18 04:15:54 -05:00