Babel-8 and Babble,
without the mystery.

01 / first program

Start in five minutes

Babble is the C-like source language. Babel-8 is the bytecode machine that runs the result. Ordinary programs should start in Babble; raw Babel instructions are useful when inspecting generated code, generating random artifacts, or exploiting operations the high-level compiler does not expose yet.

u8 x = 28;
u8 y = 28;

fn main() {
    palette(0, NAVY);
    palette(1, CYAN);

    layer(0);
    fill(0);                  // opaque background using palette slot 0

    loop {
        layer(1);
        clear();              // erase last frame's moving layer

        if (held(LEFT))  { x--; }
        if (held(RIGHT)) { x++; }
        if (held(UP))    { y--; }
        if (held(DOWN))  { y++; }

        fill_rect(x, y, 4, 4, 1, REPLACE);
        yield;                // let the browser present this frame
    }
}

02 / what exists

The machine model

The machine never faults. Addresses, registers, stacks, and the PC wrap. Division by zero has a defined result. All 256 opcode values do something deterministic. This is why arbitrary 1,024-byte files can be run without validating them first.

03 / compositor

Why there are four framebuffers

They are layers, numbered 0 through 3. Layer 0 is the bottom; layer 3 is the top. Every drawing operation affects only the active layer selected by layer(n). At presentation time, the compositor checks layer 3, then 2, then 1, then 0, and displays the first visible pixel.

Transparent is not black

Every layer pixel has a two-bit color slot and a separate visibility bit. A transparent pixel reveals the layer below. A visible pixel whose color is slot 0 covers lower layers with whatever master color slot 0 currently selects—often black.

Moving without damaging the background

// Draw once.
layer(0);
fill(NAVY);         // Wrong: fill expects slot 0–3, not master color.

// Correct:
palette(0, NAVY);
layer(0);
fill(0);

// Every frame:
layer(1);
clear();
sprite1(x, y, hero, 2, REPLACE);

Flips, scrolling, rotation, inversion, row shift, and column shift affect only the active layer. They move colors and visibility together. Pixels revealed by scrolling are transparent.

04 / palette

Choosing colors

Screen pixels store only a slot from 0 to 3. The active palette maps those four slots to four of the machine's 16 master colors. Calling palette(slot, masterColor) changes the meaning of every existing pixel using that slot immediately.

palette(0, BLACK);
palette(1, CYAN);
palette(2, ORANGE);
palette(3, WHITE);

fill_rect(4, 4, 20, 10, 2, REPLACE); // uses slot 2 → ORANGE

Blend modes

XOR and Add treat a transparent destination as color 0, then make it visible. Palette changes are effectively free color cycling because pixel data does not change.

05 / time

Frames, yield, sleep, and work

A host frame samples buttons, increments the frame counter, ticks timers and timed voices, then gives the CPU 16,384 work units. The CPU continues until it yields, sleeps, halts, reaches a breakpoint, or cannot fit the next atomic instruction into the remaining budget.

When to yield

Put yield; once at the end of the main game loop. It declares that the frame is complete and execution should resume at the following instruction next frame.

fn main() {
    setup();
    loop {
        read_input();
        update_game();
        draw_frame();
        yield;
    }
}

Yield versus sleep

Expensive instructions are atomic. A 16,384-cost full-layer hash either runs completely or waits for a fresh frame budget; it never produces a half-hashed state.

06 / controls

Held, pressed, and released

Keys are LEFT, RIGHT, UP, DOWN, A, B, START, and SELECT.

07 / high-level language

Babble language reference

Values and declarations

u8 score = 0;                    // global byte
u8 map[64] = [1, 2, 3, 4];      // remaining elements start at zero
const SPEED = 2;                 // compile-time value
asset hero = [0x18, 0x3C, 0x7E, 0xDB, 0xFF, 0x24, 0x42, 0x81];

fn add(u8 left, u8 right) {
    u8 result = left + right;    // local byte
    return result;
}

All scalar values are unsigned bytes. Arithmetic wraps modulo 256: 255 + 1 is 0 and 0 - 1 is 255. Arrays occupy consecutive RAM bytes. Assets occupy immutable asset ROM and do not consume RAM.

Operators

Control flow

if (score >= 10) { score = 0; } else { score++; }

while (timer_get(0) != 0) { yield; }

for (u8 i = 0; i < 16; i++) {
    map[i] = i * 3;
}

switch (mode) {
    case 0: fill(0); break;
    case 1: fill(1); break;
    default: clear(); break;
}

loop {
    if (pressed(B)) { break; }
    if (!held(A)) { yield; continue; }
    score++;
}

Functions and recursion

Functions accept up to four u8 parameters. Arguments travel through R0–R3 and the return value uses R0. Recursive calls are supported by saving the caller's static parameter/local frame and live expression registers on the 64-byte data stack.

Compiler behavior

Globals and locals receive fixed RAM addresses. Initial values are emitted as startup instructions. The optional ROM optimizer folds constants, emits direct comparison branches, threads jumps, and removes redundant or unreachable instructions. The artifact is always 1,024 bytes even when only a few code slots are used.

08 / standard library

Every Babble builtin

Constants accepted by builtins

Keys: LEFT RIGHT UP DOWN A B START SELECT

Blend modes: REPLACE XOR ADD ERASE

Waveforms: SQUARE TRIANGLE SAW SINE

Master colors: BLACK NAVY PURPLE PLUM RED ORANGE YELLOW CREAM FOREST GREEN MINT CYAN BLUE INDIGO VIOLET WHITE

09 / storage

RAM, assets, and stacks

RAM

RAM is 1,024 mutable bytes. Babble assigns globals, parameters, locals, and arrays fixed addresses. Array indexes are not bounds-checked; an out-of-range index continues into neighboring RAM and ultimately wraps at 1,024.

Asset ROM

Asset ROM is 512 immutable bytes stored in the second half of the artifact. Use it for sprites, maps, lookup tables, or arbitrary constants. Asset addresses wrap modulo 512. A one-bit sprite consumes 8 bytes; a two-bit sprite consumes 16.

X and Y index registers

Raw Babel code uses 10-bit X and Y for the full RAM address range, asset access, block copying, sprite sources, and bulk operations. Direct LOAD and STORE reach only addresses 0–255; LOADX/STOREX reach all 1,024 bytes through X or Y plus an encoded offset.

Two separate stacks

Both stacks are circular. Pushing when full overwrites the oldest logical entry. Popping when empty returns zero.

10 / patterns

Practical recipes

Palette cycling

switch (frame(0) & 15) {
    case 0: palette(1, CYAN); break;
    case 8: palette(1, VIOLET); break;
    default: break;
}

Non-blocking fire cooldown

if (pressed(A) && timer_get(0) == 0) {
    spawn_projectile();
    beep(0, 110, SQUARE, 2);
    timer_set(0, 12);
}

Recursive work followed by halt

u8 input = 10;
u8 result;

fn fib(u8 n) {
    if (n < 2) { return n; }
    return fib(n - 1) + fib(n - 2);
}

fn main() {
    result = fib(input);
    return; // return from main compiles to HALT
}

11 / sharp edges

Important quirks

12 / raw machine

Bytecode anatomy

Instruction n lives at code bytes 2n and 2n+1. The first byte is the opcode; the second is an immediate, register selector, descriptor, or branch destination depending on the opcode.

00: 00 2A    LDI R0, 0x2A
01: 10 01    ADDI R0, 0x01
02: 48 05    STORE [0x05], R0
03: F1 00    HALT

Flags

Z means the most recent flag-setting result was zero. Addition sets C on carry. Subtraction and comparison set C when no borrow was required. Many movement, memory, drawing, and device instructions preserve flags.

Conditional move conditions

13 / complete ISA

Every Babel-8 instruction

Ranges with eight opcodes use the opcode's low three bits to choose R0–R7. Ignored operand bits may contain anything. All operations below are valid for every operand byte.

14 / strange and powerful

Crazy memory operations

The E0–EF family is where Babel-8 stops behaving like a tiny ordinary CPU. These are raw machine instructions; most do not yet have direct Babble builtins. You can encounter them in random artifacts, hand-authored bytecode, disassembly, and decompiler output.

Instant transformations

• FILLRAM, XORRAM, ADDRAM, and INVERTRAM transform all 1 KiB in one atomic instruction.
• COPYBLOCK moves up to 256 bytes and handles overlap as if a temporary copy was made.
• ROTATERAM rotates the entire memory image, useful for ring buffers, procedural state, or deliberate chaos.

RAM as a 128×64 cellular world

LIFE, TOTALISTIC, and XORNEIGHBOURS interpret RAM's 8,192 bits as a toroidal 128×64 grid. The source and destination are logically separate, so a generation never reads partially updated neighbors.

Hashes as tiny signatures

HASHRAM and HASHSCREEN place a 32-bit FNV-1a hash in R0–R3. They are useful for conformance tests, procedural decisions, state fingerprints, or checking that two executions remain deterministic.

15 / understanding programs

Debugger, optimizer, and decompiler

Debugger

Breakpoints can be attached to source lines or raw instruction addresses. A breakpoint pauses before execution. Step instruction runs one atomic operation; step frame samples input and runs until a frame boundary. The layer inspector shows any raw layer without mutating machine state.

ROM optimizer

Enable Optimize ROM to reduce instruction count. Optimization preserves source-level behavior but changes instruction addresses, timing cost, debugger traces, artifact bytes, and therefore the artifact-seeded RNG sequence.

Decompiler

Attempt decompile follows reachable branches, identifies function candidates, names direct RAM locations, recognizes common compiler patterns, and emits pseudo-Babble. Unknown operations become asm(). It cannot recover original names, comments, scopes, or the author's exact control structures.

This handbook describes Babel-8 v2 draft 1 and the browser Babble compiler currently shipped with the VM.