ccboy

Play a Game Boy inside Minecraft using ComputerCraft. This project streams frames from a Python WebSocket server running a Game Boy emulator (PyBoy) to a ComputerCraft/CC:Tweaked client written in Lua. The client renders frames on a monitor and sends button presses back to the emulator.

Works either locally or via Docker for the server. The ComputerCraft client can be hosted on Pastebin for easy installation in‑game.

How It Works

• Server: Python app runs PyBoy on a ROM, converts each screen frame to an NFP palette, compresses it with zlib, and streams it over WebSocket.
  • Entry: main.py
  • WebSocket: websocket_server.py (default 0.0.0.0:8081 in Docker)
  • Frame conversion: screen_converter.py (palette in config.py:20)
  • Input handling: button_handler.py via ACTION_MAP in config.py:36
• Client: gameboy.lua connects via http.websocket, decompresses frames using LibDeflate.lua, loads NFP via surface.lua, draws to the main monitor, and sends touch‑based button events from a second “controller” monitor.

Prerequisites

• Server (if not using Docker):
  • Python 3.9+
  • Packages: pyboy, websockets, numpy
• Docker (optional): Docker installed
• Minecraft side:
  • ComputerCraft or CC:Tweaked with HTTP and WebSocket enabled in the mod config
  • One computer with two attached monitors:
    • Main screen: on the top side
    • Controller screen: on front, back, left, or right
  • Internet access from the CC computer to fetch Pastebin raws (or pre‑bundle the libs)

Quick Start (Docker)

1. Prepare a ROM folder and copy your ROM file (example pokemon.gbc):
   • Create and place under roms/ next to this repo
2. Build the image:
   • docker build -t ccboy .
3. Run the server, mounting your ROMs and exposing the port:
   • docker run --rm -p 8081:8081 -e ROM_FILE=pokemon.gbc -v $(pwd)/roms:/app/roms ccboy
4. Note the WebSocket endpoint for the client:
   • ws://<your-docker-host>:8081

Environment defaults are defined in config.py and the Dockerfile sets sane defaults for container use.

Run Locally (no Docker)

1. Install dependencies in a venv:
   • python -m venv .venv && source .venv/bin/activate
   • pip install pyboy websockets numpy
2. Put your ROM in roms/ and set env vars as needed, then start:
   • export ROM_FILE=pokemon.gbc
   • export ROM_PATH=$(pwd)/roms
   • export WEBSOCKET_HOST=0.0.0.0
   • export WEBSOCKET_PORT=8081
   • python main.py

On start you should see “WebSocket server started on …” in the console.

ComputerCraft Client

• Script: gameboy.lua
• Libraries auto‑downloaded by the client (Pastebin IDs embedded in the script):
  • LibDeflate.lua (zlib decompression): fN3HFQ9f
  • surface.lua (rendering): QiaQ2KBr

Two recommended ways to install the client on a CC computer:

1. Pastebin one‑liner (host gameboy.lua yourself):

   • Upload the contents of gameboy.lua to Pastebin and note the ID, then on the CC computer run:
   • pastebin get <YOUR_PASTE_ID> startup
   • Reboot the computer so it auto‑starts the client.

2. Manual copy (if you can paste directly):

   • Create a file named startup on the CC computer and paste the contents of gameboy.lua.

Before first run, edit the script endpoint if your server isn’t on the CC computer:

• Open gameboy.lua:6 and set base_url to your server, for example:
  • local base_url = "ws://192.168.1.50:8081"

Attach monitors:

• Main display monitor on top of the computer
• Controller monitor on one of: front, back, left, right

Start the CC computer. The client will:

• Connect to the WebSocket, receive compressed frames, and render to the main monitor.
• Draw a simple controller layout on the second monitor. Touching zones sends: up, down, left, right, a, b, select, start.

Controls

• Touch the controller monitor zones to send inputs.
• The client lowercases inputs internally; mapping is defined in config.py:36.

Configuration (Server)

Environment variables read in config.py:

• ROM_FILE: ROM filename inside ROM_PATH (default default.gbc)
• ROM_PATH: folder where ROMs are stored (default /app/roms)
• WEBSOCKET_HOST: bind host (Docker default 0.0.0.0; local default localhost)
• WEBSOCKET_PORT: bind port (default 8081)
• EMULATION_FPS: PyBoy tick rate (default 60)
• SCREEN_UPDATE_RATE: frames pushed per second (default 15)
• COMPRESSION_ENABLED: zlib compression toggle (always used by current server build)

Color palette and nearest‑color logic used for NFP conversion live in config.py:20 and screen_converter.py.

Notes and Tips

• The server uses PyBoy headless mode (window="null") so no GUI is shown on the host.
• The Game Boy screen is centered on the CC monitor. Large monitors improve readability.
• If the CC modpack blocks HTTP/WebSocket, enable them in the CC/CC:Tweaked config or whitelist Pastebin/raw URLs.
• If connection fails on CC, verify base_url points to the server and that port 8081 is reachable from Minecraft.
• Dockerfile references requirements.txt. If absent, create one with at least:
  • pyboy
  • websockets
  • numpy

Project Layout

• main.py: Starts emulator + WebSocket server
• websocket_server.py: Client handler and frame streaming
• emulator.py: PyBoy wrapper and button queuing
• screen_converter.py: RGB frame to NFP characters
• button_handler.py: Maps commands to emulator inputs
• config.py: All tunables and mappings
• gameboy.lua: ComputerCraft client
• lib/LibDeflate.lua, lib/surface.lua: Lua dependencies for the client
• Dockerfile: Container image for the server

License

• This repository is under the GNU AGPL v3 License (LICENSE).