Sprites and Animation

English | 繁體中文 | 日本語 | 한국어

BIT8_CLI provides a lightweight Sprite and Animation system for 2D games.

Sprites use registered tiles from the Asset Registry. They can define named animations, control playback speed, and be attached to Nodes.

In BIT8_CLI 0.1.0, each Node maintains its own animation playback state.

This allows multiple game objects to use the same Sprite definition while playing animations independently.

1. What Is a Sprite?

A Sprite represents a visual definition that can be used by game objects.

For example:

• Player characters
• Enemies
• NPCs
• Interactive objects
• Animated decorations

A Sprite may contain a static appearance or multiple animation frames.

BIT8_CLI separates Sprite definitions from individual Node instances.

This means multiple Nodes can reference the same Sprite without sharing their playback position.

2. Sprite Registry

Sprite definitions are stored in an optional project file:

bit8.sprites.toml

This file provides the definitions used by the Runtime's Sprite system.

A project may contain:

my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── bit8.sprites.toml
├── world.b8map
└── assets/
    └── characters (A).png

The Sprite Registry works together with the Asset Registry.

The Asset Registry identifies registered tiles.

The Sprite Registry defines how those tiles are used as Sprites and animations.

The exact TOML table structure should follow the corresponding release implementation.

3. Sprite Definitions

A Sprite definition describes a reusable visual resource.

For example, a project might define a Sprite named:

Player

That Sprite could provide animations such as:

idle
walk
attack

Each animation can reference registered tiles.

For example:

Player
│
├── idle
│   └── A1
│
├── walk
│   ├── A2
│   ├── A3
│   └── A4
│
└── attack
    ├── A5
    └── A6

This diagram illustrates the relationship between a Sprite, its animations, and registered tiles.

It is not a literal TOML configuration.

4. Animation Frames

An Animation consists of frames.

Each frame references graphical content from the registered Asset system.

For example:

walk

Frame 1 → A2
Frame 2 → A3
Frame 3 → A4

During playback, the Runtime selects the appropriate frame based on the animation's timing.

The resulting frame can then be drawn by the Node.

5. Animation Speed

BIT8_CLI supports animation playback rates from:

1 to 30 FPS

FPS means Frames Per Second.

For example:

Animation FPS	Approximate frame duration
1 FPS	1 second
5 FPS	0.2 seconds
10 FPS	0.1 seconds
15 FPS	0.067 seconds
30 FPS	0.033 seconds

The Runtime uses a fixed simulation rate of:

30 Hz

Animation playback speed is configured independently from the simulation rate.

This allows slow and fast animations to coexist within the same game.

6. Binding a Sprite to a Node

A Node can select a Sprite using:

self:sprite("Player")

This references a Sprite definition named Player.

For example:

func init()
    self:sprite("Player")
end

The Sprite must already exist in the project's Sprite Registry.

7. Playing an Animation

Use:

self:play("walk")

to select a named animation.

For example:

func init()
    self:sprite("Player")
    self:play("idle")
end

This selects the Player Sprite and requests its idle animation.

The animation name must exist in the selected Sprite definition.

8. Drawing a Sprite

Use:

self:spr()

to draw the Node's current Sprite frame.

For example:

func draw()
    self:spr()
end

The drawing operation uses the Node's Sprite state and position.

The active Camera may affect the final screen position.

See Camera for more information.

9. Complete Node Example

The following example assumes that:

• A Sprite named Player exists.
• The Sprite defines idle and walk animations.
• The Node has been assigned this script.

func init()
    self:sprite("Player")
    self:play("idle")
end

func update()
    if btn(LEFT) then
        self:move(-1, 0)
        self:play("walk")
    elseif btn(RIGHT) then
        self:move(1, 0)
        self:play("walk")
    else
        self:play("idle")
    end
end

func draw()
    self:spr()
end

This demonstrates how Node movement and animation selection can be combined.

The exact behavior of repeated self:play() calls should be checked against the Runtime implementation, particularly when designing animation transitions.

10. Independent Animation State

One important feature of BIT8_CLI is that animation playback state belongs to each Node.

Consider two Nodes:

Node 1 → Player Sprite → walk

Node 2 → Player Sprite → idle

Both Nodes reference the same Sprite definition.

However, their animation states are independent.

For example:

Node 1
Frame: A3

Node 2
Frame: A1

This makes reusable Sprite definitions practical for multiple game objects.

11. Persistent Sprite References

BIT8_CLI 0.1.0 supports persistent Sprite references in .b8map data.

A Node can store a Sprite name such as:

Player

The Runtime resolves the stored Sprite reference before executing the Node's initialization function.

This allows a Node to begin with its assigned Sprite.

Scripts can still select animations or change the Sprite through the supported Runtime API.

12. Sprites and the Map Workspace

The VS Code Map Workspace supports working with Sprite-related Node properties.

This helps connect visual editing with Runtime behavior.

For example, a Node can be associated with a Sprite definition while editing the Map.

The Runtime then uses the stored project data when loading the game.

The Sprite Registry remains responsible for defining the Sprite's graphical content and animations.

13. Sprites and Registered Assets

Sprites depend on registered graphical assets.

For example:

bit8.assets.toml
        │
        ▼
Registered Tiles
        │
        ▼
bit8.sprites.toml
        │
        ▼
Sprite Definitions
        │
        ▼
Node Animation State
        │
        ▼
Runtime Rendering

This separation provides several benefits:

1. Tiles can be reused across multiple Sprites.
2. Sprite definitions can be reused across multiple Nodes.
3. Each Node can maintain independent animation playback.
4. Registered Asset IDs provide stable references to graphical resources.

See Assets and Tilesheets for details.

14. Current Limitations

BIT8_CLI 0.1.0 provides a lightweight Sprite and Animation system.

It is not a complete skeletal animation or character rigging system.

The established system focuses on:

• Registered tile references
• Reusable Sprite definitions
• Named animations
• Configurable animation FPS
• Independent Node animation state
• Runtime Sprite rendering

Advanced animation systems may be explored in future releases.

Next

Continue with:

Collision

Related documentation:

• Assets and Tilesheets
• Nodes
• Maps
• Camera
• Runtime API

Define a Sprite once. Let every Node bring it to life.