README
¶
goaseprite
Goaseprite is a JSON loader for Aseprite files for Golang.
How To Use
Usage is pretty straightforward. You export a sprite sheet and its corresponding JSON data file from Aseprite (Ctrl+E). The values should be set to Hash with Frame Tags and Slices (optionally) on.
Then you'll want to load the Aseprite data. To do this, you'll call goaseprite.Open() with a string argument of where to find the Aseprite JSON data file, or manually pass the bytes to goaseprite.Read(). From this, you'll get a *goaseprite.File, which represents an Aseprite file. It's from here that you control your animation.
You can call File.Play() to play a tag / animation, and use the File.Update() function with an argument of delta time (the time between the previous frame and the current one) to update the animation. Call File.CurrentFrame() to get the current frame, which gives you the X and Y position of the current frame on the sprite sheet. Assuming a tag with a blank name ("") doesn't exist in your Aseprite file, goaseprite will create a default animation with that name, allowing you to easily play all of the frames in sequence.
Here'a quick example, using ebiten for rendering:
package main
import (
"image"
"os"
"github.com/hajimehoshi/ebiten/v2"
"github.com/hajimehoshi/ebiten/v2/ebitenutil"
"github.com/solarlune/goaseprite"
_ "image/png"
)
type Game struct {
Sprite *goaseprite.File
AsePlayer *goaseprite.Player
Img *ebiten.Image
}
func NewGame() *Game {
sprite, err := goaseprite.Open("16x16Deliveryman.json", os.DirFS("."))
if err != nil {
panic(err)
}
game := &Game{
Sprite: sprite,
}
game.AsePlayer = game.Sprite.CreatePlayer()
// There are four callback functions that you can use to watch for changes to the internal state of the *File.
// OnLoop is called when the animation is finished and a loop is completed; for ping-pong, it happens on a full revolution (after going forwards and then backwards).
// game.Sprite.OnLoop = func() { fmt.Println("loop") }
// OnFrameChange is called when the sprite's frame changes.
// game.Sprite.OnFrameChange = func() { fmt.Println("frame change") }
// OnTagEnter is called when the File enters a new Tag (i.e. if you play an animation of a sword being slashed, you can make this callback watch for a tag that indicates when a corresponding sound should play).
// game.Sprite.OnTagEnter = func(tag *goaseprite.Tag) { fmt.Println("entered: ", tag.Name) }
// OnTagExit is called when the File leaves the current Tag.
// game.Sprite.OnTagExit = func(tag *goaseprite.Tag) { fmt.Println("exited: ", tag.Name) }
img, _, err := ebitenutil.NewImageFromFile(game.Sprite.ImagePath)
if err != nil {
panic(err)
}
// game.Sprite.PlaySpeed = 2
game.Img = img
ebiten.SetWindowTitle("goaseprite example")
ebiten.SetWindowResizable(true)
game.AsePlayer.Play("idle")
return game
}
func (game *Game) Update() error {
if ebiten.IsKeyPressed(ebiten.Key1) {
game.AsePlayer.Play("idle")
} else if ebiten.IsKeyPressed(ebiten.Key2) {
game.AsePlayer.Play("walk")
} else if ebiten.IsKeyPressed(ebiten.Key3) {
game.AsePlayer.Play("") // Calling Play() with a blank string will play the full animation (similar to playing an animation in Aseprite without any tags selected).
}
game.AsePlayer.Update(float32(1.0 / 60.0))
return nil
}
func (game *Game) Draw(screen *ebiten.Image) {
opts := &ebiten.DrawImageOptions{}
sub := game.Img.SubImage(image.Rect(game.AsePlayer.CurrentFrameCoords()))
screen.DrawImage(sub.(*ebiten.Image), opts)
}
func (game *Game) Layout(w, h int) (int, int) { return 320, 180 }
func main() {
game := NewGame()
ebiten.RunGame(game)
}
You also have the ability to use File.OnLoop, File.OnFrameChange, File.OnTagEnter, and File.OnTagExit callbacks to trigger events when an animation's state changes, for example. That's roughly it!
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.
Index ¶
- Constants
- type File
- type Frame
- type Layer
- type Player
- func (player *Player) Clone() *Player
- func (player *Player) CurrentFrame() (Frame, bool)
- func (player *Player) CurrentFrameCoords() (int, int, int, int)
- func (player *Player) CurrentUVCoords() (float64, float64)
- func (player *Player) FrameIndexInAnimation() int
- func (player *Player) Play(tagName string) error
- func (player *Player) SetFrameIndexInAnimation(frameIndex int)
- func (player *Player) TouchingTagByName(tagName string) bool
- func (player *Player) TouchingTags() []Tag
- func (player *Player) Update(dt float32)
- type Slice
- type SliceKey
- type Tag
Constants ¶
const ( PlayForward = "forward" // PlayForward plays animations forward PlayBackward = "reverse" // PlayBackward plays animations backwards PlayPingPong = "pingpong" // PlayPingPong plays animation forward then backward )
const (
ErrorNoTagByName = "no tags by name"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type File ¶
type File struct {
Path string // Path to the file (exampleSprite.json); blank if the *File was loaded using Read().
ImagePath string // Path to the image associated with the Aseprite file (exampleSprite.png).
Width, Height int32 // Overall width and height of the File.
FrameWidth, FrameHeight int32 // Width and height of the frames in the File.
Frames []Frame // The animation Frames present in the File.
Tags []Tag // A map of Tags, with their names being the keys.
Layers []Layer // A slice of Layers.
Slices []Slice // A slice of the Slices present in the file.
}
File contains all properties of an exported aseprite file. ImagePath is the absolute path to the image as reported by the exported Aseprite JSON data. Path is the string used to open the File if it was opened with the Open() function; otherwise, it's blank.
func Open ¶
Open will use the provided file system to open and parse an Aseprite JSON file. Returns a *goaseprite.File. This can be your starting point. Files created with Open() will put the JSON filepath used in the Path field.
func Read ¶
Read returns a *goaseprite.File for a given sequence of bytes read from an Aseprite JSON file. This function assumes a properly formed Aseprite JSON file.
func (*File) CreatePlayer ¶
CreatePlayer returns a new animation player that plays animations from a given Aseprite file.
func (*File) SliceByName ¶
SliceByName returns a Slice that has the name specified and a boolean indicating whether it could be found or not. Note that a File can have multiple Slices by the same name.
type Layer ¶
Layer contains details regarding the layers exported from Aseprite, including the layer's name (string), opacity (0-255), and blend mode (string).
type Player ¶
type Player struct {
File *File
PlaySpeed float32 // The playback speed; altering this can be used to globally slow down or speed up animation playback.
CurrentTag Tag // The currently playing animation.
FrameIndex int // The current frame of the File's animation / tag playback.
PrevFrameIndex int // The previous frame in the playback.
// Callbacks
OnLoop func() // OnLoop gets called when the playing animation / tag does a complete loop. For a ping-pong animation, this is a full forward + back cycle.
OnFrameChange func() // OnFrameChange gets called when the playing animation / tag changes frames.
OnTagEnter func(tag Tag) // OnTagEnter gets called when entering a tag from "outside" of it (i.e. if not playing a tag and then it gets played, this gets called, or if you're playing a tag and you pass through another tag).
OnTagExit func(tag Tag) // OnTagExit gets called when exiting a tag from inside of it (i.e. if you finish passing through a tag while playing another one).
// contains filtered or unexported fields
}
Player is an animation player for Aseprite files.
func (*Player) CurrentFrame ¶
CurrentFrame returns the current frame for the currently playing Tag in the File and a boolean indicating if the Player is playing a Tag or not.
func (*Player) CurrentFrameCoords ¶
CurrentFrameCoords returns the four corners of the current frame, of format (x1, y1, x2, y2). If File.CurrentFrame() is nil, it will instead return all -1's.
func (*Player) CurrentUVCoords ¶
CurrentUVCoords returns the top-left corner of the current frame, of format (x, y). If File.CurrentFrame() is nil, it will instead return (-1, -1).
func (*Player) FrameIndexInAnimation ¶
FrameIndexInAnimation returns the currently visible frame index, using the playing animation as the range. This means that a FrameIndexInAnimation of 0 would be the first frame in the currently playing animation, regardless of what frame in the sprite strip that is). If no animation is being played, this function will return -1.
func (*Player) Play ¶
Play sets the specified tag name up to be played back. A tagName of "" will play back the entire file.
func (*Player) SetFrameIndexInAnimation ¶
SetFrameIndexInAnimation sets the currently visible frame to frameIndex, using the playing animation as the range. This means calling SetFrameIndexInAnimation with a frameIndex of 2 would set it to the third frame of the animation that is currently playing.
func (*Player) TouchingTagByName ¶
TouchingTagByName returns if a tag by the given name is being touched by the Player (tag).
func (*Player) TouchingTags ¶
TouchingTags returns the tags currently being touched by the Player (tag).
type Slice ¶
type Slice struct {
Name string // Name is the name of the Slice, as specified in Aseprite.
Data string // Data is blank by default, but can be specified on export from Aseprite to be whatever you need it to be.
Keys []SliceKey // The individual keys (positions and sizes of Slices) according to the Frames they operate on.
Color int64
}
Slice represents a Slice (rectangle) that was defined in Aseprite and exported in the JSON file.
type SliceKey ¶
SliceKey represents a Slice's size and position in the Aseprite file on a specific frame. 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.
Source Files