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.
This commit is contained in:
Brues
2026-11-11 13:02:39 -06:00
parent ea7e215a0c
commit 99fde6e1bb
5 changed files with 99 additions and 17 deletions
+10 -1
View File
@@ -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
+15 -4
View File
@@ -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
+7
View File
@@ -319,6 +319,13 @@ class Actor : public Animation::Object {
uint32_t spellVisualKit = 0;
bool spellVisualKitOneShot = false;
std::vector<void *> 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<EntityLight> kitWorldLight;
bool kitWorldDone = false;
// ApplySpellVisualKit calls made before the model loaded: {kit, oneShot}.
std::vector<std::pair<uint32_t, bool>> pendingKits;
+55 -7
View File
@@ -214,6 +214,16 @@ void __fastcall OnAnimDone(void *model, uint32_t keyBone, uint32_t animID, uint3
M2::PlayAnimation(model, static_cast<int>(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<Actor *>(static_cast<uintptr_t>(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<uint32_t>(kit, Offsets::OFF_SPELLVISUALKIT_WORLD_EFFECT));
if (effect == nullptr)
return;
void *frame = actor.SceneFrame();
void *planted =
M2::CreateModel(Model::Pane::Scene(frame), Game::Read<const char *>(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<const void *>(&OnKitWorldDone),
static_cast<uint32_t>(reinterpret_cast<uintptr_t>(&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);
+12 -5
View File
@@ -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<void *>(static_cast<uintptr_t>(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