COMBAT ASSISTANT 0.2.14 — FOREVERGEAR

0.2.14: Removes action matching and its setup button. Restores the animated target damage behavior from 0.2.12. Characters using Conservative mine + pet switch to My combat + target automatically. No Combat Log setup is needed. Existing animations, layout and incoming/healing settings are retained. Idle spectator fights stay filtered; shared hits on an enemy you are fighting may appear.

0.2.12: Restores animated outgoing text with My combat + target. Existing strict mode switches once, preserving text placement, themes and sizes. Later explicit scope choices persist. Idle spectator hits remain filtered, but shared hits on the enemy you are fighting may appear. Blizzard fallback settings are restored when leaving strict mode.

0.2.11: Strict personal combat is the default. Existing target mode switches to strict once; later scope choices persist. Unknown-source outgoing hits are never shown in strict mode. Supported Blizzard damage CVars are enabled on restricted clients (optional in General); these numbers use Blizzard appearance and placement, without addon effects. Incoming feedback, healing, buffs and XP remain custom. Restore damage preserves your scope. Native fallback does not enable native healing.

0.2.10 (previous release): My combat + target now requires readable engagement evidence:
you must be in combat, the target must be hostile, and you must be on its
threat table, have a player/pet debuff on it, or be attacked by it (including
your pet). Selecting someone else's fight while idle no longer shows hits.
Unknown engagement is excluded. Shared hits on an enemy you ARE fighting
still cannot be separated by attacker on a restricted client. Strict My
combat only remains available; All nearby combat intentionally stays broad.

0.2.9 (historical behavior, superseded by 0.2.11): Restores outgoing damage on restricted clients with My combat + target
(the new default). Full readable logs still show your own events; restricted
fallback shows incoming player feedback and hits on your selected target.
Other nearby enemy plates are excluded. Selected-target hits can include
other attackers, since this feed cannot identify their source.
The previous strict default is repaired once on restricted clients. Later
manual scope choices persist. My combat only remains the strict option and
All nearby combat keeps the wider feed. /fca damage now changes strict mode
to the target fallback when necessary to actually restore damage.

0.2.8: General > Combat shown offers My combat only and All nearby
combat. Personal mode keeps readable events involving you, plus optional pet
outgoing events. With restricted logs, it keeps incoming player feedback but
hides target/nameplate hits because their attacker cannot be identified.
As of 0.2.9, Restore damage display enables target fallback when strict mode
would otherwise prevent outgoing numbers.

Hostile stealth alerts are optional under General. Known Stealth, Prowl,
Vanish and Shadowmeld events reported by the combat log, or readable auras on
visible hostile targets/nameplates/mouseover units, can show a short notice
in the buffs area. Repeat notifications are suppressed for 10 seconds per
enemy. This never reveals hidden enemies, locations, or unreported actions.

With Utility > Outside combat: show only needed cleanses enabled, buttons
appear outside combat only for readable matching debuffs. During combat,
secure buttons remain clickable: unneeded icons dim to 25%, while a matching
cleanse shows the debuff icon and a bright highlight. Unknown/restricted aura
information cannot trigger a highlight. Targets and spells stay fixed.

0.2.7: General has separate incoming damage, outgoing damage and healing
switches. The existing source switches still gate their respective sources.
Effects intensity (0-1) adjusts particle count and brightness, with 0 off.
/fca layout: drag each area's bottom-right corner to resize independently;
movement and effects fit its saved boundaries. Right-click resets an area.
/fca diagnostics: source explanation, current filters and session counters
for shown/combined/filtered events, placement failures, restricted data,
screen fallbacks and replacement of older popups. Refresh or reset counters
there. Samples count too; events the client never sends cannot be counted.
Restricted fallback includes other attackers' hits, not just your damage.

0.2.6: /fca layout opens the editor and selects Screen lanes. The editor shows
the actual 520 x 280 area; animation and spacing stay within its boundaries.
Large text/effects fit the area. Busy lanes use the least crowded local spot
instead of jumping across the screen or discarding new hits. At the pool
limit, the oldest popup retires so the newest event can appear. Overlap is
still possible during heavy bursts. Readable combined hits retain their count.
Restricted-client feedback also includes non-selected enemy nameplates,
skipping the selected target's duplicate alias. These are all-source hits,
not confirmed player damage. Unavailable critical flags no longer discard
an otherwise displayable amount. No hidden combat data is inferred.

0.2.5: /fca damage (or General > Restore damage display) restores outgoing
damage and target feedback, enables damage presets, removes the minimum
amount filter and resets the damage lane. It selects Nameplates + fallback
while preserving colours, animation styles, effects and healing settings.
Nameplates only now reports when damage is suppressed because no usable
plate position exists. In fallback mode, numbers that cannot fit above a
nameplate also try the screen lane instead of being silently discarded.

0.2.4: Animated artwork now runs at 12 frames/second using eight-frame
texture atlases. Leaves flutter/fold, water bubbles grow and pop, flames
flicker, lightning changes shape, ice forms/cracks, holy light pulses,
shadow/arcane wisps swirl and physical strikes leave moving streaks.
Particles start at different frames, with three twinkles across the text.
All graphics stay attached to the numbers. Reduce motion freezes the atlas
and particles; the selected text animation still controls number travel.

Healing hearts replaced with leaves; Shaman water art is now a
cluster of translucent, highlighted bubbles that drift upward with the text.
Automatic effects prefer readable spell families and the known healer class.
When the client hides the source, the player's own class supplies a cosmetic
fallback: Shaman bubbles, Druid leaves, Paladin/Priest holy light. This does
not identify the real caster or add guessed spell icons. Other generic heals
use leaves. Existing healing effect on/off choices are preserved.
Damage accents are enabled once for existing characters and default on for
new profiles. Per-type choices made afterward remain saved. Flames flicker
upward, frost crystals sway, lightning crackles, poison drips, shadow/arcane
accents orbit, and physical hits send out short streaks. Three twinkling
points and a soft glow stay attached to the text. Restricted-number accents
use a compact fixed width instead of a distant edge of the safety text box.
Damage schools come from readable events; unknown damage stays generic.
Critical spells retain their school decorations. Spell icons remain genuine.
Set Effects around numbers off in a preset to disable its decorations.

0.2.3: Effects decorate the floating combat text only. Leaves, water, holy
light and other themes now move, scale and fade with their own numbers.
Removed player/target feet overlays and their controls. Old enabled body
effects migrate to text effects, including imported 0.2.2 presets. Class
and spell theme matching, previews and per-type toggles remain available.

Utility buttons now use preinstalled secure visibility rules: known spells
and existing party-member buttons appear during combat and remain clickable.
Outside combat, the optional hide-unneeded mode still follows readable
debuffs. In combat all enabled utility actions are available; the addon does
not auto-select a debuffed player or hide actions based on restricted auras.
Readable debuffs still update their icon/highlight. Party buttons cast on
the named member without changing your target. Setup/dragging stays outside
combat; spells learned or settings changed mid-fight apply afterward.

0.2.2 (body effects superseded in 0.2.3): Spell and class effect themes. Presets now has 18 combat types,
including separate Frost, Lightning, Nature, Holy, Shadow and Arcane styles.
Each preset has an Automatic/manual effect theme, Effects around numbers,
Effects near feet, and Preview this effect. Appearance can enable/disable
all effects together and adjust their size and player/target vertical offsets.
Existing healing switches migrate once; new effects start off.

Automatic healing uses readable spell families first, then the healer's
known class: Shaman water, Druid leaves, Paladin/Priest holy light, and
shadow-drain effects. An unrecognized spell with an unknown healer uses
the local class visual theme (updated in 0.2.4). English spell-family names
are recognized; other locales use an available caster class or local theme. This is not
a complete Forever spell database. Restricted UNIT_COMBAT has no caster or
spell identity, so it cannot distinguish these healing classes automatically.
Manual theme selection is available when you prefer a particular style.
Damage effects use readable school information; poison/venom names separate
poison from nature, and known Shaman nature spells use lightning accents.
Mixed schools use Fire, Frost, Shadow, Arcane, Holy, Nature precedence.
Critical spells keep their school accents while using the Critical preset's
size and effect toggles. Actual spell icons are never replaced with art.

Preview & layout has Druid leaves, Shaman water, and Paladin holy light demos.
/fca leaves, /fca water and /fca holy run the same 8-second samples without
enabling live effects; /fca stop clears them. Effects are positioned lower,
near the feet, and rise less. They remain local 2D overlays, not real 3D auras.
Player effects are screen-centred; target effects track visible nameplates
with adjustable offsets and disappear on plate loss/recycling. Camera angle,
zoom and creature size affect alignment. Up to eight recipient effects are
pooled and rate-limited. Appearance profiles preserve your effect choices.

0.2.1 (controls superseded by per-preset effects above): Original leaf flourishes for healing numbers, mint glow and
gold sparkles near your character when YOU receive healing. Actual spell
icons remain unchanged. /fca leaves runs an 8-second sample without casting
or enabling live effects. /fca stop clears it. Also available in Preview &
layout > Leaf healing preview. Appearance has separate live toggles plus
character-effect size and vertical offset. These cosmetic effects start off.
The character flourish is a local screen-space overlay, not a 3D world spell;
it does not track the character model when you change camera framing.
Reduced motion keeps the decorations still. Textures and frames are reused.

0.2.0: Smart motion-envelope spacing, critical clearance, readable hit counts
(840 ×3), four one-click appearance profiles and independently draggable
Damage / Incoming damage / Healing / Buffs / XP areas. Added targeted Normal
hit, Critical, Healing, Buff and Busy fight previews. Buff gained/refreshed/
applied switches, repeat delay and exact name / spell ID ignore list.
Party cleanse buttons now use names, class colours and native cooldown
numbers. Matching readable debuffs show their icon and highlight.


NEW CONTROLS
/fca > Appearance: Clean Blizzard / Minimal / Arcade / Healer, Undo last
profile, Edit text areas. Profiles change visuals, not notification filters.
/fca > Preview & layout: individual test buttons and 12-second Busy fight.
Edit text areas: drag each labelled area; centre guides and 10-pixel snapping;
right-click an area to reset it, or Reset all areas. Nameplate text follows
its target rather than these screen areas. Done returns to Options.
/fca > Buff notifications: independent switches, repeat delay, ignore list.
Refresh notices default off. Ignore entries are exact names or spell IDs.
Smart spacing reserves animation and critical-pop space. On crowded screens
excess text is dropped rather than stacked on an occupied area. Bleed text
falls beside a nameplate; other trajectories stay above its health bar.

0.1.6: Size popping now scales around a separate stationary anchor, preventing
unwanted diagonal screen travel. Rise is vertical, Bleed falls vertically,
and Slide stays horizontal near the origin. Added "Use for all types" to
apply an animation to every preset without changing colours or critical size.

0.1.5: Removed misleading damage-type icons from unidentified live hits.
Only the actual spell/aura icon is shown when supplied or resolvable from the
spell ID. Unknown attacks remain text-only. Preview and XP/gold keep their
illustrative icons. Recent casts are not guessed onto unrelated hit events.

0.1.4: Per-preset animations: Custom, Rise, Slide left, Slide right, Fountain,
Bleed, Still. Added outgoing placement: Screen lanes, Nameplates + fallback,
Nameplates only. Strict mode drops unanchored target hits and ends a popup
when its plate disappears or changes creature. Incoming text, buffs and XP/
money still use the screen lanes. Existing motion and placement are preserved.

0.1.3 (fallback icons superseded in 0.1.5): Added damage-type fallback icons;
known spell icons stay intact and sit next to the text. XP reads "200 XP Earned".
Added buff gained, refreshed and applied messages with a General toggle.
Added secure P1-P4 party cleanse buttons and an unlocked utility drag handle.

0.1.2: Critical hits default to triple normal text size and a quick oversized
pop that settles over 0.24 seconds. Existing character presets upgrade once.
Critical heals keep their healing colour with the same triple-size treatment.
Reduced motion keeps the larger text but skips the pop.

0.1.1: Fixed blank options pages when switching categories, restored the
JSON editor's position, and reset scrolling when opening another page.

INSTALL
Extract the CombatAssistant folder into:
World of Warcraft\_forever_\Interface\AddOns\
The TOC must be at AddOns\CombatAssistant\CombatAssistant.toc.
Restart WoW so it discovers the new addon. Enable Combat Assistant in AddOns.
Open /fca, or click its minimap icon (also offered to OneForAll's collector).
No other ForeverGear addon or external library is required.

QUICK START
1. Type /fca demo for a 12-second preview with sample numbers.
2. Drag the utility header outside combat. /fca unlock also unlocks the text
   anchor; either can be locked separately in Options.
3. Type /fca lock when finished.
4. Open /fca > Presets. Choose a style, edit it, then press Preview.
5. Open Utility to choose learned spells, change button size, or add a known
   Forever-specific spell by its spell ID and targeting mode.

ANIMATION AND PLACEMENT
Under Presets, choose Animation independently for Physical, Critical, Heal,
and each other style. Choosing an animation immediately runs a sample.
Use for all types copies only that animation choice to every text preset.
  Custom: existing horizontal/vertical velocity, gravity and wobble.
  Rise: float upward.
  Slide left / Slide right: enter horizontally from nearby (at most 160 UI
    units away) and ease toward the origin, never from the edge of the screen.
  Fountain: spray alternately to either side, rise, then fall.
  Bleed: drip straight downward (animated text, no gore art).
  Still: remain at the origin while fading. Critical size/pop is retained.
Speed, gravity and wobble tune applicable motion; Still ignores movement.
Reduced motion overrides trajectories and skips size popping.

General > Outgoing text selects screen lanes, nameplates with a screen
fallback, or nameplates only. Strict mode suppresses hits when a corresponding
visible plate cannot be found; it does not move them to the middle of the
screen. Each target has separate stacking and merging. Existing client limits
still apply: restricted UNIT_COMBAT mode displays the selected target, while
a readable full combat log can display hits on multiple visible targets.
Preview uses a visible target plate when possible and otherwise demonstrates
on screen even in strict mode, so styles can be edited outside combat.

COMMANDS
/fca or /combatassistant — options
/fca demo — auto-spawning sample scene; no spells are cast
/fca stop — stop demo and clear current popups
/fca unlock, /fca lock — move/lock both anchors
/fca status — data availability, popup counts and queued utility changes

COMBAT FEEDBACK
18 styles: Physical, Critical, Heal, Fire, Frost, Lightning, Nature, Poison,
Holy, Shadow, Arcane, Miss, Block, Shield, XP, Weak Hit, Boss Hit, Gold.

Each has its own RGB colour, font, outline, font size, lifetime, velocity,
gravity, fade timing, starting/final scale, wobble, icon and backplate.
General settings control opacity, scale, stacking, merging, popup budget,
number formatting, channels, minimum amount, nameplates and reduced motion.
Styles and preferences are saved per character.

In My combat only, readable full combat log events are attributed to you,
your pet (optional), or your incoming damage/healing. Spell icons come from
the client. Healing displays the effective amount after overhealing.
Identical readable hits within the chosen merge interval combine with a hit
count. Restricted amounts are never added together or counted as a merge.
Readable damage schools select their matching appearance preset.
Weak Hit and Boss Hit are optional numerical thresholds, initially off.
Boss Hit is a large-incoming-hit style, not automatic boss identification.
Gold shows positive money changes including trades/vendor sales, not profit.

FOREVER CLIENT LIMITS
Some Forever builds restrict the combat log. In that case the addon avoids
registering the restricted log and uses UNIT_COMBAT feedback:
  - incoming player damage/healing;
  - only in All nearby combat: selected target and hostile nameplate hits
    received from ALL attackers.
The target feedback option can be disabled separately. This feed does not
identify the attacker, spell, or periodic ticks. Unidentified live hits show
no icon. An actual spell/aura icon is displayed when available; preview icons
are illustrative samples only. This feed cannot isolate your own hits or
apply a DoT-only filter.
All nearby combat can show target and hostile nameplate feedback without
duplicating the target alias. Full-log mode follows known destination GUIDs.
There are no fabricated outgoing damage numbers.

Restricted amounts go directly to text display without arithmetic, filtering,
compacting or merging. If a particular build withholds an event or disallows
its display entirely, the addon cannot reconstruct it. /fca status identifies
the available mode. Built-in WoW combat text and other combat-text addons
remain under your control; disable unwanted duplicates in their own settings.

BUFF MESSAGES
Buff gained / Buff refreshed show readable helpful auras received by you.
Buffed <name> / Refreshed <name> show your buffs applied to another unit.
With a readable full combat log these use aura events. Otherwise the addon
compares helpful aura snapshots for player, target, focus, mouseover and party/
raid members. Old login buffs and target changes do not flood the screen.
Restricted aura identities are skipped; hidden names or casters cannot be
reconstructed. Refresh detection requires readable expiration times.
Shield's appearance is used for these messages. General > Buffs is the master
switch; Buff notifications controls gains, refreshes, applied buffs and ignores.

UTILITY BAR
Suggested buttons cover learned remove-curse, poison/disease cleansing,
magic dispel, soothe, spellsteal and purge abilities as appropriate to class.
Spell names, icons and tooltips are read from the installed game client.
Unknown spells never appear. Current abilities and talent restrictions still
apply; a suggested button does not grant a dispel your spell cannot perform.
Use the spell tooltip for the current Forever version's effects.

Left click targeting:
  help: friendly mouseover, friendly target, then yourself
  harm: hostile mouseover, then hostile target
  either: living mouseover, living target, then yourself
  ground: click, then choose a ground location
Right click casts friendly/either spells on yourself; harm/ground are unchanged.
Optional named buttons appear for existing party members below friendly/either
spell buttons. Either mouse button casts that spell directly on the indicated
member without changing your selected target. Hover for the member's name.
They do not automatically select a target or cast. Only-needed mode matches
known removal capabilities to readable harmful aura types and shows the
debuff icon. Main friendly buttons then cast on yourself, party buttons on
the named member. Unknown custom spell capabilities do not trigger prompts.
Each unit is assigned before combat. These are party buttons, not raid rows.
Drag the header outside combat; lock it under /fca > Utility when finished.
These are secure click-to-cast controls. Nothing casts automatically or picks
a debuff for you. Visible buttons remain present in combat. Spell list, size,
visibility and position changes wait until combat ends.
The bar is hidden when you have not learned any configured utility spells.
Up to eight custom known spell IDs can be added for Forever-specific skills.

JSON PRESETS
Presets.json contains the full editable defaults. WoW cannot read arbitrary
JSON files at runtime: copy the JSON text into /fca > Import / Export and
press Import presets. Export / select all gives your current styles.
An import is validated completely before anything changes. Imports are data,
never executable code. They cannot change utility buttons or spell actions.
Maximum input: 64 KB; maximum nesting depth: 15. No JSON null values.

Format (partial styles are accepted; omitted style fields use defaults):
{"version":1,"presets":{"Fire":{"color":[1,0.4,0.1],"fontSize":34,"lifetime":1.8}}}

Field                 Allowed values
enabled, icon, backplate  true / false
color                 [red, green, blue], each 0..1
font                  Default / Damage / Readable / Classic
animation             Custom / Rise / Slide left / Slide right / Fountain /
                      Bleed / Still
outline               NONE / OUTLINE / THICKOUTLINE / MONOCHROME
fontSize              12..240
lifetime              0.3..6 seconds
gravity               -200..200 (positive = downward)
velocityX             -180..180 UI units/second
velocityY             -100..220 UI units/second
fadeStart             0..0.95 fraction of lifetime
scale                 0.5..2.5 final scale
popScale              0.5..3 starting scale
wobble                0..50 UI units
wobbleSpeed           0..20 radians/second
backplateAlpha        0..1
padding               0..24 UI units

REUSABLE API
See Examples.lua (examples are deliberately not loaded by the TOC).
CombatAssistant.FloatingCombatTextLayer manages pooling, stacking and timing.
CombatAssistant.FloatingCombatTextPopup renders one reusable popup.
CombatAssistant.Layer is the already-created shared layer.
SpawnScreen accepts UIParent coordinates; Spawn chooses a configured lane.
SpawnWorld accepts a WoW unit token and follows its visible nameplate. This
is not an arbitrary 3D-world-coordinate projection API. With no visible plate,
it falls back to a screen lane. A recycled unit token never follows a new mob.
The renderer caps active popups and drops excess events instead of creating
unbounded frames. /fca status reports active, allocated and dropped counts.

VALIDATION
Automated Lua 5.1 syntax and simulated WoW runtime checks:
node --test tests/combat-assistant.test.mjs
Tests cover imports, bounded pools, secret-value handling, plate recycling,
event attribution/fallback, deferred protected changes, options reuse,
rewards and the demo. These do not replace an in-game combat/casting test.

API REFERENCE USED
Forever client UI source:
https://github.com/Gethe/wow-ui-source/tree/forever
Blizzard_FrameXML/SecureTemplates.lua (secure click actions)
Blizzard_APIDocumentationGenerated/CombatLogDocumentation.lua
Blizzard_APIDocumentationGenerated/UnitDocumentation.lua
