Skip to content

Free games for graphing calculators: NumWorks, TI-Nspire CX, Casio fx-CG50 and soon TI-84 Plus CE. Balatro, Celeste, Hollow Knight, Minecraft and more.

Live emulator: on macOS and Linux too

Mason363a9d207dfc2f7
diff --git a/.gitignore b/.gitignore
index 8f0288ff..ffc1e5a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ games/tetris/*/target/
games/tetris/tetris/src/data/image.nppm
# made by the Pages workflow (tools/badges.py)
docs/badges/
+dist/
diff --git a/tests/test_games.py b/tests/test_games.py
index 93fc6b20..3a18a000 100644
--- a/tests/test_games.py
+++ b/tests/test_games.py
@@ -54,7 +54,7 @@ GAMES = {
(3500, "ok", 250)), 5500,
presses((1500, "ok", 250), (2000, "right", 250), (2500, "ok", 250), (3000, "left", 250),
(3500, "ok", 250)), 5500),
- "tetris": ("Tetris.nwa", "tetris.sav", presses((1200, "ok")) + every(2500, 7000, 500, "ok"), 8000,
+ "tetris": ("Tetris.nwa", "tetris.sav", presses((1200, "ok")) + every(2500, 7000, 500, "up"), 8000,
presses((1200, "ok"), (2500, "ok")), 5000),
# start and run into the first cactus: a best; next time, start and hold OK (the keyboard's
# repeat jumps again on landing): further, a better best
diff --git a/tools/emu.py b/tools/emu.py
index b44a4fb4..7bab5af3 100644
--- a/tools/emu.py
+++ b/tools/emu.py
@@ -193,8 +193,7 @@ class Calculator:
a = s["st_value"] & ~1
self.functions.append((a, a + s["st_size"], s.name))
self.functions.sort()
- e.stream.close()
- # meow
+ e.stream.close() # (else Windows can't delete the temporary folder: the file is still open)
uc = self.uc = Uc(UC_ARCH_ARM, UC_MODE_THUMB | UC_MODE_MCLASS)
uc.mem_map(FLASH, FLASH_SIZE)
uc.mem_map(SRAM, SRAM_SIZE)
diff --git a/tools/emu_live.py b/tools/emu_live.py
index 2d1129b0..e6dedf51 100644
--- a/tools/emu_live.py
+++ b/tools/emu_live.py
@@ -1,9 +1,11 @@
#!/usr/bin/env python3
-"""Windows-friendly live NumWorks emulator — responsive single-file calculator skin.
+"""Live NumWorks emulator for macOS, Linux and Windows: a calculator you can click, around tools/emu.py.
Put this file beside tools/emu.py. Requires Pillow, numpy, unicorn,
-pyelftools, tkinterdnd2 and nwlink. Displays the NumWorks keyboard artwork
-from the locally installed k-kuroguro VS Code extension (CC BY-NC-SA).
+pyelftools and nwlink (tkinterdnd2 for dropping files, if you like). It shows the
+NumWorks keyboard artwork of the k-kuroguro VS Code extension (CC BY-NC-SA) when
+that extension is installed, read in place and never copied; otherwise it draws a
+calculator of its own.
Runs an ARM .nwa through the project's existing emu.Calculator, shows the
320x240 display, supports 46 clickable keys, keyboard, .nwa drops and reload.
@@ -14,7 +16,8 @@ To run:
The calculator skin does not depend on emu_live_skin.py; emu.py is still needed.
NumPlay Live Emulator V22 (USB push with live progress, opt-in):
-- Single file / Live development, automatic native Windows builds and reloads;
+- Single file / Live development: it builds again when you save, and reloads
+ (tools/watch.py on macOS and Linux, tools/build_windows.py on Windows);
- calculator skin / pixel-exact 320x240 screen, keyboard highlights;
- tear-reduced frame presentation, usable Epsilon firmware text;
- N0120 display-transfer timings calibrated using physical NumWorks results;
@@ -68,7 +71,8 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
HOME_NWA = Path.home() / "Downloads" / "nwa"
SAVE_DIR = Path.home() / ".numplay-emulator" / "saves"
LIVE_NWA = REPO_ROOT / "dist" / "live" / "NumPlay.nwa"
-BUILD_SCRIPT = REPO_ROOT / "tools" / "build_windows.py"
+BUILD_SCRIPT = REPO_ROOT / "tools" / ("build_windows.py" if os.name == "nt" else "watch.py")
+BUILTIN_SKIN = Path.home() / ".numplay-emulator" / "calculator.png"
LCD_WIDTH = 320
LCD_HEIGHT = 240
FRAME_VIRTUAL_MS = 32
@@ -180,7 +184,11 @@ def find_nwas() -> list[Path]:
def nwlink_command() -> str | None:
if os.name == "nt":
return shutil.which("nwlink.cmd") or shutil.which("nwlink.exe")
- return shutil.which("nwlink")
+ for p in (shutil.which("nwlink"), Path.home() / ".numplay" / "node_modules" / ".bin" / "nwlink",
+ REPO_ROOT / "games" / "numdash" / "node_modules" / ".bin" / "nwlink"):
+ if p and Path(p).exists():
+ return str(p)
+ return None
def fingerprint(path: Path) -> tuple[int, int] | None:
@@ -218,6 +226,9 @@ class FidelityFont:
Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts" / "segoeui.ttf",
Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts" / "arial.ttf",
Path("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"),
+ Path("/System/Library/Fonts/Supplemental/Arial.ttf"),
+ Path("/Library/Fonts/Arial.ttf"),
+ Path("/System/Library/Fonts/Helvetica.ttc"),
)
self.cells = {}
self.cache = {}
@@ -1467,6 +1478,41 @@ def installed_artwork() -> Path | None:
return max(files, key=lambda x: x.stat().st_mtime_ns) if files else None
+def builtin_artwork() -> Path:
+ """A calculator of its own, for when the VS Code extension isn't installed: the same layout (HOTSPOTS,
+ SCREEN) on a 1160 x 2221 picture, drawn once and kept in ~/.numplay-emulator."""
+ if BUILTIN_SKIN.is_file():
+ return BUILTIN_SKIN
+ w, h = 1160, 2221
+ im = Image.new("RGB", (w, h), (232, 234, 238))
+ d = ImageDraw.Draw(im)
+ d.rounded_rectangle((6, 6, w - 7, h - 7), radius=96, fill=(250, 250, 251), outline=(200, 204, 211), width=6)
+ sx, sy, sw, sh = SCREEN[0] * w, SCREEN[1] * h, SCREEN[2] * w, SCREEN[3] * h
+ d.rounded_rectangle((sx - 36, sy - 36, sx + sw + 36, sy + sh + 36), radius=28, fill=(38, 40, 46))
+ d.rectangle((sx, sy, sx + sw, sy + sh), fill=(0, 0, 0))
+ font = None
+ for name in ("DejaVuSans.ttf", "/System/Library/Fonts/Supplemental/Arial.ttf", "/Library/Fonts/Arial.ttf",
+ str(Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts" / "arial.ttf")):
+ try:
+ font = ImageFont.truetype(name, 42)
+ break
+ except OSError:
+ pass
+ font = font or ImageFont.load_default()
+ nav = {"left", "right", "up", "down", "home", "onoff", "ok", "back"}
+ for key, (x, y, kw, kh) in HOTSPOTS.items():
+ box = (x * w, y * h, (x + kw) * w, (y + kh) * h)
+ fill = (212, 216, 222) if key in nav else (225, 228, 233) if key in FUNCTIONS else (255, 255, 255)
+ d.rounded_rectangle(box, radius=min(box[2] - box[0], box[3] - box[1]) * 0.22, fill=fill,
+ outline=(178, 183, 192), width=4)
+ label = "DEL" if key == "backspace" else LABEL.get(key, key) # (⌫ isn't in most fonts)
+ tw, th = d.textbbox((0, 0), label, font=font)[2:]
+ d.text(((box[0] + box[2] - tw) / 2, (box[1] + box[3] - th) / 2), label, fill=(48, 52, 60), font=font)
+ BUILTIN_SKIN.parent.mkdir(parents=True, exist_ok=True)
+ im.save(BUILTIN_SKIN)
+ return BUILTIN_SKIN
+
+
class CalculatorSkinApp(LiveApp):
"""NumWorks skin with mutually exclusive file and live-development modes.
@@ -1814,9 +1860,8 @@ class CalculatorSkinApp(LiveApp):
if self.build_process is not None and self.build_process.poll() is None:
return
if not BUILD_SCRIPT.is_file():
- self._set_build_state("Builder not found", "Expected tools/build_windows.py", error=True)
- messagebox.showerror("Live build", f"Missing build script:\n{BUILD_SCRIPT}\n\n"
- "Put the working Windows build helper V7 in tools/build_windows.py.")
+ self._set_build_state("Builder not found", f"Expected tools/{BUILD_SCRIPT.name}", error=True)
+ messagebox.showerror("Live build", f"Missing build script:\n{BUILD_SCRIPT}")
return
# A previous process may still be shutting down. Never run concurrent
# builds of the same directory.
@@ -1844,7 +1889,7 @@ class CalculatorSkinApp(LiveApp):
self.build_process = None
return
self.live_button.configure(text="Stop live build")
- self._set_build_state("Starting Windows compiler…", "Checking dependencies", busy=True)
+ self._set_build_state("Starting the compiler…", "Checking dependencies", busy=True)
thread = threading.Thread(target=self._read_builder_output,
args=(generation, self.build_process), daemon=True)
thread.start()
@@ -2536,13 +2581,13 @@ class CalculatorSkinApp(LiveApp):
def main():
- ap = argparse.ArgumentParser(description="NumWorks-shaped .nwa emulator: single-file and live-build modes for Windows")
+ ap = argparse.ArgumentParser(description="NumWorks-shaped .nwa emulator: single-file and live-build modes, on macOS, Linux and Windows")
ap.add_argument("nwa", nargs="?", type=Path, help="optional .nwa path, or drop it after launching")
ap.add_argument("--nwlink", default=nwlink_command())
ap.add_argument("--skin-image", type=Path, help="path to extension's resources/webview/background.png")
ap.add_argument("--model", choices=("n0120", "n0110"), default="n0120")
ap.add_argument("--system", choices=("epsilon", "upsilon"), default="epsilon")
- ap.add_argument("--live", action="store_true", help="open Live development mode and start the Windows build watcher inside the GUI")
+ ap.add_argument("--live", action="store_true", help="open Live development mode and start the build watcher inside the GUI")
ap.add_argument("--follow-newest", action="store_true", help="legacy alias for --live (no ambiguous newest-file scanning)")
ap.add_argument("--profile-speed", action="store_true",
help="print a measured ARM/render/pacing speed report every 5 seconds")
@@ -2560,9 +2605,8 @@ def main():
ap.error("nwlink not found. Run: npm install -g [email protected]")
art = args.skin_image or installed_artwork()
if not art or not art.is_file():
- ap.error("NumWorks skin not found. Install k-kuroguro's Numworks Simulator in VS Code, "
- "or pass --skin-image PATH pointing to resources/webview/background.png.\n"
- f"Image source: {ART_SOURCE}")
+ # (k-kuroguro's Numworks Simulator for VS Code gives the real calculator's picture: see ART_SOURCE)
+ art = builtin_artwork()
if os.name == "nt":
# Avoid Windows silently bitmap-scaling the *whole* Tk window at 125%/
# 150% display scale, which would defeat the native 1:1 LCD view.
diff --git a/tools/watch.py b/tools/watch.py
new file mode 100644
index 00000000..46c19a61
--- /dev/null
+++ b/tools/watch.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Builds NumPlay (or one game) again each time a source file is saved, for the live emulator on macOS and Linux
+(tools/emu_live.py --live; on Windows it uses tools/build_windows.py). Each good build is copied to
+dist/live/NumPlay.nwa in one step, so the emulator never reads half a file; a failed build keeps the last good one.
+
+ python3 tools/watch.py NumPlay (build/NumPlay.nwa)
+ python3 tools/watch.py --game sokoban one game on its own (games/sokoban's Makefile)
+ python3 tools/watch.py --once build once and stop
+
+Needs what `make` needs (python3 tools/setup.py gets it). It prints the lines the live emulator follows:
+"Detected edits (...)", "Building: ...", "Stable live-emulator input: ...", "Build failed; ...",
+"Watching for the next edit".
+"""
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+LIVE = os.path.join(ROOT, "dist", "live", "NumPlay.nwa")
+WATCHED = (".c", ".h", ".S", ".s", ".rs", ".py", ".json", ".txt", ".png", ".inc", "Makefile")
+SKIP = {"build", "output", "dist", "node_modules", "target", ".git", "__pycache__"}
+
+
+def stamp(folders):
+ """The newest change time among the sources, and how many there are."""
+ newest, n = 0.0, 0
+ for top in folders:
+ for d, dirs, files in os.walk(top):
+ dirs[:] = [x for x in dirs if x not in SKIP]
+ for f in files:
+ if f.endswith(WATCHED):
+ try:
+ newest = max(newest, os.stat(os.path.join(d, f)).st_mtime)
+ n += 1
+ except OSError:
+ pass
+ return newest, n
+
+
+def nwlink():
+ for p in (shutil.which("nwlink"), os.path.join(os.path.expanduser("~"), ".numplay", "node_modules", ".bin", "nwlink"),
+ os.path.join(ROOT, "games", "numdash", "node_modules", ".bin", "nwlink")):
+ if p and os.path.exists(p):
+ return p
+ return "npx --yes -- [email protected]"
+
+
+def build(game, jobs):
+ if game:
+ target = ["make", "-C", os.path.join(ROOT, "games", game), "-j%d" % jobs, "NWLINK=" + nwlink()]
+ out = None
+ else:
+ target = ["make", "-C", ROOT, "-j%d" % jobs, "build/NumPlay.nwa", "NWLINK=" + nwlink()]
+ out = os.path.join(ROOT, "build", "NumPlay.nwa")
+ print("Building:", " ".join(target), flush=True)
+ r = subprocess.run(target, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+ for line in r.stdout.splitlines()[-25:]:
+ print(" " + line, flush=True)
+ if game: # (where each game's Makefile puts its app)
+ found = [os.path.join(ROOT, "games", game, n) for n in ("output/%s.nwa" % game, "build/%s.nwa" % game,
+ "output/device/%s.nwa" % game)]
+ found = [p for p in found if os.path.exists(p)]
+ out = max(found, key=os.path.getmtime) if found else None
+ if r.returncode or not out or not os.path.exists(out):
+ print("Build failed; the last good app stays in dist/live/NumPlay.nwa", flush=True)
+ return False
+ os.makedirs(os.path.dirname(LIVE), exist_ok=True)
+ tmp = LIVE + ".part"
+ shutil.copyfile(out, tmp)
+ os.replace(tmp, LIVE)
+ print("Stable live-emulator input:", os.path.relpath(LIVE, ROOT), flush=True)
+ return True
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--game", help="a game's folder in games/, built on its own")
+ ap.add_argument("--once", action="store_true", help="build once, don't watch")
+ ap.add_argument("-j", type=int, default=max(1, (os.cpu_count() or 2) // 2), help="make's jobs")
+ # (what tools/build_windows.py takes, so tools/emu_live.py can start either: these change nothing here)
+ ap.add_argument("--watch", action="store_true")
+ ap.add_argument("--launcher-only", action="store_true")
+ ap.add_argument("--skip-languages", action="store_true")
+ a, _ = ap.parse_known_args()
+ folders = [os.path.join(ROOT, "games", a.game)] if a.game else [os.path.join(ROOT, d) for d in ("launcher", "games")]
+ folders.append(os.path.join(ROOT, "games", "common"))
+ build(a.game, a.j)
+ if a.once:
+ return
+ last, count = stamp(folders)
+ print("Watching NumPlay source files (%d). Save a file to build again; Ctrl+C stops." % count, flush=True)
+ try:
+ while True:
+ time.sleep(1)
+ now, n = stamp(folders)
+ if now != last or n != count:
+ time.sleep(0.3) # (editors write in several steps)
+ last, count = stamp(folders)
+ print("Detected edits (%d files watched)" % count, flush=True)
+ build(a.game, a.j)
+ print("Watching for the next edit", flush=True)
+ except KeyboardInterrupt:
+ pass
+
+
+if __name__ == "__main__":
+ sys.exit(main())