I will eventually publish a sample project, which demonstrates the full use of this library.

Table of Contents

• Installation
  • Gradle
  • Maven
  • sbt
• Terminology
• Folder Structure
• File Structure
• Supported Image Formats
• Credits & Inspiration

Installation

V2DSprite is hosted on the JitPack package repository which supports Gradle, Maven, and sbt.

Gradle

Add JitPack to your build.gradle at the end of repositories.

allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}

Add V2DSprite as a dependency.

dependencies {
	implementation 'com.github.Valkryst:V2DSprite:2023.02.24-break-fixed'
}

Maven

Add JitPack as a repository.

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Add V2DSprite as a dependency.

<dependency>
    <groupId>com.github.Valkryst</groupId>
    <artifactId>V2DSprite</artifactId>
    <version>2023.02.24-break-fixed</version>
</dependency>

Scala SBT

Add JitPack as a resolver.

resolvers += "jitpack" at "https://jitpack.io"

Add V2DSprite as a dependency.

libraryDependencies += "com.github.Valkryst" % "V2DSprite" % "2023.02.24-break-fixed"

Terminology

• A SpriteSheet contains one or more Animations.
• An Animation contains one or more Frames.
• A Frame can have a CollisionBox.
• A Frame can have a Hitbox.

Folder Structure

V2DSprite assumes that all of your data is located within the sprites folder, within your .jar file.

Each subfolder of the sprites folder must contain one sprite sheet, named image.extension and an animations folder.

The animations folder must contain all of the _collisionbox.tsv, _frame.tsv, and _hitbox.tsv files for each animation in the sprite sheet.

See the following heirarchy, as an example:

• sprites
  • slime_green
    • image.png
    • animations
      • idle_collisionbox.tsv
      • idle_frame.tsv
      • idle_hitbox.tsv
      • walk_collisionbox.tsv
      • walk_frame.tsv
      • walk_hitbox.tsv
  • slime_purple
    • image.tiff
    • animations
      • idle_collisionbox.tsv
      • idle_frame.tsv
      • idle_hitbox.tsv
      • walk_collisionbox.tsv
      • walk_frame.tsv
      • walk_hitbox.tsv
  • skeleton
    • image.jpeg
    • animations
      • attack_collisionbox.tsv
      • attack_frame.tsv
      • attack_hitbox.tsv
      • idle_collisionbox.tsv
      • idle_frame.tsv
      • idle_hitbox.tsv
      • walk_collisionbox.tsv
      • walk_frame.tsv
      • walk_hitbox.tsv

File Structure

Each row of the .tsv files correspond with one another. So, the first row in _frame.tsv defines a Frame and the first row in _collisionbox.tsv defines the Collision Box for that Frame.

You are not required to use the _collisionbox.tsv or _hitbox.tsv files, but they are a useful feature for loading/working with that data in your projects.

Please remember that the values are seperated by tabs, not spaces.

frame.tsv

A Frame is defined by:

• X-Axis offset, from the top-left pixel of the Sprite Sheet.
• Y-Axis offset, from the top-left pixel of the Sprite Sheet.
• Width of the Frame (sprite).
• Height of the Frame (sprite).
• Duration, in milliseconds, that the Frame should be displayed during an Animation.

e.g. xOffset yOffset width height duration

collisionbox.tsv

A Collision Box is defined by:

• X-Axis offset, from the top-left pixel of the Frame.
• Y-Axis offset, from the top-left pixel of the Frame.
• Width of the Frame (sprite).
• Height of the Frame (sprite).

e.g. xOffset yOffset width height

hitbox.tsv

A Hitbox is defined by:

• X-Axis offset, from the top-left pixel of the Frame.
• Y-Axis offset, from the top-left pixel of the Frame.
• Width of the Frame (sprite).
• Height of the Frame (sprite).

e.g. xOffset yOffset width height

Supported Image Formats

This library uses javax.imageio to load images, and it supports the following formats:

• bmp
• gif
• jpeg/jpg
• png
• tiff/tif
• wbmp

Credits & Inspiration

• LionEngine
• LITIENGINE