0.1.0 source preview

ZeroPage

A Zig-shaped language for writing native Commodore 64 programs with explicit control over memory, hardware, and loadable code.

ZeroPage by example

A first program

Use a built-in API to print PETSCII text and write the VIC-II border register.

hello.zp64
const c64 = @import("c64");

export fn main() void {
    c64.console.clear();
    c64.console.print("HELLO FROM ZEROPAGE\n", .{});
    c64.vic.border = 5;
}

Inline 6502 assembly

A block-local loop increments a ZeroPage byte through @color. The compiler restores A, X, and status. The byte and VIC-II writes persist. Assembly chapter

asm-border.zp64
const c64 = @import("c64");

export fn main() void {
    c64.console.clear();
    var color: u8 = 2;
    asm {
        ldx #3
    brighten:
        inc @color
        dex
        bne brighten
        lda @color
        sta $d020
    }
    c64.console.print("BORDER {x}\n", .{color});
}

Read record fields from assembly

The static function reads the nested byte actor.pos.x through its flattened name. It stores the result in a local so ZeroPage can return it after A and status are restored. Source operands and storage

By-value record parameter · excerpt
fn adjustedX(actor: Actor, delta: u8) u8 {
    var result: u8 = 0;
    asm {
        lda @actor_pos_x
        clc
        adc @delta
        sta @result
    }
    return result;
}

Bring a firmware result back into ZeroPage

KERNAL GETIN returns a byte in A. Store it before the wrapper restores A, then return it as a typed value. Read the source and generated wrapper side by side.

Keyboard read · excerpt
fn readKey() u8 {
    var key: u8 = 0;
    asm {
        jsr $ffe4
        sta @key
    }
    return key;
}

Activate a DLL from REU

The typed binding declares the export signature. Loading seeds the REU cache from the resident PRG. A loaded module can be activated again after another module takes its execution window. Walk through disk loading and REU activation.

Load and dispatch · excerpt
extern module RegionDll = region_dll {
    fn tick(value: u8) u8;
}

// Inside main:
if (RegionDll.load()) {
    if (RegionDll.tick(5)) |value| {
        c64.console.print("TICK {x}\n", .{value});
    }
}

Make memory ownership explicit

This declaration reserves visible RAM for short-lived allocations and REU space for far records. Arena and pool chapter

Region declaration
memory {
    region work_ram: c64 at 0x9000 size 0x0010;
    region asset_ram: reu at 0x010000 size 0x0100;
    arena scratch in work_ram;
    arena assets in asset_ram;
}

Move records into C64 RAM

Bring two records into a scratch arena, edit one, and flush the range back to the REU. The local index is relative to the start of the range. Edit a page of a map in REU.

Materialized range excerpt
if (enemies.materializeRange(scratch, 1, 2)) |local| {
    var enemy = local.get(0);
    enemy.hp -= 2;
    enemy.score += 1;
    local.set(0, enemy);
    enemies.flushRange(1, local);
    scratch.reset();
}

Start the programming tutorial · Browse the full guide

Philosophy

Use familiar types, functions, and control flow while keeping the costs of the 6510 visible. The language uses Zig's parser for ordinary syntax. ZeroPage lowers a documented subset and adds declarations for C64 concerns such as banking, zero-page ownership, and module loading.

A small program needs only a main and the helpers it calls. A larger program can choose where code and data live, and inspect the assembled memory map to check those choices. Language reference · Runtime

C64 features

Hardware and I/O

Write to the VIC-II border register, draw directly into screen RAM, or use the PETSCII console, keyboard, KERNAL, and timing helpers. Volatile pointers expose memory-mapped devices. Inline asm { ... } embeds 6502 assembly in the same source. Library API · Inline assembler

Memory and banking

Name C64 and REU ranges in a memory block. Reserve them for arenas, fixed-block pools, the software stack, or DLL windows. Set the PRG load and entry addresses independently. Place selected code and constant data at fixed addresses or copy them into RAM under ROM at startup. Memory model

Zero page and call frames

Specify which zero-page bytes the compiler may use and which are reserved by your code or the system. Static frames give functions fixed storage. callconv(.stack) enables checked recursive frames in a configured RAM region. Calling conventions · Zero-page policy

REU and DLLs

Use explicit DMA transfers and typed views to store data in an REU. A DLL can load from disk into an REU cache, then relocate into a C64 RAM window for execution. DLLs can share a window, and configured state ranges can survive a swap. Typed imports and dependency policies make those calls visible in source. REU and DLLs

Build artifacts and tests

The compiler emits only the runtime helpers it uses. Inspect the 64tass assembly, VICE labels, and memory map. Use the Peddle 6510 test runner for target assertions and VICE for emulator integration. CLI reference · Testing

The Zig subset

Values and storage

bool, u8, i8, u16, i16, 16-bit usize, supported near and volatile pointers, fixed arrays and structs, enum(u8), scalar and pointer optionals, and narrow tagged unions.

Control flow and composition

Typed functions, local @import, if, while, fixed-array and zero-based range for, scalar switch, and layout queries such as @sizeOf.

Target semantics

Runtime array indexing is unchecked. Arithmetic retains the low bits of the destination width. Strings have PETSCII helpers and fixed-capacity buffers.

Unsupported forms

std, generics, general comptime, slices, floating point, division, error unions, try, and defer produce diagnostics. Full language reference

Sample disks

  • ZeroPage demos includes HELLO and a banked-memory example.
  • Tic-Tac-Toe includes the standalone and classic variants.
  • ZeroPage REU boots a disk-loaded DLL example with a 16 MiB REU configured.
  • ZeroPage Sheet includes ten workbooks and uses the REU for data and overlays.

Disk commands and rebuild instructions