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

AddAuraVisual now plays its state kit's sound at the actor when the aura
shows, or loops it there for a 0x200 sound, following the actor, quiet
while the scene or actor is paused and while the scene is hidden, and
fading out with the aura. The loop test and the fade move to the scene's
Sounds module (Sounds::KitLoops, Sounds::kStopFadeSec), which the casts'
channel and missile sounds share.
2026-11-11 15:17:59 -06:00
Brues bd0f61724e feat(model): auras pin their animation; the client's missile release; kit ground effect turns
The stationary pin. CGUnit_C::PlayAnimation (0x005FE2F0) passes every
request but a death through ApplyEffectAnimation (0x005FDE80): while the
unit's movement flags have none of 0x20000F (the four directions and
swimming), the newest effect on its list whose kit animation is positive
and whose flags carry 0x1000 (the kind 2 state kit, 0x0060EECD) plays
that animation with variation -1 instead. Actor::PlayAnimation now does
the same with the newest aura from AddAuraVisual, so a stunned actor
stands stunned and a moving one runs; the mover's path moves set the
forward flag as StartSplinePath (0x006187A0) does. A new aura with an
animation picks again unless the model already plays it (0x0060F383 to
0x0060F399); its end does not, and the pinned animation plays on until its
sequence ends, as on a unit.

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

The kit's ground effect. A planted effect is placed by 0x00620A90 as
Translate(point) * Rotate(owner's facing) * Scale(owner's scale), a scale
at or below 0 taken as 1. SetSpellVisualKit's +0x30 effect stood unturned
at scale 1; it now takes the actor's facing and scale when planted, as
the aura visuals' do.
2026-11-11 15:02:54 -06:00
Brues 0d7b879842 feat(model): actor:AddAuraVisual / RemoveAuraVisual, a unit's auras on actors
A 1.12.1 unit shows every aura it carries at once. When an aura slot
fills, 0x005FF350 plays the state kit of the spell's visual (SpellVisual
+0x10, now OFF_SPELLVISUAL_STATE_KIT) as a lasting kind 2 kit through the
kit player (0x0060EDF0): each effect column's model holds at its
attachment (158 Hold at each end, KitEffectHoldCallback 0x005FF170), and
the +0x30 world effect is planted where the unit stands (PlantEffect
0x0061FCF0), turned by its facing and scaled by its scale (0x00620A90),
following it for a spell with a root aura (26: flag 0x4000, re-placed at
the owner each update, 0x006205A5). When the slot clears, 0x005FF290
stops the spell's kits with force (0x00614150): an effect whose model is
loaded and has 159 Decay (ANIM_DECAY) plays it and stops at its end
(0x006141F0, the same test as EffectDoneCallback); any other stops at
once (CEffect::Stop 0x006203E0: hidden, its particles finish).

SetSpellVisualKit holds one kit, so two auras on one actor replaced each
other. model/SceneAura.cpp keeps a list of auras per actor, one per spell
as one slot holds a spell: AddAuraVisual(spellID) shows the state kit
beside the actor's kit, RemoveAuraVisual([spellID]) ends one aura or all.
VisualKit gains Stop (the removal step for an attached effect, through its
dying list), SetsColor (now shared with the cast's precast and channel
tints) and ApplyProcedures, so a removed tint gives the model back the
colors of the kits still on it. Casts::Retire hands a stopped world effect
to the actor's impact list, which frees it once its particles are gone.
The auras survive a model change and show once the new model loads;
ClearModel ends them, as the actor pool releases through it. Not played:
a state kit's animation and sound.
2026-11-11 14:42:24 -06:00
Brues d8659e4328 feat(model): channels, ground-point casts, and a lasting kit's loop sound
Channels. A 1.12.1 spell channels when AttributesEx (+0x1C) has a bit of
0x44. After its cast the server sets UNIT_CHANNEL_SPELL and the client
plays the visual's +0x14 channel kit as a lasting (kind 2) kit
(0x00612A30): its effects hold, its animation is the unit's while it
channels (0x00612990), and its chain procedures (kinds 0 and 12) draw the
beam to the channel object, which a persistent chain (value3) keeps until
0x0060D1C0 ends the channel. PlaySpellVisual now takes a channelTimeMs
after the cast time and adds a Channel phase: the kit lasts the given time,
else the spell's duration from GetSpellDuration (0x006EA000, unmodified),
forever for an endless one. The lightning renderer never expires a bolt
on its own, so a channel's hops are held by its cast ID and Chains::End
drops them. StopSpellVisual takes an optional castID to end one cast.

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

Ground points. actor:PlaySpellVisualAtPoint(spellID, x, y, z [, castTimeMs
[, channelTimeMs]]) casts at a point of the scene. At the go a visual with
no missile (+0x18 is 0) and a +0x30 model plants that model at the target
block's destination (0x006E8088 to 0x006E8143: a 0x90-byte CEffect built
by 0x0061F490 and placed by PlantEffect 0x0061FCF0), turned by the
caster's facing and scaled by its scale (0x00620A90). It plays its
sequence once; EffectDoneCallback (0x005FBF50) then stops it, hidden while
its particles finish, and the dying list (0x0061F680) frees it once none
lives. Its $SND events play at the event's point and $HIT wounds the
caster, the effect's target (0x0061F6F0). No impact kit plays: the instant
impact returns on an empty hit list (0x006E8BF0). A visual with a missile
flies one missile to the point (0x006E8A50, masks 0x20 and 0x40) and
leaves its +0x30 impact model there. Inferno (1122) is the first user: its
infernal_impact_base meteor. OnSpellVisualImpact runs with a nil target.
2026-11-11 14:11:52 -06:00
Brues 99fde6e1bb feat(model): a kit's world effect on scene actors; lasting effects hold
A 1.12.1 SpellVisualKit has nine effect columns that hang on attachments
(+0x0C to +0x2C) and a tenth, +0x30, that the world plants on the
ground. PlayUnitSpellVisualKit (0x0060EDF0) makes a CEffect for it and
PlantEffect (0x0061FCF0) puts it at the unit's position (the unit's
vtable +0x14) or at the point it is given; with a spell that has a root
aura (26) in one of its three effects the effect gets flag 0x4000 and
follows the unit. Frost Nova's state kit 285 keeps its ice there
(Frost_Nova_state.mdx), so a frozen actor showed only the head glow.

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

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

Animation 158 was named ANIM_DYNAMIC_OBJECT_LOOP for the ground areas'
use; it is ANIM_HOLD now, its AnimationData name, with both readers in
its comment. docs/API.md describes the ground effect and the hold under
SetSpellVisualKit.
2026-11-11 13:02:39 -06:00
Brues f5b240de77 feat(model): actor:FadeOut, the world's model fade; dead actors lie Dead
When the 1.12.1 client removes an object (deactivate 0x006145E0), it
hands the model to FadeOutModel (0x00672DF0) at its current alpha. A
ready model (0x00710450 with 0, 0) at an alpha of 0.01 or more, or NaN
(fcomp [0x008029D0] at 0x00672E21, test ah,5 / jnp), is kept with the
time and that alpha; any other is released at once. Each frame the pass
0x00672EF0 shows (3 - 2x)x^2 with x = (1 - age x 0.0005) x the alpha,
held to 0..1 (0x00672FD3 to 0x00673025, 3.0 at 0x0080297C), and releases
the model when the age passes 2000 ms (cmp eax,0x7D0; jle at 0x00672F36).

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

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

docs/API.md documents FadeOut and IsFadingOut, and the death hold under
SetMovementEnabled.
2026-11-11 11:08:27 -06:00
Brues bb5acbbdfb feat(model): actor:KnockBack, the client's knockback launch on scene actors
A 1.12.1 server knocks a unit back with SMSG_MOVE_KNOCK_BACK (0xEF, to
its controller) or MSG_MOVE_KNOCK_BACK (0xF1, relayed): a direction
pair, a horizontal speed and a vertical speed that the server negates
into the client's down-positive fall speed. Both paths end in the same
launch on the unit's CMovement, 0x006179C0: swimming ends (0x007C6E80),
a fall starts at the vertical speed (0x007C61F0, which re-anchors with
the old flags), the direction pair overwrites the heading +0x68 and the
direction +0x5C with 0 in z, flag 0x2 clears and 0x8001 sets whatever
the speeds, and the horizontal speed goes to +0x84. Nothing about the
unit refuses it. The direction is world-absolute.

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

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

docs/API.md documents the method next to MoveTo.
2026-11-11 10:41:33 -06:00
Brues 0825491af2 feat(model): chain-lightning bolts on scene casts; quiet missiles when paused; docs
The 1.12.1 client draws Chain Lightning's arcs from a spell visual kit
procedure of kind 0 or 12 (0x0060D7FC, through the byte table at
0x0060DC20 to 0x006ECB90). The procedure's values decode, as the area kit
does (bits of value + 512.0, shifted right 14), to a SpellChainEffects id,
a strand count capped at 3 (0x006ECC65) and a persistent flag. Chain
Lightning's cast kit 321 has kind 12, chain 1, one strand; row 1 of
SpellChainEffects.dbc is segment 2.78, width 0.5, jitter 0.04, texture
period 1.0, life 1000 ms, Textures\SpellChainEffects\Lightning.blp.

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

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

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

docs/API.md gains the scene actor methods of this branch that had no
entry: actor:SetModelBySpellArea, actor:SetGroundReticle /
ClearGroundReticle / GetGroundReticle and actor:SetMovementSpeed /
GetMovementSpeed, with the chain bolts and the paused sounds in the
PlaySpellVisual, scene:SetPaused and actor:SetPaused entries.
2026-11-11 09:49:41 -06:00
Brues 1e0871b639 feat(model): names over scene actors, as the world draws a unit's
actor:SetNameText(text [, r, g, b]) / ClearNameText / GetNameText show
a name over the head. It is drawn the way the 1.12.1 world draws a
unit's name (PLAYERNAMEDESC::UpdatePlate, 0x6C6E90):

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

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

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

The name font and batch exist only in the world: world entry makes them
(0x6C7470), and PlayerNameShutdown (0x6C7630) frees them in
ClientDestroyGame (0x40202F), before CGGameUI::ShutdownGame. Each actor
therefore keeps the font its string was made with, and frees the
string only while that font still exists. At the glue screens no name
draws.
2026-11-11 08:07:49 -06:00
Brues 70a6b99bfe feat(model): a paused scene stops movement and spell visuals too
scene:SetPaused stopped only what runs on the M2 scene clock (scene
+0x0C): the animations, GetSceneTime and the scene timers. The mover
ticked on the OS clock, as the client's does, and the casts stepped by
the frame's elapsed time. A paused scene therefore still moved its
actors in a frozen pose and flew its missiles.

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

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

FUN_SIMPLEMODEL_GET_SCENE (0x76CFC0) makes the scene on first use, so
a scene frame always has a clock to read. A hidden scene runs no
update, so its clock and its actors stop as before.
2026-11-11 08:07:49 -06:00
Brues edd7fb8577 docs(model): document the actor highlight, selection circle and move marker 2026-11-11 08:07:48 -06:00
Brues ddffa12f2f docs(model): document the scene clock and scene timers 2026-11-11 08:07:48 -06:00
Brues 3df06c056d docs(model): document scene:GetActorsInRadius 2026-11-11 08:07:48 -06:00
Brues 5a78289124 docs(model): document scene:GetCursorRay
API.md gets a GetCursorRay entry (the two points, when it returns
nothing, and how TraceSegment finds the WMO point under the cursor, with
a right-click move example). README lists it.
2026-11-11 08:07:48 -06:00
Brues 6b4224d281 docs(model): document FollowCamera and GetCameraPivotHeight
API.md gets a Follow camera section (SetFollowActor / GetFollowActor,
the pivot, the smooth height change at cameraHeightSmoothSpeed, the stop
in front of walls, the wait for the model, and how to add the camera to
a ModelSceneMixinTemplate scene) and an actor:GetCameraPivotHeight
entry (the mouth or collision-box base, the stance animations near the
actor, the swim drop, the 5/6 to 15 yard range). README lists both.
2026-11-11 08:07:48 -06:00
Brues aa88e776e9 docs(model): document ModelScene movement, traces, liquids and listener
API.md gets the scene functions that had no entry: TraceSegment (with
its camera faces), GetLiquidAtPoint, SweepCollider and
SetSoundListenerActor / GetSoundListenerActor. Scene sounds now names the
listener actor.

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

The README's model scene summary and its ModelScene and ModelSceneActor
rows list the same names.
2026-11-11 08:07:47 -06:00
Brues 2567ac1bd8 feat(model): ModelScene casts report when they reach their target
actor:PlaySpellVisual now returns a cast ID (nil when the spell has no
visual, the actor shows no model or the target is in another scene),
and the caster's new OnSpellVisualImpact script runs with (spellID,
target, castID) when the cast reaches its target. A game can apply a
spell's result at the moment its impact shows, without timing the
flight itself.

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

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

docs/API.md describes the cast ID and the script, with an example.
2026-11-11 08:07:46 -06:00
Brues 229a5d51ae docs: ModelScene SetWorldModel mapID and outdoor water light
SetWorldModel takes an optional mapID: with it, the WMO's outdoor water
takes that map's light at the camera and the world's time of day, with
the nearby zone lights blended in; without it, the light where the
player is. SetWorldModelByMapID's water takes its map's light.
2026-11-11 08:07:44 -06:00
Brues aaa033bb4f docs: ModelScene ranged slot, bowstring, eased WMO light
TryOn puts ranged weapons in slot 18; the ranged weapon shows only while
the actor shoots, in the hand the world uses. The slot methods, the
transmog lists, SetSheathed, SetSheathedCategory and PlaySpellVisual say
so. A bow has a string. An actor's light in a WMO changes over a short
time, and missiles and impact effects take the light of their place.
2026-11-11 08:07:44 -06:00
Brues 098432bee1 docs: ModelScene ranged pose, stuck arrows, camera liquid fog
PlaySpellVisual: the ranged weapon comes to hand at the spell's start;
the arrow in hand, the draw and the release; instant shots do not draw;
arrows and thrown weapons stay in the target for 5 seconds; no spell
animation plays over a death animation. StopSpellVisual lowers a drawn
bow. TryOn: an actor without a unit holds two one-hand weapons.
SetWorldModel: the camera in the WMO's water takes its underwater fog,
in lava or slime the scene's fog unless the WMO has one for it.
2026-11-11 08:07:43 -06:00
Brues 7be139fe32 docs: ModelScene WMO liquid and camera fog
SetWorldModel: the WMO's own fog holds while the camera is above an
indoor part, fades in and out over 4 seconds, blends nearby fog zones,
comes in from the far clip in a scene without fog, and does not change
for a camera in liquid. The WMO's water, lava and slime show and
animate; outdoor water takes the colors of the player's zone.
2026-11-11 08:07:42 -06:00
Brues 5783814dc5 docs: ModelScene floor shadows and footsteps, ranged shots, StopSpellVisual
API.md documents what the last three commits added to ModelScene actors:

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

README lists :StopSpellVisual with the other actor methods.
2026-11-11 08:07:42 -06:00
Brues 8640cc02da docs: ModelScene WMO backdrops, scene sounds and actor:PlaySound
docs/API.md gains the WMO backdrop methods (SetWorldModel,
SetWorldModelByMapID, ClearWorldModel), SetPlayWorldModelSounds /
GetPlayWorldModelSounds, a Scene sounds section on hearing a scene from
its camera, and actor:PlaySound. SetWorldModel covers the props, their
fade, and the light the WMO gives the actors. SetPlayAnimationSounds and
PlaySpellVisual now say where their sounds play. README lists the new
methods.
2026-11-11 08:07:42 -06:00
Brues be6a3c5bef feat(model): ModelSceneActor SetShadowShown blob shadows
A ClassicAPI extension, off by default: actor:SetShadowShown(shown) /
IsShadowShown() put the world's blob shadow under the actor.

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

The world lays the shadow onto the ground's batches with a decal
(0x006D7330). A scene has no ground, so the paint draws the turned box
itself as a flat triangle strip on the plane of the base translation,
after the animate pass and before the draw passes, so every model draws
over the shadows. Culling is off, as for the engine's lightning quad
(0x007AFCB0). The decal's height fade and its shadowBias depth test
EQUAL are not drawn: both exist to match real ground. A model hung on
another casts none.
2026-11-11 08:07:41 -06:00
Brues 4e8dc39e65 feat(model): ModelScene GetActorAtCursor and OnActorEnter/OnActorLeave
A ClassicAPI extension: scene:GetActorAtCursor() returns the shown actor
under the cursor, and the scene scripts OnActorEnter / OnActorLeave
(self, actor) run when that actor changes while the scene is the mouse
focus.

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

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

The hover runs from the scene's update walk, only while one of the two
scripts is set (Frame::ExtraScripts cells) and the scene is the mouse
focus (UI context +0x7C).
2026-11-11 08:07:41 -06:00
Brues d53e15ff45 feat(model): ModelSceneActor ApplySpellVisualKit
A ClassicAPI extension with the contract of retail's PlayerModel
(CharacterModelBase) method of the same name. The kit is added next to
the kits that the actor already shows. The actor's SetSpellVisualKit
keeps retail's behaviour: it replaces the actor's one kit.

The kit goes through Model::VisualKit::Apply, the same routine
PlayerModel:ApplySpellVisualKit uses. This is the char-select ghost's
kit step (0x004727F0) for any kit: the effect models hang at their
attachments, and the tint and alpha procedures apply. The model owns
the effects, so a looping kit stays until the model changes, and a
oneShot kit stops when its sequence ends. HasAttachment waits for an
unloaded model file, so a call made before the model has loaded is
held in Actor::pendingKits and applied with SetSpellVisualKit's kit
once the model loads.
2026-11-11 08:07:41 -06:00
Brues 5c5bedece6 feat(model): ModelSceneActor animation event sounds
ClassicAPI extensions: actor:SetPlayAnimationSounds(enabled) and
scene:SetGroundTerrain([terrainTypeID]), each with its getter.

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

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

The sounds are off by default, so stock scenes such as the dressing
room stay silent. They play in 2D through the by-ID player. A scene
without a ground terrain has no footsteps and no death thud. $CSS,
$CAH and $AH0 to $AH3 play nothing: they present a pending swing
(0x006247D0), and an actor never swings at anything. The unit's
display ID is kept on the actor so that its sound data can be found.
2026-11-11 08:07:40 -06:00
Brues a258c856d1 feat(model): ModelSceneActor PlaySpellVisual
A ClassicAPI extension. actor:PlaySpellVisual(spellID [, target
[, castTimeMs]]) plays the visual of a spell cast between two actors. It
follows the steps of the world chain between two units. That chain
depends on units, missile objects and world objects, and an actor has
none of them, so model/SceneSpell.cpp repeats each step on actor models:

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

A kit's animation plays in place of the actor's animation. It does not
fire OnAnimFinished, and SetAnimation cancels it. Kit sounds play
through the by-ID player. Sound::Play gets a small header (PlayKitID,
PlayKitLooped, Stop) so that other modules can start a sound and stop
it safely. M2.h gets the event, particle and attachment helpers, and
VisualKit exposes its loop callback.
2026-11-11 08:07:40 -06:00
Brues e9340786c9 feat(model): ModelSceneActor attachment points and AttachToActor
Three ClassicAPI extensions on the actor:

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

EnsureAnimated recurses through the parent chain, so an attach cycle
never ends. M2::CanAttach now refuses a cycle for both AttachToActor and
AttachToMount. HasAttachment moves into M2.h, and VisualKit uses it.
2026-11-11 08:07:40 -06:00
Brues 9101de7f78 feat(model): ModelSceneActor SetSheathedCategory and UseUnitSheatheCategory
SetSheathedCategory(slot, category) picks where a sheathed hand item
hangs: Default (its own place), Back, Side, or Hide. It also adds
Enum.TransmogOutfitSlotOptionSheatheCategory.

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

The lane holds the type it hangs with, so every engine detach (Undress,
UndressSlot, a TryOn that replaces the hand) removes the model from the
place it hangs at. The actor keeps each lane's own type and category,
and re-hangs a lane after each write (SetModelByUnit, TryOn,
DressPlayerSlot). UseUnitSheatheCategory(true) uses every item's own
type, because 1.12.1 units have no category.
2026-11-11 08:07:40 -06:00
Brues 8b6b6ce4ce feat(model): DressUpModel IsSlotAllowed and IsSlotVisible
IsSlotAllowed answers from the gates of 1.12.1's DressUpModel::TryOnItem
worker (0x00504540): a hand takes any held item, and an armor slot needs
the pane's character component (+0x3F8) with its ready byte (+0x40C) set.
A shapeshifted unit has neither, so its armor slots are not allowed. The
neck, rings, trinkets and ranged slot have no arm in the worker. A pane
without a model allows nothing. No 1.12 model hides an item in a slot it
takes, so IsSlotVisible gives the same answer.

The slot rule moves into Outfit::SlotAllowed, which the ModelScene actor
now shares, and TryOnResult reads the armor gate through the same
ArmorReady helper.
2026-11-11 08:07:40 -06:00
Brues ea6b3714ed feat(model): DressUpModel ItemTransmogInfo methods
DressUpModel:GetItemTransmogInfo(slot), GetItemTransmogInfoList() and
SetItemTransmogInfo(info [, slot, ignoreChildItems]), the same contract as
the ModelSceneActor's: appearanceID is the item ID, illusionID the enchant
whose glow a weapon shows, 19 slots in the list.

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

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

The ItemTransmogInfo argument reader and the ItemUtil.CreateItemTransmogInfo
pushers move from SceneActor.cpp to Model::TryOn, so both frame types share
them. Outfit gains InvSlotOfComponent for the armor arm's slot.
2026-11-11 08:07:39 -06:00
Brues 2e87d286ff feat(model): ModelSceneActor ItemTransmogInfo methods
GetItemTransmogInfo(slot), GetItemTransmogInfoList() and
SetItemTransmogInfo(info [, slot, ignoreChildItems]) on the actor. On
1.12.1 the appearance is the item ID and the illusion is the
SpellItemEnchantment whose glow a weapon shows.

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

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

SetItemTransmogInfo is TryOn on the info's IDs without ERR_NOT_EQUIPPABLE,
which the callers show themselves. An appearanceID of 0 changes nothing.
The list entries are built with ItemUtil.CreateItemTransmogInfo, now
ported with ItemTransmogInfoMixin, and Constants.Transmog is registered.
2026-11-11 08:07:39 -06:00
Brues 03afa419f2 feat(model): ModelSceneActor DressPlayerSlot, IsSlotAllowed, IsSlotVisible
DressPlayerSlot puts one inventory slot of a SetModelByUnit actor back
to what its unit wears. An armor slot copies the unit's own character
component record for the body slot (the dword array at component+0x4A8
that UnequipCharacterSlot 0x00478960 reads and clears) onto the actor's
clone with UnequipCharacterSlot + EquipBodySlotById (0x00478AA0), so a
helm or cloak the unit hides stays off: the unit's component has no
record there. A hand slot re-reads the unit's held-item lane, display
row and enchant glow and hangs only that lane, the other hand untouched.

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

Outfit's slot map is now public (ComponentSlotOf) and HangWeapons hangs
each lane through one HangLane step that DressSlot shares.
2026-11-11 08:07:39 -06:00
Brues 5d5682cbdd docs(model): ModelSceneActor:TryOn
API.md gets an entry for the actor's TryOn: which models take armor and
which take held items, the dual-wield rule, the wait for the model and
for the item data (with the hand and enchant kept), and what removes the
items. SetSheathed now says it applies to any actor and to items that
TryOn adds later. The README's ModelSceneActor row lists :TryOn.
2026-11-11 08:07:39 -06:00
Brues ce1ac37964 docs: document the ModelScene frame, its actors and C_ModelInfo
API.md gains a ModelScene section: CreateFrame("ModelScene") and its XML
attributes with the scene's starting camera, light and fog; the camera,
view inset and translation, Project3DPointTo2D, light, fog, draw layer,
pause and overlapped-model methods; every actor method (model sources,
unit dressing, placement, bounding boxes, animation and pause, spell
visual kits, mount seating), the actor scripts and <Actor> templates;
and the four C_ModelInfo getters. C_MountJournal.GetMountFromItem joins
the Mount section and GetCursorDelta the Input section.

README.md adds a Model scenes highlight, the ModelScene, ModelSceneActor,
ModelInfo and Mount rows, GetCursorDelta in the in-game and glue tables,
and Enum.ModelBlendOperation.
2026-11-11 08:07:37 -06:00
Brues d7103de564 feat(spell): count set bonuses in GetSpellBonusHealing
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
2026-11-09 11:28:51 -06:00
Brues b65c9e0319 fix(spell): never auto-unshift out of Spirit of Redemption
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).
2026-11-08 11:29:09 -06:00
Brues de033896b1 feat(spell): let autoUnshift talk and use objects in the druid forms
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.
2026-11-07 20:46:48 -06:00
MrbcatandBrues dc8d4caf12 fix(loot): skip corpses that stay lootable after LootAllCorpses (#133)
* 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>
2026-11-06 23:25:23 -06:00
Brues 20069f3815 docs(api): sort the reference's sections alphabetically
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.
2026-11-06 17:35:16 -06:00
Brues f2fa112f0a feat(mount): add C_MountJournal.GetMountFromSpell and GetMountInfoExtraByID
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.
2026-11-06 17:29:11 -06:00
Brues a106d86969 fix(unit): consult the name cache only when no unit object is held
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.
2026-11-06 11:52:58 -06:00
Brues d825bcbdda fix(spell): stand, dismount and unshift only when the cast is sent
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
2026-11-06 09:56:14 -06:00
Brues 55d94c80d6 feat(spell): apply autoStand/autoDismount/autoUnshift to interaction, loot, items, attacks and taxis
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.
2026-11-04 16:44:44 -06:00
Brues c0b403ba05 feat(model): add PlayerModel:ApplySpellVisualKit
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.
2026-11-04 15:32:23 -06:00
Brues 8f4f574174 feat(model): add PlayerModel:SetItem
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.
2026-11-04 14:21:58 -06:00
Brues 43a989dd56 feat(model): add PlayerModel:FreezeAnimation
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.
2026-11-04 13:52:02 -06:00
Brues 0caddb8fe6 feat(model): add PlayerModel animation, keep-on-hide and unit methods
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.
2026-11-04 13:11:45 -06:00
Brues 4726fd7c85 feat(model): add DressUpModel try-on hand, enchant glow, sheathing and auto-dress
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.
2026-11-04 10:16:07 -06:00