Nodes

Nodes

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

Nodes are one of the core building blocks of BIT8_CLI.

A Node represents an object within the game world. It can store properties, execute scripts, interact with collision data, and display a Sprite.

In BIT8_CLI 0.1.0, Nodes are defined as part of the Map system and executed by the Runtime.

Main assembles the game. Nodes live the game.

1. What Is a Node?

A Node is an object that exists within a game world.

For example, a Node might represent:

• A player character
• An enemy
• An NPC
• An interactive object
• A moving platform
• A decorative object with behavior

Each Node can have its own position, properties, and behavior.

Unlike a simple Tile, a Node can execute scripts and maintain runtime state.

2. Nodes and Maps

Nodes are stored as part of Map data.

BIT8_CLI uses the .b8map format for Maps.

A Map can contain:

• Tile data
• Nodes
• Cameras

Nodes are separate from the Tile grid.

This means a Node can move independently of individual Map cells.

For example, a character can move by one pixel even though the Map uses 8×8 pixel Tiles.

See Maps for more information.

3. Node Properties

Each Node exposes several properties to its script.

Property	Description
self.id	Stable Node identifier
self.name	Node name
self.x	Horizontal world position
self.y	Vertical world position
self.enabled	Whether the Node is enabled

For example:

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

This increases the Node's horizontal position during each update.

Node positions use world pixel coordinates.

4. Node Scripts

Nodes can reference scripts written in BIT8_CLI's Lua-based scripting language.

Scripts use the .b8 extension.

For example:

player.b8

A Node script can define lifecycle functions:

func init()
end

func update()
end

func draw()
end

These functions allow a Node to initialize its state, update its behavior, and draw graphics.

The Runtime executes Node scripts as part of the game lifecycle.

5. The self Object

Inside a Node script, self refers to the current Node.

It provides access to Node properties and supported methods.

For example:

func init()
    self.speed = 1
end

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

This example creates a runtime property named speed.

Custom Node state exists during Runtime execution.

Do not assume that custom script properties are automatically saved into the original .b8map file.

6. Node Movement

A Node can change its position directly:

self.x = self.x + 1

However, directly changing coordinates is different from using collision-aware movement.

BIT8_CLI provides:

self:move(dx, dy)

This method attempts to move a Node 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.

7. Collision Detection

BIT8_CLI provides a Node collision query:

self:collide(dx, dy)

This checks whether the proposed movement would collide with supported collision geometry.

The query does not move the Node.

For example:

func update()
    if not self:collide(1, 0) then
        self:move(1, 0)
    end
end

This checks whether movement to the right is blocked before attempting it.

The Runtime supports collision against Solid Tiles.

Nodes can also define optional Collider information.

BIT8_CLI 0.1.0 does not provide a complete physics engine.

See Collision for details.

8. Movement Resolution

Collision-aware movement uses pixel-based movement resolution.

The Runtime processes movement along the X axis before the Y axis.

Movement is resolved using one-pixel steps.

This allows Nodes to interact with the Tile-based collision world while moving at pixel-level precision.

For example:

self:move(2, 1)

attempts movement along the horizontal axis before the vertical axis.

Collision can prevent some or all of the requested movement.

9. Nodes and Sprites

Nodes can use Sprite definitions to display graphics.

Sprite definitions are stored in:

bit8.sprites.toml

A Node can bind a registered Sprite:

self:sprite("Player")

The Sprite can contain named animations.

For example:

self:play("walk")

The current Sprite frame can be drawn using:

self:spr()

A complete example:

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

func draw()
    self:spr()
end

This example assumes that a Sprite named Player and an animation named idle have already been defined.

10. Persistent Sprite References

BIT8_CLI 0.1.0 supports Sprite references stored in Map data.

A Node may have a persistent Sprite name associated with it.

For example, a Node can reference the Sprite definition:

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 without requiring every script to bind it manually.

11. Enabled and Disabled Nodes

Nodes expose an enabled state:

self.enabled

This property indicates whether the Node is enabled.

For example:

func update()
    if self.enabled then
        self.x = self.x + 1
    end
end

The enabled state can be used when implementing gameplay behavior.

The exact Runtime handling of disabled Nodes should be verified against the corresponding release implementation.

12. Main Scripts and Node Scripts

BIT8_CLI separates the main game script from Node behavior.

The main script can organize the overall game lifecycle:

func init()
end

func update()
end

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

Node scripts focus on individual game objects.

For example:

func init()
    self.speed = 1
end

func update()
    self:move(self.speed, 0)
end

func draw()
    self:spr()
end

This separation encourages a modular game structure.

Main assembles the game.

Nodes live the game.

13. Node Editing

BIT8_CLI provides Node editing tools through its VS Code Map Workspace.

The workspace can be used to inspect and modify supported Node properties.

These include:

• Node selection
• Position
• Name
• Script reference
• Enabled state
• Supported Sprite and Collider properties

The Map Workspace edits project data.

The Runtime remains responsible for executing Node behavior.

See Map Workspace for more information.

14. Current Limitations

BIT8_CLI 0.1.0 provides a lightweight Node system.

It is not intended to be a complete scene-tree engine.

Features such as the following are not part of the established 0.1.0 Node model:

• A general-purpose hierarchical scene tree
• Full rigid-body physics
• A complete event or signal system
• Automatic persistence of arbitrary runtime properties

The Node system focuses on lightweight game objects, scripts, movement, and rendering.

Next

Continue with:

Sprites and Animation

Related documentation:

• Maps
• Collision
• Camera
• Map Workspace
• Runtime API

Main assembles the game. Nodes live the game.