From f4862dc8173763dbffed52fbaaebd862f3ff6f2e Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Thu, 29 Oct 2026 23:00:58 -0500 Subject: [PATCH] docs(equipmentset): describe the C_EquipmentSet functions Descriptors for the 18 undocumented C_EquipmentSet functions, GameTooltip:SetEquipmentSet, and the EQUIPMENT_SETS_CHANGED, EQUIPMENT_SWAP_PENDING and EQUIPMENT_SWAP_FINISHED events. They describe what the functions return here, which differs from retail in places: an icon path, not a file ID; numMissing, not numLost; GetIgnoredSlots lists slot numbers. --- src/equipmentset/Api.cpp | 170 +++++++++++++++++++++++++++++++---- src/equipmentset/Set.h | 28 +++++- src/equipmentset/Tooltip.cpp | 13 ++- 3 files changed, 189 insertions(+), 22 deletions(-) diff --git a/src/equipmentset/Api.cpp b/src/equipmentset/Api.cpp index 4e2851e6..46637f70 100644 --- a/src/equipmentset/Api.cpp +++ b/src/equipmentset/Api.cpp @@ -543,46 +543,180 @@ int __fastcall Script_UseEquipmentSet(void *L) { return 1; } +const Game::Doc::Field kSetIDArgs[] = { + Game::Doc::Req("setID", "number"), +}; +const Game::Doc::Field kSlotArgs[] = { + Game::Doc::Req("slot", "luaIndex", "An equipment slot, from 1 to 19."), +}; + +const Game::Doc::Field kCanUseRets[] = { + Game::Doc::Req("canUseEquipmentSets", "bool", "False while a set swap is in progress."), +}; +const Game::Doc::Function kCanUseEquipmentSets{ + "Returns whether an equipment set can be used now.", {}, kCanUseRets}; + +const Game::Doc::Field kNumRets[] = { + Game::Doc::Req("numEquipmentSets", "number"), +}; +const Game::Doc::Function kGetNumEquipmentSets{ + "Returns the number of equipment sets the character has.", {}, kNumRets}; + +const Game::Doc::Field kIDsRets[] = { + Game::Doc::Req("setIDs", "table", "The set IDs in the order the sets were created."), +}; +const Game::Doc::Function kGetEquipmentSetIDs{ + "Returns the IDs of all the character's equipment sets.", {}, kIDsRets}; + +const Game::Doc::Field kIDArgs[] = { + Game::Doc::Req("name", "cstring", "The exact name; case matters."), +}; +const Game::Doc::Field kIDRets[] = { + Game::Doc::Opt("setID", "number", nullptr, "Nil when no set has that name."), +}; +const Game::Doc::Function kGetEquipmentSetID{ + "Returns the ID of the equipment set with a name.", kIDArgs, kIDRets}; + +const Game::Doc::Field kInfoRets[] = { + Game::Doc::Opt("name", "string", nullptr, + "Nil, with the rest, when the set does not exist."), + Game::Doc::Opt("icon", "string", nullptr, "The icon's texture name."), + Game::Doc::Opt("setID", "number"), + Game::Doc::Opt("isEquipped", "bool", nullptr, + "True when every slot that is not ignored holds what the set saved."), + Game::Doc::Opt("numItems", "number", nullptr, + "numEquipped plus numInInventory plus numMissing."), + Game::Doc::Opt("numEquipped", "number"), + Game::Doc::Opt("numInInventory", "number", nullptr, + "In the bags, or in the bank while the bank is open."), + Game::Doc::Opt("numMissing", "number"), + Game::Doc::Opt("numIgnored", "number"), +}; +const Game::Doc::Function kGetEquipmentSetInfo{ + "Returns an equipment set's name, icon, and where its items are.", kSetIDArgs, + kInfoRets}; + +const Game::Doc::Field kIgnoredRets[] = { + Game::Doc::Opt("ignoredSlots", "table", nullptr, + "The numbers of the ignored slots; nil when the set does not exist."), +}; +const Game::Doc::Function kGetIgnoredSlots{ + "Returns the slots an equipment set leaves alone.", kSetIDArgs, kIgnoredRets}; + +const Game::Doc::Field kItemIDsRets[] = { + Game::Doc::Opt("itemIDs", "table", nullptr, + "Keyed by slot: the item ID, 0 for an empty slot, 1 for an ignored slot, " + "or -1 when not known."), +}; +const Game::Doc::Function kGetItemIDs{ + "Returns the item ID an equipment set saved for each slot.", kSetIDArgs, kItemIDsRets}; + +const Game::Doc::Field kLocationsRets[] = { + Game::Doc::Opt("locations", "table", nullptr, + "Keyed by slot: a packed location, 0 for an empty slot, 1 for an ignored " + "slot, or -1 for a missing item."), +}; +const Game::Doc::Function kGetItemLocations{ + "Returns where each item of an equipment set is now.", kSetIDArgs, kLocationsRets}; + +const Game::Doc::Field kCreateArgs[] = { + Game::Doc::Req("name", "cstring", "Shorter than 32 characters, with no line break."), + Game::Doc::Opt("icon", "string", "\"INV_Misc_QuestionMark\"", "A texture name."), +}; +const Game::Doc::Field kCreateRets[] = { + Game::Doc::Opt("setID", "number", nullptr, "Nil when the name is already in use."), +}; +const Game::Doc::Function kCreateEquipmentSet{ + "Saves the equipped items as a new equipment set.", kCreateArgs, kCreateRets}; + +const Game::Doc::Field kSaveArgs[] = { + Game::Doc::Req("setID", "number"), + Game::Doc::Opt("icon", "string", nullptr, "A new texture name; nil keeps the icon."), +}; +const Game::Doc::Function kSaveEquipmentSet{ + "Saves the equipped items into an existing equipment set.", kSaveArgs, {}}; + +const Game::Doc::Field kModifyArgs[] = { + Game::Doc::Req("setID", "number"), + Game::Doc::Req("newName", "cstring"), +}; +const Game::Doc::Function kModifyEquipmentSet{ + "Renames an equipment set; does nothing when another set has the name.", kModifyArgs, + {}}; + +const Game::Doc::Function kDeleteEquipmentSet{ + "Deletes an equipment set and removes it from the action bars.", kSetIDArgs, {}}; + +const Game::Doc::Function kIgnoreSlotForSave{ + "Makes the next save of an equipment set leave a slot alone.", kSlotArgs, {}}; +const Game::Doc::Function kUnignoreSlotForSave{ + "Makes the next save of an equipment set include a slot again.", kSlotArgs, {}}; + +const Game::Doc::Field kIsIgnoredRets[] = { + Game::Doc::Req("isSlotIgnored", "bool"), +}; +const Game::Doc::Function kIsSlotIgnoredForSave{ + "Returns whether the next save of an equipment set leaves a slot alone.", kSlotArgs, + kIsIgnoredRets}; +const Game::Doc::Function kClearIgnoredSlotsForSave{ + "Makes the next save of an equipment set include every slot.", {}, {}}; + +const Game::Doc::Field kLockedRets[] = { + Game::Doc::Opt("hasLockedItems", "bool", nullptr, "Nil when the set does not exist."), +}; +const Game::Doc::Function kEquipmentSetContainsLockedItems{ + "Returns whether an item of an equipment set is locked by a move in progress.", + kSetIDArgs, kLockedRets}; + +const Game::Doc::Field kUseRets[] = { + Game::Doc::Req("setWasEquipped", "bool", + "True when the swap starts; EQUIPMENT_SWAP_FINISHED gives the result."), +}; +const Game::Doc::Function kUseEquipmentSet{ + "Equips the items of an equipment set.", kSetIDArgs, kUseRets}; + } // namespace static void RegisterLuaFunctions() { Game::Lua::RegisterTableFunction("C_EquipmentSet", "CanUseEquipmentSets", - &Script_CanUseEquipmentSets); + &Script_CanUseEquipmentSets, &kCanUseEquipmentSets); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetNumEquipmentSets", - &Script_GetNumEquipmentSets); + &Script_GetNumEquipmentSets, &kGetNumEquipmentSets); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetEquipmentSetIDs", - &Script_GetEquipmentSetIDs); + &Script_GetEquipmentSetIDs, &kGetEquipmentSetIDs); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetEquipmentSetID", - &Script_GetEquipmentSetID); + &Script_GetEquipmentSetID, &kGetEquipmentSetID); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetEquipmentSetInfo", - &Script_GetEquipmentSetInfo); + &Script_GetEquipmentSetInfo, &kGetEquipmentSetInfo); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetIgnoredSlots", - &Script_GetIgnoredSlots); + &Script_GetIgnoredSlots, &kGetIgnoredSlots); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetItemIDs", - &Script_GetItemIDs); + &Script_GetItemIDs, &kGetItemIDs); Game::Lua::RegisterTableFunction("C_EquipmentSet", "GetItemLocations", - &Script_GetItemLocations); + &Script_GetItemLocations, &kGetItemLocations); Game::Lua::RegisterTableFunction("C_EquipmentSet", "CreateEquipmentSet", - &Script_CreateEquipmentSet); + &Script_CreateEquipmentSet, &kCreateEquipmentSet); Game::Lua::RegisterTableFunction("C_EquipmentSet", "SaveEquipmentSet", - &Script_SaveEquipmentSet); + &Script_SaveEquipmentSet, &kSaveEquipmentSet); Game::Lua::RegisterTableFunction("C_EquipmentSet", "ModifyEquipmentSet", - &Script_ModifyEquipmentSet); + &Script_ModifyEquipmentSet, &kModifyEquipmentSet); Game::Lua::RegisterTableFunction("C_EquipmentSet", "DeleteEquipmentSet", - &Script_DeleteEquipmentSet); + &Script_DeleteEquipmentSet, &kDeleteEquipmentSet); Game::Lua::RegisterTableFunction("C_EquipmentSet", "IgnoreSlotForSave", - &Script_IgnoreSlotForSave); + &Script_IgnoreSlotForSave, &kIgnoreSlotForSave); Game::Lua::RegisterTableFunction("C_EquipmentSet", "UnignoreSlotForSave", - &Script_UnignoreSlotForSave); + &Script_UnignoreSlotForSave, &kUnignoreSlotForSave); Game::Lua::RegisterTableFunction("C_EquipmentSet", "IsSlotIgnoredForSave", - &Script_IsSlotIgnoredForSave); + &Script_IsSlotIgnoredForSave, &kIsSlotIgnoredForSave); Game::Lua::RegisterTableFunction("C_EquipmentSet", "ClearIgnoredSlotsForSave", - &Script_ClearIgnoredSlotsForSave); + &Script_ClearIgnoredSlotsForSave, + &kClearIgnoredSlotsForSave); Game::Lua::RegisterTableFunction("C_EquipmentSet", "EquipmentSetContainsLockedItems", - &Script_EquipmentSetContainsLockedItems); + &Script_EquipmentSetContainsLockedItems, + &kEquipmentSetContainsLockedItems); Game::Lua::RegisterTableFunction("C_EquipmentSet", "UseEquipmentSet", - &Script_UseEquipmentSet); + &Script_UseEquipmentSet, &kUseEquipmentSet); } static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; diff --git a/src/equipmentset/Set.h b/src/equipmentset/Set.h index 37d248f9..c3b1bcb8 100644 --- a/src/equipmentset/Set.h +++ b/src/equipmentset/Set.h @@ -151,8 +151,30 @@ constexpr int LOC_IGNORED = 1; // when the swap settles — see // `EquipmentSet::Pending`. `success` is // 1 or nil, never 0 (a Lua 0 is true). -inline const Event::Custom::AutoReserve kEvtSetsChanged{"EQUIPMENT_SETS_CHANGED"}; -inline const Event::Custom::AutoReserve kEvtSwapPending{"EQUIPMENT_SWAP_PENDING"}; -inline const Event::Custom::AutoReserve kEvtSwapFinished{"EQUIPMENT_SWAP_FINISHED"}; +inline const Game::Doc::Event kSetsChangedDoc{ + "EquipmentSet", + "Fires when an equipment set is created, saved, renamed, or deleted, or when the slots " + "ignored for the next save change.", + {}}; +inline const Game::Doc::Field kSwapPendingPayload[] = { + Game::Doc::Req("setID", "number"), +}; +inline const Game::Doc::Event kSwapPendingDoc{ + "EquipmentSet", "Fires when C_EquipmentSet.UseEquipmentSet has sent all its moves.", + kSwapPendingPayload}; +inline const Game::Doc::Field kSwapFinishedPayload[] = { + Game::Doc::Opt("result", "number", nullptr, "1 when the swap succeeded, else nil."), + Game::Doc::Req("setID", "number"), +}; +inline const Game::Doc::Event kSwapFinishedDoc{ + "EquipmentSet", "Fires when the moves of an equipment set swap are done.", + kSwapFinishedPayload}; + +inline const Event::Custom::AutoReserve kEvtSetsChanged{"EQUIPMENT_SETS_CHANGED", + &kSetsChangedDoc}; +inline const Event::Custom::AutoReserve kEvtSwapPending{"EQUIPMENT_SWAP_PENDING", + &kSwapPendingDoc}; +inline const Event::Custom::AutoReserve kEvtSwapFinished{"EQUIPMENT_SWAP_FINISHED", + &kSwapFinishedDoc}; } // namespace EquipmentSet diff --git a/src/equipmentset/Tooltip.cpp b/src/equipmentset/Tooltip.cpp index 1d4a4e21..94d4bb5c 100644 --- a/src/equipmentset/Tooltip.cpp +++ b/src/equipmentset/Tooltip.cpp @@ -218,6 +218,16 @@ const Game::Lua::FrameMethodEntry g_methods[] = { {"SetEquipmentSet", &Script_GameTooltipSetEquipmentSet}, }; +const Game::Doc::Field kSetEquipmentSetArgs[] = { + Game::Doc::Req("name", "cstring", "The name of the equipment set."), +}; +const Game::Doc::Function kSetEquipmentSet{ + "Shows an equipment set in the tooltip: its name and where its items are.", + kSetEquipmentSetArgs, {}}; +const Game::Doc::Method g_methodDocs[] = { + {"SetEquipmentSet", &kSetEquipmentSet}, +}; + } // namespace static void RegisterLuaFunctions() { @@ -226,7 +236,8 @@ static void RegisterLuaFunctions() { Game::Lua::RegisterFrameMethods( reinterpret_cast(Offsets::VAR_GAMETOOLTIP_METHOD_REGISTRY), g_methods, - static_cast(sizeof(g_methods) / sizeof(g_methods[0]))); + static_cast(sizeof(g_methods) / sizeof(g_methods[0])), g_methodDocs, + static_cast(sizeof(g_methodDocs) / sizeof(g_methodDocs[0]))); } static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};