ballz
33d628aa65
Adds tools/convert_screens.py which converts each source PNG to a
160x200 multicolor bitmap (8000 B .bin) plus a 1000 B .attr screen-
memory table, following c64-wiki Multicolor_Bitmap_Mode:
- 2-bit pixel: 00=$D021, 01=attr high nibble, 10=attr low nibble,
11=color RAM nibble.
- Per 4x8 cell: $D021 is forced into the 4-color set (it's global);
the other 3 are the 3 most common non-d021 colors in the cell.
- Pixels snap to the nearest of those 4, then packed 4-per-byte
MSB-first into the bitmap; attr byte = (cell_color_2 << 4) |
cell_color_1 (low nibble = '10' color, high = '01' color).
Tried two downscale strategies on all 5 source images; both produce
visually equivalent output at the ~9x source-to-target scale. Picked
Strategy A (direct 160x200 LANCZOS) as default because it's simpler
and slightly faster; Strategy B (LANCZOS 320x200 then 2x BOX 160x200)
remains available via --strategy. See the script docstring for the
detailed rationale.
$D021 is auto-picked as the most common C64 palette color in the
downscaled image (turns out to be black for 4 of 5 screens, dark grey
for waiting2). The .d021 sidecar files document this value so Phase 2
can program the VIC without re-deriving it.
The '11' color (color RAM nibble per cell) is not stored in .attr (no
room in 1000 B). Default is to leave color RAM at the C64 boot value
(black), which gives effectively 3 unique colors per cell + 1 global.
Phase 2 can either accept this or extend the format with a per-cell
color RAM table.
Generated files are checked in so the build doesn't depend on Python.
Output sizes verified: each .bin is exactly 8000 B, each .attr is
exactly 1000 B, total 9000 B per screen. The .bin files are not all
zero (sanity check passed).
nyuller
A C64 programming project using Oscar64
as the cross-compiler. Oscar64 is checked in as a git submodule under
./oscar64/.
Layout
.
├── oscar64/ # Oscar64 cross-compiler (git submodule)
├── docs/c64/ # Low-level C64 reference (memory map, VIC, CIA, SID, …)
├── src/ # Your C code
│ ├── helloworld.c
│ └── build.sh # Compile + run helper
├── OSCAR64.md # Notes on the Oscar64 compiler internals
└── PROG_C64.md # Notes on programming the C64 hardware
First-time setup
# 1. Clone with submodules:
git clone --recurse-submodules <this-repo-url>
# Or, if you already cloned without --recurse-submodules:
git submodule update --init --recursive
Building
cd src
./build.sh # compile helloworld.c → src/build/helloworld.prg
./build.sh -e # run in oscar64's built-in emulator (headless, fast)
./build.sh -v # run in VICE x64 (interactive, needs a real display)
./build.sh -V # run in VICE x64sc (interactive, cycle-exact)
./build.sh -c # just compile
build.sh will build the oscar64 compiler automatically the first time
(it runs make -C make compiler inside ./oscar64/ if
./oscar64/bin/oscar64 doesn't exist yet).
Default test tool is the oscar64 built-in emulator (-e): it
runs headless, needs no ROMs, no display, and is fast. Every Verify
step in tasks.md uses this.
VICE 3.9 is installed at /usr/bin/ (x64, x64sc, x128,
xvic, xpet) and is available via -v / -V. It is a GUI
emulator and needs a real X11 / Wayland display to render — it
won't produce useful screenshots in this headless environment.
Use it from a real terminal session for interactive play-testing
and cycle-exact validation of raster IRQ and SID timing; don't
expect to script it.
Documentation
PROG_C64.md— how the C64 hardware actually works, from a low-level programming perspective. Start here if you want to understand what's going on under the hood.OSCAR64.md— how the Oscar64 compiler works internally, plus a C64- specific section on how to use it well (memory model, bank switching, raster IRQs, common mistakes).docs/c64/— downloaded reference material: the full Commodore 64 Programmer's Reference Guide text, Christian Bauer's canonical VIC-II paper, and per-chip reference notes.