From f4ba890eb4b98e1a65a3d9fc8ba8f62dda66895b Mon Sep 17 00:00:00 2001
From: gbc dev <gbc@localhost>
Date: Sat, 4 Jul 2026 23:07:50 +0200
Subject: speed control: frame skipping to decouple terminal draw from
 emulation

Emulation always runs at native rate (correct game speed); --frameskip N draws
only 1 of every N+1 frames so a slow terminal no longer bottlenecks the loop.
Adds --fps cap, --uncapped/--turbo, live [ ] and f keys, HUD readout, and an
exit summary of emulated-vs-drawn fps. Replaces the confusing --render-fps.
---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 620f4c9..0412f4c 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,30 @@ make
 Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least
 160 columns wide.
 
+### Speed & frame skipping
+
+The emulator always advances every Game Boy frame at the correct rate, so
+games run at their intended speed. Because writing a frame to the terminal is
+by far the most expensive step, drawing can be *decoupled* from emulation via
+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)
+```
+
+| Flag              | Meaning                                             |
+|-------------------|-----------------------------------------------------|
+| `--frameskip N`   | draw 1 of every `N+1` emulated frames (default 0)   |
+| `--fps N`         | emulation speed cap in fps (default 59.73 native)   |
+| `--uncapped`/`--turbo` | run emulation as fast as possible              |
+
+Frame skip and turbo are also adjustable live with `[` / `]` and `f`; in turbo
+mode terminal redraws are additionally clamped to ~60 Hz. On exit the emulator
+prints how many frames it emulated vs. actually drew.
+
 ## Controls
 
 | Key            | Button  |
@@ -34,6 +58,8 @@ Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least
 | `x` / `k`      | B       |
 | enter          | Start   |
 | space          | Select  |
+| `f`            | toggle fast-forward (turbo) |
+| `[` / `]`      | decrease / increase frame skip |
 | `q` / Ctrl-C   | Quit    |
 
 Since terminals don't report key-release, buttons are held for a few frames
-- 
cgit v1.3.1-sl0p