Skip to content

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

remove old stuff

Lily Pitiot51c02c7d4569
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 660aeecb..e906c08c 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -36,7 +36,7 @@ jobs:
- name: Tools
run: |
- sudo apt-get update -q && sudo apt-get install -yq pngquant
+ sudo apt-get update -q && sudo apt-get install -yq pngquant python3-tk
pip install pillow numpy zopfli pyelftools unicorn==2.1.4
npm install -g [email protected]
rustup target add thumbv7em-none-eabihf
@@ -53,7 +53,7 @@ jobs:
- name: Test
run: |
- python3 tests/test_games.py build/apps
+ python3 tests/test_games.py build/compiled/games
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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f38a82d2..e4bf6488 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,7 +36,7 @@ Then:
| `make lang NWLINK=nwlink` | The French and Chinese versions |
| `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 tests/test_games.py build/compiled/games` | Plays every app in the emulator and checks its saves |
| `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 |
diff --git a/Makefile b/Makefile
index 788df269..3027b363 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,9 @@
# NumPlay: one launcher app with every game, plus each game on its own.
#
-# make build/NumPlay*.nwa and build/apps/*.nwa (the release files)
+# make build/data/NumPlay*.nwa and build/compiled/*.nwa
# make check link the NumPlay apps like the calculator does, print sizes, check RAM
-# make sim build/NumPlay.nwb for the Epsilon simulator
-# make emu run NumPlay.nwa in the ARM emulator (tools/emu.py)
+# make sim build/data/NumPlay.nwb for the Epsilon simulator
+# make emu run NumPlay.nwa in the ARM emulator (tools/emulator.py)
# make clean
#
# Needs arm-none-eabi-gcc (with newlib), Node.js for nwlink, Python 3 with
@@ -305,7 +305,7 @@ $(B)/NumPlay.nwb: $(LAUNCHER_SRC) $(LAUNCHER_H) $(B)/sim/gen/gametable.c $(forea
# ------------------------------------------------------------------ tools
emu: $(B)/NumPlay.nwa
- $(PY) tools/emu.py $< --ms 4000 --shots 3000 --out $(B)/emu
+ $(PY) tools/emulator.py $< --ms 4000 --shots 3000 --out $(B)/emu
clean:
rm -rf $(B)
diff --git a/docs/make-a-game.md b/docs/make-a-game.md
index 8b0a8150..84a30b16 100644
--- a/docs/make-a-game.md
+++ b/docs/make-a-game.md
@@ -87,8 +87,7 @@ And the tools, all in `tools/`:
| --- | --- |
| `setup.py` | Gets the compiler, nwlink and the Python packages |
| `new_game.py` | Starts a game from the template |
-| `emu.py` | Runs a `.nwa` in an emulator: pictures, GIFs, scripted keys, files kept between runs, profiling |
-| `emu_live.py` | The emulator in a window: click the keys or use your keyboard; `--live` rebuilds when you save (`watch.py` on macOS and Linux, `build_windows.py` on Windows) |
+| `emulator.py` | NumWorks emulator with a graphical calculator, live rebuilds and a `--headless` mode for scripted keys, frames, screenshots and profiling |
| `icon.py` | Makes the 55 x 56 app icon from any picture, with the rounded corners every NumPlay icon has |
| `record.py` | Makes GIFs from the emulator's frames |
| `sizes.py` | How much flash and RAM each game takes inside NumPlay |
diff --git a/games/championisland/Makefile b/games/championisland/Makefile
index 8ea5b1d6..37e9bc57 100644
--- a/games/championisland/Makefile
+++ b/games/championisland/Makefile
@@ -7,7 +7,7 @@
Q ?= @
CC = arm-none-eabi-gcc
NWLINK ?= npx --yes -- [email protected]
-STRIP ?= arm-none-eabi-strip --strip-unneeded # STRIP=true keeps symbols (tools/emu.py --profile)
+STRIP ?= arm-none-eabi-strip --strip-unneeded # STRIP=true keeps symbols (tools/emulator.py --profile)
BUILD_DIR = output
DOODLE ?= ../../../potherca-blog/google-doodle-champion-island
GAME = $(HOT) $(COLD)
diff --git a/games/doom/tools/fps.py b/games/doom/tools/fps.py
index 3cf68e05..7a796d36 100644
--- a/games/doom/tools/fps.py
+++ b/games/doom/tools/fps.py
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
"""fps.py [--maps 11,12,...] [--low] [--out FILE]: the frame rate in every level, measured in the emulator
-(tools/emu.py, with the calculator's 133652 bytes of RAM). A build that starts in the level and draws it from
+(tools/emulator.py, with the calculator's 133652 bytes of RAM). A build that starts in the level and draws it from
all over (src/nw/scan.c: the middle of each subsector, looking 8 ways round, monsters awake) is run until every
view has been drawn, and the time of each frame is noted: its instructions (each frame's game tics, drawing and
sending to the display) and 40 ns for each pixel sent.
@@ -19,7 +19,7 @@ import sys
HERE = os.path.dirname(os.path.abspath(__file__))
GAME = os.path.dirname(HERE)
sys.path.insert(0, os.path.join(GAME, "..", "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
ap = argparse.ArgumentParser()
ap.add_argument("--maps", default="11,12,13,14,15,16,17,18,19")
diff --git a/games/doom/tools/panel.py b/games/doom/tools/panel.py
index 41214f0c..54557a91 100644
--- a/games/doom/tools/panel.py
+++ b/games/doom/tools/panel.py
@@ -1,6 +1,6 @@
#!/usr/bin/env python3
"""panel.py NWA [--model n0120|n0110] [--hz 40] [--dir ltr|rtl] [--from MS] [--ms MS] [--keys SPEC] [--out DIR]:
-Doom in the emulator (tools/emu.py) with the calculator's display panel as it refreshes itself: every 1/hz s, after
+Doom in the emulator (tools/emulator.py) with the calculator's display panel as it refreshes itself: every 1/hz s, after
its blanking time, it goes over its memory a column at a time (left to right, or right to left), and
eadk_display_wait_for_vblank waits for the blanking time. Each refresh's picture is compared with the frames the app
sent: a refresh that shows parts of two frames is torn (its picture is saved in DIR, the first few).
@@ -15,7 +15,7 @@ import sys
import numpy as np
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
ap = argparse.ArgumentParser()
ap.add_argument("nwa")
diff --git a/games/numblocks/tests/gen/arm/bench.py b/games/numblocks/tests/gen/arm/bench.py
index 315697fe..d6ec57f8 100644
--- a/games/numblocks/tests/gen/arm/bench.py
+++ b/games/numblocks/tests/gen/arm/bench.py
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Builds bench.c + gen.c for the Cortex-M7 (-Os, hard float) and runs it in Unicorn,
counting instructions per gen_slab call (1 instruction ~ 1 cycle at 216 MHz, the same
-convention as tools/emu.py) in the game's calling pattern (see bench.c). Also reports the
+convention as tools/emulator.py) in the game's calling pattern (see bench.c). Also reports the
deepest stack use (painted stack) and gen.c's own static RAM.
Usage: bench.py [OUTDIR] [--no-spawn] [--profile] [--lines FUNC,...] [--y0 N] [--h N] [--seed S] [--ox CX] [--oz CZ]
[--game-flags]"""
diff --git a/games/twoplayer/tools/bot.py b/games/twoplayer/tools/bot.py
index 95501b2b..aa0635a4 100644
--- a/games/twoplayer/tools/bot.py
+++ b/games/twoplayer/tools/bot.py
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Plays 2 Players in the ARM emulator for the README's pictures.
-Runs the calculator build (TwoPlayers.nwa) in tools/emu.py as player 1 against the hard computer,
+Runs the calculator build (TwoPlayers.nwa) in tools/emulator.py as player 1 against the hard computer,
game after game: it reads the screen (the ball, the puck, the tanks, the light cycles) and presses
the keys a player would. Saves the raw frames, then the gallery's GIF (a few seconds of each game)
and a screenshot of each game.
@@ -17,7 +17,7 @@ import numpy as np
HERE = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, os.path.join(HERE, "..", "..", "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
import record # noqa: E402
K = emu.KEYS
diff --git a/tests/test_games.py b/tests/test_games.py
index a5957003..3a9ad563 100644
--- a/tests/test_games.py
+++ b/tests/test_games.py
@@ -11,7 +11,7 @@ what used to crash calculators or lose saves:
untouched, and a file added after the save does not stop the game from
updating it on the second run.
-Usage: test_games.py build/apps [--game NAME] [--out DIR]
+Usage: test_games.py build/compiled/games [--game NAME] [--out DIR]
"""
import argparse
import json
@@ -21,7 +21,7 @@ import sys
import tempfile
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
K = emu.KEYS
diff --git a/tests/test_numblocks_progress.py b/tests/test_numblocks_progress.py
index 548c60bd..7f5aca9a 100644
--- a/tests/test_numblocks_progress.py
+++ b/tests/test_numblocks_progress.py
@@ -11,7 +11,7 @@ numblocks_saves.py. In the ARM emulator:
2. "install again" (every file but the scripts deleted): started again, the
saves come back byte for byte and the other script is untouched.
-Usage: test_numblocks_progress.py build/apps/NumBlocks.nwa [--out DIR]
+Usage: test_numblocks_progress.py build/compiled/games/NumBlocks.nwa [--out DIR]
"""
import argparse
import base64
diff --git a/tests/test_progress.py b/tests/test_progress.py
index 2e5a6eb3..95640e7e 100644
--- a/tests/test_progress.py
+++ b/tests/test_progress.py
@@ -13,7 +13,7 @@ numplay_saves.py. In the ARM emulator:
4. holding OK resets the game, and the copy follows: after another update,
the game starts over while the others keep their progress.
-Usage: test_progress.py build/NumPlay.nwa [--out DIR]
+Usage: test_progress.py build/compiled/NumPlay.nwa [--out DIR]
"""
import argparse
import base64
@@ -25,7 +25,7 @@ import sys
import tempfile
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
K = emu.KEYS
COPY = "numplay_saves.py"
diff --git a/tests/test_small_ram.py b/tests/test_small_ram.py
index 40cebeab..82edaa56 100644
--- a/tests/test_small_ram.py
+++ b/tests/test_small_ram.py
@@ -1,12 +1,12 @@
#!/usr/bin/env python3
-"""Checks NumPlay on calculator software that gives apps less RAM (tools/emu.py --ram-length). NumPlay installs
+"""Checks NumPlay on calculator software that gives apps less RAM (tools/emulator.py --ram-length). NumPlay installs
with less, and its games use the RAM after it up to the end of what there is (tools/gen_games.py):
1. custom builds of Epsilon 25.2 give apps 133652 bytes: NumBlocks, the hungriest game, starts there;
2. with 120000 bytes, NumBlocks doesn't fit: OK on its card doesn't start it (the card says how much it lacks),
while NumDash, which fits, starts and makes no access outside the app's RAM.
-Usage: test_small_ram.py build/NumPlay.nwa [--out DIR]
+Usage: test_small_ram.py build/compiled/NumPlay.nwa [--out DIR]
"""
import argparse
import os
@@ -14,7 +14,7 @@ import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tools"))
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
from test_progress import presses, write_storage # noqa: E402
diff --git a/tests/test_uninstall.py b/tests/test_uninstall.py
index a2db0a05..91428b14 100644
--- a/tests/test_uninstall.py
+++ b/tests/test_uninstall.py
@@ -9,7 +9,7 @@ what happened to the flash and to the calculator's files.
record lookup cache no longer points into moved data;
- relaunching NumPlay shows the game gone and does not touch the flash again.
-Usage: test_uninstall.py build/NumPlay.nwa [--out DIR]
+Usage: test_uninstall.py build/compiled/NumPlay.nwa [--out DIR]
"""
import argparse
import json
@@ -18,7 +18,7 @@ import struct
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tools"))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
SECTOR = 0x10000
diff --git a/tests/test_upsilon.py b/tests/test_upsilon.py
index 1f50e330..0823c887 100644
--- a/tests/test_upsilon.py
+++ b/tests/test_upsilon.py
@@ -1,5 +1,5 @@
#!/usr/bin/env python3
-"""Checks NumPlay-Upsilon.nwa on an emulated N0110 running Upsilon (tools/emu.py --system upsilon):
+"""Checks NumPlay-Upsilon.nwa on an emulated N0110 running Upsilon (tools/emulator.py --system upsilon):
1. it makes no system call Upsilon doesn't have (Home, checksums, flash);
2. it finds the file system there: a save already on the calculator goes into its copy,
@@ -8,7 +8,7 @@
there, launcher/src/compat.c);
4. Home quits.
-Usage: test_upsilon.py build/NumPlay-Upsilon.nwa [--out DIR]
+Usage: test_upsilon.py build/compiled/NumPlay-Upsilon.nwa [--out DIR]
"""
import argparse
import os
@@ -16,7 +16,7 @@ import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "tools"))
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
emu.configure("n0110", "upsilon")
from test_progress import copy_lines, presses, records, write_storage # noqa: E402
diff --git a/tools/build.py b/tools/build.py
index 31f31c6a..103018ef 100644
--- a/tools/build.py
+++ b/tools/build.py
@@ -1,14 +1,14 @@
#!/usr/bin/env python3
-"""Build NumPlay .nwa files on native Windows (no WSL/Linux required).
+"""Build NumPlay .nwa files on Windows, macOS and Linux.
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
+Run from PowerShell (Windows) or a terminal (macOS/Linux):
+ python tools/build.py --doctor
+ python tools/build.py --launcher-only --skip-languages -j2
+ python tools/build.py --organize-only
+ python tools/build.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
@@ -293,10 +293,10 @@ def doctor() -> bool:
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(" GNU Make 4.4.1: python tools/build.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(" ARM compiler: python tools/build.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")
@@ -500,7 +500,7 @@ command -v nwlink >/dev/null || { echo 'Tetris nwlink bridge is unavailable from
# 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.
+# The stable live path can later be supplied to emulator.py for auto-reload.
LIVE_DIR = "live"
VARIANT_DIR = "variants"
GAME_DIR = "games"
diff --git a/tools/build_windows.py b/tools/build_windows.py
deleted file mode 100644
index ae5dec32..00000000
--- a/tools/build_windows.py
+++ /dev/null
@@ -1,829 +0,0 @@
-#!/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 dist/, including the stable
-live-emulator input dist/live/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 / "dist"
-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" 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) -> 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)")
-
- 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 / LANGUAGE_DIR / name
- if name.startswith("NumPlay-") and name.endswith(".nwa"):
- return output / VARIANT_DIR / 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"
- # Never include existing dist/ 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 main_src is not None:
- live = output / LIVE_DIR / "NumPlay.nwa"
- atomic_copy(main_src, live)
- published.append(live)
- 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 / LIVE_DIR / "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 dist/. 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 dist/live/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 dist/live/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)
-
-
-def main() -> int:
- ap = argparse.ArgumentParser(description="Build NumPlay .nwa apps on native Windows (no WSL).")
- ap.add_argument("--doctor", action="store_true", help="check prerequisites, don't build")
- ap.add_argument("--install-arm", action="store_true", help="download/verify official Windows ARM GCC")
- ap.add_argument("--install-make", action="store_true", help="download/verify portable Windows GNU Make 4.4.1")
- ap.add_argument("--make-zip", type=Path, metavar="ZIP", help="with --install-make, use a manually downloaded ZIP if SourceForge blocks Python")
- ap.add_argument("--launcher-only", action="store_true", help="build only combined NumPlay variants")
- ap.add_argument("--skip-check", action="store_true", help="skip linker/RAM checks")
- ap.add_argument("--skip-languages", action="store_true", help="skip French/Chinese variants")
- ap.add_argument("--organize-only", action="store_true", help="organize existing build outputs into dist/ without compiling")
- ap.add_argument("--tidy-legacy", action="store_true", help="remove only verified duplicate .nwa files in build/windows-nwa/")
- ap.add_argument("--watch", action="store_true", help="rebuild when source files change (Ctrl+C to stop)")
- ap.add_argument("--watch-interval", type=float, default=1.0,
- help="seconds between source scans in watch mode (default 1.0)")
- ap.add_argument("-j", "--jobs", type=int, default=4, help="parallel make jobs (default 4)")
- a = ap.parse_args()
- rust_bin = ensure_rust_on_path()
- if rust_bin:
- print(f"Found installed Rust at {rust_bin}; using it for this command "
- "(no permanent PATH changes).", flush=True)
- if a.jobs < 1 or a.jobs > 32:
- ap.error("--jobs must be between 1 and 32")
- if a.make_zip and not a.install_make:
- ap.error("--make-zip requires --install-make")
- if a.watch_interval <= 0:
- ap.error("--watch-interval must be positive")
- if a.watch and (a.organize_only or a.doctor or a.install_arm or a.install_make):
- ap.error("--watch requires a normal build, not --doctor / --organize-only / installation")
- if a.install_make:
- try:
- install_make(a.make_zip)
- except (OSError, RuntimeError, zipfile.BadZipFile, urllib.error.URLError) as exc:
- print("GNU Make installation failed:", exc, file=sys.stderr)
- return 1
- if not a.doctor and not a.install_arm:
- print("Next: python tools/build_windows.py --doctor")
- return 0
- if a.install_arm:
- try:
- install_arm()
- except (OSError, RuntimeError, zipfile.BadZipFile) as exc:
- print("Compiler installation failed:", exc, file=sys.stderr)
- return 1
- if not a.doctor:
- print("Next: python tools/build_windows.py --doctor")
- return 0
- if a.doctor:
- return 0 if doctor() else 1
- if a.organize_only:
- try:
- publish_outputs(apps=True, langs=True)
- if a.tidy_legacy:
- safe_remove_legacy_duplicates()
- return 0
- except (OSError, RuntimeError) as exc:
- print("Could not organize build outputs:", exc, file=sys.stderr)
- return 1
- if not doctor():
- return 1
- make, make_name = find_make()
- assert make and make_name and make_supported(make)
- bash, arm = git_bash(), find_arm()
- assert bash and arm
-
- def build_once():
- run_bash(bash, make, make_name, arm, a.jobs,
- apps=not a.launcher_only,
- check=not a.launcher_only and not a.skip_check,
- langs=not a.skip_languages)
- publish_outputs(apps=not a.launcher_only, langs=not a.skip_languages)
- if a.tidy_legacy:
- safe_remove_legacy_duplicates()
-
- if a.watch:
- try:
- # Initial build then repeat on changes; failed initial build doesn't
- # stop observation, and existing exports remain intact.
- try:
- build_once()
- except (OSError, RuntimeError) as exc:
- print("\nInitial build failed; old exported files were kept:", exc,
- file=sys.stderr, flush=True)
- run_watch(build_once, interval=a.watch_interval)
- except KeyboardInterrupt:
- print("\nStopped watching. Compiled files remain in dist/.")
- return 0
- try:
- build_once()
- return 0
- except (OSError, RuntimeError) as exc:
- print("\nWindows build failed:", exc, file=sys.stderr)
- print("The original source files and your emulator have not been modified.", file=sys.stderr)
- return 1
-
-
-if __name__ == "__main__":
- raise SystemExit(main())
diff --git a/tools/emu.py b/tools/emu.py
deleted file mode 100644
index 7bab5af3..00000000
--- a/tools/emu.py
+++ /dev/null
@@ -1,630 +0,0 @@
-#!/usr/bin/env python3
-"""Run a calculator build of an app (.nwa) in the Unicorn CPU emulator.
-
-The .nwa is linked by nwlink exactly as the calculator's installer does, at a
-realistic address, and the resulting Cortex-M7 code runs here with the
-calculator's system calls (SVC) serviced in Python:
-
-- display: a 320x240 RGB565 frame buffer, saved as PNG frames on request;
-- keyboard: keys held over scripted time ranges;
-- time: a virtual clock driven by executed instructions and msleep;
-- flash: sector erase and programming follow NOR rules (erase sets 0xFF,
- programming can only clear bits), so NumPlay's uninstaller runs for real;
-- storage: an Epsilon record file system in RAM, found by apps through the
- userland header, optionally loaded from and saved to a file.
-
-Usage:
- emu.py app.nwa --ms 5000 --keys "500-600:ok,1000-1100:right" \
- --shots 900,2000 --gif 0-5000 --out DIR
-"""
-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 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())
-
-
-if __name__ == "__main__":
- main()
diff --git a/tools/emu_live.py b/tools/emu_live.py
deleted file mode 100644
index 5f693d02..00000000
--- a/tools/emu_live.py
+++ /dev/null
@@ -1,3064 +0,0 @@
-#!/usr/bin/env python3
-"""Live NumWorks emulator for macOS, Linux and Windows: a calculator you can click, around tools/emu.py.
-
-Put this file beside tools/emu.py. Requires Pillow, numpy, unicorn,
-pyelftools and nwlink (tkinterdnd2 for dropping files, if you like). It shows a
-picture of the NumWorks N0120 (emu_live_calculator.webp, beside this file), with the
-screen and every key where they are on it.
-
-Runs an ARM .nwa through the project's existing emu.Calculator, shows the
-320x240 display, supports 46 clickable keys, keyboard, .nwa drops and reload.
-
-To run:
- python tools/emu_live.py path/to/NumPlay.nwa
-
-The calculator skin does not depend on emu_live_skin.py; emu.py is still needed.
-
-What it does:
-- Single file / Live development: it builds again when you save, and reloads
- (tools/watch.py on macOS and Linux, tools/build_windows.py on Windows);
-- calculator skin / pixel-exact 320x240 screen, keyboard highlights;
-- tear-reduced frame presentation, usable Epsilon firmware text;
-- N0120 display-transfer timings calibrated using physical NumWorks results;
-- fixed 550 MHz N0120 / 216 MHz older-model baseline (approximate timing);
-- optional host-adaptive clock and opt-in speed diagnostics;
-- manual confirmed USB upload with a live progress bar and USB activity log;
-- installer percentages are shown only when nwlink actually reports them.
-
-This is not a cycle-accurate Cortex-M7 emulator: demanding NumDrive scenes can
-still be host-CPU-limited. This release excludes the experimental SRAM hooks and
-LCD scanout simulation. Saves and crash logs remain outside build/ and dist/.
-"""
-from __future__ import annotations
-
-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
-
-# emu.py is a sibling file when installed in the repository's tools folder.
-try:
- import emu
-except ImportError as exc:
- raise SystemExit("Put emu_live.py inside NumPlay/tools/, beside emu.py. "
- f"Import failed: {exc}") from exc
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-HOME_NWA = Path.home() / "Downloads" / "nwa"
-SAVE_DIR = Path.home() / ".numplay-emulator" / "saves"
-LIVE_NWA = REPO_ROOT / "dist" / "live" / "NumPlay.nwa"
-BUILD_SCRIPT = REPO_ROOT / "tools" / ("build_windows.py" if os.name == "nt" else "watch.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 / "dist" / "live" / "*.nwa",
- REPO_ROOT / "dist" / "*.nwa",
- REPO_ROOT / "dist" / "games" / "*.nwa",
- REPO_ROOT / "dist" / "variants" / "*.nwa",
- REPO_ROOT / "dist" / "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" / "emu-live"
- 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)
-
- # 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 _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 == LIVE_NWA):
- try:
- self._maybe_reload(LIVE_NWA)
- 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)
- cmd = [sys.executable, "-u", str(BUILD_SCRIPT), "--watch",
- "--launcher-only", "--skip-languages", "-j2"]
- 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 dist/live/NumPlay.nwa", busy=False)
- if self.mode_var.get() == "live" and LIVE_NWA.is_file():
- # Emulation runs in its own thread and will stop gracefully
- # before loading the atomically replaced file.
- self.load(LIVE_NWA)
- 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 / "dist"
- 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 LIVE_NWA
- 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 dist/live/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()
-
-
-if __name__ == "__main__":
- main()
diff --git a/tools/emulator.py b/tools/emulator.py
index 7de36a85..2f7d2fa7 100644
--- a/tools/emulator.py
+++ b/tools/emulator.py
@@ -1,7 +1,7 @@
# NumPlay emulator: GUI and headless backend in one file.
from __future__ import annotations
-# -------- ARM backend (formerly emu.py) --------
+# -------- ARM backend (formerly emulator.py) --------
import argparse
import os
import struct
@@ -645,7 +645,7 @@ except ImportError:
DND_FILES = None
TkinterDnD = None
-# The old emu.py backend is inlined above, preserving its separate API.
+# The old emulator.py backend is inlined above, preserving its separate API.
class _BackendNamespace:
def __getattr__(self, key):
try:
@@ -959,7 +959,7 @@ class FidelityFont:
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*
+ In emulator.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
@@ -1234,14 +1234,14 @@ class TracedCalculator(emu.Calculator):
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
+ # emulator.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,
+ # emulator.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().
diff --git a/tools/media/tetris_bot.py b/tools/media/tetris_bot.py
index 089e88e6..abf5682b 100644
--- a/tools/media/tetris_bot.py
+++ b/tools/media/tetris_bot.py
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Plays Tetris in the ARM emulator for the README's GIF.
-Runs the real calculator build (Tetris.nwa) in tools/emu.py, reads the board
+Runs the real calculator build (Tetris.nwa) in tools/emulator.py, reads the board
and the NEXT panel from the screen, and places each piece with a classic
heuristic (few holes, low and flat stack, clear lines). Saves raw frames that
tools/record.py turns into a GIF.
@@ -14,7 +14,7 @@ import struct
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
-import emu # noqa: E402
+import emulator as emu # noqa: E402
FIELD_X, FIELD_Y, CELL, W, H = 100, 0, 12, 10, 20
# tile colours (centre pixel, RGB565) -> piece types, as in tetriminos.rs
diff --git a/tools/new_game.py b/tools/new_game.py
index 3c9fa58f..fc545f6c 100644
--- a/tools/new_game.py
+++ b/tools/new_game.py
@@ -7,7 +7,7 @@ already draws, reads the keys, pauses, saves and quits the way NumPlay's games d
python3 tools/new_game.py "My Game" --numplay also on NumPlay's home screen (games/games.json)
Then: make -C games/mygame output/mygame.nwa, ready to install
- python3 tools/emu.py games/mygame/output/mygame.nwa --ms 5000 --shots 2000 --out /tmp/shots
+ python3 tools/emulator.py games/mygame/output/mygame.nwa --ms 5000 --shots 2000 --out /tmp/shots
See docs/make-a-game.md for the whole guide. Works on macOS, Linux and Windows (Python 3 and Pillow).
"""
import argparse
@@ -57,12 +57,12 @@ def main():
open(p, "w", encoding="utf-8").write(json.dumps(games, indent=2, ensure_ascii=False) + "\n")
os.makedirs(os.path.join(dest, "docs"), exist_ok=True)
print(f"Added to games/games.json. NumPlay's card needs games/{gid}/docs/shot.png (320x240): take one with\n"
- f" python3 tools/emu.py games/{gid}/output/{gid}.nwa --ms 4000 --keys 1500-1600:ok --shots 3000 "
+ f" python3 tools/emulator.py games/{gid}/output/{gid}.nwa --ms 4000 --keys 1500-1600:ok --shots 3000 "
f"--out games/{gid}/docs\n and rename it shot.png.")
print(f"games/{gid}/ is ready: its game is in games/{gid}/src/main.c, its icon in src/icon.png "
f"(tools/icon.py makes one from any picture).\n"
f" make -C games/{gid} builds output/{gid}.nwa\n"
- f" python3 tools/emu.py games/{gid}/output/{gid}.nwa --ms 5000 --keys 1500-1600:ok --shots 3000 --out shots\n"
+ f" python3 tools/emulator.py games/{gid}/output/{gid}.nwa --ms 5000 --keys 1500-1600:ok --shots 3000 --out shots\n"
f"Install the .nwa from https://my.numworks.com/apps with the calculator plugged in.")
diff --git a/tools/record.py b/tools/record.py
index b247160c..105f4f83 100644
--- a/tools/record.py
+++ b/tools/record.py
@@ -6,7 +6,7 @@ screen as it runs (see launcher/sim/sim.c); this turns the frames into PNG
screenshots and GIFs.
Usage:
- record.py --simulator PATH/Epsilon --nwb build/NumPlay.nwb \
+ record.py --simulator PATH/Epsilon --nwb build/data/NumPlay.nwb \
--keys "1500-1600:right,3000:ok" --out docs/raw \
[--png 1200:home.png,3400:game.png] [--gif 500-4000:carousel.gif] [--fps 30] [--scale 2]
"""
@@ -81,9 +81,9 @@ def save_gif(frames, path, scale, fps):
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--simulator", default=os.environ.get("EPSILON"))
- ap.add_argument("--nwb", default="build/NumPlay.nwb")
+ ap.add_argument("--nwb", default="build/data/NumPlay.nwb")
ap.add_argument("--keys", help="scripted keys for the simulator")
- ap.add_argument("--frames", help="use raw frames already recorded (tools/emu.py, tools/media) instead")
+ ap.add_argument("--frames", help="use raw frames already recorded (tools/emulator.py, tools/media) instead")
ap.add_argument("--end", type=int, default=0)
ap.add_argument("--fps", type=int, default=30)
ap.add_argument("--out", required=True)
diff --git a/tools/watch.py b/tools/watch.py
deleted file mode 100644
index 46c19a61..00000000
--- a/tools/watch.py
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/usr/bin/env python3
-"""Builds NumPlay (or one game) again each time a source file is saved, for the live emulator on macOS and Linux
-(tools/emu_live.py --live; on Windows it uses tools/build_windows.py). Each good build is copied to
-dist/live/NumPlay.nwa in one step, so the emulator never reads half a file; a failed build keeps the last good one.
-
- python3 tools/watch.py NumPlay (build/NumPlay.nwa)
- python3 tools/watch.py --game sokoban one game on its own (games/sokoban's Makefile)
- python3 tools/watch.py --once build once and stop
-
-Needs what `make` needs (python3 tools/setup.py gets it). It prints the lines the live emulator follows:
-"Detected edits (...)", "Building: ...", "Stable live-emulator input: ...", "Build failed; ...",
-"Watching for the next edit".
-"""
-import argparse
-import os
-import shutil
-import subprocess
-import sys
-import time
-
-ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-LIVE = os.path.join(ROOT, "dist", "live", "NumPlay.nwa")
-WATCHED = (".c", ".h", ".S", ".s", ".rs", ".py", ".json", ".txt", ".png", ".inc", "Makefile")
-SKIP = {"build", "output", "dist", "node_modules", "target", ".git", "__pycache__"}
-
-
-def stamp(folders):
- """The newest change time among the sources, and how many there are."""
- newest, n = 0.0, 0
- for top in folders:
- for d, dirs, files in os.walk(top):
- dirs[:] = [x for x in dirs if x not in SKIP]
- for f in files:
- if f.endswith(WATCHED):
- try:
- newest = max(newest, os.stat(os.path.join(d, f)).st_mtime)
- n += 1
- except OSError:
- pass
- return newest, n
-
-
-def nwlink():
- for p in (shutil.which("nwlink"), os.path.join(os.path.expanduser("~"), ".numplay", "node_modules", ".bin", "nwlink"),
- os.path.join(ROOT, "games", "numdash", "node_modules", ".bin", "nwlink")):
- if p and os.path.exists(p):
- return p
- return "npx --yes -- [email protected]"
-
-
-def build(game, jobs):
- if game:
- target = ["make", "-C", os.path.join(ROOT, "games", game), "-j%d" % jobs, "NWLINK=" + nwlink()]
- out = None
- else:
- target = ["make", "-C", ROOT, "-j%d" % jobs, "build/NumPlay.nwa", "NWLINK=" + nwlink()]
- out = os.path.join(ROOT, "build", "NumPlay.nwa")
- print("Building:", " ".join(target), flush=True)
- r = subprocess.run(target, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
- for line in r.stdout.splitlines()[-25:]:
- print(" " + line, flush=True)
- if game: # (where each game's Makefile puts its app)
- found = [os.path.join(ROOT, "games", game, n) for n in ("output/%s.nwa" % game, "build/%s.nwa" % game,
- "output/device/%s.nwa" % game)]
- found = [p for p in found if os.path.exists(p)]
- out = max(found, key=os.path.getmtime) if found else None
- if r.returncode or not out or not os.path.exists(out):
- print("Build failed; the last good app stays in dist/live/NumPlay.nwa", flush=True)
- return False
- os.makedirs(os.path.dirname(LIVE), exist_ok=True)
- tmp = LIVE + ".part"
- shutil.copyfile(out, tmp)
- os.replace(tmp, LIVE)
- print("Stable live-emulator input:", os.path.relpath(LIVE, ROOT), flush=True)
- return True
-
-
-def main():
- ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
- ap.add_argument("--game", help="a game's folder in games/, built on its own")
- ap.add_argument("--once", action="store_true", help="build once, don't watch")
- ap.add_argument("-j", type=int, default=max(1, (os.cpu_count() or 2) // 2), help="make's jobs")
- # (what tools/build_windows.py takes, so tools/emu_live.py can start either: these change nothing here)
- ap.add_argument("--watch", action="store_true")
- ap.add_argument("--launcher-only", action="store_true")
- ap.add_argument("--skip-languages", action="store_true")
- a, _ = ap.parse_known_args()
- folders = [os.path.join(ROOT, "games", a.game)] if a.game else [os.path.join(ROOT, d) for d in ("launcher", "games")]
- folders.append(os.path.join(ROOT, "games", "common"))
- build(a.game, a.j)
- if a.once:
- return
- last, count = stamp(folders)
- print("Watching NumPlay source files (%d). Save a file to build again; Ctrl+C stops." % count, flush=True)
- try:
- while True:
- time.sleep(1)
- now, n = stamp(folders)
- if now != last or n != count:
- time.sleep(0.3) # (editors write in several steps)
- last, count = stamp(folders)
- print("Detected edits (%d files watched)" % count, flush=True)
- build(a.game, a.j)
- print("Watching for the next edit", flush=True)
- except KeyboardInterrupt:
- pass
-
-
-if __name__ == "__main__":
- sys.exit(main())