-- YataiDON-HSS child-skin addition (no parent counterpart).
--
-- ============================================================================
-- ROUND 96 (r96-soulgauge-cellgrid): this object NO LONGER DRAWS ANYTHING.
--
-- From ROUND 6 to ROUND 80 this file redrew the ordinary soul gauge's fill on
-- top of the engine's own, because the engine drew on an 87-cell / 12 px grid
-- while the cabinet's grid is 50 cells x 21 px, and because gauge.cpp hardcoded
-- the separator overlay at fade 0.15 where the cabinet uses Amul 77/256.
-- Redrawing on top meant this file also had to ERASE the engine's overshoot,
-- guess the difficulty from the is_clear flip so it knew which plate to erase
-- with, re-composite the separator strength in two passes, and put the
-- クリア caption back on top afterwards.
--
-- Every one of those was a workaround for the engine's grid, and the last of
-- them was also the defect the user kept reporting
-- (「soul gauge還是有錯，他的新增格數應該是一格一格，他看起來有gap」):
-- `erase()` repainted only 24 px past the arcade fill edge, but the engine's
-- own gauge-up flash `<pn>p_bar_fade` (a 24 px SOLID slab based at texture.json
-- x 732) landed at `732 + 12*floor(87*progress)`, i.e. up to
--     18 + 12*floor(87p) - 21*floor(50p) = +33 px
-- past the true cell boundary. What survived erase() was a detached,
-- wrong-height orange fragment one cell ahead of the fill, with unfilled groove
-- in between -- the "gap". Measured live at soul 945 / 2788 / 5996 as
-- +30 / +33 / +33 px (scratchpad/r96/scan.py, crop
-- scratchpad/r96/crops/live_a_58_edge.png). Worse, past screen x 1335 with the
-- difficulty still unknown, `erase()`'s PLATE_SHARED_END clamp made its width
-- <= 0 and it returned WITHOUT ERASING AT ALL, so the engine's raw fill
-- overshoot showed too.
--
-- CORRECTION TO ROUND 19: the comment that used to stand in this file --
-- "The engine's own copy is otherwise harmless (this file's opaque redraw +
-- erase() covers it)" -- was wrong, and had been wrong since ROUND 19. It is
-- the direct cause of the report ROUND 96 fixed. ROUND 34's and ROUND 37's
-- findings about this file's OWN flash placement and about
-- Background:handle_gauge's argument count were correct and are preserved in
-- MAPPING_hud.md; they simply no longer have any code to apply to.
--
-- ROUND 96 moved the grid into the engine instead: `Gauge::draw()`'s NORMAL
-- branch now draws the fill, the transition cell, the clear-zone tiles and the
-- flash on the cabinet's own 50-cell / 21 px grid (X0 = 738, clear cell
-- 30/35/40 by clear-zone art tier), and draws the separator overlay once at the
-- cabinet's real Amul 77/256 = 0.30078. It knows the true difficulty, so the
-- plate-guessing goes away as well. There is nothing left for a skin-side
-- overlay to correct, and drawing one again can only re-introduce seams.
--
-- What is kept: the `handle_gauge` / `draw_one` hook shape (background.lua and
-- Player::draw both call them, and a future round may want the hook), and
-- ROUND 43's texture-id-contamination unload -- see below.
-- ============================================================================

local ArcadeGauge   = {}
ArcadeGauge.__index = ArcadeGauge

function ArcadeGauge.new()
    local self = setmetatable({}, ArcadeGauge)
    self.p     = {}

    -- ROUND 43 (r43-gauge-contamination): the engine's script-side texture id
    -- map is keyed on "<subset-leaf>/<name>" WITHOUT the screen name
    -- (texture.cpp load_folder: `map_key = subset_key + "/" + tex_name`), so
    -- "game/gauge/1p_unfilled_hard" and "result/gauge/1p_unfilled_hard" are the
    -- SAME id -- and whichever folder loaded most recently owns the
    -- TextureObject, including its texture.json PLACEMENT bases. This file no
    -- longer draws gauge textures through the script wrapper, so it can no
    -- longer BE the victim, but the unload is kept: it costs one lookup at
    -- construction and it keeps result_player.lua's own gauge draw honest if
    -- any other script starts loading "game/gauge" later. (The C++ screens draw
    -- through a separate TextureWrapper instance and are unaffected either way.)
    tex.unload_folder("result", "gauge")
    tex.unload_folder("game", "gauge")

    return self
end

-- ROUND 37 (r37-duplicate-gauge-clear): `Background::handle_gauge`
-- (background.cpp:111) passes SIX arguments -- (player_num, progress, is_clear,
-- is_rainbow, clear_progress, flash). The formal list must keep matching it:
-- Lua binds positionally and silently drops extras, and an earlier mismatch
-- here made `flash` receive `clear_progress` for many rounds.
--
-- Nothing here draws any more, so this only records state for anyone who wants
-- to read it (and keeps the hook alive so a future round has somewhere to put
-- skin-side gauge behaviour -- e.g. the cabinet's per-cell additive `glow_N`,
-- still unimplemented; see MAPPING_hud.md ROUND 80 "Known gap").
function ArcadeGauge:handle_gauge(player_num, progress, is_clear, is_rainbow, clear_progress, flash)
    if player_num ~= 1 and player_num ~= 2 then return end
    local g = self.p[player_num]
    if not g then g = {}; self.p[player_num] = g end
    g.progress       = progress or 0
    g.is_clear       = is_clear and true or false
    g.is_rainbow     = is_rainbow and true or false
    g.clear_progress = clear_progress or 1
    g.flash          = flash or 0
end

-- ROUND 80 (r80-gauge-layering-recheck) put this call in Player::draw(), right
-- after that lane's Gauge::draw(), so a skin-side gauge layer lands in its own
-- draw slot instead of on top of the whole HUD from draw_fore(). The hook is
-- kept (and still called) even though it now draws nothing, so that z-order
-- placement does not have to be rediscovered.
function ArcadeGauge:draw_one(player_num) end
function ArcadeGauge:draw() end

return ArcadeGauge