The ZeroPage programming guide
A guide to writing ZeroPage programs, from typed values and C64 hardware to a complete game and relocatable DLLs.
How to follow the guide
Start with types and control flow if you are learning the language. Follow screen and keyboard I/O into the Tic-Tac-Toe case study to see those choices in an application. For memory-intensive projects, read memory placement before arenas and REU views. The DLL walkthrough starts with one call and works up to a shared execution window.
Code labelled as an excerpt shows part of a program. Complete source links let you read the surrounding declarations and run the example. Build and run links open commands on a separate page. The setup page collects tool installation.
Chapters
Write ZeroPage programs
1. Types, control flow, and imports
Read data layout, expressions, and diagnostics through the 6510's byte and word model.
2. Record layout, pointers, and variants
Calculate byte offsets and choose between value copies, pointers, optionals, and tagged unions.
3. C64 I/O and strings
Choose between direct screen writes, memory-mapped registers, and KERNAL services.
4. Inline 6502 assembly
Use source operands, follow the preservation wrapper, and call a ROM routine or terminal vector.
Plan memory and move data
5. Images, placement, and zero page
Plan a PRG and its regions, including startup copies, bank gateways, and reserved zero page.
6. Frames, recursion, and interop
Follow data across static and stack calls, and understand the ReadyOS boundary.
7. Arenas, pools, and records
Choose a visible-RAM arena, a fixed-block pool, or an REU arena and work with structured data.
8. Far data and materialized views
Transfer bytes, fetch typed records, or edit a working range in C64 RAM and flush it.
Load code and build applications
9. DLLs, caches, and activation
Build a first DLL, then follow it from disk to REU to a shared execution window.
10. DLL loading, ownership, and banking
Handle missing disk files, share dependencies, preserve state, and use RAM under ROM.
11. Plan a program that uses disk, REU, and RAM
Build a score updater that combines a disk DLL, an application REU arena, and a near working copy.
12. Read a complete C64 application
Follow Tic-Tac-Toe through input, state, screen RAM, assembly, and verification.
Verify what runs
13. Test a program on the 6510
Write source, compile-fail, and runtime checks with the emulator appropriate to each behavior.
14. Inspect, test, and compare
Read generated artifacts and verify execution on the host 6510 runner and VICE.
Find a worked example by task
- Carry a byte counter into a word and predict its displayed bytes.
- Choose a snapshot or an in-place update for game state.
- Keep a display updating while waiting for a key.
- Pass a string address and length to assembly and trace what the wrapper preserves.
- Capture a KERNAL register result in a typed function.
- Pass a filename to KERNAL and capture carry before the assembly wrapper restores status.
- Reserve bytes for application code and read the resulting zero-page map.
- Encode a record in a near arena or edit a range of far records and flush it to the REU.
- Reuse one working buffer to update an entire far table.
- Update 200 game enemies in batches of 20 with one 240-byte buffer.
- Calculate a map's REU and scratch capacity and test both bounds.
- Stage tile data in REU and fetch a fixed subrange directly to the screen.
- Keep mutable tile state separate from artwork so the two follow different transfer paths.
- Call the same disk DLL two ways, then trace an address into the execution window.
- Keep a byte across DLL unload and reload.
- Compare preload, on-demand, and explicit loading for the same exports.
- Package one DLL build for two applications with different loading policies.
- Trace a spreadsheet through REU-backed formulas, disk staging, and fixed-address overlays.
- Build a disk-backed score updater and diagnose a bad memory plan, signature, or disk.
- Exercise a stack limit with a passing program and a one-byte-smaller variant.
- Trace a word argument through a nested call.
- Trace a three-byte record through a static call.
- Measure a zero-page policy with the same source workload and assertions.
Look up a language or machine contract
Find a term used in the guide
- Arena and pool
- An arena reclaims its allocations together. A fixed-block pool also lets you return individual blocks.
- DLL registry row and active row
- The registry row tracks a module's residency and references. An execution window's active row identifies the module whose code occupies that window.
- Far handle and near pointer
- A far handle identifies an REU allocation. A near pointer addresses the C64's CPU-visible address space.
- Load address, entry address, and run address
- The load address is where the PRG arrives. The entry address is where control starts. A placed section's run address is where its bytes are used after any startup copy.
- Materialized view
- A typed working copy of a whole far view or a range, held in a C64 arena. Flush writes its contents back to REU.
- Relocation
- Patching encoded addresses so a copied DLL can run in its assigned C64 window.
- Sidecar
- A compiler output beside the PRG. Maps and labels support inspection. DLL metadata and relocation files also supply information to caller builds.
- Software stack
- A reserved C64 RAM range for per-call frames. Machine return addresses still go on the 6510 hardware stack.
- Zero-page claim
- A byte or range below
$0100owned by the compiler, system, or application according to the selected policy.