diff --git a/README.md b/README.md index fac4bf16..8228eaa1 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**. | Talent | `GetTalentIDByIndex`, `GetTalentSpellID` | | Time | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime` | | UIColor | `C_UIColor.GetColors` (backports `GlobalColor.dbc`; companion addon wraps each row with `ColorMixin` and assigns `_G[baseTag]` + `_G[baseTag.."_CODE"]`) | -| Unit | `GetUnitSpeed`, `UnitGUID`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsPossessed` | +| Unit | `GetUnitSpeed`, `UnitGUID`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsPossessed`, `UnitStandState` | | UnitAuras | `C_UnitAuras.GetAuraDataByIndex`, `C_UnitAuras.GetAuraDispelTypeColor`, `C_UnitAuras.GetBuffDataByIndex`, `C_UnitAuras.GetDebuffDataByIndex`, `C_UnitAuras.GetPlayerAuraBySpellID`, `C_UnitAuras.GetUnitAuraBySpellID`, `C_UnitAuras.GetUnitAuras` | ### Macros diff --git a/TODO.md b/TODO.md index 5e770ffe..95ca54ac 100644 --- a/TODO.md +++ b/TODO.md @@ -2402,7 +2402,7 @@ NOT `0xD48`). So `[player+0xD48]` is "gather-cast active" with a lootable GO" pointer. Pick which semantic you want before naming. -## 70. `UnitStandState(unit)` — easy +## ~~70. `UnitStandState(unit)`~~ — DONE Modern `GetUnitStandStateValue(unit)` or `UnitStandState(unit)` (the name varies by expansion) returns an integer describing whether diff --git a/docs/API.md b/docs/API.md index 1f37ae2f..d2b4098b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -123,6 +123,7 @@ build instructions. - [`UnitIsFeignDeath(unit)`](#unitisfeigndeathunit) - [`UnitIsInMyGuild(unitOrName)`](#unitisinmyguildunitorname) - [`UnitIsPossessed(unit)`](#unitispossessedunit) + - [`UnitStandState(unit)`](#unitstandstateunit) - [UnitAuras](#unitauras) - [`C_UnitAuras.GetAuraDataByIndex(unit, index [, filter])`](#c_unitaurasgetauradatabyindexunit-index--filter) - [`C_UnitAuras.GetBuffDataByIndex(unit, index)` / `GetDebuffDataByIndex(unit, index)`](#c_unitaurasgetbuffdatabyindexunit-index--getdebuffdatabyindexunit-index) @@ -3157,6 +3158,39 @@ Distinct from `UnitIsCharmed`: charm covers any charm-type effect (including pets summoned via mob-charm spells), possess is the specific spell-driven take-over effect modern WoW splits out. +### `UnitStandState(unit)` + +Returns the unit's standstate as an integer, matching the modern +`Enum.PlayerStandState` values: + +| Value | Meaning | +|------:|---------| +| `0` | STANDING | +| `1` | SITTING | +| `2` | SITTING_CHAIR | +| `3` | SLEEPING | +| `4` | SITTING_LOW_CHAIR | +| `5` | SITTING_MEDIUM_CHAIR | +| `6` | SITTING_HIGH_CHAIR | +| `7` | DEAD | +| `8` | KNEELING | + +Reads the low byte of `UNIT_BYTES_1` (descriptor `+0x210`), a +broadcast UpdateField — works for any synced unit (player, target, +party*, raid*, mouseover, etc.). Returns `0` (STANDING) for +unresolvable units (empty `party*` slot, no current target, etc.) +matching the modern behavior of returning a safe default. + +```lua +UnitStandState("player") -- 0 standing, 1 sitting, 5 chair-sit, … +UnitStandState("target") -- works for any visible unit +UnitStandState("party1") -- 0 if the slot is empty +``` + +1.12 has `IsSitOrStanding()` (local-player boolean) but no +unit-token form; `UnitStandState` fills the gap and exposes the +full enum. + ## UnitAuras Backport of the modern `C_UnitAuras` namespace. Returns diff --git a/src/Offsets.h b/src/Offsets.h index ce67b838..d50472f5 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -984,6 +984,19 @@ enum Offsets { OFF_UNIT_DESCRIPTOR_RACE_BYTE = 0x78, OFF_UNIT_DESCRIPTOR_CLASS_BYTE = 0x79, OFF_UNIT_DESCRIPTOR_SEX_BYTE = 0x7A, + + // `UNIT_BYTES_1` (CMaNGOS field 132 in the 1.12.1 layout). 32-bit + // composite field; the low byte is the standstate (standing / + // sitting / sleeping / kneeling / etc.), the upper bytes hold + // PetTalents / VisFlag / AnimTier per CMaNGOS docs (uncalibrated + // for 1.12). Broadcast field, so the standstate works for any + // synced unit (player, target, party/raid, inspect targets) — + // not local-only. + // + // Verified via the `IsAssistingRitual` development session by + // observing `0xEE00 → 0xEE05` on `/sit` over a chair (the medium- + // chair sit value 5). + OFF_UNIT_FIELD_BYTES_1 = 0x210, // Inner watched-faction setter — `__fastcall(ecx = factionID) → void`. // The engine's `Script_SetWatchedFactionIndex` (0x004D6B60) is a // thin Lua-side wrapper that takes a 1-based displayed-list index, diff --git a/src/unit/StandState.cpp b/src/unit/StandState.cpp new file mode 100644 index 00000000..83e3885f --- /dev/null +++ b/src/unit/StandState.cpp @@ -0,0 +1,84 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +#include "Game.h" +#include "Offsets.h" + +#include + +namespace Unit::StandState { + +namespace { + +using ResolveUnitToken_t = void *(__fastcall *)(const char *token); + +// `UnitStandState(unit)` — returns the unit's current standstate as +// the integer encoded in the low byte of `UNIT_BYTES_1` +// (descriptor + 0x210): +// +// 0 STANDING +// 1 SITTING +// 2 SITTING_CHAIR +// 3 SLEEPING +// 4 SITTING_LOW_CHAIR +// 5 SITTING_MEDIUM_CHAIR +// 6 SITTING_HIGH_CHAIR +// 7 DEAD +// 8 KNEELING +// +// Works for any synced unit (player, target, party*, raid*, +// mouseover, etc.) — the field is a broadcast UpdateField, so +// remote units' standstate is current. +// +// Returns 0 (STANDING) for: missing or invalid unit tokens (e.g. +// `partyN` slot empty, `target` with no target), and unit +// descriptors that aren't loaded yet. Matches modern semantics +// where unresolvable units don't error. +int __fastcall Script_UnitStandState(void *L) { + if (!Game::Lua::IsString(L, 1)) { + Game::Lua::Error(L, "Usage: UnitStandState(\"unit\")"); + return 0; + } + const char *token = Game::Lua::ToString(L, 1); + if (token == nullptr) { + Game::Lua::PushNumber(L, 0); + return 1; + } + + auto resolve = reinterpret_cast(Offsets::FUN_RESOLVE_UNIT_TOKEN); + auto *unit = static_cast(resolve(token)); + if (unit == nullptr) { + Game::Lua::PushNumber(L, 0); + return 1; + } + auto *fields = *reinterpret_cast( + unit + Offsets::OFF_UNIT_DESCRIPTOR); + if (fields == nullptr) { + Game::Lua::PushNumber(L, 0); + return 1; + } + const uint32_t bytes1 = *reinterpret_cast( + fields + Offsets::OFF_UNIT_FIELD_BYTES_1); + Game::Lua::PushNumber(L, static_cast(bytes1 & 0xFF)); + return 1; +} + +void RegisterLuaFunctions() { + Game::Lua::RegisterGlobalFunction("UnitStandState", &Script_UnitStandState); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace + +} // namespace Unit::StandState