297 lines
12 KiB
Lua
297 lines
12 KiB
Lua
--- Animation states using a spritesheet/imagetable. Ideal for use with `NobleSprite` objects. Suitable for other uses as well.
|
|
-- @module Noble.Animation
|
|
--
|
|
|
|
Noble.Animation = {}
|
|
|
|
--- Setup
|
|
-- @section setup
|
|
|
|
--- Create a new animation "state machine". This function is called automatically when creating a new `NobleSprite`.
|
|
-- @string __view This can be: the path to a spritesheet image file or an image table object (`Graphics.imagetable`). See Playdate SDK docs for imagetable file naming conventions.
|
|
-- @return `animation`, a new animation object.
|
|
-- @usage
|
|
-- local myHero = MyHero("path/to/spritesheet")
|
|
-- @usage
|
|
-- -- When extending NobleSprite (recommended), you don't call Noble.Animation.new(),
|
|
-- -- but you do feed its __view argument into MySprite.super.init()...
|
|
-- MyHero = {}
|
|
-- class("MyHero").extends(NobleSprite)
|
|
--
|
|
-- function MyHero:init()
|
|
-- MyHero.super.init(self, "assets/images/Hero")
|
|
-- -- ...
|
|
-- -- A new NobleSprite creates a Noble.Animation object named "self.animation"
|
|
-- self.animation:addState("idle", 1, 30)
|
|
-- self.animation:addState("jump", 31, 34, "float")
|
|
-- self.animation:addState("float", 35, 45)
|
|
-- self.animation:addState("turn", 46, 55, "idle")
|
|
-- self.animation:addState("walk", 56, 65)
|
|
-- -- ...
|
|
-- end
|
|
-- @usage
|
|
-- local myAnimation = Noble.Animation.new("path/to/spritesheet")
|
|
-- @usage
|
|
-- -- When extending playdate.graphics.Sprite, Noble.Animation.new() must be called manually...
|
|
-- MyHero = {}
|
|
-- class("MyHero").extends(Graphics.sprite)
|
|
--
|
|
-- function MyHero:init()
|
|
-- MyHero.super.init(self)
|
|
-- -- ...
|
|
-- self.animation = Noble.Animation.new("assets/images/Hero")
|
|
-- self.animation:addState("idle", 1, 30)
|
|
-- self.animation:addState("jump", 31, 34, "float")
|
|
-- self.animation:addState("float", 35, 45)
|
|
-- self.animation:addState("turn", 46, 55, "idle")
|
|
-- self.animation:addState("walk", 56, 65)
|
|
-- -- ...
|
|
-- end
|
|
-- @see NobleSprite:init
|
|
function Noble.Animation.new(__view)
|
|
|
|
local animation = {}
|
|
|
|
--- Properties
|
|
-- @section properties
|
|
|
|
--- The currently set animation state.
|
|
--
|
|
-- This is intended as `read-only`. You should not modify this property directly.
|
|
-- @see setState
|
|
animation.current = nil
|
|
|
|
--- The name of the current animation state. Calling this instead of `animation.current.name` is <em>just</em> a little faster.
|
|
--
|
|
-- This is intended as `read-only`. You should not modify this property directly.
|
|
animation.currentName = nil
|
|
|
|
--- The current frame of the animation. This is the index of the imagetable, not the frame of the current state.
|
|
--
|
|
-- Most of the time, you should not modify this directly, although you can if you're feeling saucy and are prepared for unpredictable results.
|
|
-- @see draw
|
|
animation.currentFrame = 1
|
|
|
|
--- This controls the flipping of the image when drawing. DIRECTION_RIGHT is unflipped, DIRECTION_LEFT is flipped on the X axis.
|
|
-- @usage
|
|
-- function MyHero:goLeft()
|
|
-- self.animation.direction = Noble.Animation.DIRECTION_LEFT
|
|
-- -- ...
|
|
-- end
|
|
animation.direction = Noble.Animation.DIRECTION_RIGHT
|
|
|
|
--- This animation's spritesheet. You can replace this with another `playdate.graphics.imagetable` object, but generally you would not want to.
|
|
-- @see new
|
|
if (type(__view) == "userdata") then
|
|
animation.imageTable = __view
|
|
else
|
|
animation.imageTable = Graphics.imagetable.new(__view)
|
|
end
|
|
-- The current count of frame durations. This is used to determine when to advance to the next frame.
|
|
animation.frameDurationCount = 1
|
|
-- The previous number of frame durations in the animation
|
|
animation.previousFrameDurationCount = 1
|
|
|
|
local empty = true
|
|
|
|
--- Setup
|
|
-- @section setup
|
|
|
|
--- Add an animation state. The first state added will be the default set for this animation.
|
|
--
|
|
-- <strong>NOTE:</strong> Added states are first-degree member objects of your Noble.Animation object, so do not use names of already existing methods/properties ("current", "draw", etc.).
|
|
-- @string __name The name of the animation, this is also used as the key for the animation.
|
|
-- @int __startFrame This is the first frame of this animation in the imagetable/spritesheet
|
|
-- @int __endFrame This is the final frame of this animation in the imagetable/spritesheet
|
|
-- @string[optional] __next By default, animation states will loop, but if you want to sequence an animation, enter the name of the next state here.
|
|
-- @bool[opt=true] __loop If you want a state to "freeze" on its final frame, instead of looping, enter `false` here.
|
|
-- @param[optional] __onComplete This function will run when this animation is complete. Be careful when using this on a looping animation!
|
|
-- @int[opt=1] __frameDuration This is the number of ticks between each frame in this animation. If not specified, it will be set to 1.
|
|
-- @usage
|
|
-- -- You can reference an animation's state's properties using bog-standard lua syntax:
|
|
--
|
|
-- animation.idle.startFrame -- 30
|
|
-- animation.walk.endFrame -- 65
|
|
-- animation.["walk"].endFrame -- 65
|
|
-- animation.jump.name -- "jump"
|
|
-- animation.["jump"].next -- "float"
|
|
-- animation.idle.next -- nil
|
|
function animation:addState(__name, __startFrame, __endFrame, __next, __loop, __onComplete, __frameDuration)
|
|
|
|
local loop = true
|
|
local frameDuration = 1
|
|
if (__loop ~= nil) then loop = __loop end
|
|
if(__frameDuration ~= nil) then frameDuration = __frameDuration end
|
|
self[__name] = {
|
|
name = __name,
|
|
startFrame = __startFrame,
|
|
endFrame = __endFrame,
|
|
next = __next,
|
|
loop = loop,
|
|
onComplete = __onComplete,
|
|
frameDuration = frameDuration,
|
|
}
|
|
|
|
-- Set this animation state as default if it is the first one added.
|
|
if (empty == true) then
|
|
empty = false
|
|
self.currentFrame = __startFrame
|
|
self.current = self[__name]
|
|
self.currentName = __name
|
|
self.frameDuration = frameDuration
|
|
end
|
|
|
|
end
|
|
|
|
--- Methods
|
|
-- @section methods
|
|
|
|
--- Sets the current animation state. This can be run in a object's `update` method because it only changes the animation state if the new state is different from the current one.
|
|
-- @tparam string|Noble.Animation __animationState The name of the animation to set. You can pass the name of the state, or the object itself.
|
|
-- @bool[opt=false] __continuous Set to true if your new state's frames line up with the previous one's, i.e.: two walk cycles but one is wearing a cute hat!
|
|
-- @tparam string|Noble.Animation __unlessThisState If this state is the current state, do not set the new one.
|
|
-- @usage animation:setState("walk")
|
|
-- @usage animation:setState(animation.walk)
|
|
-- @usage
|
|
-- animation:setState(animation.walkNoHat)
|
|
-- --
|
|
-- animation:setState(animation.walkYesHat, true)
|
|
-- @usage
|
|
-- function MyHero:update()
|
|
-- -- Input
|
|
-- -- ...
|
|
--
|
|
-- -- Physics/collisions
|
|
-- -- ...
|
|
--
|
|
-- -- Animation states
|
|
-- if (grounded) then
|
|
-- if (turning) then
|
|
-- self.animation:setState(self.animation.turn)
|
|
-- elseif (math.abs(self.velocity.x) > 15) then
|
|
-- self.animation:setState(self.animation.walk, false, self.animation.turn)
|
|
-- else
|
|
-- self.animation:setState(self.animation.idle, false, self.animation.turn)
|
|
-- end
|
|
-- else
|
|
-- self.animation:setState(self.animation.jump, false, self.animation.float)
|
|
-- end
|
|
--
|
|
-- groundedLastFrame = grounded
|
|
-- end
|
|
function animation:setState(__animationState, __continuous, __unlessThisState)
|
|
|
|
if (__unlessThisState ~= nil) then
|
|
if (type(__unlessThisState) == "string") then
|
|
if (self.currentName == __unlessThisState) then return end
|
|
elseif (type(__unlessThisState) == "table") then
|
|
if (self.current == __unlessThisState) then return end
|
|
end
|
|
end
|
|
|
|
local newState = nil
|
|
|
|
if (type(__animationState) == "string") then
|
|
if (self.currentName == __animationState) then return end
|
|
newState = self[__animationState]
|
|
self.currentName = __animationState
|
|
elseif (type(__animationState) == "table") then
|
|
if (self.current == __animationState) then return end
|
|
newState = __animationState
|
|
self.currentName = __animationState.name
|
|
end
|
|
|
|
local continuous = Utilities.handleOptionalBoolean(__continuous, false)
|
|
|
|
if (continuous) then
|
|
local localFrame = self.currentFrame - self.current.startFrame
|
|
self.currentFrame = newState.startFrame + localFrame
|
|
else
|
|
self.currentFrame = newState.startFrame
|
|
end
|
|
|
|
self.current = newState
|
|
end
|
|
|
|
--- Draw the current frame.
|
|
--
|
|
-- When attached to a NobleSprite, this is called by `NobleSprite:draw()` when added to a scene. For non-NobleSprite sprites, put this method inside your sprite's `draw()` method, or inside @{NobleScene:update|NobleScene:update}.
|
|
-- @number[opt=0] __x
|
|
-- @number[opt=0] __y
|
|
-- @bool[opt=true] __advance Advances to the next frame after drawing this one. Noble.Animation is frame-based, not "delta time"-based, so its speed is dependent on your game's framerate.
|
|
-- @usage
|
|
-- function MySprite:draw()
|
|
-- animation:draw()
|
|
-- end
|
|
-- @usage
|
|
-- function MyScene:update()
|
|
-- animation:draw(100,100)
|
|
-- end
|
|
function animation:draw(__x, __y, __advance)
|
|
|
|
--print(self.currentName .. " > " .. self.currentFrame .. " >> " .. tostring(self.current.loop))
|
|
|
|
if (__advance == nil) then __advance = true end
|
|
|
|
if(self.currentFrame < self.current.startFrame or self.currentFrame > self.current.endFrame + 1) then
|
|
self.currentFrame = self.current.startFrame -- Error correction.
|
|
elseif(self.currentFrame == self.current.endFrame + 1) then -- End frame behavior.
|
|
if (self.current.next ~= nil) then
|
|
self.currentFrame = self.current.next.startFrame -- Set to first frame of next animation.
|
|
self.frameDurationCount = 1 -- Reset ticks.
|
|
self.previousFrameDurationCount = self.frameDuration
|
|
self:setState(self.current.next) -- Set next animation state.
|
|
elseif (self.current.loop == true) then
|
|
self.currentFrame = self.current.startFrame -- Loop animation state. (TO-DO: account for continuous somehow?)
|
|
self.frameDurationCount = 1 -- Reset ticks.
|
|
self.previousFrameDurationCount = self.frameDuration
|
|
elseif(__advance) then
|
|
self.currentFrame = self.currentFrame - 1 -- Undo advance frame because we want to draw the same frame again.
|
|
end
|
|
|
|
if (self.current.onComplete ~= nil) then
|
|
self.current.onComplete()
|
|
end
|
|
end
|
|
|
|
local x = __x or 0
|
|
local y = __y or 0
|
|
self.imageTable:drawImage(self.currentFrame, x, y, self.direction)
|
|
|
|
if (__advance == true) then
|
|
self.frameDurationCount += 1
|
|
if((self.frameDurationCount - self.previousFrameDurationCount) >= self.current.frameDuration) then
|
|
self.currentFrame = self.currentFrame + 1
|
|
self.previousFrameDurationCount += self.current.frameDuration
|
|
end
|
|
end
|
|
--previousAnimationName = self.currentName
|
|
end
|
|
|
|
--- Sometimes, you just want to draw a specific frame.
|
|
-- Use this for objects or sprites that you want to control outside of update loops, such as score counters, flipbook-style objects that respond to player input, etc.
|
|
-- @int __frameNumber The frame to draw from the current state. This is not an imagetable index. Entering `1` will draw the selected state's `startFrame`.
|
|
-- @string[opt=self.currentName] __stateName The specific state to pull the __frameNumber from.
|
|
-- @number[opt=0] __x
|
|
-- @number[opt=0] __y
|
|
-- @param[opt=self.direction] __direction Override the current direction.
|
|
function animation:drawFrame(__frameNumber, __stateName, __x, __y, __direction)
|
|
local x = __x or 0
|
|
local y = __y or 0
|
|
local stateName = __stateName or self.currentName
|
|
local direction = __direction or self.direction
|
|
local frameNumber = self[stateName].startFrame - 1 + __frameNumber
|
|
self.imageTable:drawImage(frameNumber, x, y, direction)
|
|
end
|
|
|
|
return animation
|
|
end
|
|
|
|
--- Constants
|
|
-- @section constants
|
|
|
|
--- A re-contextualized instance of `playdate.graphics.kImageUnflipped`
|
|
Noble.Animation.DIRECTION_RIGHT = Graphics.kImageUnflipped
|
|
--- A re-contextualized instance of `playdate.graphics.kImageFlippedX`
|
|
Noble.Animation.DIRECTION_LEFT = Graphics.kImageFlippedX
|