goaseprite

README

goaseprite

Aseprite JSON loader for Go (Golang)

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 (
	"github.com/gen2brain/raylib-go/raylib"
	ase "github.com/solarlune/GoAseprite"
)


type Player struct {
    Ase         ase.File
    Texture     raylib.Texture2D
    TextureRect raylib.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 = raylib.LoadTexture(player.Ase.ImagePath)
    
    // Set up the texture rectangle for drawing the sprite
    player.TextureRect = raylib.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(raylib.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~!
    raylib.DrawTextureRec(this.Texture, this.TextureRect, raylib.Vector2{0, 0}, raylib.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

Overview

Package goaseprite is an Aseprite JSON loader written in Golang.

The package is basically written around using goaseprite.Load() to load in your exported file's JSON data, and then using that to play and get the data necessary to display the animations.

Index

• Constants
• type Animation
• type File
  • func Load(aseJSONFilePath string) File
  • func LoadBytes(fileBytes []byte) File
  • func (asf *File) FinishedAnimation() bool
  • func (asf *File) GetAnimation(animName string) *Animation
  • func (asf *File) GetFrameXY() (int32, int32)
  • 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 Slice

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
	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(aseJSONFilePath string) File

Load 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 LoadBytes

func LoadBytes(fileBytes []byte) File

LoadBytes parses and returns an File from JSON exported from Aseprite. An alternative to Load(filePath) when no file-system is available (jsgo.io, for example) ase.ImagePath will be empty

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) 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 Slice

type Slice struct {
	Name          string
	Data          string
	X, Y, W, H    int32
	StartingFrame int32
}

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. Note that StartingFrame is what frame of the Aseprite file the animation started on, but in the future this will probably change if actual animation capability is added to slices.