Collision

Collision

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

BIT8_CLI provides a lightweight collision system for tile-based 2D games.

In BIT8_CLI 0.1.0, Nodes can detect obstacles and perform collision-aware movement using Solid Tiles and supported Collider data.

The system focuses on simple, predictable movement rather than full physics simulation.

1. Collision Overview

The Collision system connects three components:

• Solid Tiles: Map tiles that block movement.
• Node Colliders: Optional collision geometry associated with Nodes.
• Movement API: Methods for checking and attempting movement.

The main Node methods are:

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

These methods allow scripts to interact with the collision world.

2. Solid Tiles

Tiles can be marked as Solid through the Asset Registry.

The registry is stored in:

bit8.assets.toml

For example:

solid = [6]

This marks the sixth tile in the corresponding registered tilesheet as Solid.

The example is a configuration fragment, not a complete registry file.

Solid Tiles occupy their entire 8×8 pixel area for collision purposes.

3. Tile Coordinates and Collision

BIT8_CLI uses 8×8 pixel tiles.

For example:

Tile (0, 0) → Pixels (0–7, 0–7)
Tile (1, 0) → Pixels (8–15, 0–7)
Tile (0, 1) → Pixels (0–7, 8–15)

A Solid Tile blocks movement through its occupied area.

Node movement operates in world pixel coordinates, allowing finer movement than the tile grid.

4. Node Colliders

Nodes can include optional Collider information.

A Collider defines collision geometry associated with a Node.

This allows the Runtime to evaluate movement against supported collision geometry.

Collider configuration is stored with the Node's Map data.

The exact supported Collider properties and file syntax should be checked against the 0.1.0 implementation.

5. Checking Collision

Use:

self:collide(dx, dy)

to check whether a proposed movement would collide.

For example:

func update()
    if self:collide(1, 0) then
        -- Movement to the right is blocked.
    end
end

The parameters represent the proposed movement offset.

The collision query does not change the Node's position.

6. Collision-Aware Movement

Use:

self:move(dx, dy)

to attempt movement while respecting supported collision rules.

For example:

func update()
    self:move(1, 0)
end

This attempts to move the Node one pixel to the right.

If collision blocks the movement, the resulting displacement may be smaller than requested.

7. Movement Resolution

BIT8_CLI 0.1.0 resolves collision-aware movement using one-pixel steps.

Movement is processed in this order:

1. X axis
2. Y axis

For example:

self:move(3, 2)

The Runtime attempts horizontal movement before vertical movement.

Each axis is resolved through pixel-level steps.

This makes collision behavior suitable for lightweight tile-based movement.

8. Collision Query vs. Movement

The two methods serve different purposes.

Method	Purpose	Changes position
self:collide(dx, dy)	Checks proposed movement	No
self:move(dx, dy)	Attempts collision-aware movement	Yes, when movement is possible

For simple movement, self:move() may be sufficient.

Use self:collide() when game logic needs to inspect obstacles before deciding what to do.

9. Example: Player Movement

The following example uses the directional input constants:

func update()
    if btn(LEFT) then
        self:move(-1, 0)
    end

    if btn(RIGHT) then
        self:move(1, 0)
    end

    if btn(UP) then
        self:move(0, -1)
    end

    if btn(DOWN) then
        self:move(0, 1)
    end
end

This provides basic collision-aware movement in four directions.

The example assumes the script is attached to a Node configured for the relevant collision behavior.

10. Direct Position Changes

A Node can also change its coordinates directly:

self.x = self.x + 1

However, directly changing position is not the same as calling:

self:move(1, 0)

Use collision-aware movement when obstacles should affect the Node.

Direct coordinate changes are useful when intentional repositioning is required.

11. Collision and Maps

Collision data is closely connected to Maps.

A Map contains Tile data, while the Asset Registry identifies which registered tiles are Solid.

Nodes use this information during collision queries and movement.

See Maps and Assets and Tilesheets for more information.

12. Current Limitations

BIT8_CLI 0.1.0 provides a lightweight collision system.

It is not a complete physics engine.

The established collision model does not include:

• Full rigid-body dynamics
• Gravity simulation as an automatic physics feature
• Realistic forces and momentum
• Advanced collision shapes as a general physics framework

Developers can implement game-specific movement behavior using Node scripts.

Next

Continue with:

Camera

Related documentation:

• Nodes
• Maps
• Assets and Tilesheets
• Runtime API

Collision defines where a Node can go.