From a166da61f56d1daf8072a6356b52978d8bd7308d Mon Sep 17 00:00:00 2001 From: avitasia Date: Tue, 7 Apr 2026 11:34:37 -0700 Subject: [PATCH] update readme --- README.md | 17 ++++------------- SCRIPTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 02fb9ab..6adc4f5 100644 --- a/README.md +++ b/README.md @@ -220,19 +220,7 @@ This includes functions for: - Talent helpers (LearnTalentRank) - Spell lookups and utilities (GetUnitGUID, CombatLogFlush, etc.) -`LearnTalentRank(talentPage, talentIndex, rank)` learns a specific talent rank directly by tab/index. -Valid ranges are: `talentPage` = `1-3`, `talentIndex` = `1-32`, `rank` = `1-5`. - -For unit data APIs, object-reference GUID fields are returned as strings (hex format) rather than numbers to avoid Lua 64-bit precision issues. -This applies to both `GetUnitData` and `GetUnitField` for fields such as: `charm`, `summon`, `charmedBy`, `summonedBy`, `createdBy`, `target`, `persuaded`, and `channelObject`. - -`GetUnitField` also has a fallback path for party/raid units when live `UnitFields` are unavailable. If the unit object is not loaded, it will try cached `party_member_fields` data instead. The overlapping `UnitFields` names available through this fallback are `health`, `maxHealth`, `level`, and `aura` for party/raid members, plus `displayId`, `health`, `maxHealth`, and `aura` for party/raid pets. `GetUnitData` does not use this fallback and still returns `nil` when the unit object is unavailable instead of returning a sparse object. - -`CancelPlayerAuraSpellId(spellId, [ignoreMissing])` supports an optional second parameter where `1` skips the aura-slot presence check (thought this might work when buff-capped but doesn't seem to work) and `0`/omitted keeps the default check. - -Cooldown detail tables now also expose `itemId`, `itemHasActiveSpell`, and `itemActiveSpellId` alongside the existing per-category timing data. - -Use `GetTrinkets([copy])` to enumerate equipped trinkets and bagged trinkets (backpack/bags 1-4) with `itemId`, `trinketName`, `texture`, `itemLevel`, `bagIndex` (nil when equipped), and 1-based `slotIndex`. It reuses cached tables by default; pass `1` (or any truthy value) to force a fresh copy. +Detailed parameter, return-value, and behavior notes for individual functions are documented in [SCRIPTS.md](SCRIPTS.md). ## Custom Events @@ -257,6 +245,9 @@ If you encounter any bugs please report them in the issues tab. Please include ## FAQ & Additional Info +### Why are some GUID values returned as hex strings? +Lua in the vanilla client does not safely preserve full 64-bit integer precision. To avoid truncated or rounded GUID values, Nampower returns object-reference GUIDs as hex strings (for example, `"0xF5300000000000A5"`) instead of Lua numbers in APIs that expose those fields. + ### OnChatMessage Patch Nampower applies an in-memory patch at `0x0049DB9F` to pass the appropriate unit guid needed by the client to display chat bubbles for following message types: diff --git a/SCRIPTS.md b/SCRIPTS.md index 841ab2b..4a038c6 100644 --- a/SCRIPTS.md +++ b/SCRIPTS.md @@ -39,6 +39,8 @@ For custom events, see [EVENTS.md](EVENTS.md). For installation, configuration, - [GetUnitData](#getunitdataunittoken-copy) - [GetUnitField](#getunitfieldunittoken-fieldname-copy) - [GetUnitGUID](#getunitguidunittoken) + - [GetRaidTargets](#getraidtargets) + - [SetLocalRaidTargetIndex](#setlocalraidtargetindexunittoken-raidtargetindex) - [Spell Casting and Queuing](#spell-casting-and-queuing) - [QueueSpellByName](#queuespellbynamespellname) - [CastSpellByNameNoQueue](#castspellbynamenoqueuespellname-onselforunit) @@ -924,6 +926,45 @@ print(GetUnitGUID("party1pet")) -- pet of party member 1 print(GetUnitGUID("0xF5300000000000A5target")) ``` +##### GetRaidTargets() +Returns the current local raid-target assignments as a table of GUID strings. + +**Returns:** +- A table indexed `1..8` +- Each value is a GUID string for the unit currently assigned to that local raid marker slot +- Empty slots return `nil` + +**Examples:** +```lua +local marks = GetRaidTargets() +print(marks[1]) -- GUID for local mark 1, or nil +print(marks[8]) -- GUID for local mark 8, or nil +``` + +##### SetLocalRaidTargetIndex(unitToken, raidTargetIndex) +Assigns a unit to a local raid-target slot. + +This uses the same extended unit-token parsing as `GetUnitGUID`, so standard unit tokens, `markN` tokens, suffix forms, and raw GUID strings are all supported. + +If the selected slot already has a unit assigned, that slot is cleared first and the previous unit's nameplate raid-target state is refreshed before the new unit is assigned. + +**Parameters:** +- `unitToken` (string): The unit to assign +- `raidTargetIndex` (number): Local raid-target slot index in the `0..8` range + +**Returns:** +- `1` on success +- `0` if the unit cannot be resolved or the underlying objects are unavailable +- Raises a Lua error if the parameters are invalid + +**Examples:** +```lua +SetLocalRaidTargetIndex("target", 0) +SetLocalRaidTargetIndex("mouseover", 3) +SetLocalRaidTargetIndex("mark1target", 7) +SetLocalRaidTargetIndex("0xF5300000000000A5", 1) +``` + ### Spell Casting and Queuing #### QueueSpellByName(spellName)