From fa3547be31becd01b931378dc253b0a61eeeb545 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Thu, 14 May 2026 23:21:43 -0500
Subject: [PATCH] UnitStandState
---
README.md | 2 +-
TODO.md | 2 +-
docs/API.md | 34 +++++++++++++++++
src/Offsets.h | 13 +++++++
src/unit/StandState.cpp | 84 +++++++++++++++++++++++++++++++++++++++++
5 files changed, 133 insertions(+), 2 deletions(-)
create mode 100644 src/unit/StandState.cpp
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