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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
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.
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.
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.
notInterruptible required InterruptFlags 0x02 (channels:
ChannelInterruptFlags 0x04) before counting the player's interrupt
spells, because the server's interrupt effect tests that bit. But the
server tests its own spell_template, not the client's Spell.dbc, and a
server can patch the one without the other. Stock 1.12.1 ships every
Healing Ward rank (5605, 6274, 11899) with InterruptFlags 0x0D; Turtle's
DBC patches them to 0x0F. On a stock client the gate read 0x0D and
reported Healing Ward as uninterruptible for warriors and rogues, while
Pummel stopped it on the reporter's realm. 171 timed SILENCE casts in
the stock DBC lack the bit.
The verdict is now PreventionType SILENCE plus the caster's immunity
auras, against the player's spellbook interrupt / silence masks. The
isChannel parameter existed only to pick the flag column, so it is gone
from NotInterruptible and from CurrentCastOf, along with the now-unused
SPELL_INTERRUPT_FLAG_DAMAGE, CHANNEL_FLAG_INTERRUPT and
OFF_SPELL_RECORD_CHANNEL_INTERRUPT_FLAGS.
Fixes#137
Set-bonus spells are applied server-side as auras the client never sees
as buffs or known spells, so the derived healing sum missed them —
Lawbringer (3) is "Increase Healing 31" (9317), Judgement (3) is 57
(18037). Add a pass that counts the equipped members of each set from
the item record's set id (OFF_ITEMSTATS_ITEM_SET), reads ItemSet.dbc's
bonus spells and member thresholds, and runs every met bonus through
the same aura decoder — the rule the item tooltip's set-bonus lines use
at 0x52DFB9.
The Ironclad (aura 199) armor conversion stays on
UNIT_FIELD_RESISTANCES[0]: the server's SpellBaseHealingBonusDone uses
GetArmor(), the full total, even though the talent text says "Armor
from items".
Refs #135
CGGameUI::Initialize (0x0048FE00) calls RegisterScriptFunctions — where
our LoadScriptFunctions hook enables claim writes — and only then
SetScriptEventTable(0xBE1198, 0x225), which builds the in-game table.
Between the two the live table at [0xCEEF68] is still glue's 26-entry
one. A third-party DLL that registers a frame from its own
LoadScriptFunctions hook fires our Frame::RegisterEvent (0x00702140)
hook in that window: Grow enlarged the glue table (26 -> 142), the
reservations claimed slots 26..125 in it, the engine freed that buffer
and built the real table, and every cached slot stayed non-negative —
never retried, invisible to IsEventValid, and a Fire would have
signalled whatever engine event sat at that id.
Two guards, both read off the engine's own build:
- GameTableInstalled: the in-game build always passes 0x225 names and
the other DLLs' SetEventCount clamps only enlarge, so a table smaller
than EVENT_NAME_TABLE_STATIC_COUNT is glue's. Claim and Grow refuse it.
- Stale: each reservation keeps the SStrDup'd pointer it wrote; when the
live entry at its slot no longer holds that pointer (or name), the
table was rebuilt behind us and every slot is forgotten and re-claimed
before the original RegisterEvent populates any chain.
Fixes#134
3.3.5's and 4.4.2's SpellShapeshiftForm.dbc give Spirit of Redemption
(form 32) flags 0x4100, which include SHAPESHIFT_FORM_FLAG_NO_AUTO_UNSHIFT
(0x100). So the later clients' CGUnit_C::CanAutoUnshift refuses it, and no
cast, interaction or item use cancels it. 1.12's row has flags 0, so with
autoUnshift on, our CanAutoUnshift allowed it. A priest in Spirit of
Redemption who cast a NOT_SHAPESHIFT spell, right-clicked an NPC or object,
used an item or opened the flight map sent CMSG_CANCEL_AURA for it.
The later-client flags that 1.12's rows lack now sit in one table:
CAN_INTERACT on the druid forms and Ghost Wolf (read only while
autoUnshift is on, as before), and NO_AUTO_UNSHIFT on form 32, which
CanAutoUnshift reads unconditionally, as 4.3.4 does. With it, every
autoUnshift site leaves Spirit of Redemption on and keeps 1.12's own
refusal.
The comment on FormCanInteract also records why a locked object still
unshifts. It opens by a spell (Opening 6478 for chests and barrels), and
the server's CheckCast form test refuses that spell on 1.12's spell data,
which keeps SPELL_ATTR_NOT_SHAPESHIFT (3.3.5 dropped it).
1.12's SpellShapeshiftForm.dbc gives SHAPESHIFT_FORM_FLAG_CAN_INTERACT
(0x8) only to Shadowform. 3.3.5 and 4.4.2 also give it to Cat, Travel,
Aquatic, Bear, Dire Bear and Ghost Wolf, and Turtle's id 11 (Swift
Travel Form) has it there too. So in the later clients, these forms pass
the NPC right-click gate (CGPlayer_C::HandleOnRightClick, 0x005F0130)
and the game-object use check (0x005F3130) as they are. The form cancel
that comes before the range check almost never runs.
In 1.12, autoUnshift cancelled every druid form at that gate, even when
the NPC was out of interact range. With autoUnshift on, the redirected
IsShapeShifted calls at both gates and at CanInteractNow (0x00606880)
now read a form in that set as able to interact. They report "not
shifted", so the engine's own 0x8 test that follows does not refuse it,
and the cursor shows the NPC's service icon. The cancel stays for a form
that cannot interact in either client.
Neither vmangos nor tortoise-wow tests the form on an NPC or object
interaction. CanInteractWithNPC and the use handlers have no form check;
the only one is item use. So the client gates are the only refusal.
* fix(loot): skip corpses that stay lootable after LootAllCorpses
A corpse whose remaining loot this player can never take keeps
UNIT_DYNFLAG_LOOTABLE set: quest items for quests they don't have,
condition-gated loot, and the like. The per-corpse re-check still
passes, so a caller that runs C_Loot.LootAllCorpses from a timer
re-opens the same corpse on every walk and re-sends the refused
CMSG_LOOT_ITEM, which never clears.
Loot mode now remembers every corpse it opened and released. Later
walks skip a remembered corpse while it is still visible and
lootable; the entry is dropped once the corpse stops being lootable or
leaves the object manager. A corpse that merely left render range is
dropped too, so it gets one retry when the player comes back.
ScanNearbyLoot stays read-only and keeps reporting the corpse.
1.12 has no per-slot "cannot loot" flag (GetLootSlotInfo has no
`locked` return), so one refused request per corpse is unavoidable;
this only stops it from repeating on every walk.
* docs(loot): describe the LootAllCorpses corpse skip
Explain why a corpse that stays lootable after the walk is skipped by
later walks, and when the skip entry is dropped.
* fix(loot): skip only corpses that open empty in LootAllCorpses
The previous change remembered every corpse the loot walk opened. The
most common reason a corpse stays UNIT_DYNFLAG_LOOTABLE is full bags,
so those corpses were never looted again by the walk, even after the
player freed bag space. Rolls and master-loot assignments in progress
had the same problem.
The server never sends a player a loot slot that player cannot take:
another member's quest item and condition-gated loot are left out of
SMSG_LOOT_RESPONSE, while the corpse stays lootable for as long as any
loot remains. So the stuck corpse opens to an EMPTY window, with no
coin and no populated VAR_LOOT_SLOTS entry. Loot mode now remembers a
corpse only when the scraped window is empty. A window with anything
in it (full bags, a roll, a master-loot slot) is retried.
An entry is forgotten:
- on the first world tick where its unit is gone or no longer
lootable. This replaces the prune at walk start, which missed a
corpse that left view and came back, and a creature that respawned
with the same GUID and died again, between two walks;
- all at once on QUEST_LOG_UPDATE (event 0x134, observed through the
shared FUN_FIRE_EVENT_NO_ARGS interceptor and never swallowed),
because quest items are per-player loot and a quest change can put
an item into a window that was empty.
The memory moves out of the per-walk ScanCtx into its own vector. The
API reference now describes the skip as a contract only.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
Seven sections were out of place in the body: ChatBubbles (after Mount),
Bindings (after Focus), APIDocumentation, CVar, MerchantFrame, NamePlate
and PvP. The contents list shared the last four. Both are now in the same
case-insensitive order, with one blank line between contents groups
(DeathInfo and Sound had none). The ClassicAPI namespace section had no
contents entry; it has one now.
The PVP_TIMER_UPDATE entry moves from the PvP section to Events, between
PLAYER_SWING_RANGE_UPDATE and QUEST_ACCEPTED. It now names the PvP timer
and links the two timer functions, and the PvP section links to it.
1.12.1 has no mount table, so a mount's ID is the ID of the spell that
summons it: GetMountFromSpell(458) returns 458. A spell is a mount when
one of its effects applies SPELL_AURA_MOUNTED (78); Spell.dbc is read
directly, so mounts the player has not learned resolve too. On Turtle
every mount item carries spell 46499 "Add Mount to Collection" instead of
its mount spell (the server maps item to spell from its own table), so
only the mount spell gives a mount ID.
GetMountInfoExtraByID returns the nine retail values. The display ID is
the one the server mounts the player on: the mount aura's misc value is a
creature entry, and the client's creature cache holds that creature's
display (SMSG_CREATURE_QUERY_RESPONSE carries the template's first
display, and every mount creature has exactly one). An uncached creature
returns nil and starts the cache load through the new
Creature::Info::RequestLoad, which C_CreatureInfo.RequestLoadCreatureByID
now uses too; CREATURE_DATA_LOAD_RESULT fires when the data lands.
Verified in game: 23219 (Swift Mistsaber) returns 14332.
Mount type and model scene default to 230 and 4. Seven mounts take
retail's values instead (the six Qiraji battle tanks use scene 44, the
Riding Turtle type 231), each checked by name against Turtle's
Spell.dbc. The seat animation is 91 (Mount), the animation 1.12.1's
world mount plays on the rider.
Six places asked the same question of a Spell.dbc record: does one of its
three effects apply aura N (EffectApplyAuraName, +0x16C, int32[3])? Each
had its own loop: the combat log's damage-shield lookup, crowd-control
classification and its snare test, tracking-spell detection,
C_SpellBook.GetPlayerSpellsByAura, and the aura-source periodic-damage
gate (which also hard-coded 3 for the effect count).
Spell::Lookup now has FindAuraEffect (the index of the first effect that
applies the aura, or -1, for callers that read that effect's other
columns) and HasAuraEffect on top of it, next to the existing HasEffect.
All six call it. Code that pairs an aura with the same effect's misc
value, amount or effect code (Cancel, Interruptible, BonusDamage,
StatAccum, EffectInfo) keeps its own per-effect reads.
SMSG_ATTACKSTART re-fired PLAYER_SWING(MainHand) whenever the main-hand
swing was still running. That was meant for a cast reset recorded before
the attack (held back because no swing was coming yet), but the server
also sends SMSG_ATTACKSTART on a target switch mid-attack. Unit::Attack
then resets only the off-hand timer; the main-hand swing keeps going.
The event carried just the time left in that swing, so listeners read a
nearly finished swing as a fresh, short one.
Each swing type now carries a held flag, set only by a reset recorded
without notify and cleared when that type's PLAYER_SWING fires. The
attack-start path reports the main hand only while it is held.
Fixesbrues-code/SuperCleveRoidMacros#11
UnitClassBase and UnitRaceBase now follow stock Script_UnitClass
(0x00518350) and Script_UnitRace (0x00518200) branch for branch.
"player" reads the selected-character record; any other token goes
through GetGUIDFromName + ClntObjMgrObjectPtr(TYPEMASK_UNIT) and reads
the held object's descriptor byte (+0x79 class, +0x78 race). The
NameCache record (+0x140 / +0x138, null callback) is peeked only when
no object is held.
Before, the NameCache was also peeked when a held object's byte was 0.
That never changed a result (creatures are not in the NameCache) but
resolved the token twice and did not match the engine's branch.
The comments and API.md also claimed creatures return nil, that class
IDs run 1-9, and that UnitClass has a third return. None of that is
true: creatures go through the same ChrClasses/ChrRaces lookup as in
UnitClass/UnitRace, Druid is 11, and stock returns exactly two values.
RegisterIntegerEnum and RegisterConstants took their entries with a
count beside them, written as sizeof(t) / sizeof(t[0]), std::size, or
a literal. They now take Game::ArrayRef<EnumIntegerEntry>, as
RegisterFrameMethods does, so the count comes from the array's type.
The documentation recorders RecordEnum and RecordConstants take the
same view.
All 34 call sites pass only the array. The six literal counts were
checked against their arrays first: each was the full length, so every
Enum.* and Constants.* table gets the same entries as before. Five
files that included <iterator> only for std::size drop it.
Every RegisterFrameMethods call passed its method table and doc table
with a count beside each: sizeof(t) / sizeof(t[0]), std::size, or a
literal. The literals had to be kept in step with the tables by hand.
Game::ArrayRef<T> is a view over a file-scope array that takes the
count from the array's type, the way Doc::FieldList already did for a
function's arguments and returns. FieldList is now ArrayRef<Field>,
Doc::MethodList is ArrayRef<Method>, and RegisterFrameMethods takes
(context, methods, docs). The table and count still go to the engine's
frame-method iterator (FUN_REGISTER_FRAME_METHODS) unchanged, and to
the documentation recorder.
All 84 call sites pass only the arrays. The 16 literal counts were
checked against their tables first: each was the full length, so every
registry gets the same methods as before.
/reload crashed with an access violation in the model release
(0x007103A3, inside FUN_MODEL_INSTANCE_RELEASE 0x007103A0) when
SetDisplayInfo had dressed a few panes.
1.12.1 reloads in two steps. CGGameUI::Shutdown (0x00490BD0) deletes
the CSimpleTop, which destroys every frame. A Model frame's teardown,
DestroyModelFrame (0x0076CA50, from the CSimpleModel and
CGCharacterModelBase destructors), releases the frame's M2 scene at
+0x314, and the scene frees every model in it, even one that something
else still holds a reference on. Only then does CGGameUI::Initialize
(0x0048FBF0) reset the Lua state, which runs FrameScript_Initialize
and our reload cleanups. DisplayInfo's cleanup destroyed each kept
compositor there (FUN_CHARCOMP_DESTROY 0x00476000), and the compositor
released its reference to a model that was already freed. VisualKit's
cleanup detached and released stopped one-shot effects that live in
the same freed scene.
Model::Teardown hooks DestroyModelFrame and runs its subscribers
before the original, while the frame's scene and models are intact,
which is where the engine frees what its own frames hold. DisplayInfo
drops the frame's dress job there, and VisualKit records each stopped
effect's pane (in the done callback's user data) and discards that
pane's effects there. Their reload cleanups keep only the
pointer-keyed state.
The ReloadAutoRegister doc now says that the cleanups run after the
frames are gone, so they may forget pointers but never release an
engine object tied to a frame.
The model modules each declared their own pointers to the same 1.12.1
engine functions: the instance gates FUN_MODEL_INSTANCE_LOADED
(0x007103D0) and FUN_MODEL_INSTANCE_READY, AddRef / Release
(0x00710390 / 0x007103A0), FUN_M2SCENE_CREATE_MODEL,
FUN_M2MODEL_PLAY_ANIMATION, the done callback, the item visuals, the
render callback, the M2 data lookup FUN_M2_LOOKUP_INDEX (0x00710310),
and the pane's model, scene, SetModelInstance virtual (vtable +0x90)
and SetDisplay. model/M2.h now holds one typed wrapper for each, and
every module calls through it.
- Game::Lua::ResolvePlayerModel / ResolveDressUpModel join the
per-type resolvers, replacing four ResolvePane copies and five
inline ResolveTypedObject calls. Game::Lua::TYPE_NONE replaces the
local kTypeNone in Rotation and frame/CreateFrame.
- Offsets.h has the full INVTYPE list, 0..28, named by the engine's
own key table at 0x0083DDB0. It replaces the four scattered
INVTYPE_* entries and the local copies in DressUp and ItemDisplay,
and the try-on result switch reads by name.
- DisplayInfo keeps its dress jobs in a map by frame, like the other
modules, in place of the fixed 8-slot pool and its eviction.
- DressUp names the held lane's bytes (item class, inventory type,
sheathe type) and detaches a lane in one place.
- ItemDisplay::OwnVisual is the one test for a display's own
ItemVisuals row (GetItemDescVisual 0x0062EC70), used by SetItem and
by TryOn's enchant glow. Both own-record panes share
Pane::DisplayRecord, and the SetDisplayInfo records are cleared on
/reload as the SetItem records are.
* feat(localization): complete and correct the Russian locale
The Russian locale was 99 keys behind enUS, so a Russian client kept the
English strings for ClassicAPI's own options: the AddOn Options title and
its game-menu button, every page name, header, control label and tooltip,
the AoE Loot binding, and the generic strings the options pages gained
(FOCUS_TOKEN_NOT_FOUND, LUA_ERROR, RELOADUI, PLAYER_LIST_DELIMITER,
SYMBOLIC_NEGATIVE_NUMBER, SYMBOLIC_POSITIVE_NUMBER and the money texture
formats). All 327 keys are now present, in enUS order, so the two files
diff key by key.
Focus follows the client's modern terms — «Взять в фокус», «Сбросить
фокус», «Выбрать фокус» and «Взять цель в фокус» — matching the existing
/фокус and /сбросфокуса aliases. The rest uses the 1.12 Russian client's
vocabulary where it has one (модификация, цель, панель команд, время
восстановления, табличка с именем) and «динамическое выделение» /
«мягкая цель» for action targeting. The money strings keep their |4
plural forms, which GetCoinText expects.
Fixes:
- LARGE_NUMBER_SEPERATOR was "", which turned digit grouping off. It is
now a space, as in the tooltip's 1 234 567.
- FIRST/SECOND_NUMBER_CAP and their _NO_SPACE twins carry the leading
space, because Abbreviate concatenates the number and the suffix
directly.
- EQUIPMENT_MANAGER_ITEMS_MISSING_TOOLTIP printed a slot number where
the missing count belongs; it now takes the missing count.
- SETTINGS_BIND_KEY_TO_COMMAND_OR_CANCEL was missing a space before
«или нажмите».
- SET_FRIENDNOTE_LABEL had a |3-5 declension token, which 1.12 renders
literally.
- ITEM_SLOTS_IGNORED and ITEMS_NOT_IN_INVENTORY had wrong third plural
forms, ITEM_MOD_HIT_MELEE_RATING_SHORT had a double space, and the flat
stat labels (Защита, Уклонение, Парирование, Блок) read wrong after a
signed value, so they use the same «к …» form as the other ITEM_MOD
labels.
The TOC gains ## Notes-ruRU next to ## Notes.
* fix(localization): restore retail ruRU focus, number and log strings
Follow-up to the Russian locale completion, which had changed several
strings that the retail ruRU client already translates. Each is now
the retail text, or a correction where the new wording was wrong:
- Focus: the FOCUSTARGET / TARGETFOCUS binding labels were swapped
(FOCUSTARGET runs FocusUnit("target"), TARGETFOCUS runs
TargetUnit("focus")). All focus strings use retail ruRU's terms
again: Запомнить цель, Восстановить цель, Отменить запоминание цели,
Запомненная цель, <фокус отсутствует>.
- EVENTTRACE_LOG_DISCARD is the message logged after the log is
discarded; it had become an option-style label. Retail: Журнал
сброшен. EVENTTRACE_BUTTON_DISCARD_FILTER read "cancel all"; retail:
Сбросить все.
- FIRST/SECOND_NUMBER_CAP and their _NO_SPACE variants go back to
retail Т / М. AbbreviateNumbers appends the _NO_SPACE suffix
directly by design ("1.2K"), so " тыс." widened compact numbers.
- LARGE_NUMBER_SEPERATOR goes back to retail "" (as frFR). A plain
space also let a number wrap across lines. The separate-large-numbers
tooltip drops its "1 234 567" example, which no longer applies.
- The loose-target option read "whom the soft target follows". The
normal target is the one that follows, so it is now "обычная цель",
and the choices name the soft enemy / soft friend.
* fix(localization): pick language rules by locale name, not 4.3.4's index
1.12.1's locale index (VAR_LOCALE_INDEX, 0xC0E080) is the Wow.ini
Language+Country tag's position in the eight-entry name table at
0x8558A4 (enUS koKR frFR deDE zhCN zhTW esES xxYY), stored once at
0x402562 and 0 when nothing matches. It is never 8. The Russian branches
ported from 4.3.4 switched on 4.3.4's own slot numbers (esMX 7, ruRU 8),
so they could never run: a client whose GetLocale() is "ruRU" fell
through to the default plural rule ("5 предмета") and got no ё/е folding
in bag search.
Localization::Locale::Client() reads the same entry Script_GetLocale
(0x48D8B0) pushes, table[index], and Is(code) compares against it. The
language-rule sites now go through it:
- Text::Grammar's plural index (|4 expansion) keys koKR/frFR/zhCN/zhTW
and ruRU by name.
- Container::Search picks its accent-folding set by name, as a Folding
value instead of an index switch.
- Localization::Numbers' ClientIsAsian reuses IsAsianLocale on the name.
- AddOns::TocRewrite drops its private copy of the reader, and the
slot-8 clamp, which guarded an index that cannot occur.
The DBC column reads keep using the index, which is what it is for.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
autoStand / autoDismount / autoUnshift ran their actions as soon as the
caster-state check (CheckCasterStateForSpell, 0x006094F0) passed. In the
1.12.1 cast request (TryCastSpell, 0x006E4B60) that check comes before
the target arm (0x006E5250), so a cast that then found no target still
dismounted the player and showed "You have no target" (Charge with
nothing targeted). A targeting cursor the player cancelled did the same.
The caster check now only keeps what its rungs noted, and the actions run
at the send. SendCast (0x006E54F0) builds the cast packet; its five
callers all pass the global pending cast: the arm's two immediate sends
and the object / location / trade-slot binders, which the targeting
cursor's click also runs. The arm's only caller is the cast request,
after the caster check, so every send follows a check of the same cast.
Each action runs only if its state still holds, since the player can
stand, dismount or leave the form while the cursor is up. The send
redirects must all apply before the rungs are patched.
Item use had the same ordering gap. Its form refusal (0x005D914D) comes
before the toggle test, which turns off a use aura that is already up
instead of casting (0x005D9157..0x005D9237). Re-using such an item while
shapeshifted dropped the form as well. The refusal now only notes the
unshift; it runs at the bind-on-use test (0x005D91D3), which every path
past the toggle reaches, and the toggle's cancel call clears it.
Fixes#132
The engine's cost helper (FUN_006E31B0) answers in stored units, and
1.12.1 stores rage in tenths, so Shield Slam's 20 rage came back as
cost = 200. Divide by the engine's own display divisor
(GetPowerDisplayDivisor, 0x006E7130: [0x0086F978 + 4*type], 1 for a
negative type; table {1, 10, 1, 1, 1000}) before pushing, the same way
the engine and our UnitPower / GetSpellInfo / combat-log paths do.
Every power amount surfaced to Lua now goes through one helper,
Unit::Power::DisplayDivisor, which calls that engine function. That
retires the duplicate FUN_GET_POWER_DISPLAY_DIVISOR offset, the two
local typedef copies, and UnitPower's direct read of the divisor table
(VAR_UNIT_POWER_DIVISOR_TABLE, now removed).
Fixes#129
The walk ignored the server's refusal. A failed CMSG_LOOT ("too far
away", not ours, ...) arrives as SMSG_LOOT_RESPONSE with loot type 0;
CGPlayer_C::ReadLootResponse (0x005EB900) shows the error and clears the
held loot target (+0x1D28) without opening a window, and the release
response (0x005EC090) clears it the same way. The walk only advanced on
the loot controller hook or a 180-frame timeout, so each refusal stalled
it for seconds. It now advances as soon as the held target is no longer
the corpse it sent for.
A send the engine refused dropped the whole queue. LootUnit (0x005DF2A0)
sends nothing while the mover flags & 0x20FF are set (moving, turning,
falling), and the walk treated each refusal as "skip this corpse", so
moving during a walk skipped every corpse left. A refused send now stays
the current corpse and is retried each tick; after 3 s the walk ends.
The queue's range check went stale. Range was tested once when the walk
began, but each corpse costs a round trip and the player can move in
between. With CanAutoInteract set, CanLootNow (0x005EC110) skips its own
reach test, so the request went out and the server refused it. Each
corpse is now checked for existence, DYNFLAG_LOOTABLE and reach right
before its send, and skipped when it fails.
The reach test is CanLootNow's own: both units' +0x1F0 reach plus the
engine's leeway, at least its minimum, with both constants read live
(VAR_MELEE_REACH_LEEWAY / VAR_MELEE_REACH_MIN) instead of local copies.
It and the lootable test move to Loot::Request, shared by
GetNearbyLootableUnits and the walk. The step timeout uses Time::Clock
instead of a frame count.
The three settings only covered casts. Each 1.12.1 gate that refuses an
action for the player's stand state, mount or form now passes when the
matching setting allows it, and the engine's own action (the stand setter
FUN_005ED430, or CMSG_CANCEL_AURA for the mount / form aura) runs just
before the action is sent. With the settings at 0 nothing changes.
- NPC right-click (0x005F0130): the IsShapeShifted call at 0x005F0150
cancels a form without SpellShapeshiftForm flag 0x8 instead of showing
ERR_CANT_INTERACT_SHAPESHIFTED. CanInteractNow (0x00606880), whose only
caller is the hover cursor, passes the same form, so the NPC's service
cursor shows.
- Game objects: the use check (vtable slot 6, 0x005F3130), also the hover
cursor's query, passes the mount (0x005F31A8) and the form (0x005F31E1)
for an object with no Lock row. The default use's no-spell branch
(0x005F35DF, before CMSG_GAMEOBJ_USE) and the mailbox and text use slots
dismount (except at a mailbox, FUN_0047CFF0) and cancel the form. A
locked object opens by a spell, which the cast path already handles.
- Loot: the GetStandState calls of the unit (0x0060BFB7) and corpse
(0x005D6C3B) right-clicks stand the player up instead of showing
ERR_LOOT_NOTSTANDING. The unit loot step's mount read (0x0060BF98)
passes, and LootUnit dismounts before CMSG_LOOT (0x005DF3B3).
- Item use (0x005D8D00): the ERR_NO_ITEMS_WHILE_SHAPESHIFTED refusal at
0x005D914D cancels the form and continues. Turtle's exe already skips
that test; the stock exe reaches it.
- Attack: the mount reads in the attack cursor (0x00482659), the
right-click attack (0x0060C1B4), StartAttack (0x005ECC06) and both tests
of the attack resolver (0x00613039, ERR_ATTACK_MOUNTED; 0x00613142)
pass. StartAttack, after all its tests (0x005ECC56), dismounts when the
target is in melee reach (Combat::Swing::InMeleeRange). Otherwise it
returns without attacking and shows ERR_OUT_OF_RANGE, except while
click-to-move (FUN_0060F900) walks the player there.
- Taxi: after the taxi map opener's TAXIMAP_OPENED tutorial call
(0x004DBAA2), a map with more than one node stands the player up,
dismounts and cancels the form, each when its setting is on.
Every site is patched only when it holds the expected stock bytes, which
both the Octo and stock 1.12.1 exes do.
PlayerModel:ApplySpellVisualKit(spellVisualKitID [, oneShot]) shows a
SpellVisualKit's effects on the pane's model.
In the world, 1.12.1 plays a kit on a unit (0x0060EDF0), through effect
objects, spell durations and the unit's own animation, and a pane has
none of these. The engine's own kit on a bare model is the
char-select ghost (0x004727F0), and this is that routine for any kit on
the pane's model:
- Each of the nine effect columns (+0x0C) is created as a model from its
SpellVisualEffectName file, in the pane's scene. It is attached at
the column's attachment (20, 34, 19, 21, 22, 17, 23, 24, 25) when the
model has that attachment (0x00712CB0, 0x00712F70), as in 0x00472780.
The effects get the frame's light through LightChildren.
- Procedure kind 1 sets the tint (an 0xRRGGBB colour stored as a float,
scaled by 1/255) and kind 14 the alpha, clamped to 0..1. Both are
plain stores (0x00710CF0, 0x00710CB0), as the ghost kit makes them.
The kit's animation and sound do not play, which matches retail.
An effect model's sequence plays one time. Without oneShot, each effect
gets the world's loop callback (KitEffectLoopCallback, 0x0060ED00): a
clean end (reason 0) plays the animation again. With oneShot, each
effect gets EffectDoneCallback's test (0x005FBF50) and CEffect::Stop's
model steps (0x006203E0): clear the callback and hide the model, so
its emitters stop and the particles already out finish. A FrameTick
drain, which runs after the strata walk, then mirrors
DrainDyingEffects (0x0061F680). It detaches a stopped effect (0x00713020)
once HasLiveParticles (0x007135C0) is false, or at once when its
model has already dropped it. A model's destructor detaches its
children first (0x0070E3F5), so the drain never reaches a freed parent.
The effects are children of the pane's model, so SetUnit, SetItem or
a hide and show clears them.
DBC::Record checked the ID against the store's count as a signed int.
A DBC column uses -1 for "none", and -1 passed that check, so the
helper returned records[0xFFFFFFFF]. On 32-bit that wraps to
records[-1], the heap word in front of the index array. A caller that
passed an unchecked column read a garbage "record": an empty
SpellVisualKit effect column gave the pointer 0xF and crashed.
The engine rejects these IDs before it compares with the count: the
char-select ghost kit's effect step tests the ID with a signed jl at
0x00472797, then a jg against the count. Record now compares
unsigned, so it rejects 0, every negative ID, an ID above the count,
and an unloaded store, whose count is -1.
PvP::Arena had its own copy of the lookup with the same signed
compare. It now calls DBC::Record.
PlayerModel:SetItem(itemID [, appearanceModID, itemVisualID]) shows one
item's own model in the pane: a weapon, shield, helm, shoulder, quiver or
ammo, with its skin texture and its glow.
A 1.12.1 pane shows whatever its display record names (+0x3F0).
SetDisplay (0x00505CB0) stores the record and builds it when the pane is
visible, the show path (0x00505D49) builds it again, and the SetUnit
helper (0x00505B50) clears it. SetItem gives the pane a record of its
own and passes it to SetDisplay. The AttachDisplayModel (0x00505A70)
co-hook in Model::DisplayInfo then builds the item instead of a
creature. So hide, show, SetUnit, SetDisplayInfo and SetKeepModelOnHide
handle an item with no new hooks.
The model is built from 1.12.1's own steps:
- the item folder by inventory type, from the engine's own
Item\ObjectComponents\ path strings (0x00838CD8 on);
- model name 0, else name 1, with the texture of the same index;
- for a head item, the helm builder's (0x004799A0) path, with the
player's race prefix (ChrRaces +0x18) and sex letter (0x00838AB4);
- AttachItemModelFile's (0x004798C0) steps: create the model in the
pane's scene, load the skin with the item-model status (0x00B424F0)
and filter 3, bind it as texture type 2 (0x00710EC0), and attach the
item visuals (0x00479700);
- AttachDisplayModel's install: SetModelInstance (vtable +0x90), the
pane's done callback (0x005062A0 through 0x00711BB0), Stand, and the
release of the creation reference.
The display's own ItemVisuals row wins over itemVisualID, the rule
GetItemDescVisual (0x0062EC70) applies to enchants. The visual's child
models get the frame's light and fog callback, now a shared
LightChildren helper, so they are not drawn black. An uncached item is
queued through Item::Data::WarmCache, and each visible pane that still
shows it is built again when the item loads.
FreezeAnimation(animation, variation, frame) holds the model in one
pose of an animation until the pane loads a new model, as SetAnimation
does. frame is the time into the animation in milliseconds, the unit
of M2 sequence times.
The engine's sequence time is start + (ftol(elapsed * speed) + offset)
mod length. So the pane's arm plays the animation through
PlayAnimation (0x007121A0) at speed 0 and writes frame to bone 0's
slot offset (+0xB8, bone states 0x118 bytes each at [model+0x90]).
Speed 0 also puts the end stamp on the start stamp. Update
(0x00719370) would then queue the done callback on the next frame, and
the pane's done callback (0x005062A0) would arm Stand. The arm
therefore sets the slot's done latch (+0xC0), the flag Update itself
sets once it has reported done. A held animation never ends.
SetAnimation and FreezeAnimation now also mark the pane for one re-arm.
A call with the animation that already plays then still starts or ends
a freeze, where the per-paint compare alone would skip it.
Adds SetAnimation, SetDoBlend/GetDoBlend, HasAnimation,
SetKeepModelOnHide/GetKeepModelOnHide, CanSetUnit and GetDisplayInfo
to PlayerModel (and so to DressUpModel and TabardModel). SetUnit now
returns whether the unit exists, and SetCreature takes an optional
display ID.
Animation. A 1.12.1 pane rests on Stand: its per-paint UpdateModel
(0x00505C50) arms Stand (PlayAnimation 0x007121A0 with id 0) whenever
key bone -1 plays anything else and no turn is pending. A deadline of 0
counts as passed, so any other animation lasted one frame. SetAnimation
gives the pane a resting animation and variation of its own. With one
set, UpdateModel is hooked to arm that animation in Stand's place, using
the pane's blend setting. Every other pane runs the stock function. The
pane's done callback (0x005062A0) arms Stand when the animation ends,
so the next paint starts it again and it loops. CSimpleModelFFX's
SetModelInstance (0x0076CD30), which every pane model build and hide
goes through, clears it, so a new model rests on Stand again.
SetRotation turns without the shuffle while a resting animation other
than Stand is set. HasAnimation is PlayAnimation's own test on the raw
id: the lookup at shared data +0x24 must give an index below the
sequence count at +0x1C. It is false until the model has loaded.
Keep on hide. The pane's Hide (0x00505CE0) drops its model through
slot 36, and its Show (0x00505D00) builds a new one from the unit or
display record. With keep on, Hide runs only the base hide (0x0076AD50)
and Show runs only the base show (0x0076AE10) while the pane still
holds its model. The model then comes back with its try-ons and
animation. The SetUnit helper (0x00505B50, behind SetUnit, RefreshUnit
and Dress) and SetDisplay (0x00505CB0) only store the new subject while
the pane is hidden, so they drop a kept model first. The next Show then
builds the new one. Off is the default and matches the stock client.
Units and displays. SetUnit runs the engine's method (0x00505D70,
which Turtle patches) unchanged. It then reports whether the GUID it
stored resolves to a unit (type mask 8), the same test the helper uses
before it builds. CanSetUnit is that resolve without the set.
GetDisplayInfo reads the display record's ID, or the unit's
UNIT_FIELD_DISPLAYID (+0x1F4, field 0x7D). SetCreature with a display
ID shows that display through the SetDisplayInfo record.
IsLoggedIn returned whether the player GUID was set. That GUID falls
back to the char-select GUID before the world loads, and on a /reload
the live GUID is already set while the addons load. So IsLoggedIn was
true while every addon's files ran, and EventUtil.ContinueOnPlayerLogin
ran its callback at once instead of waiting for PLAYER_LOGIN. An addon
that hooked another addon this way hooked it before that addon had set
itself up.
1.12.1 fires PLAYER_LOGIN from one place: the enter cascade
(0x004908C0) calls FUN_FIRE_EVENT_NO_ARGS with 0x10E at 0x00490959,
once per interface initializer run (login and reload). Its arm byte
0x00B4E260 cannot answer the question directly: the initializer sets
it after the addons load (0x0049011D) and the cascade clears it after
the fire (0x0049095E). That call is now redirected to set a flag just
before the event goes out, and the FrameScript_Initialize cleanup,
which runs before every /reload and /logout, clears it.
IsLoggedIn is now false on glue and during addon load, and true from
the PLAYER_LOGIN handlers on, through world transfers.
UnitGUID("player") keeps its char-select fallback.
TryOn now takes retail's (item [, handSlotName, spellEnchantID]) and
returns an Enum.ItemTryOnReason. The pane gains IsGeoReady, SetSheathed /
GetSheathed and SetAutoDress / GetAutoDress.
Hand: TryOnItem (0x00504540) picks a lane at one site, 0x0050492D
(mov edx,[edi+0x2C]; cmp edx,0x0D). A 6-byte call there jumps a named hand
to the worker's own main-hand (0x0050495F) or off-hand (0x005049B1) path,
so its CanHoldBoth (0x00504BC0) eviction, lane store and attach all still
run; with no hand it replays the two instructions and the jnz reads their
flags. The name is matched like GetInventorySlotInfo matches it: SStrCmpI
over the PaperDollItemFrame rows, slot 16 or 17.
Enchant glow: the player's AttachEnchantVisual step (0x005EED50) on the
attachment AttachItemModel (0x0047A0C0) returns: FindChild (0x00712F00),
then AttachItemVisuals (0x00479700) with SpellItemEnchantment +0x58,
skipped when the display's own ItemVisuals row exists (GetItemDescVisual's
rule, 0x0062EC70). The enchant is the argument, else the link's enchant
field, which Item::Arg now parses.
Sheathing re-runs the unit's AttachHandItem step on the pane's lanes with
the sheathed flag. The lanes keep no display row, so the pane records one:
the unit's vtable +0x9C row when SetModelInstance (slot 0x00808438) clones
it, then whatever the worker's attach (0x00504AE6) installs; its two
evictions (0x00504A0C, 0x00504A55) drop theirs. Each lane keeps its glow
too, a player's read through GetVisibleItem + GetItemDescVisual, so a
re-hung weapon keeps it. Auto-dress off runs ClearModel (0x00504490) after
SetModelInstance unless Dress() is the one rebuilding.
TryOn's result reads the gates the worker passes: an uncached record is
DataPending, a held type installs, armor needs the component and the
ready byte (+0x40C).
DressUpItemLink now passes the whole link to DressUpItem, so a
Control-click shows the link's enchant, and skips a cached item that
IsDressableItem rejects. DressUpItem stays, since Blizzard_AuctionUI and
Turtle both replace it.
Adds the expandedCursors cvar (default 0; AddOn Options > ClassicAPI >
Interface > Cursor). At 1 the hover cursor shows what an NPC offers: an
anvil for a repairer, a hearthstone for an innkeeper, a horseshoe for a
stable master, and a quest giver's ! or ? (a blue ? for a repeatable
reward). The player's fishing bobber shows a fish hook in place of the
Interact gear. Each has a gray form beyond reach or when not usable.
NPCs: ClassifyHoveredUnit (0x00482200) reaches its NPC flag chain at
0x00482336 for a unit the player can interact with, the unit in ESI and
the beyond-reach flag in EBX. The chain's `mov ecx, [esi+0x110]` becomes
a call to a thunk. At 0 it replays the instruction and the stock chain
runs. At 1 it picks from the quest giver status first (CGUnit_C +0xCB8,
read by the meaning of the client's status-to-marker table at
0x0080C454), then the NPC flags in service order: repair, innkeeper,
flight master, trainer, spirit healer, banker, registrar/tabard/
battlemaster, auctioneer, stable master, vendor, then gossip or a quest
giver IsQuestGiverToTalk (0x005DF490) accepts. It leaves through the
chain's own epilogue (0x00482356).
Bobber: the fishing node handler's cursor slot (vtable 0x0080BC80, slot
4; GetCursor 0x005F8760 is its one reader) points at a wrapper that runs
BaseHandlerGetCursor (0x005F3070) and maps Interact/UnableInteract to
the hook. The engine still decides whether the bobber is interactable
and usable.
Showing a mode past 41: SetCursorMode indexes a 42-slot image table, so
its existing hook now sends the new modes to Cursor::Extended::Show. It
calls SetCustomCursor (0x00523C40) with the mode's path, so a real file
wins, and otherwise does what that function does after its load: copy
the 32x32 image into slot 41 (0x00C0BD80), store mode 41, send it
(SendCursorImage 0x00523790) and keep the name. The hook also records
the new modes while Hover::Mode computes, so the soft-interact pick, its
icon and SetUnitCursorTexture follow; a quest cursor has no icon image.
Images: the 14 BLPs ship inside the DLL (src/embed/Textures, a new
TEXTURES_ROOT pack). Texture::Builtin decodes each once with the
engine's BLP reader from memory: BlpParse (0x005A83B0) is BlpOpen
without the file read, and BlpReset never frees the file buffer. The
reader moves to Texture::BlpReader, shared with the map overlays.
Texture loads of the same paths, such as the option label's inline
icons, get the same images.
The reader refuses a DXT5 file. BlpDecodeLevel (0x005A7F00) converts a
DXT level through the matrix InitConvertMatrix (0x005A4FC0) fills, and
that matrix has DXT1 and DXT3 converters to BGRA8888 but none for DXT5:
BlpDecodeLevel would return 1 with its SMemAlloc buffer unwritten. No
shipped cursor is DXT5; the check keeps a later embedded DXT5 file, or a
DXT5 map overlay, from being read as heap memory.
Game paths now compare through one rule, Common::SamePath (any case,
either slash), and the embedded manifests through Embed::FindFile. The
embedded addons, the bindings splice and sound muting each had their own
copy of the rule; they and Texture::Builtin now share it.
The option's header, label and tooltip are translated for every client
locale, in Blizzard's own terms for each (NSC, PNJ, 物体, 物件, ...).
Release Win32 build is clean. In game, only the soft-interact quest
icon was checked so far.
* feat(localization): translate the addon options panel into zhCN
A Chinese client kept the English strings for ClassicAPI's own options:
the AddOn Options window title and its game-menu button, every page
name, header, control label and tooltip, and the AoE Loot binding name,
which zhCN only had as a commented-out line. The generic strings enUS
gained with those pages were missing from zhCN too: FOCUS_TOKEN_NOT_FOUND,
LUA_ERROR, RELOADUI, PLAYER_LIST_DELIMITER, SYMBOLIC_NEGATIVE_NUMBER,
SYMBOLIC_POSITIVE_NUMBER and the money texture formats.
The locale files load enUS first and the file that matches GetLocale()
overrides it, so English clients are unchanged and only zhCN is filled
in. Terminology follows the client's own: 插件, 界面, 姓名板, 动作条 and
动作瞄准 for action targeting.
The Release Win32 build embeds the new zhCN.lua in the !!!ClassicAPI
pack (the packed strings were checked). Not tested in-game.
* fix(localization): use Blizzard's zhCN terms in the options panel
The backpack options said 背包, which zhCN uses for bags in general,
so "ignore backpack" read as "ignore bags" and its tooltip contradicted
itself. Use 行囊 for bag 0, as BACKPACK_TOOLTIP and
BINDING_NAME_TOGGLEBACKPACK do. Junk is 垃圾 (BAG_FILTER_JUNK), and
helpful spells are 有益法术, as in the self-cast option tooltips.
Drop the coin-texture and signed-number format strings: they were
byte-for-byte copies of enUS.lua, which always loads first.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
Crash #132 at 0x00768323 (FUN_REGION_GET_RECT reading [5+0x3C]): Show lays
a frame out before its children leave their layout deferral, so its
OnSizeChanged ran; the ScrollBox handler read a region's size, and laying
that region out reached an anchor point on a still-deferred child. The
point getter (0x007A2F90 / 0x007A3070) ends the relative's deferral with
FUN_REGION_LAYOUT_REALIZE(0), which ran the child's OnSizeChanged; that
script re-anchored the region, freeing the point, and the getter then read
the point again (0x007A2FC5) from freed heap.
The getters now end the deferral themselves with the point marked busy.
The point's deleting destructor (0x00767D80, the only free path) flags a
busy point; a flagged getter returns the layout's undefined value without
touching the point, and the point walk (0x007671A0 / 0x007671F0) is run
again with the current anchors, up to ten times. Otherwise the engine's
own getter reads the value, with the deferred bit hidden so a script that
hid the relative again cannot start a second resolve.
No hooks: the three getters/destructor are patched in the relative-point
vtable (0x0081C44C, their only reference), and the six edge resolvers'
calls to the walks are redirected. Adds Common::RedirectSlot for the
vtable entries.
* feat(texture): add static creature portraits by display ID
* docs(api): document static creature portrait functions
* Update API.md
* refactor(model): bake display-ID portraits on the engine's own path
SetPortraitTextureFromCreatureDisplayID now replays 1.12.1's unit
portrait bake, BakePortrait (0x00524F60), call for call on a display
model of its own, instead of driving a hidden PlayerModel through Lua.
The display model is built the way AttachDisplayModel (0x00505A70)
builds one, without a frame: M2CreateScene (0x00706E10), then
CreateModelFromPath (0x00707350) on the CreatureModelData path, then
ApplyCreatureDisplay (0x004797B0). A character display is dressed
through the engine compositor with the same code that dresses
PlayerModel:SetDisplayInfo, now shared as Model::DisplayInfo::
CreateDresser / PumpDresser / DestroyDresser.
The bake's own gate, IsReady(model, 0, 1) (0x00710450), only passes for
a model that something has drawn: a BLP texture gets its device texture
only when GetTextureDeviceObject (0x0044ACF0) is asked with wait set.
The shared M2 still loads on its own, so the gate here is
IsLoaded(model, 0, 1) (0x007103D0) plus the dress, and the bake's
IsReady(copy, 1, 1) makes the device textures, as it does for the copy
of a unit's model.
The bake itself is the engine's sequence: copy into a fresh scene,
DetachAllItemModels, camera 0, PlayAnimation, save projection, view,
viewport and fog (GxMasterEnable 0x0058A210 / 0x0058A1E0), the 64x64
DDC box in the bake's own float order, CameraSetDeviceTransforms, clear
colour 0, ClearDevice(3), PortraitLighting, both scene passes, read back
through 0x00589CF0, clear, cut the alpha mask in (0x005258A0), restore.
It runs at the head of the UI render callback, the same point as an
OnUpdate script that calls SetPortraitTexture, behind the bake's device
gate (0x0058A260 window active, 0x0058A280 device alive).
Each display ID owns one callback texture (TextureCreateWithCallback,
which makes its device texture at creation). It is bound with SetImage
(0x00770300) at call time and filled in place with GxTexMarkRectDirty
(0x0058ACD0), the bake's own path for re-baking a cached portrait. A
region the caller re-points before the bake finishes keeps what it was
given, so no region is tracked: the request map, the region-destruction
subscription and ClassicAPI_CancelPortraitTextureRequest are gone. The
function returns nothing, as retail's does.
Portraits are kept until logout, the lifetime of the engine's display-ID
portrait cache (cleared in ShutdownGame). A display with no portrait
camera is done once and stays transparent.
Offsets.h: the portrait block is renamed to engine names with calling
conventions and sources; the duplicates of FUN_M2SCENE_ANIMATE,
FUN_M2MODEL_SET_ANIMATED and GetCameraById are removed, as are the
made-up draw-flag and scene-count fields and the raw device-vtable
slots. Model::Camera::CameraById is exposed instead of being copied.
---------
Co-authored-by: z1xel <ramirezthiago@71gmail.com>
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
The Lua row gains debuglocals, debugstack's coroutine argument,
difftime, gmatch, math.cosh/sinh/tanh, newproxy, scrub, string.byte and
strbyte ranges, string.format's two-digit %n$, %0 in string.gsub and
table.removemulti. The Lua errors section says the window shows each
error's local variables.
debugstack([thread,] [start [, count1 [, count2]]]) returns the stack
of a coroutine when one is passed first, with start defaulting to 0
(the coroutine's innermost level), as 4.3.4's Script_debugstack does.
1.12.1's debugstack (0x703760) has no thread argument. A thread fails
its lua_isnumber and lua_isstring checks, so it returns the thread
itself, and msg .. debugstack(co) raises "attempt to concatenate a
thread value" in the coroutine error paths of WeakAuras, Questie's
ThreadLib, MRT and Zygor.
The engine function still builds the text, so its line format and its
12/10-level head and tail windows are unchanged, which keeps addons
that parse debugstack() for their folder working. It reads levels
through six calls on the state it runs on: lua_getstack (0x6FBAA0) at
0x70383F, 0x70386E, 0x703896, 0x7038AD and 0x703998, and
lua_getinfo (0x6FBC70) at 0x7038CD. Those calls are redirected to
read from the state the new global names for the call: the thread, or
the calling state. The engine function has no callers of its own, so
the global is its only way in and sets that state for every call; an
error part way cannot leave a thread behind for the next call.
The global removes the thread argument, inserts 0 as start when none
is given, and calls the engine function directly in its own frame, so
levels without a thread count exactly as before.
debuglocals([level [, skipFunctionsAndUserdata]]) returns the locals and
then the upvalues of a call level as text, one name=value line each.
It runs only while an error handler runs, as in 4.3.4. 1.12.1's error
function sets no flag for that, but while a handler runs that function
(FUN_FRAMESCRIPT_CALL_ERROR_HANDLER) is a C closure level on the stack;
ErrorCallstack's search for it moves into a header so both modules use
it. level counts as lua_getstack and debugstack do.
Each local comes from lua_getlocal (0x6FBB20, fastcall L/ar + n), then
each upvalue of the level's function (lua_getinfo "f") from
lua_getupvalue (0x6F4660, fastcall L/funcindex + n). Values are
formatted as 4.3.4's FrameScript_PackVariable does, with retail's
spacing (probed: n=7, s="hi", t=<table>{ / k=1 / }): a frame table shows
its name, read from t[0] as FrameScript_GetObject does; a table's fields
show one space in at the top level only; a function shows where it is
defined (lua_getinfo ">nS"). The text stops at 4095 bytes. The second
argument, which retail's error handler passes as true, leaves out
function and userdata values.
Where 4.3.4 would fail inside the handler, this does not: a number key
outside int range is formatted from a copy, not converted in place
(which breaks lua_next), and a key that is not a number or string prints
as its type.
Retail also lists (*temporary) lines, 5.1's names for a level's stack
slots past its locals, including a C level's arguments. 1.12.1's
lua_getlocal is 5.0's and names declared locals only; those slots are
compiler registers that 5.0 and 5.1 allocate differently, so they are
not imitated.
The error window takes the locals as retail's GetErrorData does,
debuglocals(level, true) at the stack's level, and shows them under
Locals ("<none>" when there are none).
LuaCAPI.md had lua_pushupvalues, lua_getupvalue and aux_upvalue one row
off; corrected.
The base-library names that 1.12.1's Lua 5.0 and its compat.lua do not
have:
- gmatch: the global alias of string.gmatch (5.0's str_gfind,
0x7FCFA0), set by value like strmatch and strrev.
- table.removemulti(t [, pos [, count]]): removes count elements from
pos, shifts the rest down with lua_rawgeti/lua_rawseti and returns the
removed elements. 5.0 keeps the length apart from the keys, so like
the engine's table.remove (0x7FB770) it records the new length with
luaL_setn (0x6F4EA0).
- math.cosh, math.sinh, math.tanh: luaL_checknumber (0x6F4C80) and the
C function.
- difftime(t2 [, t1]): C difftime over the two times, next to the
engine's date and time globals.
- newproxy([false | true | proxy]): an empty userdata from
lua_newuserdata. The closure's upvalue is a weak table (its own
metatable, __mode "kv") that marks the metatables newproxy(true)
makes, so only those can be shared.
- scrub(...): replaces each argument that is not a boolean, number or
string with nil, in place with lua_replace (0x6F32B0).
All are registered on both Lua states.
Game::Lua gains RawSetI (lua_rawseti, 0x6F3F60), Replace, CheckLString
(luaL_checklstring, 0x6F4BE0), CheckNumber and OptNumber (luaL_optnumber,
0x6F4CD0); string.byte now uses them instead of local typedefs.
issecure, issecurevariable and forceinsecure are left out. 1.12.1 has
no taint, so they could only return constants, and a constant
"secure" from issecurevariable makes AceHook-3.0 refuse every plain
hook.
1.12.1's str_byte (0x7FC210) is Lua 5.0's: it reads only the start
position and pushes one code, so string.byte(s, 1, -1) silently returns
the first byte alone.
string.byte and the strbyte global now take (s [, i [, j]]) and push the
codes of bytes i..j, with j defaulting to i. Negative positions count
from the end and the range is clamped to the string. The arguments are
read with the engine's luaL_checklstring (0x6F4BE0) and luaL_optnumber
(0x6F4CD0), and positions truncate toward zero as the engine's str_byte
and str_sub do, so a call without j returns exactly what it did before.
Each code takes a stack slot, reserved with lua_checkstack (0x6F2F30).
The engine refuses more than 2048 slots, so a range longer than about
2000 bytes raises "stack overflow (string slice too long)".
compat.lua set strbyte from the old string.byte when the state opened,
so strbyte is re-aliased to the new table entry.
1.12.1's str_gsub (0x7FD0E0) is Lua 5.0's. Its replacement argument
differs from 5.1 in four ways: a table is rejected ("string or function
expected"); in a replacement string, %0, and %1 when the pattern has no
captures, raise "invalid capture index" (add_s checks every %n with
check_capture, 0x7FCE20); a function that returns nil or false deletes
the match instead of keeping it; and one that returns a table deletes
it too instead of raising an error.
The first two only ever raised errors, so the 5.1 behavior cannot break
an existing addon. The function rules can: SuperAPI's
CombatText_AddMessage returns nil to delete the player's own " [0x...]"
GUID from heal text. So function replacements keep 1.12.1's behavior,
and only string and table replacements change. A scan of every gsub
call in the installed addons and the stock FrameXML found no other code
that depends on the old string or function results.
str_gsub's match loop, anchor, count and buffer stay the engine's. Two
parts are replaced:
- The 60-byte replacement-type gate at 0x7FD15E (lua_gettop / isstring /
lua_type == function, then luaL_argerror) becomes a call to a
__fastcall check with ECX = L that accepts a number, string, function
or table and raises "string/function/table expected" otherwise.
- The one call to add_s (0x7FD203 -> 0x7FD2A0, __fastcall ms/b + s/e on
the stack, ret 8) goes to a function with the same signature. A
function replacement calls the engine's add_s unchanged. A string or
number gets 5.1's add_s, and a table gets 5.1's lookup: the first
capture or whole match as the key, a nil or false value keeps the
match, and any other non-string value raises "invalid replacement
value". Both use the engine's push_onecapture (0x7FCF40, plus 5.1's
whole-match case for index 0 with no captures), luaL_addlstring
(0x6F51F0) and luaL_addvalue (0x6F5270).
Both patches check the original bytes or call target and are skipped
when they differ.
The table-replacement shim in StringLib is removed. It wrapped the
pattern in an outer capture so a closure could return the whole match,
and deleted the match for a missing key when the pattern had a
back-reference. string.gsub and gsub are the engine's function again.
1.12.1's str_format (0x7FD3D0) only reads a one-digit argument number:
isdigit(p[0]) && p[1] == '$'. In "%10$s" the "10" is read as a width and
the '$' as the conversion, which raises "invalid option in `format'".
Combat log strings such as ACTION_SPELL_PERIODIC_LEECH_RESULT,
"(%10$s %8$s Gained)", cannot be formatted.
Replace the engine's 18-byte one-digit branch at 0x7FD4AC with a call to
a naked thunk that sets the argument number ([ebp-8]) and the flags scan
start (EBX) for both "n$" and "nn$". EAX/ECX/EDX are dead at the site.
The engine still tests the first digit with its own isdigit, increments
the argument after the site, and does every conversion, so string.format,
format and the C callers of str_format all get the change. The patch
checks the original bytes and is skipped when they differ.
* fix(softinteract): anyinteract yields when the target is out of reach
GetAny treated Reach::Out — the cursor's Unable form — as a usable
target, so with a target too far away the Interact Key pressed the inert
target instead of the nearest object it could interact with.
Prefer the target only while the cursor says it can be used now
(Reach::Now), and fall back to softinteract otherwise. A target behind
the camera still wins while it is in reach: the cursor verdict does not
look at facing.
* docs(api): anyinteract needs the target to be in reach now
The token section said a target that is too far away still counts, which
the implementation no longer does.
* fix(softinteract): anyinteract keeps an out-of-reach target when nothing is picked
Retail 12.1.5, targeting an NPC that is out of reach: facing away from
everything (softinteract nil), anyinteract is the target; facing a nearer
NPC, it is that NPC. The previous change returned 0 in the first case,
so the Interact Key lost the engine's own out-of-reach handling on the
target (the "need to be closer" error, or the click-to-move walk).
GetAny now reads the target's cursor verdict once: in reach wins, then
softinteract, then the target while it is interactable but out of reach.
* feat(interact): honor looseTargeting in C_PlayerInteractionManager.InteractUnit
On retail the Interact Key on a nearer NPC opens its dialog while a
farther unit stays targeted; with no target it targets the NPC. The key
calls InteractUnit("anyinteract") with looseTargeting at its default,
true, which ClassicAPI ignored, so the right-click's select replaced the
target.
FUN_ON_SPRITE_RIGHT_CLICK (0x00492820) is the active-player gate, the
select (FUN_SET_SELECTION_BY_GUID, 0x00493540), then the object's
right-click virtual (vtable +0x60, call at 0x00492881) with
FUN_GAMEUI_IS_KEY_DOWN(0). The select stores only units, so only a unit
other than the current target would move it. With looseTargeting and a
target, that one case runs the gate and the virtual without the select;
every other case still calls the engine function, which nampower also
detours for its right-click guards. The global InteractUnit keeps
targeting.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
Each options page's MinimalScrollBar is now ClassicAPIOptionsScrollBarN,
numbered like the ClassicAPIOptionsControlN controls, so a skin can find
the scroll bars the same way it finds the controls.
The Interact Key page gets rows for Interact With Target and Interact
With Mouseover, and Bags and Items gets AoE Loot under a Loot header.
A row is retail's settings-page binding row: the binding's name, then a
button for each of its two keys. Left click a button and press a key,
mouse button 3-5 or the wheel to bind it; Escape cancels; right click
unbinds that key. The tooltip on a bound key and the page's output line
use retail's strings, added to every locale with Blizzard's translations.
The binding is 1.12's Key Bindings window's (Blizzard_BindingUI): the
same ALT-CTRL-SHIFT chord order, the same skipped modifier keys, the same
KEY_UNBOUND_ERROR check for an action that loses its last key, and the
same put-back when SetBinding refuses a key. A change saves at once with
SaveBindings(GetCurrentBindingSet()), so it lands in the account or
character set in use, as every other control on these pages writes at
once.
While a button listens, a full-screen button on FULLSCREEN_DIALOG takes
keys, clicks and the wheel, as retail's KeybindListener and its input
blocker do. A left or right click on it cancels, and so does hiding the
page.
C_ActionBar.FindSpellActionButtons, HasSpellActionButtons and
IsOnBarOrSpecialBar find a spell on the bars. A slot matches on the
spell ID stored in VAR_ACTION_TABLE under the spell tag, the same test
4.3.4's PutActionInSlot makes, so a macro or item that casts the spell
does not count and a rank matches only itself. A name resolves through
the engine's spellbook resolver. IsOnBarOrSpecialBar also reads the
shapeshift bar's spell array (pointer at 0x00B71108, count at
0x00B71104, as Script_GetShapeshiftFormInfo 0x004B45C0 reads them) and
the pet bar's spell entries (types 1-5, spell ID in the low 16 bits, as
Script_GetPetActionInfo 0x004BDC50 reads them, gated on the pet GUID).
Enum.ActionBarSet is registered; all 120 slots are its Mkb set.
IsStackableAction (global, 1/nil) and C_ActionBar.IsStackableAction
(bool) answer 4.3.4's IsStackableAucItem: the slot's item has a max stack
above 1. C_ActionBar.GetItemActionOnEquipSpellID returns the item's
first spell with trigger 1 (on equip). The item is the item-by-ID
action's, or the one a macro's #showtooltip / #show resolved to, as
4.3.4's CGActionBar::GetItem returns it. Both peek the item cache and
never query it.
C_ActionBar.IsMacroActionWithShowTooltip parses the macro's body with
the parse Macro::ShowTooltip hands the tooltip over on, so it answers
while that module yields or a publisher owns the macro.
C_ActionBar.GetSpell(actionID) returns the spell an action-bar slot
casts, or 0. It is the engine's own slot resolver (0x004E5A50), which
the cooldown, usable and range readers already go through: a spell
action is its spell, a macro is its cached primary spell (+0x564, the
one #showtooltip sets), and an item-by-ID action is the first on-use
spell in its item cache record. An empty slot, a slot outside 1..120,
an equipment set or a macro whose macro is gone gives 0. The spellbook
flag the resolver also hands back is not part of the answer.
GetContainerNumFreeSlots and GetContainerFreeSlots now take the main bank
(-1) and the bank bags (5..10) while a banker is open. The main bank is
gated on the banker GUID (0x00BDD038); bank bags get the gate from the
engine's container-GUID getter (0x004F93E0), which answers 0 for them
while the bank is closed.
A bag's empty slots are counted by the engine's own CountFreeSlots
(0x00622910, __thiscall on the bag's inventory list), and its slot count
comes from that live list instead of the item record. The backpack and
main bank are ranges of the player's list, walked slot by slot. Nothing
walks PackBagSlot per slot any more, so the Lua stack is left alone.
A container that is not there (keyring, empty bag slot, closed bank) now
returns only 0, leaving bagFamily nil.
The bag view SortBags kept for itself moves to Container::Bag so both
modules share it, and Item::Location::EquippedBagInventory becomes
BagInventory (1..10) beside a new BagContainer.
C_Item.GetItemData's bagFamily now goes through BitmaskForRecord, so a
bag whose family field is empty reports the same family there as it does
from GetItemFamily (a Soul Pouch was 0 there, 0x4 here).
LinkUtil.SplitLinkData and SplitLinkOptions looked up string.split on
every call. BigWigs (pepopo978 fork) defines a table-returning
string:split in Plugins/SpellRequests.lua, which replaces the global, so
with it loaded every custom link type resolved to a table, no handler
matched, and SetItemRef rejected the link as unknown.
string.split is registered in C by the DLL before any addon loads, so a
file-local captured when LinkUtil.lua loads always holds the real one.
Fixesbrues-code/pfUI#73
While combat logging is on, each combat log entry is also written as one
CSV line in 4.3.4's PackEvent layout: the subevent, source and dest
(GUID, quoted name or nil, flags as hex), the spell prefix, then the
suffix blocks the entry carries. Fields are written as 1 or nil, damage
values as numbers, and there is no hideCaster, isOffHand or alternate
power type. The line is written from Queue before the events fire, so
it is written even when no frame listens.
The switch is LoggingCombat's own flag (0x00B4FDB8), so /combatlog and
LoggingCombat() control both files. Each time the flag turns on, a new
file starts, named as retail names it:
Logs\WoWCombatLog-MMDDYY_HHMMSS.txt, the local time logging started.
The file is a Storm log opened as LoggingCombat opens its own:
SLogCreate (0x0065A0C0) with flag 4 (append). Lines go through SLogWrite
(0x0065ACE0), which puts the "M/D HH:MM:SS.mmm " stamp in front.
The flag is read once a frame on FrameTick and before each line. When it
turns off, SLogClose (0x00659EC0) writes the buffered lines and closes
the file. This also covers logout: the chat teardown in
CGGameUI::ShutdownGame (0x00498700, its only caller) clears the flag,
and FrameTick runs on the glue screen too. Storm closes what is still
open at exit (0x0065A4B0). LoggingCombat itself is not hooked: it is a
jmp into the enable code the chat log shares, and other DLLs add their
own logs to it.
1.12's Logs\WoWCombatLog.txt keeps its chat-text lines, written by
0x0049B1E8, for the log readers that parse them.
ACTION_RANGE_CHECK_UPDATE(slot, isInRange, checksRange) and
C_ActionBar.EnableActionRangeCheck(slot, enable). Enabled slots are
checked on each world tick while a frame is registered for the event,
with IsActionInRange's own answer (Action::Range::Answer, the macro
unit redirect included), and fire on change. Enabling is counted per
slot, and each enable makes the slot's next check fire, because retail
buttons take their first state from the event. A new Lua state starts
with no slot enabled.
ACTION_USABLE_CHANGED(changes) carries { slot, usable, noMana } for
each slot that changed. The engine's bulk refresh 0x004E5C00 already
compares each slot's pair against the caches IsUsableAction reads
(0x00BC6B60 / 0x00BC67A0). Its per-slot call at 0x004E5C15 is
redirected to record the slots whose pair differs, and its
ACTIONBAR_UPDATE_USABLE signal at 0x004E5C53 to send that event
unchanged and then the new one. No hook.
wow_turbo detours about 380 engine functions to its own reimplementations
from its DllMain. It yields any function whose prologue another mod has
already patched, but ClassicAPI installs from the Load export, which
VanillaFixes calls after every DllMain. So wow_turbo always patches first,
and MinHook copies its jmp into our trampoline: the hook then calls the
reimplementation, not the engine's body. Everything that lives in that body
was lost. The script runners (0x00704D50, 0x00704F10) never reached the
pcall redirects at 0x00704E79 / 0x00705199, so every handler saw self ==
nil. The text builder (0x005CDC20) calls its own emitter, so the inline
texture emitter hook (0x005CCBE0) and the word-wrap redirects at
0x005CDDD3 / 0x005CDE23 never ran.
Before each HookAutoRegister hook is created, a prologue that is a jmp
rel32 into wow_turbo.dll gets its five stock bytes back. The bytes come from
WoW.exe on disk, found through the loaded image's section table. Then the
hook wraps the engine's body. wow_turbo's own rule produces the same state
when it loads after a mod that hooked first. It keeps its original in
place, logs the overwrite and does not re-patch these entries. Release
builds reclaim six: the two runners, the text builder and emitter,
GxSetViewport (0x0058AF60) and the selection-circle update (0x00614A90).
Nothing changes when wow_turbo is not loaded.
UpdateAddOnMemoryUsage summed Gc::Tag::SizeOf over the keys of the tag
map. That is only safe while every free reaches luaC_freeobj (0x006F7260),
whose co-hook erases the key. wow_turbo replaces luaC_collectgarbage
(0x006F7340) with a parallel sweep that frees strings, tables, closures,
userdata and upvalues itself and sends only threads and protos through
freeobj. Dead keys stayed in the map, and the recount read freed blocks:
crash 132.
The recount now walks the lists the engine sweeps: rootgc (G+0x10),
rootudata (G+0x14) and every string-table bucket (G+0x04, size G+0x0C),
and looks up the tag of each live object. 3.3.5's luaC_sizeall walks the
same lists. A create with no context word now erases its address's entry,
so a reused address never carries a dead object's tag, whoever freed it.
Dead entries a foreign sweep leaves are never read, and the pool's address
reuse bounds them. _classicapi_LuaHeapAudit uses the same walk.
Fixes#120
1.12's CSimpleStatusBar::OnFrameUpdate (0x007833C0) draws the fill by
cropping. InstallBarTexture (0x007831F0) sets the texture's
SetTexCoordModifiesRect flag (+0x124), and the update writes the filled
part into the coordinates. The crop shrinks the drawn quad but leaves the
texture's rect at the full bar, so a region anchored to
GetStatusBarTexture() stays on the bar's far edge. Reverse, center,
rotated and tiled bars already moved the texture's points.
The OnFrameUpdate hook now replaces the engine's update for every bar. It
runs the base frame update (0x0076B2C0), clears the crop flag, and moves
the texture's four points in from the bar's edges with CLayoutFrame
SetPoint and doResize, as 4.3.4's OnLayerUpdate does. The fraction comes
from the bar's fill-fraction virtual (+0x98), so SetValue, the ease and
SetTimerDuration all move the rect. doResize queues the texture for the
layout pass before the draw, so anchored regions follow in the same frame.
An empty fill keeps a zero-width rect on the start edge (CalculateRect
0x767A20 has no size test), so its anchors still resolve.
The crop path and the code that handed a bar back to it are removed. A
standard vertical bar now shows the bottom part of its image.
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.
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.
An inline icon texture was given its fontstring's layout scale (layout
slot 0x10, as AddRegionToLayer gives a region its frame's), its anchor
offsets were divided by that same scale, and every tick read each drawn
icon's resolved width back and folded the error into a per-icon
correction, re-placing the icon until it settled within 0.5%.
The textures have no frame, so that machinery has nothing to correct. The
layout constructor (0x00767680) sets the scale (layout +0x58, region +0x7C)
to 1.0 and nothing else changes it without a parent. RelativePointGetX/Y
(0x007A2F90 / 0x007A3070) place a point at the positioned region's own
scale times the stored offset plus the relative edge, so with scale 1 the
fontstring-relative edges land exactly. The scale copy and the divide
cancelled, and the correction stayed at 1.
The icon is now placed with two SetPoints at the raw offsets and the
layout realize (0x00768060, SetDeferResize(0), which resizes at once when
a resize is pending). Removed: the scale copy, the correction and the
per-tick rect readback, and VTBL_LAYOUT_SET_LAYOUT_SCALE, which named the
same slot as VTBL_LAYOUT_SET_SCALE.
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.
The line layout (0x00788750) shows record (position - i) in line i and sets
each line's text through ShowLine (0x00788AF0). When the position moves, by
a message at the bottom or a scroll, every line got the text of its
neighbour: a copy, a freed built string, a new measure and a new shaping.
Before a layout of a shown frame, the line entries are now turned by the
distance the position moves (the layout's record minus the scroll record
+0x348, the record line 0 shows), so each line that stays on screen is the
font string that already holds its text. The layout itself runs unchanged.
SetText (0x00771D80) returns at its SStrCmp when the text is the one the
line holds, so the line keeps its built string and measured height;
SetVertexColor (0x0077F750) skips a repeated colour; the forced Resize only
moves the built string, since the rect callback 0x00772D40 rebuilds only on
a size change. Only lines that come round get new text. Hyperlink buttons
are rebuilt from the lines after every layout, and inline textures are
anchored to their line, so both follow.
The 0x10-byte entries move whole, as the engine's own array grow 0x00789060
moves them with SMemReAlloc. Two lines get new anchors: the new line 0 goes
on the frame, then the old line 0 on the line below it, in that order so no
line is anchored to one that depends on it. Both are anchored as the layout
anchors a new line, in the frame's insert mode (InsertMode::AnchorLine, now
shared). A frame whose last layout placed no line (+0x34C = 0, a hidden
frame's layout) is laid out as before, as is a distance as large as the
lines. A wrong distance costs only the reuse: the layout still sets every
text it shows.
The layout's before-listener now receives the record it runs from.
The ring writer 0x00788150, AddMessage's only callee, lays the lines out
(0x00788750) after every message at the bottom, and the layout sets the text
of every line it shows. k messages in one update cost k layouts of every
shown line, and only the last is drawn.
The writer's layout call (0x00788234) is redirected. The layout is put off
when its result is known apart from line heights: the frame is shown, it had
a message before this one, and its top flag +0x350 is clear (the lines do
not reach the oldest message, and a newer message cannot make them). The
layout's first store, the scroll record +0x348 = the newest record, is made
at once, so GetCurrentScroll and the writer's next check read as before.
The put-off layout runs at the first of:
- the frame's update, between its OnUpdate script and its fader (the call
to 0x0076B2C0 at 0x00788471). The fader, RearmLines and the link-button
rebuild read each line's record through node+0xC, and the writer may have
reused those records.
- the end of the top's update pass, before the second layout-queue drain
(0x00768ED0 at 0x00765799) and the draw, so a message added by any
OnUpdate draws in the same frame.
- RearmLines 0x00788B80 (hooked), which ScrollDown, ScrollToBottom and
ScrollToOffset run at the bottom instead of a layout.
- GetNumLinesDisplayed (0x00793590, reads +0x34C), overridden on the method
registry to lay out first.
- any other layout of the frame, which replaces it. Layout gains a
before-listener for this, since a layout can run Lua.
OnMessageScrollChanged now runs once for the messages a layout covers: the
put-off layout gets the scroll record from before the first of them. The
writer is put off only when both flush redirects apply.
BackFillMessage made every older message move up one record. It copied the
record span into a vector and back, built a new Lua table for the extra
arguments, and laid the lines out again on every call. pfUI's combat-log
refilter calls it once per frame for up to 300 lines, and its chat history
up to 30 times per frame at login.
The records now rotate in place (std::rotate over the 0x18-byte records),
and the extra-argument tables follow each cycle of the rotation in the same
table, so a call makes no garbage. RemoveMessagesByPredicate shares the
rotation.
A shown frame whose lines do not reach the oldest message (+0x350, the top
flag the layout 0x00788750 sets) cannot show the new oldest one. The layout
would place the same lines again, so it is skipped. The one thing it would
change, each laid-out node's record pointer (node+0xC, written by ShowLine
0x00788AF0), moves one record up with its message. The fader 0x00788460,
RearmLines 0x00788B80 and RebuildLinkButtons 0x00788C00 read records only
through that pointer, for nodes 0..+0x34C-1. Clear leaves +0x350 at 0 on an
empty frame, so the skip also needs existing messages. An empty or hidden
frame is laid out as before.
bar:SetValue(value, interpolation) and SetMinMaxValues(min, max,
interpolation) take Enum.StatusBarInterpolation. With
ExponentialEaseOut the fill eases from what it showed to the new value;
GetInterpolatedValue, IsInterpolating and SetToTargetValue read and end
the ease, and SetTimerDuration's interpolation argument now chases the
timer the same way. The curve was measured in a retail 12.1.5 client
at 77 and 30 frames per second and fits to under 1%: each frame closes
the gap in the fill FRACTION by exp(-18 * elapsed), whatever the range,
and the frame whose gap before its step is under 0.001 snaps to the
target. The same probe on 1.12 matches: k = 18.0, a full-bar ease done
in 0.38 s against retail's 0.39.
SetValue stores the target at once (GetValue returns it, OnValueChanged
runs once, with it); a new eased value goes on from the shown fill, and
an Immediate one, or SetToTargetValue, snaps. SetMinMaxValues with the
ease keeps the fraction shown and eases to the new one. A hidden bar
does not ease. Only a target that held still since the last frame may
snap: an eased timer starts at a near-zero gap, and retail chases it
until the timer ends.
The ease lives where the timer does, so StatusBar::Timer becomes
StatusBar::Display: one state per bar holding the timer, the ease and
the fraction drawn. The co-hook on the bar's GetFillFraction virtual
(0x783380) answers that fraction, so the ease keeps 1.12's texture crop
and StatusBar::Fill's styles. Advance runs at the head of
CSimpleStatusBar::OnFrameUpdate (0x7833C0) for shown bars and now takes
the pass's elapsed, which is the step retail takes.
SetValue and SetMinMaxValues stay the engine's Lua methods (0x78F690,
0x78F4B0, read from the method table at 0x87B010), registered over by
wrappers that read the interpolation argument and the fraction shown,
call the engine method for its checks, errors and setter, then start or
stop the ease. Both engine methods read no argument past their own.
Frame::RegionDestruction co-hooks SimpleRegionDestruct (0x77F6F0), the
destructor body every region ends in, and runs its listeners first. It
has exactly three callers: the base region's deleting destructor
(0x77F6C6), ~CSimpleTexture (0x76FD40, a tail JMP; its only caller is
the deleting destructor 0x76FD10) and ~CSimpleFontString (0x770E50, a
tail JMP; called by its deleting destructor 0x770E20 and by a
subclass's, 0x789320). The texture and font string vtables (0x81C718,
0x81C778) are written only by their constructor and destructor, so no
inlined destructor skips the hook. It replaces FontString::Destruction,
the font-string-only hook from the previous commit; the duration text
binding now listens here.
InlineTexturePool kept icon state keyed by font string pointer and
judged a key alive by its first word matching a vtable it had seen
painted. That guess had a hole: a destroyed font string's block goes
back to the region pool and can come back as another font string,
vtable and all, and the dead key's icons then served the new one. It
also read possibly-freed memory on every tick. Now a destroyed key
takes its entry with it at once, so the address starts clean; its icon
regions live on with their parent frame and are hidden on the next
tick, never inside the destructor that reported the death. A destroyed
icon region is dropped wherever it is held, and a live key that loses
one is placed again. The learned-vtable sets, IsLiveFontString and
IsLiveRegion are gone. The SEH latch stays, for the engine region calls
the tick makes from paint-time data.
A font string can now count down by itself. A binding from
C_DurationUtil.CreateDurationTextBinding() takes a font string
(SetFontString), a duration object (SetDuration) and a format: either
SetFormatter(formatter), which writes a NumericRuleFormatter's text for
the remaining seconds, or SetTextFormat(formatString, components), where
each "{}" takes one component's property (Enum.DurationTextBindingProperty)
through its own formatter. SetExpiredText and SetZeroDurationText give
fixed texts, SetUpdateInterval spaces the updates out, and SetEnabled /
Enable / Disable start and stop it. The getters, Copy, Assign,
SetToDefaults, UpdateFontString, GetFormattedText and the Can* checks
are there too; the color curves are not. Duration objects gain
FormatElapsedDuration, FormatRemainingDuration and FormatTotalDuration
on the same formatter. Each answer was probed in a retail 12.1.5 client,
and the same probe matches on 1.12.
A binding is a userdata over a reference-counted native object, like the
duration object and the formatter, and it keeps both of those by
reference, so a change to the duration shows at the next frame. An
enabled binding takes a reference of its own, because it must go on
updating with no Lua object left; a Game::ReloadAutoRegister disables
every binding before the Lua state goes. The text is set through
CSimpleFontString::SetText (0x771D80), only when it differs from the
font string's own text buffer (+0xF0).
The updates run at the head of the UI render root (0x764330), before
the frame pass runs any OnUpdate or draws: Tick::FrameTick gains
AutoSubscribeBefore for this. At the tail, where FrameTick and
WorldTick subscribers run, the text would draw a frame after a timer
bar's fill, which the same pass computes; the probe caught that as a
"3.0" where retail showed "2.9". Nothing is mid-draw at the head, so the
formatter's call into str_format is safe there.
A binding keeps a font string pointer, and 1.12 hands a destroyed font
string's block back to the region pool, where it can come back as
another font string. The new FontString::Destruction co-hooks
CSimpleFontString::~CSimpleFontString (0x770E50, decompiled; its
deleting destructor 0x770E20 calls it, then frees the block) and runs
its listeners first, like Frame::Destruction does for frames. The
binding drops the pointer there and writes nothing after.
GetTotemDuration(slot) now returns a duration object, as retail's does:
the totem's span from its spawn stamp to its expiry, in exact
GetTime() seconds rather than GetTotemInfo's whole seconds, or a zero
span for an empty slot, since retail's return is never nil. Each call
returns a new object.
A status bar can now fill by itself from a duration, with no Lua on each
frame. bar:SetTimerDuration(duration [, interpolation [, direction]])
takes a duration object from C_DurationUtil.CreateDuration(), and
Enum.StatusBarTimerDirection picks ElapsedTime (fills) or RemainingTime
(empties). GetTimerDuration() returns it. UnitCastingDuration(unit) and
UnitChannelDuration(unit) return the time span of a unit's cast or
channel as a duration object.
The duration object is a userdata like the NumericRuleFormatter: a
pointer to a reference-counted span (start, total, mod rate) that every
Lua object and every bar holding it own a reference to. Times are
GetTime() seconds read through Time::Clock::NowSeconds, so they agree
with GetTime() exactly. Its methods set the span from a start, an end
or both, and read the start, end, total, elapsed and remaining time,
the two percents and the started / expired / active state, in real or
base time (Enum.DurationTimeModifier). The answers were probed in a
retail 12.1.5 client and the same probe matches on 1.12.
1.12 already draws a bar's fill from a virtual, not from its stored
value: CSimpleStatusBar::OnFrameUpdate (0x7833C0) crops the bar texture
to the fraction its vtable slot +0x98 returns (0x783380,
(value - min) / (max - min), or 0 for an empty range; disassembled).
The timer co-hooks that function, so a timed bar keeps 1.12's texture
crop. StatusBar::Fill's reversed, centered, turned and tiled layouts
now take their fraction from the same virtual, so they follow a timer
too. Fill's OnFrameUpdate co-hook calls Timer::Advance first, which
marks the fill changed when the share moved and caches the share it
drew. Shown bars update on every frame; hidden bars do nothing and are
right on their first frame shown.
As in retail, the timer stores 0 for the value and the range (written
directly, so no OnValueChanged runs), SetValue leaves it running, and
SetMinMaxValues ends it: Frame::MinMaxChanged's co-hook on the range
setter (0x783270) clears the timer first. The bar keeps the duration
object, not a copy, so a change to the object shows on the next frame.
ExponentialEaseOut is accepted and draws as Immediate for now.
UnitCastingDuration and UnitChannelDuration share one per-unit lookup
with C_Spell.UnitCastingInfo / UnitChannelInfo, so they take the same
unit tokens and have the same limits. Each call returns a new snapshot;
it does not follow pushback or the end of the cast.
The name-query callback (0x5FB86E) and the creature-cache reply (0x6046C1)
call CGUnit_C::ReleaseNamePlate (0x608A10) so the plate is rebuilt with the
name, and the next tick takes a plate again through AllocNamePlate
(0x6087F0). The free list is FIFO: release links the frame in at the tail
and alloc takes s_freeNamePlates[2], the head. So unless the list was empty,
the unit gets a different CGNamePlateFrame. The per-tick diff compared GUIDs
only. The GUID was in both snapshots, so no event fired, and an addon that
keys its state by frame kept the old, hidden frame.
A binding is now the (GUID, frame) pair. A unit on a new frame gets
NAME_PLATE_UNIT_REMOVED for the old binding, then NAME_PLATE_UNIT_ADDED for
the new one. The REMOVED pass now runs before the ADDED pass, so the old
binding's slot is free before the new one is assigned. A re-acquire that
hands back the same frame still fires nothing.
During REMOVED, GetNamePlateForUnit / GetNamePlateForGUID now return the
frame being removed before they read unit+0xE60. After a rebind, that field
already names the new frame, and the getters would have given the handler
the wrong plate.
/etrace and /eventtrace now open a backport of retail's
Blizzard_EventTrace, the load-on-demand addon ClassicAPI_EventTrace
embedded in the DLL. It replaces the old event trace frame in
ClassicAPI_DebugTools, and DebugToolsSavedVars with it; the panel saves
EventTraceSavedVars.
What differs on 1.12.1:
- RegisterAllEvents adds the frame to every event slot, so it opens the
listener gate of each ClassicAPI event that builds its arguments only
for a listener (UNIT_AURA_DELTA, the combat log and cast events). The
panel registers all events only while it is shown or logging while
hidden; otherwise it keeps PLAYER_LOGOUT, which saves its variables,
since this client has no ADDONS_UNLOADING.
- An engine event signalled by a number with no name arrives with a nil
event and is not logged.
- An event's table arguments are copied when logged, and the tooltip
lists their contents. UNIT_AURA_DELTA refills the same tables on every
fire, so a kept reference shows only the latest delta.
- No tool windows, ImGui debug tools or secret values.
The window's templates are new shared templates in !!!ClassicAPI:
ButtonFrameTemplate and PortraitFrameBaseTemplate (with
PortraitFrameMixin / TitledPanelMixin), UIPanelCloseButtonNoScripts,
PanelResizeButtonTemplate, InputBoxInstructionsTemplate,
SharedTooltipTemplate, VisibleWhilePlayingAnimGroupTemplate, and
GameTooltip_AddHighlightLine / GameTooltip_AddColoredDoubleLine. Art
this client lacks is drawn with its own textures: tooltip border
chrome, the world map magnifier, the cancel button, a turned chat
expand arrow for the resize grip, and the panel button in three slices.
The scroll bars are the 1.12 bar, whose art is wider than its frame,
so the lists leave room for it.
Retail's search box is ClassicAPISearchBoxTemplate. Turtle's FrameXML
registers its own SearchBoxTemplate first, and 1.12 keeps the first
template of a name, so the retail one takes that name only through a
TOC line marked [ExcludeLoadGameType turtle].
The EVENTTRACE_* strings and SLASH_EVENTTRACE1-4 come from Classic
Era's GlobalStrings for each client locale but koKR.
A TOC file line can now end in [ExcludeLoadGameType ...] as well as
[AllowLoadGameType ...]. An unknown condition drops its line, so a
line excluded for some other game type used to be dropped here too.
Both lists may name "turtle", a ClassicAPI extension like the
_Turtle.toc flavor: it matches when Turtle::Detected() (the engine's
TURTLE_WOW_VERSION or the glue TURTLE_* globals), and "vanilla" matches
on every client. So [ExcludeLoadGameType turtle] loads a line
everywhere but Turtle.
The TOCs of the addons embedded in the DLL now go through the same
rewrite. The FUN_FILE_READ hook serves an embedded addon's file from
disk or from the DLL as before, now in ReadAddonFile, and passes a read
that succeeded to TocRewrite::Transform, which rewrites only TOCs.
When a frame finishes loading from XML, CSimpleFrame::PostLoadXML
(0x0076A2F0) clears the loading flag and, for a visible frame, ends the
layout deferral of the frame, its title region and its registered
regions with 0x00768060(0). That call resolves a pending layout at once
(0x007680E0 with force 1), so OnSizeChanged runs before the frame's
OnLoad, and before its children, built next, run theirs. Building the
children first does not help: resolving a child ends the deferral of the
frame it anchors to and lays that frame out too (0x007A2F90).
Retail lays these frames out later, from its end-of-frame resize list.
Its EventFrame, ScrollBox and scroll bars trigger callbacks from
OnSizeChanged on the registry their OnLoad creates, so a retail window
that loads visible raised "executingEvents (a nil value)" from each of
them.
The three calls (0x0076A310, 0x0076A324, 0x0076A35B) now go to
EndLoadDeferral: it clears the deferred bit (0x02 of the layout flags
at +0x3C) the same way, and sends a pending layout (0x00768310) to the
engine's layout queue with 0x007680E0(0), the path SetPoint takes. The
queue drains on the top's update and in the interface build, after
every OnLoad of the load. A script that reads a size or an edge still
lays its frame out at once. The minimap and tooltip finalizers call the
base first and read no rect after it. Each redirect checks the call's
target first, so a site another DLL has patched keeps its code.
For a region with no set size, 1.12's Script_GetWidth (0x007A1E00) and
Script_GetHeight (0x007A2030) return the rect span without dividing by
the region's layout scale. The value is the size times the effective
scale: a 160-high track at a UI scale of 0.91 answers 145.6.
dceec8b replaced both getters with the divided form. That broke vanilla
addons tuned to the scaled value. BetterCharacterPanel sets its paperdoll
column from PaperDollFrame:GetHeight() with padding tuned at one UI
scale, so the resist icons and the stat list left the frame.
- GetWidth / GetHeight / GetSize call the engine getters again. With
ignoreRect, a region with no set size still answers 0.
- New region methods GetUnscaledWidth / GetUnscaledHeight /
GetUnscaledSize give the size in GetTop / GetBottom units: the explicit
size, else the rect span over OFF_REGION_EFFECTIVE_SCALE after a
pending resize. GetRect and GetScaledRect keep using these.
- The ported Lua in !!!ClassicAPI (ScrollBox, Menu, LayoutFrame, Util)
calls the GetUnscaled* names wherever it measures a region.
Fixes#118
The Texture row lists the SetTexture wrap modes and the tile methods. The
XML attributes row now names the element attributes that ClassicAPI reads,
for frames, buttons, textures, font strings, status bars and edit boxes,
and intrinsic frame types.
texture:SetTexture(file, wrapModeHorizontal, wrapModeVertical), the XML
hWrapMode / vWrapMode attributes, texture:SetHorizTile / GetHorizTile /
SetVertTile / GetVertTile and the XML horizTile / vertTile attributes.
Wrap. 1.12 fixes a texture's wrap when its file loads.
CSimpleTexture::SetTexture (0x00770200) builds the flags word with
CGxTexFlags (0x0058A980) from one wrap argument for both axes, and
TextureCreate (0x00449D90) caches the handle under the name and that
word, so a repeating copy of a file is its own shared texture. The device
reads one bit per axis (3 for U, 4 for V), repeat or clamp, so the mirror
and border modes clamp. A texture with a mode or a tile flag loads
through a co-hook on that SetTexture: the same body, with a repeat per
axis. The engine's same-file early-out (0x0044AC70) ignores flags, so the
co-hook also compares the held image's wrap (its device texture's flags
at +0x3C, or a loading BLP handle's at +0x150), and for the same file it
swaps in the other copy and keeps the pixel shader. Changing a mode or a
tile flag reloads the held file the same way. The Lua method is
registered again so it stores the wrap arguments before the engine
handler (0x0079BB40) runs: true or "REPEAT" repeats, anything else clamps.
Tiling. A tiled axis repeats, and each non-zero coordinate on it becomes
the texture's length in script units over the image's size in texels.
The script units are the engine's own coordinate push: DivideByScreenScaleX
(0x0041AE40) of aspect (0x0041AD70) x 1024 x length, over the effective
scale. The texels are the device texture's width and height (+0x24 /
+0x28): the file's size, halved only past the GPU limit and untouched by
BaseMip. The layer batch keeps a pointer to the eight coordinates
(0x00772FD0), so the count is written whenever an input changes: after
each corner store, after both native SetTexCoord forms (0x00770410,
0x007704C0), on a tile change, and after CSimpleTexture::Emit
(0x007706E0), whose device lookup loads the image. A tile change counts
against the held image before the repeating copy of the same file
replaces it, since the copy has no size until it is drawn.
A texture showing an atlas does not tile (the atlases are parts of their
files), and neither does one with SetTexCoordModifiesRect on. SetAtlas
clears modes and tiling. A tiled status bar texture takes
StatusBar::Fill's anchored layout instead of 1.12's crop, which would size
it by the count, and its fill sets no coordinates. An XML <TexCoords> that
moves a tiled axis off 0..1 logs "Invalid TexCoords value (horizTile is
on)" at error level (new Xml::Error) and falls back to the whole image.
Also corrects the AtlasData.h note on the atlas tile flags: 4 is
horizontal and 2 is vertical.
MinHook takes one hook per address. Texture::Mask hooked the
CSimpleTexture constructor (0x0076FC40) to drop its state when pool memory
is reused, and Texture::Transform hooked the corner store (0x007705B0) to
turn the quad again after each layout. Texture wrap modes and tiling need
both hooks too, so each hook now has an owner that fans out to listeners:
- Texture::Construct runs its listeners before the constructor, on the
memory it is about to build. Mask listens.
- Texture::CornerStore runs its listeners after the store. Transform
listens.
The store writes only the corners. The layer batch reads them through a
pointer on every draw, so nothing marks the layer changed.
The XML number parse through SStrToFloat (0x0064AAA0) moves into
Xml::FloatAttr, which NativeSetters and Transform's rotation attributes
now share.
Four more later-client XML attributes, each applied only when present and
non-empty, after the engine has loaded the node.
- Texture `rotation` (degrees) and FontString `degrees` / `radians`
(`radians` wins when both are given), parsed with SStrToFloat
(FUN_SSTR_TO_FLOAT): Texture::Transform's rotation about the default
pivot. The bodies of texture:SetRotation and fontstring:SetRotation
move into SetTextureRotation / SetFontStringRotation, which the Lua
methods and the Xml::TypeLoad subscribers both call.
- Frame `registerForDrag`: the names, split on spaces and commas with
Storm's tokenizer (FUN_STORM_STR_TOKENIZE) as registerForClicks is,
passed to Frame:RegisterForDrag itself (FUN_SCRIPT_FRAME_REGISTERFORDRAG
0x00776D60) as its own Lua call. That function ORs LeftButton 1,
MiddleButton 2 and RightButton 4 and stores the mask at frame+0xFC;
there is no setter to call instead.
- AnimationGroup `parentArray`: the group is appended to region[key].
The append moves out of Xml::ParentKey into Xml::AppendToArray, which
frames, regions and groups now share.
Tested in game with an XML test addon: rotation="90" and degrees="90"
read back as pi/2, two groups land in parentArray in load order, and a
frame with registerForDrag="LeftButton" drags.
Later clients' animation attributes and the methods behind them, on the
animation port's own objects.
Alpha fromAlpha / toAlpha (SetFromAlpha / SetToAlpha / GetFromAlpha /
GetToAlpha): an absolute alpha. Each update the target's alpha becomes
from + (to - from) x progress, through Region::SetAnimAlpha, which takes
AddAnimAlpha's target rule but sets instead of adding: a frame's own
alpha through its vtable setter, a texture's or font string's vertex
alpha through FUN_REGION_GET_COLOR / FUN_FONTSTRING_SET_COLOR. Earlier
orders apply at full progress before the current order updates, so the
last write wins. Setting either end turns the mode on, an unset end is 0,
and SetChange returns to the relative change. Absolute values and the 0
default follow Blizzard's own code: it starts fades with
SetFromAlpha(region:GetAlpha()) and fades in with toAlpha="1" alone.
AnimationGroup setToFinalAlpha (SetToFinalAlpha / IsSetToFinalAlpha):
when the group finishes (Finish included), Region::KeepAnimAlpha makes
the alpha each alpha animation's target ended on the stored alpha, so the
end restores that. Stop restores the stored alpha as before.
targetKey / childKey (SetTargetKey / SetChildKey), with SetTarget,
SetTargetName, SetTargetParent and GetTarget: a key path from the
animation, where $parent steps to the group, then its region, then that
region's parent; childKey "X" is "$parent.$parent.X". The steps among the
animation objects are taken by Region::FindRegionByKey, and the rest goes
to the relativeKey resolver in Xml::Anchors, now public with a switch for
its leading-global rule. A name or key is looked up again on Play, as
4.3.4 looks up `target`; the setters also look it up at once and return
whether they found a region. GetTarget returns the group's region when
there is no target.
Scale fromScaleX / fromScaleY / toScaleX / toScaleY (SetScaleFrom /
SetScaleTo / GetScaleFrom / GetScaleTo): the scale goes from `from` to
`to`, passed to AddAnimScale as 1 - scale. SetScale sets the end, so
4.3.4's scale is the case from = 1 and its results do not change.
Tested in game with an XML test addon: childKey and targetKey resolve,
the absolute alpha and the last-write-wins rule give each order's end
value, setToFinalAlpha keeps 0.5 after the group finishes, a group without
it restores alpha 1, and the from/to scale values load.
Later clients read these attributes in their XML loaders; 1.12's do not.
Each is now read after the engine has loaded the node (Xml::FrameLoad for
frames, Xml::TypeLoad for the rest) and goes through the setter the
matching Lua method uses. Each applies only when present and non-empty,
so an element's own value overrides its template's.
Frames:
- scale: Frame:SetScale's path (0x00775140). A negative scale is refused,
anything else goes to SetFrameScale (FUN_FRAME_SET_SCALE 0x0076AC10,
__thiscall(frame, float, force), ret 8) without force. A Model keeps
`scale` as its model scale, which its own loader reads.
- dontSavePosition, propagateKeyboardInput: the existing frame flags,
through FUN_FRAME_SET_FRAME_FLAG.
Textures and font strings:
- alpha: parsed as the frame loader parses its own `alpha` (SStrToFloat,
clamped to 0..1, truncated to a byte), then set as Texture:SetAlpha and
FontString:SetAlpha set it (0x0079B580, 0x0079CB70): the region color
from FUN_REGION_GET_COLOR with its alpha byte replaced, through
FUN_FONTSTRING_SET_COLOR. It applies after the node's <Color>.
- desaturated (textures): Texture::Desaturation's full amount, the same
as SetDesaturated. It applies whenever present; an empty value is false.
- indented (font strings): the style bit SetIndentedWordWrap sets.
Status bars:
- reverseFill, rotatesTexture, fillStyle: StatusBar::Fill's modes, read
after the status bar loader has set the BarTexture. An unknown
fillStyle name changes nothing.
Tested in game with an XML test addon: every attribute set its value, and
parentKey, wordwrap and countInvisibleLetters still load.
MinHook allows one hook per address, so the texture, font string and
button loader hooks lived in Xml::ParentKey, which then read every other
module's attribute for it (mask, atlas, wordwrap, registerForClicks), and
CountInvisibleLetters hooked the EditBox loader on its own.
Xml::TypeLoad now owns the hooks on the engine's per-type node loaders,
the way Xml::FrameLoad owns FUN_XML_FRAME_LOAD's, and fans out to
subscribers after the engine has loaded each node:
- texture FUN_XML_TEXTURE_LOAD 0x0076FE20
- font string FUN_XML_FONTSTRING_LOAD 0x00770F40
- button FUN_XML_BUTTON_LOAD 0x007788C0 (CheckButton's loader
calls it first)
- edit box FUN_XML_EDITBOX_LOAD 0x00779FB0
- status bar FUN_XML_STATUSBAR_LOAD 0x00782EF0 (new; calls
FUN_XML_FRAME_LOAD first at 0x00782F06, ret 8)
All five share the sub-object convention __thiscall(loader, node,
status), ret 8, object = loader - OFF_XML_LOADER_SUBOBJECT. An inherited
template goes through the same loader first, so a node's subscribers run
after its templates'. The texture and font string loads keep running in
the node's mixin scope (Xml::Mixin::Begin / End), as before.
Each attribute is now read in the module that owns its setter:
Texture::Mask (mask), Texture::Atlas (atlas, useAtlasSize),
FontString::WordWrap (wordwrap), Frame::ClickMask (registerForClicks) and
EditBox::CountInvisibleLetters (countInvisibleLetters). The XML-only
entry points Atlas::SetFromXml, WordWrap::Set and ClickMask::SetFromXml
become private, and ClickMask.h and WordWrap.h go. ParentKey keeps only
its own binding work. Same hook addresses, same order around the engine
call, no behavior change.
1.12's loaders read neither attribute: the Button loader (0x007788C0)
has no registerForClicks, and the font string loader (0x00770F40) reads
nonspacewrap but not wordwrap. Both were silently ignored, so ported
templates got the default click mask and wrapping text.
Both are read in the loader hooks Xml::ParentKey already owns, after
the engine's loader and before OnLoad, and only when present and
non-empty, so a node's value beats its template's and an OnLoad call
still overrides it. No new hooks.
registerForClicks follows 3.3.5's CSimpleButton::LoadXML. Storm's
tokenizer (0x0064AE50, the one 3.3.5 calls) splits the value on spaces
and commas. Each name ORs in its bits through
Frame::MouseRegistration::MaskForName, the RegisterForMouse name table
(3.3.5's MouseButtonStringToBitmask, AnyUp / AnyDown included). The
result replaces the mask through the engine's own setter 0x00779730
(__thiscall(button, mask), ret 4, writes only +0x330).
wordwrap goes through FontString::WordWrap::Set, the body of
fontstring:SetWordWrap: it clears the font's override of the no-wrap
style bit and lays the string out again when the value changes.
Tested in game: WowStyle1DropdownTemplate's Text (wordwrap="false")
now reports CanWordWrap() = nil.
Adds the three call stack heights an error handler uses to start its
stack at the code that failed:
debugstack(GetCallstackHeight() - (GetErrorCallstackHeight() - 1))
A height counts levels as lua_getstack (0x006FBAA0) does, and so as
debugstack does: C functions and lost tail calls count, and level 1 is
the caller.
1.12.1 records no error height, but every error report runs one C
function, FrameScriptCallErrorHandler (0x00703B40, __fastcall(L)). It
pushes the seterrorhandler function (registry ref 0x008722CC), moves it
under the message and lua_calls it. Nothing calls it directly: state
open pushes it as a C closure and refs it (0x008722C8). Every script
pcall passes that closure as the errfunc, so Lua calls it at the point
of the error before the stack unwinds; a chunk that fails to compile is
reported by a pcall of it (0x00704AE0). ClassicAPI's securecall,
hooksecurefunc and script runners pass the same ref.
So while any handler runs, that closure's level sits directly above the
code that failed. GetErrorCallstackHeight walks the levels with
lua_getstack and lua_getinfo "f", finds the innermost one whose function
is 0x00703B40 (lua_tocfunction, 0x006F3720) and answers the height below
it, or nil when no error is being reported. There is no hook, and
nothing is recorded, so a handler that fails part way leaves nothing
behind.
SetErrorCallstackHeight sets the height for a handler called with no
error raised. It applies only while no 0x00703B40 level is on the stack,
so a value left set by a failed handler cannot move a later error's
stack. A new Lua state starts with no value set.
Users:
- The Lua error window takes its stack this way, so it starts at the
failing code even when another addon wraps the handler.
- CallErrorHandler and assertsafe set the height around their direct
handler call, so they report from their caller.
- Game::Lua gains GetStack, GetInfo and ToCFunction; SourceLocation uses
them in place of its own copies.
Docs: the xpcall and coroutine notes said error() returns without
raising. Stock error (0x00702970) ends in lua_error (0x006F4440) and
raises. pfUI replaces the global error with one that prints and
returns, which is what those notes described.
Tested in game: with seterrorhandler wrapping the old handler, a nil
index in a local function f showed a stack that starts at f.
The Lua error window (/luaerrors) moves from the load-on-demand
ClassicAPI_DebugTools into !!!ClassicAPI and becomes the client's error
display. Each error opens it with the message, time, count and stack, and
the arrows page through every error so far.
1.12.1's error handler is FrameXML's _ERRORMESSAGE (BasicControls.xml). It
reports an error as ScriptErrors_Message:SetText(message) and then
ScriptErrors:Show(), and only while the stock box is hidden. The window's
OnLoad takes those two slots, the same two !BugGrabber 2.1.1 takes: SetText
records the error and Show does nothing, so the stock box stays hidden and
every error arrives. Errors still pass through the handler first, so:
- !BugGrabber loads after !!!ClassicAPI and takes the slots back. BugSack
gets the errors and the window does not open.
- An addon that calls seterrorhandler (pfUI) replaces _ERRORMESSAGE, so
neither shows. One that wraps the old handler still ends here.
The engine's error function (0x00703B40) is C. It runs at the point of the
error, before the stack unwinds, and calls the registered handler. From the
SetText slot, level 1 is the slot, 2 is _ERRORMESSAGE, 3 is that C function
and 4 is the code that failed, so the stack starts at debugstack(4), the
level !BugGrabber's GrabError reads from the same slot.
The text is ClassicAPI's ScrollingEditBoxTemplate with a MinimalScrollBar.
The bottom row has Reload UI, arrows that wrap around the index label, and
Close. /luaerrors opens or closes the window and /luaerrors clear empties
it; the old on/off handler install is gone.
Not tested in game yet.
Fires (no payload) each time the game applies the interface scale to
UIParent.
In 1.12 every scale change goes through one function, SetUiParentScale
(0x00494550, void __stdcall(float), ret 4). It raises the value to 0.64,
calls SetScale with force (0x0076AC10) and drains the layout queue
(0x00768ED0), and does nothing while UIParent (0x00B4B44C) is null. It
has six callers:
- the uiScale cvar callback (0x00490770, two sites)
- the useUiScale cvar callback (0x004907F0, two sites)
- OnDisplaySizeChanged (0x00492E90) when useUiScale is on
- the automatic scale ApplyAutoUiScale (0x00492F70)
One MinHook on it fires the custom event after the original returns,
only while UIParent is set. The game UI's Initialize stores UIParent
(0x00490077) and its Shutdown clears it (0x00490CA4), so the event never
fires on the glue screen. Each path calls the setter once, so one change
fires one event; a resize fires it before DISPLAY_SIZE_CHANGED.
Tested in game: useUiScale on, uiScale 0.8 and useUiScale off each fired
one event with the new scale (0.91, 0.8, the automatic 0.9).
Adds C_AutoComplete.GetAutoCompleteResults, C_AutoComplete.IsRecognizedName,
Enum.AutoCompleteEntryFlag and Enum.AutoCompletePriority, and the cvars
autoCompleteResortNamesOnRecency, autoCompleteWhenEditingFromCenter and
autoCompleteUseContext. ClassicAPI only answers the queries; an addon draws
the list of names.
1.12.1 keeps no autocomplete list, but it keeps every list the names come
from, so each query reads them where the client keeps them:
- party: the four GUIDs at VAR_PARTY_GUIDS (0x00BC6F48), names from the
name cache, online from the member stats block
- raid: the VAR_RAID_MEMBER_PTRS slots (0x00B712A8) and their online bit
- guild: the GuildMemberInfo roster at 0x00B72704, GUID at +0x00 and the
online word at +0x48 (stored at 0x004D0C22, tested by GetGuildRosterInfo
at 0x004D13C5). Read only while the player's guild key is set, the test
IsInGuild (0x00516DE0) makes, because the client keeps the old roster
after a /gquit
- friends: the 50 slots of the social singleton
Whisper partners are the one list the client does not keep. The chat
dispatch hook (FUN_0049A870) reports each whisper and whisper inform
(types 6 and 7, not the addon language -1) with the sender GUID it already
resolves. Logging out clears the list.
Names match case-insensitively by UTF-8 code point; Text::Utf8::CompareI
now takes a character limit. Results come most recent whisper first, then
by name. A result's priority is its closest tie: friend, guild, group,
whisper.
GetAutoCompletePresenceID and GetAutoCompleteRealms are constant answers in
Compat.lua. The three cvars are on a new Social page of the options panel.
Adds C_SpellActivationOverlay.IsSpellOverlayed (and the global
IsSpellOverlayed), Enum.ScreenLocationType, and the four
SPELL_ACTIVATION_OVERLAY_* events. Nothing is drawn: an action-bar or
UI addon draws the alerts and the glows from these.
Glows come from the engine's own reactive-spell list. AddSpellToBook
puts every learned spell whose record has AttributesEx4 0x200 on the
list at 0x00B71150 (count 0x00B7114C), one 8-byte {spellID, usable}
entry per name. FireUsableEvents (0x004B31C0) retests the list with
the engine's usable check, stores each answer, then signals
SPELL_UPDATE_USABLE (0x107). The module subscribes to that signal
through Event::SignalHook and reads the stored answers, so the verdict
is the engine's (rage, target health, aura states, and the hidden
combo point behind Overpower) and no new hook is needed. A usable entry
glows every spellbook spell with the same name, which is the list's own
identity rule, so a bar slot with any rank glows. On stock 1.12.1 this
is Execute, Overpower, Revenge, Riposte, Counterattack, Mongoose Bite
and Hammer of Wrath; Turtle's Spell.dbc changes the set by itself.
Alerts come from two Blizzard rows whose aura exists unchanged in 1.12:
Shadow Trance (Nightfall art, glows Shadow Bolt through its class mask
via Spell::Lookup::IsFitToFamily) and druid Clearcasting
(Natures_Grace art). An Aura::Source observer reconciles on the
player's aura add/remove, rescanning the descriptor so counts can't
drift. The texture is a path; 1.12 has no file data IDs.
On world entry, HIDE fires with no spell ID and every active alert
fires SHOW again, so a /reload redraws them. Glows already lit before a
/reload do not re-fire; a button reads IsSpellOverlayed when it draws.
Logging out clears the state without events.
Event::EnteringWorld gains an observer list, because it claims
PLAYER_ENTERING_WORLD in the signal chain and later subscribers never
see it. Event::Custom's reservation cap goes from 96 to 128: the four
new events filled the old cap exactly, and a name past the cap is
dropped silently.
The persistent name cache copied every name reply into its own map, so
each player the engine named this session was held twice. The copy also
went stale. On a rename the server sends SMSG_INVALIDATE_PLAYER (0x31C)
and HandleNameInvalidate 0x00555600 frees the engine's record, but our
copy kept the old name, and GetPlayerInfoByGUID / UnitNameFromGUID fell
through to it.
The store now holds only the players the engine's name cache
(0x00C0E228) does not:
- A Net::PacketDispatch subscriber reads SMSG_NAME_QUERY_RESPONSE (0x51)
in the same order as HandleNameQueryResponse 0x005551A0 and drops our
entry just before the engine stores its record. This replaces the hook
on NameCacheStore 0x0055F310. The backstop save runs before the drop,
so no save misses the player.
- The same subscriber drops our entry on SMSG_INVALIDATE_PLAYER.
- The engine empties its cache only at world entry: NameCacheClear
0x00560400, called from CGGameUI::InitializeGame through 0x00555740.
A hook there copies the engine's records into the store first, while
the store still holds the realm they came from.
- At exit the engine frees the cache from its atexit handler
(NameCacheSave 0x0055EC70). Storm's exit handler 0x0064CC30 runs every
atexit handler before ExitProcess, so DLL_PROCESS_DETACH was too late
to read it. At the first world entry the clear hook registers our save
with the exe's own _atexit (0x00409AEF). Handlers run newest first, so
ours runs before the engine's. Detach now calls Shutdown, which never
reads the engine's cache.
- A save writes our store, then the engine's records, so a load applies
the engine's data over ours.
- C_PlayerCache.RememberPlayer leaves alone a player the engine holds.
One hook removed (0x0055F310), one added (0x00560400).
The persistent name cache cut names at 16 bytes. A Chinese character is
3 bytes in UTF-8, so a 6-character name lost part of its last
character. The limit is now the engine's own: the name cache store
(0x0055F310) copies the name with SStrCopy(dst, src, 0x30) and the
realm with SStrCopy(dst, src, 0x100), now PLAYER_INFO_NAME_SIZE and
PLAYER_INFO_REALM_SIZE in Offsets.h. A longer name from Lua is cut on
a UTF-8 lead byte, never inside a character.
Entries are now keyed by GUID, the engine name cache's own key, and
keep the record's server name (+0x30, empty for a player on this
realm). The by-name index uses the form the engine itself shows for a
player from another realm: ClientChatHandler (0x0049D560) builds the
sender as name, "-", and the realm with spaces and tabs removed. A
bare name stands for this realm. Player::FullName builds and parses
that form. Two players with one name from two realms no longer replace
each other, C_PlayerCache.GetPlayerInfoByName takes "Name-Realm" (a
chat sender name as it comes), and the persistent fallbacks of
GetPlayerInfoByGUID and UnitNameFromGUID return the stored realm. A
"Name-Realm" skips the by-name search and the friends list, which keep
no realm. The engine name cache walk moved from Unit::Identity into
Player::Info, its one caller.
The cache is one flat file per realm,
WTF\ClassicAPI\NameCache-<realm>@<realmList>.txt, in a v5 format split
on tabs (a realm can hold spaces): guid, name, realm, class, race, sex.
The v4 file under WTF\ClassicAPI\<realmList>\<realm>\ is migrated on
first load and deleted, with its emptied folders, once v5 is saved.
The old import from the per-account path is gone.
The store loaded once per process and saved to whatever realm was
current, so logging out into another realm wrote the first realm's
players into the second realm's file. It now records the file it
holds: every access compares that with the current realm's file, and
on a change saves the old realm's entries to their own file before
loading the new one. A failed rename leaves the cache dirty for the
next flush.
Verified on Octo: all 63,178 N'Zoth v4 entries migrated unchanged,
13 of 13 C'Thun entries migrated, the v4 folders were removed, and a
N'Zoth to C'Thun switch in one session kept the two files apart.
Fixes#119
CGUnit_C::GetUnitName (0x00609210) takes a realm out-pointer as its
stack argument, not the flags word Offsets.h called it. For a player
whose name-cache record has a non-empty server name (record +0x30) it
stores a pointer to that string, and otherwise leaves the pointer alone
(0x0060926B-0x00609283). Vanilla's Script_UnitName (0x00517020) passes
&realm there and returns it as UnitName's second value. The record's
server name is the realm string SMSG_NAME_QUERY_RESPONSE carries:
Tortoise sends it empty, a cross-realm server fills it.
UnitNameFromGUID pushed a hard-coded "" instead. NameFromGuid now passes
the out-pointer through, as Script_UnitName does, and gains a step
between the friends list and the persistent cache: the engine name
cache record itself (FUN_PLAYER_INFO_LOOKUP with no callback, a passive
peek), which also gives the realm for players out of range. Before, a
player who whispered from far away resolved only with the persistent
cache on. UnitSpellTargetName shares NameFromGuid and finds those
players too. The realm is "" when the record has none, or when the name
came from the friends list or the persistent cache, which stores no
realm. Retail documents both returns as non-nil strings.
GetNameAndServerNameFromGUID in the addon's PlayerUtil returned
GetRealmName(), the local realm, for every GUID. It now returns
GetPlayerInfoByGUID's realm, as retail's UnitUtil does, so a player on
the local realm gets "" and code that appends "-" .. realm only when it
is non-empty works.
Seven files declared their own function-pointer type for 0x00609210,
all with the wrong int *outFlags argument. Unit::Identity::NameForUnit
is now the one wrapper. The other six callers pass no realm and behave
as before.
Offsets.h gives the getter's real signature (RET 4) and what it stores.
API.md's GetPlayerInfoByGUID and UnitNameFromGUID entries describe the
realm and the four sources.
StopSpeakingText purges SAPI's queue, but the purge still queues
START/END events for the streams it cut off, and SAPI numbers streams
from 1 again afterwards. The next SpeakText then reused stream 1, so
the stale events were read as the new utterance's:
VOICE_CHAT_TTS_PLAYBACK_STARTED and _FINISHED fired for it before it
played, and its real end fired a FINISHED with utteranceID 0.
The purge is synchronous and has queued all of those events by the
time it returns, so StopAll now drains and discards them right after
it. That covers stop and speak in the same Lua call too, where the
stale START is still queued and a "require START first" check on the
END handler would not have been enough. An END for a stream we do not
track no longer fires FINISHED with utteranceID 0. Purged utterances
now signal nothing, which is retail's contract.
Verified with a standalone SAPI probe: speak/stop/speak, with and
without a message pump between the calls.
The engine's handler for the three mirror-timer SMSGs (0x005E7990) only
reads each packet and signals MIRROR_TIMER_START / _PAUSE / _STOP, so
GetMirrorTimerInfo and GetMirrorTimerProgress read a table of our own.
A MinHook on that handler fed it by reading the packet and putting the
cursor back. The table now reads START (0x1D9) and STOP (0x1DB) as a
Net::PacketDispatch subscriber, and the hook is gone.
CGPlayer_C::Release (0x005E9AA0) runs StopMirrorTimers (0x005E9B90) for
the active player: MIRROR_TIMER_STOP for all three types, with no
packet. The table never saw it, so a breath timer stayed after a logout
or a loading screen. Release then calls LeaveWorldUI (0x00490A80),
which fires PLAYER_LEAVING_WORLD through the no-arg dispatcher. An
Event::SignalHook subscriber clears the table on that event.
What the functions return:
- GetMirrorTimerInfo returns an empty slot as "UNKNOWN" with zeros, the
name helper 0x005E7AE0 gives for no type, instead of nothing. Code
that tests for "UNKNOWN" on PLAYER_ENTERING_WORLD called its setup
with nil before. paused is a number, as the event's %d is, and
spellID is a seventh value.
- A PAUSE packet no longer changes the table. Tortoise never sends one:
it resends START with the paused byte, which the table keeps.
- GetMirrorTimerProgress is value + scale * elapsed with no clamp. A
timer started paused holds its value. Names match through SStrCmpI,
and a name that is not a timer type returns nil.
- The time comes from Time::Clock. 0x0042B790 truncates the tick
itself and returns it in EAX, so the GetTickCount workaround for an
FPU return had no cause.
Offsets.h drops the CDataStore readers, the handler and the PAUSE
opcode, which nothing reads now, and its comment gives the verified
signatures and packet layout. Both functions get API descriptors under
the MirrorTimer system. API.md's section is rewritten to match.
pfDebug was a separate addon that profiled through ClassicAPI's own
APIs: GetAddOnMemoryUsage and GetAddOnCPUUsage, GetFrameCPUUsage,
GetFunctionCPUUsage, GetEventCPUUsage, and the intrinsic precall and
postcall script hooks. Its code now lives in ClassicAPI_DebugTools
under Profiler/, with its MIT notice (Copyright (c) 2018 Shagu). The
analyzer tabs (Addons, Frames, Events, Globals) and the widget are
pfDebug's, with the frame and template names renamed to
ClassicAPIProfiler*.
/profiler and /prof load DebugTools on demand through the same stub as
/dump, then toggle the analyzer. The subcommands widget, reset and
profile on|off are pfDebug's.
What changed in the move:
- The sampler starts only when the widget or the analyzer first opens,
so a load for /dump costs nothing. It first takes every counter as it
is, so the first CPU/s and KB/s cover one second, not the session.
- Whether profiling runs is probed, not read from the cvar: a function
is called once and GetFunctionCPUUsage must count that call. The
scriptProfile cvar can already hold the next session's value.
- A frame record starts at the frame's current CPU time and call count,
and opening the analyzer takes every frame and event counter again,
because the frame totals and the deep hooks keep counting while it is
closed. pfDebug started records at 0, so the first scan and each
reopen showed a frame's whole session as one second.
- The /fstack lines (owner, OnUpdate and OnEvent owner and CPU, all
scripts, deep allocations) are added at the end of
FrameStackTooltip_OnTooltipSetFrameStack, not by hooking
OnTooltipSetFrameStack.
- No pfUI skin and no SavedVariables. The plain backdrop is pfDebug's
own fallback. The widget no longer opens at login, because that would
load DebugTools at login.
README's Debug tools table gains /profiler and the new /fstack lines.
Each embedded file was its own gzipped RCDATA resource, 175 in all.
Every stream started with an empty deflate window, so no file could
match text it shares with its neighbours, and 97 of the files are under
4 KB, where that costs the most. Each resource also cost about 50 bytes
of resource directory and padding.
cmake/pack_files.cmake, which replaces gzip_file.cmake, now joins each
addon's files at build time into one gzip stream. It holds an index,
each file's size as a decimal line and then an empty line, followed by
the files' bytes in path order. `cmake -E cat` joins them byte for
byte, in batches of 100 so the Windows command-line limit cannot fail
the build. The index goes through file(CONFIGURE NEWLINE_STYLE UNIX)
because file(WRITE) writes \r\n on Windows. The resources are now three:
Bindings.xml as a pack of one, !!!ClassicAPI, and ClassicAPI_DebugTools.
The manifest entries become {path, resourceId, index}, and
Embed::Resource(id) becomes Embed::File(id, index). On first use it
inflates the whole pack with the engine's zlib, splits it into views,
and keeps it for the life of the DLL, as before. A pack whose sizes do
not cover its bytes exactly is rejected. The load-on-demand DebugTools
pack is still inflated only when it loads.
Embedded data 323,947 -> 272,825 bytes; .rsrc 334,336 -> 274,432;
DLL 1,632,768 -> 1,573,888 bytes.
ClassicAPI fires its own unit events (UNIT_AURA_DELTA, the remote
UNIT_SPELLCAST_*, the power, group-member, distance, incoming-resurrection
and targetable events) once per token through
Unit::Identity::TokensForGUID. That took the engine's tokens from its
reverse map FUN_UNIT_TOKENS_FROM_GUID (0x00515C50) and then added its own
short list: focus and nameplateN. The engine's unit events get their
ClassicAPI tokens from a second list in Unit::TokenEvents, which also has
markN, softenemy and softfriend. So a soft enemy got UNIT_HEALTH but never
UNIT_SPELLCAST_START.
That list is now the public Unit::TokenEvents::TokensOf, capped at the
caller's room and empty before the player object exists, as before.
TokensForGUID appends it to the engine's tokens, so both kinds of event
reach the same tokens, and a new token goes in one place. nameplateN now
comes before focus, the order TokensOf already used.
API.md's soft enemy and soft friend section now says that their tokens
fire unit events, as the focus, nameplateN and markN sections do.
44f9bcd added softenemy and softfriend to Unit::TokenEvents, but the
comments that list its tokens still named only focus, nameplateN and
markN. They now name all five. The call-site mismatch log no longer
lists them at all: it says ClassicAPI tokens get no engine unit events.
The token resolver's header in TokenExtensions.cpp had drifted too. It
said markN unit events go through TokenObserver (TokenEvents fires them
now), spoke of "both" families where there are six, and gave a
resolution order of focus then nameplate. The order in the hook is raw
GUID, focus, the soft targets, nameplateN, markN. UnitCreatureID's
comment now points at that header instead of keeping its own list.
UnitTokenFromGUID's comment called the soft targets' place in retail's
order unverified. Retail's list puts them last, as the code does, and
has no markN, so the comment now says markN is never returned.
Unit::TokenEvents already redirects the 38 broadcast and 4 combat
feedback call sites so a unit holding focus / nameplateN / markN gets
every engine unit event under that token. softenemy and softfriend join
that token list, read through SoftUnit::Current (the last pick, no scan)
because TokensOf runs on every unit event.
The registration bit (UNIT_SCRIPT_REG_TOKENS) is what makes the engine
watch a unit, so SoftUnit::Refresh re-runs FUN_UNIT_SCRIPT_RECOMPUTE
through TokenEvents::Refresh for the old and new guid before the
PLAYER_SOFT_*_CHANGED event fires. The frame tick now picks every frame
rather than only while that event has a listener: a UNIT_HEALTH listener
never registers for it, and the pick is cached per scene drain anyway.
Retail shows a soft unit's overhead name the way it shows the target's:
a soft enemy past nameplate range keeps its name, whatever the UnitName
cvars say.
1.12 decides an overhead name in CGUnit_C::ShouldShowName (0x6070A0),
which its only caller, the name draw PLAYERNAMEDESC::UpdatePlate
(0x6C6EE2), asks every frame. In order: no name when CanSelect (vtable
+0x58) refuses the unit, or when it has a nameplate (+0xE60) or a chat
bubble (+0xE64); the active player by UnitNameOwn; the target always;
then the UnitName mask. A hook gives a soft unit the target's branch:
the first three tests, then 1. The player is never a soft unit, so the
own-unit test does not apply. In nameplate range the plate shows and
the name does not, as for the target.
The name draw runs inside the scene (the model draw callback 0x6C7780),
so the hook reads the soft GUIDs cached on the UI frame tick, as the
selection circle does, and never picks there. Nothing invalidates: the
verdict is asked fresh each draw.
Addons can now choose the countdown text and its color for each range of
time left. Cooldown:SetCountdownFormatter(formatter) and
GetCountdownFormatter() take a NumericRuleFormatter from
C_StringUtil.CreateNumericRuleFormatter(). Its breakpoints each give a
threshold, an optional step, rounding (Enum.NumericRuleFormatRounding),
min and max, a format string, and optional div/mod/step components, one
for each format argument. Color codes in the format string pass through.
The formatter is a full Lua userdata, the first in the DLL. Its block
holds a pointer to a reference-counted native object. Every Lua object
and every frame that uses it hold one reference, so the GC finalizer
(__gc) and the frame's deleting destructor can run in any order.
lua_newuserdata (0x6F4560, __fastcall, block at Udata + 0x10, read from
the disassembly) is new in Offsets.h. lua_touserdata reuses
FUN_FRAMESCRIPT_GET_OBJECT, which is that function. One metatable per
Lua state lives in the registry. Its __metatable is false, and the
identity check compares a value's metatable with it. 1.12 has no
newproxy, so the only finalizer an allocation can run is ours. Thus no
addon code can change a formatter while it formats.
The text goes through 1.12's own str_format (0x7FD3D0). Its closure is
made once per state and kept in the registry, because FormatNumber runs
from addon timers and lua_pushcclosure allocates on each push. The
rounding is x - fmod(x, step), plus a step away from zero when the
rounding needs it. Only that arithmetic matches retail to the last bit:
Up of 0.7 by 0.1 gives 0.7000000000000001 and of 0.6 gives 0.6, but
ceil(x / step) * step gives 0.6000000000000001.
The cooldown shares the formatter and gives it the unrounded seconds
left. The formatter replaces the built-in text and both thresholds, and
every gate stays. The cached countdown text is now a heap std::string,
because a formatter's text has no length limit. The frame frees it, and
its reference, in DeletingDestructor.
A probe addon recorded 229 results in retail 12.1.5. The same probe on
1.18.1 matched 197 of them. The other results come from 1.12's own
str_format (%e exponent digits, %q, %d past the int range, its error
wording), from field storage on the object (not ported), and from
addresses and times.
The global wipe is ours only until an addon declares its own: whoever
writes _G.wipe last wins, with no error. RegisterGlobalFunction mirrors
every global it binds into _G.ClassicAPI at registration, before FrameXML
and every addon load, so ClassicAPI.wipe is always our table.wipe C
function.
The nine embedded files that call the bare global now take
`local wipe = ClassicAPI.wipe;` and list it as their difference from
retail: ScrollBoxListView, ScrollUtil, Menu, CallbackRegistry, MixinUtil,
SecureTypes and the three DebugTools table inspector files. Files that
read table.wipe, as their retail sources do, are unchanged. The global
stays for third-party code.
On a stock 1.12.1 client, ScrollBoxListView, ScrollUtil, Menu and the
DebugTools table inspector failed with "attempt to call global `wipe'":
those ports call bare wipe(), and only Turtle's client defines that
global. Stock 1.12.1 has only the table.wipe that ClassicAPI registers.
3.3.5 makes the alias in FrameScript's compat preamble, next to tinsert
and tremove (wipe = tab.wipe). 1.12's preamble is older than table.wipe,
so Wipe.cpp now registers the same C function as the global wipe as well
as table.wipe, with a LuaGlobals descriptor.
CallbackRegistry, MixinUtil and SecureTypes lose their "1.12 has no
global wipe" notes and their table.wipe locals, and now match retail.
UnitFacing(unit) returns the unit's facing in radians (0 = north,
counter-clockwise, 0..2pi), or nothing when the token has no unit.
The facing comes from the object's GetFacing virtual, vtable slot 6.
The unit and player vtables (0x80C4F8 / 0x80AF78) both hold
CGUnit_C::GetFacing (0x5F1F30) there, read from the binary: it loads the
mover at +0x118, pushes its facing +0x1C and returns
CMovement::TransportFacingToWorld (0x7C4AE0), which adds the transport's
facing and wraps once into [0, 2pi]. Unit::Position::Facing wraps the
call next to the shared position read.
GetPlayerFacing moves to the same read. It used to load the float at
+0x9C4 (the mover's +0x1C) directly, which is the facing relative to the
transport, so on a boat or zeppelin it returned the wrong angle. The
OFF_UNIT_FACING offset goes with it.
The bag sort compared item class before the equip slot rank. Shields,
held-in-off-hand items and relics are armor class (4), so they left the
weapon group and sorted first in the armor block, before head pieces.
For gear, the slot rank (Item m_inventoryType through kSlotOrder) now
comes first and item class is the next tiebreak. Those items now sort
with the weapons, where the slot order puts them. Non-gear items sort
the same as before.
A weapon equipped in combat resets that hand's swing timer on the
server, with no packet for it. PLAYER_SWING used to catch this by
reading the main-hand, off-hand and ranged GUIDs from the player's
inventory manager (player+0x1D38) on every WorldTick and comparing
them with the previous frame.
The engine already reports these changes. CGPlayer_C::AddActiveWatchers
(0x005DD8A0) registers OnInventorySlotChanged (0x005DDCF0) on every
equipment slot, and the descriptor dispatcher calls it only when a
slot's GUID really changes. Player::Equipment already hooks that
handler for PLAYER_EQUIPMENT_CHANGED. It now also calls
Combat::Swing::OnWeaponSlotChanged, which resets the hand for slots
15/16/17 when the player is in combat.
The call runs inside SMSG_UPDATE_OBJECT, after the values block is
written, so the attack-time descriptor field already holds the new
weapon's speed. The lookups it makes (player by GUID, descriptor
reads) do not throw.
The per-frame poll and its snapshot state are removed. The WorldTick
subscriber stays: it still merges several resets in one frame into
one PLAYER_SWING per swing type.
The AddOn Options panel now has a control for each of the 38 cvars that
ClassicAPI registers, plus the player cache, on pages grouped by
feature: Interact Key, Action Targeting, Combat, Bags and Items,
Interface, Text To Speech and Advanced.
Each control reads and writes exactly one cvar, and writes it only when
the player uses that control. The "Interact Key Icons" preset dropdown
is gone: it wrote four icon cvars at once, and Cancel restored it from
a snapshot that read any mixed state as "NPCs Only", which turned
SoftTargetIconInteract back on. Okay, Cancel and Defaults no longer
write anything on these pages.
- On/off cvars are checkboxes. The soft-target enable cvars read as on
for 2 or 3 and write 3 or 0; 1 is gamepad, which does nothing here.
- Fixed choices (the three arc cvars, SoftTargetForce) are dropdowns. A
value outside the choices shows as its number.
- Open-ended numbers (ranges, icon size, shake strength, combat log
retention) are number boxes, so the panel sets no maximum. Sliders
are kept for documented ranges only.
- Each page's controls sit in a WowScrollBox with a MinimalScrollBar.
The box clips its children, and the clip also keeps the mouse off
controls that are scrolled out of view.
The panel's strings are globals in locales\enUS.lua, which every client
loads: CLASSICAPI_* for ClassicAPI's own, and retail's GlobalStrings
keys where retail has the string (COUNTDOWN_FOR_COOLDOWNS_TEXT and its
tooltip, with retail's translations in the other locale files).
The README cvar table gains the five cvars it was missing.
CWorld::BeginFrame (0x0066FD50), the world tick, runs inside the UI
strata walk. Its only caller is CGWorldFrame::OnRender (0x00482EA0),
which WorldFrame's layer-0 draw callback (0x00482D70) runs. By then
0x007657D0 has already rebuilt the WORLD stratum's level batches. The
levels above 0 are not drawn yet. Nameplates sit at level 1, with
their name and level text on OVERLAY.
A batch's text run keeps a raw pointer to its font. The run's draw
(0x005C8FE0) uploads all eight of that font's atlas pages, even when
no strings are left in the run. Every subscriber ran at the hook, and
several of them run Lua (NAME_PLATE_CREATED, the C_Timer callbacks).
An addon that restyled a plate there made the plate leave level 1 and
gave its font strings a new font. The old font was destroyed while
the built batch still pointed at it. The upload then read a freed
texture's format and faulted at 0x005A09B8.
The crash dump shows this state:
- Level 1 has no frames.
- Its dirty mask is 0xFFFFFFFF, and the stratum's flags are set again.
Both were written after the rebuild.
- Its one OVERLAY run is empty, and its font's memory holds Lua table
nodes.
The hook now only marks that the world ran. The subscribers run from
the UI render root's tail (Tick::FrameTick), after the strata walk,
so the engine rebuilds anything they change before it is drawn.
OnUpdate and packet events still run in the same order relative to
them. GetTickTime() also reads the same pass delta as before.
Fixes#116
The intro and the Lua-calls summary still said 550+ functions across ~60
namespaces and 50+ events, the counts from 54516ad. Counted the same way
(backticked calls in the Lua-calls table, rows in the Events table), the
README now lists 980 calls under 75 namespaces and 86 events, so the
rounded-down figures become 950+, ~75 and 80+.
Port of retail's Blizzard_SharedXML/SharedColorConstants.lua, in
Blizzard's own text. It loads after ColorUtil.lua, when Color.lua has
already made the GlobalColor globals it reads, and adds
PLAYER_FACTION_COLORS_HEX, PLAYER_FACTION_BRIGHT_COLORS (the PvP
scoreboard colors) and COVENANT_COLORS.
FACTION_BAR_COLORS now holds retail's color objects in place of 1.12's
plain {r, g, b} tables. The stock code that reads it (the unit tooltip
and the reputation bars) reads only .r, .g and .b, which the objects
have; the values differ by less than 1/255.
PLAYER_FACTION_COLORS moves out of Constants.lua, because retail
defines it only here, and GetFactionColor goes back to retail's
one-line body without our nil guard.
Verified in game: FACTION_BAR_COLORS[1] is ffcc4d38 and [5] is
FACTION_GREEN_COLOR, PLAYER_FACTION_COLORS_HEX[0] is ffff2934,
PLAYER_FACTION_BRIGHT_COLORS[1] is ff00adf0, GetFactionColor("Alliance")
is ff00adf0, and COVENANT_COLORS.Kyrian is ff2aa2ff.
C_UIColor.GetColors now returns the GlobalColor.dbc rows of build
1.60.1.70707 instead of the BC Classic 2.5.5 snapshot: 331 rows where
there were 187, in the table's own row order.
- 148 new colors, among them PVP_SCOREBOARD_*_CELL_COLOR, the
EXPANSION_COLOR_* set, and the profession, threat and power-prediction
colors.
- 10 changed values, as the newer client has them: NORMAL_FONT_COLOR
ffd200, RED_FONT_COLOR ff2020, PLAYER_FACTION_COLOR_HORDE ff2934,
PLAYER_FACTION_COLOR_ALLIANCE 00adf0, TALENT_LINK_COLOR 71d5ff, and
more. The C++ tooltips that read the table (item comparison,
equipment sets, links) take the new values. Lua globals that 1.12
FrameXML already defines keep their own values, because Color.lua
only creates the globals that do not exist.
- The four HEALTHBAR_*_HEAL_PREDICTION_GRADIENT_COLOR* rows are gone;
the newer table does not have them and nothing read them.
- A name that the DBC lists twice keeps only its last row, which is
the value the client's own Color.lua loop ends on.
COMPACT_UNIT_FRAME_FRIENDLY_HEALTH_COLOR and
CHARACTER_FRAME_SIDE_PANEL_SKILL_COLOR join the earlier duplicates.
- DEBUFF_TYPE_ENRAGE_COLOR stays as our own row, for
C_UnitAuras.GetAuraDispelTypeColor("Enrage").
Verified in game: GetColors returns 331 rows,
PVP_SCOREBOARD_HORDE_CELL_COLOR is ffff2934 and the alliance one
ff00adf0, GetAuraDispelTypeColor("Enrage") is ffff8c00, and
HEALTHBAR_MY_HEAL_PREDICTION_GRADIENT_COLOR1 is nil.
Ports from retail's Blizzard_ObjectAPI, SharedXML, SharedXMLBase and
FrameXMLUtil, in Blizzard's own text, from the _forever_ build:
- ObjectCache.lua and SpellBookItemLocation.lua (ObjectAPI).
- TypeUtil.lua: ValueToBoolean and StringToBoolean.
- SortUtil.lua: SortUtil.CreateSortManager and the comparators.
- Sequencer.lua, Spline.lua (Catmull-Rom splines), TaggableObject.lua,
ObjectUpdater.lua and ExportUtil.lua (base64 export/import streams).
- AnimationSystem.lua: SetUpAnimation and CancelAnimations.
- SmoothStatusBar.lua: SmoothStatusBarMixin.
- MixinUtil.lua: DrawLine, LineMixin, SparseGridMixin,
DoublyLinkedListMixin, DirtiableMixin, DirtyPhaseMixin and more. 1.12
has no global wipe, so the file reads table.wipe, as the other ports do.
FrameDeltaLerp now takes retail's three arguments and reads the frame
time from GetTickTime(). The old form needed a fourth elapsed argument,
so SmoothStatusBar's per-frame ticker would have errored. Nothing else
called it.
DebugTools drops its private StringToBoolean copy and calls the global
one from TypeUtil for the /framestack arguments.
FadingFrame.lua is not ported: 1.12's own FrameXML defines the same
FadingFrame_* names with no-argument `this` signatures, and ZoneText
calls FadingFrame_OnUpdate() every frame.
Verified in game: StringToBoolean, ValueToBoolean and
SpellBookItemLocation return the expected values, a 2D spline's midpoint
is (5, 10), an export stream round-trips 200 and 9, the sort manager
orders {3,1,2}, the linked list enumerates 0 1 2, ObjectUpdater,
Sequencer and SetUpAnimation finish, a smoothed status bar reaches 100,
and /framestack still opens.
UNIT_IN_RANGE_UPDATE (unitTarget, isInRange). Nothing in the client
reacts to a distance: the player moves every frame while it moves, and
other units in view are moved a little each frame between their movement
packets. So a world-tick pass checks the units, only while a frame is
registered for the event. The pass walks the event's subscriber chain
(Event::Custom::ForEachListener, which FireValues now uses too): a frame
registered with RegisterUnitEvent adds its units
(Frame::UnitEvent::Units), and a plain registration adds pet and each
party and raid member and their pets. A token fires when
Unit::Range::InRange changes for it. UnitInRange now calls the same
function. A filter unit that is not a unit token is dropped after one
protected IsUnitToken check, since the engine's resolver raises a Lua
error for it.
UNIT_DISTANCE_CHECK_UPDATE (unitTarget, isInDistance) is true while the
client holds a group member's object. UpdateRaidMemberRecord (0x004BADC0)
has four E8 callers, which are exactly a player object entering the
object table (CGPlayer_C::PostInit 0x005DEC43, PostUpdate on reactivation
0x005DECAF) and leaving it (the release slot 0x005E9ACF, ~CGPlayer_C
0x005DD6AB for an object never released). The calls point at a site that
notes a party or raid member's GUID (IsRaidMemberOrPet, not the active
player), and the next world tick fires for each of its tokens with
whether the object table holds it then. The release slot runs before the
manager moves the object to the released table, so a fire in place would
still show the member to UnitIsVisible. No loaded DLL references the
function or the sites.
DiffPartyRecords (0x005E5510) already sets bit 0x80 when the zone in a
party record (+0x14) differs, but SignalPartyRecordChanges (0x005E5720)
raises nothing for it. The existing SignalSite redirects (the calls in
ReadPartyMemberStats and ComparePartyRecord, and the AddPartyMember tail)
now fire UNIT_AREA_CHANGED (unitTarget) on that bit, after the engine's own
events, once per token of the member.
The server sends the zone only to members that cannot see the player.
A member in view is built with the player's own zone (BuildPartyRecord
stores s_zoneId), the same zone GetRaidRosterInfo gives for a held object,
so ComparePartyRecord sets the bit when a member comes into view from
another zone. CGPlayer_C::PostInit skips ComparePartyRecord for the active
player, so "player" gets no event.
1.12.1 reacts to a unit's new UNIT_FIELD_MOUNTDISPLAYID in
CGUnit_C::OnMountDisplayChanged (0x005FFA50): dismount from the old
display, mount the new one with the mount-up effect, refresh the loop
sound, quest marker and name. The field's type watcher
OnMountDisplayFieldChanged (0x00604570) resolves the unit and calls it
with the old value from one E8 call (0x0060459B), only on a real change.
That call now reaches a function that runs the handler, then fires
PLAYER_MOUNT_DISPLAY_CHANGED (no payload) when the unit is the player.
VanillaHelpers calls the handler directly after a local mount morph and
patches neither address, so a cosmetic morph fires nothing.
1.12.1 reacts to a changed UNIT_FIELD_FLAGS in
CGUnit_C::OnUnitFlagsChanged (0x005FF580), which the flags field's type
watcher OnFlagsFieldChanged (0x006044B0) calls with the old flags from
one E8 call (0x006044DB). It handles looting, disarm, reaction, PvP and
the aura bit, but nothing reads UNIT_FLAG_NOT_SELECTABLE (0x02000000).
Unit::FlagsChanged now owns that call: it runs the handler, then each
subscriber with the unit and the flags before and after, since a call
site can be redirected only once. Unit::Targetable subscribes and fires
UNIT_TARGETABLE_CHANGED (unitTarget) once per token of the unit when the
not-selectable bit flips.
A party record's status byte (+0x08) carries the online bit
UnitIsConnected reads. 1.12.1 changes it in three places, and none
signals the flip:
- The party member stats packet: ReadPartyMemberStats (0x005E5110) ends
in SignalPartyRecordChanges (0x005E5720) with the status change bit.
The redirected call that already adds the generic power events now
also fires UNIT_CONNECTION (unitTarget, isConnected) when the old and
new records differ in the online bit.
- The group list (0x7D): the server reports a logoff only there.
AddPartyMember (0x004E82D0) copies a kept member's previous record and
sets the online bit, then stops. Its call now diffs the previous record
against the stored one (DiffPartyRecords, 0x005E5510) and runs the same
SignalPartyRecordChanges path, so the engine's status events and
UNIT_CONNECTION follow.
- A raid member outside the player's party has only a raid slot, whose
status byte RebuildRaidRoster (0x004BA5F0) sets from the same list. Its
call now compares each returning member's online bit before and after
and fires UNIT_CONNECTION on a flip; party members are skipped, since
AddPartyMember ran first.
isConnected is a real boolean, pushed through FireValues.
Every unit-field watcher keeps a mirror of its bytes in the object's
watch copy, at the slot UnitWatchedIndex (0x0047DB20) finds for the field
in the table at 0x00839E48. A field not in the table gets 0xB6, past the
unit's 170-slot copy. UNIT_MOD_CAST_SPEED (139), named for
UNIT_SPELL_HASTE, is such a field, so every watcher on it wrote the
field over memory past the copy: a pet's cast-speed update on its
owner's logoff put a 1.0f over a list link, and ClntObjMgrRelease
crashed on the next SMSG_DESTROY_OBJECT (ERROR #132 at 0x00464A02).
The table holds 166 fields and one spare entry (0xB6, the copy's last
slot, which no field asks for); UnitWatchedIndex is its only reader and
nothing writes it. EngineName now writes a field without a slot into
that spare before naming its slot, and refuses the name once the spare
is taken. Field 139 takes it, so UNIT_SPELL_HASTE keeps the engine's
watcher for every unit.
1.12.1 calls type-wide field observers for every unit whose watched
bytes change: ClntObjMgrSetTypeMirrorHandler (0x00468070) puts a record
on the global list of a (bank, field), and CGUnit_C::RegisterFieldWatchers
(0x006041F0) uses it for the engine's own unit handlers, among them
OnPowerFieldChanged on the power block, which only refreshes usability.
Two handlers join those lists, one record per POWER1..5 and MAXPOWER1..5
slot, so the callback's field offset is the power type. They fire
UNIT_POWER_UPDATE and UNIT_POWER_FREQUENT, or UNIT_MAXPOWER, with
(unitTarget, powerType) once per token of the unit. Every client power
change is a server update, so FREQUENT fires with UPDATE.
Each in-world registration pass removes and re-adds the records through
0x00468240: the first pass of a session runs in CGGameUI::InitializeGame,
after MirrorInitialize (0x0047F840) has rebuilt the tables a record's
copy offset comes from, and the removal keeps /reload from stacking a
second record. The list array has no other writer, so nothing frees a
record behind us.
A group member the client cannot see has no unit to watch; its power
comes in the party member stats packet. ReadPartyMemberStats (0x005E5110)
and ComparePartyRecord (0x005F0B80) end in SignalPartyRecordChanges
(0x005E5720), which fires the per-type power events for the changed
record bits. Both E8 calls now reach a function that calls it and then
fires the generic events for the same bits, the member's and its pet's.
1.12.1 turns unit-field changes into events by index: FUN_0051bbb0
watches unit field i when slot i of the static event-name array at
0x00BE1198 is named, and FUN_0051bd50 signals event i once per token of
the unit. UNIT_MOD_CAST_SPEED, the field UnitSpellHaste reads, is index
139 (OFF_UNIT_MOD_CAST_SPEED / 4), and slot 139 has no name, so the
engine never watched it.
Event::Custom::EngineName names slot 139, and the engine's own watchers
fire the event for every token. Nothing else signals 139 by number: it
is above the glue band and not in the chat-type event table.
1.12.1 already turns unit-field changes into events. FUN_0051bbb0
registers a watcher on unit field i for each named slot i of the static
event-name array at 0x00BE1198, and the watcher (FUN_0051bd50) signals
event i once per token of the unit through the broadcast FUN_00515e50.
The field index is the event id. UNIT_FIELD_TARGET is index 10, and the
watcher's size selector still gives it the 8 bytes of a GUID, but slot
10 has no name, so the engine never watches the field.
Event::Custom::EngineName names such a slot. It writes the name into the
static array at load, before any world init or unit watch. World init
copies the array into the live event table (0x0048FEA1), and the
engine's own watchers then fire the event for every token, with focus,
nameplateN, markN and focustarget included. The entry joins the
reservation list with a fixed slot, so it is documented, kept across
/reload, and not counted by Grow.
Slot 10 is in the glue band. Its one by-number signal is the glue
realm-list rebuild (0x0046E73D), which only CGlueMgr::Idle reaches.
When an alpha group starts on a frame, every region below it stores its
vertex alpha, and every update writes that alpha back. The colour getter
(0x77F8C0) reads a gradient back as white, and the setter (0x77F750)
shrinks a gradient's four entries to that one white entry. So a gradient
under a fading frame went flat at the first update and stayed flat after
the group ended. pfUI's easteregg night lost its fade to the bottom.
SetVertexAlpha now writes nothing when the alpha is unchanged. For one
colour entry the setter already does nothing then, so only the gradient
case changes. The frame's fade still reaches the gradient: a change of
the frame's alpha refolds each region's entries (0x77FAC0).
3.3.5's and 4.3.4's PreOnAnimUpdate drop the gradient the same way. A
texture that an alpha animation itself fades still loses its gradient.
Verified in game: a black gradient on a frame fading by -0.5 over 3 s
keeps its gradient during and after the fade.
Ports from retail's Blizzard_ObjectAPI and SharedXML, in Blizzard's own
text, from the _forever_ build (the newest interface code on disk):
- Util/Spell.lua: Spell:CreateFromSpellID and SpellMixin.
- Util/ContinuableContainer.lua: one callback for a group of item and
spell objects.
- Util/IndexRangeDataProvider.lua: CreateIndexRangeDataProvider, which
ScrollBoxListView already expected.
- Util/TableBuilder.lua: CreateTableBuilder, for the existing
ScrollUtil.RegisterTableBuilder.
- FrameXML/CallbackRegistrant: CallbackRegistrantMixin and
CallbackRegistrantTemplate.
AsyncCallbackSystem.lua gets its ASYNC_SPELL type and SpellEventListener
back, so it is the _forever_ text again.
New in the DLL for SpellMixin:
- C_Spell.IsSpellDataCached, C_Spell.RequestLoadSpellData and
SPELL_DATA_LOAD_RESULT. Every spell is client data, so a spell that
exists is cached, and a request fires the event before it returns:
(spellID, 1), or (spellID, nil) for an ID with no spell. Retail marks
the event synchronous, and AsyncCallbackSystem relies on that.
- C_Spell.GetSpellDescriptionForItemLocation. The item tooltip expands a
spell's text with the same arguments GetSpellDescription passes, so it
returns that text. The item location is still required.
Verified in game: IsSpellDataCached(133) and (999999) are true and false,
Spell:CreateFromSpellID(133) calls back with (133, 1), a container with
item 19019 and spell 133 calls back, CreateIndexRangeDataProvider(5)
has size 5, and GetSpellDescriptionForItemLocation(133, slot 1) equals
GetSpellDescription(133).
FireValues walks the subscriber chain itself and runs each OnEvent
through RunSlotWithValues, so it never reached the runner where
Frame::UnitEvent's gate sits. RegisterUnitEvent("UNIT_AURA_DELTA", unit)
fired for every unit's deltas.
Frame::UnitEvent::Accepts shares the gate's match. FireValues asks it
for each frame when the first value is a string, the same rule the
engine path uses for a %s arg1.
2026-10-31 00:21:18 -05:00
507 changed files with 56405 additions and 7790 deletions
ClassicAPI is a DLL for World of Warcraft 1.12.1 (Vanilla / Turtle WoW). It
backports a large part of the modern WoW API — 550+ functions and 50+ events,
backports a large part of the modern WoW API — 950+ functions and 80+ events,
plus much of Lua 5.1 — into the 1.12 client, so addons written for later
versions (3.3.5+ or Classic Era) run with little or no change.
@@ -22,8 +22,9 @@ reference is in **[docs/API.md](docs/API.md)**.
| Inline textures | Draws inline texture markup (`\|T…\|t`) and atlas markup (`\|A…\|a`) as icons in FontStrings, chat, and tooltips. This covers item and spell icons, raid-target markers, and the coin icons in money strings. `GetStringWidth` and `GetStringHeight` count the icons, so measured width and text wrapping stay correct. Done in pure C++ by hooking the engine's text pipeline — no addon. |
| [Soft targeting](docs/API.md#soft-interact-softinteract--anyinteract) | The Interact Key and soft targets. Bind **Interact With Target** to a key to interact with the nearest NPC, corpse, mailbox, chest or gathering node in front of you. The [`softenemy` and `softfriend`](docs/API.md#soft-enemy-and-soft-friend-softenemy--softfriend--anyenemy--anyfriend) tokens point at the nearest enemy and friendly unit without a change of target. With no target, harmful spells go to `softenemy` and helpful spells go to `softfriend`. `PLAYER_SOFT_*_CHANGED` events fire when the units change. |
| [Animations](docs/API.md#animation) | Animation groups on frames, textures and font strings, made in Lua or XML: `CreateAnimationGroup`, looping, smoothing, scripts and templates, with `Alpha`, `Translation`, `Scale`, `Rotation` and `Path` applied. |
| [Model scenes](docs/API.md#modelscene) | The `ModelScene` frame type shows many models in one 3D scene, with its own camera, light and fog. Each model is an actor that you place, turn, scale and animate. An actor shows a creature display, a model file or a copy of a unit. It can also seat a rider, show spell visual kits and pause on one frame. A scene can show a WMO, for example a dungeon, around the actors, with its props and their sounds. An actor can move on the WMO as a character moves in the world: it runs, jumps, falls, swims and walks to a point. You hear the sounds of a scene from its camera, or from an actor. A follow camera follows an actor as the camera of the world follows your character, and stops in front of walls. An actor can glow, show a selection circle and show a name over its head, and a scene can show the click-to-move marker. |
| Tooltip line cap | Removes `GameTooltip`'s 30-line limit for every `GameTooltipTemplate` frame (`GameTooltip`, `ShoppingTooltip1/2`, `ItemRefTooltip`, AtlasLoot, …). A tooltip adds a new line pair when it needs one, so long tooltips and comparison blocks (for example, pfUI's eqcompare) keep all their lines. |
| [XML attributes](docs/API.md#parentkey-in-xml) | More XML attributes work: `parentKey="Name"` makes `parent.Name` point to a frame, texture or font string, `<OnLoad function="Name"/>` uses a global function as a script handler, `<OnLoad method="Name"/>` uses the frame's own function, `mixin="A, B"` copies mixins onto the object, `<KeyValues>` sets fields on the object, a button's `<NormalFont style="..."/>` sets its font, and `inherits="A, B"` applies more than one template. `parentArray="Name"` adds the object to a list on its parent. An `<Anchor>` takes `x` and `y` offsets and `relativeKey="$parent.Key"`. `<OnEnter inherit="prepend">` runs the template's handler and then its own, and `inherit="append"` runs them in the other order. |
| [XML attributes](docs/API.md#parentkey-in-xml) | More XML attributes work: `parentKey="Name"` makes `parent.Name` point to a frame, texture or font string, `<OnLoad function="Name"/>` uses a global function as a script handler, `<OnLoad method="Name"/>` uses the frame's own function, `mixin="A, B"` copies mixins onto the object, `<KeyValues>` sets fields on the object, a button's `<NormalFont style="..."/>` sets its font, and `inherits="A, B"` applies more than one template. `parentArray="Name"` adds the object to a list on its parent. An `<Anchor>` takes `x` and `y` offsets and `relativeKey="$parent.Key"`. `<OnEnter inherit="prepend">` runs the template's handler and then its own, and `inherit="append"` runs them in the other order. A frame with `intrinsic="true"` makes a new frame type. Frames take `scale`, `registerForDrag`, `clipChildren`, `useParentLevel`, `dontSavePosition`, `propagateKeyboardInput`, `propagateMouseInput`, `enableMouseClicks`, `enableMouseMotion` and `motionScriptsWhileDisabled`, and buttons take `registerForClicks`. Textures take `alpha`, `atlas`, `useAtlasSize`, `mask`, `desaturated`, `rotation`, `horizTile`, `vertTile`, `hWrapMode` and `vWrapMode`. Font strings take `alpha`, `wordwrap`, `indented`, `degrees` and `radians`. Status bars take `reverseFill`, `rotatesTexture` and `fillStyle`, and edit boxes take `countInvisibleLetters`. |
| [Macro conditions](docs/API.md#more-commands-with-conditions) | `[conditions]` and `@unit` work on 38 slash commands, from `/cast` and `/use` to `/target`, `/follow`, `/cancelaura` and the `/pet` family. With `/cast [@mouseover,harm][] Fireball`, the spell goes to the mouseover unit. With no mouseover unit, it goes to your target. `@cursor` places a ground-target spell or item under the mouse and `@player` places it at your feet. A character name works where a unit token does (`[target=Feral]`). Addons read the same rules through `SecureCmdOptionParse`. |
| [`#showtooltip`](docs/API.md#showtooltip-and-show) | A macro button shows the spell or item that its directive resolves to, conditions included: icon, tooltip, cooldown, range, usable state and auto-repeat glow. Action-bar addons get this with no code of their own. Addons with their own macro parser can publish through `C_Macro.SetMacroDisplay`. |
| [Event-driven nameplates](docs/API.md#nameplate) | The modern `C_NamePlate` API, driven by real events. `NAME_PLATE_UNIT_ADDED` / `NAME_PLATE_UNIT_REMOVED` fire as plates appear and vanish, `nameplate1`..`nameplateN` tokens resolve with every `UnitX` function (and fire `UNIT_HEALTH`, `UNIT_AURA`, … as `arg1 == "nameplateN"`), and `C_NamePlate.GetNamePlateForUnit` / `GetNamePlates` hand back the live frames. |
@@ -45,17 +46,18 @@ heading to expand it. For signatures and return values, see the per-function
reference in **[docs/API.md](docs/API.md)**.
<details>
<summary><b>In-game Lua calls</b> — 550+ functions across ~60 namespaces</summary>
<summary><b>In-game Lua calls</b> — 950+ functions across ~75 namespaces</summary>
In the Frame rows, a name that starts with `:` is a method of the widget that the row names, for example `:SetShown` is `frame:SetShown`.
| Script | `RunScript` (compile and run a Lua chunk in the glue state's globals — useful for slash-command-style helpers in GlueXML) |
| State | `IsLoggedIn` |
@@ -208,16 +217,25 @@ for what each command does, and
Each setting is saved in `WTF\Config.wtf`. Read and write them with `GetCVar`
/ `SetCVar` or `/console`. Click a group name for the full rules. To change
the most common settings and the player cache in the game, open the game
menu and click AddOn Options, then ClassicAPI.
these settings, the player cache and the ClassicAPI key bindings in the game,
open the game menu and click AddOn Options, then ClassicAPI.
| Group | CVar | Default | What it does |
|-------|------|---------|--------------|
| [Bindings](docs/API.md#actionbuttonusekeydown) | `ActionButtonUseKeyDown` | `0` | `1` uses an action-bar key binding when you press the key. `0` uses it when you release the key. |
| [Combat](docs/API.md#stopautoattackontargetchange) | `stopAutoAttackOnTargetChange` | `0` | `1` stops melee auto-attack, Auto Shot and wand shots when you change target. |
| [Cast settings](docs/API.md#cast-settings-autostand-autodismount-autounshift) | `autoStand` | `0` | `1` makes you stand up when you cast while you sit. |
| | `autoDismount` | `0` | `1` makes you dismount when you cast while you are mounted. |
| | `autoUnshift` | `0` | `1` makes you leave your form when a spell cannot be cast in it. |
| [Combat log](docs/API.md#kept-entries) | `combatLogRetentionTime` | `300` | The number of seconds that the combat log keeps an entry. |
| [Stand, dismount and form](docs/API.md#stand-dismount-and-form-settings-autostand-autodismount-autounshift) | `autoStand` | `0` | `1` makes you stand up when you cast, loot or open the flight map while you sit. |
| | `autoDismount` | `0` | `1` makes you dismount when you cast, use an object, loot, attack or open the flight map while you are mounted. |
| | `autoUnshift` | `0` | `1` makes you leave your form when you cast a spell that cannot be cast in it, use an item, or open the flight map. It also lets you talk to NPCs and use objects in druid forms and Ghost Wolf. |
| [Bag sorting](docs/API.md#c_containergetsortbagsrighttoleft--c_containersetsortbagsrighttoleftenable) | `sortBagsRightToLeft` | `0` | `1` makes a sort fill your bags from the last slot of the last bag. |
| | `backpackAutosortDisabled` | `0` | `1` keeps the items in your backpack in place when you sort your bags. |
| | `bankAutosortDisabled` | `0` | `1` keeps the items in the main bank slots in place when you sort your bank. |
| [Expanded cursors](docs/API.md#expanded-cursors-expandedcursors) | `expandedCursors` | `0` | `1` makes the cursor show what you can do with an NPC or an object: an anvil for repairs, a hearthstone for an inn, a horseshoe for a stable, `!` or `?` for quests, and a fish hook for your fishing bobber. |
| [Equipment sets](docs/API.md#equipment-sets-on-item-tooltips) | `dontShowEquipmentSetsOnItems` | `0` | `1` removes the Equipment Sets line from item tooltips. |
| [Name completion](docs/API.md#name-completion-settings) | `autoCompleteResortNamesOnRecency` | `1` | `1` puts the players that you whispered first in `C_AutoComplete` results, the most recent first. `0` uses alphabetical order. |
| | `autoCompleteWhenEditingFromCenter` | `1` | `1` also matches the text after the cursor when you type inside a name. |
| | `autoCompleteUseContext` | `1` | `0` makes `C_AutoComplete` ignore `includeFlags` and `excludeFlags`. |
| [Profiling](docs/API.md#scriptprofile) | `scriptProfile` | `0` | `1` turns on CPU profiling for the `*CPUUsage` functions. The change starts after `/reload`. |
| `ACTION_USABLE_CHANGED` | `changes` (a `{ slot, usable, noMana }` table for each slot that changed) |
| `BAG_NEW_ITEMS_UPDATED` | *(none)* |
| `BAG_UPDATE_DELAYED` | *(none)* |
| `CHAT_MSG_*` | adds `lineID, guid` as `arg11, arg12` after the existing ten ([details](docs/API.md#chat_msg_-arguments-lineid-arg11-and-guid-arg12)) |
@@ -300,6 +320,7 @@ when launching with `-console`), not as Lua functions. See the
@@ -421,10 +461,10 @@ Download the prebuilt `ClassicAPI.dll` from the
3. Add `ClassicAPI.dll` to `dlls.txt`.
4. Launch the game with `VanillaFixes.exe`.
The `!!!ClassicAPI` and`ClassicAPI_DebugTools` addons are *inside* the
DLL. You do not download or install them. The`src/embed/AddOns/` folder
in this repository is source code for the DLL. Do not copy it into your
game.
The `!!!ClassicAPI`,`ClassicAPI_DebugTools` and `ClassicAPI_EventTrace`
addons are *inside* the DLL. You do not download or install them. The
`src/embed/AddOns/` folder in this repository is source code for the DLL.
Do not copy it into your game.
## Bundled addon: !!!ClassicAPI
@@ -469,22 +509,40 @@ without a DLL rebuild. Without this file, the game uses the copy with the
newer `## Version:`. The copy is hidden and always enabled, the same as
the embedded addon.
## Lua errors
ClassicAPI replaces the game's Lua error box with a Lua error window. The
window opens when an error occurs. It shows the message, the time, the count,
the stack and the local variables of each error. You can select and copy the
text. The arrow buttons show the previous and the next error. The
**Reload UI** button reloads the interface.
If you use `!BugGrabber` (with BugSack), BugGrabber gets the errors and the
window does not open. If an addon sets its own error handler, the window also
does not open.
| Command | Purpose |
|---------|---------|
| `/luaerrors` (or `/scripterrors`) | Opens or closes the Lua error window. |
| `/luaerrors clear` | Removes all errors from the window. |
## Debug tools
ClassicAPI contains a backport of Blizzard's`Blizzard_DebugTools` addon,
with the name `ClassicAPI_DebugTools`. The DLL contains this addon, so you do
not install it. The addon is not in the AddOns list, and you cannot disable it.
ClassicAPI contains backports of two Blizzard addons:`Blizzard_DebugTools`,
with the name `ClassicAPI_DebugTools`, and `Blizzard_EventTrace`, with the
name `ClassicAPI_EventTrace`. The DLL contains theseaddons, so you do not
install them. They are not in the AddOns list, and you cannot disable them.
The slash commands are always available. The tools load the first time
that you use one of these commands:
The slash commands are always available. Each addon loads the first time
that you use one of its commands:
| Command | Purpose |
|---------|---------|
| `/dump <expr>` | Shows a Lua value in the chat frame. It shows tables and all return values. Use it to examine the return values of `GetSpellInfo`, `C_Item.GetItemInfoInstant`, and other functions. |
| `/etrace`| Opens the event trace window. Other forms: `/etrace start`, `/etrace stop`, `/etrace add EVENT`, and more. |
| `/framestack [showHidden [showRegions]]` (or `/fstack`) | Shows a tooltip with a list of the frames under the cursor. A `-->` mark shows one frame, with its anchors and the file and line that made it. Left Alt and Right Alt move the mark. Ctrl opens the marked frame in the table inspector. Shift shows its texture files. |
| `/etrace`(or `/eventtrace`) | Opens or closes the event trace window. The window logs each event with its time and its arguments. Move the mouse over an event to see its arguments, and the contents of each table argument. You can search the log, hide events with the filter, and pause the log. `/etrace mark <text>` adds a line of text to the log. |
| `/framestack [showHidden [showRegions]]` (or `/fstack`) | Shows a tooltip with a list of the frames under the cursor. A `-->` mark shows one frame, with its anchors and the file and line that made it. Left Alt and Right Alt move the mark. Ctrl opens the marked frame in the table inspector. Shift shows its texture files. The tooltip also shows the addon that made the marked frame. When `scriptProfile` is `1`, it shows the CPU time of the frame scripts. |
| `/tinspect [expr]` (or `/tins`) | Opens a table inspector on the result of `expr`. With no table, it opens on the frame under the cursor. The window shows the anchors and the fields of the table, grouped by type. You can edit numbers, strings and booleans, filter the lines, and open a child table or frame. |
| `/profiler` (or `/prof`) | Opens the profiler. The profiler shows the Lua memory, the allocations and the CPU time of each addon, frame, event and global function. `/profiler widget` shows a small window with the Lua memory, the frame rate and the addons that use the most. `/profiler reset` sets the counters to zero. CPU times need `scriptProfile``1`. `/profiler profile on` sets it and reloads the UI. |
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Brues