diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 78 |
1 files changed, 39 insertions, 39 deletions
@@ -1,4 +1,4 @@ -# gbc — a Game Boy Color emulator in C, rendered to the terminal +# sl0pboy — a Game Boy Color emulator in C, rendered to the terminal A from-scratch Game Boy / Game Boy Color emulator written in plain C11. It renders graphics directly to the terminal using 24-bit (truecolor) ANSI escape @@ -17,15 +17,15 @@ over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint. ```sh make -./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 +./build/sl0pboy path/to/rom.gb # interactive (ROM is the final argument) +./build/sl0pboy --test 30 rom.gb # run 30s, log serial to stderr (test roms) +./build/sl0pboy --shot 60 out.ppm rom.gb # run 60 frames, dump a PPM screenshot +./build/sl0pboy --sixel 3 rom.gb # sixel graphics output at 3x zoom +./build/sl0pboy --sixel 3 --chrome rom.gb # ...wrapped in a Game Boy body/frame +./build/sl0pboy --bios rom.gb # boot through the BIOS before the game +./build/sl0pboy --sock rom.gb # open a control/debug socket (/tmp/sl0pboy.sock) +./build/sl0pboy --headless rom.gb # no video; serial <-> stdio (OS console) +./build/sl0pboy --help # full option list ``` ### Boot ROM / BIOS (`--bios`) @@ -37,9 +37,9 @@ 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 +./build/sl0pboy --bios roms/pky.gbc # defaults to bios/gbc_bios.bin +./build/sl0pboy --bios path/to/boot.bin roms/pky.gbc +./build/sl0pboy --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 @@ -62,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 --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 +./build/sl0pboy --headless os.gb # interactive byte console +./build/sl0pboy --headless --uncapped os.gb # as fast as possible +printf 'ls\n' | ./build/sl0pboy --headless os.gb # feed input, capture output +./build/sl0pboy --headless os.gb | tee session.log ``` The serial console model matches what a GB program expects: write the byte to @@ -83,8 +83,8 @@ mlterm, Contour, recent iTerm2, etc.) pass `--sixel [scale]` to render true pixels instead of half-blocks: ```sh -./build/gbc --sixel rom.gb # default 2x zoom (320×288 pixels) -./build/gbc --sixel 4 rom.gb # 4x zoom +./build/sl0pboy --sixel rom.gb # default 2x zoom (320×288 pixels) +./build/sl0pboy --sixel 4 rom.gb # 4x zoom ``` Each frame builds a per-frame palette from the framebuffer (≤256 entries — 4 @@ -103,7 +103,7 @@ 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 +./build/sl0pboy --sixel 3 --chrome rom.gb ``` The shell is drawn with flat colors so it adds only a handful of palette @@ -118,9 +118,9 @@ 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 +./build/sl0pboy --sixel 3 --chrome --palette dmg rom.gb # classic DMG-01 pea green +./build/sl0pboy --sixel 3 --green rom.gb # alias for --palette dmg +./build/sl0pboy --palette gray rom.gb # GB-Pocket grayscale ``` Names: `dmg`/`green` (the iconic `#9bbc0f` pea-green ramp) and `pocket`/`gray` @@ -136,9 +136,9 @@ frame skipping — the machine keeps running in real time while the terminal is refreshed less often: ```sh -./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) +./build/sl0pboy --frameskip 2 rom.gb # emulate 60 fps, draw every 3rd frame (20 fps) +./build/sl0pboy --fps 120 rom.gb # run the game at 2x speed +./build/sl0pboy --uncapped rom.gb # run as fast as possible (turbo) ``` | Flag | Meaning | @@ -169,20 +169,20 @@ after each keypress (relying on the terminal's key-repeat for sustained holds). ### External control channel (FIFO) -Start with `--fifo [path]` (default `/tmp/gbc.fifo`) to open a named pipe that +Start with `--fifo [path]` (default `/tmp/sl0pboy.fifo`) to open a named pipe that accepts button commands from any process. Unlike the terminal keyboard, this can send true key-**release** events, so it gives deterministic input for scripting and automated testing. ```sh -./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 -echo 'a b' > /tmp/gbc.fifo # tap A and B together (Left still held) -echo '-left' > /tmp/gbc.fifo # release Left -echo 'release' > /tmp/gbc.fifo # release everything held -echo 'a:30' > /tmp/gbc.fifo # tap A, held for 30 frames +./build/sl0pboy --fifo /tmp/sl0pboy.fifo rom.gb & +echo 'a' > /tmp/sl0pboy.fifo # momentary tap of A +echo 'start' > /tmp/sl0pboy.fifo # tap Start +echo '+left' > /tmp/sl0pboy.fifo # press and HOLD Left +echo 'a b' > /tmp/sl0pboy.fifo # tap A and B together (Left still held) +echo '-left' > /tmp/sl0pboy.fifo # release Left +echo 'release' > /tmp/sl0pboy.fifo # release everything held +echo 'a:30' > /tmp/sl0pboy.fifo # tap A, held for 30 frames ``` Commands (one line, space/comma separated tokens, case-insensitive): @@ -202,16 +202,16 @@ use the socket control channel below, which is a strict superset. ### Socket control & debug channel -Start with `--sock [path]` (default `/tmp/gbc.sock`) to open a Unix-domain +Start with `--sock [path]` (default `/tmp/sl0pboy.sock`) to open a Unix-domain stream socket. It accepts everything the FIFO does **plus** emulator introspection commands, and — being a socket — it *replies* to each command and pushes asynchronous events when execution stops. Connect any line-oriented client: ```sh -./build/gbc --sock /tmp/gbc.sock rom.gb & -socat - UNIX-CONNECT:/tmp/gbc.sock # interactive -# or: nc -U /tmp/gbc.sock +./build/sl0pboy --sock /tmp/sl0pboy.sock rom.gb & +socat - UNIX-CONNECT:/tmp/sl0pboy.sock # interactive +# or: nc -U /tmp/sl0pboy.sock ``` The protocol is line based (one command per line). Replies start with `ok` or |