Screen RAM, color, and VIC-II
c64.screen writes the default screen at $0400 and color RAM. Screen codes represent glyphs on screen. c64.console accepts text and manages a cursor, newlines, and scrolling. c64.vic.border maps to $d020. For other registers, use a volatile pointer and the register's hardware contract.
const c64 = @import("c64");
fn poke(ptr: *volatile u8, value: u8) void {
ptr.* = value;
}
fn peek(ptr: *volatile u8) u8 {
return ptr.*;
}
export fn main() void {
c64.console.clear();
c64.console.print("pointer mmio\n", .{});
var value: u8 = 1;
const local_ptr: *u8 = &value;
local_ptr.* = 0x21;
c64.console.print("local {x}\n", .{local_ptr.*});
const border: *volatile u8 = @ptrFromInt(0xd020);
const background: *volatile u8 = @ptrFromInt(0xd021);
poke(border, 5);
background.* = 0;
const m0: *volatile u8 = @ptrFromInt(0x04a0);
const m1: *volatile u8 = @ptrFromInt(0x04a1);
const m2: *volatile u8 = @ptrFromInt(0x04a2);
const m3: *volatile u8 = @ptrFromInt(0x04a3);
const m4: *volatile u8 = @ptrFromInt(0x04a4);
m0.* = 'M';
m1.* = 'M';
m2.* = 'I';
m3.* = 'O';
m4.* = '!';
if (peek(m0) == 'M' and value == 0x21) {
c64.console.print("poke ok\n", .{});
} else {
c64.console.print("poke bad\n", .{});
border.* = 2;
}
}
Use ptr.* for a single-item pointer and ptr[i] for a many-item pointer. Volatile reads and writes reach the device. When your program banks memory or changes VIC-II screen configuration, check the assumptions of built-in helpers.
Distinguish screen codes from PETSCII bytes
In this language, the character literal 'A' is screen code $01. In the default screen layout, a store to $0400 writes that code directly. putAt takes a screen code and putsAt converts text to screen codes. Each approach puts $01 into its destination in the example below.
const c64 = @import("c64");
export fn main() void {
c64.screen.clear();
const row: [*]volatile u8 = @ptrFromInt(0x0400);
row[0] = 'A';
c64.screen.putAt(1, 0, 'A');
c64.screen.putsAt(2, 0, "A");
c64.screen.hexAt(0, 2, row[0]);
c64.screen.hexAt(3, 2, row[1]);
c64.screen.hexAt(6, 2, row[2]);
}
Expect AAA and, two rows below, 01 01 01. Compare that with reading A from the keyboard, which returns PETSCII $41 in the standard input configuration. If you are matching keyboard input, use the PETSCII value or the appropriate c64.key constant. Use screen codes when writing cells directly and PETSCII text with KERNAL output.
PETSCII, formatting, and buffers
String constants and buffers are length-counted. The PETSCII and ASCII wrappers choose byte encoding explicitly. A mutable string has fixed capacity and static storage. Appending beyond capacity truncates. Format fields {s}, {x}, and {x16} take arguments in an anonymous tuple.
const c64 = @import("c64");
const hello = "hello, ";
const subject = "mutable";
export fn main() void {
c64.console.clear();
c64.console.print("MUTABLE STRING DEMO\n", .{});
var msg = c64.string.buffer(40);
msg = hello ++ subject;
c64.string.append(msg, " ok\n");
c64.console.puts(msg);
c64.string.clear(msg);
c64.string.append(msg, "runtime ");
c64.string.append(msg, "append\n");
c64.console.puts(msg);
c64.string.clear(msg);
msg = "kernal " ++ "buffer ok\r";
c64.kernal.puts(msg);
c64.kernal.setName(msg);
c64.console.print("BUFFER SETNAM OK\n", .{});
}
Use the assembly string operands when native code needs the data address or length.
Choose a pointer or a screen helper
A literal MMIO address is useful when the hardware register itself is part of the program's contract. A screen helper computes an address from a row and column. A many-item volatile pointer lets you step through consecutive registers or RAM cells with explicit offsets. These are target addresses. Confirm the mapped device and keep runtime offsets within its range.
Direct volatile access fixture · Indexed volatile access fixture · String encoding and buffer fixtures
Build a line from text and PETSCII controls
Use c64.petscii constants when a control byte should affect the display. A text line can contain an explicit clear, home, reverse-video, or color control. c64.string.ascii and c64.string.petscii specify how literal bytes are interpreted. Use the wrapper that matches the consumer. The control-string demo appends content to a fixed buffer, so every append shares its capacity limit.
const c64 = @import("c64");
const title = c64.petscii.clear ++ c64.petscii.home ++ "controls demo\n";
const banner = c64.petscii.reverse_on ++ "reverse" ++ c64.petscii.reverse_off ++ "\n";
const raw = c64.string.petscii("raw byte: \x41\n");
const host = c64.string.ascii("ascii proxy: ok\n");
const multi = c64.string.petscii(
\\multi
\\line
);
export fn main() void {
c64.console.clear();
c64.console.puts(title);
c64.console.puts(banner);
c64.console.puts(raw);
var msg = c64.string.buffer(64);
msg = "buffer " ++ c64.petscii.yellow ++ "control\n";
c64.string.append(msg, host);
c64.string.append(msg, multi);
c64.console.puts(msg);
}
Complete control-string demo · Length, concatenation, and buffer assertions
KERNAL, keyboard, and timing
readPetscii() returns zero when the buffer is empty. waitPetscii() waits for the first nonzero byte, drains further buffered bytes until GETIN returns zero, and returns the first byte. The empty-buffer check does not observe physical key release. c64.key provides named keys. Use KERNAL calls with the appropriate ROM mapping and system workspace.
const c64 = @import("c64");
export fn main() void {
c64.console.clear();
c64.console.print("keyboard demo\n", .{});
c64.console.print("poll A\n", .{});
var first = c64.keyboard.readPetscii();
while (first == c64.key.none) {
first = c64.keyboard.readPetscii();
}
if (first == 65) {
c64.console.print("read A ok\n", .{});
} else {
c64.console.print("read bad {x}\n", .{first});
}
c64.console.print("wait down\n", .{});
const cursor = c64.keyboard.waitPetscii();
if (cursor == c64.key.cursor_down) {
c64.console.print("wait down ok\n", .{});
c64.vic.border = 5;
} else {
c64.console.print("wait bad {x}\n", .{cursor});
c64.vic.border = 2;
}
}
Poll with readPetscii() when the rest of the program must keep running between keys. Use the blocking form for a prompt that can wait. sleepTicks waits for changes in the low byte of CIA1 timer A at $dc04. sleepFrames waits for the low raster register at $d012 to leave zero and return to it. These are polling loops over the hardware registers. Their timing depends on the running hardware and its configuration. Use VICE to observe behavior that depends on the VIC-II or CIA.
Keep updating the display while you wait for a key
Try the running counter below. Each pass asks for one buffered key. A stops the loop. With an empty buffer, the program advances the counter, writes it to the screen, and paces the next poll with a short raster wait. Use the same structure to advance a game, animate a cursor, or keep a status display current.
const c64 = @import("c64");
export fn main() void {
c64.console.clear();
c64.console.print("PRESS A TO STOP\n", .{});
var ticks: u8 = 0;
var running: bool = true;
while (running) {
const key = c64.keyboard.readPetscii();
if (key == 0x41) {
running = false;
} else {
ticks += 1;
c64.screen.hexAt(0, 2, ticks);
c64.time.sleepFrames(2);
}
}
c64.screen.putsAt(0, 4, "STOPPED");
c64.vic.border = 5;
}
Let the count run, then press A. The screen shows STOPPED and the border turns green. The counter is a byte and wraps. The delay illustrates pacing on the default machine mapping. It gives no exact wall-clock interval and does not let other source code run concurrently.
For a prompt that can pause everything, use waitPetscii(). Use a poll when input should share the loop with drawing or game rules. If each keystroke matters, consume the buffered bytes with readPetscii() so the blocking helper does not drain subsequent keys. See polling in the Tic-Tac-Toe case study.