--- @module MRE

--- AnimatedImagePlayer class for handling animated images in Lua
-- @type AnimatedImagePlayer
AnimatedImagePlayer = {}
AnimatedImagePlayer.__index = AnimatedImagePlayer

--- Constructor
-- @tparam string identifier
-- @tparam AnimatedImage animatedImage
-- @tparam WorldPoint2 position
-- @tparam number startTime
-- @tparam bool removeWhenFinished
function AnimatedImagePlayer:new(identifier, animatedImage, position, startTime, removeWhenFinished)
    local obj = {
        identifier = identifier,
        animatedImage = animatedImage,
        position = position,
        startTime = startTime or 0.0,
        currentFrameIndex = 1,
        hasFinished = false,
        removeWhenFinished = removeWhenFinished or false
    }
    setmetatable(obj, AnimatedImagePlayer)
    return obj
end

--- Update method to be called each frame with absolute timeSeconds
-- @tparam number timeSeconds
function AnimatedImagePlayer:update(timeSeconds)
    -- If not looping or if removed
    if self.hasFinished then
        return
    end
    
    if #self.animatedImage.frames == 0 then
        return
    end
    
    -- Calculate elapsed time since start (accounting for pauses)
    local elapsedTime = timeSeconds - self.startTime
    if elapsedTime < 0 then
        -- Animation scheduled for later
        return
    end
    
    -- Calculate time per frame
    local timePerFrame = 1.0 / self.animatedImage.fps
    
    -- Calculate which frame we should be on
    local targetFrameIndex = math.floor(elapsedTime / timePerFrame) + 1
    
    -- Handle looping or stopping at end
    if targetFrameIndex > #self.animatedImage.frames then
        if self.animatedImage.shouldLoop then
            -- For looping, use modulo to wrap around
            local totalFrames = #self.animatedImage.frames
            targetFrameIndex = ((targetFrameIndex - 1) % totalFrames) + 1
        else
            -- For non-looping, clamp to last frame and mark as finished
            targetFrameIndex = #self.animatedImage.frames
            self.hasFinished = true
            if self.removeWhenFinished then
                iconRenderer:removeIcon(self.identifier)
            end
        end
    end
    
    self.currentFrameIndex = targetFrameIndex
    
    -- Display current frame
    self:displayCurrentFrame()
end

--- Display the current frame
function AnimatedImagePlayer:displayCurrentFrame()
    if #self.animatedImage.frames > 0 then
        local currentFrame = self.animatedImage.frames[self.currentFrameIndex]
        iconRenderer:displayIcon(self.identifier, currentFrame, self.position)
    end
end

--- Restart back to the specified time
-- @tparam number currentTime
function AnimatedImagePlayer:restart(currentTime)
    self.startTime = currentTime or 0.0
    self.currentFrameIndex = 1
    self.hasFinished = false
end

--- Remove from the engine
function AnimatedImagePlayer:remove()
    self.hasFinished = true
    iconRenderer.removeIcon(self.identifier)
end

--- Set the position
-- @tparam WorldPoint2 newPosition
function AnimatedImagePlayer:setPosition(newPosition)
    self.position = newPosition
end
