diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 98 |
1 files changed, 80 insertions, 18 deletions
@@ -17,14 +17,37 @@ over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint. ```sh make -./build/gbc path/to/rom.gb # interactive -./build/gbc rom.gb --test 30 # run 30s, log serial to stderr (test roms) -./build/gbc rom.gb --shot 60 out.ppm # run 60 frames, dump a PPM screenshot -./build/gbc rom.gb --sixel 3 # sixel graphics output at 3x zoom -./build/gbc rom.gb --sock # open a control/debug socket (/tmp/gbc.sock) -./build/gbc rom.gb --headless # no video; serial <-> stdio (OS console) +./build/gbc path/to/rom.gb # interactive (ROM is the final argument) +./build/gbc --test 30 rom.gb # run 30s, log serial to stderr (test roms) +./build/gbc --shot 60 out.ppm rom.gb # run 60 frames, dump a PPM screenshot +./build/gbc --sixel 3 rom.gb # sixel graphics output at 3x zoom +./build/gbc --sixel 3 --chrome rom.gb # ...wrapped in a Game Boy body/frame +./build/gbc --bios rom.gb # boot through the BIOS before the game +./build/gbc --sock rom.gb # open a control/debug socket (/tmp/gbc.sock) +./build/gbc --headless rom.gb # no video; serial <-> stdio (OS console) +./build/gbc --help # full option list ``` +### Boot ROM / BIOS (`--bios`) + +By default the emulator skips the boot ROM and starts the cartridge directly +with the documented post-boot register state. Pass `--bios [path]` to instead +run a real boot ROM first, so you get the authentic power-on animation (the +Nintendo logo drop, and on a CGB the color splash + chime) before control is +handed to the game: + +```sh +./build/gbc --bios roms/pky.gbc # defaults to bios/gbc_bios.bin +./build/gbc --bios path/to/boot.bin roms/pky.gbc +./build/gbc --bios --sixel 3 --chrome roms/pky.gbc # boot inside the shell +``` + +The boot ROM is mapped over low memory (with the CGB header hole at +`0x0100-0x01FF` where the cartridge shows through) and unmaps itself when the +ROM writes `0xFF50`, exactly like hardware. A 256-byte image boots as DMG; a +2304-byte image (like the bundled `bios/gbc_bios.bin`) boots as CGB — which +also colorizes plain DMG games via the boot ROM's compatibility palette. + ### Headless serial console (`--headless`) For bring-up and debugging of an OS/monitor running on the emulated Game Boy, @@ -39,10 +62,10 @@ Emulation is paced to native speed by default; add `--uncapped` to run flat out. Because it's plain stdio it pipes and scripts cleanly: ```sh -./build/gbc os.gb --headless # interactive byte console -./build/gbc os.gb --headless --uncapped # as fast as possible -printf 'ls\n' | ./build/gbc os.gb --headless # feed input, capture output -./build/gbc os.gb --headless | tee session.log +./build/gbc --headless os.gb # interactive byte console +./build/gbc --headless --uncapped os.gb # as fast as possible +printf 'ls\n' | ./build/gbc --headless os.gb # feed input, capture output +./build/gbc --headless os.gb | tee session.log ``` The serial console model matches what a GB program expects: write the byte to @@ -60,8 +83,8 @@ mlterm, Contour, recent iTerm2, etc.) pass `--sixel [scale]` to render true pixels instead of half-blocks: ```sh -./build/gbc rom.gb --sixel # default 2x zoom (320×288 pixels) -./build/gbc rom.gb --sixel 4 # 4x zoom +./build/gbc --sixel rom.gb # default 2x zoom (320×288 pixels) +./build/gbc --sixel 4 rom.gb # 4x zoom ``` Each frame builds a per-frame palette from the framebuffer (≤256 entries — 4 @@ -71,6 +94,39 @@ run-length encoding. `scale` is an integer pixel zoom (1–6). Sixel frames are sent in full (no inter-frame diffing), so combine with `--frameskip` on slower terminals. +#### Game Boy chrome + +Add `--chrome` (sixel only) to draw a DMG-style **sl0pboy** handheld around the +LCD — screen bezel with accent stripe, power LED, silk-screened branding +(`sl0pboy` logo, `DOT MATRIX WITH STEREO SOUND`, button labels), a D-pad, A/B +buttons, Start/Select and a speaker grille. The controls light up while the +matching button is held, so it doubles as an on-screen input display: + +```sh +./build/gbc --sixel 3 --chrome rom.gb +``` + +The shell is drawn with flat colors so it adds only a handful of palette +entries. It composites into a larger canvas (240×342 px before scaling), so a +given `scale` produces a proportionally bigger image than the bare LCD. + +#### LCD palette (`--palette`) + +By default the LCD shows the game's true colors (the greenish DMG shades, or +full CGB color). Pass `--palette NAME` to remap every LCD pixel to a 4-shade +palette by luminance for the classic monochrome-LCD look — this even greens +out full-color CGB games for that retro vibe: + +```sh +./build/gbc --sixel 3 --chrome --palette dmg rom.gb # classic DMG-01 pea green +./build/gbc --sixel 3 --green rom.gb # alias for --palette dmg +./build/gbc --palette gray rom.gb # GB-Pocket grayscale +``` + +Names: `dmg`/`green` (the iconic `#9bbc0f` pea-green ramp) and `pocket`/`gray` +(grayscale). The recolor applies to every render path — half-block, sixel and +chrome — and only touches the LCD, not the drawn shell. + ### Speed & frame skipping The emulator always advances every Game Boy frame at the correct rate, so @@ -80,9 +136,9 @@ frame skipping — the machine keeps running in real time while the terminal is refreshed less often: ```sh -./build/gbc rom.gb --frameskip 2 # emulate 60 fps, draw every 3rd frame (20 fps) -./build/gbc rom.gb --fps 120 # run the game at 2x speed -./build/gbc rom.gb --uncapped # run as fast as possible (turbo) +./build/gbc --frameskip 2 rom.gb # emulate 60 fps, draw every 3rd frame (20 fps) +./build/gbc --fps 120 rom.gb # run the game at 2x speed +./build/gbc --uncapped rom.gb # run as fast as possible (turbo) ``` | Flag | Meaning | @@ -119,7 +175,7 @@ can send true key-**release** events, so it gives deterministic input for scripting and automated testing. ```sh -./build/gbc rom.gb --fifo /tmp/gbc.fifo & +./build/gbc --fifo /tmp/gbc.fifo rom.gb & echo 'a' > /tmp/gbc.fifo # momentary tap of A echo 'start' > /tmp/gbc.fifo # tap Start echo '+left' > /tmp/gbc.fifo # press and HOLD Left @@ -153,7 +209,7 @@ pushes asynchronous events when execution stops. Connect any line-oriented client: ```sh -./build/gbc rom.gb --sock /tmp/gbc.sock & +./build/gbc --sock /tmp/gbc.sock rom.gb & socat - UNIX-CONNECT:/tmp/gbc.sock # interactive # or: nc -U /tmp/gbc.sock ``` @@ -190,7 +246,7 @@ or decimal; **memory bytes are hex** (so `read` output feeds straight back into ### Video capture & input replay (demo GIFs) -Capture the RGB framebuffer to a flat file and turn it into a GIF: +Capture the displayed frame to a flat file and turn it into a GIF: ``` ./gbctl record start /abs/out.gbv 2 # capture 1 of every 2 frames (~30fps) @@ -199,6 +255,12 @@ Capture the RGB framebuffer to a flat file and turn it into a GIF: python3 tools/gbgif.py out.gbv out.gif --scale 3 ``` +Recording captures exactly what's on screen: if the emulator was started with +`--palette` and/or `--chrome`, those are baked into the capture (the `.gbv` +header records the resulting dimensions, so e.g. chrome frames are 240×362 and +`gbgif.py` picks that up automatically). `--shot` screenshots honor the same +options. Start without them for the bare 160×144 true-color LCD. + Drive the ROM from a **synthesized input movie** instead of live input, for reproducible demos. A movie is a text file of `<frames> [buttons...]` lines (`a b start select up down left right`; none/`-` = released); the emulator |