Maps

Maps

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

BIT8_CLI provides a tile-based Map system for creating 2D game worlds.

Maps use registered Asset IDs, support editable dimensions, and can contain Nodes and Cameras.

This guide introduces the Map system in BIT8_CLI 0.1.0.

1. Map Overview

BIT8_CLI uses a fixed tile size of:

8 × 8 pixels

The default Map dimensions are:

64 × 64 tiles

A Map can be configured with dimensions from:

1 × 1 to 256 × 256 tiles

The maximum number of Map cells is:

65,536

Map dimensions are independent of the 64×64 game framebuffer.

A Map can therefore be much larger than the visible game screen.

2. Map Files

BIT8_CLI stores Map data in files using the extension:

.b8map

For example:

world.b8map

Map files contain tile data and may also define Nodes and Cameras.

A project may contain a structure such as:

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

This is an illustrative project layout.

3. Map Coordinates

Maps use tile-based coordinates.

Each Map cell represents an 8×8 pixel area in the game world.

For example:

Tile (0, 0) → World pixels (0, 0)

Tile (1, 0) → World pixels (8, 0)

Tile (2, 0) → World pixels (16, 0)

Tile (0, 1) → World pixels (0, 8)

To convert a tile coordinate into a pixel coordinate:

pixel_x = tile_x × 8
pixel_y = tile_y × 8

For example, tile coordinate (5, 3) corresponds to world pixel coordinate (40, 24).

4. Map Cells

Each Map cell can reference a registered Tile.

For example:

A1
A2
A3

These identifiers refer to Tiles registered through:

bit8.assets.toml

An empty Map cell is represented by:

--

A simplified Map might look like:

A1 A1 A1 A1 A1
A1 -- -- -- A1
A1 -- A2 -- A1
A1 -- -- -- A1
A1 A1 A1 A1 A1

This is a conceptual representation of Map cells, not a complete .b8map file.

5. Drawing Maps

Use map() to draw the current Map.

func draw()
    cls(0)
    map()
end

This clears the framebuffer and draws the Map.

The visible area depends on the framebuffer and active Camera.

For complete parameter details, refer to the corresponding BIT8_CLI release source.

6. Reading Map Cells

BIT8_CLI provides:

mget(...)

This API reads a Tile value from the Runtime Map.

Map operations use tile coordinates rather than pixel coordinates.

7. Modifying Map Cells

BIT8_CLI provides:

mset(...)

This API modifies a Tile value in the Runtime Map.

Runtime Map modifications affect the running game state.

They should not be confused with saving changes to the original .b8map file through the Editor.

8. Map Workspace

BIT8_CLI includes a Map Workspace integrated into its VS Code extension.

The workspace provides visual tools for working with Map data.

Features include:

• Map canvas
• Tile selection
• Tile painting
• Map cell inspection
• Zoom controls
• Node selection and editing
• Camera visualization
• Property inspection

The Map Workspace uses the same underlying project data as the Runtime.

The editor interface is not the authoritative definition of Map behavior.

9. Nodes in Maps

Maps can contain Nodes.

A Node may define:

• Stable Node ID
• Name
• Position
• Enabled state
• Script reference
• Optional Sprite reference
• Optional Collider

Nodes are part of the game's world structure.

Their scripts can control behavior during Runtime execution.

For example, a Node script can update its position:

func update()
    self.x = self.x + 1
end

See Nodes for details.

10. Cameras in Maps

Maps can contain Camera Nodes.

A Camera determines which part of the world is visible.

BIT8_CLI uses a 64×64 viewport.

Camera coordinates represent the center of that viewport.

Supported world-space rendering operations are transformed relative to the active Camera.

Screen-space operations such as:

cls(0)
pix(32, 32, 7)

remain in screen coordinates.

See Camera for details.

11. Solid Tiles and Collision

Registered Tiles can be marked as Solid.

For example:

solid = [6]

This marks the sixth Tile in the corresponding registered Tilesheet as Solid.

Solid Tiles occupy their full 8×8 pixel area for collision detection.

Node collision methods can interact with these tiles:

self:collide(dx, dy)
self:move(dx, dy)

See Collision for more information.

12. Map Size and Performance

The maximum supported Map dimensions are:

256 × 256 tiles

The maximum supported cell count is:

65,536 cells

A Map does not need to fit inside the 64×64 framebuffer.

Only the visible region is relevant to the current view.

Large Maps should still be designed with the project's rendering and gameplay requirements in mind.

13. Current Limitations

BIT8_CLI 0.1.0 provides a tile-based Map system.

The following features are not part of the established 0.1.0 Map system:

• Multiple independent Map layers
• Large background images placed directly as world objects
• A complete physics engine

These may be explored in future versions.

Next

Continue with:

Nodes

Related documentation:

• Assets and Tilesheets
• Collision
• Camera
• Map Workspace
• Runtime API

Maps define the world. Nodes bring behavior into it.