AnimatedSprite.lua

-----------------------------------------------
--- Sprite class extension with support of  ---
--- imagetables and finite state machine,   ---
--- with json configuration and autoplay.   ---
---            By @Whitebrim   git.brim.ml  ---
-----------------------------------------------

-- You can find examples and docs at https://github.com/Whitebrim/AnimatedSprite/wiki
-- Comments use EmmyLua style

import 'CoreLibs/object'
import 'CoreLibs/sprites'
local gfx <const> = playdate.graphics
local function emptyFunc()end

class("AnimatedSprite").extends(gfx.sprite)

---@param imagetable table|string actual imagetable or path
---@param states? table If provided, calls `setStates(states)` after initialisation
---@param animate? boolean If `True`, then the animation of default state will start after initialisation. Default: `False`
function AnimatedSprite.new(imagetable, states, animate)
	return AnimatedSprite(imagetable, states, animate)
end

function AnimatedSprite:init(imagetable, states, animate)
	AnimatedSprite.super.init(self)

	---@type table
	if (type(imagetable) == "string") then
		imagetable = gfx.imagetable.new(imagetable)
	end
	self.imagetable = imagetable
	assert(self.imagetable, "Imagetable is nil. Check if it was loaded correctly.")

	self:add()

	self.globalFlip = gfx.kImageUnflipped
	self.defaultState = "default"
	self.states = {
		default = {
			name = "default",
			---@type integer|string
			firstFrameIndex = 1,
			framesCount = #self.imagetable,
			animationStartingFrame = 1,
			tickStep = 1,
			frameStep = 1,
			reverse = false,
			---@type boolean|integer
			loop = true,
			yoyo = false,
			flip = gfx.kImageUnflipped,
			xScale = 1,
			yScale = 1,
			nextAnimation = nil,

			onFrameChangedEvent = emptyFunc,
			onStateChangedEvent = emptyFunc,
			onLoopFinishedEvent = emptyFunc,
			onAnimationEndEvent = emptyFunc
		}
	}

	self._enabled = false
	self._currentFrame = 0 -- purposely
	self._ticks = 1
	self._previousTicks = 1
	self._loopsFinished = 0
	self._currentYoyoDirection = true

	if (states) then
		self:setStates(states)
	end

	if (animate) then
		self:playAnimation()
	end
end

local function drawFrame(self)
	local state = self.states[self.currentState]
	self:setImage(self._image, state.flip ~ self.globalFlip, state.xScale, state.yScale)
end

local function setImage(self)
	local frames = self.states[self.currentState].frames
	if (frames) then
		self._image = self.imagetable[frames[self._currentFrame]]
	else
		self._image = self.imagetable[self._currentFrame]
	end
end

---Start/resume the animation  
---If `currentState` is nil then `defaultState` will be choosen as current
function AnimatedSprite:playAnimation()

	local state = self.states[self.currentState]

	if (type(self.currentState) == 'nil') then
		self.currentState = self.defaultState
		state = self.states[self.currentState]
		self._currentFrame = state.animationStartingFrame + state.firstFrameIndex - 1
	end

	if (self._currentFrame == 0) then
		self._currentFrame = state.animationStartingFrame + state.firstFrameIndex - 1
	end

	self._enabled = true
	self._previousTicks = self._ticks
	setImage(self)
	drawFrame(self)
	if (state.framesCount == 1) then
		self._loopsFinished += 1
		state.onFrameChangedEvent(self)
		state.onLoopFinishedEvent(self)
	else
		state.onFrameChangedEvent(self)
	end
end

---Stop the animation without resetting
function AnimatedSprite:pauseAnimation()
	self._enabled = false
end

---Play the animation without resetting
function AnimatedSprite:resumeAnimation()
	self._enabled = true
end

---Play/Pause animation based on current state
function AnimatedSprite:toggleAnimation()
	if (self._enabled) then
		self:pauseAnimation()
	else
		self:resumeAnimation()
	end
end

---Stop and reset the animation  
---After calling `playAnimation` the animation will start from `defaultState` 
function AnimatedSprite:stopAnimation()
	self:pauseAnimation()
	self.currentState = nil
	self._currentFrame = 0 -- purposely
	self._ticks = 1
	self._previousTicks = self._ticks
	self._loopsFinished = 0
	self._currentYoyoDirection = true
end

local function addState(self, params)
	assert(params.name, "The animation state is unnamed!")
	if (self.defaultState == "default") then
		self.defaultState = params.name -- Init first added state as default
	end

	self.states[params.name] = {}
	local state = self.states[params.name]
	setmetatable(state, {__index = self.states.default})

	params = params or {}

	state.name = params.name
	if (params.frames ~= nil) then
		state["frames"] = params.frames -- Custom animation for non-sequential frames from the imagetable
		params.firstFrameIndex = 1
		params.framesCount = #params.frames
	end
	if (type(params.firstFrameIndex) == "string") then
		local thatState = self.states[params.firstFrameIndex]
		state["firstFrameIndex"] = thatState.firstFrameIndex + thatState.framesCount
	else
		state["firstFrameIndex"] = params.firstFrameIndex -- index in the imagetable for the firstFrame
	end
	state["framesCount"] = params.framesCount and params.framesCount or (self.states.default.framesCount - state.firstFrameIndex + 1) -- This state frames count
	state["nextAnimation"] = params.nextAnimation -- Animation to switch to after this finishes
	if (params.nextAnimation == nil) then
		state["loop"] = params.loop -- You can put in number of loops or true for endless loop
	else
		state["loop"] = params.loop or false
	end
	state["reverse"] = params.reverse -- You can reverse animation sequence
	state["animationStartingFrame"] = params.animationStartingFrame or (state.reverse and state.framesCount or 1) -- Frame to start the animation from
	state["tickStep"] = params.tickStep -- Speed of animation (2 = every second frame)
	state["frameStep"] = params.frameStep -- Number of images to skip on next frame
	state["yoyo"] = params.yoyo -- Ping-pong animation (from 1 to n to 1 to n)
	state["flip"] = params.flip -- You can set up flip mode, read Playdate SDK Docs for more info
	state["xScale"] = params.xScale -- Optional scale for horizontal axis
	state["yScale"] = params.yScale -- Optional scale for vertical axis

	state["onFrameChangedEvent"] = params.onFrameChangedEvent -- Event that will be raised when animation moves to the next frame
	state["onStateChangedEvent"] = params.onStateChangedEvent -- Event that will be raised when animation state changes
	state["onLoopFinishedEvent"] = params.onLoopFinishedEvent -- Event that will be raised when animation changes to the final frame
	state["onAnimationEndEvent"] = params.onAnimationEndEvent -- Event that will be raised after animation in this state ends

	return state
end

---Parse `json` file with animation configuration
---@param path string Path to the file
---@return table config You can use it in `setStates(states)`
function AnimatedSprite.loadStates(path)
	return assert(json.decodeFile(path), "Requested JSON parse failed. Path: " .. path)
end

---Get imagetable's frame index that is currently displayed
---@return integer index Current frame index
function AnimatedSprite:getCurrentFrameIndex()
	if (self.currentState and self.states[self.currentState].frames) then
		return self.states[self.currentState].frames[self._currentFrame]
	else
		return self._currentFrame
	end
end

---Get the current frame's local index in the state  
---I.e. 1, 2, 3, N, where N = number of frames in this state  
---Also works if `frames` property was provided
---@return integer index Current frame local index
function AnimatedSprite:getCurrentFrameLocalIndex()
	return self._currentFrame - self.states[self.currentState].firstFrameIndex + 1
end

---Get reference to the current state
---@return table state Reference to the current state
function AnimatedSprite:getCurrentState()
	return self.states[self.currentState]
end

---Get reference to the current states
---@return table states Reference to the current states
function AnimatedSprite:getLocalStates()
	return self.states
end

---Get copy of the states
---@return table states Deepcopy of the current states
function AnimatedSprite:copyLocalStates()
	return table.deepcopy(self.states)
end

---Add all states from the `states` to the current state machine (overwrites values in case of conflicts)
---@param states table State machine state list, you can get one by calling `loadStates`
---@param animate? boolean If `True`, then the animation of default/current state will start immediately after. Default: `False`
---@param defaultState? string If provided, changes default state
function AnimatedSprite:setStates(states, animate, defaultState)
	local statesCount = #states

	local function proceedState(state)
		if (state.name ~= "default") then
			addState(self, state)
		else
			local default = self.states.default
			for key, value in pairs(state) do
				default[key] = value
			end
		end
	end

	if (statesCount == 0) then
		proceedState(states)
		if (defaultState) then
			self.defaultState = defaultState
		end
		if (animate) then
			self:playAnimation()
		end
		return
	end

	for i = 1, statesCount do
		proceedState(states[i])
	end
	if (defaultState) then
		self.defaultState = defaultState
	end
	if (animate) then
		self:playAnimation()
	end
end

---Add new state to the state machine
---@param name string Name of the state, should be unique, used as id
---@param startFrame? integer Index of the first frame in the imagetable (starts from 1). Default: `1` (from states.default)
---@param endFrame? integer Index of the last frame in the imagetable. Default: last frame (from states.default)
---@param params? table See examples
---@param animate? boolean If `True`, then the animation of this state will start immediately after. Default: `False`
function AnimatedSprite:addState(name, startFrame, endFrame, params, animate)
	params = params or {}
	params.firstFrameIndex = startFrame or 1
	params.framesCount = endFrame and (endFrame - params.firstFrameIndex + 1) or nil
	params.name = name

	addState(self, params)

	if (animate) then
		self.currentState = name
		self:playAnimation()
	end

	return {
		asDefault = function ()
			self.defaultState = name
		end
	}
end

---Change current state to an existing state
---@param name string New state name
---@param play? boolean If new animation should be played right away. Default: `True`
function AnimatedSprite:changeState(name, play)
	if (name == self.currentState) then
		return
	end
	play = type(play) == "nil" and true or play
	local state = self.states[name]
	assert (state, "There's no state named \""..name.."\".")
	self.currentState = name
	self._currentFrame = 0 -- purposely
	self._loopsFinished = 0
	self._currentYoyoDirection = true
	state.onStateChangedEvent(self)
	if (play) then
		self:playAnimation()
	end
end

---Change current state to an existing state and start from selected frame  
---If new state is the same as current state, nothing will change
---@param name string New state name
---@param frameIndex integer Local frame index of this state. Indexing starts from 1. Default: `1`
---@param play? boolean If new animation should be played right away. Default: `True`
function AnimatedSprite:changeStateAndSelectFrame(name, frameIndex, play)
	if (name == self.currentState) then
		return
	end
	play = type(play) == "nil" and true or play
	frameIndex = frameIndex or 1
	local state = self.states[name]
	assert (state, "There's no state named \""..name.."\".")
	self.currentState = name
	self._currentFrame = state.firstFrameIndex + frameIndex - 1
	self._loopsFinished = 0
	self._currentYoyoDirection = true
	state.onStateChangedEvent(self)
	if (play) then
		self:playAnimation()
	end
end

---Force animation state machine to switch to the next state
---@param instant? boolean If `False` change will be performed after the final frame of this loop iteration. Default: `True`
---@param state? string Name of the state to change to. If not provided, animator will try to change to the next animation, else stop the animation
function AnimatedSprite:forceNextAnimation(instant, state)
	instant = type(instant) == "nil" and true or instant
	local currentState = self.states[self.currentState]
	self.forcedState = state

	if (instant) then
		self.forcedSwitchOnLoop = nil
		currentState.onAnimationEndEvent(self)
		if (currentState.name == self.currentState) then -- If state was not changed during the event then proceed
			if (type(self.forcedState) == "string") then
				self:changeState(self.forcedState)
				self.forcedState = nil
			elseif (currentState.nextAnimation) then
				self:changeState(currentState.nextAnimation)
			else
				self:stopAnimation()
			end
		end
	else
		self.forcedSwitchOnLoop = self._loopsFinished + 1
	end
end

---Set default state
---@param name string Name of an existing state
function AnimatedSprite:setDefaultState(name)
	assert (self.states[name], "State name is nil.")
	self.defaultState = name
end

---Print all states from this state machine to the console for debug purposes
function AnimatedSprite:printAllStates()
	printTable(self.states)
end

---Procees the animation to the next step without redrawing the sprite
local function processAnimation(self)
	local state = self.states[self.currentState]

	local function changeFrame(value)
		value += state.firstFrameIndex
		self._currentFrame = value
		state.onFrameChangedEvent(self)
	end

	local reverse = state.reverse
	local frame = self._currentFrame - state.firstFrameIndex
	local framesCount = state.framesCount
	local frameStep = state.frameStep

	if (self._currentFrame == 0) then -- true only after changing state
		self._currentFrame = state.animationStartingFrame + state.firstFrameIndex - 1
		if (framesCount == 1) then
			self._loopsFinished += 1
			state.onFrameChangedEvent(self)
			state.onLoopFinishedEvent(self)
			return
		else
			state.onFrameChangedEvent(self)
		end
		setImage(self)
		return
	end

	if (framesCount == 1) then -- if this state is only 1 frame long
		self._loopsFinished += 1
		state.onFrameChangedEvent(self)
		state.onLoopFinishedEvent(self)
		return
	end

	if (state.yoyo) then
		if (reverse ~= self._currentYoyoDirection) then
			if (frame + frameStep + 1 < framesCount) then
				changeFrame(frame + frameStep)
			else
				if (frame ~= framesCount - 1) then
					self._loopsFinished += 1
					changeFrame(2 * framesCount - frame - frameStep - 2)
					state.onLoopFinishedEvent(self)
				else
					changeFrame(2 * framesCount - frame - frameStep - 2)
				end
				self._currentYoyoDirection = not self._currentYoyoDirection
			end
		else
			if (frame - frameStep > 0) then
				changeFrame(frame - frameStep)
			else
				if (frame ~= 0) then
					self._loopsFinished += 1
					changeFrame(frameStep - frame)
					state.onLoopFinishedEvent(self)
				else
					changeFrame(frameStep - frame)
				end
				self._currentYoyoDirection = not self._currentYoyoDirection
			end
		end
	else
		if (reverse) then
			if (frame - frameStep > 0) then
				changeFrame(frame - frameStep)
			else
				if (frame ~= 0) then
					self._loopsFinished += 1
					changeFrame((frame - frameStep) % framesCount)
					state.onLoopFinishedEvent(self)
				else
					changeFrame((frame - frameStep) % framesCount)
				end
			end
		else
			if (frame + frameStep + 1 < framesCount) then
				changeFrame(frame + frameStep)
			else
				if (frame ~= framesCount - 1) then
					self._loopsFinished += 1
					changeFrame((frame + frameStep) % framesCount)
					state.onLoopFinishedEvent(self)
				else
					changeFrame((frame + frameStep) % framesCount)
				end
			end
		end
	end

	setImage(self)
end

---Called by default in the `:update()` function.  
---Must be called once per frame if you overwrite `:update()`.  
---Invoke manually to move the animation to the next frame.
function AnimatedSprite:updateAnimation()
	if (self._enabled) then
		self._ticks += 1
		if ((self._ticks - self._previousTicks) >= self.states[self.currentState].tickStep) then
			local state = self.states[self.currentState]
			local loop = state.loop
			local loopsFinished = self._loopsFinished
			if (type(loop) == "number" and loop <= loopsFinished or
				type(loop) == "boolean" and not loop and loopsFinished >= 1 or
				self.forcedSwitchOnLoop == loopsFinished) then
				self:forceNextAnimation(true)
				return
			end
			processAnimation(self)
			drawFrame(self)
			self._previousTicks += state.tickStep
		end
	end
end

function AnimatedSprite:update()
	self:updateAnimation()
end