Noble.Animation

Animation states using a spritesheet/imagetable.

Ideal for use with NobleSprite objects. Suitable for other uses as well.

Setup

Noble.Animation.new(__view)
Create a new animation "state machine". This function is called automatically when creating a new NobleSprite.

Parameters

  • __view string
    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.

Returns

    animation, a new animation object.

See

Usage

local myHero = MyHero("path/to/spritesheet")
-- 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
local myAnimation = Noble.Animation.new("path/to/spritesheet")
-- 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
animation:addState(__name, __startFrame, __endFrame, __next[, __loop=true], __onComplete[, __frameDuration=1])
Add an animation state. The first state added will be the default set for this animation.

NOTE: 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.).

Parameters

  • __name string
    The name of the animation, this is also used as the key for the animation.
  • __startFrame integer
    This is the first frame of this animation in the imagetable/spritesheet
  • __endFrame integer
    This is the final frame of this animation in the imagetable/spritesheet
  • __next string
    By default, animation states will loop, but if you want to sequence an animation, enter the name of the next state here.
  • __loop boolean = true (default)
    If you want a state to "freeze" on its final frame, instead of looping, enter false here.
  • __onComplete
    This function will run when this animation is complete. Be careful when using this on a looping animation!
  • __frameDuration integer = 1 (default)
    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

Properties

animation.current
The currently set animation state.

This is intended as read-only. You should not modify this property directly.

See

animation.currentName
The name of the current animation state. Calling this instead of animation.current.name is just a little faster.

This is intended as read-only. You should not modify this property directly.

animation.currentFrame
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

animation.direction
This controls the flipping of the image when drawing. DIRECTIONRIGHT is unflipped, DIRECTIONLEFT is flipped on the X axis.

Usage

function MyHero:goLeft()
	self.animation.direction = Noble.Animation.DIRECTION_LEFT
	-- ...
end

Methods

animation:setState(__animationState[, __continuous=false], __unlessThisState)
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.

Parameters

  • __animationState string or Noble.Animation
    The name of the animation to set. You can pass the name of the state, or the object itself.
  • __continuous boolean = false (default)
    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!
  • __unlessThisState string or Noble.Animation
    If this state is the current state, do not set the new one.

Usage

animation:setState("walk")
animation:setState(animation.walk)
animation:setState(animation.walkNoHat)
--
animation:setState(animation.walkYesHat, true)
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
animation:draw([__x=0[, __y=0[, __advance=true]]])
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.

Parameters

  • __x number = 0 (default)
  • __y number = 0 (default)
  • __advance boolean = true (default)
    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
function MyScene:update()
	animation:draw(100,100)
end
animation:drawFrame(__frameNumber[, __stateName=self.currentName[, __x=0[, __y=0[, __direction=self.direction]]]])
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.

Parameters

  • __frameNumber integer
    The frame to draw from the current state. This is not an imagetable index. Entering 1 will draw the selected state's startFrame.
  • __stateName string = self.currentName (default)
    The specific state to pull the __frameNumber from.
  • __x number = 0 (default)
  • __y number = 0 (default)
  • __direction = self.direction (default)
    Override the current direction.

Constants

Noble.Animation.DIRECTION_RIGHT
A re-contextualized instance of playdate.graphics.kImageUnflipped
Noble.Animation.DIRECTION_LEFT
A re-contextualized instance of playdate.graphics.kImageFlippedX
Noble Engine by Mark LaCroix, Noble Robot Documentation created using LDoc 1.5.0.