diff --git a/README.md b/README.md index 56e3629e..5737c0d8 100644 --- a/README.md +++ b/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` | diff --git a/docs/API.md b/docs/API.md index 446c7243..88e7d4c0 100644 --- a/docs/API.md +++ b/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 diff --git a/src/unit/Range.cpp b/src/unit/Range.cpp index 7ffaf087..5b3ed9d8 100644 --- a/src/unit/Range.cpp +++ b/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(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};