unit: add UnitDistanceSquared

Backport retail's UnitDistanceSquared(unit) -> (distanceSquared,
checkedPosition): the squared world distance from the player to the unit,
plus a flag for whether both positions were readable. Squared because
almost all distance logic is a threshold compare or nearest-unit sort,
neither of which needs the sqrt — which is why retail never shipped a plain
UnitDistance.

Added to the existing Unit::Range module alongside UnitInRange (both now
share one PlayerToUnitDistSq compute off the CGObject::GetPosition vtable
virtual). Center-to-center, self-contained (reads the position in C — no
SuperWoW dependency, and leaves SuperWoW's own UnitPosition untouched).
Verified in-game to match SuperWoW UnitPosition math to float precision.

On a position miss returns (0, false); no self-quirk, so
UnitDistanceSquared("player") is a legitimate (0, true).

Author: brues-code

README.md

@@ -62,7 +62,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Time](docs/API.md#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` |
 | [TradeSkillUI](docs/API.md#tradeskillui) | `C_TradeSkillUI.GetTradeSkillListLink`, `C_TradeSkillUI.GetCraftListLink`, `C_TradeSkillUI.GetTradeSkillListRecipes` |
 | [UIColor](docs/API.md#uicolor) | `C_UIColor.GetColors` |
-| [Unit](docs/API.md#unit) | `GetUnitSpeed`, `UnitClassBase`, `UnitGUID`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitPower`, `UnitPowerMax`, `UnitPowerType`, `UnitRaceBase`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
+| [Unit](docs/API.md#unit) | `GetUnitSpeed`, `UnitClassBase`, `UnitDistanceSquared`, `UnitGUID`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitPower`, `UnitPowerMax`, `UnitPowerType`, `UnitRaceBase`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
 | [UnitAuras](docs/API.md#unitauras) | `C_UnitAuras.GetAuraDataByIndex`, `C_UnitAuras.GetAuraDataBySpellName`, `C_UnitAuras.GetAuraDispelTypeColor`, `C_UnitAuras.GetBuffDataByIndex`, `C_UnitAuras.GetDebuffDataByIndex`, `C_UnitAuras.GetPlayerAuraBySpellID`, `C_UnitAuras.GetUnitAuraBySpellID`, `C_UnitAuras.GetUnitAuras`, `C_UnitAuras.RegisterComboDuration` |
 | [VoiceChat](docs/API.md#voicechat) | `C_VoiceChat.GetTtsVoices`, `C_VoiceChat.GetRemoteTtsVoices`, `C_VoiceChat.SpeakText`, `C_VoiceChat.StopSpeakingText`, `C_TTSSettings.GetSpeechRate`, `C_TTSSettings.GetSpeechVolume`, `C_TTSSettings.GetSpeechVoiceID`, `C_TTSSettings.GetVoiceOptionName`, `C_TTSSettings.SetSpeechRate`, `C_TTSSettings.SetSpeechVolume`, `C_TTSSettings.SetVoiceOption`, `C_TTSSettings.SetVoiceOptionByName`, `C_TTSSettings.SetDefaultSettings`, `C_TTSSettings.RefreshVoices` |
 | [XMLUtil](docs/API.md#xmlutil) | `C_XMLUtil.DoesTemplateExist`, `C_XMLUtil.GetTemplateInfo`, `C_XMLUtil.GetTemplates` |

docs/API.md

@@ -428,6 +428,7 @@ build instructions.
   - [`UnitIsOtherPlayersPet(unit)`](#unitisotherplayerspetunit)
   - [`UnitStandState(unit)`](#unitstandstateunit)
   - [`UnitInRange(unit)`](#unitinrangeunit)
+  - [`UnitDistanceSquared(unit)`](#unitdistancesquaredunit)
   - [`UnitPower(unit [, powerType])` / `UnitPowerMax(unit [, powerType])`](#unitpowerunit--powertype--unitpowermaxunit--powertype)
   - [`UnitPowerType(unit)`](#unitpowertypeunit)
 
@@ -10211,6 +10212,44 @@ mouseover, etc.). For raid members in a different zone or otherwise
 not in the engine's sync window, the position virtual returns null
 and the function reports `(false, false)`.
 
+### `UnitDistanceSquared(unit)`
+
+Returns `(distanceSquared, checkedPosition)` — the **squared** world
+distance (yards²) from the player to `unit`, and a flag indicating
+whether both positions were available.
+
+```lua
+local distSq, checked = UnitDistanceSquared("target")
+if checked and distSq <= 30 * 30 then
+    -- target is within 30 yards
+end
+```
+
+| Return | Meaning |
+|--------|---------|
+| `distanceSquared` | Squared distance player→unit. `0` when `checkedPosition` is `false` (a placeholder — matches retail's "always a number" shape). |
+| `checkedPosition` | `true` when both positions were read. `false` when `unit`'s position isn't available (empty `partyN` slot, no target, raid member outside the sync window, etc.). |
+
+The value is **squared** on purpose: nearly all distance logic is a
+threshold compare (`distSq <= range * range`) or a nearest-unit sort,
+neither of which needs the square root — so retail exposes only the
+squared form (added 5.0.4) and never a plain `UnitDistance`. Take
+`math.sqrt(distanceSquared)` only when you need a yard number to show a
+human.
+
+Reads world positions via the `CGObject::GetPosition` vtable virtual
+(slot 5, offset `+0x14`) — the same path `UnitInRange` /
+`CheckInteractDistance` use. **Center-to-center**, not reach-aware (that
+edge-to-edge nicety is UnitXP_SP3's niche); the value equals what you'd
+compute from SuperWoW's `UnitPosition`, but it's self-contained (no
+sibling-DLL dependency, and no clash with SuperWoW's own `UnitPosition`,
+which is left untouched).
+
+> No self-quirk (unlike `UnitInRange`): `UnitDistanceSquared("player")`
+> returns a legitimate `(0, true)`. Because a real `0` (self, or two
+> exactly co-located units) is indistinguishable by value from the miss
+> placeholder, always branch on `checkedPosition`.
+
 ### `UnitClassBase(unit)`
 
 Returns `(classFile, classID)` — the locale-independent class

src/unit/Range.cpp

@@ -8,11 +8,21 @@
 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 // PURPOSE. See the GNU General Public License for more details.
 
-// `UnitInRange(unit) → (inRange, checkedRange)` — 40-yard healing-
-// range check, modern's `UnitInRange` shape. Vanilla 1.12 doesn't
-// ship the function but has all the underlying machinery — the
-// same `GetPosition` virtual (vtable slot 5) `CheckInteractDistance`
-// uses, applied with a fixed 40-yard threshold.
+// Player↔unit proximity, modern's shape. Vanilla 1.12 ships neither
+// function but has all the underlying machinery — the object's
+// `GetPosition` virtual (vtable slot 5) `CheckInteractDistance` uses:
+//
+//   `UnitInRange(unit) → (inRange, checkedRange)` — 40-yard healing-
+//     range check (fixed threshold on the squared distance).
+//   `UnitDistanceSquared(unit) → (distanceSquared, checkedPosition)` —
+//     the raw squared world distance player→unit. Squared because
+//     nearly every consumer compares against a threshold (`distSq <=
+//     range*range`) or ranks by nearest, neither of which needs the
+//     sqrt; that's why retail exposes only the squared form (added
+//     5.0.4). Center-to-center — NOT reach-aware (that's UnitXP_SP3's
+//     niche); equivalent to computing it from SuperWoW `UnitPosition`,
+//     but self-contained (reads the position in C, no sibling-DLL
+//     dependency, no clash with SuperWoW's own `UnitPosition`).
 
 #include "Game.h"
 #include "unit/Position.h"
@@ -26,6 +36,24 @@ namespace {
 constexpr float kRangeYards = 40.0f;
 constexpr float kRangeYardsSq = kRangeYards * kRangeYards;
 
+// Squared world distance from the player to `token`'s unit. Returns true
+// and writes *outSq on success; false when either position is unavailable
+// (unresolved / absent token, or an object with no known position yet —
+// e.g. a party member outside the client's sync range). This false is
+// exactly the `checkedPosition = false` case retail flags.
+bool PlayerToUnitDistSq(const char *token, float *outSq) {
+    float unitPos[3] = {};
+    float playerPos[3] = {};
+    if (!Unit::Position::ReadToken(token, unitPos) ||
+        !Unit::Position::ReadToken("player", playerPos))
+        return false;
+    const float dx = unitPos[0] - playerPos[0];
+    const float dy = unitPos[1] - playerPos[1];
+    const float dz = unitPos[2] - playerPos[2];
+    *outSq = dx * dx + dy * dy + dz * dz;
+    return true;
+}
+
 int __fastcall Script_UnitInRange(void *L) {
     if (!Game::Lua::IsString(L, 1)) {
         Game::Lua::Error(L, "Usage: UnitInRange(\"unit\")");
@@ -44,27 +72,47 @@ int __fastcall Script_UnitInRange(void *L) {
         return 2;
     }
 
-    float unitPos[3] = {};
-    float playerPos[3] = {};
-    if (!Unit::Position::ReadToken(token, unitPos) ||
-        !Unit::Position::ReadToken("player", playerPos)) {
+    float distSq = 0.0f;
+    if (!PlayerToUnitDistSq(token, &distSq)) {
         Game::Lua::PushBool(L, false);
         Game::Lua::PushBool(L, false);
         return 2;
     }
 
-    const float dx = unitPos[0] - playerPos[0];
-    const float dy = unitPos[1] - playerPos[1];
-    const float dz = unitPos[2] - playerPos[2];
-    const float distSq = dx * dx + dy * dy + dz * dz;
-
     Game::Lua::PushBool(L, distSq <= kRangeYardsSq);
     Game::Lua::PushBool(L, true);
     return 2;
 }
 
+// `UnitDistanceSquared("unit") → (distanceSquared, checkedPosition)`.
+// Unlike UnitInRange there's no self-quirk: `UnitDistanceSquared("player")`
+// is a legitimate `(0, true)`. On a position miss returns `(0, false)` —
+// matching retail's "always a number" shape; consumers must branch on
+// `checkedPosition`, since a real `0` (self, or exactly co-located units)
+// is indistinguishable from the miss placeholder by value alone.
+int __fastcall Script_UnitDistanceSquared(void *L) {
+    if (!Game::Lua::IsString(L, 1)) {
+        Game::Lua::Error(L, "Usage: UnitDistanceSquared(\"unit\")");
+        return 0;
+    }
+    const char *token = Game::Lua::ToString(L, 1);
+
+    float distSq = 0.0f;
+    if (!PlayerToUnitDistSq(token, &distSq)) {
+        Game::Lua::PushNumber(L, 0.0);
+        Game::Lua::PushBool(L, false);
+        return 2;
+    }
+
+    Game::Lua::PushNumber(L, static_cast<double>(distSq));
+    Game::Lua::PushBool(L, true);
+    return 2;
+}
+
 void RegisterLuaFunctions() {
     Game::Lua::RegisterGlobalFunction("UnitInRange", &Script_UnitInRange);
+    Game::Lua::RegisterGlobalFunction("UnitDistanceSquared",
+                                      &Script_UnitDistanceSquared);
 }
 
 const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};