goaseprite

README

goaseprite

GoDoc link

Yo, 'sup! This is a JSON loader for Aseprite files written in / for Go.

How To Use

Usage is pretty straightforward. You export a sprite sheet from Aseprite (Ctrl+E), with Output File and JSON data checked, and the values set to Hash with Frame Tags and Slices (optionally) on.

For use with your project, you'll call goaseprite.Load() with a string argument of where to find the outputted Aseprite JSON data file. The function will return a goaseprite.File struct. It's from here that you control your animation. Since each instance of an File struct has playback specific variables and values, it's best not to share these across multiple instances (unless they are supposed to share animation playback).

After you have a File, you can just call its File.Update() function with an argument of delta time (the time between the previous frame and the current one) to get it updating. After that, use File.Play() to play a specific animation, and call File.GetFrameXY() to get the X and Y position of the current frame on the sprite sheet. Here's a quick pseudo-example for a simple "Player" class using raylib-go:

package main

import (
	rl "github.com/gen2brain/raylib-go/raylib"
	ase "github.com/solarlune/GoAseprite"
)


type Player struct {
    Ase         ase.File
    Texture     rl.Texture2D
    TextureRect rl.Rectangle
}

func NewPlayer() *Player {

    player := Player{}
    
    // goaseprite.Load() returns an AsepriteFile, assuming it finds the JSON file
    player.Ase = ase.Load("assets/graphics/Player.json")
    
    // AsepriteFile.ImagePath will be the absolute path to the image file.
    player.Texture = rl.LoadTexture(player.Ase.ImagePath)
    
    // Set up the texture rectangle for drawing the sprite
    player.TextureRect = rl.Rectangle{0, 0, player.Ase.FrameWidth, player.Ase.FrameHeight}
    
    // Queues up the "Play" animation
    player.Ase.Play("Idle")
    
    return &player
    
}

func (this *Player) Update() {
    
    // Call this every frame with the delta-time (time since the last frame)
    this.Ase.Update(rl.GetFrameTime())
    
    // Set up the source rectangle for drawing the sprite (on the sprite sheet)
    x, y := this.Ase.GetFrameXY()
    this.TextureRect.X = float32(x)
    this.TextureRect.Y = float32(y)
}

func (this *Player) Draw() {
    // And draw it~!
    rl.DrawTextureRec(this.Texture, this.TextureRect, rl.Vector2{0, 0}, rl.White)
}

Take a look at the Wiki for more information on the API!

Additional Notes

As for dependencies, GoAseprite makes use of tidwall's nice gjson package.

Documentation

Index

• Constants
• type Animation
• type File
  • func Load(file string) *File
  • func LoadData(aseJSONFilePath string) *File
  • func (asf *File) FinishedAnimation() bool
  • func (asf *File) GetAnimation(animName string) *Animation
  • func (asf *File) GetFrameXY() (int32, int32)
  • func (asf *File) GetSlice(sliceName string) *Slice
  • func (asf *File) HasAnimation(animName string) bool
  • func (asf *File) HasSlice(sliceName string) bool
  • func (asf *File) HitTag(tagName string) bool
  • func (asf *File) HitTags() []string
  • func (asf *File) IsPlaying(animName string) bool
  • func (asf *File) LeftTag(tagName string) bool
  • func (asf *File) LeftTags() []string
  • func (asf *File) Play(animName string)
  • func (asf *File) TouchingTag(tagName string) bool
  • func (asf *File) TouchingTags() []string
  • func (asf *File) Update(deltaTime float32)
• type Frame
• type Layer
• type Slice
• type SliceKey

Constants

const (
	// PlayForward plays animations forward
	PlayForward = "forward"
	// PlayBackward plays animations backwards
	PlayBackward = "reverse"
	// PlayPingPong plays animation forward then backward
	PlayPingPong = "pingpong"
)

Types

type Animation

type Animation struct {
	Name      string
	Start     int32
	End       int32
	Direction string
}

Animation contains details regarding each animation from Aseprite. This also represents a tag in Aseprite and in goaseprite. Direction is a string, and can be assigned one of the playback constants.

type File

type File struct {
	ImagePath        string
	FrameWidth       int32
	FrameHeight      int32
	Frames           []Frame
	Animations       []Animation
	Layers           []Layer
	CurrentAnimation *Animation

	CurrentFrame int32

	PrevFrame int32
	PlaySpeed float32
	Playing   bool
	Slices    []*Slice
	// contains filtered or unexported fields
}

File contains all properties of an exported aseprite file.

func Load

func Load(file string) *File

func LoadData

func LoadData(aseJSONFilePath string) *File

LoadData parses and returns an File for a supplied JSON exported from Aseprite. This is your starting point. goaseprite is set up to read JSONs for sprite sheets exported with the Hash type.

func (*File) FinishedAnimation

func (asf *File) FinishedAnimation() bool

FinishedAnimation returns true if the animation is finished playing. When playing forward or backward, it returns true on the frame that the File loops the animation (assuming the File gets Update() called every game frame). When playing using ping-pong, this function will return true when a full loop is finished (when the File plays forwards and then backwards, and loops again).

func (*File) GetAnimation

func (asf *File) GetAnimation(animName string) *Animation

GetAnimation returns a pointer to an Animation of the desired name. If it can't be found, it will return `nil`.

func (*File) GetFrameXY

func (asf *File) GetFrameXY() (int32, int32)

GetFrameXY returns the current frame's X and Y coordinates on the source sprite sheet for drawing the sprite.

func (*File) GetSlice

func (asf *File) GetSlice(sliceName string) *Slice

GetSlice returns a Slice that has the name specified.

func (*File) HasAnimation

func (asf *File) HasAnimation(animName string) bool

HasAnimation returns true if the File has an Animation of the specified name.

func (*File) HasSlice

func (asf *File) HasSlice(sliceName string) bool

HasSlice returns true if the File has a Slice of the specified name.

func (*File) HitTag

func (asf *File) HitTag(tagName string) bool

HitTag returns if the File's playback just touched a tag by the specified name.

func (*File) HitTags

func (asf *File) HitTags() []string

HitTags returns a list of tags the File just touched.

func (*File) IsPlaying

func (asf *File) IsPlaying(animName string) bool

IsPlaying returns if the named animation is playing.

func (*File) LeftTag

func (asf *File) LeftTag(tagName string) bool

LeftTag returns if the File's playback just left a tag by the specified name.

func (*File) LeftTags

func (asf *File) LeftTags() []string

LeftTags returns a list of tags the File just left.

func (*File) Play

func (asf *File) Play(animName string)

Play queues playback of the specified animation (assuming it's in the File).

func (*File) TouchingTag

func (asf *File) TouchingTag(tagName string) bool

TouchingTag returns if the File's playback is touching a tag by the specified name.

func (*File) TouchingTags

func (asf *File) TouchingTags() []string

TouchingTags returns a list of tags the playback is touching.

func (*File) Update

func (asf *File) Update(deltaTime float32)

Update steps the File forward in time, updating the currently playing animation (and also handling looping).

type Frame

type Frame struct {
	X        int32
	Y        int32
	Duration float32
}

Frame contains timing and position information for the frame on the spritesheet. Note that Duration is in seconds.

type Layer

type Layer struct {
	Name      string
	Opacity   uint8
	BlendMode string
}

Layer contains details regarding the layers exported from Aseprite, including the layer's name (string), opacity (0-255), and blend mode (string).

type Slice

type Slice struct {
	Name  string
	Data  string
	Color int64
	Keys  []*SliceKey
}

Slice represents a Slice (rectangle) that was defined in Aseprite and exported in the JSON file. Data by default is blank, but can be specified on export from Aseprite to be whatever you need it to be.

type SliceKey

type SliceKey struct {
	Frame      int32
	X, Y, W, H int32
}

SliceKey represents a Slice's size and position in the Aseprite file. An individual Aseprite File can have multiple Slices inside, which can also have multiple frames in which the Slice's position and size changes. The SliceKey's Frame indicates which frame the key is operating on, and should generally also be the same as the index of the SliceKey in the Slice's Keys array.