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.
C calculatorcalculator-gamescasiochesscrossy-roaddrive-madfx-cg50gamesgeometry-dashgraphing-calculatorndlessnumworksnumworks-appsnumworks-calculatornumworks-gamenumworks-gamestetristi-84-plus-ceti-nspire
change emu and build
Lily Pitiot94522ab65d74
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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@v4with:name: nwapath: |- build/NumPlay*.nwa- build/apps/*.nwa+ build/compiled/NumPlay*.nwa+ build/compiled/games/*.nwa- name: Testrun: |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.nwamake -C games/numblocks host testmake -C games/championisland host testmake -C games/undertale host test@@ -90,9 +90,9 @@ jobs:echo "$tag is already released"exit 0fi- 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.txtgh 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 againgh workflow run pages.yml --ref main || echo "(the site was not deployed again)"diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 325c6c24..f38a82d2 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -25,7 +25,7 @@ git clone https://github.com/Mason363/NumPlay.gitpython3 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.txtBefore 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/Makefileindex f4ac69ac..788df269 100644--- a/Makefile+++ b/Makefile@@ -15,7 +15,7 @@ ARM_LD = arm-none-eabi-ldARM_OBJCOPY = arm-none-eabi-objcopyPY ?= python3CARGO ?= 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 ownAPP_numdash = games/numdash/build/numdash.nwa:NumDash.nwadiff --git a/README.md b/README.mdindex 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.mdindex 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 calculatordiff --git a/tools/build.py b/tools/build.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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.pyindex 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 argparseimport 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")