From d53e15ff45a4a2c1aceddadc4bfa09c42b207e8a Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Sat, 7 Nov 2026 18:53:36 -0600 Subject: [PATCH] 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. --- README.md | 2 +- docs/API.md | 15 +++++++++++++++ src/model/Scene.h | 3 +++ src/model/SceneActor.cpp | 36 ++++++++++++++++++++++++++++++++++++ 4 files changed, 55 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6983c946..dec37037 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th | [Frame: Slider](docs/API.md#sliderenable--sliderdisable--sliderisenabled) | `:Enable` / `:Disable` / `:IsEnabled` | | [Frame: Cooldown](docs/API.md#createframecooldown--name-parent-template) | `CreateFrame("Cooldown")`, `:SetCooldown`, `:SetCooldownDuration`, `:SetCooldownFromExpirationTime`, `:Clear`, `:GetCooldownTimes`, `:GetCooldownDuration`, `:GetCooldownDisplayDuration`, `:Pause` / `:Resume`, `:SetPaused` / `:IsPaused`, `:SetReverse` / `:GetReverse`, `:SetDrawEdge` / `:GetDrawEdge`, `:SetDrawSwipe` / `:GetDrawSwipe`, `:SetDrawBling` / `:GetDrawBling`, `:SetSwipeColor`, `:SetEdgeColor`, `:SetSwipeTexture`, `:SetEdgeTexture`, `:SetBlingTexture`, `:SetRotation` / `:GetRotation`, `:SetHideCountdownNumbers` / `:GetHideCountdownNumbers`, `:GetCountdownFontString`, `:SetCountdownAbbrevThreshold` / `:GetCountdownAbbrevThreshold`, `:SetCountdownMillisecondsThreshold` / `:GetCountdownMillisecondsThreshold`, `:SetMinimumCountdownDuration` / `:GetMinimumCountdownDuration`, `OnCooldownDone`, `CooldownFrame_Set`, `CooldownFrame_Clear`, `CooldownFrame_SetDisplayAsPercentage` | | [Frame: ModelScene](docs/API.md#modelscene) | `CreateFrame("ModelScene")`, `` (`drawLayer`, `fogNear`, `fogFar`, ``, ``), `:CreateActor`, `:GetNumActors`, `:GetActorAtIndex`, `:SetCameraPosition` / `:GetCameraPosition`, `:SetCameraOrientationByYawPitchRoll`, `:SetCameraOrientationByAxisVectors`, `:GetCameraForward`, `:GetCameraRight`, `:GetCameraUp`, `:SetCameraFieldOfView` / `:GetCameraFieldOfView`, `:SetCameraNearClip` / `:GetCameraNearClip`, `:SetCameraFarClip` / `:GetCameraFarClip`, `:SetViewInsets` / `:GetViewInsets`, `:SetViewTranslation` / `:GetViewTranslation`, `:Project3DPointTo2D`, `:SetLightType` / `:GetLightType`, `:SetLightVisible` / `:IsLightVisible`, `:SetLightDirection` / `:GetLightDirection`, `:SetLightPosition` / `:GetLightPosition`, `:SetLightAmbientColor` / `:GetLightAmbientColor`, `:SetLightDiffuseColor` / `:GetLightDiffuseColor`, `:SetFogColor` / `:GetFogColor`, `:SetFogNear` / `:GetFogNear`, `:SetFogFar` / `:GetFogFar`, `:ClearFog`, `:SetDrawLayer` / `:GetDrawLayer`, `:SetPaused`, `:SetAllowOverlappedModels` / `:GetAllowOverlappedModels`, `:SetGroundTerrain` / `:GetGroundTerrain` | -| [Frame: ModelSceneActor](docs/API.md#actorsetmodelbycreaturedisplayiddisplayid--useactiveplayercustomizations) | `:SetModelByCreatureDisplayID`, `:SetModelByPath`, `:SetModelByUnit`, `:SetModelByUnitCreatureDisplayID`, `:GetModelUnitGUID`, `:Dress`, `:Undress`, `:UndressSlot`, `:TryOn`, `:DressPlayerSlot`, `:IsSlotAllowed` / `:IsSlotVisible`, `:GetItemTransmogInfo`, `:GetItemTransmogInfoList`, `:SetItemTransmogInfo`, `:SetSheathed` / `:GetSheathed`, `:SetSheathedCategory`, `:UseUnitSheatheCategory`, `:SetAutoDress` / `:GetAutoDress`, `:IsGeoReady`, `:ClearModel`, `:IsLoaded`, `:GetModelPath`, `:SetPosition` / `:GetPosition`, `:SetYaw` / `:GetYaw`, `:SetPitch` / `:GetPitch`, `:SetRoll` / `:GetRoll`, `:SetScale` / `:GetScale`, `:SetUseCenterForOrigin` / `:IsUsingCenterForOrigin`, `:GetActiveBoundingBox`, `:GetMaxBoundingBox`, `:Show` / `:Hide` / `:SetShown` / `:IsShown` / `:IsVisible`, `:SetAlpha` / `:GetAlpha`, `:SetAnimation` / `:GetAnimation`, `:GetAnimationVariation`, `:SetAnimationBlendOperation` / `:GetAnimationBlendOperation`, `:SetPaused` / `:GetPaused`, `:SetSpellVisualKit` / `:GetSpellVisualKit`, `:PlayAnimationKit` / `:StopAnimationKit`, `:AttachToMount`, `:DetachFromMount`, `:CalculateMountScale`, `:GetAttachmentPosition`, `:AttachToActor`, `:DetachFromActor`, `:PlaySpellVisual`, `:SetPlayAnimationSounds` / `:GetPlayAnimationSounds`, `OnLoad`, `OnUpdate`, `OnModelLoading`, `OnModelLoaded`, `OnModelCleared`, `OnAnimFinished`, `` templates | +| [Frame: ModelSceneActor](docs/API.md#actorsetmodelbycreaturedisplayiddisplayid--useactiveplayercustomizations) | `:SetModelByCreatureDisplayID`, `:SetModelByPath`, `:SetModelByUnit`, `:SetModelByUnitCreatureDisplayID`, `:GetModelUnitGUID`, `:Dress`, `:Undress`, `:UndressSlot`, `:TryOn`, `:DressPlayerSlot`, `:IsSlotAllowed` / `:IsSlotVisible`, `:GetItemTransmogInfo`, `:GetItemTransmogInfoList`, `:SetItemTransmogInfo`, `:SetSheathed` / `:GetSheathed`, `:SetSheathedCategory`, `:UseUnitSheatheCategory`, `:SetAutoDress` / `:GetAutoDress`, `:IsGeoReady`, `:ClearModel`, `:IsLoaded`, `:GetModelPath`, `:SetPosition` / `:GetPosition`, `:SetYaw` / `:GetYaw`, `:SetPitch` / `:GetPitch`, `:SetRoll` / `:GetRoll`, `:SetScale` / `:GetScale`, `:SetUseCenterForOrigin` / `:IsUsingCenterForOrigin`, `:GetActiveBoundingBox`, `:GetMaxBoundingBox`, `:Show` / `:Hide` / `:SetShown` / `:IsShown` / `:IsVisible`, `:SetAlpha` / `:GetAlpha`, `:SetAnimation` / `:GetAnimation`, `:GetAnimationVariation`, `:SetAnimationBlendOperation` / `:GetAnimationBlendOperation`, `:SetPaused` / `:GetPaused`, `:SetSpellVisualKit` / `:GetSpellVisualKit`, `:ApplySpellVisualKit`, `:PlayAnimationKit` / `:StopAnimationKit`, `:AttachToMount`, `:DetachFromMount`, `:CalculateMountScale`, `:GetAttachmentPosition`, `:AttachToActor`, `:DetachFromActor`, `:PlaySpellVisual`, `:SetPlayAnimationSounds` / `:GetPlayAnimationSounds`, `OnLoad`, `OnUpdate`, `OnModelLoading`, `OnModelLoaded`, `OnModelCleared`, `OnAnimFinished`, `` templates | | [Frame: ScrollingMessageFrame](docs/API.md#smfsethyperlinksenabledenabled--smfgethyperlinksenabled) | `:SetHyperlinksEnabled` / `:GetHyperlinksEnabled`, `:GetMessageInfo` (with the extra `:AddMessage` values), `:BackFillMessage` (adds a message as the oldest), `:RemoveMessagesByPredicate`, `:SetScrollOffset` / `:GetScrollOffset`, `:GetMaxScrollRange`, `:ScrollByAmount`, `:SetInsertMode` / `:GetInsertMode`, `:AddOnDisplayRefreshedCallback` | | [Frame: scripts](docs/API.md#onenable-and-ondisable-scripts) | `OnEnable`, `OnDisable`, `OnMinMaxChanged`, `OnAttributeChanged`, `OnCharComposition`, `OnTextChanged` (`userInput`), `PreClick`, `PostClick`, `SetModernScriptArgs` / `GetModernScriptArgs` | | [FriendList](docs/API.md#friendlist) | `AddOrRemoveFriend`, `C_FriendList.GetFriendInfo`, `C_FriendList.GetFriendInfoByIndex`, `C_FriendList.GetNumFriends`, `C_FriendList.GetNumOnlineFriends`, `C_FriendList.GetNumWhoResults`, `C_FriendList.GetWhoInfo`, `C_FriendList.IsFriend`, `C_FriendList.IsIgnored`, `C_FriendList.IsIgnoredByGuid`, `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName`, `C_FriendList.SetFriendNotes`, `C_FriendList.SetFriendNotesByIndex` | diff --git a/docs/API.md b/docs/API.md index 610faeea..bbbd3351 100644 --- a/docs/API.md +++ b/docs/API.md @@ -869,6 +869,7 @@ build instructions. - [`actor:SetAnimationBlendOperation(blendOperation)` / `actor:GetAnimationBlendOperation()`](#actorsetanimationblendoperationblendoperation--actorgetanimationblendoperation) - [`actor:SetPaused(paused [, affectsGlobalPause])` / `actor:GetPaused()`](#actorsetpausedpaused--affectsglobalpause--actorgetpaused) - [`actor:SetSpellVisualKit([spellVisualKitID, oneShot])` / `actor:GetSpellVisualKit()`](#actorsetspellvisualkitspellvisualkitid-oneshot--actorgetspellvisualkit) + - [`actor:ApplySpellVisualKit(spellVisualKitID [, oneShot])`](#actorapplyspellvisualkitspellvisualkitid--oneshot) - [`actor:PlayAnimationKit(animationKit [, isLooping])` / `actor:StopAnimationKit()`](#actorplayanimationkitanimationkit--islooping--actorstopanimationkit) - [`actor:AttachToMount(rider, animation [, spellKitVisualID])`](#actorattachtomountrider-animation--spellkitvisualid) - [`actor:DetachFromMount(rider)`](#actordetachfrommountrider) @@ -19599,6 +19600,20 @@ caster:SetSpellVisualKit(38, true) -- Fireball cast target:SetSpellVisualKit(286, true) -- Fireball impact ``` +### `actor:ApplySpellVisualKit(spellVisualKitID [, oneShot])` + +Adds the effects of a spell visual kit to the model. The kits that the model +already shows stay: those of `SetSpellVisualKit`, of `PlaySpellVisual`, and +of earlier calls of this method. With `oneShot` set to `true`, each effect +plays one time. Without it, the effects stay until the model changes. As +with `SetSpellVisualKit`, the kit does not play its animation or its sound. +If the model has not loaded, the kit shows when it loads. This is a +ClassicAPI extension. + +```lua +target:ApplySpellVisualKit(286, true) -- a Fireball impact, the old kit stays +``` + ### `actor:PlayAnimationKit(animationKit [, isLooping])` / `actor:StopAnimationKit()` These have no effect. There are no animation kits in this game. diff --git a/src/model/Scene.h b/src/model/Scene.h index e54543ab..a1d99eab 100644 --- a/src/model/Scene.h +++ b/src/model/Scene.h @@ -19,6 +19,7 @@ #include #include +#include #include // The ModelScene frame (model/Scene.cpp) and its actors (model/SceneActor.cpp). @@ -146,6 +147,8 @@ class Actor : public Animation::Object { uint32_t spellVisualKit = 0; bool spellVisualKitOneShot = false; std::vector kitEffects; // the kit's effect models, one reference each + // ApplySpellVisualKit calls made before the model loaded: {kit, oneShot}. + std::vector> pendingKits; // A spell kit's animation, shown in place of `animation` (-1 none): a // precast's loops, a cast's or an impact's plays once. diff --git a/src/model/SceneActor.cpp b/src/model/SceneActor.cpp index cf3a3f88..b1a1c493 100644 --- a/src/model/SceneActor.cpp +++ b/src/model/SceneActor.cpp @@ -242,6 +242,7 @@ void ReleaseModel(Actor &actor) { slot = Outfit::Appearance{}; actor.armorReady = true; actor.pendingTryOns.clear(); + actor.pendingKits.clear(); actor.loaded = false; actor.animFinished = false; actor.kitAnimation = -1; @@ -533,6 +534,10 @@ void Actor::Update(float elapsedSec) { loaded = true; PutOnWaiting(*this); ApplyKit(*this); + for (const auto &[kitID, oneShot] : pendingKits) + if (const uint8_t *kit = Model::VisualKit::Record(kitID)) + Model::VisualKit::Apply(SceneFrame(), model, kit, oneShot); + pendingKits.clear(); RunScript(S_ONMODELLOADED, 0); } } else { @@ -1064,6 +1069,27 @@ int __fastcall Script_PlaySpellVisual(void *L) { return 1; } +// Retail PlayerModel's ApplySpellVisualKit on the actor: the kit joins the +// ones shown (Model::VisualKit::Apply, the model owning the effects), where +// SetSpellVisualKit replaces the actor's one kit. Applied once the model has +// loaded, as SetSpellVisualKit's. +int __fastcall Script_ApplySpellVisualKit(void *L) { + Actor *actor = Self(L); + if (actor == nullptr || !NumberArgs(L, 2, 1, actor->DisplayName(), + "ApplySpellVisualKit(spellVisualKitID [, oneShot])")) + return 0; + const auto kitID = static_cast(Game::Lua::ToNumber(L, 2)); + const bool oneShot = Game::Lua::ToBoolean(L, 3) != 0; + const uint8_t *kit = Model::VisualKit::Record(kitID); + if (kit == nullptr || actor->model == nullptr) + return 0; + if (actor->loaded) + Model::VisualKit::Apply(actor->SceneFrame(), actor->model, kit, oneShot); + else + actor->pendingKits.emplace_back(kitID, oneShot); + return 0; +} + int __fastcall Script_SetPlayAnimationSounds(void *L) { if (Actor *actor = Self(L)) actor->playAnimationSounds = Game::Lua::ToBoolean(L, 2) != 0; @@ -1376,6 +1402,7 @@ const Game::Lua::FrameMethodEntry kMethods[] = { {"AttachToActor", &Script_AttachToActor}, {"DetachFromActor", &Script_DetachFromActor}, {"PlaySpellVisual", &Script_PlaySpellVisual}, + {"ApplySpellVisualKit", &Script_ApplySpellVisualKit}, {"SetPlayAnimationSounds", &Script_SetPlayAnimationSounds}, {"GetPlayAnimationSounds", &Script_GetPlayAnimationSounds}, {"ClearModel", &Script_ClearModel}, @@ -1659,6 +1686,14 @@ const Game::Doc::Function kPlaySpellVisual{ "the missile and the impact, with their animations and sounds. False when the spell has no " "visual or this actor shows no model.", kPlaySpellVisualArgs, kMountSuccessRet, nullptr, true}; +const Game::Doc::Field kApplySpellVisualKitArgs[] = { + Req("spellVisualKitID", "number", "A SpellVisualKit ID."), + Opt("oneShot", "bool", "false", + "True plays the effects once; false keeps them until the model changes."), +}; +const Game::Doc::Function kApplySpellVisualKit{ + "Adds a spell visual kit's effects to the model, next to the kits it already shows.", + kApplySpellVisualKitArgs, {}, nullptr, true}; const Game::Doc::Field kAnimationSoundsArg[] = {Req("enabled", "bool")}; const Game::Doc::Function kSetPlayAnimationSounds{ "Sets whether the model's animations play their sounds, as a unit's do in the world: fidgets, " @@ -1745,6 +1780,7 @@ const Game::Doc::Method kMethodDocs[] = { {"AttachToActor", &kAttachToActor}, {"DetachFromActor", &kDetachFromActor}, {"PlaySpellVisual", &kPlaySpellVisual}, + {"ApplySpellVisualKit", &kApplySpellVisualKit}, {"SetPlayAnimationSounds", &kSetPlayAnimationSounds}, {"GetPlayAnimationSounds", &kGetPlayAnimationSounds}, {"ClearModel", &kClearModel},