anim

README

Anim

Anim is an easy to use animation player package for Ebitengine v2

import "github.com/setanarut/anim"

Tutorial

Let's declare a global variable for the animation player

var animPlayer *anim.AnimationPlayer

Make new animation player from sprite atlas

spriteSheet := anim.Atlas{
	Name:  "Default",
	Image: ebiten.NewImageFromImage(img),
}
animPlayer = anim.NewAnimationPlayer(spriteSheet)

Let's specify the coordinates of the animations for the player states. The figure shows the coordinates for "run" state.

animPlayer.NewAnim("idle", 0, 0, 32, 32, 5, false, false, 5)
animPlayer.NewAnim("run", 0, 32, 32, 32, 8, false, false, 12)
animPlayer.NewAnim("jump", 0, 32*2, 32, 32, 4, false, false, 15)

Let's set the initial animation state.

animPlayer.SetAnim("idle)

Update animation player

func (g *Game) Update() error {
	animPlayer.Update()

Let's update the states according to the character's movement.

if ebiten.IsKeyPressed(ebiten.KeySpace) {
	animPlayer.SetAnim("jump")
} else if ebiten.IsKeyPressed(ebiten.KeyD) {
	animPlayer.SetAnim("run")
} else if ebiten.IsKeyPressed(ebiten.KeyA) {
	animPlayer.SetAnim("run")
	// FlipX
	DIO.GeoM.Scale(-1, 1)
	// Align to zero
	DIO.GeoM.Translate(float64(animPlayer.CurrentFrame.Bounds().Dx()), 0)
} else {
	animPlayer.SetAnim("idle")
}

Finally let's draw Animation player

func (g *Game) Draw(screen *ebiten.Image) {
	screen.DrawImage(animPlayer.CurrentFrame, DIO)

Examples

Simple demo

Run demo on your local machine

go run github.com/setanarut/anim/examples/demo@latest

Multiple sprite sheet example

Example of alternative sprite sheets with exactly the same coordinates.
Run atlases on your local machine;

go run github.com/setanarut/anim/examples/atlases@latest

Documentation

Index

• Constants
• func MakePingPong(frames []*ebiten.Image) []*ebiten.Image
• func SubImages(spriteSheet *ebiten.Image, x, y, w, h, subImageCount int, vertical bool) []*ebiten.Image
• type Animation
• type AnimationPlayer
  • func NewAnimationPlayer(atlases ...Atlas) *AnimationPlayer
  • func (ap *AnimationPlayer) Anim() string
  • func (ap *AnimationPlayer) Atlas() string
  • func (ap *AnimationPlayer) CurrentAnimFPS() float64
  • func (ap *AnimationPlayer) NewAnim(stateName string, x, y, w, h, frameCount int, pingPong bool, vertical bool, ...)
  • func (ap *AnimationPlayer) PauseAtFrame(index int)
  • func (ap *AnimationPlayer) SetAllFPS(FPS float64)
  • func (ap *AnimationPlayer) SetAnim(animName string)
  • func (ap *AnimationPlayer) SetAnimFPS(animName string, FPS float64)
  • func (ap *AnimationPlayer) SetAtlas(atlasName string)
  • func (ap *AnimationPlayer) String() string
  • func (ap *AnimationPlayer) Update()
• type Atlas
• type PlaybackData

Constants

const Str string = `
Playback state;
Current Atlas: %v
Current Anim: %v
Paused: %v
Tick: %v
Current Anim Index %v
Current Anim FPS: %v
`

Functions

func MakePingPong

func MakePingPong(frames []*ebiten.Image) []*ebiten.Image

MakePingPong arranges the animation indexes to play back and forth. [0 1 2 3] -> [0 1 2 3 2 1]

func SubImages

func SubImages(spriteSheet *ebiten.Image, x, y, w, h, subImageCount int, vertical bool) []*ebiten.Image

SubImages returns sub-images from spriteSheet image

Types

type Animation

type Animation struct {
	Name   string          // Name of the aimation state
	Frames []*ebiten.Image // Animation frames
	FPS    float64         // Animation playback speed (Frames Per Second).
}

Animation for AnimationPlayer

type AnimationPlayer

type AnimationPlayer struct {
	Data PlaybackData
	// Current frame of the current animation.
	//
	// The frame is dynamically updated with `AnimationPlayer.Update()`.
	CurrentFrame *ebiten.Image
	Atlases      []Atlas
	// Animations and alternative sprite sheet atlases
	Animations map[string]map[string]*Animation
}

AnimationPlayer plays and manages animations.

func NewAnimationPlayer

func NewAnimationPlayer(atlases ...Atlas) *AnimationPlayer

NewAnimationPlayer returns new AnimationPlayer with spriteSheet

func (*AnimationPlayer) Anim

func (ap *AnimationPlayer) Anim() string

Anim returns current animation state name

func (*AnimationPlayer) Atlas

func (ap *AnimationPlayer) Atlas() string

Atlas returns current Atlas

func (*AnimationPlayer) CurrentAnimFPS

func (ap *AnimationPlayer) CurrentAnimFPS() float64

CurrentAnimFPS returns FPS of the current animation

func (*AnimationPlayer) NewAnim

func (ap *AnimationPlayer) NewAnim(
	stateName string,
	x, y,
	w, h,
	frameCount int,
	pingPong bool,
	vertical bool,
	FPS float64,
)

NewAnim appends a new Animation to the AnimationPlayer and returns the Animation.

Parameters:

• x, y - Top-left coordinates of the first frame's rectangle.
• w, h - Width and height of the first frame's rectangle.
• frameCount - Animation frame count
• vertical - If true, frames are appended vertically, otherwise horizontally.
• pingPong - If true, arranges the animation indexes to play back and forth. [0 1 2 3 2 1]
• FPS - Playback FPS

func (*AnimationPlayer) PauseAtFrame

func (ap *AnimationPlayer) PauseAtFrame(index int)

PauseAtFrame pauses the current animation at the frame. If index is out of range it does nothing.

func (*AnimationPlayer) SetAllFPS

func (ap *AnimationPlayer) SetAllFPS(FPS float64)

SetAllFPS overwrites the FPS of all animations.

func (*AnimationPlayer) SetAnim

func (ap *AnimationPlayer) SetAnim(animName string)

SetAnim sets the animation and resets to the first frame.

If you assign ap.Data.CurrentAnim = "animName" directly, the animation will not be reset.

func (*AnimationPlayer) SetAnimFPS

func (ap *AnimationPlayer) SetAnimFPS(animName string, FPS float64)

SetAnimFPS sets FPS of the animation state.

func (*AnimationPlayer) SetAtlas

func (ap *AnimationPlayer) SetAtlas(atlasName string)

func (*AnimationPlayer) String

func (ap *AnimationPlayer) String() string

func (*AnimationPlayer) Update

func (ap *AnimationPlayer) Update()

Update updates AnimationPlayer. Place this func inside Ebitengine `Game.Update()`.

// example
func (g *Game) Update() error {
animPlayer.Update()
...

type Atlas

type Atlas struct {
	Name  string
	Image *ebiten.Image
}

Atlas is a sprite sheet state for animation player.

It is used to easily switch between different sprite sheet variations that share the same coordinates.

type PlaybackData

type PlaybackData struct {
	// Current sprite sheet atlas
	CurrentAtlas string
	// CurrentAnim name (animation name)
	CurrentAnim string
	// If true, animations will be paused.
	Paused bool
	// Animation tick
	Tick float64
	// Current animation frame index
	CurrentIndex int
}

PlaybackData is AnimationPlayer's playback data. With this structure, the playback state can be saved to disk and reloaded.