kryosprite

README

KryoSprite

A sprite library for Ebitengine. Kryosprite helps ease handling your sprite's texture, drawing, updating, and animations in one package.

Check Out Examples

I highly recommend checking out the example code for a full demonstration.

go run -tags=example github.com/KalebHawkins/kryosprite/examples/basic@latest

go run -tags=example github.com/KalebHawkins/kryosprite/examples/fox@latest

Using the Library

First you need to add the library to your project.

go get github.com/KalebHawkins/kryosprite

Then import it.

import (
    ks "github.com/KalebHawkins/kryosprite"
)

See the wiki for a walkthrough on how to build a simple game from scratch using Ebitengine and Kryosprite.

The fox sprite sheet was made by Elthen's Pixel Art Shop.

TODO

• Make Wiki...
• Add loading and parsing images from JSON-exported sprite sheets.
  • LibreSprite/Aesprite
  • Others? (Open an issue for suggestions)
• Feedback? (Open an issue for feedback)
• Contributions? (Open a pull request)
• Create developer documentation and guides for issues and pull requests.

Documentation

Index

• Variables
• type Animation
  • func (a *Animation) Frame() image.Rectangle
  • func (a *Animation) FrameHeight() int
  • func (a *Animation) FrameWidth() int
• type Animator
  • func NewAnimator() Animator
• type Direction
• type Frame
• type Origin
• type Sprite
  • func (s *Sprite) Draw(dst *ebiten.Image)
  • func (s *Sprite) FlipHorizontal(flip bool)
  • func (s *Sprite) FlipVertical(flip bool)
  • func (s *Sprite) SetScale(x, y float64)
  • func (s *Sprite) Update()
• type Vector

Variables

var ErrAnimationExists = errors.New("animation already exists in animator instance")

ErrAnimationExists is an error returned if an Animation already exists in the animator instance.

var ErrAnimationNotFound = errors.New("animation was not found")

ErrAnimationNotFound is an error returned if an Animation called by string is not found in the animator instance.

Types

type Animation

type Animation struct {
	// StartFrame is the frame's starting x and y location, width and height.
	StartFrame Frame
	// FrameCount the number of frames for a particular animation.
	FrameCount int
	// Delay is the number of ticks it takes for each frame of the animation to pass.
	Delay float64
	// Direction is the Direction the spritesheet should be read.
	// This should be either Horizontal or Vertical.
	Direction Direction
	// contains filtered or unexported fields
}

Animation defines a spritesheet's animation.

func (*Animation) Frame

func (a *Animation) Frame() image.Rectangle

Frame returns a rect repesenting the current frame of the animation.

func (*Animation) FrameHeight

func (a *Animation) FrameHeight() int

FrameHeight returns the height of the frame.

func (*Animation) FrameWidth

func (a *Animation) FrameWidth() int

FrameWidth returns the width of the frame.

type Animator

type Animator interface {
	// Add will add an animation to the map of the animator instance.
	//
	// If an animation already exists in the map this function will
	// return an ErrAnimationExists error.
	Add(animationName string, animation *Animation) error

	// Play will play the animation, iterating through each frame.
	//
	// This function should be called every frame in your update function.
	//
	// If the animation name passed is not found in the animator's map an
	// ErrAnimationNotFound error is returned.
	Play(animationName string) error

	// Pause will stop an animation from playing until the next call to Resume.
	Pause()

	// Resume will start an animation until the next call to Pause.
	//
	// Note: you must still call the `Play()` method to iterate through the
	// frames of an animation.
	Resume()

	// Reset will reset an animation back to it's startFrame
	Reset()

	// Animation returns the currently selected animation.
	//
	// If no animation has been set using the Play() method
	// a zero valued Animation will be returned.
	Animation() *Animation

	// Paused returns true if the animator's current animation is paused, otherwise it returns false.
	Paused() bool

	// AnimationTicks returns the number of ticks it takes to perform a full animation sequence.
	AnimationTicks() float64
}

Animator is an interface that acts as a handler for animations.

func NewAnimator

func NewAnimator() Animator

NewAnimator returns a new Animator interface.

type Direction

type Direction int

Direction repestents the Direction in which the animation is read from a spritesheet.

const (
	// Horizontal, when provided to an Animation's Direction, will read the spritesheet from left to right.
	Horizontal Direction = iota
	// Vertical, when provided to an Animation's Direction, will read the spritesheet from top to bottom.
	Vertical
)

type Frame

type Frame struct {
	X, Y, Width, Height int
}

Frame represents a frame of an animation as a rectangle.

type Origin

type Origin int

Origin repesents the x, y drawing point of the sprite.

This means if the x, y location of the origin is TopLeft the sprite's image will be drawn to the destination image from the TopLeft corner of the image.

If the origin is centered, the sprite will be drawn to the destination image from the center of the sprite's image.

TopLeft ──┐
 Origin   │
          │     ┌── Center
          │     │    Origin
          │     │
          o─────┼──────┐
          │     │      │
          │     │      │
          │     o      │
          │            │
          │            │
          └────────────┘

const (
	// Topleft origin of a sprite image.
	TopLeft Origin = iota
	// Center origin of a sprite image.
	Center
)

type Sprite

type Sprite struct {
	// Texture is the sprite's image.
	Texture *ebiten.Image
	// Position is the sprites location on screen.
	Position Vector
	// Animator can be used to add animations to your sprite.
	Animator Animator
	// UpdateFunc handles your sprites update logic. This function should be
	// called in Ebitengine's Game Upadate() method.
	UpdateFunc func() error
	// Origin repesents the origin point of the sprite.
	Origin Origin
	// Color will fill the sprite with a give color.
	// This is mostly used for prototyping.
	Color color.Color
	// Scale represents the scale of the sprite.
	Scale Vector
	// contains filtered or unexported fields
}

Sprite represents any visible image on the game screen.

func (*Sprite) Draw

func (s *Sprite) Draw(dst *ebiten.Image)

Draw draws the sprite at the sprites current location.

func (*Sprite) FlipHorizontal

func (s *Sprite) FlipHorizontal(flip bool)

FlipHorizontal will flip a sprite horizontally.

func (*Sprite) FlipVertical

func (s *Sprite) FlipVertical(flip bool)

FlipVertical will flip a sprite vertically if flipped is set to true.

func (*Sprite) SetScale

func (s *Sprite) SetScale(x, y float64)

Scale will set the scale of the sprite texture.

func (*Sprite) Update

func (s *Sprite) Update()

Update performs the sprite's logical updates.

type Vector

type Vector struct {
	X, Y float64
}

Vector represents a mathematical vector used for positioning and movement.