aseplayer

README

aseplayer

Aseprite animation player for Ebitengine.

[!NOTE]
Only the topmost visible layer is considered. Others are ignored..

Parsing Aseprite file

fly, _ = aseplayer.NewAnimPlayerFromAsepriteFile("bird.ase")

Tags

Each Aseprite Tag is imported as an Animation{} struct and is ready to play.

Playing tags

To play multiple animation tags simultaneously, use a shallow copy of AnimPlayer. It will share the same animations. Update each AnimPlayer with Update() and draw it with Draw().

bird1, _ = aseplayer.NewAnimPlayerFromAsepriteFile("bird.ase", aseplayer.Default)
bird2 = *bird1
bird3 = *bird1

bird1.Play("fly")
bird2.Play("fly")
bird3.Play("walk")

Tag properties

Animation Directions

AsePlayer supports three Animation Directions: Forward, Reverse, and Ping-pong.

[!NOTE]
For Ping-Pong and Reverse playback, the []Frame is specifically manipulated. For Ping-Pong, the number of frames will be greater than the Aseprite range. [0 1 2 3] -> [0 1 2 3 2 1]. Reverse is an reversed []Frame.

Repeat

AsePlayer supports the Repeat property; Animation.Repeat = 0 means infinite loop.

// Override.
g.animPlayer.Animations["turn"].Repeat = 1

UserData

Text field of Aseprite Tag's User Data. It is useful for data transfer. It can be automated with Aseprite Lua scripting. https://www.aseprite.org/api/tag#tagdata

Frame Durations

Frame durations are supported. The animation plays according to these durations.

// Override frame's duration.
animPlayer.Animations["walk"].Frames[2].Duration = time.Millisecond * 100

Usage

A pseudo-code for basic usage with Play()

func (g *Game) Update() error {
	if inpututil.IsKeyJustPressed(ebiten.KeyRight) {
		g.AnimPlayer.Play("walk")
	}
	if inpututil.IsKeyJustPressed(ebiten.KeySpace) {
		g.AnimPlayer.Play("jump")
	}
	// Update AnimPlayer
	g.myAnimPlayer.Update(aseplayer.Delta)
	return nil
}

func (g *Game) Draw(s *ebiten.Image) {
	// Draw AnimPlayer
	s.DrawImage(g.myAnimPlayer.CurrentFrame.Image, nil)
}

Documentation

Index

• Constants
• type AnimPlayer
  • func NewAnimPlayerFromAsepriteFile(asePath string) (ap *AnimPlayer, err error)
  • func NewAnimPlayerFromAsepriteFileSystem(fs fs.FS, asePath string) (ap *AnimPlayer, err error)
  • func (a *AnimPlayer) IsEnded() bool
  • func (a *AnimPlayer) Play(tag string)
  • func (a *AnimPlayer) PlayIfNotCurrent(tag string)
  • func (a *AnimPlayer) Rewind()
  • func (a *AnimPlayer) String() string
  • func (a *AnimPlayer) Update(dt time.Duration)
• type Animation
  • func (a *Animation) String() string
• type Frame

Constants

const Delta = time.Second / 60

Types

type AnimPlayer

type AnimPlayer struct {
	// The frame of the animation currently being played.
	//
	// Example:
	//	dio.GeoM.Translate(animPlayer.CurrentFrame.Position.X, animPlayer.CurrentFrame.Position.Y)
	//	dio.GeoM.Translate(x, y)
	//	screen.DrawImage(g.animPlayer.CurrentFrame.Image, dio)
	CurrentFrame *Frame
	// The animation currently being played
	CurrentAnimation *Animation
	// Animations accessible by their Aseprite tag names
	Animations map[string]*Animation
	// If true, the animation is paused
	Paused bool
	// contains filtered or unexported fields
}

AnimPlayer plays and manages Aseprite tag animations.

func NewAnimPlayerFromAsepriteFile

func NewAnimPlayerFromAsepriteFile(asePath string) (ap *AnimPlayer, err error)

NewAnimPlayerFromAsepriteFile creates an AnimPlayer from an Aseprite file.

The first Aseprite tag is automatically set as the current animation.

The Aseprite file must contain at least one tag, otherwise an error will occur.

func NewAnimPlayerFromAsepriteFileSystem

func NewAnimPlayerFromAsepriteFileSystem(fs fs.FS, asePath string) (ap *AnimPlayer, err error)

NewAnimPlayerFromAsepriteFileSystem creates an AnimPlayer from an Aseprite file.

The first Aseprite tag is automatically set as the current animation.

The Aseprite file must contain at least one tag, otherwise an error will occur.

func (*AnimPlayer) IsEnded

func (a *AnimPlayer) IsEnded() bool

If Animation.Repeat is not zero, it returns true when the animation ends. If it is zero, it is always false.

func (*AnimPlayer) Play

func (a *AnimPlayer) Play(tag string)

Play rewinds and plays the animation.

func (*AnimPlayer) PlayIfNotCurrent

func (a *AnimPlayer) PlayIfNotCurrent(tag string)

PlayIfNotCurrent rewinds and plays the animation with the given tag if it's not already playing

func (*AnimPlayer) Rewind

func (a *AnimPlayer) Rewind()

Rewinds animation

func (*AnimPlayer) String

func (a *AnimPlayer) String() string

func (*AnimPlayer) Update

func (a *AnimPlayer) Update(dt time.Duration)

Update advances the animation by the given delta time.

It handles frame progression, looping, and repeat count logic. Does nothing if the animation is paused or has ended.

Example:

myAnimPlayer.Update(aseplayer.Delta)

type Animation

type Animation struct {
	// The animation tag name is identical to the Aseprite tags
	Name string
	// Animation frames
	Frames []Frame
	// Repeat specifies how many times the animation should loop.
	// A value of 0 means infinite looping.
	Repeat uint16
	// Text field of Aseprite Tag's User Data.
	//
	// It is useful for data transfer. It can be automated with Aseprite Lua scripting.
	//
	// https://www.aseprite.org/api/tag#tagdata
	UserData string
}

Animation for AnimPlayer

func (*Animation) String

func (a *Animation) String() string

type Frame

type Frame struct {
	*ebiten.Image
	// Position represents the Cel's top-left coordinates relative to the Aseprite canvas.
	Position v.Vec
	// Duration of the frame as defined in the Aseprite file.
	Duration time.Duration
}