valkryst / v2dsprite

A Java2D library which allows for easy management, loading, and use of sprite sheets.

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

v2dsprite's Issues

Does exist a Project example?

Hi, I would like to test the library but I didnt see any example project.

Many thanks in advance

Juan Antonio

TexturePacker Support

Ass support for sprite sheets created using the TexturePacker tool.

Rewrite the Readme for V3

Free Texture Packer Support

Add support for sprite sheets created using the Free Texture Packer tool.

Free Sprite Sheet Packer Support

Ass support for sprite sheets created using the Free Sprite Sheet Packer tool.

Can't pull this repository with Maven.

I added this to the pom.xml, but it can't seem to be found:

...
    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>
...
    <dependencies>
        <dependency>
            <groupId>com.github.Valkryst</groupId>
            <artifactId>V2DSprite</artifactId>
            <version>2020.04.05-break</version>
        </dependency>
    </dependencies>

SpriteSheet Packer Support

Add support for sprite sheets created using the SpriteSheet Packer tool.