Repository navigation
Expand file tree
/
Copy pathcompat.lua
More file actions
2543 lines (2379 loc) · 105 KB
/
Copy pathcompat.lua
File metadata and controls
2543 lines (2379 loc) · 105 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
--=========================================================================================
-- Cross-client compatibility layer.
--
-- SwedgeTimer ships one build for every WoW client family (Classic Era, TBC, Wrath,
-- Cata, Mists, Retail, WoW Forever, plus legacy/private clients). This is the single
-- place where client API differences are handled.
--
-- Sets:
-- st.family : "ERA" | "TBC" | "WRATH" | "CATA" | "MISTS" | "RETAIL"
-- | "FOREVER" | "UNKNOWN"
-- st.interface_number : the running client's TOC interface version, when knowable
-- st.is_retail : true on the Retail (mainline) client
-- st.is_mainline : true on Mainline-code clients (Retail, WoW Forever): their
-- classic combat log is gone, so the swing engine cannot run
-- st.gcd_probe_spell_id : spell id whose cooldown reading mirrors the global cooldown
-- st.lust_spell_ids : confirmed Bloodlust (2825) / Heroism (32182) spell ids
-- st.lust_supported : true where Bloodlust/Heroism can exist (TBC+; Era: false)
-- st.cleu_supported : true where the classic combat log exists (classic-line;
-- Retail/Forever: false, so CLEU-driven chains stay inert)
-- st.api.* : normalized wrappers for APIs that differ across clients
--
-- On clients where the original global function still exists, each wrapper preserves the
-- global's exact return values, so Titanforge 3.80.2 (the regression baseline) behaves
-- exactly as before. A few wrappers add a secret-value guard on top (see below): where
-- the value is not secret that guard is an exact no-op, and where a restricted read
-- hands back an opaque value it degrades to the documented "unknown" shape instead of
-- raising a Lua error.
-- Retail-only replacements (C_Spell, C_UnitAuras, C_SpecializationInfo) are used only
-- where the globals are gone.
--
-- Rule for the rest of the addon: never call a cross-client API directly - go through
-- st.api. Per-family data (spell IDs, form indices, talent checks) lives with the
-- class modules in classes/.
--=========================================================================================
---@class LibCustomGlow
---@field PixelGlow_Start fun(frame: any, color?: table, N?: number, frequency?: number, length?: number, th?: number, xOffset?: number, yOffset?: number, border?: boolean, key?: any, frameLevel?: number)
---@field PixelGlow_Stop fun(frame: any, key?: any)
---@field ButtonGlow_Start fun(frame: any, color?: table, frequency?: number, frameLevel?: number)
---@field ButtonGlow_Stop fun(frame: any)
---@field AutoCastGlow_Start fun(frame: any, color?: table, N?: number, frequency?: number, scale?: number, xOffset?: number, yOffset?: number, key?: any, frameLevel?: number)
---@field AutoCastGlow_Stop fun(frame: any, key?: any)
local addon_name, st = ...
st.addon_name = st.addon_name or addon_name
--------------------------------------------------------------------------------
-- Client family detection
--------------------------------------------------------------------------------
local family = "UNKNOWN"
local interface_number
-- WoW Forever ("Camelot") reports WOW_PROJECT_CAMELOT; fall back to its numeric value
-- so the comparison still works on clients where the global does not exist.
local WOW_PROJECT_FOREVER = WOW_PROJECT_CAMELOT or 18
do
-- Preferred: the WOW_PROJECT_ID constants, present on every official client.
local project_id = WOW_PROJECT_ID
if project_id ~= nil then
if project_id == WOW_PROJECT_CLASSIC then
family = "ERA"
elseif project_id == WOW_PROJECT_BURNING_CRUSADE_CLASSIC then
family = "TBC"
elseif project_id == WOW_PROJECT_WRATH_CLASSIC then
family = "WRATH"
elseif project_id == WOW_PROJECT_CATACLYSM_CLASSIC then
family = "CATA"
elseif project_id == WOW_PROJECT_MISTS_CLASSIC then
family = "MISTS"
elseif project_id == WOW_PROJECT_MAINLINE then
family = "RETAIL"
elseif project_id == WOW_PROJECT_FOREVER then
family = "FOREVER"
end
end
-- Fallback: the TOC interface version. Legacy/private clients have no project id.
local get_build_info = GetBuildInfo
if get_build_info then
local _, _, _, toc = get_build_info()
interface_number = tonumber(toc)
end
if family == "UNKNOWN" and interface_number then
local major = math.floor(interface_number / 10000)
if major == 1 and interface_number >= 16000 then
-- WoW Forever shares Classic Era's major version (1.60.x -> 16000+)
-- but runs Mainline client code: never bucket it as Era.
family = "FOREVER"
elseif major == 1 then
family = "ERA"
elseif major == 2 then
family = "TBC"
elseif major == 3 then
family = "WRATH"
elseif major == 4 then
family = "CATA"
elseif major == 5 then
family = "MISTS"
elseif major >= 10 then
family = "RETAIL"
end
end
-- WoW Forever / Camelot probe: if C_SwingTimer is exposed or Camelot project matches,
-- this client is FOREVER, never Retail, Era, or Unknown.
if rawget(_G, "C_SwingTimer") ~= nil then
family = "FOREVER"
elseif (family == "RETAIL" or family == "UNKNOWN") then
local camelot_id = WOW_PROJECT_CAMELOT or 18
if project_id ~= nil and project_id == camelot_id then
family = "FOREVER"
end
end
end
st.family = family
st.interface_number = interface_number
st.is_retail = (family == "RETAIL")
-- Retail and WoW Forever run Mainline client code; the classic combat log is gone
-- there, so the swing engine (LibClassicSwingTimerAPI) cannot work on them.
st.is_mainline = (family == "RETAIL" or family == "FOREVER")
-- GCD probe spell: a spell that has no cooldown of its own, so its cooldown reading
-- mirrors the global cooldown. 29515 ("TEST Scorch") is a vanilla-era test spell
-- present on every classic client; 61304 ("Global Cooldown") is Blizzard's dummy
-- for the same purpose on Mainline clients.
st.gcd_probe_spell_id = 29515
if st.is_mainline then
st.gcd_probe_spell_id = 61304
end
--------------------------------------------------------------------------------
-- Bloodlust / Heroism (the lust window)
--------------------------------------------------------------------------------
-- Bloodlust (Horde) 2825 and its Alliance twin Heroism 32182 are a first-class
-- haste-window input for the swing tracking (hunter H2, paladin P3). Both ids
-- are CONFIRMED (bench/verify_bank.md §2: Wowhead TBC pages, 40s duration). The
-- spells only exist from TBC onward, so a lust helper must never arm on Classic
-- Era: consumers gate on st.lust_supported, which is derived from st.family
-- (never a version string) and stays false on Era and on the UNKNOWN fallback
-- family - only the confirmed families TBC/WRATH/CATA/MISTS/RETAIL/FOREVER arm.
st.lust_spell_ids = { 2825, 32182 }
st.lust_supported = (family ~= "ERA" and family ~= "UNKNOWN")
-- Post-lust debuff ids, registered for reference only. UNCONFIRMED:
-- bench/verify_bank.md §2 found no primary source for Exhaustion/Sated
-- 57723/57724 (secondary WeakAura mentions only), and the 57723-vs-57724 name
-- mapping is unconfirmed as well. IN-CLIENT CHECK: read the debuff id off the
-- player right after a Bloodlust lands before any caller depends on it. Nothing
-- may hard-depend on these values: matching them must stay on nil-safe paths
-- that degrade to "no debuff" instead of erroring.
st.post_lust_debuff_ids = { 57723, 57724 }
--------------------------------------------------------------------------------
-- Normalized API surface
--------------------------------------------------------------------------------
local api = {}
st.api = api
-- Secret values (Mainline-code clients) ---------------------------------------------------
-- Under the Mainline secret-value regime, restricted reads (cooldowns, power, health,
-- auras, combat stats, casts) can return opaque "secret" values: type() still reports the
-- underlying type, so a type() or "== nil" guard cannot see them, while arithmetic,
-- comparison and table indexing with one raises a Lua error. The probe itself is
-- documented on every shipped branch, but only the Mainline-code clients declare any
-- SecretWhen* predicate (the classic branches declare access preconditions only), so no
-- value is ever secret there and every guard below is an exact no-op.
local is_secret = issecretvalue or function()
return false
end
-- Additive observability (SEC-12, 2026-11-07): callers that receive a third-party state
-- table (the HUD provider contract) can verify a numeric field before doing arithmetic
-- on it. It is never used to branch on a secret VALUE - only to choose the documented
-- unknown face. Exact no-op on the classic clients (issecretvalue is absent there and
-- no value is ever secret).
function api.is_secret(value)
return is_secret(value) == true
end
-- Spell info -----------------------------------------------------------------------------
-- Classic shape: name, rank, icon, castTime, minRange, maxRange, spellID
-- Retail shape: C_Spell.GetSpellInfo returns a SpellInfo table.
if GetSpellInfo then
api.GetSpellInfo = GetSpellInfo
elseif C_Spell and C_Spell.GetSpellInfo then
api.GetSpellInfo = function(spell)
local info = C_Spell.GetSpellInfo(spell)
if not info then
return nil
end
-- Retail has no "rank"; the remaining units match the classic returns.
return info.name, nil, info.originalIconID, info.castTime, info.minRange, info.maxRange, info.spellID
end
else
-- Unknown client: report a 1.5s cast time so GCD estimation stays sane.
api.GetSpellInfo = function()
return nil, nil, nil, 1500, 0, 0, nil
end
end
-- Spell knowledge ------------------------------------------------------------------------
-- Whether the player knows a spell, used to resolve the highest known rank of a tracked
-- spell family. The probes exist on different client families; the first one that ANSWERS
-- wins (a probe that returns nil declines, and the chain moves on to the next probe).
--
-- CONTRACT (binary, never nil): api.is_spell_known answers true or false and nothing else.
-- true = a probe answered "the player knows this spell".
-- false = a probe answered "the player does not know it" OR no probe could answer at all
-- (no probe on this client, or every probe declined).
-- A false is therefore NOT the claim "the client says the player does not know the spell":
-- on a client that cannot answer it is the fail-closed answer, not a fact about the player.
-- Every caller in the tree treats only true as affirmative knowledge (== true / ~= true),
-- so a false never turns a row on.
--
-- The two cases ARE told apart by api.is_spell_known_state below - the same shape as
-- api.get_family_spell_id_state (the answer first, the state string second): a caller that
-- must not guess (a row that hides when the client cannot answer) reads the state, never
-- the boolean alone.
--
-- Client note (wow-ui-source, per branch): C_SpellBook.IsSpellKnown is documented on every
-- targeted family (classic_era, classic_anniversary, classic_titan, forever, live) and
-- returns a bool; the classic global IsSpellKnown is Blizzard's deprecated shim over
-- C_SpellBook (Blizzard_DeprecatedSpellBook/Deprecated_SpellBook.lua) and exists only while
-- the loadDeprecationFallbacks CVar is on. So no targeted client is probe-less - the
-- no-probe branch below is the defensive path, not a shape the shipped matrix reaches.
local spell_known_probes = {}
-- IsSpellKnown is deprecated on modern clients, so resolve it dynamically; this both
-- dodges the deprecation annotation and tolerates clients that removed the global.
local classic_is_spell_known = rawget(_G, "IsSpellKnown")
if classic_is_spell_known then
spell_known_probes[#spell_known_probes + 1] = classic_is_spell_known
end
-- C_SpellBook.IsSpellKnown (SpellBookDocumentation.lua: "Returns true if a player knows
-- a spell"; sibling IsSpellKnownOrInSpellBook beside it) is the probe on the
-- Mainline-code clients, where the global above is absent. NOTE: C_Spell.IsSpellKnown*
-- exists on NO client (absent on era/anniversary/titan/forever/live alike) - the live
-- namespace is C_SpellBook, so nothing probes C_Spell here. Appended after the global
-- on purpose: a client whose chain already answers (the classic clients, with
-- Blizzard's deprecation fallbacks loaded) keeps the exact same answer source, so
-- nothing changes there.
local spell_book_api = rawget(_G, "C_SpellBook")
if spell_book_api then
if spell_book_api.IsSpellKnown then
spell_known_probes[#spell_known_probes + 1] = spell_book_api.IsSpellKnown
end
if spell_book_api.IsSpellKnownOrInSpellBook then
spell_known_probes[#spell_known_probes + 1] = spell_book_api.IsSpellKnownOrInSpellBook
end
end
-- A spell NAME is not a probe argument on the modern clients. TBC Anniversary's
-- IsSpellKnown global is Blizzard's deprecated shim
-- (Blizzard_DeprecatedSpellBook/Deprecated_SpellBook.lua), which forwards its argument
-- to C_SpellBook.IsSpellInSpellBook - an id-only API that throws on a string:
-- "bad argument #1 to 'IsSpellInSpellBook' (outside of expected range ...)",
-- operator in-client BugGrabber evidence 2026-10-21 (hunter post_init, "Kill Shot").
-- The caller's token is therefore probed AS GIVEN first: on the clients where a name is
-- the query form (operator-confirmed name-vs-id rule) that keeps the exact answer source.
-- Only a THROWING probe triggers the one-time name -> id resolution through the ONE compat
-- spell-info path above (api.GetSpellInfo; its 7th return is the id) - no second
-- resolution path - after which the same probe is retried with the id. A name that
-- resolves to nothing is "unknown": never a guess, never a throw.
local function spell_known_name_id(spell_name)
if type(spell_name) ~= "string" then
return nil
end
local ok, _, _, _, _, _, _, id = pcall(api.GetSpellInfo, spell_name)
if not ok or is_secret(id) or type(id) ~= "number" then
return nil
end
return id
end
-- The state variant of the probe - the tri-state the boolean above folds away:
-- true, "known" a probe answered true
-- false, "not_known" a probe answered false
-- false, "unknown" no probe answered - the client cannot answer the question,
-- or the token did not resolve to a spell id at all
-- Same contract as api.get_family_spell_id_state: the answer first, the state second.
-- Every probe call is pcall-wrapped: a probe that throws is "no answer" (the chain
-- moves on), so a client-side throw costs the answer, never the caller's init. The
-- probe order is unchanged (classic global first, C_SpellBook probes after it).
function api.is_spell_known_state(spell_id, fallback_id)
-- Neither a spell id nor a spell name can be a probe argument: fail closed before any
-- client call. pcall would contain the throw, but there is nothing to resolve either.
if type(spell_id) ~= "number" and type(spell_id) ~= "string" then
if type(fallback_id) == "number" or type(fallback_id) == "string" then
spell_id = fallback_id
fallback_id = nil
else
return false, "unknown"
end
end
local fallback_resolved = false
for i = 1, #spell_known_probes do
local ok, known = pcall(spell_known_probes[i], spell_id)
if not ok then
if not fallback_resolved then
local resolved_id = spell_known_name_id(spell_id)
if resolved_id ~= nil then
fallback_id = resolved_id
end
fallback_resolved = true
end
if fallback_id ~= nil then
ok, known = pcall(spell_known_probes[i], fallback_id)
end
end
if ok and not is_secret(known) then
if known == true then
return true, "known"
end
if known ~= nil then
return false, "not_known"
end
end
end
return false, "unknown"
end
-- The boolean form: the answer half of the state above, unchanged for every caller
-- (true / false, never nil).
function api.is_spell_known(spell_id, fallback_id)
local known = api.is_spell_known_state(spell_id, fallback_id)
return known
end
-- Spell cooldowns ------------------------------------------------------------------------
-- Classic shape: start, duration, enabled, modRate (enabled is 1/0)
-- Retail shape: C_Spell.GetSpellCooldown returns a SpellCooldownInfo table.
--
-- One wrapper for every family instead of a pass-through of the classic global: that
-- global's annotation declares no return values, and inheriting it would make the
-- wrapper's own returns look redundant to the type checker.
local classic_get_spell_cooldown = GetSpellCooldown
local retail_get_spell_cooldown = C_Spell and C_Spell.GetSpellCooldown
-- Mainline-code clients answer a restricted cooldown through a duration object that is
-- itself never secret; it is the only readable source while cooldown restrictions are on.
local retail_get_spell_cooldown_duration = C_Spell and C_Spell.GetSpellCooldownDuration
-- WoW Forever native pass-through surface (2026-11-08, bench/forever_hud_api_2026-11-08.md
-- §4-§6). C_Spell.GetSpellCooldownDuration carries no SecretWhen* predicate, so its
-- LuaDurationObject is a NON-secret opaque handle whose values may be secret; the native
-- sinks (CooldownFrame:SetCooldownFromDurationObject, DurationTextBinding:SetDuration)
-- consume it without a Lua number ever being exposed. Every reader below is Forever-only
-- AND probe-gated, so on any other client it answers "no" and the existing numeric paths
-- are byte-identical. C_Secrets answers are plain booleans/enums; the duration-text
-- binding is documented to evaluate its own (possibly secret-valued) duration internally.
local secrets_api = rawget(_G, "C_Secrets")
local should_spell_cooldown_be_secret = secrets_api and secrets_api.ShouldSpellCooldownBeSecret
local duration_util = rawget(_G, "C_DurationUtil")
local create_duration_text_binding = duration_util and duration_util.CreateDurationTextBinding
local string_util = rawget(_G, "C_StringUtil")
local create_seconds_formatter = string_util and string_util.CreateSecondsFormatter
local create_numeric_rule_formatter = string_util and string_util.CreateNumericRuleFormatter
local curve_util = rawget(_G, "C_CurveUtil")
local create_color_curve = curve_util and curve_util.CreateColorCurve
-- Every classic return is checked before any of them is used: a restricted duration would
-- otherwise reach the "duration == 0" test below, and comparing a secret value raises.
local function spell_cooldown_values_are_secret(start_time, duration, enabled, mod_rate)
return is_secret(start_time) or is_secret(duration) or is_secret(enabled)
or is_secret(mod_rate)
end
-- A finite number only: NaN and +-inf are not usable cooldown readings either.
local function is_finite_number(value)
return type(value) == "number" and value == value
and value ~= math.huge and value ~= -math.huge
end
-- C_Spell.GetSpellCooldownDuration (Retail, WoW Forever) returns a LuaDurationObject whose
-- HasSecretValues() is documented as never secret; its individual reads are NOT, so they are
-- only trusted when that probe answers exactly false. Everything is pcall-wrapped: an object
-- with a different method set declines instead of throwing.
local function read_cooldown_duration_object(object)
local has_secret_values = object.HasSecretValues
if type(has_secret_values) ~= "function" then
return nil
end
local secret_ok, secret = pcall(has_secret_values, object)
if not secret_ok or secret ~= false then
return nil
end
local remaining_ok, remaining = pcall(object.GetRemainingDuration, object)
local total_ok, total = pcall(object.GetTotalDuration, object)
local start_ok, object_start = pcall(object.GetStartTime, object)
if not remaining_ok or not total_ok or not start_ok then
return nil
end
return remaining, total, object_start
end
-- Classic shape (start, duration) from the duration object: start = end - duration with
-- end = now + remaining, so the four classic returns stay the one shape every caller knows.
-- nil when the client cannot answer or the object reports a restricted read.
local function cooldown_duration_fallback(token)
if type(retail_get_spell_cooldown_duration) ~= "function" then
return nil
end
local ok, object = pcall(retail_get_spell_cooldown_duration, token)
if not ok or object == nil then
return nil
end
local read_ok, remaining, total, object_start =
pcall(read_cooldown_duration_object, object)
if not read_ok or remaining == nil then
return nil
end
if not is_finite_number(remaining) or not is_finite_number(total)
or not is_finite_number(object_start) then
return nil
end
if total <= 0 then
return nil
end
local now = api.get_time()
if not is_finite_number(now) or is_secret(now) then
return nil
end
return now - (total - remaining), total
end
-- raw_query's fifth return is `restricted`: true only when a restricted (secret) reading was
-- hit and no readable source produced a duration.
local function raw_query_spell_cooldown(token)
if token == nil then
return 0, 0, 0, 0
end
local start_time, duration, enabled, mod_rate
local restricted = false
-- Whether any source actually answered. A readable zero IS an answer ("not on
-- cooldown"), so it clears the flag; only "every source was restricted" reports
-- restricted. Without this, one restricted source would discard another source's
-- readable values (compat.lua's own contract: the flag means no readable source).
local readable = false
if classic_get_spell_cooldown then
local ok, s, d, e, m = pcall(classic_get_spell_cooldown, token)
if ok then
if spell_cooldown_values_are_secret(s, d, e, m) then
restricted = true
elseif s then
start_time = s
duration = d
enabled = e
mod_rate = m
readable = true
end
end
end
if retail_get_spell_cooldown and (not duration or duration == 0) then
local ok, info = pcall(retail_get_spell_cooldown, token)
if ok and type(info) == "table" then
local enabled_raw = info.isEnabled
if spell_cooldown_values_are_secret(info.startTime, info.duration, enabled_raw,
info.modRate) then
restricted = true
else
start_time = info.startTime
duration = info.duration
enabled = enabled_raw and 1 or 0
mod_rate = info.modRate
readable = true
end
end
end
if readable then
restricted = false
end
-- Cooldown restrictions (combat, encounter, challenge, PvP) are the only source of a
-- restricted read. On Mainline-code clients the duration object can still answer; on the
-- classic-line families no secret values exist, so this branch stays unreachable.
if restricted and st.is_mainline then
local fallback_start, fallback_duration = cooldown_duration_fallback(token)
if fallback_duration then
return fallback_start, fallback_duration, 1, 1
end
end
if restricted then
return 0, 0, 0, 0, true
end
return start_time or 0, duration or 0, enabled or 0, mod_rate or 0
end
-- Public wrapper: the classic four values, plus a fifth `restricted` value ONLY when the
-- cooldown could not be read at all right now (a restricted read and no readable fallback).
-- Every other read keeps the classic four-value arity exactly, so no classic-line caller
-- (Era/TBC/Wrath) can observe a shape change. A consumer that must not render "unknown" as
-- "ready" checks the fifth (nil == not restricted).
function api.GetSpellCooldown(spell, fallback_id)
if type(spell) ~= "number" and type(spell) ~= "string" then
if type(fallback_id) == "number" or type(fallback_id) == "string" then
spell = fallback_id
fallback_id = nil
else
return 0, 0, 0, 0
end
end
local start_time, duration, enabled, mod_rate, restricted = raw_query_spell_cooldown(spell)
if canaccessvalue(duration) then
if duration and duration > 0 then
return start_time, duration, enabled, mod_rate
end
end
if fallback_id and fallback_id ~= spell then
local fb_s, fb_d, fb_e, fb_m, fb_restricted = raw_query_spell_cooldown(fallback_id)
if canaccessvalue(fb_d) then
if fb_d and fb_d > 0 then
return fb_s, fb_d, fb_e, fb_m
end
end
if canaccessallvalues(start_time, fb_s) then
if start_time == 0 and fb_s and fb_s > 0 then
return fb_s, fb_d, fb_e, fb_m
end
end
if restricted then
-- Only a restricted primary defers to the fallback's verdict: a readable
-- fallback (zeros included) is an answer and clears the flag; a readable
-- primary is never demoted by a restricted alternate rank.
restricted = fb_restricted == true
end
end
if restricted then
return 0, 0, 0, 0, true
end
return start_time or 0, duration or 0, enabled or 0, mod_rate or 0
end
-- Remaining cooldown, restricted-aware (SEC-6, 2026-11-06): the shared shape the class
-- guides need so a restricted read is UNKNOWN, never "ready".
-- readable -> remaining_seconds, duration_seconds, false (idle reads 0, 0, false)
-- restricted -> nil, nil, true (fifth return of the
-- wrapper above; a readable fallback answers instead)
-- no clock -> nil, nil, false
-- remaining clamps at 0; it never turns a missing read into a zero.
function api.get_cooldown_remaining(spell, fallback_id)
local start_time, duration, _, _, restricted = api.GetSpellCooldown(spell, fallback_id)
if restricted == true then
return nil, nil, true
end
if type(start_time) ~= "number" or type(duration) ~= "number" then
return nil, nil, false
end
local now = api.get_time()
if type(now) ~= "number" then
return nil, nil, false
end
if not (canaccessvalue and canaccessvalue(start_time)) or not (canaccessvalue and canaccessvalue(duration)) or not (canaccessvalue and canaccessvalue(now)) then
return nil, nil, true
end
local remaining = start_time + duration - now
if remaining < 0 then
remaining = 0
end
return remaining, duration, false
end
-- Forever duration-object pass-through (2026-11-08, bench/forever_hud_api_2026-11-08.md) -----
-- WoW Forever hides cooldown timing in the restricted states (combat, encounter, challenge
-- mode, PvP): C_Spell.GetSpellCooldown then hands back a SpellCooldownInfo whose timing
-- fields are secret. C_Spell.GetSpellCooldownDuration carries NO SecretWhen* predicate, so
-- the LuaDurationObject it returns is a non-secret opaque handle whose VALUES may be secret.
-- A tainted addon may (a) hold that handle, (b) hand it to a native sink, and (c) read the
-- object's own HasSecretValues probe (documented ReturnsNeverSecret) - and must never read
-- a number out of it. The helpers below are Forever-only AND probe-gated: on every other
-- client they answer "no" so the existing numeric paths stay byte-identical.
-- The opaque duration object for a spell, or nil when this client cannot answer / is not a
-- Forever client / the call or the secrecy probe fails. The second return is the object's
-- own HasSecretValues() answer (a plain bool: true = the object was configured with secret
-- values, so its individual reads must not be used in Lua; nil = the probe is absent).
-- ignore_gcd defaults to false exactly like the client API: false carries the global
-- cooldown in the object, true describes the spell's own cooldown only.
function api.get_spell_cooldown_duration(spell, ignore_gcd)
if st.family ~= "FOREVER" or type(retail_get_spell_cooldown_duration) ~= "function" then
return nil
end
if type(spell) ~= "number" and type(spell) ~= "string" then
return nil
end
local ok, object = pcall(retail_get_spell_cooldown_duration, spell, ignore_gcd == true)
if not ok or object == nil then
return nil
end
local probe = object.HasSecretValues
if type(probe) ~= "function" then
return object
end
local probe_ok, has_secret_values = pcall(probe, object)
if not probe_ok or is_secret(has_secret_values) then
return nil
end
return object, has_secret_values == true
end
-- The two SpellCooldownInfo fields a HUD may branch on while cooldowns are restricted:
-- isOnGCD and isActive are NeverSecret = true (SpellSharedDocumentation.lua:25,26,30), so
-- they are plain booleans even when the table's timing fields are secret. Returns
-- (on_gcd, active); nil, nil = the client cannot answer, the call threw, or a field came
-- back secret (in which case nothing is compared). Only exact booleans are ever reported.
function api.get_spell_cooldown_state(spell)
if st.family ~= "FOREVER" or type(retail_get_spell_cooldown) ~= "function" then
return nil, nil
end
if type(spell) ~= "number" and type(spell) ~= "string" then
return nil, nil
end
local ok, info = pcall(retail_get_spell_cooldown, spell)
if not ok or type(info) ~= "table" then
return nil, nil
end
local fields_ok, on_gcd, active = pcall(function()
return info.isOnGCD, info.isActive
end)
if not fields_ok or is_secret(on_gcd) or is_secret(active) then
return nil, nil
end
return on_gcd == true, active == true
end
-- "Is this spell's cooldown secret right now", from the client's own documented predicate
-- (C_Secrets.ShouldSpellCooldownBeSecret, SecretPredicateAPIDocumentation.lua:171-186).
-- The answer is plain and safe to branch on. nil = the predicate is absent on this client.
function api.get_spell_cooldown_secrecy(spell)
if st.family ~= "FOREVER" or type(should_spell_cooldown_be_secret) ~= "function" then
return nil
end
if type(spell) ~= "number" and type(spell) ~= "string" then
return nil
end
local ok, secret = pcall(should_spell_cooldown_be_secret, spell)
if not ok or type(secret) ~= "boolean" then
return nil
end
return secret
end
-- A native duration-text binding (C_DurationUtil.CreateDurationTextBinding), or nil when
-- the client does not expose the surface. The binding formats a duration object itself:
-- call SetFontString/SetFormatter/SetDuration and never read the text back (GetFormattedText
-- is ConditionalSecret, and GetText turns secret once the Text aspect is attached).
function api.create_duration_text_binding()
if st.family ~= "FOREVER" or type(create_duration_text_binding) ~= "function" then
return nil
end
local ok, binding = pcall(create_duration_text_binding)
if not ok then
return nil
end
return binding
end
-- A seconds formatter configured with plain arguments to match the HUD's readable face as
-- closely as the native formatter allows: bare numbers (no unit letters), one decimal below
-- 3 s, whole seconds above, seconds kept as the largest interval band, truncation with a
-- rounded-up last unit (Blizzard's own aura-duration configuration). Every setter is
-- optional and pcall-guarded so an older build keeps a working default formatter.
-- A unitless human countdown formatter for the native text. The SecondsFormatter
-- always appends an interval unit ("4 Seconds" with the default full abbreviation);
-- the AbbreviatedNumberFormatter exposes the raw float ("2.518"). A NumericRuleFormatter
-- with ONE rule (threshold 0, step 1, rounding Down, format "%.0f") renders the truncated
-- whole second ("2"), matching the operator's integer countdown face. It is still fed
-- through the proven DurationTextBinding:SetFormatter path; no new binding surface.
function api.create_duration_number_formatter()
if st.family ~= "FOREVER" or type(create_numeric_rule_formatter) ~= "function" then
return nil
end
local enum = rawget(_G, "Enum")
local rounding = enum and enum.NumericRuleFormatRounding
local down = rounding and rounding.Down or 2 -- Enum.NumericRuleFormatRounding.Down
local ok, formatter = pcall(create_numeric_rule_formatter)
if not ok or formatter == nil then
return nil
end
local added = pcall(function()
formatter:AddBreakpoint({
threshold = 0,
step = 1,
rounding = down,
format = "%.0f",
})
end)
if not added then
return nil
end
return formatter
end
function api.create_seconds_formatter()
if st.family ~= "FOREVER" or type(create_seconds_formatter) ~= "function" then
return nil
end
local ok, formatter = pcall(create_seconds_formatter)
if not ok or formatter == nil then
return nil
end
local enum = rawget(_G, "Enum")
local abbreviation = enum and enum.SecondsFormatterAbbreviation
local interval = enum and enum.SecondsFormatterInterval
local rounding = enum and enum.SecondsFormatterRounding
pcall(function()
if abbreviation then
formatter:SetDefaultAbbreviation(abbreviation.None)
end
if interval then
formatter:SetMinInterval(interval.Seconds)
formatter:SetMaxInterval(interval.Seconds)
end
if rounding then
formatter:SetRounding(rounding.Truncate)
end
formatter:SetDesiredUnitCount(1)
formatter:SetCanRoundUpLastUnit(true)
formatter:SetMillisecondsThreshold(3)
end)
return formatter
end
-- A colour curve for the native countdown text: `warn_color` while the remaining duration
-- is under `warn_seconds`, `normal_color` above. The binding evaluates the curve against
-- the (possibly secret-valued) duration natively, so the addon never reads the number; the
-- points are the same shape Blizzard's aura pipeline and the sibling Forever HUD use.
-- Colours are colorRGBA tables in the 0-1 domain. Returns (curve, property) or nil, nil.
function api.create_duration_text_color_curve(warn_seconds, warn_color, normal_color)
if st.family ~= "FOREVER" or type(create_color_curve) ~= "function" then
return nil, nil
end
local enum = rawget(_G, "Enum")
local property = enum and enum.DurationTextBindingProperty
if type(property) ~= "table" then
return nil, nil
end
if rawget(property, "RemainingDuration") == nil then
return nil, nil
end
local function plain_color(color)
if type(color) ~= "table" then
return nil
end
local r, g, b = color.r or color[1], color.g or color[2], color.b or color[3]
local a = color.a or color[4] or 1
if type(r) ~= "number" or type(g) ~= "number" or type(b) ~= "number"
or type(a) ~= "number" then
return nil
end
return { r = r, g = g, b = b, a = a }
end
local warn = plain_color(warn_color)
local normal = plain_color(normal_color)
if warn == nil or normal == nil then
return nil, nil
end
local threshold = tonumber(warn_seconds) or 3
local ok, curve = pcall(create_color_curve)
if not ok or curve == nil then
return nil, nil
end
local points_ok = pcall(function()
curve:AddPoint(0, warn)
curve:AddPoint(threshold, warn)
curve:AddPoint(threshold + 0.01, normal)
curve:AddPoint(3600, normal)
end)
if not points_ok then
return nil, nil
end
return curve, property.RemainingDuration
end
-- Spell usability ------------------------------------------------------------------------
-- Whether a spell can be cast right now, and specifically whether it is unusable for lack
-- of resources (mana). Every probe shape returns (usable, insufficientPower): the C_Spell
-- form on Mainline and the newer classic clients, the classic IsSpellUsable global, then
-- the older IsUsableSpell. All three are read through _G: they are not in the annotation
-- set of every client family, where naming them directly would be an undefined-global /
-- undefined-field reference. No probe at all: nil, i.e. unknown - callers must treat
-- unknown as "no tint", never as a usable reading.
local spell_usable_probe
do
local c_spell = rawget(_G, "C_Spell")
if type(c_spell) == "table" and type(c_spell.IsSpellUsable) == "function" then
spell_usable_probe = c_spell.IsSpellUsable
elseif type(rawget(_G, "IsSpellUsable")) == "function" then
spell_usable_probe = rawget(_G, "IsSpellUsable")
elseif type(rawget(_G, "IsUsableSpell")) == "function" then
spell_usable_probe = rawget(_G, "IsUsableSpell")
end
end
function api.IsSpellUsable(spell)
if not spell_usable_probe then
return nil
end
local usable, insufficient = spell_usable_probe(spell)
-- A restricted reading reports unknown (nil), which every caller renders as "no
-- tint", never as a usable/insufficient claim.
if is_secret(usable) or is_secret(insufficient) then
return nil, nil
end
return usable, insufficient
end
-- Spell power costs ----------------------------------------------------------------------
-- Classic and retail both return an array of cost structs; entries have a .cost field.
-- Read through _G: the global, and the classic-only C_Spell fields below, are not in the
-- annotation set of Mainline-code clients, where naming them directly would be an
-- undefined-global / undefined-field reference.
local spell_api = rawget(_G, "C_Spell")
local get_spell_power_cost = _G.GetSpellPowerCost
or (spell_api and spell_api.GetSpellPowerCost)
-- Unknown client: a zero-cost entry of the expected shape instead of an error.
api.GetSpellPowerCost = get_spell_power_cost or function()
return { { cost = 0, minCost = 0 } }
end
-- Spell base cooldowns -------------------------------------------------------------------
-- Classic: GetSpellBaseCooldown(spell) returns the base cooldown in milliseconds.
-- Retail has no replacement; degrade to 0 rather than error.
if GetSpellBaseCooldown then
local raw_get_spell_base_cooldown = GetSpellBaseCooldown
api.GetSpellBaseCooldown = function(spell)
local first, second = raw_get_spell_base_cooldown(spell)
-- A restricted reading reports the absent-client shape (0, 0): callers treat a
-- non-positive base cooldown as "no value" and fall back to their own constant.
if is_secret(first) or is_secret(second) then
return 0, 0
end
return first, second
end
else
api.GetSpellBaseCooldown = function()
return 0, 0
end
end
-- Current spell --------------------------------------------------------------------------
-- Detects on-next-attack abilities queued for the current cast (Maul, Heroic Strike, ...).
-- The classic global is read through _G: it is absent on Mainline-code clients, and
-- naming it directly would be an undefined-global reference there.
local is_current_spell = _G.IsCurrentSpell
api.IsCurrentSpell = is_current_spell or (C_Spell and C_Spell.IsCurrentSpell) or function()
return false
end
-- Resources (rage, mana, energy) ---------------------------------------------------------
-- UnitPower / UnitPowerMax exist on every supported client (the modern ones prefer
-- UnitPowerType but do not remove the globals). Wrapped for the secret regime: a
-- restricted reading reports nil (unknown), which every caller's type() guard already
-- routes to its "cannot claim" branch. An unknown client keeps reporting 0 so a caller
-- can never error while comparing.
local legacy_unit_power = rawget(_G, "UnitPower")
local legacy_unit_power_max = rawget(_G, "UnitPowerMax")
if legacy_unit_power then
api.UnitPower = function(unit, power_type)
local value = legacy_unit_power(unit, power_type)
if is_secret(value) then
return nil
end
return value
end
else
api.UnitPower = function()
return 0
end
end
if legacy_unit_power_max then
api.UnitPowerMax = function(unit, power_type)
local value = legacy_unit_power_max(unit, power_type)
if is_secret(value) then
return nil
end
return value
end
else
api.UnitPowerMax = function()
return 0
end
end
-- Secret-SAFE power reader for widgets that can take a restricted value -----------------
-- UnitPower is SecretWhenUnitPowerRestricted and UnitPowerMax is
-- SecretWhenUnitPowerMaxRestricted on origin/forever
-- (Interface/AddOns/Blizzard_APIDocumentationGenerated/UnitDocumentation.lua:2732-2747 and
-- :2801-2824), so the bar cannot read them through api.UnitPower/api.UnitPowerMax above:
-- those nil a restricted value because every other consumer does arithmetic with it
-- (classes/*.lua resource gates). A StatusBar, however, is allowed to RECEIVE a secret:
-- SetMinMaxValues (SimpleStatusBarAPIDocumentation.lua:229-236) and SetValue (:354-361)
-- are SecretArguments = "AllowedWhenTainted" with SecretArgumentsAddAspect =
-- { Enum.SecretAspect.BarValue }, and Blizzard's own mana-bar update feeds the raw
-- UnitPower/UnitPowerMax straight into them with no Lua arithmetic
-- (Blizzard_UnitFrame/Mainline/UnitFrame.lua:948-970 on origin/forever). This reader is the
-- additive path for exactly that widget case: the raw values, never nil'd, plus a flag the
-- caller must use to skip every comparison, fraction and format on them. The flag is false
-- (never nil) on the classic clients, where issecretvalue is absent and no value is secret.
api.GetPlayerPower = function(power_type)
if not legacy_unit_power then
return nil, nil, false
end
local value = legacy_unit_power("player", power_type)
if not legacy_unit_power_max then
return value, nil, is_secret(value)
end
local max_value = legacy_unit_power_max("player", power_type)
return value, max_value, is_secret(value) or is_secret(max_value)
end
-- Unit power type: UnitPowerType(unit) returns the numeric power-type id (0 mana,
-- 1 rage, 3 energy, ...) and its token. The druid form label maps 3 -> Cat and
-- 1 -> Bear (reference GetDruidFormLabel, SuperSwingTimer_ClassMods.lua:4530-4538) and
-- the energy tick bar only shows for the energy power type. Unknown client: mana (0,
-- "MANA"), the safe default - every mapping then falls through to "Caster" and the
-- energy tick stays hidden. Read through _G for the same undefined-global reason.
local legacy_unit_power_type = rawget(_G, "UnitPowerType")
if legacy_unit_power_type then
api.UnitPowerType = function(unit)
local power_type, token = legacy_unit_power_type(unit)
-- A restricted reading reports unknown (nil), which every mapping falls through
-- as "Caster" / no energy tick - the same shape an absent client gets.
if is_secret(power_type) or is_secret(token) then
return nil
end
return power_type, token
end
else
api.UnitPowerType = function()
return 0, "MANA"
end
end
-- Health ---------------------------------------------------------------------------------
-- UnitHealth / UnitHealthMax exist on every supported client like the power reads above;
-- read through _G for the same undefined-global reason. A client that cannot answer
-- returns nil, which callers read as unknown health - never as zero. A restricted
-- (secret) reading degrades the same way.
local legacy_unit_health = rawget(_G, "UnitHealth")
local legacy_unit_health_max = rawget(_G, "UnitHealthMax")
if legacy_unit_health then
api.UnitHealth = function(unit)
local value = legacy_unit_health(unit)
if is_secret(value) then
return nil
end
return value
end
else
api.UnitHealth = function()
return nil
end
end
if legacy_unit_health_max then
api.UnitHealthMax = function(unit)
local value = legacy_unit_health_max(unit)
if is_secret(value) then
return nil
end
return value
end
else
api.UnitHealthMax = function()
return nil
end
end
-- Auras ----------------------------------------------------------------------------------
-- Classic shape: UnitAura(unit, index, filter) returns
-- name, icon, count, dispelName, duration, expirationTime, sourceUnit, isStealable,
-- nameplateShowPersonal, spellId, ...
-- Retail shape: C_UnitAuras.GetAuraDataByIndex returns an AuraData table. The field
-- order below matches Blizzard's own AuraUtil.UnpackAuraData back-compat mapping.
-- Aura entries are taken whole or not at all: one secret field makes the entry unusable
-- (consumers run arithmetic on durations/expirations, compare names and index spell-id
-- tables), and the existing "name == nil -> stop scanning" loops are the only degrade
-- they can consume, so a secret entry is returned as absent (nil) instead of per-field
-- nils. All three source paths are wrapped, including the classic-global pass-through.