ShaguTweaks-ClassicAPI/Docs/CLASSICAPI_UPDATES.md

# ClassicAPI integration updates

These changes use newer ClassicAPI features while retaining older fallback paths.
ClassicAPI v1.18.13 was the latest release reviewed on 2026-10-31 (the previous
review covered v1.17.6 on 2026-10-24). Update both ClassicAPI's DLL and its
bundled `!!!ClassicAPI` addon together, following its installation
instructions; a DLL update needs a full client restart.

The integration code below was written against v1.17.6. The v1.17.7 to v1.18.13
review found nothing that needed a rewrite; see
[Reviewed since v1.17.6](#reviewed-since-v1176).

## Changes

- **Health correctness:** `UnitHealthMissing` returns a deficit in the same units
  as the health getters. It can be a percentage, so it is no longer used to infer
  absolute health. Direct health and the existing combat-estimation cache remain.
- **Chat identity:** `GetPlayerInfoByGUID` supplies the name in return position 6.
  The synchronous class fallback now checks that name against the requested player.
- **Cooldown rendering:** Target Debuff Timer creates native `Cooldown` frames on
  ClassicAPI 1.17.1+, retaining `Model` frames on older builds. Numeric timers and
  the existing timer dispatcher are preserved.
- **Unit event filtering:** health/power overlays register only player, target and
  pet unit events; the health estimator and target castbar register only target
  unit events. Older clients without `RegisterUnitEvent` use plain registration
  and their existing handler-side checks.
- **Chat payload:** spam filtering and passive sender collection read
  `GetCurrentChatEvent` when available. The filter uses local payload values and
  does not overwrite shared `arg1`/`arg2` globals. The older global path remains.
- **Player-cache duplication:** when native persistence is already enabled and
  `C_PlayerCache.RememberPlayer` succeeds, new chat-only sightings do not also
  create ShaguTweaks SavedVariables records. Native class-only lookups can avoid
  creating another record. Existing records, raw levels and social history stay
  intact. With persistence off or native storage unavailable, the original Lua
  cache behavior remains. The addon never enables native persistence itself.

## Reviewed since v1.17.6

156 ClassicAPI commits (v1.17.7 to v1.18.13) were read against the modules in
this addon.

**Changed here**

- **Debuff Timer:** the native `Cooldown` frame it creates now calls
  `SetHideCountdownNumbers(true)` when available. ClassicAPI can draw its own
  countdown numbers when the `countdownForCooldowns` CVar is `1` (default `0`),
  which would have doubled the timer text this module draws itself.

**Worth knowing, no code change**

- **Nameplate crash fix (v1.18.10):** world-tick subscribers now run after the
  UI draw. Before this, an addon that restyled a nameplate from
  `NAME_PLATE_CREATED` or a `C_Timer` callback could crash the client. No
  crash was traced to this addon, but v1.18.10 or newer is recommended for the
  Nameplates modules.
- **Range Color:** since v1.18.0, `C_Spell.IsSpellInRange` returns `nil` for a
  unit the spell cannot be cast at. The module already treats `nil` as "no
  range to fail", so it needs nothing.
- **Cooldown Numbers:** action, bag and spellbook cooldowns are still 1.12
  indicator Models, and `CooldownFrame_SetTimer` still serves them. The
  module's hook is still required; the native countdown numbers do not replace
  it.
- **Filtered unit events:** `RegisterUnitEvent` now also filters custom events
  that ClassicAPI fires itself (v1.18.9). The vanilla events used here were
  already filtered.

**Not adopted**

- `UNIT_POWER_UPDATE`, `UNIT_POWER_FREQUENT`, `UNIT_MAXPOWER` (v1.18.10): the
  legacy `UNIT_MANA` / `UNIT_ENERGY` / `UNIT_RAGE` events still fire and the
  overlays depend on their payloads. Switching would add a code path without a
  measured gain.
- `UNIT_AURA_DELTA` and aura instance IDs (v1.17.10): the debuff library
  refreshes on `UNIT_AURA` for the target and reads auras by index, so it does
  not need change sets.
- `UNIT_TARGET`, `UnitFacing`, `wipe`, the `Cooldown` countdown formatter and
  the other new APIs: no module here needs them.

Nothing from this review was tested in game.

## Measuring performance

On current ClassicAPI, the following prints ShaguTweaks' Lua memory in KiB:

```lua
/script UpdateAddOnMemoryUsage(); DEFAULT_CHAT_FRAME:AddMessage(GetAddOnMemoryUsage("ShaguTweaks"))
```

Memory readings include uncollected objects. For comparisons, collect through
GentleGC first and measure at the same point after login and after playing.
Texture/native allocations are not equivalent to this Lua-memory counter.

For a short CPU investigation:

1. Run `/console scriptProfile 1`, then `/reload`.
2. Run `/script ResetCPUUsage()` and play through a representative encounter.
3. Read the total CPU time in milliseconds:
   `/script UpdateAddOnCPUUsage(); DEFAULT_CHAT_FRAME:AddMessage(GetAddOnCPUUsage("ShaguTweaks"))`
4. Run `/console scriptProfile 0`, then `/reload` when finished.

Profiling adds overhead. Compare the same workload and measurement duration;
the cumulative CPU number alone is not an FPS measurement. Profiling is not
turned on by this addon.

## Verification

Lua 5.1 syntax checks cover all addon Lua files. Mocked regression checks cover:
unknown percentage health, valid cached estimates, direct health, native and
fallback unit-event registration, sixth-return chat identity and name mismatch,
native chat payload with corrupted globals, duplicate filtering, native/legacy
cooldown creation, and persistence enabled/disabled while retaining levels and
history. Existing health overlays and English-only load-list checks also pass.
These checks do not replace in-game rendering, event-order and combat testing;
no memory/FPS improvement is claimed without a live measurement.

## Primary references

- [ClassicAPI v1.18.13](https://github.com/brues-code/ClassicAPI/releases/tag/v1.18.13)
- [API reference (v1.18.13)](https://github.com/brues-code/ClassicAPI/blob/v1.18.13/docs/API.md)
- [ClassicAPI v1.17.6](https://github.com/brues-code/ClassicAPI/releases/tag/v1.17.6)
- [Nameplate crash fix](https://github.com/brues-code/ClassicAPI/commit/4eb214f)
- [Native cooldown rendering](https://github.com/brues-code/ClassicAPI/commit/b83bb5b52b11ffd51dd59aa7465b1185222f2bd4)
- [Reliable chat payload](https://github.com/brues-code/ClassicAPI/commit/b5aed30a5db5ef033dd9a6619d8f74310787c4c9)
- [Native player-name lookup](https://github.com/brues-code/ClassicAPI/commit/c7bb90895f8802ba837833d5ad1f9acbe0afece4)