diff --git a/README.md b/README.md index deedd175..5079e95c 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th | [Map](docs/API.md#map) | `C_Map.CanSetUserWaypointOnMap`, `C_Map.ClearUserWaypoint`, `C_Map.GetAreaInfo`, `C_Map.GetAreas`, `C_Map.GetAreaTriggerInfo`, `C_Map.GetAreaTriggers`, `C_Map.GetBestMapForUnit`, `C_Map.GetFallbackWorldMapID`, `C_Map.GetMapAreaIDs`, `C_Map.GetMapArtLayers`, `C_Map.GetMapArtLayerTextures`, `C_Map.GetMapChildrenInfo`, `C_Map.GetMapInfo`, `C_Map.GetMapInfoAtPosition`, `C_Map.GetMapOverlays`, `C_Map.GetMapPosFromWorldPos`, `C_Map.GetMapRectOnMap`, `C_Map.GetMapWorldSize`, `C_Map.GetPlayerMapPosition`, `C_Map.GetUserWaypoint`, `C_Map.GetUserWaypointFromHyperlink`, `C_Map.GetUserWaypointHyperlink`, `C_Map.GetUserWaypointPositionForMap`, `C_Map.GetWorldPosFromMapPos`, `C_Map.HasUserWaypoint`, `C_Map.MapHasArt`, `C_Map.SetUserWaypoint` | | [MapExplorationInfo](docs/API.md#mapexplorationinfo) | `C_MapExplorationInfo.GetExploredAreaIDsAtPosition`, `C_MapExplorationInfo.GetExploredMapTextures`, `C_MapExplorationInfo.GetUnexploredMapTextures` | | [MerchantFrame](docs/API.md#merchantframe) | `C_MerchantFrame.GetBuybackItemID`, `C_MerchantFrame.GetItemInfo`, `C_MerchantFrame.GetNumJunkItems`, `C_MerchantFrame.IsMerchantItemRefundable`, `C_MerchantFrame.IsSellAllJunkEnabled`, `C_MerchantFrame.SellAllJunkItems`, `GetBuybackItemLink` | -| [Model](docs/API.md#model) | `DressUpModel:TryOn` (links, recipes, names, hand, enchant glow, result), `DressUpModel:UndressSlot`, `DressUpModel:IsGeoReady`, `DressUpModel:SetSheathed` / `GetSheathed`, `DressUpModel:SetAutoDress` / `GetAutoDress`, `Model:SetGlow`, `PlayerModel:RefreshCamera`, `PlayerModel:SetCamDistanceScale`, `PlayerModel:SetCreature` (`displayID`), `PlayerModel:SetDisplayInfo`, `PlayerModel:SetItem`, `PlayerModel:SetPortraitZoom`, `PlayerModel:SetRotation` (`animate`), `PlayerModel:SetUnit` (result), `PlayerModel:CanSetUnit`, `PlayerModel:GetDisplayInfo`, `PlayerModel:SetAnimation`, `PlayerModel:FreezeAnimation`, `PlayerModel:HasAnimation`, `PlayerModel:SetDoBlend` / `GetDoBlend`, `PlayerModel:SetKeepModelOnHide` / `GetKeepModelOnHide` | +| [Model](docs/API.md#model) | `DressUpModel:TryOn` (links, recipes, names, hand, enchant glow, result), `DressUpModel:UndressSlot`, `DressUpModel:IsGeoReady`, `DressUpModel:SetSheathed` / `GetSheathed`, `DressUpModel:SetAutoDress` / `GetAutoDress`, `Model:SetGlow`, `PlayerModel:RefreshCamera`, `PlayerModel:SetCamDistanceScale`, `PlayerModel:SetCreature` (`displayID`), `PlayerModel:SetDisplayInfo`, `PlayerModel:SetItem`, `PlayerModel:SetPortraitZoom`, `PlayerModel:SetRotation` (`animate`), `PlayerModel:SetUnit` (result), `PlayerModel:CanSetUnit`, `PlayerModel:GetDisplayInfo`, `PlayerModel:SetAnimation`, `PlayerModel:FreezeAnimation`, `PlayerModel:HasAnimation`, `PlayerModel:SetDoBlend` / `GetDoBlend`, `PlayerModel:SetKeepModelOnHide` / `GetKeepModelOnHide`, `PlayerModel:ApplySpellVisualKit` | | [NamePlate](docs/API.md#nameplate) | `C_NamePlate.GetNamePlateForGUID`, `C_NamePlate.GetNamePlateForUnit`, `C_NamePlate.GetNamePlateGUIDs`, `C_NamePlate.GetNamePlates` | | [NameCache](docs/API.md#namecache) | `C_PlayerCache.GetPlayerInfoByName`, `C_PlayerCache.IsEnabled`, `C_PlayerCache.RememberPlayer`, `C_PlayerCache.SetEnabled`, `GetPlayerInfoByGUID`, `UnitNameFromGUID` | | [NewItems](docs/API.md#newitems) | `C_NewItems.ClearAll`, `C_NewItems.IsNewItem`, `C_NewItems.RemoveNewItem` | diff --git a/docs/API.md b/docs/API.md index a402ff51..662e0d77 100644 --- a/docs/API.md +++ b/docs/API.md @@ -796,6 +796,7 @@ build instructions. - [`model:GetDoBlend()`](#modelgetdoblend) - [`model:SetKeepModelOnHide(keepModelOnHide)`](#modelsetkeepmodelonhidekeepmodelonhide) - [`model:GetKeepModelOnHide()`](#modelgetkeepmodelonhide) + - [`model:ApplySpellVisualKit(spellVisualKitID [, oneShot])`](#modelapplyspellvisualkitspellvisualkitid--oneshot) - [`DressUpModel:UndressSlot(slot)`](#dressupmodelundressslotslot) - [`DressUpModel:TryOn(item [, handSlotName, spellEnchantID])`](#dressupmodeltryonitem--handslotname-spellenchantid) - [`DressUpModel:IsGeoReady()`](#dressupmodelisgeoready) @@ -18736,6 +18737,29 @@ DressUpModel:SetKeepModelOnHide(true) Returns the value that `SetKeepModelOnHide` set. +### `model:ApplySpellVisualKit(spellVisualKitID [, oneShot])` + +Shows the effects of a spell visual kit (a `SpellVisualKit` ID) on the +model, for example the glow on the hands while a spell is cast. Each effect +attaches to its point on the model: head, chest, base, hands, breath, or +weapons. An effect whose point the model does not have does not show. + +If `oneShot` is `true`, each effect plays one time and then fades out. If +`oneShot` is `false` or not given, the effects play again and again until +the model changes. The model changes after `SetUnit`, `SetDisplayInfo`, +`SetCreature`, `SetItem`, and when the frame shows again after it was +hidden. + +A kit can also change the color or the transparency of the model. This +change stays until the model changes. The kit does not play its animation +or its sound. A kit ID that is not in `SpellVisualKit` does nothing. + +```lua +PreviewModel:SetUnit("player") +PreviewModel:ApplySpellVisualKit(99) -- holy glow on both hands +PreviewModel:ApplySpellVisualKit(154, true) -- Holy Light flash, one time +``` + ### `DressUpModel:UndressSlot(slot)` Removes the item in one inventory slot from a `DressUpModel`. `slot` is an diff --git a/src/Offsets.h b/src/Offsets.h index f690b340..343b0723 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -5991,6 +5991,23 @@ enum Offsets { VAR_ITEMVISUALS_RECORDS = 0x00C0DB70, VAR_ITEMVISUALS_COUNT = 0x00C0DB74, + // SpellVisualKit.dbc (35 columns, 0x8C-byte rows). The char-select ghost + // kit (0x004727F0) reads the store at 0x004727F6/0x0047280A: nine effect + // IDs from +0x0C (attachments 20, 34, 19, 21, 22, 17, 23, 24, 25, pushed + // at 0x00472821..0x0047287F), then four procedure kinds from +0x3C with + // their first values from +0x4C (the loop at 0x00472888). Kind 1 is a + // tint, the value an 0xRRGGBB colour stored as a float; kind 14 an alpha. + VAR_SPELLVISUALKIT_RECORDS = 0x00C0D74C, + VAR_SPELLVISUALKIT_COUNT = 0x00C0D750, + OFF_SPELLVISUALKIT_EFFECTS = 0x0C, + OFF_SPELLVISUALKIT_PROC_KIND = 0x3C, + OFF_SPELLVISUALKIT_PROC_VALUE = 0x4C, + // SpellVisualEffectName.dbc: the model file at +0x08, which the ghost + // kit's effect step (0x00472780) creates (0x004727AF). + VAR_SPELLVISUALEFFECTNAME_RECORDS = 0x00C0D760, + VAR_SPELLVISUALEFFECTNAME_COUNT = 0x00C0D764, + OFF_SPELLVISUALEFFECTNAME_FILE = 0x08, + // ItemSet.dbc — armor/equipment set definitions referenced by // `ItemStats_C::m_itemSet`. Standard 5-DWORD class shape at // 0x00C0DBB8 (records-ptr at +0x08, count at +0x0C). 45 columns, @@ -12925,6 +12942,28 @@ enum Offsets { FUN_MODEL_INSTANCE_READY = 0x00710450, // CM2Model::SetVisible — `__thiscall(model, bool)`. FUN_M2MODEL_SET_VISIBLE = 0x00710C50, + // CM2Model::SetAlpha — `__thiscall(model, float)`; SetDiffuseColor — + // `__thiscall(model, const float rgb[3])`. Plain stores, which the + // ghost kit applies (0x004728C1, 0x00472939). Attached children take + // them through the per-frame combine. + FUN_M2MODEL_SET_ALPHA = 0x00710CB0, + FUN_M2MODEL_SET_DIFFUSE_COLOR = 0x00710CF0, + // CM2Model::HasAttachment — `__thiscall(model, id)`, ret 4. Waits for + // the model file (0x00710520) when it has not loaded. + FUN_M2MODEL_HAS_ATTACHMENT = 0x00712CB0, + // CM2Model::Attach — `__thiscall(child, parent, id)`, ret 8. The + // parent takes a reference; the attach index resolves once the parent + // loads. + FUN_M2MODEL_ATTACH = 0x00712F70, + // CM2Model::Detach — `__thiscall(child)`: unlinks the child from its + // parent, clears its parent (OFF_M2MODEL_PARENT) and drops the parent's + // reference. The destructor (0x0070E3F5) detaches every child this way. + FUN_M2MODEL_DETACH = 0x00713020, + OFF_M2MODEL_PARENT = 0x1CC, + // CM2Model::HasLiveParticles — `__thiscall(model)`: +0x3D8, which + // Animate sets while an emitter emits or holds a live particle. The + // dying-effect drain (0x0061F6CC) releases a stopped effect once false. + FUN_M2MODEL_HAS_LIVE_PARTICLES = 0x007135C0, // CM2Model::PlayAnimation — `__thiscall(model, 7 args)`, `ret 0x1C`. The // bake passes (-1, 0, 0, 0, 1.0f, 0, 1). FUN_M2MODEL_PLAY_ANIMATION = 0x007121A0, diff --git a/src/model/VisualKit.cpp b/src/model/VisualKit.cpp new file mode 100644 index 00000000..ae8c2caa --- /dev/null +++ b/src/model/VisualKit.cpp @@ -0,0 +1,235 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +// `PlayerModel:ApplySpellVisualKit(spellVisualKitID [, oneShot])`: a spell's +// visual kit on the pane's model. +// +// The world plays a kit on a unit (0x0060EDF0) through effect objects, spell +// durations and the unit's own animation. 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: a model of the SpellVisualEffectName +// file, made in the pane's scene and attached at the column's attachment +// when the model has it (0x00472780). The children get the frame's light +// like the item glows (Model::DisplayInfo::LightChildren). +// - The procedures the ghost applies: kind 1 sets the tint, kind 14 the +// alpha clamped to 0..1, as plain stores on the model. +// The kit's animation, sound and the world-only procedures are not played, +// as retail does not play them on a model frame either (probed: no cast +// pose, no sound; the tint applies). +// +// oneShot is the world's one-shot kind: CEffect::AddEffect (0x0061FDD0) +// gives the effect model a done callback, and EffectDoneCallback +// (0x005FBF50) stops the effect when the sequence ends cleanly (reason 0). +// CEffect::Stop (0x006203E0) clears the model's callbacks and hides it, so +// its emitters stop and the particles already out finish; each frame the +// 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. +// +// 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 +// stopped effects still on it detaches them first (0x0070E3F5). + +#include "Game.h" +#include "Offsets.h" +#include "dbc/Lookup.h" +#include "model/DisplayInfo.h" +#include "tick/FrameTick.h" + +#include +#include + +namespace Model::VisualKit { +namespace { + +using GetScene_t = void *(__thiscall *)(void *frame); +using CreateModel_t = void *(__thiscall *)(void *scene, const char *path, uint32_t flags); +using ModelFn_t = void(__fastcall *)(void *model); +using HasAttachment_t = int(__thiscall *)(void *model, uint32_t id); +using Attach_t = void(__thiscall *)(void *child, void *parent, uint32_t id); +using SetVisible_t = void(__thiscall *)(void *model, int visible); +using SetAlpha_t = void(__thiscall *)(void *model, float alpha); +using SetDiffuse_t = void(__thiscall *)(void *model, const float *rgb); +using HasLiveParticles_t = int(__thiscall *)(void *model); +using SetAnimDone_t = void(__thiscall *)(void *model, const void *callback, uint32_t userLow, + uint32_t userHigh); +using PlayAnimation_t = void(__thiscall *)(void *model, int keyBone, uint32_t id, int variation, + int offset, float speed, int blend, int primary); + +// The attachment of each effect column, in the ghost kit's order. +constexpr uint32_t kAttachments[] = {20, 34, 19, 21, 22, 17, 23, 24, 25}; +constexpr int kProcedures = 4; +constexpr int32_t kProcTint = 1; +constexpr int32_t kProcAlpha = 14; +// The ghost kit's byte scale (0x008026C8). +constexpr float kByteScale = 1.0f / 255.0f; + +// Stopped one-shot effects, each with one reference of ours. +std::vector g_stopped; + +void Release(void *model) { + reinterpret_cast(Offsets::FUN_MODEL_INSTANCE_RELEASE)(model); +} + +void SetDoneCallback(void *model, const void *callback) { + reinterpret_cast(Offsets::FUN_M2MODEL_SET_ANIM_DONE_CALLBACK)(model, callback, + 0, 0); +} + +// EffectDoneCallback's test, then CEffect::Stop's model steps. +void __fastcall OnEffectDone(void *model, uint32_t /*keyBone*/, uint32_t /*animID*/, + uint32_t reason, uint32_t /*overshoot*/, uint32_t /*userLow*/, + uint32_t /*userHigh*/) { + if (reason != 0) + return; + SetDoneCallback(model, nullptr); + reinterpret_cast(Offsets::FUN_M2MODEL_SET_VISIBLE)(model, 0); + reinterpret_cast(Offsets::FUN_MODEL_INSTANCE_ADDREF)(model); + g_stopped.push_back(model); +} + +// KitEffectLoopCallback: a sequence that ended cleanly plays again. +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; + reinterpret_cast(Offsets::FUN_M2MODEL_PLAY_ANIMATION)(model, -1, animID, -1, + 0, 1.0f, 1, 1); +} + +// Detaches a stopped effect that is still on its model, then drops our +// reference. +void Discard(void *model) { + if (Game::Read(model, Offsets::OFF_M2MODEL_PARENT) != nullptr) + reinterpret_cast(Offsets::FUN_M2MODEL_DETACH)(model); + Release(model); +} + +// The dying-effect drain: a stopped effect goes once its particles are gone, +// or at once when its model has already dropped it. +void Drain() { + for (size_t i = 0; i < g_stopped.size();) { + void *model = g_stopped[i]; + if (Game::Read(model, Offsets::OFF_M2MODEL_PARENT) != nullptr && + reinterpret_cast(Offsets::FUN_M2MODEL_HAS_LIVE_PARTICLES)(model)) { + ++i; + continue; + } + Discard(model); + g_stopped[i] = g_stopped.back(); + g_stopped.pop_back(); + } +} + +const Tick::FrameTick::AutoSubscribe g_drain{&Drain}; + +// The ghost kit's procedure step: kind 1 tints, kind 14 sets the alpha. +void ApplyProcedures(void *model, const uint8_t *kit) { + for (int i = 0; i < kProcedures; ++i) { + const auto kind = Game::Read(kit, Offsets::OFF_SPELLVISUALKIT_PROC_KIND + i * 4); + const float value = Game::Read(kit, Offsets::OFF_SPELLVISUALKIT_PROC_VALUE + i * 4); + if (kind == kProcTint) { + const auto color = static_cast(static_cast(value)); + const float rgb[3] = {static_cast((color >> 16) & 0xFF) * kByteScale, + static_cast((color >> 8) & 0xFF) * kByteScale, + static_cast(color & 0xFF) * kByteScale}; + reinterpret_cast(Offsets::FUN_M2MODEL_SET_DIFFUSE_COLOR)(model, rgb); + } else if (kind == kProcAlpha) { + const float alpha = value < 0.0f ? 0.0f : value > 1.0f ? 1.0f : value; + reinterpret_cast(Offsets::FUN_M2MODEL_SET_ALPHA)(model, alpha); + } + } +} + +void Apply(void *pane, const uint8_t *kit, bool oneShot) { + void *model = Game::Read(pane, Offsets::OFF_SIMPLEMODELFFX_MODEL_INSTANCE); + if (model == nullptr) + return; + void *scene = reinterpret_cast(Offsets::FUN_SIMPLEMODEL_GET_SCENE)(pane); + for (int i = 0; i < static_cast(sizeof(kAttachments) / sizeof(kAttachments[0])); ++i) { + const uint8_t *effect = DBC::Record( + Offsets::VAR_SPELLVISUALEFFECTNAME_RECORDS, Offsets::VAR_SPELLVISUALEFFECTNAME_COUNT, + Game::Read(kit, Offsets::OFF_SPELLVISUALKIT_EFFECTS + i * 4)); + if (effect == nullptr || + !reinterpret_cast(Offsets::FUN_M2MODEL_HAS_ATTACHMENT)( + model, kAttachments[i])) + continue; + void *child = reinterpret_cast(Offsets::FUN_M2SCENE_CREATE_MODEL)( + scene, Game::Read(effect, Offsets::OFF_SPELLVISUALEFFECTNAME_FILE), 0); + if (child == nullptr) + continue; + SetDoneCallback(child, oneShot ? reinterpret_cast(&OnEffectDone) + : reinterpret_cast(&OnEffectLoop)); + reinterpret_cast(Offsets::FUN_M2MODEL_ATTACH)(child, model, kAttachments[i]); + Release(child); + } + Model::DisplayInfo::LightChildren(pane, model); + ApplyProcedures(model, kit); +} + +int __fastcall Script_ApplySpellVisualKit(void *L) { + void *pane = Game::Lua::ResolveTypedObject(L, 1, Offsets::VAR_PLAYERMODEL_LUA_TYPE_ID); + if (pane == nullptr) + return 0; + if (!Game::Lua::IsNumber(L, 2)) { + Game::Lua::Error(L, "Usage: ApplySpellVisualKit(spellVisualKitID [, oneShot])"); + return 0; + } + const uint8_t *kit = + DBC::Record(Offsets::VAR_SPELLVISUALKIT_RECORDS, Offsets::VAR_SPELLVISUALKIT_COUNT, + static_cast(Game::Lua::ToNumber(L, 2))); + if (kit != nullptr) + Apply(pane, kit, Game::Lua::ToBoolean(L, 3) != 0); + return 0; +} + +const Game::Lua::FrameMethodEntry g_methods[] = { + {"ApplySpellVisualKit", &Script_ApplySpellVisualKit}, +}; + +const Game::Doc::Field kApplyArgs[] = { + Game::Doc::Req("spellVisualKitID", "number", "A SpellVisualKit ID."), + Game::Doc::Opt("oneShot", "boolean", "false", + "True plays the effects once; false keeps them until the model changes."), +}; +const Game::Doc::Function kApply{"Shows a spell visual kit's effects on the model.", kApplyArgs, + {}}; +const Game::Doc::Method g_methodDocs[] = { + {"ApplySpellVisualKit", &kApply}, +}; + +void RegisterLuaFunctions() { + Game::Lua::RegisterFrameMethods( + reinterpret_cast(Offsets::VAR_PLAYERMODEL_METHOD_REGISTRY), g_methods, + static_cast(sizeof(g_methods) / sizeof(g_methods[0])), g_methodDocs, + static_cast(sizeof(g_methodDocs) / sizeof(g_methodDocs[0]))); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +// Drop every stopped effect before the reload tears the panes down. +void PrepareForReload() { + for (void *model : g_stopped) + Discard(model); + g_stopped.clear(); +} + +const Game::ReloadAutoRegister _reloadReg{&PrepareForReload}; + +} // namespace +} // namespace Model::VisualKit