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.

change emu and build

Lily Pitiot94522ab65d74
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 7ef63814..660aeecb 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -42,23 +42,23 @@ jobs:
rustup target add thumbv7em-none-eabihf
- name: Build
- run: make -j4 nwa apps check NWLINK=nwlink && make lang NWLINK=nwlink
+ run: python3 tools/build.py -j4
- uses: actions/upload-artifact@v4
with:
name: nwa
path: |
- build/NumPlay*.nwa
- build/apps/*.nwa
+ build/compiled/NumPlay*.nwa
+ build/compiled/games/*.nwa
- name: Test
run: |
python3 tests/test_games.py build/apps
- python3 tests/test_uninstall.py build/NumPlay.nwa --game numdrive
- python3 tests/test_progress.py build/NumPlay.nwa
- python3 tests/test_numblocks_progress.py build/apps/NumBlocks.nwa
- python3 tests/test_upsilon.py build/NumPlay-Upsilon.nwa
- python3 tests/test_small_ram.py build/NumPlay.nwa
+ python3 tests/test_uninstall.py build/compiled/NumPlay.nwa --game numdrive
+ python3 tests/test_progress.py build/compiled/NumPlay.nwa
+ python3 tests/test_numblocks_progress.py build/compiled/games/NumBlocks.nwa
+ python3 tests/test_upsilon.py build/compiled/NumPlay-Upsilon.nwa
+ python3 tests/test_small_ram.py build/compiled/NumPlay.nwa
make -C games/numblocks host test
make -C games/championisland host test
make -C games/undertale host test
@@ -90,9 +90,9 @@ jobs:
echo "$tag is already released"
exit 0
fi
- python3 tools/release.py --tag "$tag" --notes build/release-notes.md > build/release-files.txt
- mapfile -t files < build/release-files.txt
+ python3 tools/release.py --build build/compiled --tag "$tag" --notes build/data/release-notes.md > build/data/release-files.txt
+ mapfile -t files < build/data/release-files.txt
gh release create "$tag" "${files[@]}" --target "$GITHUB_SHA" \
- --title "NumPlay $tag" --notes-file build/release-notes.md
+ --title "NumPlay $tag" --notes-file build/data/release-notes.md
# the README's version and downloads badges come from the site (docs/badges): deploy it again
gh workflow run pages.yml --ref main || echo "(the site was not deployed again)"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 325c6c24..f38a82d2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,7 +25,7 @@ git clone https://github.com/Mason363/NumPlay.git
python3 NumPlay/tools/setup.py
```
-`tools/setup.py` gets the ARM compiler, nwlink and the Python packages into `~/.numplay` and tells you the one line that puts them on your PATH (`source ~/.numplay/env.sh` on macOS and Linux). On macOS, run `xcode-select --install` first if `make` is missing. Rust is needed only for Tetris: [rustup.rs](https://rustup.rs), then `rustup target add thumbv7em-none-eabihf`. On Windows, `python tools/build_windows.py` builds NumPlay natively (`--doctor` checks your setup), or use WSL.
+`tools/setup.py` gets the ARM compiler, nwlink and the Python packages into `~/.numplay` and tells you the one line that puts them on your PATH (`source ~/.numplay/env.sh` on macOS and Linux). On macOS, run `xcode-select --install` first if `make` is missing. Rust is needed only for Tetris: [rustup.rs](https://rustup.rs), then `rustup target add thumbv7em-none-eabihf`. On Windows, `python tools/build.py` builds NumPlay natively (`--doctor` checks your setup), or use WSL.
Then:
@@ -37,8 +37,8 @@ Then:
| `make -C games/<game> NWLINK=nwlink` | One game on its own |
| `make -C games/<game> test` | That game's tests on your computer (most games have them) |
| `python3 tests/test_games.py build/apps` | Plays every app in the emulator and checks its saves |
-| `python3 tools/emu.py app.nwa --ms 5000 --shots 2000 --out shots` | Runs any `.nwa` in the emulator and takes pictures |
-| `python3 tools/emu_live.py app.nwa` | The emulator in a window, to play with the mouse and keyboard; `--live` rebuilds as you save |
+| `python3 tools/emulator.py app.nwa --ms 5000 --shots 2000 --out shots` | Runs any `.nwa` in the emulator and takes pictures |
+| `python3 tools/emulator.py app.nwa` | The emulator in a window, to play with the mouse and keyboard; `--live` rebuilds as you save |
## How the code is laid out
@@ -77,7 +77,7 @@ Texts players read are marked `T("...")` in the code. Each game has `lang/fr.txt
Before a pull request:
1. `make -C games/<game> test` if your game has tests, and add some if it hasn't: its rules against the original, a scripted playthrough, and a few hundred random-key runs that must not crash.
-2. Run it in the emulator (`tools/emu.py`), also with `--model n0110`.
+2. Run it in the emulator (`tools/emulator.py`), also with `--model n0110`.
3. `make -j4 check NWLINK=nwlink` if you touched NumPlay or a game inside it.
4. Play the first minute as someone who has never seen the game.
diff --git a/Makefile b/Makefile
index f4ac69ac..788df269 100644
--- a/Makefile
+++ b/Makefile
@@ -15,7 +15,7 @@ ARM_LD = arm-none-eabi-ld
ARM_OBJCOPY = arm-none-eabi-objcopy
PY ?= python3
CARGO ?= cargo
-B = build
+B = build/data
# the RAM the oldest calculator software that runs apps gives them (23.2: 148928 bytes; 25.2 gives 153676).
# NumPlay itself takes less: a game goes on past it into the RAM the software has left (see
# tools/gen_games.py), so it installs with less too, custom builds of the software say, where a game that
@@ -183,12 +183,12 @@ lang: $(foreach l,$(LANGS),$(B)/NumPlay-$(LANG_$(l)).nwa)
$(foreach l,$(LANGS),$(B)/NumPlay-$(LANG_$(l)).nwa): $(B)/NumPlay-%.nwa: FORCE | $(B)
$(eval L := $(if $(filter French,$*),fr,zh))
$(PY) tools/lang.py tree $(L) $(B)/lang/$(L)
- $(MAKE) -C $(B)/lang/$(L) build/NumPlay.nwa NWLINK="$(NWLINK)"
- $(NWLINK) nwa-bin --ram-length $$(( $(CUSTOM_RAM) - $$(cat $(B)/lang/$(L)/build/gen/arena_extra) )) \
- $(B)/lang/$(L)/build/NumPlay.nwa $(B)/lang/$(L)/build/NumPlay.bin
- @n=$$(wc -c < $(B)/lang/$(L)/build/NumPlay.bin); echo "NumPlay-$*.nwa installs as $$n bytes ($$(( $(APP_SPACE) - n )) to spare)"; \
+ $(MAKE) -C $(B)/lang/$(L) build/data/NumPlay.nwa NWLINK="$(NWLINK)"
+ $(NWLINK) nwa-bin --ram-length $$(( $(CUSTOM_RAM) - $$(cat $(B)/lang/$(L)/build/data/gen/arena_extra) )) \
+ $(B)/lang/$(L)/build/data/NumPlay.nwa $(B)/lang/$(L)/build/data/NumPlay.bin
+ @n=$$(wc -c < $(B)/lang/$(L)/build/data/NumPlay.bin); echo "NumPlay-$*.nwa installs as $$n bytes ($$(( $(APP_SPACE) - n )) to spare)"; \
[ $$n -le $(APP_SPACE) ] || { echo "NumPlay-$*.nwa is bigger than the calculator's app space"; exit 1; }
- cp $(B)/lang/$(L)/build/NumPlay.nwa $@
+ cp $(B)/lang/$(L)/build/data/NumPlay.nwa $@
# ------------------------------------------------------------------ games on their own
APP_numdash = games/numdash/build/numdash.nwa:NumDash.nwa
diff --git a/README.md b/README.md
index b564ee60..ab6d771f 100644
--- a/README.md
+++ b/README.md
@@ -242,7 +242,7 @@ NumPlay is a fan project, made out of love for these games and for the NumWorks
- **[Gabriele Cirulli](https://github.com/gabrielecirulli/2048)** made 2048.
- **Block Blast!** by [Hungry Studio](https://www.hungrystudio.com) inspired NumPlay's Block Blast, written in C for NumPlay with no code or art from it. Its blocks, scoring and colours follow measurements of the app by the players behind [blockblast-Self-Improvement-loop](https://github.com/Kucze3205/blockblast-Self-Improvement-loop).
- Snake, Solitaire and Block Breaker look and play like **Google's games** in Search. They are drawn from scratch; nothing is taken from Google.
-- **Chrome's dinosaur game** by Google inspired Chrome Dino, which ports its rules, numbers and pictures from [Chromium's source](https://chromium.googlesource.com/chromium/src/+/main/components/neterror/resources/dino_game/) (BSD license). **[LilyTheCatgirl](https://github.com/LilyTheCuteCatgirl)** brought it to NumPlay, and also made the live emulator (`tools/emu_live.py`) and the Windows builder. Not affiliated with Google.
+- **Chrome's dinosaur game** by Google inspired Chrome Dino, which ports its rules, numbers and pictures from [Chromium's source](https://chromium.googlesource.com/chromium/src/+/main/components/neterror/resources/dino_game/) (BSD license). **[LilyTheCatgirl](https://github.com/LilyTheCuteCatgirl)** brought it to NumPlay, and also made the live emulator (`tools/emulator.py`) and the Windows builder. Not affiliated with Google.
- **[gd3ds](https://github.com/AleFunky/gd3ds)** by AleFunky and friends, whose research into Geometry Dash made NumDash possible. Clubstep, Deadlocked and Dash also rely on [gdsolver](https://github.com/gdsolver/gdsolver)'s measurements of Geometry Dash 2.2, level data from [gmdkit](https://github.com/UHDanke/gmdkit) by HDanke and checks against [GDRWeb](https://github.com/iliasHDZ/GDRWeb) by IliasHDZ.
- **Balatro** by LocalThunk inspired NumPlay's Balatro, which uses art adapted from the game and the **m6x11** font by Daniel Linssen.
- **Minecraft** by Mojang inspired NumBlocks, which follows Minecraft 1.8.8 exactly: it makes its worlds the way Minecraft 1.8.8 does and uses its blocks, items, recipes, textures, font and screens.
diff --git a/docs/make-a-game.md b/docs/make-a-game.md
index 465aaf35..8b0a8150 100644
--- a/docs/make-a-game.md
+++ b/docs/make-a-game.md
@@ -27,7 +27,7 @@ python3 NumPlay/tools/setup.py
| --- | --- |
| **macOS** (Apple silicon or Intel) | If `make` is missing, run `xcode-select --install` first. Then, in each new terminal: `source ~/.numplay/env.sh` |
| **Linux** | Same as macOS: `source ~/.numplay/env.sh` |
-| **Windows** | `tools/setup.py` prints the PowerShell line to use. `python tools/build_windows.py` builds NumPlay natively (it gets GNU make for you), or use WSL |
+| **Windows** | `tools/setup.py` prints the PowerShell line to use. `python tools/build.py` builds NumPlay natively (it gets GNU make for you), or use WSL |
## 2. Start a game
@@ -45,19 +45,19 @@ You get `games/mygame/output/mygame.nwa`. Now change `games/mygame/src/main.c` i
## 3. Try it without a calculator
-`tools/emu.py` runs a `.nwa` in an emulator of the calculator's ARM chip, with its screen, keys, clock and files. It takes pictures and GIFs, so you can see your game without installing it:
+`tools/emulator.py` runs a `.nwa` in an emulator of the calculator's ARM chip, with its screen, keys, clock and files. It takes pictures and GIFs, so you can see your game without installing it:
```bash
-python3 tools/emu.py games/mygame/output/mygame.nwa --ms 6000 --keys "1500-1600:ok,2000-4000:right" --shots 1400,3900 --out shots
+python3 tools/emulator.py games/mygame/output/mygame.nwa --ms 6000 --keys "1500-1600:ok,2000-4000:right" --shots 1400,3900 --out shots
```
To play it with your mouse and keyboard instead, open it in the live emulator, a calculator in a window (made by LilyTheCuteCatgirl). With `--live` it builds your game again each time you save a file and reloads it:
```bash
-python3 tools/emu_live.py games/mygame/output/mygame.nwa
+python3 tools/emulator.py games/mygame/output/mygame.nwa
```
-`tools/emu.py`'s `--keys` holds keys over time ranges in milliseconds (`ok`, `back`, `left`, `up`, `exe`, `home`, `1`...`9`, `shift`, `alpha`...). `--gif 0-5000` records a GIF, `--model n0110` emulates the slower N0110 and N0115 (if your game is smooth there, it's smooth everywhere), `--system upsilon` emulates Upsilon. It runs at about the speed of an N0110.
+`tools/emulator.py`'s `--keys` holds keys over time ranges in milliseconds (`ok`, `back`, `left`, `up`, `exe`, `home`, `1`...`9`, `shift`, `alpha`...). `--gif 0-5000` records a GIF, `--model n0110` emulates the slower N0110 and N0115 (if your game is smooth there, it's smooth everywhere), `--system upsilon` emulates Upsilon. It runs at about the speed of an N0110.
## 4. Put it on a calculator
diff --git a/tools/build.py b/tools/build.py
new file mode 100644
index 00000000..31f31c6a
--- /dev/null
+++ b/tools/build.py
@@ -0,0 +1,888 @@
+#!/usr/bin/env python3
+"""Build NumPlay .nwa files on native Windows (no WSL/Linux required).
+
+Requirements: Git for Windows (Git Bash), GNU Make 4.4.1 for Windows, Node.js/npm,
+Python, Rust/rustup and a native Windows arm-none-eabi-gcc toolchain.
+
+Run from PowerShell in the repository root:
+ python tools/build_windows.py --doctor
+ python tools/build_windows.py --launcher-only --skip-languages -j2
+ python tools/build_windows.py --organize-only --tidy-legacy
+ python tools/build_windows.py --watch --launcher-only --skip-languages -j2
+
+It keeps Make's intermediate outputs untouched under build/ and atomically
+exports finished calculator apps into top-level build/compiled/, including the stable
+live-emulator input build/compiled/NumPlay.nwa. `--watch` monitors source edits and
+rebuilds incrementally, publishing only after successful builds. `--organize-only`
+exports an existing successful build with no toolchain necessary.
+
+It also finds an existing Rustup installation under the current user's
+.cargo/bin even when VS Code did not refresh PATH; no permanent environment
+changes are needed. The Tetris nwlink.exe bridge and Windows-specific
+dependency installers are preserved unchanged. This script does not modify emulator code.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import time
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+
+ROOT = Path(__file__).resolve().parent.parent
+TOOL_VERSION = "15.2.1-1.1" # Same xPack GCC version as CI on Oct 19, 2026.
+TOOL_NAME = f"xpack-arm-none-eabi-gcc-{TOOL_VERSION}-win32-x64.zip"
+TOOL_URL = ("https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/releases/"
+ f"download/v{TOOL_VERSION}/{TOOL_NAME}")
+TOOL_SHA256 = "bae6a3d1667697ce750c3b13d6d26d80973ecedc2cc87bf04869e83447fd93ea"
+ARM_BASE = Path(os.environ.get("LOCALAPPDATA", Path.home())) / "NumPlay" / "toolchains"
+OUTPUT = ROOT / "build" / "compiled"
+RUST_TARGET = "thumbv7em-none-eabihf"
+
+# GnuWin32 Make 3.81 (often installed by winget) can crash with 0xc0000005
+# before running any recipe on Windows 11. Prefer portable GNU Make 4.4.1.
+MAKE_VERSION = "4.4.1"
+MAKE_ARCHIVE = "make-4.4.1-without-guile-w32-bin.zip"
+MAKE_URL = ("https://sourceforge.net/projects/ezwinports/files/"
+ f"{MAKE_ARCHIVE}/download")
+# Published by SourceForge and Chocolatey's verified GNU Make 4.4.1 package.
+MAKE_SHA256 = "fb66a02b530f7466f6222ce53c0b602c5288e601547a034e4156a512dd895ee7"
+MAKE_BASE = ARM_BASE.parent / "make"
+MAKE_ROOT = MAKE_BASE / f"make-{MAKE_VERSION}"
+
+
+
+def where(name: str) -> Path | None:
+ candidate = shutil.which(name)
+ # Rustup's Windows command proxies (rustc.exe, cargo.exe, etc.) may be
+ # links to rustup.exe. Their invoked file name is important: rustup.exe
+ # behaves differently from rustc.exe. Never resolve proxy links here.
+ return Path(os.path.abspath(candidate)) if candidate else None
+
+
+def ensure_rust_on_path() -> Path | None:
+ """Use the current user's *installed* Windows Rust tools despite a stale PATH.
+
+ The Rustup installer normally places cargo.exe and rustup.exe in
+ %USERPROFILE%\\.cargo\\bin. VS Code's integrated terminal can inherit an
+ older process environment after the user PATH was updated. Prepending the
+ verified installation to this script's process PATH also makes it visible
+ to Cargo and Git Bash subprocesses. This does not modify the registry or
+ require administrative rights. Never replace the rustup proxy filenames
+ with their resolved filesystem targets.
+ """
+ if os.name != "nt":
+ return None
+ if (where("cargo.exe") or where("cargo")) and (where("rustup.exe") or where("rustup")):
+ return None
+ cargo_home = Path(os.environ.get("CARGO_HOME", str(Path.home() / ".cargo"))).expanduser()
+ cargo_bin = cargo_home / "bin"
+ if not (cargo_bin / "rustup.exe").is_file() or not (cargo_bin / "cargo.exe").is_file():
+ return None
+ # PATH here is only changed inside this running Python process (and its
+ # children), never for PowerShell, Windows or other apps.
+ existing = os.environ.get("PATH", "")
+ normalized = lambda p: os.path.normcase(os.path.normpath(p.strip('"')))
+ if normalized(str(cargo_bin)) not in {normalized(p) for p in existing.split(os.pathsep) if p}:
+ os.environ["PATH"] = str(cargo_bin) + os.pathsep + existing
+ return cargo_bin
+
+
+def git_bash() -> Path | None:
+ # Never accidentally launch the WSL bash.exe from System32.
+ candidates = []
+ for env in ("ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA"):
+ base = os.environ.get(env)
+ if base:
+ candidates += [Path(base) / "Git" / "bin" / "bash.exe",
+ Path(base) / "Programs" / "Git" / "bin" / "bash.exe"]
+ g = where("git.exe") or where("git")
+ if g:
+ # git.exe normally lives in Git/cmd/, Git/bin/ or Git/mingw64/bin/.
+ for folder in (g.parent, *list(g.parents)[:3]):
+ candidates += [folder / "bin" / "bash.exe", folder / "usr" / "bin" / "bash.exe"]
+ b = where("bash.exe")
+ if b and "system32" not in str(b).lower():
+ candidates.append(b)
+ return next((x for x in candidates if x.is_file()), None)
+
+
+def make_version(exe: Path) -> tuple[int, int, int] | None:
+ """Probe actual GNU Make version; PATH presence alone is not enough."""
+ try:
+ p = subprocess.run([str(exe), "--version"], capture_output=True,
+ text=True, timeout=10, check=False)
+ except (OSError, subprocess.TimeoutExpired):
+ return None
+ if p.returncode:
+ return None
+ import re
+ m = re.search(r"GNU Make\s+(\d+)\.(\d+)(?:\.(\d+))?", p.stdout)
+ if not m:
+ return None
+ return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
+
+
+def make_supported(exe: Path | None) -> bool:
+ version = make_version(exe) if exe else None
+ return version is not None and version >= (4, 0, 0)
+
+
+def find_make() -> tuple[Path | None, str]:
+ # Prefer the verified portable version even when GnuWin32 make.exe appears
+ # earlier on PATH (e.g., C:\Program Files (x86)\GnuWin32\bin).
+ candidates: list[Path] = []
+ preferred = os.environ.get("NUMPLAY_MAKE_EXE")
+ if preferred:
+ candidates.append(Path(preferred).expanduser())
+ candidates.extend([MAKE_ROOT / "bin" / "make.exe",
+ MAKE_ROOT / "make.exe",
+ *(list(MAKE_ROOT.rglob("make.exe")) if MAKE_ROOT.is_dir() else []),
+ Path.home() / "scoop/apps/make/current/bin/make.exe",
+ Path.home() / "scoop/shims/make.exe"])
+ for name in ("make.exe", "make", "mingw32-make.exe", "mingw32-make"):
+ p = where(name)
+ if p:
+ candidates.append(p)
+ candidates.extend([
+ Path(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")) / "GnuWin32/bin/make.exe",
+ Path(os.environ.get("ProgramFiles", r"C:\Program Files")) / "GnuWin32/bin/make.exe",
+ ])
+ seen: set[str] = set()
+ old: Path | None = None
+ for candidate in candidates:
+ key = str(candidate).lower()
+ if key in seen or not candidate.is_file():
+ continue
+ seen.add(key)
+ version = make_version(candidate)
+ if version and version >= (4, 0, 0):
+ return candidate, candidate.stem
+ if version and old is None:
+ old = candidate
+ return (old, old.stem) if old else (None, "make")
+
+
+def install_make(archive_override: Path | None = None) -> Path:
+ """Install verified portable Windows GNU Make; never touch system PATH."""
+ if os.name != "nt":
+ raise RuntimeError("The Windows Make installer must run on Windows.")
+ existing = MAKE_ROOT / "bin" / "make.exe"
+ if make_supported(existing):
+ print("Modern GNU Make is already installed:", existing)
+ return existing
+ MAKE_BASE.mkdir(parents=True, exist_ok=True)
+ archive = MAKE_BASE / MAKE_ARCHIVE
+ if archive_override is not None:
+ archive = archive_override.expanduser().resolve()
+ if not archive.is_file():
+ raise RuntimeError(f"GNU Make ZIP not found: {archive}")
+ if not archive.is_file():
+ print("Downloading portable GNU Make 4.4.1 for Windows (~400 KB):")
+ print(MAKE_URL)
+ # SourceForge responds with a mirror redirect. A verified SHA-256 guards
+ # against a mirror returning HTML or unexpected/untrusted bytes.
+ request = urllib.request.Request(MAKE_URL,
+ headers={"User-Agent": "NumPlay-Windows-Builder/3"})
+ try:
+ with urllib.request.urlopen(request, timeout=90) as response, archive.open("wb") as f:
+ total = 0
+ while block := response.read(64 * 1024):
+ total += len(block)
+ if total > 16 * 1024 * 1024:
+ raise RuntimeError("Unexpectedly large GNU Make archive; aborted")
+ f.write(block)
+ except Exception:
+ archive.unlink(missing_ok=True)
+ raise
+ print("Verifying GNU Make archive SHA-256...")
+ with archive.open("rb") as f:
+ digest = hashlib.file_digest(f, "sha256").hexdigest()
+ if digest != MAKE_SHA256:
+ if archive_override is None:
+ archive.unlink(missing_ok=True)
+ raise RuntimeError("GNU Make ZIP SHA-256 mismatch (or HTML mirror page). "
+ "Try downloading the ZIP from SourceForge in your browser "
+ "and passing --make-zip PATH.")
+ # Reject arbitrary path traversal as a defense in depth.
+ with zipfile.ZipFile(archive) as z:
+ members = z.infolist()
+ if any(name.filename.startswith(("/", "\\")) or ".." in Path(name.filename).parts
+ or ":" in name.filename for name in members):
+ raise RuntimeError("Unexpected paths in the GNU Make ZIP")
+ z.extractall(MAKE_ROOT)
+ found = [p for p in MAKE_ROOT.rglob("make.exe") if make_supported(p)]
+ if not found:
+ raise RuntimeError("GNU Make executable was not found in the archive")
+ exe = found[0]
+ print("Installed portable GNU Make:", exe)
+ return exe
+
+
+def find_arm() -> Path | None:
+ hint = os.environ.get("NUMPLAY_ARM_GCC_BIN")
+ if hint:
+ p = Path(hint).expanduser()
+ if (p / "arm-none-eabi-gcc.exe").is_file():
+ return p
+ gcc = where("arm-none-eabi-gcc.exe") or where("arm-none-eabi-gcc")
+ if gcc:
+ return gcc.parent
+ candidates = [ARM_BASE / f"xpack-arm-none-eabi-gcc-{TOOL_VERSION}" / "bin"]
+ candidates += list(ARM_BASE.glob("*/bin")) if ARM_BASE.is_dir() else []
+ roaming = Path(os.environ.get("APPDATA", Path.home())) / "xPacks" / "arm-none-eabi-gcc"
+ candidates += list(roaming.glob("*/bin")) if roaming.is_dir() else []
+ return next((p for p in candidates if (p / "arm-none-eabi-gcc.exe").is_file()), None)
+
+
+def rust_target_installed() -> bool:
+ if not where("rustup.exe") and not where("rustup"):
+ return False
+ try:
+ result = subprocess.run(["rustup", "target", "list", "--installed"],
+ text=True, capture_output=True, timeout=20, check=False)
+ return result.returncode == 0 and RUST_TARGET in result.stdout.splitlines()
+ except (OSError, subprocess.TimeoutExpired):
+ return False
+
+
+def python_packages() -> list[str]:
+ missing = []
+ for name, module in (("pillow", "PIL"), ("numpy", "numpy"),
+ ("zopfli", "zopfli"), ("pyelftools", "elftools")):
+ try:
+ __import__(module)
+ except ImportError:
+ missing.append(name)
+ return missing
+
+
+def doctor() -> bool:
+ print("\nNumPlay Windows build tool check (native Windows; no WSL)")
+ print("Repository:", ROOT)
+ b = git_bash()
+ make, _ = find_make()
+ version = make_version(make) if make else None
+ make_ok = make_supported(make)
+ arm = find_arm()
+ node = where("node.exe") or where("node")
+ npx = where("npx.cmd") or where("npx")
+ cargo = where("cargo.exe") or where("cargo")
+ rustup = where("rustup.exe") or where("rustup")
+ tools = [("Git Bash", b), ("GNU Make 4+", make if make_ok else None),
+ ("ARM GCC (Windows)", arm / "arm-none-eabi-gcc.exe" if arm else None),
+ ("Node.js", node), ("npx", npx), ("Cargo", cargo), ("rustup", rustup)]
+ for name, value in tools:
+ if name == "GNU Make 4+" and not value and make is not None:
+ print(f" OLD {name:<18} {make} (version {'.'.join(map(str, version)) if version else 'broken'})")
+ else:
+ print(f" {'OK ' if value else 'MISSING'} {name:<18} {value or ''}")
+ rt = rust_target_installed()
+ print(f" {'OK ' if rt else 'MISSING'} Rust target {RUST_TARGET}")
+ missing = python_packages()
+ print(f" {'MISSING' if missing else 'OK '} Python packages {', '.join(missing) if missing else 'all installed'}")
+ show_instructions = not all(v for _, v in tools) or not rt or bool(missing)
+ print("\nMissing-tool instructions:" if show_instructions else "\nAll required tools detected.")
+ if not b:
+ print(" Git for Windows: https://git-scm.com/downloads/win (includes Git Bash; NOT Linux)")
+ if not make_ok:
+ print(" GNU Make 4.4.1: python tools/build_windows.py --install-make")
+ print(" (Portable Windows binary; ~400 KB; no administrator privileges or PATH change)")
+ if not arm:
+ print(" ARM compiler: python tools/build_windows.py --install-arm")
+ print(" (Downloads official xPack Windows compiler, about 320 MB, SHA-256 verified)")
+ if not node or not npx:
+ print(" Node.js: winget install --id OpenJS.NodeJS.LTS -e")
+ if not rustup or not cargo:
+ print(" Rust: https://rustup.rs/ (choose the Windows toolchain)")
+ elif not rt:
+ print(f" rustup target add {RUST_TARGET}")
+ if missing:
+ print(f" {sys.executable} -m pip install {' '.join(missing)}")
+ ok = (os.name == "nt" and all(v for _, v in tools) and rt and not missing)
+ if os.name != "nt":
+ print(" This helper intentionally runs only on native Windows.")
+ print("\n" + ("Ready to build!" if ok else "Complete the missing requirements above, then rerun --doctor."))
+ return ok
+
+
+def install_arm() -> Path:
+ existing = find_arm()
+ if existing:
+ print("ARM GCC is already installed:", existing)
+ return existing
+ if os.name != "nt":
+ raise RuntimeError("The Windows compiler installer must run on Windows.")
+ ARM_BASE.mkdir(parents=True, exist_ok=True)
+ archive = ARM_BASE / TOOL_NAME
+ if not archive.is_file():
+ print("Downloading the official Windows ARM compiler (~320 MB):")
+ print(TOOL_URL)
+ with urllib.request.urlopen(TOOL_URL, timeout=120) as response, open(archive, "wb") as out:
+ total = 0
+ while block := response.read(1024 * 1024):
+ out.write(block)
+ total += len(block)
+ if total % (32 * 1024 * 1024) == 0:
+ print(f" {total // (1024 * 1024)} MB received", flush=True)
+ print("Checking the official archive SHA-256...")
+ digest = hashlib.sha256()
+ with archive.open("rb") as src:
+ for block in iter(lambda: src.read(4 * 1024 * 1024), b""):
+ digest.update(block)
+ if digest.hexdigest() != TOOL_SHA256:
+ archive.unlink(missing_ok=True)
+ raise RuntimeError("ARM compiler SHA-256 mismatch: archive removed; installation aborted.")
+ print("Extracting ARM compiler into", ARM_BASE)
+ with zipfile.ZipFile(archive) as z:
+ z.extractall(ARM_BASE)
+ installed = find_arm()
+ if not installed:
+ raise RuntimeError("Extracted compiler not found. Check the archive layout.")
+ print("ARM compiler ready:", installed)
+ return installed
+
+
+def ensure_build_directories(build: Path | None = None) -> tuple[Path, ...]:
+ """Repair an incomplete build tree without deleting any existing outputs.
+
+ The root Makefile creates build/arm, build/modules, etc. inside the recipe
+ for the `build` directory. If build/ *already exists* (for example after
+ an interrupted attempt, or after a previous failed Make invocation), Make
+ skips that recipe. Parallel ARM compiler jobs then fail with an interleaved
+ `can't create build/arm/*.o: No such file or directory` error.
+
+ These directories are always safe to create ahead of Make, and the rest
+ remain governed by the repo's Makefile. Creating them before starting
+ any parallel build jobs also removes a directory-creation race.
+ """
+ build = ROOT / "build" / "data" if build is None else build
+ relative = ("modules", "gen", "arm", "apps", "sim", "variant",
+ "tetris", "gen-upsilon", "arm-upsilon", "lang")
+ created = []
+ build.mkdir(parents=True, exist_ok=True)
+ for name in relative:
+ folder = build / name
+ if not folder.is_dir():
+ folder.mkdir(parents=True, exist_ok=True)
+ created.append(folder)
+ return tuple(created)
+
+
+# The Rust Tetris build script calls Command::new("nwlink") at build.rs:16.
+# Unlike a shell, Rust's Windows process launcher does not find npm's .cmd
+# shims from that extensionless name. Supply an actual nwlink.exe on PATH.
+# We compile it with the Windows rustc the project already requires.
+# The adapter delegates to the exact pinned nwlink package used by Make.
+NWLINK_BRIDGE_RS = r"""
+use std::env;
+use std::process::{Command, Stdio};
+
+fn main() {
+ let mut child = Command::new("npx.cmd");
+ child.args(["--yes", "--", "[email protected]"]);
+ child.args(env::args_os().skip(1));
+ child.stdin(Stdio::inherit())
+ .stdout(Stdio::inherit())
+ .stderr(Stdio::inherit());
+ match child.status() {
+ Ok(status) => std::process::exit(status.code().unwrap_or(1)),
+ Err(e) => {
+ eprintln!("NumPlay nwlink bridge could not launch npx.cmd: {e}");
+ std::process::exit(1);
+ }
+ }
+}
+"""
+
+
+def create_nwlink_bridge(shims: Path) -> Path:
+ """Make a *Windows* nwlink.exe for Cargo's direct process invocation.
+
+ The source is fixed, generated locally and built with the user's own
+ installed Rust compiler; it has no external dependencies or downloads.
+ Both source and exe live in the temporary helper folder and are removed
+ when the build ends. It never edits games/tetris/tetris/build.rs.
+ """
+ # Don't use Path.resolve() on ~/.cargo/bin/rustc.exe: it can resolve
+ # Rustup's rustc proxy to rustup.exe. Rustup then receives --edition as
+ # its own argument and fails with "unexpected argument '--edition'".
+ # `rustup which rustc` instead locates the real host compiler binary.
+ rustup = shutil.which("rustup.exe") or shutil.which("rustup")
+ if not rustup:
+ raise RuntimeError("Rustup was not found in PATH; ensure .cargo\\bin is on PATH")
+ located = subprocess.run([rustup, "which", "rustc"],
+ text=True, capture_output=True, check=False)
+ if located.returncode:
+ raise RuntimeError("Rustup could not locate the host Rust compiler. "
+ "Try: rustup default stable\n"
+ + (located.stderr or located.stdout))
+ rustc = Path(located.stdout.strip().strip('"'))
+ if not rustc.is_file():
+ raise RuntimeError(f"Rustup reported a missing Rust compiler: {rustc}")
+ src = shims / "numplay_nwlink_bridge.rs"
+ exe = shims / "nwlink.exe"
+ src.write_text(NWLINK_BRIDGE_RS, encoding="utf-8", newline="\n")
+ print("Preparing temporary Windows nwlink.exe bridge for Tetris...", flush=True)
+ try:
+ completed = subprocess.run([str(rustc), "--edition=2021",
+ "--crate-name", "numplay_nwlink_bridge",
+ "-C", "opt-level=0", str(src), "-o", str(exe)],
+ cwd=ROOT, text=True, capture_output=True, check=False)
+ except OSError as exc:
+ raise RuntimeError(f"Could not start Rust compiler {rustc}: {exc}") from exc
+ if completed.returncode or not exe.is_file():
+ raise RuntimeError("Could not compile Windows nwlink bridge using rustc.\n"
+ + (completed.stderr or completed.stdout or "unknown error"))
+ return exe
+
+
+def run_bash(bash: Path, make: Path, make_name: str, arm: Path, jobs: int,
+ *, apps: bool, check: bool, langs: bool, target_args: list[str] | None = None) -> None:
+ # Ensure make's directories exist even when build/ was created by an
+ # interrupted earlier run. Keep all existing compiled files for a retry.
+ created = ensure_build_directories()
+ if created:
+ print(f"Prepared {len(created)} missing build directories "
+ f"(including build/arm); keeping existing build files.", flush=True)
+ # Git Bash supplies sh/cp/mkdir/wc/etc., but every compiler and runtime
+ # launched by it is the normal Windows executable, not a Linux program.
+ with tempfile.TemporaryDirectory(prefix="numplay-win-") as td:
+ shims = Path(td)
+ python3 = shims / "python3"
+ python3.write_text('#!/bin/sh\nexec "$NUMPLAY_PYTHON_POSIX" "$@"\n', encoding="utf-8", newline="\n")
+ # 'nwlink' in Tetris's Rust build.rs is launched without a .cmd
+ # extension, so give Cargo a real executable to find in PATH.
+ create_nwlink_bridge(shims)
+ env = os.environ.copy()
+ env.update({"NUMPLAY_MAKE_BIN": str(make.parent), "NUMPLAY_ARM_BIN": str(arm),
+ "NUMPLAY_PYTHON_EXE": sys.executable, "NUMPLAY_SHIMS": str(shims)})
+ prefix = r'''set -e
+export NUMPLAY_PYTHON_POSIX="$(cygpath -u "$NUMPLAY_PYTHON_EXE")"
+export PATH="$(cygpath -u "$NUMPLAY_SHIMS"):$(cygpath -u "$NUMPLAY_ARM_BIN"):$(cygpath -u "$NUMPLAY_MAKE_BIN"):$PATH"
+chmod +x "$(cygpath -u "$NUMPLAY_SHIMS")/python3"
+command -v sh >/dev/null || { echo 'Git Bash sh is unavailable'; exit 1; }
+command -v arm-none-eabi-gcc >/dev/null || { echo 'ARM GCC is unavailable from Git Bash'; exit 1; }
+command -v node >/dev/null || { echo 'Node.js is unavailable from Git Bash'; exit 1; }
+command -v python3 >/dev/null || { echo 'Python is unavailable from Git Bash'; exit 1; }
+command -v nwlink >/dev/null || { echo 'Tetris nwlink bridge is unavailable from Git Bash'; exit 1; }
+'''
+ common = ["NWLINK=npx --yes -- [email protected]", "SHELL=sh"]
+
+ def invoke(args: list[str]) -> None:
+ import shlex
+ command = " ".join(shlex.quote(arg) for arg in [make_name, *args, *common])
+ print("\nBuilding: ", command, flush=True)
+ completed = subprocess.run([str(bash), "--noprofile", "--norc", "-c", prefix + "\n" + command],
+ cwd=ROOT, env=env, check=False)
+ if completed.returncode:
+ raise RuntimeError(f"GNU Make exited with code {completed.returncode} (build stopped)")
+
+ if target_args is not None:
+ invoke([f"-j{jobs}", *target_args])
+ else:
+ targets = ["nwa"]
+ if apps or check:
+ targets.append("apps")
+ if check:
+ targets.append("check")
+ invoke([f"-j{jobs}", *targets])
+ if langs:
+ invoke(["lang"])
+
+
+# Publish end-user .nwa files outside Make's internal build/ directory.
+# build/ is intentionally left alone: NumPlay's Makefile hard-codes B = build.
+# The stable live path can later be supplied to emu_live.py for auto-reload.
+LIVE_DIR = "live"
+VARIANT_DIR = "variants"
+GAME_DIR = "games"
+LANGUAGE_DIR = "languages"
+LANGUAGE_VARIANTS = ("NumPlay-French.nwa", "NumPlay-Chinese.nwa")
+
+
+def destination_for(name: str, output: Path) -> Path:
+ if name == "NumPlay.nwa":
+ return output / name
+ if name in LANGUAGE_VARIANTS:
+ return output / name
+ if name.startswith("NumPlay-") and name.endswith(".nwa"):
+ return output / name
+ return output / GAME_DIR / name
+
+
+def atomic_copy(src: Path, dest: Path) -> None:
+ """Do not expose partly written files to a future live emulator.
+
+ Windows can temporarily block os.replace when another process has the file
+ open. Keep the old export on such failures and retry briefly.
+ """
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ # Unique temporary file in the destination directory ensures atomic rename.
+ tmp_name = None
+ try:
+ with tempfile.NamedTemporaryFile(prefix="." + dest.name + ".",
+ suffix=".tmp", dir=dest.parent,
+ delete=False) as temp:
+ tmp_name = Path(temp.name)
+ with src.open("rb") as source:
+ shutil.copyfileobj(source, temp, length=1024 * 1024)
+ temp.flush()
+ os.fsync(temp.fileno())
+ for attempt in range(10):
+ try:
+ os.replace(tmp_name, dest)
+ tmp_name = None
+ return
+ except PermissionError:
+ if attempt == 9:
+ raise
+ time.sleep(0.2)
+ finally:
+ if tmp_name:
+ tmp_name.unlink(missing_ok=True)
+
+
+def collect_sources(*, apps: bool, langs: bool) -> list[Path]:
+ build = ROOT / "build" / "data"
+ # Never include existing build/compiled/ files: only fresh Makefile output sources.
+ sources = list(sorted(build.glob("NumPlay*.nwa")))
+ if not langs:
+ sources = [p for p in sources if p.name not in LANGUAGE_VARIANTS]
+ if apps:
+ sources.extend(sorted((build / "apps").glob("*.nwa")))
+ return sources
+
+
+def publish_outputs(*, apps: bool, langs: bool, output: Path = OUTPUT,
+ verbose: bool = True) -> list[Path]:
+ """Organize completed binaries, leaving compiler artifacts in build/.
+
+ If a build fails this function isn't called, so the last successful live
+ binary remains untouched. No .nwa source or compiler object is deleted.
+ """
+ sources = collect_sources(apps=apps, langs=langs)
+ if not sources:
+ raise RuntimeError("No .nwa files found inside build/. Run a build first.")
+ # Keep these generated binary exports out of git status without touching
+ # the project's tracked root .gitignore. A lone '*' ignores this file too.
+ output.mkdir(parents=True, exist_ok=True)
+ ignore = output / ".gitignore"
+ if not ignore.exists():
+ ignore.write_text("*\n", encoding="utf-8")
+ published: list[Path] = []
+ # Publish user-facing variants and standalone games first.
+ # Publish the stable live file *last*, marking the completed build.
+ main_src = None
+ for src in sources:
+ if src.name == "NumPlay.nwa":
+ main_src = src
+ dest = destination_for(src.name, output)
+ atomic_copy(src, dest)
+ published.append(dest)
+ if verbose:
+ print(f"\nSUCCESS: organized {len(sources)} calculator app(s) in:", output)
+ for path in published:
+ print(" " + str(path.relative_to(output)))
+ if main_src:
+ print("\nStable live-emulator input: " + str(output / "NumPlay.nwa"))
+ return published
+
+
+def safe_remove_legacy_duplicates(output: Path = OUTPUT) -> None:
+ """Opt-in cleanup of only byte-identical earlier exports in build/windows-nwa.
+
+ Do not delete anything that wasn't safely copied into build/compiled/. No recursive
+ deletion; unknown or changed files are left exactly as they were.
+ """
+ legacy = ROOT / "build" / "windows-nwa"
+ if not legacy.is_dir():
+ print("No old build/windows-nwa/ export folder to tidy.")
+ return
+ count = 0
+ for path in sorted(legacy.iterdir()):
+ if not path.is_file() or path.suffix.lower() != ".nwa":
+ print("Kept unknown legacy entry:", path)
+ continue
+ newer = destination_for(path.name, output)
+ if not newer.is_file() or newer.stat().st_size != path.stat().st_size:
+ print("Kept unmatched legacy file:", path.name)
+ continue
+ def sha256(p: Path) -> str:
+ with p.open("rb") as f:
+ return hashlib.file_digest(f, "sha256").hexdigest()
+ if sha256(path) != sha256(newer):
+ print("Kept changed legacy file:", path.name)
+ continue
+ path.unlink()
+ count += 1
+ if not any(legacy.iterdir()):
+ legacy.rmdir()
+ print(f"Tidied {count} byte-identical old .nwa export(s) from build/windows-nwa/.")
+
+
+# Watch *inputs* only. Ignore intermediate compiler output, Rust target/, npm
+# install directories, exported files, and emulator screenshots. Otherwise a
+# rebuild could detect its own outputs and create an infinite rebuild loop.
+WATCH_IGNORED_DIRS = frozenset({
+ ".git", ".venv", "venv", "__pycache__", "build", "dist", "target",
+ "node_modules", "output", ".idea", ".pytest_cache", ".mypy_cache",
+ ".ruff_cache", ".tox", ".next", ".cache", ".vs", "windows-nwa",
+})
+WATCH_EXTS = frozenset({
+ ".c", ".h", ".s", ".rs", ".py", ".json", ".toml", ".lock",
+ ".mk", ".ld", ".txt", ".png", ".ppm", ".jpg", ".jpeg",
+ ".svg", ".webp", ".gif", ".bin", ".ttf", ".otf", ".sh",
+ ".js", ".ts", ".yml", ".yaml", ".ini", ".csv",
+})
+WATCH_NAMES = frozenset({"Makefile", "makefile", "GNUmakefile", "VERSION"})
+
+
+def is_source_file(name: str) -> bool:
+ if name.startswith(("~", ".#")) or name.endswith(("~", ".swp", ".tmp")):
+ return False
+ if name in WATCH_NAMES:
+ return True
+ if name.startswith("."):
+ return False
+ # .nwi/.nppm are generated by Rust's build.rs; avoid output-trigger loops.
+ if name.lower().endswith((".nwi", ".nppm")):
+ return False
+ return Path(name).suffix.lower() in WATCH_EXTS
+
+
+def source_snapshot(root: Path = ROOT) -> dict[str, tuple[int, int]]:
+ result: dict[str, tuple[int, int]] = {}
+ # Exclude the build helper while it is running; edits to it require restart.
+ own = Path(__file__).resolve()
+ for folder, directories, files in os.walk(root):
+ directories[:] = [d for d in directories
+ if d not in WATCH_IGNORED_DIRS and
+ (not d.startswith(".") or d == ".cargo")]
+ for name in files:
+ if not is_source_file(name):
+ continue
+ p = Path(folder) / name
+ if p == own:
+ continue
+ try:
+ st = p.stat()
+ except OSError:
+ continue
+ result[p.relative_to(root).as_posix()] = (st.st_mtime_ns, st.st_size)
+ return result
+
+
+def differences(a: dict, b: dict) -> list[str]:
+ return sorted(k for k in (a.keys() | b.keys()) if a.get(k) != b.get(k))
+
+
+def run_watch(build_once, *, interval: float = 1.0,
+ settle: float = 1.0, root: Path = ROOT) -> None:
+ """Debounce editor save bursts; rebuild and publish only on success.
+
+ No extra watchdog package needed. Capture the baseline after a build so
+ files generated inside source folders don't retrigger it immediately.
+ """
+ if interval <= 0 or settle <= 0:
+ raise ValueError("watch interval and settle time must be positive")
+ print("\nWatching NumPlay source files. Save an edit to rebuild; Ctrl+C to stop.")
+ print("Build failures keep the previous build/compiled/NumPlay.nwa untouched.\n")
+ baseline = source_snapshot(root)
+ pending: dict[str, tuple[int, int]] | None = None
+ last_change = 0.0
+ while True:
+ time.sleep(interval)
+ current = source_snapshot(root)
+ now = time.monotonic()
+ if current == baseline:
+ pending = None
+ continue
+ if pending != current:
+ pending = current
+ last_change = now
+ continue
+ if now - last_change < settle:
+ continue
+ changed = differences(baseline, current)
+ print("\nDetected edits ({} file(s)):".format(len(changed)), flush=True)
+ for name in changed[:12]:
+ print(" " + name)
+ if len(changed) > 12:
+ print(f" ... plus {len(changed) - 12} more")
+ try:
+ build_once()
+ except (OSError, RuntimeError) as exc:
+ print("\nBuild failed; keeping last good build/compiled/NumPlay.nwa:", exc,
+ file=sys.stderr, flush=True)
+ # Rescan after build. Generated files, if any, become the new baseline.
+ # A human edit made during the build may need a further save to trigger.
+ baseline = source_snapshot(root)
+ pending = None
+ print("\nWatching for the next edit...", flush=True)
+
+
+
+
+# ---- Universal build entry point: native Windows, macOS and Linux ----
+
+def _nwlink() -> str:
+ found = shutil.which("nwlink")
+ if found:
+ return found
+ local = Path.home() / ".numplay" / "node_modules" / ".bin" / "nwlink"
+ if local.exists():
+ return str(local)
+ return "npx --yes -- [email protected]"
+
+
+def _run_make(args: list[str], *, jobs: int) -> None:
+ print("Building:", " ".join(["make", f"-j{jobs}", *args]), flush=True)
+ if os.name == "nt":
+ make, make_name = find_make()
+ bash, arm = git_bash(), find_arm()
+ if not (make and make_name and bash and arm and make_supported(make)):
+ raise RuntimeError("Windows toolchain missing; run python tools/build.py --doctor")
+ run_bash(bash, make, make_name, arm, jobs, apps=False, check=False, langs=False,
+ target_args=args)
+ else:
+ cmd = ["make", f"-j{jobs}", *args, "NWLINK=" + _nwlink()]
+ subprocess.run(cmd, check=True, cwd=ROOT)
+
+
+def _game_output(game: str) -> tuple[str, Path]:
+ import json
+ import re
+ manifest = json.loads((ROOT / "games" / "games.json").read_text(encoding="utf-8"))
+ labels = {g["id"]: g["app"] for g in manifest if g.get("app")}
+ for match in re.finditer(r"(?m)^APP_(\w+)\s*=\s*([^:\n]+):(\S+\.nwa)\s*$",
+ (ROOT / "Makefile").read_text(encoding="utf-8")):
+ labels[match.group(1)] = match.group(3)
+ if game not in labels:
+ raise ValueError(f"Unknown standalone game '{game}'. Choices: " + ", ".join(sorted(labels)))
+ game_dir = ROOT / "games" / game
+ if not game_dir.is_dir():
+ raise ValueError(f"Missing game directory: {game}")
+ file = labels[game]
+ # A small set of games have unusual outputs. Only select the exact expected
+ # game-specific NWA, not a random newest .nwa in the output directory.
+ candidate = [game_dir / "output" / f"{game}.nwa",
+ game_dir / "output" / "device" / f"{game}.nwa",
+ game_dir / "build" / f"{game}.nwa"]
+ if game == "tetris":
+ candidate = [game_dir / "tetris" / "target" / "thumbv7em-none-eabihf" / "release" / "tetris"]
+ return file, next((p for p in candidate if p.is_file()), candidate[0])
+
+
+def _publish_game(game: str) -> Path:
+ name, src = _game_output(game)
+ if not src.is_file():
+ raise RuntimeError(f"No successful game build found at {src}")
+ dst = OUTPUT / "games" / name
+ atomic_copy(src, dst)
+ print("Stable live-emulator input:", dst.relative_to(ROOT), flush=True)
+ return dst
+
+
+def _build_once(a) -> None:
+ if a.game:
+ if a.game == "tetris":
+ # Tetris is a Cargo project; the regular root apps target also
+ # creates standalone Tetris, but would compile ALL games. This path
+ # is intentionally disabled until the bridge is generalized.
+ raise RuntimeError("Tetris standalone single-game mode is not wired yet; use a full build")
+ _game_output(a.game) # Fail before launching a compiler on invalid IDs.
+ _run_make(["-C", f"games/{a.game}", "build"], jobs=a.jobs)
+ _publish_game(a.game)
+ return
+ if os.name == "nt":
+ if not doctor():
+ raise RuntimeError("Windows requirements are not yet ready")
+ make, make_name = find_make()
+ bash, arm = git_bash(), find_arm()
+ assert make and make_name and bash and arm
+ run_bash(bash, make, make_name, arm, a.jobs,
+ apps=not a.launcher_only, check=not a.skip_check and not a.launcher_only,
+ langs=not a.skip_languages)
+ else:
+ targets = ["nwa"]
+ if not a.launcher_only:
+ targets += ["apps"]
+ if not a.skip_check and not a.launcher_only:
+ targets += ["check"]
+ _run_make(targets, jobs=a.jobs)
+ if not a.skip_languages:
+ _run_make(["lang"], jobs=a.jobs)
+ sources = collect_sources(apps=not a.launcher_only, langs=not a.skip_languages)
+ publish_outputs(apps=not a.launcher_only, langs=not a.skip_languages)
+ if (ROOT / "build" / "compiled" / "NumPlay.nwa").is_file():
+ print("Stable live-emulator input: build/compiled/NumPlay.nwa", flush=True)
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description="NumPlay unified build + live watch (Windows, macOS, Linux)")
+ ap.add_argument("--doctor", action="store_true")
+ ap.add_argument("--install-arm", action="store_true", help="Windows: install verified ARM compiler")
+ ap.add_argument("--install-make", action="store_true", help="Windows: install portable GNU Make")
+ ap.add_argument("--make-zip", type=Path)
+ ap.add_argument("--game", metavar="ID", help="compile one standalone game")
+ ap.add_argument("--launcher-only", action="store_true")
+ ap.add_argument("--skip-check", action="store_true")
+ ap.add_argument("--skip-languages", action="store_true")
+ ap.add_argument("--organize-only", action="store_true", help="publish existing successful .nwa files")
+ ap.add_argument("--watch", action="store_true", help="rebuild when source files change")
+ ap.add_argument("--once", action="store_true", help="alias for a normal one-time build")
+ ap.add_argument("--clean", action="store_true", help="make clean; removes generated build files")
+ ap.add_argument("--watch-interval", type=float, default=1.0)
+ ap.add_argument("-j", "--jobs", type=int, default=2)
+ a = ap.parse_args()
+ if a.jobs < 1 or a.jobs > 32 or a.watch_interval <= 0:
+ ap.error("jobs must be 1..32 and watch interval must be positive")
+ if os.name == "nt":
+ # Older PowerShell windows may not inherit ~/.cargo/bin in their PATH.
+ ensure_rust_on_path()
+ if a.doctor:
+ if os.name == "nt":
+ return 0 if doctor() else 1
+ return subprocess.call([sys.executable, str(ROOT / "tools" / "setup.py"), "--check"])
+ if a.install_arm or a.install_make:
+ if os.name != "nt":
+ ap.error("Windows installers are Windows-only; use tools/setup.py")
+ if a.install_arm:
+ install_arm()
+ if a.install_make:
+ install_make(a.make_zip)
+ return 0
+ if a.clean:
+ _run_make(["clean"], jobs=1)
+ # Only compiler-generated outputs: user saves are in ~/.numplay-emulator.
+ shutil.rmtree(OUTPUT, ignore_errors=True)
+ return 0
+ if a.organize_only:
+ publish_outputs(apps=True, langs=True)
+ return 0
+ if a.game and a.launcher_only:
+ ap.error("--game and --launcher-only are mutually exclusive")
+ try:
+ _build_once(a)
+ except (OSError, RuntimeError, subprocess.CalledProcessError, ValueError) as exc:
+ print("Build failed; the last good .nwa stays untouched:", exc, file=sys.stderr, flush=True)
+ if not a.watch:
+ return 1
+ if a.watch and not a.once:
+ try:
+ run_watch(lambda: _build_once(a), interval=a.watch_interval)
+ except KeyboardInterrupt:
+ return 0
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/emulator.py b/tools/emulator.py
new file mode 100644
index 00000000..7de36a85
--- /dev/null
+++ b/tools/emulator.py
@@ -0,0 +1,3732 @@
+# NumPlay emulator: GUI and headless backend in one file.
+from __future__ import annotations
+
+# -------- ARM backend (formerly emu.py) --------
+import argparse
+import os
+import struct
+import subprocess
+import sys
+import tempfile
+
+from elftools.elf.elffile import ELFFile
+from unicorn import (UC_ARCH_ARM, UC_HOOK_CODE, UC_HOOK_INTR, UC_HOOK_MEM_INVALID, UC_HOOK_MEM_READ, UC_HOOK_MEM_WRITE,
+ UC_MODE_MCLASS, UC_MODE_THUMB, Uc, UcError)
+from unicorn.arm_const import (UC_ARM_REG_LR, UC_ARM_REG_PC, UC_ARM_REG_R0, UC_ARM_REG_R1, UC_ARM_REG_R2,
+ UC_ARM_REG_R3, UC_ARM_REG_SP)
+
+KEYS = {"left": 0, "up": 1, "down": 2, "right": 3, "ok": 4, "back": 5, "home": 6, "onoff": 8, "shift": 12,
+ "alpha": 13, "xnt": 14, "var": 15, "toolbox": 16, "backspace": 17, "exp": 18, "ln": 19, "log": 20,
+ "i": 21, "comma": 22, "power": 23, "sin": 24, "cos": 25, "tan": 26, "pi": 27, "sqrt": 28, "square": 29,
+ "7": 30, "8": 31, "9": 32, "lparen": 33, "rparen": 34, "4": 36, "5": 37, "6": 38, "mul": 39, "div": 40,
+ "1": 42, "2": 43, "3": 44, "plus": 45, "minus": 46, "0": 48, "dot": 49, "ee": 50, "ans": 51, "exe": 52}
+
+FLASH, FLASH_SIZE = 0x90000000, 0x800000
+SRAM, SRAM_SIZE = 0x24000000, 0x40000
+USERLAND_HEADER = 0x90020000 # N0120: kernel, extra data sector, then userland
+TRAMPOLINE = 0x90010400
+DRAW_STRING_HOOK = 0x90010800
+EXIT_HOOK = 0x90010900
+STORAGE = 0x24001000
+STORAGE_SIZE = 42 * 1024
+EXT_RAM_END = 0x24037000
+EXT_RAM_LEN = 153676
+EXT_RAM_START = EXT_RAM_END - EXT_RAM_LEN
+STACK_TOP = 0x2403F000
+EXT_FLASH_START = 0x90200000
+EXT_FLASH_END = 0x903F0000
+CPU_HZ = 216_000_000
+MODEL, SYSTEM = "n0120", "epsilon"
+
+
+def configure(model="n0120", system="epsilon", ram_length=None):
+ """The calculator to emulate: the N0120 (RAM at 0x24000000, the userland after an extra data
+ sector) or the N0110/N0115 (RAM at 0x20000000); Epsilon or Upsilon (its userland header has no
+ device name, apps get 107674 bytes of RAM, its file system is Epsilon 15's and it has none of
+ the system calls for Home, checksums or flash). ram_length: the RAM apps get, when another
+ build of the software gives them another amount."""
+ global MODEL, SYSTEM, SRAM, USERLAND_HEADER, STORAGE, STORAGE_SIZE, EXT_RAM_END, EXT_RAM_LEN, EXT_RAM_START, \
+ STACK_TOP
+ MODEL, SYSTEM = model, system
+ SRAM = 0x20000000 if model == "n0110" else 0x24000000
+ USERLAND_HEADER = 0x90010000 if model == "n0110" else 0x90020000
+ STORAGE = SRAM + 0x1000
+ STORAGE_SIZE = 64400 if system == "upsilon" else 42 * 1024
+ EXT_RAM_END = SRAM + 0x37000
+ EXT_RAM_LEN = ram_length or (107674 if system == "upsilon" else 153676)
+ EXT_RAM_START = EXT_RAM_END - EXT_RAM_LEN
+ STACK_TOP = SRAM + 0x3F000
+# Epsilon's SmallFont.ttf and LargeFont.ttf (from the epsilon repository), for text drawn by
+# the firmware. Without them, text shows as blank cells.
+FONT_DIR = os.environ.get("EPSILON_FONTS", "")
+
+
+def epsilon_crc32(data):
+ """Ion::crc32Byte as in Epsilon's simulator: CRC-32/MPEG-2 fed word by word
+ (little-endian words, most significant byte first), then the tail bytes."""
+ if not data:
+ return 0
+ crc = 0xFFFFFFFF
+
+ def eat(crc, b):
+ crc ^= b << 24
+ for _ in range(8):
+ crc = ((crc << 1) ^ 0x04C11DB7) if crc & 0x80000000 else crc << 1
+ crc &= 0xFFFFFFFF
+ return crc
+
+ n = len(data) // 4
+ for i in range(n):
+ for j in (3, 2, 1, 0):
+ crc = eat(crc, data[4 * i + j])
+ for b in data[4 * n:]:
+ crc = eat(crc, b)
+ return crc
+
+
+def record_crc(full_name):
+ base, _, ext = full_name.rpartition(".")
+ parts = struct.pack("<II", epsilon_crc32(base.encode()), epsilon_crc32(ext.encode()))
+ return epsilon_crc32(parts)
+
+
+def sector_of(addr):
+ """Epsilon's Ion::Device::Flash::SectorAtAddress (8x4K, 1x32K, then 64K sectors)."""
+ off = addr - FLASH
+ i = off >> 16
+ if i >= 1:
+ return 8 + 1 + i - 1
+ i = off >> 15
+ if i >= 1:
+ return 8 + i - 1
+ return off >> 12
+
+
+def sector_range(index):
+ if index < 8:
+ return FLASH + index * 0x1000, 0x1000
+ if index == 8:
+ return FLASH + 0x8000, 0x8000
+ return FLASH + (index - 8) * 0x10000, 0x10000
+
+
+class Font:
+ """Approximates Epsilon's fonts (4-bit anti-aliased, fixed cells) with PIL."""
+
+ def __init__(self):
+ from PIL import Image, ImageDraw, ImageFont
+ self.cells = {}
+ for large, (name, px, w, h) in ((False, ("SmallFont.ttf", 12, 7, 14)), (True, ("LargeFont.ttf", 16, 10, 18))):
+ path = os.path.join(FONT_DIR, name)
+ glyphs = {}
+ if os.path.exists(path):
+ f = ImageFont.truetype(path, px)
+ asc, _ = f.getmetrics()
+ for c in range(32, 127):
+ im = Image.new("L", (w, h), 0)
+ ImageDraw.Draw(im).text((0, h - 3 - asc + (1 if large else 0)), chr(c), font=f, fill=255)
+ glyphs[c] = im.tobytes()
+ self.cells[large] = (w, h, glyphs)
+
+ def draw(self, screen, text, x, y, large, fg, bg):
+ w, h, glyphs = self.cells[large]
+
+ def mix(t):
+ out = 0
+ for shift, mask in ((11, 31), (5, 63), (0, 31)):
+ a, b = (bg >> shift) & mask, (fg >> shift) & mask
+ out |= ((a * (255 - t) + b * t) // 255) << shift
+ return out
+
+ cx = x
+ for ch in text:
+ g = glyphs.get(ord(ch)) if ord(ch) < 128 else None
+ for j in range(h):
+ for i in range(w):
+ px, py = cx + i, y + j
+ if 0 <= px < 320 and 0 <= py < 240:
+ t = g[j * w + i] if g else 0
+ struct.pack_into("<H", screen, (py * 320 + px) * 2, mix(t))
+ cx += w
+ return cx
+
+
+class Calculator:
+ def __init__(self, nwa, flash_start=EXT_FLASH_START, storage_file=None, nwlink="nwlink", external_data=None):
+ self.flash_start = flash_start
+ self.storage_file = storage_file
+ with tempfile.TemporaryDirectory() as d:
+ elf = os.path.join(d, "app.elf")
+ cmd = [nwlink, "nwa-elf", nwa, elf, "--flash-start", hex(flash_start), "--flash-length",
+ hex(EXT_FLASH_END - flash_start), "--ram-start", hex(EXT_RAM_START), "--ram-length",
+ str(EXT_RAM_LEN), "--trampoline-start", hex(TRAMPOLINE)]
+ if external_data:
+ cmd += ["--external-data", external_data]
+ subprocess.run(cmd, check=True)
+ e = ELFFile(open(elf, "rb"))
+ self.segments = [(s["p_paddr"], s.data()) for s in e.iter_segments()
+ if s["p_type"] == "PT_LOAD" and s["p_filesz"]]
+ self.entry = e["e_entry"]
+ self.symbols = {}
+ self.functions = [] # (start, end, name) for --profile
+ st = e.get_section_by_name(".symtab")
+ if st:
+ for s in st.iter_symbols():
+ if s.name:
+ self.symbols[s.name] = s["st_value"]
+ if s["st_info"]["type"] == "STT_FUNC" and s["st_size"]:
+ a = s["st_value"] & ~1
+ self.functions.append((a, a + s["st_size"], s.name))
+ self.functions.sort()
+ 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)
+ uc.mem_write(FLASH, b"\xff" * FLASH_SIZE)
+ for addr, data in self.segments:
+ uc.mem_write(addr, data)
+ self.app_end = max(a + len(d) for a, d in self.segments if a >= FLASH)
+ # userland header (Ion::Device::UserlandHeader) and slot info, as apps find them
+ if SYSTEM == "upsilon": # no device name; then Omega's and Upsilon's blocks
+ hdr = struct.pack("<I8sIIIIIIII4sI8s16sII16sII", 0xDEC0EDFE, b"15.5.0\0\0", STORAGE, STORAGE_SIZE,
+ EXT_FLASH_START, 0x907FFFFF, EXT_RAM_START, EXT_RAM_END, 0xDEC0EDFE, 0xEFBEADDE,
+ b"1.0\0", DRAW_STRING_HOOK | 1, bytes(8), bytes(16), 0xEFBEADDE, 0x55707369,
+ b"1.1.2", 0x79827178, 0x55707369)
+ else:
+ hdr = struct.pack("<I8sIIIIIIIII", 0xDEC0EDFE, b"25.2.2\0\0", STORAGE, STORAGE_SIZE, EXT_FLASH_START,
+ EXT_FLASH_END, EXT_RAM_START, EXT_RAM_END, 0x903F0000, 0x903F0400, 0xDEC0EDFE)
+ uc.mem_write(USERLAND_HEADER, hdr)
+ uc.mem_write(SRAM, struct.pack("<IIII", 0xEFEEDBBA, 0x90000000, USERLAND_HEADER, 0xEFEEDBBA))
+ # Epsilon's file system object: magic, buffer, magic, then private members
+ storage = bytearray(STORAGE_SIZE)
+ if storage_file and os.path.exists(storage_file):
+ saved = open(storage_file, "rb").read()[:STORAGE_SIZE]
+ storage[:len(saved)] = saved
+ uc.mem_write(STORAGE, struct.pack("<I", 0xEE0BDDBA) + bytes(storage) + struct.pack("<I", 0xEE0BDDBA))
+ # then, as in Epsilon's FileSystem: delegate, record name verifier (128 bytes),
+ # accessible size, and the cache of the last record looked up (checksum, pointer)
+ self.fs_private = STORAGE + 8 + STORAGE_SIZE
+ if SYSTEM == "upsilon": # Epsilon 15's: the delegate, then the cache
+ self.cache_at = self.fs_private + 4
+ uc.mem_write(self.fs_private, struct.pack("<III", SRAM + 0xF00, 0, 0))
+ else:
+ self.cache_at = self.fs_private + 4 + 128 + 4
+ uc.mem_write(self.fs_private, struct.pack("<I", SRAM + 0xF00) + bytes(128) +
+ struct.pack("<III", STORAGE_SIZE, 0, 0))
+ # trampoline: entry 0 is the firmware's draw string
+ uc.mem_write(TRAMPOLINE, struct.pack("<I", DRAW_STRING_HOOK | 1))
+ uc.mem_write(DRAW_STRING_HOOK, b"\x70\x47" * 8)
+ uc.mem_write(EXIT_HOOK, b"\x70\x47" * 8)
+ self.screen = bytearray(320 * 240 * 2)
+ self.font = Font()
+ self.keys = [] # (start_ms, end_ms, key index)
+ self.now_ms = 0.0
+ self.slept_ms = 0.0 # time the app spent in msleep/usleep (its idle time)
+ self.samples = None # --profile: pc samples, one per emulated millisecond
+ self.rng = 0x2545F491
+ self.events = []
+ self.flash_log = []
+ self.frames = []
+ self.frame_times = []
+ self.shots = {}
+ self.pending_shots = []
+ self.insns = 0
+ self.exited = False
+ self.svc_counts = {}
+ self.locks = self.max_locks = 0
+ self.intr_hook = uc.hook_add(UC_HOOK_INTR, self._intr)
+ uc.hook_add(UC_HOOK_CODE, self._draw_string, begin=DRAW_STRING_HOOK, end=DRAW_STRING_HOOK + 1)
+ uc.hook_add(UC_HOOK_CODE, self._exit, begin=EXIT_HOOK, end=EXIT_HOOK + 1)
+ uc.hook_add(UC_HOOK_MEM_INVALID, self._invalid)
+ uc.reg_write(UC_ARM_REG_SP, STACK_TOP)
+ uc.reg_write(UC_ARM_REG_LR, EXIT_HOOK | 1)
+ self.pc = self.entry | 1
+
+ # ------------------------------------------------------------ checks
+ def enable_checks(self, reads=True):
+ """Watch for what would crash or corrupt a real calculator: unaligned
+ multi-word loads (LDRD, LDM, VLDR... fault on the Cortex-M7), writes to
+ flash outside the flash system calls, changes to the firmware's RAM
+ other than its file system, and the deepest stack use.
+ (Unicorn mis-runs some code with write hooks on RAM, so RAM writes are
+ checked by comparing snapshots, and the stack is painted.)"""
+ self.violations = []
+ if reads: # loads from the file system: records sit at any byte offset
+ self.uc.hook_add(UC_HOOK_MEM_READ, self._check, begin=STORAGE, end=STORAGE + STORAGE_SIZE + 8)
+ self.uc.hook_add(UC_HOOK_MEM_WRITE, self._flash_write, begin=FLASH, end=FLASH + FLASH_SIZE - 1)
+ self.uc.mem_write(EXT_RAM_END, b"\xa5" * (STACK_TOP - EXT_RAM_END))
+ self.ram_before = bytes(self.uc.mem_read(SRAM, SRAM_SIZE))
+
+ def _flash_write(self, uc, access, addr, size, value, data):
+ self.violations.append(f"write to flash at {addr:#x} (pc {uc.reg_read(UC_ARM_REG_PC):#x})")
+
+ def stack_used(self):
+ stack = bytes(self.uc.mem_read(EXT_RAM_END, STACK_TOP - EXT_RAM_END))
+ i = 0
+ while i < len(stack) and stack[i] == 0xA5:
+ i += 1
+ return len(stack) - i
+
+ def firmware_ram_changes(self):
+ """Offsets of firmware RAM that changed, outside the file system."""
+ now = bytes(self.uc.mem_read(SRAM, SRAM_SIZE))
+ allowed = [(EXT_RAM_START, STACK_TOP), (STORAGE + 4, STORAGE + 4 + STORAGE_SIZE),
+ (self.cache_at, self.cache_at + 8)]
+ changed = []
+ for i in range(0, SRAM_SIZE, 4):
+ if now[i:i + 4] != self.ram_before[i:i + 4]:
+ a = SRAM + i
+ if not any(lo <= a < hi for lo, hi in allowed):
+ changed.append(a)
+ return changed
+
+ def _needs_alignment(self, pc):
+ hw1, = struct.unpack("<H", self.uc.mem_read(pc, 2))
+ if hw1 >> 11 in (0x18, 0x19): # 16-bit LDM/STM
+ return "LDM/STM"
+ if hw1 < 0xE800:
+ return None
+ hw2, = struct.unpack("<H", self.uc.mem_read(pc + 2, 2))
+ if hw1 & 0xFE40 == 0xE800:
+ return "LDM/STM"
+ if hw1 & 0xFE40 == 0xE840:
+ return "LDRD/STRD/LDREX"
+ if hw1 & 0xFE00 == 0xEC00 and (hw2 >> 9) & 7 == 5:
+ return "VLDR/VSTR/VLDM/VSTM"
+ return None
+
+ def _check(self, uc, access, addr, size, value, data):
+ if addr & 3:
+ pc = uc.reg_read(UC_ARM_REG_PC)
+ kind = self._needs_alignment(pc)
+ if kind:
+ self.violations.append(f"unaligned {kind} at {addr:#x} (pc {pc:#x})")
+
+ def app_ram_clean(self):
+ return not any(self.uc.mem_read(EXT_RAM_START, EXT_RAM_LEN))
+
+ # ------------------------------------------------------------ helpers
+ def reg(self, r):
+ return self.uc.reg_read(r)
+
+ def keyboard_state(self):
+ s = 0
+ for a, b, k in self.keys:
+ if a <= self.now_ms < b:
+ s |= 1 << k
+ return s
+
+ def storage_bytes(self):
+ return bytes(self.uc.mem_read(STORAGE + 4, STORAGE_SIZE))
+
+ def set_records(self, records, cached=None):
+ """Fills the file system with (name, content) records; `cached` names the
+ record Epsilon's lookup cache points to."""
+ buf = bytearray(STORAGE_SIZE)
+ p = 0
+ where = {}
+ for name, content in records:
+ size = 2 + len(name) + 1 + len(content)
+ struct.pack_into("<H", buf, p, size)
+ buf[p + 2:p + size] = name.encode() + b"\0" + content
+ where[name] = p
+ p += size
+ self.uc.mem_write(STORAGE + 4, bytes(buf))
+ crc = ptr = 0
+ if cached:
+ crc, ptr = record_crc(cached), STORAGE + 4 + where[cached]
+ self.uc.mem_write(self.cache_at, struct.pack("<II", crc, ptr))
+
+ def cache(self):
+ return struct.unpack("<II", self.uc.mem_read(self.cache_at, 8))
+
+ def records(self):
+ buf = self.storage_bytes()
+ out, p = [], 0
+ while p + 2 <= len(buf):
+ size, = struct.unpack_from("<H", buf, p)
+ if size == 0:
+ break
+ name = buf[p + 2:buf.index(b"\0", p + 2)]
+ out.append((name.decode("latin1"), size))
+ p += size
+ return out
+
+ def save_png(self, path):
+ from PIL import Image
+ im = Image.new("RGB", (320, 240))
+ px = []
+ for i in range(0, len(self.screen), 2):
+ v = self.screen[i] | self.screen[i + 1] << 8
+ px.append((((v >> 11) & 31) * 255 // 31, ((v >> 5) & 63) * 255 // 63, (v & 31) * 255 // 31))
+ im.putdata(px)
+ im.save(path)
+
+ def frame_image(self):
+ from PIL import Image
+ import numpy as np
+ a = np.frombuffer(bytes(self.screen), dtype="<u2").reshape(240, 320)
+ rgb = np.stack([((a >> 11) & 31) * 255 // 31, ((a >> 5) & 63) * 255 // 63, (a & 31) * 255 // 31], -1)
+ return Image.fromarray(rgb.astype("uint8"), "RGB")
+
+ # ------------------------------------------------------------ hooks
+ def _invalid(self, uc, access, addr, size, value, data):
+ print(f"emu: invalid memory access at {addr:#x} (pc {uc.reg_read(UC_ARM_REG_PC):#x})", file=sys.stderr)
+ return False
+
+ def _exit(self, uc, addr, size, data):
+ self.exited = True
+ uc.emu_stop()
+
+ def _draw_string(self, uc, addr, size, data):
+ text_p, point, large, fg = (self.reg(r) for r in (UC_ARM_REG_R0, UC_ARM_REG_R1, UC_ARM_REG_R2, UC_ARM_REG_R3))
+ sp = self.reg(UC_ARM_REG_SP)
+ bg, = struct.unpack("<H", uc.mem_read(sp, 2))
+ raw = bytes(uc.mem_read(text_p, 256))
+ text = raw[:raw.index(b"\0")].decode("utf-8", "replace")
+ self.font.draw(self.screen, text, point & 0xFFFF, point >> 16, bool(large & 0xFF), fg & 0xFFFF, bg)
+ uc.reg_write(UC_ARM_REG_PC, self.reg(UC_ARM_REG_LR))
+
+ def _intr(self, uc, intno, data):
+ if intno != 2: # EXCP_SWI
+ print(f"emu: exception {intno} at pc {self.reg(UC_ARM_REG_PC):#x}", file=sys.stderr)
+ uc.emu_stop()
+ self.exited = True
+ return
+ pc = self.reg(UC_ARM_REG_PC)
+ op, = struct.unpack("<H", uc.mem_read(pc - 2, 2))
+ n = op & 0xFF
+ self.svc_counts[n] = self.svc_counts.get(n, 0) + 1
+ if SYSTEM == "upsilon" and n not in (1, 2, 3, 4, 5, 18, 19, 20, 21, 23, 34, 45, 48, 49, 50):
+ if hasattr(self, "violations"):
+ self.violations.append(f"system call {n}, which Upsilon doesn't have")
+ r0, r1, r2, r3 = (self.reg(r) for r in (UC_ARM_REG_R0, UC_ARM_REG_R1, UC_ARM_REG_R2, UC_ARM_REG_R3))
+ ret = None
+ ret1 = None
+ if n in (18, 19, 20): # pull, push, push uniform
+ x, y, w, h = r0 & 0xFFFF, r0 >> 16, r1 & 0xFFFF, r1 >> 16
+ if x + w > 320 or y + h > 240:
+ print(f"emu: rect out of screen {x},{y} {w}x{h}", file=sys.stderr)
+ w, h = max(0, min(w, 320 - x)), max(0, min(h, 240 - y))
+ if n == 20:
+ c = struct.pack("<H", r2 & 0xFFFF) * w
+ for j in range(h):
+ o = ((y + j) * 320 + x) * 2
+ self.screen[o:o + 2 * w] = c
+ elif n == 19:
+ src = bytes(uc.mem_read(r2, w * h * 2)) if w and h else b""
+ for j in range(h):
+ o = ((y + j) * 320 + x) * 2
+ self.screen[o:o + 2 * w] = src[j * w * 2:(j + 1) * w * 2]
+ else:
+ out = bytearray()
+ for j in range(h):
+ o = ((y + j) * 320 + x) * 2
+ out += self.screen[o:o + 2 * w]
+ if out:
+ uc.mem_write(r2, bytes(out))
+ self.insns += w * h // 4 # the bus is not free
+ elif n == 21:
+ ret = 1
+ elif n == 34 or n == 33:
+ s = self.keyboard_state()
+ ret, ret1 = s & 0xFFFFFFFF, s >> 32
+ elif n == 48:
+ ms = int(self.now_ms)
+ ret, ret1 = ms & 0xFFFFFFFF, ms >> 32
+ elif n == 49:
+ self.now_ms += r0
+ self.slept_ms += r0
+ elif n == 50:
+ self.now_ms += r0 / 1000
+ self.slept_ms += r0 / 1000
+ elif n == 45:
+ self.rng ^= (self.rng << 13) & 0xFFFFFFFF
+ self.rng ^= self.rng >> 17
+ self.rng ^= (self.rng << 5) & 0xFFFFFFFF
+ ret = self.rng
+ elif n == 23: # event get
+ ret = 216 # Ion::Events::None
+ s = self.keyboard_state()
+ for k in range(64):
+ if s >> k & 1:
+ ret = k
+ break
+ if ret == 216:
+ self.now_ms += 10
+ elif n in (1,):
+ ret = 128
+ elif n == 2:
+ pass
+ elif n == 3:
+ ret = 0
+ elif n == 4:
+ ret = 3 # Ion::Battery::Charge::FULL
+ elif n == 52:
+ ret = 0
+ elif n == 30: # erase sector
+ base, size = sector_range(r0)
+ ok = EXT_FLASH_START <= base and base + size <= EXT_FLASH_END
+ self.flash_log.append(("erase", r0, base, size, ok))
+ if ok:
+ uc.mem_write(base, b"\xff" * size)
+ self.now_ms += 400
+ ret = 1 if ok else 0
+ elif n == 32: # write memory
+ dst, src, length = r0, r1, r2
+ ok = EXT_FLASH_START <= dst and dst + length <= EXT_FLASH_END
+ self.flash_log.append(("write", dst, length, ok))
+ if ok:
+ old = bytes(uc.mem_read(dst, length))
+ new = bytes(uc.mem_read(src, length))
+ uc.mem_write(dst, bytes(a & b for a, b in zip(old, new)))
+ self.now_ms += length / 1024
+ ret = 1 if ok else 0
+ elif n == 10: # circuit breaker lock: Home cannot interrupt until unlock
+ self.locks += 1
+ self.max_locks = max(self.max_locks, self.locks)
+ elif n == 13:
+ self.locks -= 1
+ elif n == 15: # Ion::crc32Byte(data, length)
+ ret = epsilon_crc32(bytes(uc.mem_read(r0, r1)))
+ elif n == 16: # Ion::crc32DoubleWord(data, words)
+ ret = epsilon_crc32(bytes(uc.mem_read(r0, 4 * r1)))
+ else:
+ print(f"emu: unhandled svc {n} at {pc - 2:#x}", file=sys.stderr)
+ if ret is not None:
+ uc.reg_write(UC_ARM_REG_R0, ret & 0xFFFFFFFF)
+ if ret1 is not None:
+ uc.reg_write(UC_ARM_REG_R1, ret1 & 0xFFFFFFFF)
+
+ # ------------------------------------------------------------ running
+ def run(self, until_ms, on_frame=None, frame_ms=None):
+ chunk = CPU_HZ // 1000 # about one millisecond of instructions
+ next_frame = self.now_ms if frame_ms else None
+ while not self.exited and self.now_ms < until_ms:
+ try:
+ self.uc.emu_start(self.pc, 0xFFFFFFFF, count=chunk)
+ except UcError as err:
+ pc = self.reg(UC_ARM_REG_PC)
+ raise RuntimeError(f"CPU fault {err} at pc {pc:#x}") from None
+ self.pc = self.reg(UC_ARM_REG_PC) | 1
+ if self.samples is not None:
+ self.samples.append(self.pc & ~1)
+ self.insns += chunk
+ self.now_ms += 1
+ while self.pending_shots and self.pending_shots[0][0] <= self.now_ms:
+ t, path = self.pending_shots.pop(0)
+ self.save_png(path)
+ if frame_ms and self.now_ms >= next_frame:
+ if on_frame:
+ on_frame(self)
+ next_frame += frame_ms
+ if self.storage_file:
+ open(self.storage_file, "wb").write(self.storage_bytes())
+
+
+def parse_keys(spec):
+ out = []
+ for item in filter(None, spec.split(",")):
+ rng, k = item.split(":")
+ a, _, b = rng.partition("-")
+ a = int(a)
+ b = int(b) if b else a + 120
+ out.append((a, b, KEYS[k] if k in KEYS else int(k)))
+ return out
+
+
+def emu_cli_main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("nwa")
+ ap.add_argument("--ms", type=int, default=3000)
+ ap.add_argument("--keys", default="")
+ ap.add_argument("--shots", default="", help="comma separated times (ms)")
+ ap.add_argument("--gif", default="", help="start-end (ms) of a GIF recording")
+ ap.add_argument("--fps", type=int, default=25)
+ ap.add_argument("--out", default=".")
+ ap.add_argument("--storage", help="file keeping the calculator's storage between runs")
+ ap.add_argument("--flash-start", type=lambda s: int(s, 0), default=EXT_FLASH_START)
+ ap.add_argument("--nwlink", default="nwlink")
+ ap.add_argument("--model", choices=["n0120", "n0110"], default="n0120")
+ ap.add_argument("--system", choices=["epsilon", "upsilon"], default="epsilon")
+ ap.add_argument("--ram-length", type=int, help="the RAM apps get (default: the system's)")
+ ap.add_argument("--records", action="store_true", help="list storage records at the end")
+ ap.add_argument("--frames", help="save raw RGB565 frames here (for tools/record.py --frames)")
+ ap.add_argument("--profile", type=int, default=0,
+ help="print the N functions the CPU was found in most (build the .nwa without stripping it)")
+ a = ap.parse_args()
+ configure(a.model, a.system, a.ram_length)
+ os.makedirs(a.out, exist_ok=True)
+ c = Calculator(a.nwa, a.flash_start, a.storage, a.nwlink)
+ c.keys = parse_keys(a.keys)
+ if a.profile:
+ c.samples = []
+ c.pending_shots = sorted((int(t), os.path.join(a.out, f"shot_{int(t):06d}.png"))
+ for t in filter(None, a.shots.split(",")))
+ frames = []
+ g0, g1 = (int(x) for x in a.gif.split("-")) if a.gif else (None, None)
+
+ count = [0]
+
+ def grab(calc):
+ if g0 is not None and g0 <= calc.now_ms <= g1:
+ frames.append(calc.frame_image())
+ if a.frames:
+ name = f"{count[0]:06d}_{int(calc.now_ms):06d}.raw"
+ open(os.path.join(a.frames, name), "wb").write(bytes(calc.screen))
+ count[0] += 1
+
+ if a.frames:
+ os.makedirs(a.frames, exist_ok=True)
+ recording = a.gif or a.frames
+ c.run(a.ms, grab if recording else None, 1000 / a.fps if recording else None)
+ if frames:
+ frames[0].save(os.path.join(a.out, "anim.gif"), save_all=True, append_images=frames[1:],
+ duration=int(1000 / a.fps), loop=0)
+ c.save_png(os.path.join(a.out, "last.png"))
+ print(f"emu: {c.now_ms:.0f} ms, {c.insns / 1e6:.1f} M instructions, exited={c.exited}, "
+ f"idle {100 * c.slept_ms / max(c.now_ms, 1):.0f}%")
+ if "perf_frames" in c.symbols: # apps may count their frames in a uint32_t perf_frames
+ n = struct.unpack("<I", bytes(c.uc.mem_read(c.symbols["perf_frames"], 4)))[0]
+ print(f"emu: {n} frames, {n * 1000 / max(c.now_ms, 1):.1f} fps, "
+ f"{(c.now_ms - c.slept_ms) / max(n, 1):.1f} ms of work per frame", end="")
+ if "perf_max" in c.symbols:
+ print(f", slowest {struct.unpack('<I', bytes(c.uc.mem_read(c.symbols['perf_max'], 4)))[0]} ms", end="")
+ if "perf_slow" in c.symbols:
+ print(f", {struct.unpack('<I', bytes(c.uc.mem_read(c.symbols['perf_slow'], 4)))[0]} over 33 ms", end="")
+ print()
+ if a.profile and c.samples:
+ import bisect
+ from collections import Counter
+ starts = [f[0] for f in c.functions]
+ hits = Counter()
+ for pc in c.samples:
+ i = bisect.bisect_right(starts, pc) - 1
+ hits[c.functions[i][2] if i >= 0 and pc < c.functions[i][1] else f"?{pc:#x}"] += 1
+ for name, n in hits.most_common(a.profile):
+ print(f"emu: {100 * n / len(c.samples):5.1f}% {name}")
+ if c.flash_log:
+ print("emu: flash operations:", len(c.flash_log), "failed:", sum(1 for x in c.flash_log if not x[-1]))
+ if a.records:
+ print("emu: records:", c.records())
+
+
+
+
+# -------- Live calculator UI --------
+
+import argparse
+import json
+import os
+import queue
+import re
+import subprocess
+import signal
+import tempfile
+from collections import deque
+import shutil
+import struct
+import sys
+import threading
+import time
+import traceback
+import webbrowser
+from pathlib import Path
+import tkinter as tk
+from tkinter import filedialog, messagebox, ttk
+import tkinter.font as tkfont
+
+import numpy as np
+from PIL import Image, ImageTk, ImageDraw, ImageFont, ImageFilter
+
+try:
+ from tkinterdnd2 import DND_FILES, TkinterDnD
+except ImportError:
+ DND_FILES = None
+ TkinterDnD = None
+
+# The old emu.py backend is inlined above, preserving its separate API.
+class _BackendNamespace:
+ def __getattr__(self, key):
+ try:
+ return globals()[key]
+ except KeyError:
+ raise AttributeError(key) from None
+
+ def __setattr__(self, key, value):
+ globals()[key] = value
+
+emu = _BackendNamespace()
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+HOME_NWA = Path.home() / "Downloads" / "nwa"
+SAVE_DIR = Path.home() / ".numplay-emulator" / "saves"
+LIVE_NWA = REPO_ROOT / "build" / "compiled" / "NumPlay.nwa"
+BUILD_SCRIPT = REPO_ROOT / "tools" / "build.py"
+LCD_WIDTH = 320
+LCD_HEIGHT = 240
+FRAME_VIRTUAL_MS = 32
+STEP_VIRTUAL_MS = 2 # Bound application execution between worker checks.
+UI_POLL_MS = 20 # Keep the interface responsive to finished frames.
+LCD_UPDATE_INTERVAL_S = 1.0 / 40.0 # At most 40 displayed frames per second.
+LCD_QUIET_INTERVAL_S = 0.045 # Fallback: don't capture in the middle of a drawing burst.
+LCD_STALE_FRAME_S = 0.35 # Fallback for games with no obvious end-of-frame signal.
+WATCH_MS = 1000
+# First-pass N0120 measurements from the same Speed Probe on real hardware.
+# Solid fills: 24 * 320 * 152 pixels took 85 ms.
+# Pixel pushes: 120 * 320 * 16 pixels took 45 ms.
+# These two independent tests agree to within 0.6%: ~13.7 Mpix/s.
+# Charge a single shared LCD transfer time without sleeping the host thread.
+LCD_MS_PER_PIXEL = (85.0 / (24 * 320 * 152) + 45.0 / (120 * 320 * 16)) / 2
+# 120 18-character 7x14-pixel Epsilon text draws took 44 ms.
+# Partition approximate per-call and per-character cost; this is not a
+# replacement for a firmware-specific glyph rasterizer cycle model.
+FONT_CALL_MS = 0.030
+FONT_CHAR_MS = (44.0 / 120.0 - FONT_CALL_MS) / 18
+# The interface takes macOS's own colours (window background, labels, separators, accent), light and dark;
+# the calculator's picture keeps its own.
+SETTINGS_FILE = Path.home() / ".numplay-emulator" / "settings.json"
+THEME_PALETTES = {
+ "light": {
+ "BG": "#ececec", "PANEL": "#ececec", "PANEL_2": "#e0e0e3", "HOVER": "#d8d8dc", "LINE": "#d0d0d4",
+ "FG": "#1d1d1f", "MUTED": "#6e6e73", "ACCENT": "#007aff", "SELECT": "#cfe0fc", "ERROR_BG": "#fbe3e1",
+ "GREEN": "#28cd41", "ORANGE": "#ff9500", "RED": "#ff3b30", "CHIP": "#ffffff",
+ },
+ "dark": {
+ "BG": "#323232", "PANEL": "#323232", "PANEL_2": "#3d3d3f", "HOVER": "#48484a", "LINE": "#4a4a4c",
+ "FG": "#ececec", "MUTED": "#9a9a9f", "ACCENT": "#0a84ff", "SELECT": "#25416b", "ERROR_BG": "#4a2b2a",
+ "GREEN": "#30d158", "ORANGE": "#ff9f0a", "RED": "#ff453a", "CHIP": "#48484c",
+ },
+}
+
+
+def _read_settings():
+ try:
+ data = json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
+ except (OSError, ValueError, TypeError):
+ return {}
+ return data if isinstance(data, dict) else {}
+
+
+def _save_setting(key, value):
+ """Atomically update one preference without overwriting the others."""
+ data = _read_settings()
+ data[key] = value
+ SETTINGS_FILE.parent.mkdir(parents=True, exist_ok=True)
+ temporary = SETTINGS_FILE.with_suffix(".tmp")
+ try:
+ temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+ os.replace(temporary, SETTINGS_FILE)
+ finally:
+ temporary.unlink(missing_ok=True)
+
+
+def _activate_theme_palette(name):
+ global CURRENT_THEME
+ CURRENT_THEME = name if name in THEME_PALETTES else "light"
+ globals().update(THEME_PALETTES[CURRENT_THEME])
+
+
+_activate_theme_palette(_read_settings().get("theme", "light")) # ("system" is settled once Tk runs)
+UI_FAMILY = ("Helvetica Neue" if sys.platform == "darwin" else "Segoe UI" if os.name == "nt" else "DejaVu Sans")
+MONO_FAMILY = ("Menlo" if sys.platform == "darwin" else "Consolas" if os.name == "nt" else "DejaVu Sans Mono")
+FONT_GROW = 3 if sys.platform == "darwin" else 0 # (Tk's points are smaller on a Mac)
+
+
+def font(size, weight="normal"):
+ return (UI_FAMILY, size + FONT_GROW, weight)
+
+
+def mono(size):
+ return (MONO_FAMILY, size + FONT_GROW)
+
+# All 46 named keys in emu.KEYS. Blank cells below are intentional spacers.
+KEY_ROWS = [
+ ["home", "back", "onoff", "shift", "alpha", "backspace"],
+ ["xnt", "var", "toolbox", "up", "ok", "exe"],
+ ["exp", "ln", "log", "left", "down", "right"],
+ ["i", "comma", "power", "sin", "cos", "tan"],
+ ["pi", "sqrt", "square", "lparen", "rparen", None],
+ ["7", "8", "9", "div", "mul", "minus"],
+ ["4", "5", "6", "plus", "ee", "ans"],
+ ["1", "2", "3", "0", "dot", None],
+]
+LABEL = {
+ "home": "Home", "back": "Back", "onoff": "Power", "shift": "Shift",
+ "alpha": "Alpha", "backspace": "⌫", "xnt": "x,n,t", "var": "var",
+ "toolbox": "Toolbox", "up": "↑", "down": "↓", "left": "←", "right": "→",
+ "ok": "OK", "exe": "EXE", "exp": "eˣ", "ln": "ln", "log": "log",
+ "i": "i", "comma": ",", "power": "^", "sin": "sin", "cos": "cos",
+ "tan": "tan", "pi": "π", "sqrt": "√", "square": "x²",
+ "lparen": "(", "rparen": ")", "div": "÷", "mul": "×",
+ "minus": "−", "plus": "+", "ee": "×10ⁿ", "ans": "ans", "dot": ".",
+}
+
+# Every calculator function can also be clicked on the on-screen keyboard.
+# PC bindings emphasize unambiguous shortcuts: F1-F12 + familiar keys.
+PC_KEYSYM = {
+ "left": "left", "right": "right", "up": "up", "down": "down",
+ "return": "ok", "kp_enter": "exe", "escape": "back", "home": "home",
+ "delete": "backspace", "backspace": "backspace", "shift_l": "shift", "shift_r": "shift",
+ "alt_l": "alpha", "alt_r": "alpha", "space": "ok",
+ "f1": "home", "f2": "back", "f3": "shift", "f4": "alpha",
+ "f5": "toolbox", "f6": "var", "f7": "xnt", "f8": "onoff",
+ "f9": "ans", "f10": "exe", "f11": "sqrt", "f12": "square",
+ "plus": "plus", "kp_add": "plus", "minus": "minus", "kp_subtract": "minus",
+ "asterisk": "mul", "kp_multiply": "mul", "slash": "div", "kp_divide": "div",
+ "period": "dot", "kp_decimal": "dot", "comma": "comma", "parenleft": "lparen",
+ "parenright": "rparen", "asciicircum": "power",
+}
+PC_KEYSYM.update({str(n): str(n) for n in range(10)})
+PC_KEYSYM.update({f"kp_{n}": str(n) for n in range(10)})
+PC_KEYSYM.update({
+ "x": "xnt", "v": "var", "b": "toolbox", "e": "exp", "l": "ln",
+ "g": "log", "i": "i", "s": "sin", "c": "cos", "t": "tan",
+ "p": "pi", "q": "sqrt", "w": "square", "r": "power", "n": "ee",
+ "a": "ans",
+})
+
+
+def validate_layout():
+ placed = [k for row in KEY_ROWS for k in row if k is not None]
+ if set(placed) != set(emu.KEYS) or len(placed) != len(set(placed)):
+ missing = set(emu.KEYS) - set(placed)
+ extras = set(placed) - set(emu.KEYS)
+ raise RuntimeError(f"Keypad does not match emu.KEYS: missing={missing}, extras={extras}")
+
+
+def find_nwas() -> list[Path]:
+ """Quick bounded discovery: local builds and the user's normal download folder."""
+ patterns = (
+ REPO_ROOT / "build" / "compiled" / "live" / "*.nwa",
+ REPO_ROOT / "build" / "compiled" / "*.nwa",
+ REPO_ROOT / "build" / "compiled" / "games" / "*.nwa",
+ REPO_ROOT / "build" / "compiled" / "variants" / "*.nwa",
+ REPO_ROOT / "build" / "compiled" / "languages" / "*.nwa",
+ REPO_ROOT / "build" / "*.nwa",
+ REPO_ROOT / "build" / "apps" / "*.nwa",
+ REPO_ROOT / "games" / "*" / "output" / "*.nwa",
+ REPO_ROOT / "games" / "*" / "build" / "*.nwa",
+ HOME_NWA / "*.nwa",
+ HOME_NWA / "apps" / "*.nwa",
+ )
+ # Path.glob does not accept absolute pattern strings; use glob.glob.
+ import glob
+ found: dict[str, Path] = {}
+ for pattern in patterns:
+ for name in glob.glob(str(pattern)):
+ path = Path(name).resolve()
+ if path.is_file():
+ found[str(path).lower()] = path
+ return sorted(found.values(), key=lambda p: p.stat().st_mtime_ns, reverse=True)
+
+
+def nwlink_command() -> str | None:
+ if os.name == "nt":
+ return shutil.which("nwlink.cmd") or shutil.which("nwlink.exe")
+ 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:
+ try:
+ s = path.stat()
+ return (s.st_size, s.st_mtime_ns)
+ except OSError:
+ return None
+
+
+def rgb565_to_photo_bytes(pixels: bytes) -> Image.Image:
+ a = np.frombuffer(pixels, dtype="<u2").reshape(240, 320)
+ r = ((a >> 11) & 31) * 255 // 31
+ g = ((a >> 5) & 63) * 255 // 63
+ b = (a & 31) * 255 // 31
+ rgb = np.stack((r, g, b), axis=-1).astype(np.uint8)
+ return Image.fromarray(rgb, "RGB")
+
+
+class FidelityFont:
+ """Draw EADK firmware text with real glyphs, even without EPSILON_FONTS.
+
+ emu.Font used empty glyph dictionaries whenever EPSILON_FONTS was unset,
+ and only populated ASCII 32..126 when it was set. That rendered valid
+ firmware draw_string calls as blank foreground-free rectangles. We prefer
+ locally supplied Epsilon TTFs and use installed system fonts otherwise.
+ No fonts are downloaded or redistributed.
+ """
+
+ def __init__(self):
+ configured = Path(emu.FONT_DIR).expanduser() if emu.FONT_DIR else None
+ repo_fonts = (REPO_ROOT / "tools" / "fonts", REPO_ROOT / "fonts",
+ Path.home() / ".numplay-emulator" / "fonts")
+ system_fonts = (
+ 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 = {}
+ self.sources = []
+ for large, (filename, size, width, height) in (
+ (False, ("SmallFont.ttf", 12, 7, 14)),
+ (True, ("LargeFont.ttf", 16, 10, 18)),
+ ):
+ candidates = []
+ if configured:
+ candidates.append(configured / filename)
+ candidates.extend(folder / filename for folder in repo_fonts)
+ candidates.extend(system_fonts)
+ # Pillow ships/locates DejaVu Sans on most installations. Prefer
+ # this over the 1-bit PIL fallback if no system font can be found.
+ candidates.append("DejaVuSans.ttf")
+ font = None
+ source = None
+ for location in candidates:
+ try:
+ font = ImageFont.truetype(str(location), size)
+ source = str(location)
+ break
+ except (OSError, ValueError):
+ pass
+ if font is None:
+ try:
+ font = ImageFont.load_default(size=size)
+ except TypeError:
+ font = ImageFont.load_default()
+ source = "Pillow default fallback"
+ self.cells[large] = (width, height, font)
+ self.cache[large] = {}
+ self.sources.append(f"{'large' if large else 'small'}: {source}")
+ print("[NumPlay fonts] " + " | ".join(self.sources), file=sys.stderr, flush=True)
+ if not configured:
+ print("[NumPlay fonts] Exact Epsilon fonts are optional: set EPSILON_FONTS "
+ "to a directory containing SmallFont.ttf and LargeFont.ttf.",
+ file=sys.stderr, flush=True)
+
+ def _glyph(self, char: str, large: bool) -> bytes:
+ cache = self.cache[large]
+ if char not in cache:
+ w, h, f = self.cells[large]
+ img = Image.new("L", (w, h), 0)
+ asc = f.getmetrics()[0] if hasattr(f, "getmetrics") else h - 2
+ # Maintain the baseline used by emu.Font; match fixed EADK cells.
+ y = h - 3 - asc + (1 if large else 0)
+ if char not in ("\n", "\r", "\t"):
+ ImageDraw.Draw(img).text((0, y), char, font=f, fill=255)
+ if len(cache) >= 512:
+ cache.clear()
+ cache[char] = img.tobytes()
+ return cache[char]
+
+ def draw(self, screen: bytearray, text: str, x: int, y: int,
+ large: bool, fg: int, bg: int) -> int:
+ w, h, _ = self.cells[large]
+ fg &= 0xffff
+ bg &= 0xffff
+ # Precalculate the 256 RGB565 alpha blends once per call, not once
+ # per pixel; retain the backend's own interpolation semantics.
+ palette = []
+ for t in range(256):
+ out = 0
+ for shift, mask in ((11, 31), (5, 63), (0, 31)):
+ a = (bg >> shift) & mask
+ b = (fg >> shift) & mask
+ out |= ((a * (255 - t) + b * t) // 255) << shift
+ palette.append(struct.pack("<H", out))
+ cx = int(x)
+ for char in text:
+ if cx >= 320:
+ break
+ x0, x1 = max(0, -cx), min(w, 320 - cx)
+ y0, y1 = max(0, -y), min(h, 240 - y)
+ if x0 < x1 and y0 < y1:
+ glyph = self._glyph(char, large)
+ for j in range(y0, y1):
+ beg = j * w + x0
+ end = j * w + x1
+ dst = ((y + j) * 320 + cx + x0) * 2
+ screen[dst:dst + (end - beg) * 2] = b"".join(palette[v] for v in glyph[beg:end])
+ cx += w
+ return cx
+
+
+class TracedCalculator(emu.Calculator):
+ """Keep the headless emulator intact, but yield on time-changing syscalls.
+
+ In emu.py, Calculator.run() requests a full millisecond of ARM *instructions*
+ at once. A program can call eadk_timing_msleep(16) hundreds of times before
+ that instruction budget expires. Each call immediately advances now_ms, so
+ a single emu_start() can advance several *seconds* of virtual time. A 2ms
+ outer frontend slice cannot interrupt that work.
+
+ End the current Unicorn batch when a system call advances virtual time.
+ Calculator.run() then checks its until_ms limit and the frontend gets back
+ control between ordinary app sleeps, preserving keyboard responsiveness.
+ """
+
+ # EADK event_get with no key (23), flash erase/write (30/32), and the
+ # millisecond/microsecond sleep calls (49/50) can advance emulated time.
+ TIME_ADVANCING_SVCS = (23, 30, 32, 49, 50)
+
+ def __init__(self, *args, max_sleep_ms: int = 0, **kwargs):
+ self.max_sleep_ms = max_sleep_ms
+ self.last_long_sleep = None # (requested_ms, used_ms, svc, pc, symbol)
+ self.long_sleep_count = 0
+ self.last_svc_yield = None # (svc, pc, requested_or_delta_ms)
+ self.svc_yield_count = 0
+ self._sleep_warning_at = {} # SVC site and duration -> last diagnostic timestamp
+ # NumDrive draws 320-pixel-wide strips. Record completed bottom strips
+ # as an estimate of actual game frames, independent of UI refreshes.
+ self.fullwidth_blits = 0
+ self.fullwidth_bytes = 0
+ self.complete_display_frames = 0
+ self.fullwidth_copy_seconds = 0.0
+ # Keep a single CPU-visible framebuffer, just like V13. Unlike V13,
+ # publishing waits for a *frame boundary* instead of copying a random
+ # partial strip every 25 ms. No V14 LCD scanout or simulated tearing.
+ self.lcd_revision = 0
+ self.lcd_last_write_wall = time.monotonic()
+ self.lcd_last_published_revision = -1
+ self.on_lcd_write = None
+ self._next_lcd_notice_wall = 0.0
+ super().__init__(*args, **kwargs)
+ self.font = FidelityFont()
+ self.clipped_display_rects = 0
+ self.lcd_bus_ms = 0.0
+ self._lcd_unyielded_ms = 0.0
+
+ def _charge_lcd(self, uc, ms: float, svc: int):
+ """Account for real LCD transfers in virtual time, not host wall time.
+
+ The backend adds one virtual millisecond at the end of each Unicorn
+ instruction batch. If a display transfer exhausts the front-end's
+ 2-ms time slice, exit the batch at the drawing call boundary so input,
+ reset and window events stay responsive. The -1 compensates for the
+ backend's unconditional +1 immediately after the Unicorn stop.
+ """
+ if ms <= 0:
+ return
+ self.now_ms += ms
+ self.lcd_bus_ms += ms
+ self._lcd_unyielded_ms += ms
+ if self._lcd_unyielded_ms >= 1.0:
+ elapsed = self._lcd_unyielded_ms
+ self._lcd_unyielded_ms = 0.0
+ self.last_svc_yield = (svc, uc.reg_read(emu.UC_ARM_REG_PC), elapsed)
+ self.svc_yield_count += 1
+ self.now_ms -= 1.0
+ uc.emu_stop()
+
+ def _lcd_changed(self, complete_frame: bool = False):
+ """Record a completed EADK write, but don't expose a partial redraw.
+
+ Full-width pixel strips reaching the bottom of the screen are the
+ launcher's natural frame boundary. For games with another drawing
+ scheme, event/sleep calls and the worker's quiet-period fallback
+ provide other opportunities to publish a complete screen.
+ """
+ self.lcd_revision += 1
+ self.lcd_last_write_wall = time.monotonic()
+ if complete_frame:
+ self.publish_lcd_if_ready()
+
+ def publish_lcd_if_ready(self, *, force: bool = False) -> bool:
+ """Publish at most one stable framebuffer copy per presentation tick.
+
+ This does not touch the app-facing framebuffer, keyboard, emulated time
+ or the physical LCD's imagined scan position. It only controls which
+ *completed snapshots* reach Tk. Must run on the emulator worker thread.
+ """
+ callback = self.on_lcd_write
+ if callback is None or self.lcd_last_published_revision == self.lcd_revision:
+ return False
+ now = time.monotonic()
+ if not force and now < self._next_lcd_notice_wall:
+ return False
+ self._next_lcd_notice_wall = now + LCD_UPDATE_INTERVAL_S
+ self.lcd_last_published_revision = self.lcd_revision
+ callback(self.screen, self.now_ms, self.lcd_revision)
+ return True
+
+ def _fast_fullwidth_display(self, uc, svc: int) -> bool:
+ """Byte-copy a whole screen-width strip in one operation.
+
+ The original emu.Calculator._intr handles SVC 18/19/20 correctly, but
+ copies every row individually in Python. NumDrive's 3D renderer calls
+ push_rect(0, strip_y, 320, strip_h) for every rendered strip. Such
+ strips are contiguous in *both* source and framebuffer and can be
+ transferred exactly with a single Unicorn read/write and slice.
+ All partial-width and out-of-bounds rectangles use the original path.
+ """
+ r0 = uc.reg_read(emu.UC_ARM_REG_R0)
+ r1 = uc.reg_read(emu.UC_ARM_REG_R1)
+ x, y = r0 & 0xFFFF, r0 >> 16
+ w, h = r1 & 0xFFFF, r1 >> 16
+ if x != 0 or w != 320 or h == 0 or y + h > 240:
+ return False
+ started = time.perf_counter()
+ offset = y * 320 * 2
+ length = w * h * 2
+ if svc == 19: # eadk_display_push_rect
+ self.screen[offset:offset + length] = uc.mem_read(
+ uc.reg_read(emu.UC_ARM_REG_R2), length)
+ if y + h == 240:
+ self.complete_display_frames += 1
+ elif svc == 18: # eadk_display_pull_rect
+ uc.mem_write(uc.reg_read(emu.UC_ARM_REG_R2),
+ bytes(self.screen[offset:offset + length]))
+ elif svc == 20: # eadk_display_push_rect_uniform
+ color = uc.reg_read(emu.UC_ARM_REG_R2) & 0xFFFF
+ self.screen[offset:offset + length] = color.to_bytes(2, "little") * (w * h)
+ else:
+ return False
+ # Match the backend's accounting. Do not suppress an EADK syscall.
+ self.svc_counts[svc] = self.svc_counts.get(svc, 0) + 1
+ self.insns += w * h // 4
+ self.fullwidth_blits += 1
+ self.fullwidth_bytes += length
+ self.fullwidth_copy_seconds += time.perf_counter() - started
+ self._charge_lcd(uc, w * h * LCD_MS_PER_PIXEL, svc)
+ if svc in (19, 20):
+ # Drawing one final full-width image strip is an actual application
+ # frame boundary. A uniform color fill may be an initial clear,
+ # so don't publish a blank screen as a completed frame.
+ self._lcd_changed(complete_frame=(svc == 19 and y + h == LCD_HEIGHT))
+ return True
+
+ def _draw_string(self, uc, addr, size, data):
+ """Render firmware EADK strings; include Unicode and longer labels.
+
+ The emulator base class read 256 bytes regardless of the string's
+ length and silently blanked any non-ASCII glyphs. Respect the NUL
+ terminator while limiting input to 2 KiB for a faulty application.
+ """
+ regs = (emu.UC_ARM_REG_R0, emu.UC_ARM_REG_R1,
+ emu.UC_ARM_REG_R2, emu.UC_ARM_REG_R3)
+ ptr, point, large, fg = (uc.reg_read(r) for r in regs)
+ sp = uc.reg_read(emu.UC_ARM_REG_SP)
+ bg = int.from_bytes(uc.mem_read(sp, 2), "little")
+ raw = bytearray()
+ for offset in range(0, 2048, 32):
+ block = bytes(uc.mem_read(ptr + offset, 32))
+ nul = block.find(b"\x00")
+ raw.extend(block if nul < 0 else block[:nul])
+ if nul >= 0:
+ break
+ text = raw.decode("utf-8", "replace")
+ self.font.draw(self.screen, text, point & 0xFFFF, point >> 16,
+ bool(large & 0xFF), fg & 0xFFFF, bg)
+ uc.reg_write(emu.UC_ARM_REG_PC, uc.reg_read(emu.UC_ARM_REG_LR))
+ self._lcd_changed()
+ chars = len(text)
+ w, h = (10, 18) if (large & 0xFF) else (7, 14)
+ self._charge_lcd(uc, (FONT_CALL_MS + chars * FONT_CHAR_MS *
+ (w * h) / (7 * 14)), -1)
+
+ def _clipped_display(self, uc, svc: int) -> bool:
+ """Keep original input-buffer row stride when an EADK rect is clipped.
+
+ The backend reduces w before stepping across source rows. With a
+ clipped rectangle, that mistakenly pulls pixels from the next row,
+ looking like wrong colors/corrupt graphics at the screen edges.
+ """
+ r0 = uc.reg_read(emu.UC_ARM_REG_R0)
+ r1 = uc.reg_read(emu.UC_ARM_REG_R1)
+ x, y = r0 & 0xFFFF, r0 >> 16
+ src_w, src_h = r1 & 0xFFFF, r1 >> 16
+ if x + src_w <= 320 and y + src_h <= 240:
+ return False # fast path or the backend already handles this.
+ self.clipped_display_rects += 1
+ if self.clipped_display_rects <= 4:
+ print(f"[NumPlay display] Clipped SVC {svc}: rect "
+ f"({x}, {y}, {src_w}, {src_h})", file=sys.stderr)
+ if x >= 320 or y >= 240 or src_w == 0 or src_h == 0:
+ self.svc_counts[svc] = self.svc_counts.get(svc, 0) + 1
+ return True
+ w, h = min(src_w, 320 - x), min(src_h, 240 - y)
+ pointer = uc.reg_read(emu.UC_ARM_REG_R2)
+ for row in range(h):
+ dst = ((y + row) * 320 + x) * 2
+ length = w * 2
+ if svc == 19: # Push rows, preserving the ORIGINAL rectangle width.
+ self.screen[dst:dst + length] = uc.mem_read(pointer + row * src_w * 2, length)
+ elif svc == 18: # Pull rows, likewise preserve destination stride.
+ uc.mem_write(pointer + row * src_w * 2, bytes(self.screen[dst:dst + length]))
+ elif svc == 20:
+ color = pointer & 0xFFFF
+ self.screen[dst:dst + length] = color.to_bytes(2, "little") * w
+ self.svc_counts[svc] = self.svc_counts.get(svc, 0) + 1
+ self.insns += w * h // 4
+ self._charge_lcd(uc, w * h * LCD_MS_PER_PIXEL, svc)
+ if svc in (19, 20) and w and h:
+ self._lcd_changed(complete_frame=(svc == 19 and x == 0 and
+ w == LCD_WIDTH and y + h == LCD_HEIGHT))
+ return True
+
+ def _intr(self, uc, intno, data):
+ # The backend registers self._intr during Calculator.__init__.
+ if intno != 2:
+ return super()._intr(uc, intno, data)
+ pc = uc.reg_read(emu.UC_ARM_REG_PC)
+ op = int.from_bytes(uc.mem_read(pc - 2, 2), "little")
+ svc = op & 0xFF
+ if svc in (18, 19, 20):
+ if self._fast_fullwidth_display(uc, svc) or self._clipped_display(uc, svc):
+ return
+ start_ms = float(self.now_ms)
+ requested_ms = None
+ used_ms = None
+ if svc in (49, 50):
+ raw = uc.reg_read(emu.UC_ARM_REG_R0)
+ requested_ms = float(raw if svc == 49 else raw / 1000.0)
+ used_ms = requested_ms
+ if self.max_sleep_ms and requested_ms > self.max_sleep_ms:
+ limit = self.max_sleep_ms * (1000 if svc == 50 else 1)
+ uc.reg_write(emu.UC_ARM_REG_R0, int(limit))
+ used_ms = float(self.max_sleep_ms)
+
+ # Run the backend's real SVC implementation: preserves keyboard,
+ # flash, display, register returns, and all other NumPlay semantics.
+ result = super()._intr(uc, intno, data)
+ if svc in (18, 19, 20):
+ # The backend performed an in-bounds partial-width transfer.
+ r1 = uc.reg_read(emu.UC_ARM_REG_R1)
+ pixels = (r1 & 0xFFFF) * (r1 >> 16)
+ self._charge_lcd(uc, pixels * LCD_MS_PER_PIXEL, svc)
+ if svc in (19, 20):
+ # The backend handles ordinary partial-width display writes.
+ # Don't send Tk a half-drawn framebuffer at this SVC boundary.
+ self._lcd_changed()
+ elif svc in (23, 49, 50):
+ # Games commonly check events or sleep between complete frames.
+ # Prefer that natural boundary to a timer-driven partial snapshot.
+ self.publish_lcd_if_ready()
+ delta_ms = float(self.now_ms) - start_ms
+
+ if requested_ms is not None:
+ if requested_ms >= 250 or used_ms != requested_ms:
+ where = pc - 2
+ symbol = "(stripped/unknown symbol)"
+ for begin, end, name in getattr(self, "functions", ()):
+ if begin <= where < end:
+ symbol = name
+ break
+ self.last_long_sleep = (requested_ms, used_ms, svc, where, symbol)
+ self.long_sleep_count += 1
+ # Trace normal 16ms calls too (an earlier version only traced >=250ms),
+ # which is why sleep_svc=None even for a 3808ms step.
+ if delta_ms >= 1:
+ signature = (svc, pc - 2, round(requested_ms, 1))
+ now = time.monotonic()
+ if now - self._sleep_warning_at.get(signature, -1e9) >= 30:
+ self._sleep_warning_at[signature] = now
+ extra = (f" (guarded to {used_ms:.0f}ms)"
+ if used_ms != requested_ms else "")
+ print(f"[NumPlay sleep] svc={svc} PC=0x{pc-2:08x}; "
+ f"requested={requested_ms:.1f}ms{extra}; "
+ "yielding at SVC boundary",
+ file=sys.stderr, flush=True)
+
+ if svc == 23 and delta_ms >= 1:
+ # emu.py's 'no event' path adds 10ms, but does not mark the
+ # interval as idle. Correct the worker's CPU-load measurement.
+ self.slept_ms += delta_ms
+
+ if svc in self.TIME_ADVANCING_SVCS and delta_ms >= 0.5:
+ self.last_svc_yield = (svc, pc - 2, delta_ms)
+ self.svc_yield_count += 1
+ # emu.py unconditionally adds +1ms after emu_start() returns,
+ # assuming its entire instruction budget ran. We deliberately
+ # stopped before the budget was exhausted. Cancel that extra ms
+ # now; the backend adds it back immediately after emu_stop().
+ # (CPU cycles spent before the SVC remain an approximation.)
+ self.now_ms -= 1.0
+ uc.emu_stop()
+ return result
+
+
+class EmulatorWorker(threading.Thread):
+ def __init__(self, app_path: Path, nwlink: str, events: queue.Queue,
+ stop: threading.Event, paused: threading.Event,
+ pressed: set[str], pressed_lock: threading.Lock, save_dir: Path,
+ model: str = "n0120", system: str = "epsilon",
+ clock_mhz: list[int] | None = None,
+ auto_clock: list[bool] | None = None,
+ max_sleep_ms: int = 0,
+ profile_speed: bool = False):
+ super().__init__(daemon=True)
+ self.app_path, self.nwlink, self.events = app_path, nwlink, events
+ self.stop_requested, self.paused = stop, paused
+ self.pressed, self.pressed_lock = pressed, pressed_lock
+ self.save_dir = save_dir
+ self.model, self.system = model, system
+ self.max_sleep_ms = max_sleep_ms
+ self.profile_speed = profile_speed
+ # The UI may change this list's sole int while the worker runs.
+ # Access is atomic under Python's GIL; only this worker calls emu.run().
+ self.clock_mhz = clock_mhz if clock_mhz is not None else [216]
+ self.auto_clock = auto_clock if auto_clock is not None else [True]
+ self.end_reason: str | None = None
+ self.last_sleep_delta_ms = 0.0
+ self.last_svc_detail = None
+ self.last_sleep_detail = None
+ # Plain Python attributes: GUI only reads them; the worker only writes.
+ # These distinguish an overloaded Unicorn call from a legitimate EADK sleep.
+ self.phase = "initializing"
+ self.phase_since_wall = time.monotonic()
+ self.last_progress_wall = self.phase_since_wall
+ self.last_progress_ms = 0.0
+ self.last_cpu_seconds = 0.0
+ self.last_virtual_delta = 0.0
+
+ def set_phase(self, name: str):
+ if name != self.phase:
+ self.phase = name
+ self.phase_since_wall = time.monotonic()
+
+ def emit(self, kind: str, *payload):
+ if kind == "frame":
+ try:
+ self.events.put_nowait((kind, *payload))
+ except queue.Full:
+ # Drop an old screen rather than lagging behind the real app.
+ try:
+ self.events.get_nowait()
+ except queue.Empty:
+ pass
+ try:
+ self.events.put_nowait((kind, *payload))
+ except queue.Full:
+ pass
+ else:
+ # A small event queue is enough, even if frame production is fast.
+ while True:
+ try:
+ self.events.put_nowait((kind, *payload))
+ break
+ except queue.Full:
+ try:
+ self.events.get_nowait()
+ except queue.Empty:
+ pass
+
+ def storage_path(self) -> Path:
+ # Keep saves for separate .nwa names in a stable user directory.
+ import hashlib
+ unique = hashlib.sha256(str(self.app_path).lower().encode("utf-8")).hexdigest()[:10]
+ return self.save_dir / f"{self.app_path.stem}-{unique}.bin"
+
+ def read_keyboard(self) -> int:
+ with self.pressed_lock:
+ names = tuple(self.pressed)
+ state = 0
+ for k in names:
+ state |= 1 << emu.KEYS[k]
+ return state
+
+ def run(self):
+ app = None
+ save_path = self.storage_path()
+ try:
+ self.save_dir.mkdir(parents=True, exist_ok=True)
+ self.emit("status", f"Linking {self.app_path.name} with nwlink")
+ emu.configure(self.model, self.system)
+ app = TracedCalculator(str(self.app_path), storage_file=str(save_path),
+ nwlink=self.nwlink, max_sleep_ms=self.max_sleep_ms)
+ # Avoid rewriting a save file 30 times per second; save on stop.
+ app.storage_file = None
+ app.keyboard_state = self.read_keyboard
+ self.emit("status", f"Running {self.app_path.name}")
+ # Run ARM instructions in *small* virtual-time slices. A full 33ms
+ # emu.Calculator.run() was blocking the only CPU worker for seconds
+ # in expensive games and at module transitions. A 2ms slice limits
+ # the time before the next keyboard/frame/stop check. It preserves
+ # the backend's instruction-count and EADK msleep clock model.
+ was_paused = False
+ clock_anchor = time.monotonic()
+ last_frame_wall = clock_anchor
+ last_frame_virtual = float(app.now_ms)
+ last_frame_revision = -1
+
+ def publish_lcd(pixels, virtual_ms, revision):
+ # Called synchronously from the ARM worker's display hook.
+ # The event carries a *copy*; the emulator can continue drawing
+ # while Tk consumes it asynchronously. No fabricated swipe.
+ nonlocal last_frame_wall, last_frame_virtual, last_frame_revision
+ if self.stop_requested.is_set():
+ return
+ self.emit("frame", bytes(pixels), int(virtual_ms))
+ last_frame_wall = time.monotonic()
+ last_frame_virtual = float(virtual_ms)
+ last_frame_revision = revision
+
+ app.on_lcd_write = publish_lcd
+ rate_wall = clock_anchor
+ rate_virtual = float(app.now_ms)
+ busy_wall = busy_virtual = 0.0
+ last_auto_adjust = clock_anchor
+ smoothed_load = None
+ self.last_progress_wall = clock_anchor
+ self.last_progress_ms = float(app.now_ms)
+ profile_start = clock_anchor
+ profile_start_virtual = float(app.now_ms)
+ profile_start_frames = app.complete_display_frames
+ profile_start_blits = app.fullwidth_blits
+ profile_start_copy_seconds = app.fullwidth_copy_seconds
+ profile_cpu_seconds = 0.0
+ profile_wait_seconds = 0.0
+ while not self.stop_requested.is_set() and not app.exited:
+ if self.paused.is_set():
+ self.set_phase("paused")
+ was_paused = True
+ self.stop_requested.wait(0.035)
+ continue
+ if was_paused:
+ # Re-anchor; never run faster to pay back paused/late frames.
+ clock_anchor = time.monotonic()
+ last_auto_adjust = rate_wall = clock_anchor
+ app._next_lcd_notice_wall = 0.0
+ # Show the last completed image when resuming from pause.
+ app.publish_lcd_if_ready(force=True)
+ rate_virtual = float(app.now_ms)
+ busy_wall = busy_virtual = 0.0
+ smoothed_load = None
+ was_paused = False
+ profile_start = clock_anchor
+ profile_start_virtual = float(app.now_ms)
+ profile_start_frames = app.complete_display_frames
+ profile_start_blits = app.fullwidth_blits
+ profile_start_copy_seconds = app.fullwidth_copy_seconds
+ profile_cpu_seconds = profile_wait_seconds = 0.0
+
+ emu.CPU_HZ = max(27, min(550, int(self.clock_mhz[0]))) * 1_000_000
+ started = time.monotonic()
+ self.set_phase("running ARM CPU")
+ before_ms = float(app.now_ms)
+ before_sleep_ms = float(app.slept_ms)
+ before_sleep_count = app.long_sleep_count
+ before_yield_count = app.svc_yield_count
+ app.run(app.now_ms + STEP_VIRTUAL_MS)
+ work_seconds = max(0.0, time.monotonic() - started)
+ profile_cpu_seconds += work_seconds
+ delta_ms = max(0.0, float(app.now_ms) - before_ms)
+ slept_ms = max(0.0, float(app.slept_ms) - before_sleep_ms)
+ active_ms = max(0.0, delta_ms - min(delta_ms, slept_ms))
+ self.last_cpu_seconds = work_seconds
+ self.last_virtual_delta = delta_ms
+ self.last_sleep_delta_ms = slept_ms
+ self.last_sleep_detail = (app.last_long_sleep
+ if app.long_sleep_count != before_sleep_count else None)
+ self.last_svc_detail = (app.last_svc_yield
+ if app.svc_yield_count != before_yield_count else None)
+ self.last_progress_wall = time.monotonic()
+ self.last_progress_ms = float(app.now_ms)
+ if self.stop_requested.is_set() or app.exited:
+ break
+
+ # A large emulated sleep is not evidence that the CPU is slow.
+ # In particular, don't downclock because a single emulated
+ # millisecond of ARM work accompanied a six-second SVC sleep.
+ if self.auto_clock[0] and active_ms >= 0.5 and slept_ms < 250:
+ busy_wall += work_seconds
+ busy_virtual += active_ms
+
+ # Fallback for apps that paint isolated patches but don't
+ # sleep, request events or end with a full-width bottom strip.
+ # Avoid showing intermediate top-to-bottom redraw strips:
+ # require a quiet window after the most recent LCD write.
+ # The stale timeout guarantees that even unconventional games
+ # eventually show progress, at the cost of an occasional tear.
+ wall_now = time.monotonic()
+ if (app.lcd_revision != app.lcd_last_published_revision and
+ wall_now - last_frame_wall >= LCD_UPDATE_INTERVAL_S and
+ (wall_now - app.lcd_last_write_wall >= LCD_QUIET_INTERVAL_S or
+ wall_now - last_frame_wall >= LCD_STALE_FRAME_S)):
+ app.publish_lcd_if_ready()
+
+ # One simulated millisecond must never take *less* than one
+ # actual millisecond. Sleep overestimated virtual time, but
+ # stop waiting as soon as Reload, Pause or Power is requested.
+ # Keep a continuous timeline when on time; erase lateness
+ # beyond 40ms so there are NO catch-up bursts.
+ clock_anchor = max(clock_anchor, started - 0.040)
+ clock_anchor += delta_ms / 1000.0
+ wait_started = time.monotonic()
+ while not self.stop_requested.is_set() and not self.paused.is_set():
+ remaining = clock_anchor - time.monotonic()
+ if remaining <= 0:
+ break
+ self.set_phase("waiting for app sleep" if slept_ms >= 250
+ else "waiting for emulated time")
+ self.stop_requested.wait(min(remaining, 0.015))
+ profile_wait_seconds += max(0.0, time.monotonic() - wait_started)
+ if self.stop_requested.is_set():
+ break
+ if self.paused.is_set():
+ was_paused = True
+ continue
+
+ self.set_phase("running ARM CPU")
+ wall_now = time.monotonic()
+ if self.profile_speed and wall_now - profile_start >= 5.0:
+ seconds = wall_now - profile_start
+ frames = app.complete_display_frames - profile_start_frames
+ blits = app.fullwidth_blits - profile_start_blits
+ simulated = float(app.now_ms) - profile_start_virtual
+ # One full-width bottom strip generally completes one
+ # NumDrive 3D image. Report graphics throughput *separately*
+ # from how quickly the emulated virtual clock advances.
+ copied_ms = (app.fullwidth_copy_seconds -
+ profile_start_copy_seconds) * 1000.0
+ avg_frame_ms = (f"{1000*profile_cpu_seconds/frames:.1f}"
+ if frames else "n/a")
+ print(f"[NumPlay speed profile] "
+ f"render_fps~{frames/seconds:.1f}; "
+ f"virtual_rate={simulated/(1000*seconds):.2f}x; "
+ f"ARM_work={100*profile_cpu_seconds/seconds:.0f}%; "
+ f"wall_wait={100*profile_wait_seconds/seconds:.0f}%; "
+ f"CPU={int(self.clock_mhz[0])}MHz "
+ f"({'auto' if self.auto_clock[0] else 'manual'}); "
+ f"fullwidth_blits={blits}; "
+ f"copy_ms={copied_ms:.1f}; "
+ f"avg_ARM_ms_per_frame={avg_frame_ms}",
+ file=sys.stderr, flush=True)
+ profile_start = wall_now
+ profile_start_virtual = float(app.now_ms)
+ profile_start_frames = app.complete_display_frames
+ profile_start_blits = app.fullwidth_blits
+ profile_start_copy_seconds = app.fullwidth_copy_seconds
+ profile_cpu_seconds = profile_wait_seconds = 0.0
+ # Calibrate based on actual Unicorn throughput, separately
+ # from time spent inside EADK sleep. Earlier 1.25s sampling
+ # intervals could take far longer in a busy scene. Faster
+ # sampling and bounded steps make this responsive without a
+ # constantly oscillating MHz value.
+ if self.auto_clock[0] and wall_now - last_auto_adjust >= 0.45:
+ if busy_virtual >= 8.0:
+ load = busy_wall / max(0.001, busy_virtual / 1000.0)
+ smoothed_load = (load if smoothed_load is None else
+ 0.65 * smoothed_load + 0.35 * load)
+ old = int(self.clock_mhz[0])
+ if smoothed_load > 1.05:
+ new = max(27, int(old * 0.80))
+ elif smoothed_load < 0.58 and old < 216:
+ new = min(216, max(old + 1, int(old * 1.05)))
+ else:
+ new = old
+ self.clock_mhz[0] = new
+ busy_wall = busy_virtual = 0.0
+ last_auto_adjust = wall_now
+ elif not self.auto_clock[0]:
+ busy_wall = busy_virtual = 0.0
+ smoothed_load = None
+ last_auto_adjust = wall_now
+
+ if wall_now - rate_wall >= 1.0:
+ rate = (float(app.now_ms) - rate_virtual) / (1000.0 * (wall_now - rate_wall))
+ self.emit("pace", round(rate, 2), int(self.clock_mhz[0]), bool(self.auto_clock[0]))
+ rate_wall, rate_virtual = wall_now, float(app.now_ms)
+ if app.exited:
+ self.set_phase("exited")
+ # The caller must blank the screen; the final framebuffer is
+ # NOT a valid representation of a powered-off calculator.
+ self.end_reason = "exited"
+ self.emit("ended", "The app quit. Press On/Off or Restart to start it again")
+ except Exception:
+ self.set_phase("error")
+ error_report = traceback.format_exc()
+ # Preserve the complete traceback even if the GUI dialog is closed.
+ # Never allow a diagnostic logging error to hide the original fault.
+ try:
+ error_log = SAVE_DIR.parent / "last-error.txt"
+ error_log.parent.mkdir(parents=True, exist_ok=True)
+ error_log.write_text(error_report, encoding="utf-8")
+ except OSError:
+ error_log = None
+ print(error_report, file=sys.stderr, flush=True)
+ if error_log is not None:
+ print(f"[NumPlay emulator] Full traceback: {error_log}",
+ file=sys.stderr, flush=True)
+ self.emit("error", error_report)
+ finally:
+ if not app or not app.exited:
+ if self.phase != "error":
+ self.set_phase("stopped")
+ if app is not None:
+ try:
+ save_path.write_bytes(app.storage_bytes())
+ except Exception as exc:
+ self.emit("error", f"Could not save emulated storage:\n{exc}")
+
+
+class LiveApp:
+ def __init__(self, root: tk.Tk, initial: Path | None, nwlink: str,
+ model: str, system: str, auto_follow: bool,
+ max_sleep_ms: int = 0, profile_speed: bool = False):
+ validate_layout()
+ self.root, self.nwlink = root, nwlink
+ self.model, self.system = model, system
+ self.max_sleep_ms = max_sleep_ms
+ self.profile_speed = profile_speed
+ # Match the requested calculator model by default. For N0120 the
+ # measured integer test was 58ms at 550MHz (52ms on physical hardware).
+ # This is a stable virtual-clock baseline, not a cycle-accurate model.
+ self.clock_mhz = [550 if model == "n0120" else 216]
+ # Host-adaptive mode dynamically changes the virtual clock and can
+ # distort game timing; make it opt-in, not the release default.
+ self.auto_clock = [False]
+ self.powered_off = False
+ self._power_key_held = False
+ self.root.title("NumPlay emulator")
+ self.root.configure(bg=BG)
+ self.root.minsize(690, 820)
+ self.root.protocol("WM_DELETE_WINDOW", self.on_close)
+ self.worker: EmulatorWorker | None = None
+ self.stop_event = threading.Event()
+ self.pause_event = threading.Event()
+ self.messages: queue.Queue = queue.Queue(maxsize=3)
+ self.pressed: set[str] = set()
+ self.pressed_pc: dict[str, str] = {}
+ self.mouse_pressed: str | None = None
+ self.pressed_lock = threading.Lock()
+ self.key_widgets: dict[str, tk.Label] = {}
+ self.current: Path | None = None
+ self.pending: Path | None = None
+ self.current_stamp: tuple[int, int] | None = None
+ self.watch_candidate: tuple[tuple[str, tuple[int, int]], int] | None = None
+ self.watch_var = tk.BooleanVar(value=True)
+ self.follow_var = tk.BooleanVar(value=auto_follow)
+ self.status = tk.StringVar(value="Drop a .nwa on the calculator, or choose Open")
+ self.file_label = tk.StringVar(value="No application loaded")
+ self.time_label = tk.StringVar(value="0 ms")
+ self._screen_rgb: Image.Image | None = None
+ self._photo = None
+ self._closing = False
+ self._last_frame_wall = time.monotonic()
+ self._last_stall_log_wall = 0.0
+ self.input_status = tk.StringVar(value="Keys: ready")
+ self._build_ui()
+ self.root.bind_all("<KeyPress>", self.on_pc_down, add="+")
+ self.root.bind_all("<KeyRelease>", self.on_pc_up, add="+")
+ self.root.bind_all("<ButtonRelease-1>", self.on_mouse_up, add="+")
+ self.root.bind("<FocusOut>", self.on_focus_out, add="+")
+ self.root.bind("<FocusIn>", self.on_focus_in, add="+")
+ self.root.bind("<Map>", self.on_window_map, add="+")
+ if DND_FILES is not None:
+ for widget in (self.root, self.screen_label, self.drop_line):
+ widget.drop_target_register(DND_FILES)
+ widget.dnd_bind("<<Drop>>", self.on_drop)
+ self._poll_id = self.root.after(UI_POLL_MS, self.poll)
+ self._watch_id = self.root.after(WATCH_MS, self.watch)
+ if initial is not None:
+ self.root.after(150, lambda: self.load(initial))
+ elif not getattr(self, "_simple_mode_ui", False):
+ latest = find_nwas()
+ if latest:
+ self.root.after(150, lambda: self.load(latest[0]))
+ else:
+ self.root.after(250, self.open_file)
+
+ def _build_ui(self):
+ top = tk.Frame(self.root, bg=BG)
+ top.pack(fill="x", padx=12, pady=(12, 4))
+ tk.Label(top, text="NumPlay emulator", bg=BG, fg=FG,
+ font=font(17, "bold")).pack(side="left")
+ tk.Label(top, textvariable=self.time_label, bg=BG, fg=MUTED,
+ font=font(10)).pack(side="right")
+ actions = tk.Frame(self.root, bg=BG)
+ actions.pack(fill="x", padx=10, pady=6)
+ for title, cb in (("Open .nwa", self.open_file), ("Find newest", self.find_latest),
+ ("Reload", self.reset), ("Pause", self.toggle_pause),
+ ("Screenshot", self.screenshot), ("Keymap", self.show_keymap)):
+ button = tk.Button(actions, text=title, command=cb, bg=PANEL_2, fg=FG,
+ activebackground=HOVER, activeforeground=FG,
+ relief="flat", bd=0, padx=9, pady=7, font=font(9))
+ button.pack(side="left", padx=2)
+ if title == "Pause":
+ self.pause_button = button
+ choices = tk.Frame(self.root, bg=BG)
+ choices.pack(fill="x", padx=12, pady=(0, 6))
+ for var, label in ((self.watch_var, "Auto-reload changed .nwa"),
+ (self.follow_var, "Follow newest local build")):
+ tk.Checkbutton(choices, text=label, variable=var, bg=BG, fg=MUTED,
+ activebackground=BG, activeforeground=ACCENT,
+ selectcolor=PANEL, font=font(9)).pack(side="left", padx=4)
+ path_panel = tk.Frame(self.root, bg=PANEL, padx=10, pady=7)
+ path_panel.pack(fill="x", padx=12, pady=2)
+ tk.Label(path_panel, textvariable=self.file_label, bg=PANEL, fg=FG,
+ anchor="w", font=font(9)).pack(fill="x")
+ center = tk.Frame(self.root, bg=BG)
+ center.pack(fill="x", padx=12, pady=8)
+ self._screen_rgb = Image.new("RGB", (320, 240), (235, 235, 235))
+ self._photo = ImageTk.PhotoImage(self._screen_rgb.resize((640, 480), Image.Resampling.NEAREST))
+ self.screen_label = tk.Label(center, image=self._photo, bg="#050505", bd=7, relief="flat")
+ self.screen_label.pack(anchor="center")
+ self.drop_line = tk.Label(center, text=("Drop a .nwa here, " if DND_FILES else "") +
+ "click a key or use your PC keyboard", bg=BG, fg=MUTED,
+ font=font(9), pady=4)
+ self.drop_line.pack()
+ keyboard = tk.Frame(self.root, bg=BG)
+ keyboard.pack(fill="both", expand=True, padx=12, pady=5)
+ for col in range(6):
+ keyboard.grid_columnconfigure(col, weight=1, uniform="numworks")
+ for i, row in enumerate(KEY_ROWS):
+ keyboard.grid_rowconfigure(i, weight=1)
+ for j, key in enumerate(row):
+ if key is None:
+ continue
+ bg = ACCENT if key in ("ok", "exe") else (SELECT if key in
+ ("left", "right", "up", "down") else PANEL_2)
+ if key in ("home", "onoff", "shift", "alpha"):
+ bg = HOVER
+ w = tk.Label(keyboard, text=LABEL.get(key, key), bg=bg, fg=FG,
+ relief="flat", bd=0, font=font(10, "bold"),
+ padx=5, pady=5, cursor="hand2")
+ w.grid(row=i, column=j, sticky="nsew", padx=3, pady=3)
+ w.bind("<ButtonPress-1>", lambda e, k=key: self.on_mouse_down(k))
+ w.bind("<ButtonRelease-1>", self.on_mouse_up)
+ self.key_widgets[key] = w
+ status = tk.Label(self.root, textvariable=self.status, bg=PANEL, fg=ACCENT,
+ anchor="w", padx=12, pady=7, font=font(9))
+ status.pack(fill="x", side="bottom")
+ self.root.focus_force()
+
+ def set_status(self, msg: str):
+ self.status.set(msg)
+
+ def open_file(self):
+ path = filedialog.askopenfilename(parent=self.root, title="Open a NumWorks application",
+ filetypes=[("NumWorks apps", "*.nwa"), ("All files", "*.*")],
+ initialdir=str(HOME_NWA if HOME_NWA.exists() else REPO_ROOT))
+ if path:
+ self.follow_var.set(False)
+ self.load(Path(path))
+
+ def on_drop(self, event):
+ for s in self.root.tk.splitlist(event.data):
+ if s.lower().endswith(".nwa"):
+ self.follow_var.set(False)
+ self.load(Path(s))
+ return
+ self.set_status("Drop a .nwa file from File Explorer.")
+
+ def find_latest(self):
+ found = find_nwas()
+ if found:
+ self.load(found[0])
+ else:
+ messagebox.showinfo("No .nwa found", "Build a .nwa or drop one here.\n"
+ "Searches build/, games/*/output/ and Downloads/nwa/.")
+
+ def load(self, path: Path):
+ path = path.expanduser().resolve()
+ if path.suffix.lower() != ".nwa" or not path.is_file():
+ self.set_status(f"Not a valid .nwa file: {path}")
+ return
+ self.pending = path
+ self.pause_event.clear()
+ self.pause_button.configure(text="Pause")
+ self.clear_keys()
+ if self.worker is not None and self.worker.is_alive():
+ self.stop_event.set()
+ self.set_status(f"Reloading {path.name}")
+ else:
+ self.start_pending()
+
+ def start_pending(self):
+ path = self.pending
+ if path is None:
+ return
+ self.pending = None
+ self.current = path
+ self._last_frame_wall = time.monotonic()
+ self._last_stall_log_wall = 0.0
+ self.current_stamp = fingerprint(path)
+ self.watch_candidate = None
+ self.file_label.set(str(path))
+ self.time_label.set("0 ms")
+ self.messages = queue.Queue(maxsize=3)
+ self.stop_event = threading.Event()
+ self.powered_off = False
+ self.worker = EmulatorWorker(path, self.nwlink, self.messages, self.stop_event,
+ self.pause_event, self.pressed, self.pressed_lock,
+ SAVE_DIR, self.model, self.system,
+ self.clock_mhz, self.auto_clock,
+ self.max_sleep_ms, self.profile_speed)
+ self.worker.start()
+
+ def reset(self):
+ if self.current:
+ self.load(self.current)
+ else:
+ self.find_latest()
+
+ def present_screen(self):
+ """Display the current RGB screen; overridden by the skinned GUI."""
+ if self._screen_rgb is None:
+ return
+ self._photo = ImageTk.PhotoImage(self._screen_rgb.resize((640, 480), Image.Resampling.NEAREST))
+ self.screen_label.configure(image=self._photo)
+
+ def black_screen(self, reason: str):
+ self.powered_off = True
+ self._screen_rgb = Image.new("RGB", (320, 240), (0, 0, 0))
+ self.present_screen()
+ self.time_label.set("Powered off")
+ self.set_status(reason)
+
+ def power_button(self):
+ """Power button is a frontend power toggle, not a stuck ARM key.
+
+ Epsilon's power-off firmware isn't emulated. Sending the raw on/off
+ key can leave the app waiting forever for firmware wakeup, so blank
+ the screen and stop the worker. Click again to boot the .nwa anew.
+ """
+ if self.powered_off:
+ self.reset()
+ else:
+ self.pending = None
+ self.stop_event.set()
+ self.pause_event.clear()
+ self.pause_button.configure(text="Pause")
+ self.clear_keys()
+ self.black_screen("Turned off. Press On/Off or Restart to start again")
+
+ def toggle_pause(self):
+ if self.pause_event.is_set():
+ self.pause_event.clear()
+ self.pause_button.configure(text="Pause")
+ self.set_status("Resumed")
+ else:
+ self.pause_event.set()
+ self.pause_button.configure(text="Resume")
+ self.set_status("Paused (emulated clock stopped)")
+
+ def screenshot(self):
+ if self._screen_rgb is None:
+ return
+ directory = REPO_ROOT / "build" / "data" / "emulator"
+ directory.mkdir(parents=True, exist_ok=True)
+ path = directory / f"{self.current.stem if self.current else 'screen'}-{int(time.time())}.png"
+ self._screen_rgb.save(path)
+ self.set_status(f"Screenshot saved: {path}")
+
+ def on_mouse_down(self, key: str):
+ if key == "onoff":
+ self.power_button()
+ return
+ if self.powered_off:
+ return
+ if self.mouse_pressed is not None:
+ self.on_mouse_up()
+ self.mouse_pressed = key
+ self.input_status.set(f"Keys: {key}")
+ self.refresh_pressed()
+
+ def on_mouse_up(self, event=None):
+ if self.mouse_pressed is not None:
+ self.mouse_pressed = None
+ self.refresh_pressed()
+
+ def on_pc_down(self, event):
+ # Don't send keyboard shortcuts from another Toplevel (e.g. Keymap).
+ if event.widget.winfo_toplevel() is not self.root:
+ return None
+ if sys.platform == "darwin" and event.state & 0x8: # (Command: a menu's shortcut)
+ return None
+ sym = event.keysym.lower()
+ key = PC_KEYSYM.get(sym)
+ if key == "onoff":
+ if not self._power_key_held:
+ self._power_key_held = True
+ self.power_button()
+ return "break"
+ if self.powered_off:
+ return "break" if key else None
+ if key:
+ self.pressed_pc[sym] = key
+ self.input_status.set(f"Keys: {key}")
+ self.refresh_pressed()
+ # ALL NumWorks keys must be intercepted, not just Space. Otherwise
+ # Tk buttons/dropdowns can steal arrow keys after a focus change.
+ return "break"
+ return None
+
+ def on_pc_up(self, event):
+ if event.widget.winfo_toplevel() is not self.root:
+ return None
+ sym = event.keysym.lower()
+ if PC_KEYSYM.get(sym) == "onoff":
+ self._power_key_held = False
+ return "break"
+ if sym in self.pressed_pc:
+ self.pressed_pc.pop(sym, None)
+ self.refresh_pressed()
+ return "break"
+ return None
+
+ def on_focus_out(self, event):
+ # Releasing Alt, Shift or directions in another window does not produce
+ # KeyRelease events here. Prevent ghost keys when returning to the game.
+ if event.widget is self.root:
+ self.clear_keys()
+ self.input_status.set("Keys: released")
+
+ def on_focus_in(self, event):
+ if event.widget is self.root:
+ self.root.after(60, self.refocus_input)
+
+ def on_window_map(self, event):
+ if event.widget is self.root:
+ self.root.after(80, self.refocus_input)
+
+ def refocus_input(self):
+ """Give keyboard events to the calculator after a dialog or Alt-Tab.
+
+ Use focus_set (not focus_force), to avoid grabbing focus away from
+ other Windows applications when we're in the background.
+ """
+ if self._closing or not hasattr(self, "canvas"):
+ return
+ try:
+ if self.root.focus_displayof() is not None:
+ self.canvas.focus_set()
+ self.input_status.set("Keys: ready")
+ except tk.TclError:
+ pass
+
+ def clear_keys(self):
+ self.pressed_pc.clear()
+ self.mouse_pressed = None
+ self._power_key_held = False
+ self.refresh_pressed()
+
+ def refresh_pressed(self):
+ names = set(self.pressed_pc.values())
+ if self.mouse_pressed is not None:
+ names.add(self.mouse_pressed)
+ with self.pressed_lock:
+ self.pressed.clear()
+ self.pressed.update(names)
+ for k, widget in self.key_widgets.items():
+ if k in names:
+ widget.configure(bg=ACCENT, fg=FG)
+ else:
+ widget.configure(fg=FG, bg=(ACCENT if k in ("ok", "exe") else
+ SELECT if k in ("left", "right", "up", "down") else
+ HOVER if k in ("home", "onoff", "shift", "alpha") else PANEL_2))
+
+ def show_keymap(self):
+ w = tk.Toplevel(self.root)
+ w.title("PC keyboard shortcuts")
+ w.configure(bg=BG)
+ w.geometry("615x430")
+ lines = [
+ "ALL calculator keys are clickable on the main window.",
+ "Hold mouse button for continuous keypress (e.g. duck).",
+ "", "Arrows = ← ↑ ↓ → Enter / Space = OK Numpad Enter = EXE",
+ "Esc = Back Home / F1 = Home Backspace / Delete = ⌫",
+ "Shift = Shift Alt = Alpha F8 = Power",
+ "", "F2 Back F3 Shift F4 Alpha F5 Toolbox",
+ "F6 var F7 x,n,t F9 ans F10 EXE",
+ "F11 = Fullscreen in skinned UI (√ in plain UI) F12 = x²", "",
+ "Digits 0–9, numpad, + - * / , . ( ) ^ work as expected.",
+ "", "x=x,n,t v=var b=Toolbox e=eˣ l=ln g=log",
+ "i=i s=sin c=cos t=tan p=π q=√",
+ "w=x² r=^ n=×10ⁿ a=ans", "",
+ "Drag any .nwa into the window or click Open .nwa.",
+ "Single file: no automatic builds or reloads.",
+ "Live development: compiles sources and reloads after a successful build.",
+ "Emulated saves persist in ~/.numplay-emulator/saves/.",
+ ]
+ tk.Label(w, text="\n".join(lines), justify="left", bg=BG, fg=FG,
+ font=mono(10), padx=18, pady=14).pack(anchor="nw")
+
+ def poll(self):
+ if self._closing:
+ return
+ newest_frame = None
+ last_status = None
+ ended = None
+ error = None
+ while True:
+ try:
+ m = self.messages.get_nowait()
+ except queue.Empty:
+ break
+ if m[0] == "frame":
+ newest_frame = m
+ elif m[0] == "status":
+ last_status = m[1]
+ elif m[0] == "ended":
+ ended = m[1]
+ elif m[0] == "error":
+ error = m[1]
+ if last_status and not self.powered_off:
+ self.set_status(last_status)
+ if not self.powered_off and newest_frame and not ended:
+ _, raw, elapsed = newest_frame
+ try:
+ self._screen_rgb = rgb565_to_photo_bytes(raw)
+ self.present_screen()
+ self.time_label.set(f"{elapsed:,} ms (virtual)")
+ except Exception as exc:
+ self.set_status(f"Display error: {exc}")
+ if ended and not self.powered_off:
+ self.black_screen(ended)
+ elif (self.worker is not None and self.worker.end_reason == "exited"
+ and not self.powered_off):
+ # Also handle a full message queue dropping an end notification.
+ self.black_screen("The app quit. Press Restart to start it again")
+ if error and not self.powered_off:
+ self.set_status("The emulator stopped with an error")
+ messagebox.showerror("NumPlay emulator", error)
+ if self.pending is not None and (self.worker is None or not self.worker.is_alive()):
+ self.start_pending()
+ self._poll_id = self.root.after(UI_POLL_MS, self.poll)
+
+ def watch(self):
+ if self._closing:
+ return
+ try:
+ if self.follow_var.get():
+ latest = find_nwas()
+ if latest and (self.current is None or latest[0] != self.current):
+ # Switch only when a new build is stable across checks.
+ self._maybe_reload(latest[0])
+ elif self.current is not None and self.watch_var.get():
+ self._maybe_reload(self.current)
+ elif self.current is not None and self.watch_var.get():
+ self._maybe_reload(self.current)
+ except OSError as exc:
+ self.set_status(f"Auto-reload check: {exc}")
+ self._watch_id = self.root.after(WATCH_MS, self.watch)
+
+ def _maybe_reload(self, path: Path):
+ stamp = fingerprint(path)
+ if stamp is None:
+ return
+ if path == self.current and stamp == self.current_stamp:
+ self.watch_candidate = None
+ return
+ marker = (str(path), stamp)
+ if self.watch_candidate is None or self.watch_candidate[0] != marker:
+ self.watch_candidate = (marker, 1)
+ return
+ self.watch_candidate = None
+ self.load(path)
+
+ def on_close(self):
+ self._closing = True
+ self.stop_event.set()
+ self.clear_keys()
+ # Worker is a daemon; allow a short non-blocking poll to save storage.
+ self._close_deadline = time.monotonic() + 3.0
+ self._finish_close()
+
+ def _finish_close(self):
+ if self.worker is None or not self.worker.is_alive() or time.monotonic() > self._close_deadline:
+ for callback in (self._poll_id, self._watch_id):
+ try:
+ self.root.after_cancel(callback)
+ except tk.TclError:
+ pass
+ self.root.destroy()
+ else:
+ self.root.after(100, self._finish_close)
+
+
+# ---------- The calculator: a picture of a NumWorks N0120, its screen and keys measured on it ----------
+CALCULATOR = Path(__file__).resolve().parent / "emu_live_calculator.webp"
+CALCULATOR_SIZE = (1018, 2000)
+# (x, y, width, height) in the picture's pixels; the arrows' middle does nothing, as on the calculator
+SCREEN_PX = (148, 154, 722, 542)
+KEYS_PX = {
+ "up": (191, 799, 74, 88), "down": (191, 960, 74, 88), "left": (105, 887, 86, 73), "right": (265, 887, 88, 73),
+ "home": (439, 816, 139, 90), "onoff": (439, 941, 139, 90), "ok": (664, 866, 109, 112),
+ "back": (803, 866, 109, 112),
+}
+FUNCTIONS = (
+ "shift", "alpha", "xnt", "var", "toolbox", "backspace",
+ "exp", "ln", "log", "i", "comma", "power",
+ "sin", "cos", "tan", "pi", "sqrt", "square",
+)
+DIGITS = (
+ "7", "8", "9", "lparen", "rparen",
+ "4", "5", "6", "mul", "div",
+ "1", "2", "3", "plus", "minus",
+ "0", "dot", "ee", "ans", "exe",
+)
+for _row, (_y0, _y1) in enumerate(((1094, 1168), (1204, 1280), (1316, 1392))):
+ for _col, (_x0, _x1) in enumerate(((105, 214), (244, 354), (384, 493), (524, 633), (664, 773), (803, 912))):
+ KEYS_PX[FUNCTIONS[_row * 6 + _col]] = (_x0, _y0, _x1 - _x0, _y1 - _y0)
+for _row, (_y0, _y1) in enumerate(((1431, 1517), (1556, 1641), (1678, 1766), (1805, 1890))):
+ for _col, (_x0, _x1) in enumerate(((105, 239), (273, 407), (442, 576), (610, 744), (779, 912))):
+ KEYS_PX[DIGITS[_row * 5 + _col]] = (_x0, _y0, _x1 - _x0, _y1 - _y0)
+
+
+def _fraction(box):
+ x, y, w, h = box
+ return (x / CALCULATOR_SIZE[0], y / CALCULATOR_SIZE[1], w / CALCULATOR_SIZE[0], h / CALCULATOR_SIZE[1])
+
+
+SCREEN = _fraction(SCREEN_PX)
+HOTSPOTS = {key: _fraction(box) for key, box in KEYS_PX.items()}
+assert set(HOTSPOTS) == set(emu.KEYS), (set(emu.KEYS) - set(HOTSPOTS))
+
+
+class FlatButton(tk.Label):
+ """A plain button that keeps its colours on every system (a Mac's tk.Button ignores them): grey, or NumWorks
+ yellow for the one main action; greyed out when disabled. Takes text=, state= and command= like tk.Button."""
+
+ def __init__(self, parent, text, command, primary=False):
+ self._bg = ACCENT if primary else PANEL_2
+ super().__init__(parent, text=text, bg=self._bg, fg=("#34343a" if primary else FG), font=font(10, "bold" if primary else "normal"),
+ pady=8, cursor="hand2", disabledforeground="#b5b5b5")
+ self._command = command
+ self.bind("<Enter>", lambda e: self._enabled() and super(FlatButton, self).configure(
+ bg="#ffc85c" if self._bg == ACCENT else HOVER))
+ self.bind("<Leave>", lambda e: super(FlatButton, self).configure(bg=self._bg))
+ self.bind("<ButtonRelease-1>", lambda e: self._enabled() and self._command and self._command())
+
+ def _enabled(self):
+ return str(self.cget("state")) != "disabled"
+
+ def configure(self, cnf=None, **kw):
+ if "command" in kw:
+ self._command = kw.pop("command")
+ return super().configure(cnf, **kw)
+
+ config = configure
+
+
+def _safe_window_geometry(placement, root):
+ """Ignore invalid/off-screen saved placements after a display change."""
+ if not isinstance(placement, dict):
+ return None
+ values = [placement.get(k) for k in ("width", "height", "x", "y")]
+ if any(type(v) is not int or abs(v) > 100000 for v in values):
+ return None
+ width, height, x, y = values
+ if width < 400 or height < 250:
+ return None
+ screen_w, screen_h = root.winfo_screenwidth(), root.winfo_screenheight()
+ if min(screen_w, screen_h) <= 0:
+ return None
+ width = min(width, screen_w)
+ height = min(height, screen_h)
+ # A title bar and at least a strip of the window should remain accessible.
+ if x + width < 160 or x > screen_w - 160 or y + height < 60 or y > screen_h - 60:
+ x = max(0, (screen_w - width) // 2)
+ y = max(0, (screen_h - height) // 2)
+ else:
+ x = max(0, min(x, screen_w - 160))
+ y = max(0, min(y, screen_h - 60))
+ return (width, height, x, y, placement.get("maximized") is True)
+
+
+# ---------- Keys pressed: each sinks in, in its own shape ----------
+def _key_radius(key, w, h):
+ """The corner radius of a key's face, in the same units as w and h (None: it's round)."""
+ if key in ("ok", "back"):
+ return None
+ if key in ("up", "down", "left", "right"):
+ return min(w, h) * 0.3
+ return h * (0.42 if key in DIGITS else 0.5)
+
+
+def key_sprite(key, w, h, state):
+ """A see-through picture laid over a key: "pressed" darkens its face and shades its top edge inside, as a
+ key pushed in; "hover" shades it a little."""
+ k = 4 # (drawn 4 times bigger, then made smaller: smooth edges)
+ mask = Image.new("L", (w * k, h * k), 0)
+ d = ImageDraw.Draw(mask)
+ r = _key_radius(key, w * k, h * k)
+ if r is None:
+ d.ellipse((0, 0, w * k - 1, h * k - 1), fill=255)
+ else:
+ d.rounded_rectangle((0, 0, w * k - 1, h * k - 1), radius=r, fill=255)
+ mask = mask.resize((w, h), Image.Resampling.LANCZOS)
+ m = np.asarray(mask, dtype=np.float32) / 255
+ if state == "hover":
+ alpha = m * 0.06
+ out = np.zeros((h, w, 4), np.float32)
+ out[..., 3] = alpha
+ return Image.fromarray((out * 255).astype(np.uint8), "RGBA")
+ # the shadow under the top edge: the face less itself moved down, blurred, kept inside the face
+ drop = max(1, round(h * 0.08))
+ moved = np.zeros_like(m)
+ moved[drop:] = m[:-drop]
+ edge = Image.fromarray((np.clip(m - moved, 0, 1) * 255).astype(np.uint8), "L")
+ edge = edge.filter(ImageFilter.GaussianBlur(max(1.0, h * 0.07)))
+ shade = np.asarray(edge, dtype=np.float32) / 255 * m
+ dark = np.clip(m * 0.15 + shade * 0.6, 0, 0.8)
+ # a thin light line along the bottom edge, inside
+ up = np.zeros_like(m)
+ up[:-1] = m[1:]
+ light = np.clip(m - up, 0, 1) * 0.35
+ layer = lambda rgb, a: Image.merge("RGBA", [Image.new("L", (w, h), c) for c in rgb] +
+ [Image.fromarray((a * 255).astype(np.uint8), "L")])
+ return Image.alpha_composite(layer((16, 18, 24), dark), layer((255, 255, 255), light))
+
+
+# what a computer key is called on its key cap, for the badge over the calculator key it presses
+PC_GLYPH = {"return": "⏎", "kp_enter": "⌅", "escape": "esc", "left": "←", "right": "→", "up": "↑",
+ "down": "↓", "shift_l": "⇧", "shift_r": "⇧", "alt_l": "⌥", "alt_r": "⌥", "space": "space",
+ "delete": "⌫", "backspace": "⌫", "home": "home", "plus": "+", "kp_add": "+", "minus": "−",
+ "kp_subtract": "−", "asterisk": "*", "kp_multiply": "*", "slash": "/", "kp_divide": "/",
+ "period": ".", "kp_decimal": ".", "comma": ",", "parenleft": "(", "parenright": ")",
+ "asciicircum": "^"}
+
+
+# the calculator keys by name, where their label is a symbol
+KEY_NAMES = {"left": "Left", "right": "Right", "up": "Up", "down": "Down", "ok": "OK", "back": "Back",
+ "home": "Home", "onoff": "On/Off", "shift": "Shift", "alpha": "Alpha", "backspace": "Delete",
+ "exe": "EXE", "toolbox": "Toolbox"}
+
+
+def pc_glyph(sym):
+ if sym in PC_GLYPH:
+ return PC_GLYPH[sym]
+ if sym.startswith("kp_"):
+ return sym[3:]
+ if len(sym) == 1:
+ return sym.upper()
+ return sym.upper() if re.fullmatch(r"f\d+", sym) else sym
+
+
+def round_rect(canvas, x0, y0, x1, y1, r, **kw):
+ """A rounded rectangle on a Tk canvas (a smoothed polygon)."""
+ pts = [x0 + r, y0, x1 - r, y0, x1, y0, x1, y0 + r, x1, y1 - r, x1, y1, x1 - r, y1, x0 + r, y1, x0, y1,
+ x0, y1 - r, x0, y0 + r, x0, y0]
+ return canvas.create_polygon(pts, smooth=True, **kw)
+
+
+class CalculatorSkinApp(LiveApp):
+ """NumWorks skin with mutually exclusive file and live-development modes.
+
+ Only this GUI runs the watcher; the existing Makefiles/build script and
+ emu.Calculator backend are deliberately untouched.
+ """
+
+ def __init__(self, root, initial, nwlink, model, system, auto_follow,
+ art_path: Path, max_sleep_ms: int = 0,
+ profile_speed: bool = False, start_live: bool = False):
+ self.art_path = art_path
+ self._art_rgba = Image.open(art_path).convert("RGBA") # (its corners and shadow are see-through)
+ self.art = self._art_on(BG)
+ self.art_px = self.art.size
+ self._canvas_image = None
+ self._canvas_screen = None
+ self._bg_photo = None
+ self._art_geometry = (0, 0, 0, 0)
+ self._hover = None
+ self._last_canvas_size = None
+ self.fullscreen = False
+ self.f11_down = False
+ self.rate_label = tk.StringVar(master=root, value="Emulator ready")
+ # Display choice and build choice are independent: neither view switch
+ # restarts Unicorn nor starts/stops the compiler.
+ self.view_var = tk.StringVar(master=root, value="calculator")
+ self._native_geometry = None
+ self.mode_var = tk.StringVar(master=root, value="live" if start_live else "file")
+ self.build_status = tk.StringVar(master=root, value="Choose a .nwa to play")
+ self.build_detail = tk.StringVar(master=root, value="No compiler process running")
+ self.build_process = None
+ self._builder_generation = 0
+ self._builder_events = queue.Queue()
+ self._builder_log = deque(maxlen=850)
+ self._build_log_window = None
+ self._build_log_text = None
+ self._builder_has_error = False
+ self._builder_ready = False
+ self._builder_busy = False
+ self._builder_stopping = False
+ self._simple_mode_ui = True
+ # A physical USB flash must never be triggered by auto-build/reload.
+ self._upload_running = False
+ self._upload_events = queue.Queue()
+ self._upload_log = deque(maxlen=120)
+ self._upload_start_wall: float | None = None
+ self._upload_progress_is_reported = False
+ self._upload_log_window = None
+ self._upload_log_text = None
+ self.upload_status = tk.StringVar(master=root, value="Installs the open app on a calculator plugged in "
+ "with USB")
+ self.upload_activity = tk.StringVar(master=root, value="")
+ self.upload_elapsed = tk.StringVar(master=root, value="")
+ self.appearance = _read_settings().get("theme", "system")
+ if self.appearance not in ("system", "light", "dark"):
+ self.appearance = "system"
+ self._sprites = {}
+ self._sprite_photos = []
+ self._speed_hist = deque(maxlen=60)
+ self._snap_id = None
+ self._look_checked = 0.0
+ super().__init__(root, initial, nwlink, model, system, False,
+ max_sleep_ms=max_sleep_ms, profile_speed=profile_speed)
+ # Avoid the original fallback's ambiguous 'newest local file' behavior.
+ self.watch_var.set(False)
+ self.follow_var.set(False)
+ self._builder_poll_id = self.root.after(120, self._poll_builder)
+ self._upload_poll_id = self.root.after(160, self._poll_upload)
+ self._set_appearance(self.appearance, initial=True)
+ self._apply_interface_theme()
+ self._restore_window_placement()
+ self.root.bind("<Configure>", self._remember_window_geometry, add="+")
+ if start_live:
+ self.root.after(260, self._start_builder)
+
+ def _art_on(self, bg):
+ return Image.alpha_composite(Image.new("RGBA", self._art_rgba.size, bg), self._art_rgba).convert("RGB")
+
+ def _restore_window_placement(self):
+ placement = _safe_window_geometry(_read_settings().get("window"), self.root)
+ self._window_last_normal = None
+ self._window_restoring = bool(placement)
+ if placement is None:
+ return
+ width, height, x, y, maximized = placement
+ self._window_last_normal = (width, height, x, y)
+ self.root.geometry(f"{width}x{height}+{x}+{y}")
+ if maximized:
+ self.root.after(110, self._restore_window_maximized)
+ self.root.after(200, self._finish_window_restoring)
+
+ def _restore_window_maximized(self):
+ try:
+ self.root.state("zoomed")
+ except tk.TclError:
+ try:
+ self.root.attributes("-zoomed", True)
+ except tk.TclError:
+ pass
+
+ def _finish_window_restoring(self):
+ self._window_restoring = False
+
+ def _remember_window_geometry(self, event=None):
+ if event is not None and event.widget is not self.root:
+ return
+ if getattr(self, "_window_restoring", False) or self.fullscreen:
+ return
+ try:
+ if self.root.state() == "normal":
+ width, height = self.root.winfo_width(), self.root.winfo_height()
+ if width >= 400 and height >= 250:
+ self._window_last_normal = (width, height,
+ self.root.winfo_x(), self.root.winfo_y())
+ except tk.TclError:
+ pass
+
+ def _save_window_placement(self):
+ try:
+ state = self.root.state()
+ if state == "normal" and not self.fullscreen:
+ self._remember_window_geometry()
+ if self._window_last_normal is None:
+ return
+ width, height, x, y = self._window_last_normal
+ _save_setting("window", {"width": width, "height": height,
+ "x": x, "y": y,
+ "maximized": state == "zoomed" and not self.fullscreen})
+ except (OSError, ValueError, tk.TclError) as exc:
+ print(f"[NumPlay] Could not save window placement: {exc}", file=sys.stderr)
+
+ INSPECTOR_W = 280
+ MODELS = (("N0120", "n0120"), ("N0110 or N0115", "n0110"))
+ SYSTEMS = (("Epsilon", "epsilon"), ("Upsilon", "upsilon"))
+ SPEEDS = ("Like the calculator", "Like this computer (less exact)", "108 MHz", "54 MHz", "27 MHz")
+
+ def _build_ui(self):
+ aqua = self.root.tk.call("tk", "windowingsystem") == "aqua"
+ self._aqua = aqua
+ if aqua: # (the system font, San Francisco)
+ global UI_FAMILY
+ UI_FAMILY = tkfont.nametofont("TkDefaultFont").actual("family")
+ self._cmd = "Command" if aqua else "Control"
+ self.root.title("NumPlay Simulator")
+ # the window holds the calculator and the inspector, no more: the calculator as tall as fits
+ dev_h = max(560, min(860, self.root.winfo_screenheight() - 150))
+ dev_w = round(dev_h * self.art_px[0] / self.art_px[1])
+ self.root.geometry(f"{dev_w + 1 + self.INSPECTOR_W}x{dev_h + 47}")
+ self.root.minsize(520, 560)
+ self.live_var = tk.BooleanVar(master=self.root, value=self.mode_var.get() == "live")
+ self.model_var = tk.StringVar(master=self.root, value=dict((v, k) for k, v in self.MODELS)[self.model])
+ self.system_var = tk.StringVar(master=self.root, value=dict((v, k) for k, v in self.SYSTEMS)[self.system])
+ self.speed_var = tk.StringVar(master=self.root, value=self.SPEEDS[0])
+ self.appearance_var = tk.StringVar(master=self.root, value=self.appearance)
+ self.speed_value = tk.StringVar(master=self.root, value="")
+ self.speed_detail = tk.StringVar(master=self.root, value="Not running")
+ self._app_name = None
+ self._update_subtitle()
+ self._build_menus()
+
+ toolbar = tk.Frame(self.root, bg=PANEL)
+ toolbar.pack(fill="x", side="top")
+ bar = tk.Frame(toolbar, bg=PANEL)
+ bar.pack(fill="x", padx=10, pady=7)
+ self.shot_button = ttk.Button(bar, text="Screenshot", command=self._focus_after(self.screenshot))
+ self.shot_button.pack(side="right", padx=(6, 0))
+ self.reload_button = ttk.Button(bar, text="Restart", command=self._focus_after(self.reset))
+ self.reload_button.pack(side="right", padx=(6, 0))
+ self.pause_button = ttk.Button(bar, text="Pause", command=self._focus_after(self.toggle_pause))
+ self.pause_button.pack(side="right", padx=(6, 0))
+ self.pick_button = ttk.Button(bar, text="Open…", command=self._focus_after(self.open_file))
+ self.pick_button.pack(side="left")
+ tk.Frame(self.root, bg=LINE, height=1).pack(fill="x", side="top")
+
+ body = tk.Frame(self.root, bg=BG)
+ body.pack(fill="both", expand=True)
+ sidebar = tk.Frame(body, bg=PANEL, width=self.INSPECTOR_W)
+ sidebar.pack(side="right", fill="y")
+ sidebar.pack_propagate(False)
+ tk.Frame(body, bg=LINE, width=1).pack(side="right", fill="y")
+ self.canvas = tk.Canvas(body, bg=BG, bd=0, highlightthickness=0, takefocus=1)
+ self.canvas.pack(side="left", fill="both", expand=True)
+ self.screen_label = self.canvas
+ self.canvas.bind("<Configure>", self._resize)
+ self.canvas.bind("<ButtonPress-1>", self._mouse_press)
+ self.canvas.bind("<Motion>", self._mouse_move)
+ self.canvas.bind("<Leave>", self._mouse_leave)
+ self.root.bind("<Configure>", self._schedule_snap, add="+")
+
+ inner = tk.Frame(sidebar, bg=PANEL)
+ inner.pack(fill="both", expand=True, padx=16, pady=(12, 12))
+ wrap = self.INSPECTOR_W - 34
+
+ # Device
+ self._section(inner, "Device", first=True)
+ grid = tk.Frame(inner, bg=PANEL)
+ grid.pack(fill="x")
+ grid.grid_columnconfigure(1, weight=1)
+ for row, (label, var, values, command) in enumerate((
+ ("Model", self.model_var, [k for k, _ in self.MODELS], self._change_model),
+ ("Software", self.system_var, [k for k, _ in self.SYSTEMS], self._change_system),
+ ("Speed", self.speed_var, list(self.SPEEDS), self._change_speed))):
+ tk.Label(grid, text=label, bg=PANEL, fg=FG, font=font(10), anchor="w").grid(
+ row=row, column=0, sticky="w", pady=3)
+ menu = ttk.OptionMenu(grid, var, var.get(), *values, command=lambda _v, c=command: c())
+ menu.grid(row=row, column=1, sticky="e", pady=3)
+
+ # Quick compiled app picker (only files from build/compiled).
+ self._section(inner, "Compiled Games")
+ self._compiled_choice = tk.StringVar(master=self.root, value="NumPlay.nwa")
+ self._compiled_picker = ttk.Combobox(inner, textvariable=self._compiled_choice,
+ state="readonly", width=30)
+ self._compiled_picker.pack(fill="x", pady=(2, 4))
+ self._compiled_picker.bind("<Button-1>", lambda _e: self._refresh_compiled_games())
+ self._refresh_compiled_games()
+ actions = tk.Frame(inner, bg=PANEL)
+ actions.pack(fill="x", pady=(0, 3))
+ ttk.Button(actions, text="Run", command=self._run_compiled_selection).pack(side="left")
+ ttk.Button(actions, text="Build + Run", command=self._build_compiled_selection).pack(side="left", padx=(5, 0))
+
+ # Live Build
+ self._section(inner, "Live Build")
+ ttk.Checkbutton(inner, text="Rebuild and reload when I save", variable=self.live_var,
+ command=self._live_checked).pack(anchor="w")
+ state = tk.Frame(inner, bg=PANEL)
+ state.pack(fill="x", pady=(6, 0))
+ self.build_dot = tk.Canvas(state, width=8, height=8, bg=PANEL, bd=0, highlightthickness=0)
+ self.build_dot.pack(side="left", padx=(1, 7))
+ self.build_dot_item = self.build_dot.create_oval(0, 0, 7, 7, fill=MUTED, outline="")
+ self.build_status_label = tk.Label(state, textvariable=self.build_status, bg=PANEL, fg=FG, font=font(10),
+ anchor="w", justify="left", wraplength=wrap - 16)
+ self.build_status_label.pack(side="left", fill="x")
+ self.build_info = tk.Label(inner, textvariable=self.build_detail, bg=PANEL, fg=MUTED, font=font(8),
+ anchor="w", justify="left", wraplength=wrap)
+ self.build_info.pack(fill="x", pady=(2, 0))
+ self.progress = ttk.Progressbar(inner, mode="indeterminate")
+ self.progress_after = self.build_info
+ log_row = tk.Frame(inner, bg=PANEL)
+ log_row.pack(fill="x", pady=(6, 0))
+ self.build_log_button = ttk.Button(log_row, text="Build Log", command=self._show_build_log)
+ self.build_log_button.pack(side="left")
+
+ # Speed
+ self._section(inner, "Speed")
+ speed = tk.Frame(inner, bg=PANEL)
+ speed.pack(fill="x")
+ tk.Label(speed, textvariable=self.speed_value, bg=PANEL, fg=FG, font=font(18, "bold"),
+ anchor="w").pack(side="left")
+ self.spark = tk.Canvas(speed, width=110, height=28, bg=PANEL, bd=0, highlightthickness=0)
+ self.spark.pack(side="right")
+ tk.Label(inner, textvariable=self.speed_detail, bg=PANEL, fg=MUTED, font=font(8), anchor="w",
+ justify="left", wraplength=wrap).pack(fill="x", pady=(2, 0))
+
+ # Keys Held
+ self._section(inner, "Keys Held")
+ self.chips = tk.Canvas(inner, height=24, bg=PANEL, bd=0, highlightthickness=0)
+ self.chips.pack(fill="x")
+
+ tk.Frame(inner, bg=PANEL).pack(fill="both", expand=True)
+
+ # Calculator: sending the app to a real one, only when asked
+ self._section(inner, "Calculator")
+ self.upload_status_label = tk.Label(inner, textvariable=self.upload_status, bg=PANEL, fg=MUTED,
+ font=font(8), wraplength=wrap, justify="left", anchor="w")
+ self.upload_status_label.pack(fill="x")
+ # (nwlink's own percentage when it gives one, else a bar that only says it is still running)
+ self.upload_progress_panel = tk.Frame(inner, bg=PANEL)
+ self.upload_progress = ttk.Progressbar(self.upload_progress_panel, mode="indeterminate", maximum=100)
+ self.upload_progress.pack(fill="x", pady=(5, 3))
+ tk.Label(self.upload_progress_panel, textvariable=self.upload_elapsed, bg=PANEL, fg=MUTED,
+ font=font(8), anchor="w").pack(fill="x")
+ tk.Label(self.upload_progress_panel, textvariable=self.upload_activity, bg=PANEL, fg=MUTED,
+ font=font(8), anchor="w", justify="left", wraplength=wrap).pack(fill="x", pady=(2, 0))
+ self.upload_button = ttk.Button(inner, text="Install on Calculator…", command=self._push_current_build)
+ self.upload_button.pack(anchor="w", pady=(6, 0))
+
+ tk.Frame(inner, bg=LINE, height=1).pack(fill="x", pady=(12, 8))
+ self.drop_line = tk.Label(inner, textvariable=self.status, bg=PANEL, fg=MUTED, font=font(8),
+ anchor="w", justify="left", wraplength=wrap)
+ self.drop_line.pack(fill="x")
+ self.status.set("Drop a .nwa on the calculator, or choose Open")
+ self._configure_mode_panel()
+ self._update_upload_controls()
+ self._draw_chips()
+ self.root.focus_force()
+ self.root.after(150, self.refocus_input)
+
+ def _build_menus(self):
+ """The menu bar: what the app can do, where a Mac app keeps it."""
+ cmd, mac = self._cmd, self._aqua
+ acc = (lambda keys: keys) if mac else (lambda keys: keys.replace("Command-", "Ctrl+"))
+ bar = tk.Menu(self.root)
+ if mac:
+ app = tk.Menu(bar, name="apple", tearoff=0)
+ app.add_command(label="About NumPlay Simulator",
+ command=lambda: webbrowser.open("https://github.com/Mason363/NumPlay"))
+ bar.add_cascade(menu=app)
+ def bind(seq, action):
+ self.root.bind_all(f"<{cmd}-{seq}>", lambda e: (action(), "break")[1])
+
+ m = tk.Menu(bar, tearoff=0)
+ m.add_command(label="Open App…", accelerator=acc("Command-O"), command=self._focus_after(self.open_file))
+ m.add_command(label="Take Screenshot", accelerator=acc("Command-S"), command=self._focus_after(self.screenshot))
+ m.add_separator()
+ m.add_command(label="Install on Calculator…", accelerator=acc("Command-I"), command=self._push_current_build)
+ m.add_command(label="Show Built Apps", command=self._open_dist)
+ bar.add_cascade(label="File", menu=m)
+ bind("o", self.open_file)
+ bind("s", self.screenshot)
+ bind("i", self._push_current_build)
+
+ m = tk.Menu(bar, tearoff=0)
+ m.add_radiobutton(label="Calculator", variable=self.view_var, value="calculator",
+ accelerator=acc("Command-1"), command=self._switch_view)
+ m.add_radiobutton(label="Screen Only, Actual Size", variable=self.view_var, value="screen",
+ accelerator=acc("Command-2"), command=self._switch_view)
+ m.add_separator()
+ look = tk.Menu(m, tearoff=0)
+ for label, value in (("Like the System", "system"), ("Light", "light"), ("Dark", "dark")):
+ look.add_radiobutton(label=label, variable=self.appearance_var, value=value,
+ command=lambda: self._set_appearance(self.appearance_var.get()))
+ m.add_cascade(label="Appearance", menu=look)
+ m.add_separator()
+ m.add_command(label="Enter Full Screen", accelerator=acc("Command-F"), command=self.toggle_fullscreen)
+ bar.add_cascade(label="View", menu=m)
+ bind("1", lambda: (self.view_var.set("calculator"), self._switch_view()))
+ bind("2", lambda: (self.view_var.set("screen"), self._switch_view()))
+ bind("f", self.toggle_fullscreen)
+
+ m = tk.Menu(bar, tearoff=0)
+ m.add_command(label="Home", accelerator=acc("Shift-Command-H"), command=lambda: self._tap("home"))
+ m.add_command(label="Restart App", accelerator=acc("Command-R"), command=self._focus_after(self.reset))
+ m.add_command(label="Pause or Resume", accelerator=acc("Command-P"), command=self.toggle_pause)
+ m.add_command(label="Turn Off or On", command=self.power_button)
+ m.add_separator()
+ sub = tk.Menu(m, tearoff=0)
+ for label, _ in self.MODELS:
+ sub.add_radiobutton(label=label, variable=self.model_var, value=label, command=self._change_model)
+ m.add_cascade(label="Model", menu=sub)
+ sub = tk.Menu(m, tearoff=0)
+ for label, _ in self.SYSTEMS:
+ sub.add_radiobutton(label=label, variable=self.system_var, value=label, command=self._change_system)
+ m.add_cascade(label="Software", menu=sub)
+ sub = tk.Menu(m, tearoff=0)
+ for label in self.SPEEDS:
+ sub.add_radiobutton(label=label, variable=self.speed_var, value=label, command=self._change_speed)
+ m.add_cascade(label="Speed", menu=sub)
+ bar.add_cascade(label="Device", menu=m)
+ self.root.bind_all(f"<Shift-{cmd}-H>", lambda e: (self._tap("home"), "break")[1])
+ self.root.bind_all(f"<Shift-{cmd}-h>", lambda e: (self._tap("home"), "break")[1])
+ bind("r", self.reset)
+ bind("p", self.toggle_pause)
+
+ m = tk.Menu(bar, tearoff=0)
+ m.add_checkbutton(label="Rebuild and Reload When I Save", variable=self.live_var,
+ accelerator=acc("Command-B"), command=self._live_checked)
+ m.add_command(label="Show Build Log", accelerator=acc("Command-L"), command=self._show_build_log)
+ m.add_command(label="Show USB Log", command=self._show_upload_log)
+ bar.add_cascade(label="Build", menu=m)
+ bind("b", lambda: (self.live_var.set(not self.live_var.get()), self._live_checked()))
+ bind("l", self._show_build_log)
+
+ if mac:
+ bar.add_cascade(menu=tk.Menu(bar, name="window", tearoff=0), label="Window")
+ m = tk.Menu(bar, name="help" if mac else None, tearoff=0)
+ m.add_command(label="Keyboard Shortcuts", command=self.show_keymap)
+ m.add_command(label="Make Your Own Game",
+ command=lambda: webbrowser.open("https://github.com/Mason363/NumPlay/blob/main/docs/make-a-game.md"))
+ m.add_command(label="NumWorks Web Installer", command=lambda: webbrowser.open("https://my.numworks.com/apps"))
+ bar.add_cascade(label="Help", menu=m)
+ self.root.configure(menu=bar)
+ self._menubar = bar
+
+ def _tap(self, key):
+ """A calculator key pressed for a moment (the menus' Home)."""
+ self.on_mouse_down(key)
+ self.root.after(120, self.on_mouse_up)
+
+ def _update_subtitle(self):
+ """The window's title: the app, then the calculator it runs on (as Simulator names its device)."""
+ model = dict((v, k) for k, v in self.MODELS)[self.model]
+ system = dict((v, k) for k, v in self.SYSTEMS)[self.system]
+ device = f"NumWorks {model} · {system}"
+ self.root.title(f"{self._app_name} · {device}" if self._app_name else device)
+
+ def _change_model(self):
+ self.model = dict(self.MODELS)[self.model_var.get()]
+ self._update_subtitle()
+ self._change_speed(quiet=True)
+ self._restart_for_device(f"Now an {self.model_var.get()}")
+
+ def _change_system(self):
+ self.system = dict(self.SYSTEMS)[self.system_var.get()]
+ self._update_subtitle()
+ self._restart_for_device(f"Now running {self.system_var.get()}")
+
+ def _restart_for_device(self, message):
+ if self.current is not None:
+ self.load(self.current)
+ self.set_status(message)
+
+ def _change_speed(self, quiet=False):
+ choice = self.speed_var.get()
+ self.auto_clock[0] = choice == self.SPEEDS[1]
+ if self.auto_clock[0]:
+ # (the adaptive clock was tuned around 216 MHz: it starts there, not with a jump from 550)
+ self.clock_mhz[0] = 216
+ elif choice == self.SPEEDS[0]:
+ self.clock_mhz[0] = 550 if self.model == "n0120" else 216
+ else:
+ self.clock_mhz[0] = int(choice.split()[0])
+ if not quiet:
+ self.set_status("Speed follows this computer, so timing may differ from a calculator"
+ if self.auto_clock[0] else f"The processor runs at {self.clock_mhz[0]} MHz")
+
+ def _live_checked(self):
+ self.mode_var.set("live" if self.live_var.get() else "file")
+ self._switch_mode()
+
+ def _set_appearance(self, choice, *, initial=False):
+ """Light, dark, or the system's: the window, its controls (aqua) and the colours drawn here."""
+ self.appearance = choice
+ if self._aqua:
+ try:
+ self.root.tk.call("::tk::unsupported::MacWindowStyle", "appearance", self.root._w,
+ {"light": "aqua", "dark": "darkaqua"}.get(choice, "auto"))
+ except tk.TclError:
+ pass
+ if not initial:
+ try:
+ _save_setting("theme", choice)
+ except OSError as exc:
+ self.set_status(f"Could not keep the appearance for next time: {exc}")
+ self._follow_appearance()
+
+ def _is_dark(self):
+ if self.appearance in ("light", "dark"):
+ return self.appearance == "dark"
+ if self._aqua:
+ try:
+ return bool(int(self.root.tk.call("::tk::unsupported::MacWindowStyle", "isdark", self.root._w)))
+ except (tk.TclError, ValueError):
+ return False
+ return False
+
+ def _follow_appearance(self):
+ want = "dark" if self._is_dark() else "light"
+ if want != CURRENT_THEME:
+ self._apply_interface_theme(want)
+
+ def _apply_interface_theme(self, requested=None, *, initial=False):
+ """Repaint the Tk widgets in the other palette, without restarting the emulator or the builder."""
+ previous = THEME_PALETTES[CURRENT_THEME]
+ if requested is not None:
+ _activate_theme_palette(requested)
+ updated = THEME_PALETTES[CURRENT_THEME]
+ mapping = {old.lower(): updated[key] for key, old in previous.items()}
+ tk_options = ("background", "foreground", "activebackground", "activeforeground", "selectcolor",
+ "disabledforeground", "highlightbackground", "highlightcolor", "insertbackground",
+ "troughcolor")
+ visited = set()
+
+ def paint(widget):
+ if str(widget) in visited:
+ return
+ visited.add(str(widget))
+ try:
+ options = set(widget.keys())
+ changes = {}
+ for option in tk_options:
+ if option in options:
+ value = str(widget.cget(option)).lower()
+ if value in mapping and mapping[value] != value:
+ changes[option] = mapping[value]
+ if changes:
+ widget.configure(**changes)
+ for child in widget.winfo_children():
+ paint(child)
+ except tk.TclError:
+ pass
+
+ paint(self.root)
+ self.root.configure(bg=BG)
+ if not getattr(self, "_aqua", False):
+ try:
+ style = ttk.Style(self.root)
+ style.theme_use("clam")
+ style.configure(".", background=PANEL, foreground=FG)
+ style.configure("TButton", background=PANEL_2)
+ style.configure("TCheckbutton", background=PANEL, foreground=FG)
+ style.configure("TMenubutton", background=PANEL_2, foreground=FG)
+ style.configure("Horizontal.TProgressbar", background=ACCENT, troughcolor=PANEL_2)
+ except tk.TclError:
+ pass
+ # the calculator's picture on the new background (its edges are see-through), the rest drawn again
+ self.art = self._art_on(BG)
+ self._art_geometry = (0, 0, 0, 0)
+ try:
+ self.build_dot.itemconfigure(self.build_dot_item, fill=self._dot_colour())
+ self._draw_spark()
+ self._draw_chips()
+ self._resize()
+ self.canvas.itemconfigure("native-border", outline=LINE)
+ self._draw_highlight()
+ except (tk.TclError, AttributeError):
+ pass
+
+ def _section(self, parent, title, first=False):
+ if not first:
+ tk.Frame(parent, bg=LINE, height=1).pack(fill="x", pady=(14, 10))
+ label = tk.Label(parent, text=title, bg=PANEL, fg=FG, font=font(10, "bold"), anchor="w")
+ label.pack(fill="x", pady=(0, 6))
+ return label
+
+ def _button(self, parent, label, callback, primary=False):
+ return ttk.Button(parent, text=label, command=self._focus_after(callback))
+
+ def _focus_after(self, action):
+ def call():
+ try:
+ action()
+ finally:
+ self.root.after(75, self.refocus_input)
+ return call
+
+ def _configure_mode_panel(self):
+ live = self.mode_var.get() == "live"
+ self.live_var.set(live)
+ if not live:
+ self._set_build_state("Off", "Opens one .nwa. Turn this on to build NumPlay again each time you save "
+ "a file, and reload it.")
+
+ def _compiled_choices(self):
+ root = REPO_ROOT / "build" / "compiled"
+ return ([root / "NumPlay.nwa"] if (root / "NumPlay.nwa").is_file() else []) + \
+ sorted(p for p in root.glob("NumPlay-*.nwa") if p.is_file()) + \
+ sorted(p for p in (root / "games").glob("*.nwa") if p.is_file())
+
+ def _refresh_compiled_games(self):
+ paths = self._compiled_choices()
+ self._compiled_paths = {str(p.relative_to(REPO_ROOT / "build" / "compiled")): p for p in paths}
+ self._compiled_picker.configure(values=list(self._compiled_paths))
+ if not self._compiled_choice.get() or self._compiled_choice.get() not in self._compiled_paths:
+ if self._compiled_paths:
+ self._compiled_choice.set(next(iter(self._compiled_paths)))
+
+ def _selected_compiled_path(self):
+ return (REPO_ROOT / "build" / "compiled" / self._compiled_choice.get()).resolve()
+
+ def _game_id_for_compiled(self, path):
+ import json
+ if path.parent.name != "games":
+ return None
+ manifest = json.loads((REPO_ROOT / "games" / "games.json").read_text(encoding="utf-8"))
+ for record in manifest:
+ if record.get("app") == path.name:
+ return record["id"]
+ for item in re.finditer(r"(?m)^APP_(\w+)\s*=\s*[^:\n]+:(\S+\.nwa)\s*$",
+ (REPO_ROOT / "Makefile").read_text(encoding="utf-8")):
+ if item.group(2) == path.name:
+ return item.group(1)
+ return None
+
+ def _run_compiled_selection(self):
+ path = self._selected_compiled_path()
+ if not path.is_file():
+ self._set_build_state("Not built yet", "Build the selected app first", error=True)
+ return
+ self.mode_var.set("file")
+ self._switch_mode()
+ self.load(path)
+
+ def _build_compiled_selection(self):
+ self.mode_var.set("live")
+ self.live_var.set(True)
+ self._switch_mode()
+
+ def _switch_mode(self):
+ self._configure_mode_panel()
+ self.watch_candidate = None
+ self.follow_var.set(False)
+ if self.mode_var.get() == "live":
+ self.watch_var.set(True)
+ self._start_builder()
+ else:
+ self.watch_var.set(False)
+ self._stop_builder()
+ self._configure_mode_panel()
+ self._update_upload_controls()
+ self.root.after(75, self.refocus_input)
+
+ def open_file(self):
+ if self.mode_var.get() != "file":
+ self.mode_var.set("file")
+ self._switch_mode()
+ # Calling the existing picker preserves file handling and focus.
+ super().open_file()
+
+ def on_drop(self, event):
+ if self.mode_var.get() != "file":
+ self.mode_var.set("file")
+ self._switch_mode()
+ super().on_drop(event)
+
+ def watch(self):
+ """Never search for a vague newest build or reload single-file mode."""
+ if self._closing:
+ return
+ if (self.mode_var.get() == "live" and self.watch_var.get() and
+ self._builder_ready and self.current == self._selected_compiled_path()):
+ try:
+ self._maybe_reload(self._selected_compiled_path())
+ except OSError as exc:
+ self.build_status.set("Live reload check failed")
+ self.build_detail.set(str(exc)[:140])
+ self._watch_id = self.root.after(WATCH_MS, self.watch)
+
+ def _set_build_state(self, status, detail="", *, busy=False, error=False):
+ self.build_status.set(status)
+ self.build_detail.set(detail)
+ self._build_error = error
+ try:
+ self.build_dot.itemconfigure(self.build_dot_item, fill=self._dot_colour(busy))
+ self.build_status_label.configure(fg=RED if error else FG)
+ except (tk.TclError, AttributeError):
+ pass
+ if busy != self._builder_busy:
+ self._builder_busy = busy
+ if busy:
+ self.progress.pack(fill="x", pady=(6, 0), after=self.progress_after)
+ self.progress.start(11)
+ else:
+ self.progress.stop()
+ self.progress.pack_forget()
+
+ def _dot_colour(self, busy=None):
+ busy = self._builder_busy if busy is None else busy
+ if getattr(self, "_build_error", False):
+ return RED
+ if busy:
+ return ORANGE
+ if self.mode_var.get() == "live" and self.build_process is not None:
+ return GREEN
+ return MUTED
+
+ def _toggle_builder(self):
+ if self.build_process and self.build_process.poll() is None:
+ self._stop_builder()
+ self._set_build_state("Watcher stopped", "Turn Rebuild and reload back on to start again")
+ else:
+ self._start_builder()
+
+ def _start_builder(self):
+ if self._closing or self.mode_var.get() != "live":
+ return
+ 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", 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.
+ if self._builder_stopping:
+ self.root.after(200, self._start_builder)
+ return
+ self._builder_generation += 1
+ generation = self._builder_generation
+ self._builder_ready = False
+ self._builder_has_error = False
+ self._builder_log.clear()
+ self.watch_candidate = None
+ self.watch_var.set(True)
+ selected = self._selected_compiled_path()
+ game_id = self._game_id_for_compiled(selected) if selected else None
+ cmd = [sys.executable, "-u", str(BUILD_SCRIPT), "--watch", "-j2"]
+ if game_id:
+ cmd.extend(["--game", game_id])
+ else:
+ cmd.extend(["--launcher-only", "--skip-languages"])
+ flags = subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
+ try:
+ self.build_process = subprocess.Popen(cmd, cwd=str(REPO_ROOT),
+ stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+ text=True, encoding="utf-8", errors="replace",
+ bufsize=1, creationflags=flags,
+ start_new_session=(os.name != "nt"))
+ except OSError as exc:
+ self._set_build_state("Cannot start compiler", str(exc), error=True)
+ self.build_process = None
+ return
+ 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()
+
+ def _read_builder_output(self, generation, process):
+ """Read compiler output off Tk's thread; never block the calculator UI."""
+ try:
+ if process.stdout is not None:
+ for line in process.stdout:
+ self._builder_events.put((generation, "line", line.rstrip("\r\n")))
+ except (OSError, ValueError) as exc:
+ self._builder_events.put((generation, "line", f"Compiler output error: {exc}"))
+ finally:
+ rc = process.wait()
+ self._builder_events.put((generation, "ended", rc))
+
+ def _stop_builder(self):
+ process = self.build_process
+ self._builder_generation += 1 # Ignore stale lines from a stopped watch.
+ self._builder_ready = False
+ self.watch_var.set(False)
+ self.watch_candidate = None
+ self.build_process = None
+ self._set_build_state("Stopped" if self.mode_var.get() == "live" else "Off",
+ "Not building" if self.mode_var.get() == "live" else self.build_detail.get(), busy=False)
+ if process is None or process.poll() is not None:
+ return
+ self._builder_stopping = True
+ # Start terminating the process tree *before* closing Tk. If shutdown
+ # were deferred entirely to a daemon thread, the Python process could
+ # exit first and leave an orphaned Windows watcher running.
+ try:
+ if os.name == "nt":
+ subprocess.Popen(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+ else:
+ os.killpg(process.pid, signal.SIGTERM)
+ except OSError:
+ try:
+ process.terminate()
+ except OSError:
+ pass
+ def wait_for_stopped():
+ try:
+ process.wait(timeout=7)
+ except subprocess.TimeoutExpired:
+ try:
+ process.kill()
+ process.wait(timeout=2)
+ except (OSError, subprocess.TimeoutExpired):
+ pass
+ finally:
+ self._builder_events.put((None, "stopped", None))
+ threading.Thread(target=wait_for_stopped, daemon=True).start()
+
+ def _poll_builder(self):
+ if self._closing:
+ return
+ count = 0
+ while count < 240:
+ try:
+ generation, kind, value = self._builder_events.get_nowait()
+ except queue.Empty:
+ break
+ count += 1
+ if kind == "stopped":
+ self._builder_stopping = False
+ continue
+ if generation != self._builder_generation:
+ continue
+ if kind == "ended":
+ self.build_process = None
+ self.watch_var.set(False)
+ if value != 0:
+ self._set_build_state("Compiler stopped unexpectedly",
+ f"Exit code {value}. See the Build Log", error=True)
+ else:
+ self._set_build_state("Watcher stopped", "No longer monitoring edits")
+ continue
+ line = value
+ self._builder_log.append(line)
+ self._append_log(line)
+ if "Detected edits (" in line:
+ self._builder_has_error = False
+ self._set_build_state("Changes detected", "Rebuilding NumPlay", busy=True)
+ elif "Building:" in line:
+ self._set_build_state("Compiling NumPlay", "Source files and game modules", busy=True)
+ elif "Preparing temporary Windows nwlink" in line:
+ self._set_build_state("Preparing compiler", "Rust and ARM tools", busy=True)
+ elif "SUCCESS: organized" in line:
+ self._set_build_state("Publishing compiled app", "Finishing the live .nwa", busy=True)
+ elif "Stable live-emulator input:" in line:
+ self._builder_has_error = False
+ self._builder_ready = True
+ self._set_build_state("Built", "Reloading build/compiled/NumPlay.nwa", busy=False)
+ if self.mode_var.get() == "live" and self._selected_compiled_path().is_file():
+ # Emulation runs in its own thread and will stop gracefully
+ # before loading the atomically replaced file.
+ self.load(self._selected_compiled_path())
+ elif ("Build failed;" in line or "Initial build failed" in line or
+ "Windows build failed:" in line):
+ self._builder_has_error = True
+ self._set_build_state("Build failed", "The last good app stays. See the Build Log",
+ busy=False, error=True)
+ elif "Watching for the next edit" in line or "Watching NumPlay source files" in line:
+ if self._builder_has_error:
+ self._set_build_state("Build failed, watching", "Fix and save code to retry",
+ busy=False, error=True)
+ else:
+ self._set_build_state("Watching for changes", "Edit and save a game to rebuild",
+ busy=False)
+ self._update_upload_controls()
+ self._builder_poll_id = self.root.after(120, self._poll_builder)
+
+ def _append_log(self, line):
+ box = self._build_log_text
+ if box is not None:
+ try:
+ box.configure(state="normal")
+ box.insert("end", line + "\n")
+ # Trim long-running logs to avoid unbounded Tk memory usage.
+ if int(box.index("end-1c").split(".")[0]) > 870:
+ box.delete("1.0", "120.0")
+ box.see("end")
+ box.configure(state="disabled")
+ except tk.TclError:
+ self._build_log_text = None
+
+ def _show_build_log(self):
+ if self._build_log_window is not None:
+ try:
+ self._build_log_window.lift()
+ self._build_log_window.focus_set()
+ return
+ except tk.TclError:
+ self._build_log_window = None
+ win = tk.Toplevel(self.root)
+ win.title("Build log")
+ win.geometry("790x480")
+ win.configure(bg=BG)
+ frame = tk.Frame(win, bg=BG)
+ frame.pack(fill="both", expand=True, padx=8, pady=8)
+ scroll = tk.Scrollbar(frame)
+ scroll.pack(side="right", fill="y")
+ box = tk.Text(frame, bg=PANEL, fg=FG, relief="flat", bd=0,
+ font=mono(9), padx=10, pady=10, wrap="none",
+ yscrollcommand=scroll.set)
+ box.pack(side="left", fill="both", expand=True)
+ scroll.configure(command=box.yview)
+ box.insert("end", "\n".join(self._builder_log) or "No compilation output yet.")
+ box.configure(state="disabled")
+ self._build_log_window = win
+ self._build_log_text = box
+ def close():
+ self._build_log_window = None
+ self._build_log_text = None
+ win.destroy()
+ win.protocol("WM_DELETE_WINDOW", close)
+
+ def _open_dist(self):
+ path = REPO_ROOT / "build" / "compiled"
+ path.mkdir(parents=True, exist_ok=True)
+ if os.name == "nt":
+ os.startfile(str(path))
+ elif sys.platform == "darwin":
+ subprocess.Popen(["open", str(path)])
+ else:
+ self.set_status(f"Compiled files: {path}")
+
+ def _upload_source(self):
+ """Choose exactly what the user is looking at, never a random newest app."""
+ if self.mode_var.get() == "live":
+ if self._builder_busy or not self._builder_ready:
+ return None
+ return self._selected_compiled_path()
+ return self.current
+
+ def _update_upload_controls(self):
+ if not hasattr(self, "upload_button"):
+ return
+ source = self._upload_source()
+ available = (not self._upload_running and source is not None
+ and source.is_file() and source.suffix.lower() == ".nwa")
+ self.upload_button.configure(state="normal" if available else "disabled",
+ text="Installing…" if self._upload_running else "Install on Calculator…")
+
+ def _show_upload_log(self):
+ """A small live log for USB details that nwlink prints to stdout."""
+ if self._upload_log_window is not None:
+ try:
+ self._upload_log_window.lift()
+ self._upload_log_window.focus_force()
+ return
+ except tk.TclError:
+ self._upload_log_window = None
+ win = tk.Toplevel(self.root)
+ win.title("USB log")
+ win.geometry("680x350")
+ win.configure(bg=BG)
+ frame = tk.Frame(win, bg=BG)
+ frame.pack(fill="both", expand=True, padx=8, pady=8)
+ scroll = tk.Scrollbar(frame)
+ scroll.pack(side="right", fill="y")
+ box = tk.Text(frame, bg=PANEL, fg=FG, relief="flat", bd=0,
+ font=mono(9), padx=10, pady=10, wrap="word",
+ yscrollcommand=scroll.set)
+ box.pack(side="left", fill="both", expand=True)
+ scroll.configure(command=box.yview)
+ box.insert("end", "\n".join(self._upload_log) or "No USB install activity yet.")
+ box.configure(state="disabled")
+ self._upload_log_window = win
+ self._upload_log_text = box
+
+ def close():
+ self._upload_log_window = None
+ self._upload_log_text = None
+ win.destroy()
+ win.protocol("WM_DELETE_WINDOW", close)
+
+ def _append_upload_log(self, line: str):
+ self._upload_log.append(line)
+ box = self._upload_log_text
+ if box is not None:
+ try:
+ box.configure(state="normal")
+ box.insert("end", line + "\n")
+ box.see("end")
+ box.configure(state="disabled")
+ except tk.TclError:
+ self._upload_log_window = None
+ self._upload_log_text = None
+
+ def _push_current_build(self):
+ """Physical USB install: deliberately NEVER called by the build watcher."""
+ if self._upload_running:
+ return
+ source = self._upload_source()
+ if source is None or not source.is_file() or source.suffix.lower() != ".nwa":
+ messagebox.showwarning("Push to NumWorks", "No finished .nwa is ready.\n\n"
+ "Choose a file or finish a successful Live build first.",
+ parent=self.root)
+ return
+ try:
+ source = source.resolve(strict=True)
+ if source.stat().st_size < 1024:
+ raise ValueError("The .nwa file is unusually small")
+ # Snapshot BEFORE confirmation; a concurrent compiler can publish a
+ # new file without changing the exact bytes chosen for this push.
+ snapshot_dir = tempfile.TemporaryDirectory(prefix="numplay-usb-push-")
+ snapshot = Path(snapshot_dir.name) / source.name
+ shutil.copy2(source, snapshot)
+ except (OSError, ValueError) as exc:
+ try:
+ snapshot_dir.cleanup()
+ except (NameError, OSError):
+ pass
+ messagebox.showerror("Push to NumWorks", f"Cannot prepare .nwa:\n{exc}",
+ parent=self.root)
+ return
+ warning = (
+ f"Send {source.name} ({snapshot.stat().st_size:,} bytes) to your real NumWorks?\n\n"
+ "WARNING: nwlink install-nwa REPLACES the calculator's installed "
+ "third-party applications; it does not just patch NumPlay. "
+ "Saved application data may be affected.\n\n"
+ "Back up important data and keep copies of any other apps you want to reinstall.\n\n"
+ "Connect the calculator with USB and leave it on its CONNECTED screen. "
+ "Close any NumWorks browser tab that is using the USB connection. "
+ "Do NOT unplug the cable until installation finishes.\n\n"
+ "Proceed with this potentially destructive USB installation?"
+ )
+ if not messagebox.askyesno("Confirm calculator installation", warning,
+ icon="warning", parent=self.root, default="no"):
+ snapshot_dir.cleanup()
+ return
+ self._upload_running = True
+ self._upload_start_wall = time.monotonic()
+ self._upload_progress_is_reported = False
+ self._upload_log.clear()
+ self._append_upload_log(f"Installing {source.name} ({snapshot.stat().st_size:,} bytes)")
+ self.upload_status.set("Starting USB installer")
+ self.upload_activity.set("Waiting for nwlink to connect to the calculator")
+ self.upload_elapsed.set("Elapsed: 0 s, Keep USB connected")
+ self.upload_progress.configure(mode="indeterminate")
+ self.upload_progress_panel.pack(fill="x", pady=(2, 7), after=self.upload_status_label)
+ self.upload_progress.start(12)
+ self.set_status("Installing on the calculator. Keep it plugged in")
+ self._update_upload_controls()
+ threading.Thread(target=self._upload_worker,
+ args=(snapshot, snapshot_dir), daemon=True).start()
+
+ def _upload_worker(self, snapshot: Path, snapshot_dir):
+ """Run the installer off Tk's thread, STREAMING its output to the UI.
+
+ nwlink's CLI may suppress numeric progress when stdout isn't a TTY;
+ in that case the UI uses a genuine indeterminate activity bar instead
+ of inventing completion percentages.
+ """
+ try:
+ cmd = [self.nwlink, "install-nwa", str(snapshot)]
+ flags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+ with subprocess.Popen(cmd, cwd=str(REPO_ROOT),
+ stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+ text=True, encoding="utf-8", errors="replace",
+ stdin=subprocess.DEVNULL, creationflags=flags,
+ bufsize=1) as proc:
+ self._upload_events.put(("started", None))
+ if proc.stdout is not None:
+ for raw in proc.stdout:
+ # Strip ANSI sequences and control chars. Progress
+ # tools sometimes redraw a line with CR rather than NL.
+ for part in re.split(r"[\r\n]+", raw):
+ part = re.sub(r"\x1b\[[0-9;]*[A-Za-z]", "", part).strip()
+ if part:
+ self._upload_events.put(("line", part[-450:]))
+ returncode = proc.wait()
+ self._upload_events.put(("done", returncode))
+ except Exception as exc:
+ self._upload_events.put(("error", str(exc)))
+ finally:
+ snapshot_dir.cleanup()
+
+ def _poll_upload(self):
+ if self._closing:
+ return
+ # A clock is honest even if nwlink doesn't print transfer progress.
+ if self._upload_running and self._upload_start_wall is not None:
+ elapsed = int(max(0, time.monotonic() - self._upload_start_wall))
+ self.upload_elapsed.set(f"Elapsed: {elapsed} s, Keep USB connected")
+ while True:
+ try:
+ kind, value = self._upload_events.get_nowait()
+ except queue.Empty:
+ break
+ if kind == "started":
+ self.upload_status.set("USB installer running")
+ self.upload_activity.set("Connecting / transferring, Waiting for nwlink")
+ continue
+ if kind == "line":
+ line = str(value)
+ self._append_upload_log(line)
+ # Honor a real percentage IF nwlink prints one. It describes
+ # the CURRENT CLI operation, not necessarily whole-file upload.
+ match = re.search(r"(?<!\d)(100|[1-9]?\d)(?:\.\d+)?\s*%", line)
+ if match:
+ pct = int(match.group(1))
+ if not self._upload_progress_is_reported:
+ self.upload_progress.stop()
+ self.upload_progress.configure(mode="determinate", value=pct)
+ self._upload_progress_is_reported = True
+ else:
+ self.upload_progress.configure(value=pct)
+ self.upload_activity.set(f"nwlink reports {pct}% for its current operation")
+ else:
+ self.upload_activity.set(f"nwlink: {line[:130]}")
+ continue
+ self._upload_running = False
+ self._upload_start_wall = None
+ self.upload_progress.stop()
+ self.upload_progress_panel.pack_forget()
+ if kind == "done":
+ code = int(value)
+ if code == 0:
+ self.upload_status.set("Installed on the calculator")
+ self.set_status("NumWorks installation reported success")
+ self._append_upload_log("nwlink exited with code 0 (success)")
+ messagebox.showinfo("NumWorks", "nwlink reported a successful upload.\n\n"
+ "Check the calculator for the newly installed app.",
+ parent=self.root)
+ else:
+ self.upload_status.set(f"USB install failed (exit {code})")
+ self._append_upload_log(f"nwlink exited with code {code}")
+ self._upload_failure("\n".join(list(self._upload_log)[-14:]) or
+ f"nwlink exited with code {code}")
+ elif kind == "error":
+ self.upload_status.set("USB install could not start")
+ self._append_upload_log(f"Error: {value}")
+ self._upload_failure(str(value))
+ self._update_upload_controls()
+ self._upload_poll_id = self.root.after(160, self._poll_upload)
+
+ def _upload_failure(self, detail):
+ self.set_status("The install didn't finish. The .nwa is still safe on this computer")
+ msg = ("The USB installer reported a problem:\n\n" + detail[-1700:] +
+ "\n\nCheck the cable and calculator connection. "
+ "The NumWorks website is an alternative.\n\n"
+ "Open https://my.numworks.com/apps now?")
+ if messagebox.askyesno("USB upload failed", msg, parent=self.root):
+ webbrowser.open("https://my.numworks.com/apps")
+
+ def on_close(self):
+ if self._upload_running:
+ messagebox.showwarning("USB installation in progress",
+ "Please let nwlink finish before closing the emulator. "
+ "Do NOT unplug the NumWorks during installation.",
+ parent=self.root)
+ return
+ self._save_window_placement()
+ try:
+ self.root.after_cancel(self._upload_poll_id)
+ except (tk.TclError, AttributeError):
+ pass
+ self._stop_builder()
+ try:
+ self.root.after_cancel(self._builder_poll_id)
+ except (tk.TclError, AttributeError):
+ pass
+ super().on_close()
+
+ def toggle_fullscreen(self):
+ self.fullscreen = not self.fullscreen
+ self.root.attributes("-fullscreen", self.fullscreen)
+ # Force the image to refit after the window manager changes its size.
+ self.root.after(50, self._resize)
+
+ def on_pc_down(self, event):
+ if event.keysym.lower() == "f11":
+ if not self.f11_down:
+ self.f11_down = True
+ self.toggle_fullscreen()
+ return "break"
+ return super().on_pc_down(event)
+
+ def on_pc_up(self, event):
+ if event.keysym.lower() == "f11":
+ self.f11_down = False
+ return "break"
+ return super().on_pc_up(event)
+
+ def change_clock(self, selected):
+ if self.auto_clock[0]:
+ return
+ self.clock_mhz[0] = int(selected.split()[0])
+ self.rate_label.set("Measuring real-time speed")
+ self.set_status(f"Manual CPU clock set to {self.clock_mhz[0]} MHz")
+
+ def _switch_view(self):
+ """Switch the viewport only; the running game/keyboard/build are untouched."""
+ self._hover = None
+ # A held mouse key was pressed on a key that disappears in screen view.
+ # Release it to avoid a stuck calculator button.
+ self.on_mouse_up()
+ self.canvas.configure(cursor="arrow")
+ self._native_geometry = None
+ self._art_geometry = (0, 0, 0, 0)
+ self._canvas_screen = None
+ self._canvas_image = None
+ self._bg_photo = None
+ self.canvas.delete("all")
+ self._resize()
+ self.refocus_input()
+
+ def present_screen(self):
+ self._display_screen()
+
+ def _resize(self, event=None):
+ ww = self.canvas.winfo_width()
+ hh = self.canvas.winfo_height()
+ if ww < 20 or hh < 20:
+ return
+ if self.view_var.get() == "screen":
+ # A native 320x240 LCD. Its bitmap is NEVER resized, even if the
+ # window is larger, smaller, or maximized. Only its position moves.
+ x = (ww - LCD_WIDTH) // 2
+ y = (hh - LCD_HEIGHT) // 2
+ geom = (x, y)
+ if geom != self._native_geometry:
+ self._native_geometry = geom
+ # A one-pixel surround is outside the image; the image itself
+ # contains exactly 320x240 framebuffer pixels.
+ self.canvas.delete("native-border")
+ self.canvas.create_rectangle(x-1, y-1, x+LCD_WIDTH, y+LCD_HEIGHT,
+ outline=LINE, width=1,
+ tags="native-border")
+ self._display_screen()
+ return
+ # the calculator as big as its side of the window holds, edge to edge
+ ratio = self.art_px[0] / self.art_px[1]
+ art_w = max(1, int(min(ww, hh * ratio)))
+ art_h = max(1, int(art_w / ratio))
+ x0 = (ww - art_w) // 2
+ y0 = (hh - art_h) // 2
+ geom = (x0, y0, art_w, art_h)
+ if geom == self._art_geometry:
+ return
+ self._art_geometry = geom
+ self._bg_photo = ImageTk.PhotoImage(self.art.resize((art_w, art_h), Image.Resampling.LANCZOS))
+ self.canvas.delete("all")
+ self._canvas_image = self.canvas.create_image(x0, y0, image=self._bg_photo, anchor="nw", tags="art")
+ self._canvas_screen = None
+ self._sprites.clear()
+ if self._screen_rgb is None:
+ sx, sy, sw, sh = self._rect(SCREEN)
+ self.canvas.create_text(sx + sw // 2, sy + sh // 2, tags="hint", fill="#8e8e93", font=font(10),
+ width=sw - 40, justify="center",
+ text="Drop a .nwa here, or choose Open")
+ self._display_screen()
+ self._draw_highlight()
+
+ def _rect(self, rect):
+ x0, y0, aw, ah = self._art_geometry
+ x, y, w, h = rect
+ return (round(x0 + x * aw), round(y0 + y * ah),
+ max(1, round(w * aw)), max(1, round(h * ah)))
+
+ def _display_screen(self):
+ if self._screen_rgb is None:
+ return
+ if self.view_var.get() == "screen":
+ # No PIL resize (not even NEAREST): one bitmap pixel maps to one
+ # Tk image pixel. The native framebuffer must be exactly 320x240.
+ if self._screen_rgb.size != (LCD_WIDTH, LCD_HEIGHT):
+ raise ValueError(f"Expected 320x240 LCD; got {self._screen_rgb.size}")
+ if self._native_geometry is None:
+ return
+ x, y = self._native_geometry
+ photo = ImageTk.PhotoImage(self._screen_rgb)
+ else:
+ x, y, w, h = self._rect(SCREEN)
+ photo = ImageTk.PhotoImage(self._screen_rgb.resize((w, h), Image.Resampling.NEAREST))
+ self._photo = photo
+ self.canvas.delete("hint")
+ if self._canvas_screen is None or not self.canvas.find_withtag("screen"):
+ self._canvas_screen = self.canvas.create_image(x, y, image=photo, anchor="nw", tags="screen")
+ else:
+ self.canvas.itemconfigure(self._canvas_screen, image=photo)
+ self.canvas.coords(self._canvas_screen, x, y)
+
+ def _key_at(self, x, y) -> str | None:
+ if self.view_var.get() == "screen" or self._art_geometry[2] == 0:
+ return None
+ # A few nav keys' rectangular touch regions overlap: choose the closest
+ # *center* of a containing key, consistent with the visible button art.
+ matched = []
+ for key, bounds in HOTSPOTS.items():
+ bx, by, bw, bh = self._rect(bounds)
+ if bx <= x <= bx + bw and by <= y <= by + bh:
+ center_distance = ((x - bx - bw / 2) / bw) ** 2 + ((y - by - bh / 2) / bh) ** 2
+ matched.append((center_distance, key))
+ return min(matched)[1] if matched else None
+
+ def _sprite(self, key, state, w, h):
+ cache = (key, state, w, h)
+ if cache not in self._sprites:
+ self._sprites[cache] = ImageTk.PhotoImage(key_sprite(key, w, h, state))
+ return self._sprites[cache]
+
+ def _draw_highlight(self):
+ self.canvas.delete("key-light")
+ if self.view_var.get() == "screen" or not self._art_geometry[2]:
+ return
+ held = set(self.pressed_pc.values())
+ if self.mouse_pressed:
+ held.add(self.mouse_pressed)
+ for key in sorted(held):
+ if key in HOTSPOTS:
+ x, y, w, h = self._rect(HOTSPOTS[key])
+ self.canvas.create_image(x, y, image=self._sprite(key, "pressed", w, h), anchor="nw",
+ tags="key-light")
+ if self._hover and self._hover in HOTSPOTS and self._hover not in held:
+ x, y, w, h = self._rect(HOTSPOTS[self._hover])
+ self.canvas.create_image(x, y, image=self._sprite(self._hover, "hover", w, h), anchor="nw",
+ tags="key-light")
+ badge = font(8, "bold")
+ measure = tkfont.Font(root=self.root, font=badge)
+ for sym, key in sorted(self.pressed_pc.items()):
+ if key not in HOTSPOTS:
+ continue
+ x, y, w, h = self._rect(HOTSPOTS[key])
+ text = pc_glyph(sym)
+ tw = measure.measure(text) + 12
+ th = measure.metrics("linespace") + 4
+ cx, top = x + w / 2, y - th - 3
+ round_rect(self.canvas, cx - tw / 2, top, cx + tw / 2, top + th, th / 2, fill="#1d1d1f", outline="",
+ tags="key-light")
+ self.canvas.create_text(cx, top + th / 2, text=text, fill="#ffffff", font=badge, tags="key-light")
+ self.canvas.tag_raise("key-light")
+
+ def _draw_chips(self):
+ """Keys Held: each key down, and the computer key it comes from."""
+ c = self.chips
+ c.delete("all")
+ held = []
+ name = lambda key: KEY_NAMES.get(key, LABEL.get(key, key))
+ for sym, key in sorted(self.pressed_pc.items()):
+ held.append(f"{name(key)} {pc_glyph(sym)}")
+ if self.mouse_pressed and self.mouse_pressed not in self.pressed_pc.values():
+ held.append(name(self.mouse_pressed))
+ if not held:
+ c.create_text(0, 12, text="None", anchor="w", fill=MUTED, font=font(8))
+ return
+ chip = font(8)
+ measure = tkfont.Font(root=self.root, font=chip)
+ x = 1
+ for text in held:
+ w = measure.measure(text) + 16
+ round_rect(c, x, 2, x + w, 22, 6, fill=CHIP, outline=LINE)
+ c.create_text(x + w / 2, 12, text=text, fill=FG, font=chip)
+ x += w + 6
+
+ def _draw_spark(self):
+ c = self.spark
+ c.delete("all")
+ values = list(self._speed_hist)
+ if len(values) < 2:
+ return
+ w, h = int(c.cget("width")), int(c.cget("height"))
+ top = max(1.2, max(values))
+ c.create_line(0, h - 2 - (h - 4) / top, w, h - 2 - (h - 4) / top, fill=LINE, dash=(2, 3))
+ pts = []
+ for i, v in enumerate(values):
+ pts += [w * i / (len(values) - 1), h - 2 - (h - 4) * min(v, top) / top]
+ c.create_line(*pts, fill=ACCENT, width=1.6, smooth=True)
+
+ def _schedule_snap(self, event=None):
+ if event is not None and event.widget is not self.root:
+ return
+ if self._snap_id is not None:
+ self.root.after_cancel(self._snap_id)
+ self._snap_id = self.root.after(300, self._snap_to_device)
+
+ def _snap_to_device(self):
+ """After the window is resized, its width follows the calculator again: no empty space beside it."""
+ self._snap_id = None
+ if self.fullscreen or self.view_var.get() != "calculator":
+ return
+ try:
+ if self.root.state() != "normal":
+ return
+ ch, cw = self.canvas.winfo_height(), self.canvas.winfo_width()
+ except tk.TclError:
+ return
+ if ch < 100:
+ return
+ want = int(ch * self.art_px[0] / self.art_px[1])
+ if abs(cw - want) > 2:
+ self.root.geometry(f"{self.root.winfo_width() - cw + want}x{self.root.winfo_height()}")
+
+ def _mouse_press(self, event):
+ # Crucial on Windows: clicking the calculator after using a sidebar
+ # button must direct the NEXT real keyboard press to the calculator.
+ self.canvas.focus_set()
+ key = self._key_at(event.x, event.y)
+ if key:
+ self.on_mouse_down(key)
+ return "break"
+ return None
+
+ def _mouse_move(self, event):
+ self._hover = self._key_at(event.x, event.y)
+ self.canvas.configure(cursor="hand2" if self._hover else "arrow")
+ self._draw_highlight()
+
+ def _mouse_leave(self, event):
+ self._hover = None
+ self._draw_highlight()
+
+ def refresh_pressed(self):
+ names = set(self.pressed_pc.values())
+ if self.mouse_pressed is not None:
+ names.add(self.mouse_pressed)
+ with self.pressed_lock:
+ self.pressed.clear()
+ self.pressed.update(names)
+ if hasattr(self, "canvas"):
+ self._draw_highlight()
+ self._draw_chips()
+
+ def poll(self):
+ if self._closing:
+ return
+ newest_frame = None
+ last_status = None
+ latest_pace = None
+ ended = None
+ error = None
+ while True:
+ try:
+ m = self.messages.get_nowait()
+ except queue.Empty:
+ break
+ if m[0] == "frame":
+ newest_frame = m
+ elif m[0] == "status":
+ last_status = m[1]
+ elif m[0] == "pace":
+ latest_pace = m
+ elif m[0] == "ended":
+ ended = m[1]
+ elif m[0] == "error":
+ error = m[1]
+ if last_status and not self.powered_off:
+ self.set_status(last_status)
+ if latest_pace and not self.powered_off:
+ _, factor, mhz, auto = latest_pace
+ self.rate_label.set(f"Speed {factor:.2f}x, CPU: {mhz} MHz" +
+ (" (auto)" if auto else " (manual)"))
+ self._speed_hist.append(factor)
+ self.speed_value.set(f"{factor:.2f}×")
+ self.speed_detail.set(f"of the calculator's own speed, with the processor at {mhz} MHz" +
+ (" (following this computer)" if auto else ""))
+ self._draw_spark()
+ if self.current and self._app_name != self.current.stem:
+ self._app_name = self.current.stem
+ self._update_subtitle()
+ if self.appearance == "system" and time.monotonic() - self._look_checked > 1.5:
+ self._look_checked = time.monotonic()
+ self._follow_appearance()
+ if (self.worker is not None and self.worker.is_alive() and
+ not self.powered_off and not self.pause_event.is_set() and
+ time.monotonic() - self._last_frame_wall > 3.0):
+ phase = self.worker.phase
+ age = time.monotonic() - self.worker.phase_since_wall
+ if phase == "running ARM CPU":
+ self.rate_label.set(f"Slow ARM emulation: {age:.1f}s in CPU step")
+ elif phase == "waiting for app sleep":
+ detail = self.worker.last_svc_detail
+ if detail:
+ svc, where, duration = detail
+ self.rate_label.set(f"Pacing {duration:.0f}ms SVC {svc} at 0x{where:x}")
+ else:
+ self.rate_label.set("Waiting for emulated app timing")
+ elif phase == "waiting for emulated time":
+ self.rate_label.set("Pacing virtual clock (not an ARM crash)")
+ else:
+ self.rate_label.set(f"Worker: {phase} ({age:.1f}s)")
+ # If a real .nwa still wedges, this tells us *where*, without
+ # printing private save data or flooding PowerShell each frame.
+ now = time.monotonic()
+ if ((self.profile_speed or (phase == "running ARM CPU" and age >= 3.0))
+ and now - self._last_stall_log_wall > 5.0):
+ self._last_stall_log_wall = now
+ print(f"[NumPlay emulator diagnostic] no frame for "
+ f"{now-self._last_frame_wall:.1f}s; phase={phase}; "
+ f"phase_age={age:.1f}s; virtual_ms={self.worker.last_progress_ms:.0f}; "
+ f"last_cpu_step={self.worker.last_cpu_seconds:.3f}s; "
+ f"last_virtual_step={self.worker.last_virtual_delta:.1f}ms; "
+ f"app_sleep_step={self.worker.last_sleep_delta_ms:.1f}ms; "
+ f"last_svc={self.worker.last_svc_detail}; "
+ f"CPU={self.clock_mhz[0]}MHz; auto={self.auto_clock[0]}",
+ file=sys.stderr, flush=True)
+ if newest_frame and not self.powered_off and not ended:
+ self._last_frame_wall = time.monotonic()
+ _, raw, elapsed = newest_frame
+ try:
+ self._screen_rgb = rgb565_to_photo_bytes(raw)
+ self.present_screen()
+ self.time_label.set(f"{elapsed:,} ms (virtual)")
+ except Exception as exc:
+ self.set_status(f"Display error: {exc}")
+ if ended and not self.powered_off:
+ self.black_screen(ended)
+ elif (self.worker is not None and self.worker.end_reason == "exited"
+ and not self.powered_off):
+ self.black_screen("The app quit. Press On/Off or Restart to start it again")
+ if error and not self.powered_off:
+ self.set_status("The emulator stopped with an error")
+ messagebox.showerror("NumPlay emulator", error)
+ if self.pending is not None and (self.worker is None or not self.worker.is_alive()):
+ self.start_pending()
+ self._poll_id = self.root.after(UI_POLL_MS, self.poll)
+
+
+def main():
+ 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("--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 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")
+ ap.add_argument("--max-sleep-ms", type=int, default=0, metavar="MS",
+ help="EXPERIMENTAL: cap any EADK app sleep to MS milliseconds; "
+ "0 (default) preserves exact emulator behavior")
+ args = ap.parse_args()
+ if args.max_sleep_ms < 0 or args.max_sleep_ms > 10000:
+ ap.error("--max-sleep-ms must be between 0 and 10000")
+ if args.max_sleep_ms:
+ print(f"[NumPlay diagnostic] EXPERIMENTAL sleep guard ON: "
+ f"sleep calls over {args.max_sleep_ms}ms will be shortened. "
+ "Game timing may differ from the calculator.", file=sys.stderr)
+ if not args.nwlink:
+ ap.error("nwlink not found. Run: npm install -g [email protected]")
+ art = CALCULATOR
+ 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.
+ # Call before Tk creates its first window; keep a safe fallback.
+ try:
+ import ctypes
+ ctypes.windll.shcore.SetProcessDpiAwareness(2) # per-monitor aware
+ except (AttributeError, OSError):
+ try:
+ ctypes.windll.user32.SetProcessDPIAware()
+ except (AttributeError, OSError):
+ pass
+ if TkinterDnD:
+ root = TkinterDnD.Tk()
+ else:
+ root = tk.Tk()
+ print("Tip: pip install tkinterdnd2 for .nwa drag-and-drop.")
+ start_live = args.live or args.follow_newest
+ if start_live and args.nwa:
+ print("[NumPlay] --live uses build/compiled/NumPlay.nwa; ignoring the supplied single-file path.")
+ CalculatorSkinApp(root, None if start_live else args.nwa, args.nwlink,
+ args.model, args.system, False, art,
+ max_sleep_ms=args.max_sleep_ms, profile_speed=args.profile_speed,
+ start_live=start_live)
+ root.mainloop()
+
+
+
+
+# Previous headless CLI flags continue to work with this single file.
+def _run_headless_cli():
+ options = ("--ms", "--keys", "--shots", "--gif", "--fps", "--out",
+ "--storage", "--flash-start", "--ram-length", "--records",
+ "--frames", "--profile")
+ return "--headless" in sys.argv or any(arg.split("=", 1)[0] in options for arg in sys.argv[1:])
+
+
+if __name__ == "__main__":
+ if _run_headless_cli():
+ if "--headless" in sys.argv:
+ sys.argv.remove("--headless")
+ emu_cli_main()
+ else:
+ main()
diff --git a/tools/release.py b/tools/release.py
index e1c01922..fa7a1a9d 100644
--- a/tools/release.py
+++ b/tools/release.py
@@ -89,7 +89,7 @@ def main():
ap = argparse.ArgumentParser()
ap.add_argument("--tag", required=True)
ap.add_argument("--notes", required=True)
- ap.add_argument("--build", default="build")
+ ap.add_argument("--build", default="build/compiled")
a = ap.parse_args()
games = json.load(open(os.path.join(ROOT, "games", "games.json")))
apps = standalone_names()
diff --git a/tools/setup.py b/tools/setup.py
index a4b1aa94..a39ecb00 100644
--- a/tools/setup.py
+++ b/tools/setup.py
@@ -12,7 +12,7 @@ What it gets:
- nwlink 1.0.0 (NumWorks' tool that turns a program into a .nwa app), with npm, from Node.js;
- the Python packages of the tools and the emulator (Pillow, NumPy, pyelftools, Unicorn, zopfli).
It needs Python 3.9 or newer and Node.js (https://nodejs.org) already installed, and GNU make (on macOS,
-`xcode-select --install`; on Windows, see tools/build_windows.py). Rust is only needed for Tetris.
+`xcode-select --install`; on Windows, see tools/build.py). Rust is only needed for Tetris.
"""
import argparse
import hashlib
@@ -119,7 +119,7 @@ def main():
[sys.executable, "-c", f"import {m}"], capture_output=True).returncode]
say(not missing, "Python packages (Pillow, NumPy, pyelftools, Unicorn, zopfli)",
f"{sys.executable} -m pip install {' '.join(missing)}")
- say(bool(shutil.which("make")), "GNU make", "macOS: xcode-select --install; Windows: tools/build_windows.py")
+ say(bool(shutil.which("make")), "GNU make", "macOS: xcode-select --install; Windows: tools/build.py")
say(bool(shutil.which("cargo")), "Rust (only for Tetris)", "https://rustup.rs, then: rustup target add "
"thumbv7em-none-eabihf")