# ClassicAPI integration updates

These changes use newer ClassicAPI features while retaining older fallback paths.
ClassicAPI v1.17.6 was the latest release reviewed 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.

## 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.

## 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.17.6](https://github.com/brues-code/ClassicAPI/releases/tag/v1.17.6)
- [API reference](https://github.com/brues-code/ClassicAPI/blob/v1.17.6/docs/API.md)
- [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)