Getting people back into the physical world, one object at a time.
Most games keep you seated, staring at a screen. Yolo Game does the opposite. It gives you a prompt, starts a 2-minute countdown, and sends you sprinting through your house to hold a real object up to the camera before time runs out. YOLO26 MLX runs entirely on your Apple Silicon Mac, no cloud, no latency, recognizing objects as fast as you can find them.
A local-first scavenger hunt game powered by YOLO26 MLX on-device object detection.
- 5 rounds per session - rounds 1–3 use easy household prompts; rounds 4–5 ramp to hard. Each round starts a 2-minute timer and activates your camera.
- Find it fast - score decays linearly from 100 to 0 over 2 minutes. Finding the object scores 2× the current HUD value.
- Tap Give Up to collect a share of remaining score - the share grows as time passes, so there's a sweet spot around the halfway mark.
- Run out the clock and you score 0 for that round.
- Works best on a Mac where you can move around -hold the laptop and walk room to room, or prop it up and run back with objects.
Built for the WebAI YOLO26 MLX Build Challenge - Austin-flavored track.
Pre-built Apple Silicon releases include the game, yolo26n weights, and an embedded Python/MLX runtime. No Homebrew, venv, or manual model download required.
- Open the DMG and drag Yolo Game to Applications.
- Launch the app; allow camera access when macOS prompts.
- Wait for “Loading inference model…” to finish (~5-10s first launch), then tap Play Now.
- Apple Silicon Mac (M1, M2, M3, or M4) - MLX requires Apple Silicon
- macOS 13+
- Python 3.10+
- Node.js 18+
- npm 9+
git clone https://github.com/bishopZ/yolo-game.git
cd yolo-gamenpm installElectron binary: Electron 42+ downloads its runtime on the first
npm start(not duringnpm install). The first launch may take a minute while the binary is fetched.Cursor / VS Code: Some editors set
ELECTRON_RUN_AS_NODE=1, which breaksrequire('electron'). Thestartscript unsets that variable automatically on macOS/Linux.
# Python 3.10–3.12 recommended (MLX / yolo-mlx)
python3.12 -m venv .venv
source .venv/bin/activate
# Install yolo-mlx from GitHub (or pip install -e /path/to/yolo-mlx clone)
pip install -r inference/requirements.txtNote: Requires Apple Silicon.
requirements.txtinstalls yolo-mlx from GitHub. Override the interpreter withYOLO_PYTHONwhen launching the app.
Quick path (if you have a local yolo-mlx clone):
export YOLO_MLX_ROOT=/path/to/yolo-mlx # optional if auto-detected
bash scripts/setup_model.shManual path - from the yolo-mlx repo root:
bash scripts/download_yolo26_models.sh
yolo-mlx converters convert models/yolo26n.pt -o models/yolo26n.npz --verifyCopy (or symlink) the resulting yolo26n.npz into this repo:
mkdir -p models
cp /path/to/yolo-mlx/models/yolo26n.npz models/The game expects weights at models/yolo26n.npz relative to the repo root. The file must be a real NPZ zip archive (typically ~6MB). If you only have yolo26n.pt, place it at models/yolo26n.pt - the game can load .pt directly, or convert it with the command above.
Activate your Python venv, then:
source .venv/bin/activate
npm startThe app launches an Electron window. The model loads and warms up in the background (JIT compile on first inference - typically 5-10 seconds on M-series). The Play Now button activates once the model is ready.
Camera permission: macOS may prompt for camera access. Click Allow.
Renderer (Electron web view)
└─ Canvas grabs 640×480 RGBA frame from <video>
└─ ArrayBuffer → contextBridge → Electron main process
└─ Raw bytes → Python subprocess stdin
└─ numpy.frombuffer → RGB → yolo26n.predict()
└─ JSON detection line → stdout
└─ Result relayed back to renderer
└─ Bounding boxes drawn on overlay canvas
└─ If detected label matches target prompt → round scored
Inference runs at ~5fps. Camera preview runs at native frame rate. Only the detection overlay updates at inference speed.
Model: yolo26n - the smallest YOLO26 variant, ~6MB NPZ, 5.9ms inference on M4 Pro. COCO class vocabulary (80 classes) maps to the puzzle map of 33 household-findable prompts.
You leave the JSON-only path and train or fine-tune a model that emits new class labels, then point the Python subprocess at those weights.
Prerequisites
- Apple Silicon Mac, macOS 13+
- Python 3.10+ venv with
yolo26mlx - Local clone of yolo-mlx and weights tooling
- Labeled images for your new classes (or a workflow that produces them)
- Comfort with WebAI’s Infernace / fine-tune flow
Process (headline steps)
- Train or obtain weights - Use upstream YOLO26 MLX + Infernace docs to add detection heads for your classes and export a compatible
.npz/.pt. - Install weights - Place the file under
models/(or setYOLO_MODELwhen launching). - Wire inference - Ensure
inference/server.pyloads your variant; adjust env vars documented in Setup if needed. - Map prompts - Add
puzzle_map.jsonentries whoseclassesstrings exactly match the labels your model returns. - Play-test - Run at home; tune
YOLO_CONFif finds are too strict or loose.
Full training commands, dataset formats, and Infernace UI steps live in YOLO26 MLX (yolo-mlx).
If you modify inference/server.py or bundle custom weights, AGPL-3.0 applies to what you distribute - see LICENSE.
yolo-game/
├── main.cjs Electron main process (subprocess spawn, IPC)
├── preload.cjs contextBridge API surface (CJS for Electron 42 / Node 24)
├── package.json
├── inference/
│ ├── server.py Python inference subprocess (stdin/stdout IPC)
│ └── requirements.txt
├── scripts/
│ ├── time_ipc.py Round-trip latency benchmark (verifies AC-03)
│ └── detect_test.py Standalone detection test (verifies AC-04)
├── renderer/
│ ├── index.html Main game UI
│ ├── app.js UI logic (state machine subscriber)
│ ├── styles.css Mobile-first responsive styles
│ ├── game.js State machine + scoring engine
│ ├── puzzle_map.json 33 household prompts → COCO class names
│ ├── test.html IPC smoke-test page (dev use)
│ └── tests/
│ ├── scoring.test.js Scoring unit tests (AC-07)
│ └── state.test.js State machine unit tests
└── models/ .gitignored — place yolo26n.npz here
This city's motto used to be "Austin, the friendly city." It is a friendly town. People talk to each other in the grocery store, on the street, in the park. Austinites are very present in the physical world. When thinking about the challenge and the Austin category, I didn't want to just slap a bat logo on the title screen. I wanted to build a product that is shaped by the place, the culture, and daily life. I didn't want it be superficially Austin-themed. Such as, a traffic monitor that just happens to be in Austin. I also didn't want it to be stereotypical: bats, tacos, keeping it weird. I wanted something that would capture the lifeblood of the city: curious, friendly, fun, supportive, and experimental. I wanted something that used the newest technology, yet gets us to re-engage with our physical environment.
Yolo Game fits that frame in a few concrete ways.
- Get out of your chair: It assumes a real home, not a staged lab bench. You move room to room. The camera is the referee.
- Have fun: Yolo Game is a game after all, but the most fun part is that anyone can run inference to create new puzzles. The core game mechanices scale beyond what the game ships with.
- Make friends: Yolo Game is fun to play solo, but it's even more fun to play with friends or family. It doesn't require a group, but it' an immediate activity or ice breaker for any social gathering.
AGPL-3.0 - required by the WebAI challenge terms. See LICENSE for full text.
- YOLO26 MLX - upstream inference library by WebAI
- Built by Bishop Zareh for the WebAI YOLO26 MLX Build Challenge, May 2026