Farkle — A UEFI Native Dice Game in C

Farkle is a press-your-luck dice game (also known as Zonk, Hot Dice, Ten Thousand) running natively on UEFI firmware — no operating system required. Built in C99 with a custom pixel-based graphical UI rendered through the UEFI Graphics Output Protocol (GOP).

---

Features

• Bare-metal UEFI application — boots directly from firmware, no OS needed
• Pixel-perfect graphical UI — dice, scoreboard, buttons, and particle effects
• Single-player vs computer — smart rule-based opponent ("Lucky")
• Bilingual UI — English / Chinese, toggle with L key
• Particle effects — score explosions, farkle screen shake, victory confetti
• Direct framebuffer rendering — writes BGRx pixels directly to GOP framebuffer
• Zero external dependencies — self-contained UEFI types in uefi.h, minimal libc stubs
• Zero heap allocation in hot path — stack-buffer formatting, no per-frame allocs
• 13/13 game-logic tests + 46,656 exhaustive fuzz + 300,000 AI states all passing

---

Gameplay

Action	Key
Move cursor	← →
Select / deselect die	Space
Score meld + roll again	R
Score meld + bank	B
Toggle language	L
Quit	Q

Rules (Farkle)

Roll six dice and set aside at least one scoring combination each roll. Re-roll remaining dice. Bank your score at any time. If a roll produces no scoring dice, you Farkle and lose all unbanked points for the turn. First to 5,000 wins.

Meld	Points
Each 1	100
Each 5	50
Three 1s	1,000
Three 2s–6s	200–600
Four of a kind	1,000
Five of a kind	2,000
Six of a kind	3,000
1–6 Straight	1,500
Three pairs	1,500
Two triplets	2,500

---

Technology Stack

Layer	Technology
Language	C11
Compiler	x86_64-w64-mingw32-gcc
Output	Native PE/COFF (EFI application)
UEFI types	Self-defined in src/uefi.h
2D Graphics	Direct GOP framebuffer (pixel-by-pixel)
Chinese Font	Generated from Sarasa Gothic SC (12×12 pixel glyphs)
RNG	Xorshift64* + RDTSC seed (per-boot random)
Emulator	QEMU + OVMF

---

Project Structure

farkle/
├── Makefile                  # Build system (mingw cross-compile)
├── src/
│   ├── uefi.h                # Self-contained UEFI type definitions
│   ├── libc_stubs.c          # Minimal memset/memcpy/strlen for -nostdlib
│   ├── main.c                # UEFI entry point + main game loop (60fps)
│   ├── game.h / game.c       # Farkle rules engine, AI opponent, meld detection
│   ├── game_loop.h / game_loop.c  # Phase dispatcher, RNG, milestones
│   ├── framebuffer.h / framebuffer.c  # GOP double-buffer, text rendering, scanlines
│   ├── input.h / input.c     # Keyboard polling (UEFI SimpleTextIn)
│   ├── effects.h / effects.c # Particle system, screen shake, flash overlay
│   ├── sound.h / sound.c     # PC speaker via PIT (non-blocking)
│   ├── background.h / background.c  # Balatro-style gradient background
│   ├── logger.h / logger.c   # File-based debug logging to ESP
│   ├── ui.h / ui.c           # UI state machine + rendering dispatch
│   ├── ui_dice.h / ui_dice.c # Dice face drawing (pips, glow halos)
│   ├── ui_layout.h / ui_layout.c  # Responsive layout (scales with screen height)
│   ├── ui_lang.h / ui_lang.c # Bilingual EN/CN string tables
│   ├── ui_cn_font.h / ui_cn_font.c  # 12×12 Chinese pixel font (binary search)
│   └── fmt_buf.h / fmt_buf.c # Stack-allocated formatting buffer
├── test/
│   ├── test_game.c           # Game logic test harness (13 tests + exhaustive fuzz)
│   └── test_efi.h            # Type stubs for host-side testing
├── scripts/
│   ├── build.sh              # Build release + stage to esp/
│   ├── verify.sh             # Full verification: build + tests
│   ├── run-qemu.sh           # One-click QEMU launcher (FAT16 image, pflash)
│   ├── run-qemu-gdb.sh       # QEMU with GDB stub (:1234) for remote debugging
│   ├── deploy-usb.sh         # USB deployment (interactive device selection)
│   ├── quick-deploy.sh       # Deploy to /dev/sda with confirmation
│   └── view-log.sh           # View debug log from USB drive
├── esp/                      # Staged EFI boot files
│   └── EFI/BOOT/BOOTX64.EFI
├── game-design-doc.md        # Full game design document
├── rules.md                  # Original Farkle rule reference
└── DEBUG.md                  # Debugging guide

---

Build & Run

Prerequisites

# Arch
sudo pacman -S mingw-w64-gcc edk2-ovmf qemu-desktop mtools

Build

make
# Output: esp/EFI/BOOT/farkle.efi (57 KB)

Verify (build + tests)

bash scripts/verify.sh

Run in QEMU

bash scripts/run-qemu.sh

Run on Real Hardware

sudo scripts/quick-deploy.sh     # Deploy to /dev/sda (USB drive)

---

Design Documents

• game-design-doc.md — Complete game design with state machine, UI layout, scoring algorithm
• rules.md — Original Farkle rule reference
• DEBUG.md — Debugging guide and QEMU setup

---

Acknowledgements

• Chinese font glyphs generated from Sarasa Gothic (SIL Open Font License)
• Original Rust version built with uefi-rs and embedded-graphics

---

License

MIT