Assets and Tilesheets

Assets and Tilesheets

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

BIT8_CLI uses registered PNG tilesheets to provide graphics for games.

Each tilesheet is divided into 8×8 pixel tiles. Registered tiles receive stable Asset IDs that can be referenced by scripts, maps, sprites, and collision definitions.

This guide introduces the asset system in BIT8_CLI 0.1.0.

1. Tilesheets

A tilesheet is a PNG image containing multiple tiles.

BIT8_CLI uses a fixed tile size:

8 × 8 pixels

For example, a 32×16 PNG contains:

• 4 columns
• 2 rows
• 8 tiles

Tiles are numbered in row-major order, from left to right and then from top to bottom.

32 × 16 PNG

+------+------+------+------+
|  A1  |  A2  |  A3  |  A4  |
+------+------+------+------+
|  A5  |  A6  |  A7  |  A8  |
+------+------+------+------+

Each tile occupies exactly 8×8 pixels.

2. Asset Registry

BIT8_CLI uses an asset registry to manage registered tilesheets.

The registry is stored in:

bit8.assets.toml

The registry associates tilesheets with stable group identifiers.

For example, a registered tilesheet may use group A.

Its tiles can then be referenced as:

A1
A2
A3
A4

The registry is the source of truth for asset identity.

Do not assume that simply placing a PNG inside a project automatically registers it.

Use the project's asset registration workflow to create or update registry entries.

3. Stable Asset IDs

BIT8_CLI uses stable identifiers consisting of:

Group + Tile Number

Examples:

A1
A4
B12
C3

The group identifies a registered tilesheet.

The number identifies a tile within that tilesheet.

This design allows scripts and maps to reference tiles without depending on a global numeric ordering.

For example:

spr(A4, 16, 16)

draws tile A4 at the specified coordinates.

Why Stable IDs Matter

Imagine a project with multiple tilesheets.

If assets depended entirely on their position in a global list, adding or rearranging tilesheets could change existing references.

Stable Asset IDs help avoid this problem.

BIT8_CLI also tracks retired group identifiers to prevent accidental reuse.

4. Registered PNG Names

Registered tilesheets use a canonical filename pattern:

<name> (<GROUP>).png

For example:

terrain (A).png
characters (B).png
items (C).png

The group identifier is part of the registered asset identity.

The Asset Registry remains authoritative.

Renaming a registered PNG manually without updating its registration may break asset references.

5. Drawing Tiles

Use spr() to draw a registered tile.

func draw()
    cls(0)
    spr(A4, 16, 16)
end

This example clears the screen and draws tile A4.

The referenced tile must exist in the project's registered assets.

BIT8_CLI also preserves legacy numeric sprite references for compatibility with older projects.

For new projects, stable Asset IDs are recommended.

6. Transparency and Palette

BIT8_CLI supports transparent pixels in registered PNG tilesheets.

Transparent pixels are treated as transparent when tiles are rendered.

PNG colors are converted to the runtime palette representation.

The asset pipeline is designed to keep runtime rendering and editor previews consistent.

For predictable results, use pixel-art images with clearly defined colors and transparency.

7. Solid Tiles

Tiles can be marked as solid for collision detection.

Solid tile metadata belongs to the Asset Registry.

For example, a tilesheet may mark tile number 6 as solid:

solid = [6]

This value represents the sixth tile within its registered tilesheet group.

A solid tile occupies its full 8×8 pixel area for collision purposes.

Solid tile collision can be used by Node collision methods such as:

self:collide(dx, dy)

and:

self:move(dx, dy)

The solid property must be placed in the appropriate registered asset entry in bit8.assets.toml, not as an unrelated top-level setting.

See Collision for more information.

8. Assets and Maps

Maps reference registered Asset IDs.

A map cell can contain a tile reference such as:

A1
A2
A3

This allows maps to use tiles from different registered groups.

The Map Workspace provides tools for selecting registered tiles and painting map cells.

See Maps for details.

9. Assets and Sprites

Tiles are also used by Sprite definitions.

A Sprite can reference registered tiles to define:

• A static preview
• Animation frames
• Named animations

Sprite definitions are stored in:

bit8.sprites.toml

For example, a Sprite named Player may use several registered tiles as animation frames.

Node scripts can then control its animation:

self:play("walk")

and draw the current frame:

self:spr()

See Sprites and Animation for more information.

10. Asset Management Guidelines

When managing assets:

1. Register PNG tilesheets through the supported asset workflow.
2. Keep registered group identifiers stable.
3. Avoid manually reassigning existing Asset IDs.
4. Update registry entries when changing registered asset files.
5. Check map and Sprite references before removing assets.
6. Use retired group identifiers to prevent accidental identity reuse.

Stable IDs are intended to protect references, but they do not automatically guarantee that every asset edit preserves the same visual meaning.

For example, rearranging tiles inside a registered PNG can change which artwork an existing tile ID refers to.

11. Example Project Structure

A project using registered tilesheets may contain:

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

This is an illustrative layout. Actual registered asset paths must match the Asset Registry.

Next

Continue with:

Maps

Related documentation:

• Sprites and Animation
• Collision
• Runtime API
• Map Workspace

Stable Asset IDs let game content reference registered tiles consistently across scripts, maps, and sprites.