From 99fde6e1bbf013ef439acdbbdd0946d1091bab9b Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Wed, 11 Nov 2026 13:02:39 -0600 Subject: [PATCH] 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. --- docs/API.md | 11 ++++++- src/Offsets.h | 19 +++++++++--- src/model/Scene.h | 7 +++++ src/model/SceneActor.cpp | 62 +++++++++++++++++++++++++++++++++++----- src/model/VisualKit.cpp | 17 +++++++---- 5 files changed, 99 insertions(+), 17 deletions(-) diff --git a/docs/API.md b/docs/API.md index 7a7628da..1c52451a 100644 --- a/docs/API.md +++ b/docs/API.md @@ -20145,10 +20145,19 @@ false)` sets only the first flag. The actor stops when either flag is Shows the effects of a spell visual kit (a `SpellVisualKit` ID) on the model, for example the glow in the hands of a caster. A new kit removes the effects of the old kit. `0` or `nil` removes the kit. With `oneShot` set to -`true`, each effect plays one time. Without it, the effects loop. The kit +`true`, each effect plays one time. Without it, the effects last until the +kit changes: an effect that has a lasting state shows it after it starts, +for example the ice of Frost Nova after it forms, and the other effects +loop. The kit does not play its animation or its sound: use `SetAnimation` for the animation. +Most effects of a kit hang on a point of the model, for example a hand. A +kit can also have one effect that stands on the ground where the actor is, +for example the ice of Frost Nova's state kit (285). This effect stays at +the place where the actor stood when the kit started. It does not move with +the actor. + ```lua -- Cast a Fireball: hold the precast glow, then release it. caster:SetAnimation(51) -- ReadySpellDirected diff --git a/src/Offsets.h b/src/Offsets.h index 01438667..f339ae03 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -6400,6 +6400,13 @@ enum Offsets { VAR_SPELLVISUALKIT_RECORDS = 0x00C0D74C, VAR_SPELLVISUALKIT_COUNT = 0x00C0D750, OFF_SPELLVISUALKIT_EFFECTS = 0x0C, + // The kit's tenth effect, which the world plants in the world rather + // than on an attachment: PlayUnitSpellVisualKit (0x0060EDF0) makes a + // CEffect and PlantEffect (0x0061FCF0) puts it at the unit's position + // (its vtable +0x14), or at the point it is given; with a spell that has a + // root aura (26) the effect gets flag 0x4000 and follows the unit. Frost + // Nova's state kit 285 holds its ice here (Frost_Nova_state.mdx). + OFF_SPELLVISUALKIT_WORLD_EFFECT = 0x30, OFF_SPELLVISUALKIT_PROC_KIND = 0x3C, OFF_SPELLVISUALKIT_PROC_VALUE = 0x4C, // SpellVisualEffectName.dbc: the model file at +0x08, which the ghost @@ -6456,10 +6463,14 @@ enum Offsets { // to the area's radius over the model's bounding-sphere radius when that // radius is above this double (0.001, fcomp at 0x005D538E). VAR_DYNAMIC_OBJECT_MIN_SPHERE = 0x00801608, - // The animation the hook plays on a model that has it and no animation 0 - // (HasAnimation 0x9E at 0x005D5345, played at 0x005D53D8); the done - // callback (0x005D5580) plays it again at each natural end. - ANIM_DYNAMIC_OBJECT_LOOP = 158, + // Hold (AnimationData.dbc), an effect's lasting state. The hook plays it + // on a model that has it and no animation 0 (HasAnimation 0x9E at + // 0x005D5345, played at 0x005D53D8), and its done callback (0x005D5580) + // plays it again at each natural end. A state kit's effect plays it once + // its first sequence ends (KitEffectHoldCallback 0x005FF170), and + // KitEffectDecayCallback (0x005FF1D0) plays it again until the effect's + // end time, which a state kit leaves at 0, so it holds until the aura goes. + ANIM_HOLD = 158, // The area kit's shard emitter (0x005D55C0 -> 0x006ECE30 -> 0x006EB930; // the shards 0x006EBB30..0x006EBDA9), verified by disassembly and by // reading the binary: the procedure kind that starts it (cmp [ecx], 9 at diff --git a/src/model/Scene.h b/src/model/Scene.h index 99c21dae..92baf6b7 100644 --- a/src/model/Scene.h +++ b/src/model/Scene.h @@ -319,6 +319,13 @@ class Actor : public Animation::Object { uint32_t spellVisualKit = 0; bool spellVisualKitOneShot = false; std::vector kitEffects; // the kit's effect models, one reference each + // The kit's world effect (OFF_SPELLVISUALKIT_WORLD_EFFECT): a model of its + // own in the scene, planted where the actor stood, one reference, lit as + // an entity; `kitWorldDone` once a one-shot effect has ended. + void *kitWorldEffect = nullptr; + float kitWorldPosition[3] = {0.0f, 0.0f, 0.0f}; + std::unique_ptr kitWorldLight; + bool kitWorldDone = false; // ApplySpellVisualKit calls made before the model loaded: {kit, oneShot}. std::vector> pendingKits; diff --git a/src/model/SceneActor.cpp b/src/model/SceneActor.cpp index 7bf60195..336e263a 100644 --- a/src/model/SceneActor.cpp +++ b/src/model/SceneActor.cpp @@ -214,6 +214,16 @@ void __fastcall OnAnimDone(void *model, uint32_t keyBone, uint32_t animID, uint3 M2::PlayAnimation(model, static_cast(keyBone), 0xFFFFFFFFu, -1, 0, 1.0f, 1, 1); } +// A one-shot world effect's end (EffectDoneCallback's test, reason 0): it +// hides until the kit goes. +void __fastcall OnKitWorldDone(void *model, uint32_t /*keyBone*/, uint32_t /*animID*/, uint32_t reason, + uint32_t /*overshoot*/, uint32_t userLow, uint32_t /*userHigh*/) { + if (reason != 0) + return; + reinterpret_cast(static_cast(userLow))->kitWorldDone = true; + M2::SetVisible(model, false); +} + // Takes the kit's effects off the model and undoes its tint. void DropKitEffects(Actor &actor) { for (void *effect : actor.kitEffects) { @@ -221,6 +231,11 @@ void DropKitEffects(Actor &actor) { M2::Release(effect); } actor.kitEffects.clear(); + if (actor.kitWorldEffect != nullptr) { + M2::SetAnimDoneCallback(actor.kitWorldEffect, nullptr, 0, 0); + ReleaseLit(actor.kitWorldEffect, actor.kitWorldLight); + actor.kitWorldEffect = nullptr; + } if (actor.model != nullptr) { const float white[3] = {1.0f, 1.0f, 1.0f}; M2::SetDiffuse(actor.model, white); @@ -231,9 +246,32 @@ void DropKitEffects(Actor &actor) { void ApplyKit(Actor &actor) { if (actor.model == nullptr || !actor.loaded || actor.spellVisualKit == 0) return; - if (const uint8_t *kit = Model::VisualKit::Record(actor.spellVisualKit)) - Model::VisualKit::Apply(actor.SceneFrame(), actor.model, kit, actor.spellVisualKitOneShot, - &actor.kitEffects); + const uint8_t *kit = Model::VisualKit::Record(actor.spellVisualKit); + if (kit == nullptr) + return; + Model::VisualKit::Apply(actor.SceneFrame(), actor.model, kit, actor.spellVisualKitOneShot, &actor.kitEffects); + // The world effect, planted where the actor stands (PlantEffect + // 0x0061FCF0). A kit given without a spell has no root aura, so it stays + // there, as the world's does without flag 0x4000. + const uint8_t *effect = + DBC::Record(Offsets::VAR_SPELLVISUALEFFECTNAME_RECORDS, Offsets::VAR_SPELLVISUALEFFECTNAME_COUNT, + Game::Read(kit, Offsets::OFF_SPELLVISUALKIT_WORLD_EFFECT)); + if (effect == nullptr) + return; + void *frame = actor.SceneFrame(); + void *planted = + M2::CreateModel(Model::Pane::Scene(frame), Game::Read(effect, Offsets::OFF_SPELLVISUALEFFECTNAME_FILE)); + if (planted == nullptr) + return; + actor.kitWorldEffect = planted; + actor.kitWorldDone = false; + std::memcpy(actor.kitWorldPosition, actor.position, sizeof actor.kitWorldPosition); + LightAsEntity(planted, actor.kitWorldLight, frame); + if (actor.spellVisualKitOneShot) + M2::SetAnimDoneCallback(planted, reinterpret_cast(&OnKitWorldDone), + static_cast(reinterpret_cast(&actor)), 0); + else + M2::SetAnimDoneCallback(planted, Model::VisualKit::LoopCallback(), 0, 0); } // ---- the ranged slot (Offsets: UNIT_HAND_RANGED) ---- @@ -1041,8 +1079,8 @@ void SizeSpellArea(Actor &actor) { if (size > 0.0f) actor.scale = actor.areaRadius / size; } - if (M2::HasAnimation(actor.model, Offsets::ANIM_DYNAMIC_OBJECT_LOOP) && !M2::HasAnimation(actor.model, 0)) { - actor.animation = Offsets::ANIM_DYNAMIC_OBJECT_LOOP; + if (M2::HasAnimation(actor.model, Offsets::ANIM_HOLD) && !M2::HasAnimation(actor.model, 0)) { + actor.animation = Offsets::ANIM_HOLD; actor.PlayAnimation(); } } @@ -1133,6 +1171,8 @@ void Actor::Update(float elapsedSec, float sceneSec) { WriteStringUnit(*this); Casts::Update(*this, sceneSec); Areas::Update(*this, sceneSec); + if (kitWorldEffect != nullptr) + SettleLight(kitWorldEffect, kitWorldLight.get(), sceneSec); // The casts that reached their target, with (spellID, target, castID). // Taken first: a script may cast again, and its impact waits for the next // update. @@ -1169,6 +1209,10 @@ void Actor::Update(float elapsedSec, float sceneSec) { void Actor::Link() { Casts::Link(*this); Areas::Link(*this); + if (kitWorldEffect != nullptr && M2::IsReady(kitWorldEffect, 0, 1)) { + M2::SetVisible(kitWorldEffect, shown && !kitWorldDone); + M2::SetAnimated(kitWorldEffect, true); + } if (model == nullptr || !M2::IsReady(model, 0, 1)) return; if (M2::Parent(model) == nullptr) // a seated rider is animated by its mount @@ -1181,11 +1225,15 @@ void Actor::Link() { void Actor::Place() { Casts::Place(*this); Areas::Place(*this); - if (model == nullptr) - return; const float axisX[3] = {1.0f, 0.0f, 0.0f}; const float axisY[3] = {0.0f, 1.0f, 0.0f}; const float axisZ[3] = {0.0f, 0.0f, 1.0f}; + if (kitWorldEffect != nullptr) { + const float unit[3] = {1.0f, 1.0f, 1.0f}; + M2::SetBaseTRS(kitWorldEffect, kitWorldPosition, 0.0f, axisZ, unit); + } + if (model == nullptr) + return; const float scales[3] = {scale, scale, scale}; M2::SetBaseTRS(model, position, ShownYaw(), axisZ, scales); float *matrix = M2::BaseMatrix(model); diff --git a/src/model/VisualKit.cpp b/src/model/VisualKit.cpp index 59253928..dd05becc 100644 --- a/src/model/VisualKit.cpp +++ b/src/model/VisualKit.cpp @@ -36,9 +36,11 @@ // drain (0x0061F680) releases a stopped effect once HasLiveParticles is // false. Here the release is the detach from the pane's model, run on // FrameTick's tail where no model is mid-draw. Without oneShot an effect -// loops until the model is replaced, as on retail: an effect model's sequence -// does not loop by itself, so it gets the world's loop callback -// (KitEffectLoopCallback, 0x0060ED00), which plays the ended animation again. +// lasts until the model is replaced, as on retail: an effect model's sequence +// does not loop by itself, so at each end it holds Hold (158) when the model +// has it, as a state kit's effect does (KitEffectHoldCallback 0x005FF170), +// and else plays the ended animation again (KitEffectLoopCallback, +// 0x0060ED00). // // The effects are children of the pane's model, so they go when the model // does: SetUnit, SetItem, a hide and show, and so on. A model destroyed with @@ -90,13 +92,18 @@ void __fastcall OnEffectDone(void *model, uint32_t /*keyBone*/, uint32_t /*animI g_stopped.push_back({reinterpret_cast(static_cast(userLow)), model}); } -// KitEffectLoopCallback: a sequence that ended cleanly plays again. +// A lasting effect's sequence that ended cleanly: a model with Hold holds +// it, as a state kit's effect does (KitEffectHoldCallback 0x005FF170, then +// KitEffectDecayCallback 0x005FF1D0 with no end time, which plays Hold again +// at each end); one without plays its sequence again, as a channel kit's does +// (KitEffectLoopCallback 0x0060ED00). Frost Nova's ice forms once, then stays. void __fastcall OnEffectLoop(void *model, uint32_t /*keyBone*/, uint32_t animID, uint32_t reason, uint32_t /*overshoot*/, uint32_t /*userLow*/, uint32_t /*userHigh*/) { if (reason != 0) return; - M2::PlayAnimation(model, -1, animID, -1, 0, 1.0f, 1, 1); + const uint32_t next = M2::HasAnimation(model, Offsets::ANIM_HOLD) ? Offsets::ANIM_HOLD : animID; + M2::PlayAnimation(model, -1, next, -1, 0, 1.0f, 1, 1); } // Detaches a stopped effect that is still on its model, then drops our