Free games for graphing calculators: NumWorks, TI-Nspire CX, Casio fx-CG50 and soon TI-84 Plus CE. Balatro, Celeste, Hollow Knight, Minecraft and more.
C calculatorcalculator-gamescasiochesscrossy-roaddrive-madfx-cg50gamesgeometry-dashgraphing-calculatorndlessnumworksnumworks-appsnumworks-calculatornumworks-gamenumworks-gamestetristi-84-plus-ceti-nspire
#!/usr/bin/env python3
"""The NumWorks emulator in a window, for macOS, Linux and Windows: a calculator you can click, around 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, and runs any .nwa through tools/emu.py's Calculator.
python3 tools/emulator.py path/to/NumPlay.nwa # one app
python3 tools/emulator.py --live # Live development: builds again when you save
python3 tools/emulator.py --headless app.nwa ... # tools/emu.py's own options, without a window
Live development builds with tools/build.py, which puts the finished apps in build/compiled/ (NumPlay.nwa and
the other versions, games/ for each game on its own); pick any of them to build and run just that one.
"""
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
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import emu # noqa: E402 (the ARM emulator: the CPU, the screen, the keys, the files)
REPO_ROOT = Path(__file__).resolve().parent.parent
HOME_NWA = Path.home() / "Downloads" / "nwa"
SAVE_DIR = Path.home() / ".numplay-emulator" / "saves"
LIVE_NWA = REPO_ROOT / "build" / "compiled" / "NumPlay.nwa"
BUILD_SCRIPT = REPO_ROOT / "tools" / "build.py"
LCD_WIDTH = 320
LCD_HEIGHT = 240
FRAME_VIRTUAL_MS = 32
STEP_VIRTUAL_MS = 2 # Bound application execution between worker checks.
UI_POLL_MS = 20 # Keep the interface responsive to finished frames.
LCD_UPDATE_INTERVAL_S = 1.0 / 40.0 # At most 40 displayed frames per second.
LCD_QUIET_INTERVAL_S = 0.045 # Fallback: don't capture in the middle of a drawing burst.
LCD_STALE_FRAME_S = 0.35 # Fallback for games with no obvious end-of-frame signal.
WATCH_MS = 1000
# First-pass N0120 measurements from the same Speed Probe on real hardware.
# Solid fills: 24 * 320 * 152 pixels took 85 ms.
# Pixel pushes: 120 * 320 * 16 pixels took 45 ms.
# These two independent tests agree to within 0.6%: ~13.7 Mpix/s.
# Charge a single shared LCD transfer time without sleeping the host thread.
LCD_MS_PER_PIXEL = (85.0 / (24 * 320 * 152) + 45.0 / (120 * 320 * 16)) / 2
# 120 18-character 7x14-pixel Epsilon text draws took 44 ms.
# Partition approximate per-call and per-character cost; this is not a
# replacement for a firmware-specific glyph rasterizer cycle model.
FONT_CALL_MS = 0.030
FONT_CHAR_MS = (44.0 / 120.0 - FONT_CALL_MS) / 18
# The interface takes macOS's own colours (window background, labels, separators, accent), light and dark;
# the calculator's picture keeps its own.
SETTINGS_FILE = Path.home() / ".numplay-emulator" / "settings.json"
THEME_PALETTES = {
"light": {
"BG": "#ececec", "PANEL": "#ececec", "PANEL_2": "#e0e0e3", "HOVER": "#d8d8dc", "LINE": "#d0d0d4",
"FG": "#1d1d1f", "MUTED": "#6e6e73", "ACCENT": "#007aff", "SELECT": "#cfe0fc", "ERROR_BG": "#fbe3e1",
"GREEN": "#28cd41", "ORANGE": "#ff9500", "RED": "#ff3b30", "CHIP": "#ffffff",
},
"dark": {
"BG": "#323232", "PANEL": "#323232", "PANEL_2": "#3d3d3f", "HOVER": "#48484a", "LINE": "#4a4a4c",
"FG": "#ececec", "MUTED": "#9a9a9f", "ACCENT": "#0a84ff", "SELECT": "#25416b", "ERROR_BG": "#4a2b2a",
"GREEN": "#30d158", "ORANGE": "#ff9f0a", "RED": "#ff453a", "CHIP": "#48484c",
},
}
def _read_settings():
try:
data = json.loads(SETTINGS_FILE.read_text(encoding="utf-8"))
except (OSError, ValueError, TypeError):
return {}
return data if isinstance(data, dict) else {}
def _save_setting(key, value):
"""Atomically update one preference without overwriting the others."""
data = _read_settings()
data[key] = value
SETTINGS_FILE.parent.mkdir(parents=True, exist_ok=True)
temporary = SETTINGS_FILE.with_suffix(".tmp")
try:
temporary.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
os.replace(temporary, SETTINGS_FILE)
finally:
temporary.unlink(missing_ok=True)
def _activate_theme_palette(name):
global CURRENT_THEME
CURRENT_THEME = name if name in THEME_PALETTES else "light"
globals().update(THEME_PALETTES[CURRENT_THEME])
_activate_theme_palette(_read_settings().get("theme", "light")) # ("system" is settled once Tk runs)
UI_FAMILY = ("Helvetica Neue" if sys.platform == "darwin" else "Segoe UI" if os.name == "nt" else "DejaVu Sans")
MONO_FAMILY = ("Menlo" if sys.platform == "darwin" else "Consolas" if os.name == "nt" else "DejaVu Sans Mono")
FONT_GROW = 3 if sys.platform == "darwin" else 0 # (Tk's points are smaller on a Mac)
def font(size, weight="normal"):
return (UI_FAMILY, size + FONT_GROW, weight)
def mono(size):
return (MONO_FAMILY, size + FONT_GROW)
# All 46 named keys in emu.KEYS. Blank cells below are intentional spacers.
KEY_ROWS = [
["home", "back", "onoff", "shift", "alpha", "backspace"],
["xnt", "var", "toolbox", "up", "ok", "exe"],
["exp", "ln", "log", "left", "down", "right"],
["i", "comma", "power", "sin", "cos", "tan"],
["pi", "sqrt", "square", "lparen", "rparen", None],
["7", "8", "9", "div", "mul", "minus"],
["4", "5", "6", "plus", "ee", "ans"],
["1", "2", "3", "0", "dot", None],
]
LABEL = {
"home": "Home", "back": "Back", "onoff": "Power", "shift": "Shift",
"alpha": "Alpha", "backspace": "⌫", "xnt": "x,n,t", "var": "var",
"toolbox": "Toolbox", "up": "↑", "down": "↓", "left": "←", "right": "→",
"ok": "OK", "exe": "EXE", "exp": "eˣ", "ln": "ln", "log": "log",
"i": "i", "comma": ",", "power": "^", "sin": "sin", "cos": "cos",
"tan": "tan", "pi": "π", "sqrt": "√", "square": "x²",
"lparen": "(", "rparen": ")", "div": "÷", "mul": "×",
"minus": "−", "plus": "+", "ee": "×10ⁿ", "ans": "ans", "dot": ".",
}
# Every calculator function can also be clicked on the on-screen keyboard.
# PC bindings emphasize unambiguous shortcuts: F1-F12 + familiar keys.
PC_KEYSYM = {
"left": "left", "right": "right", "up": "up", "down": "down",
"return": "ok", "kp_enter": "exe", "escape": "back", "home": "home",
"delete": "backspace", "backspace": "backspace", "shift_l": "shift", "shift_r": "shift",
"alt_l": "alpha", "alt_r": "alpha", "space": "ok",
"f1": "home", "f2": "back", "f3": "shift", "f4": "alpha",
"f5": "toolbox", "f6": "var", "f7": "xnt", "f8": "onoff",
"f9": "ans", "f10": "exe", "f11": "sqrt", "f12": "square",
"plus": "plus", "kp_add": "plus", "minus": "minus", "kp_subtract": "minus",
"asterisk": "mul", "kp_multiply": "mul", "slash": "div", "kp_divide": "div",
"period": "dot", "kp_decimal": "dot", "comma": "comma", "parenleft": "lparen",
"parenright": "rparen", "asciicircum": "power",
}
PC_KEYSYM.update({str(n): str(n) for n in range(10)})
PC_KEYSYM.update({f"kp_{n}": str(n) for n in range(10)})
PC_KEYSYM.update({
"x": "xnt", "v": "var", "b": "toolbox", "e": "exp", "l": "ln",
"g": "log", "i": "i", "s": "sin", "c": "cos", "t": "tan",
"p": "pi", "q": "sqrt", "w": "square", "r": "power", "n": "ee",
"a": "ans",
})
def validate_layout():
placed = [k for row in KEY_ROWS for k in row if k is not None]
if set(placed) != set(emu.KEYS) or len(placed) != len(set(placed)):
missing = set(emu.KEYS) - set(placed)
extras = set(placed) - set(emu.KEYS)
raise RuntimeError(f"Keypad does not match emu.KEYS: missing={missing}, extras={extras}")
def find_nwas() -> list[Path]:
"""Quick bounded discovery: local builds and the user's normal download folder."""
patterns = (
REPO_ROOT / "build" / "compiled" / "live" / "*.nwa",
REPO_ROOT / "build" / "compiled" / "*.nwa",
REPO_ROOT / "build" / "compiled" / "games" / "*.nwa",
REPO_ROOT / "build" / "compiled" / "variants" / "*.nwa",
REPO_ROOT / "build" / "compiled" / "languages" / "*.nwa",
REPO_ROOT / "build" / "*.nwa",
REPO_ROOT / "build" / "apps" / "*.nwa",
REPO_ROOT / "games" / "*" / "output" / "*.nwa",
REPO_ROOT / "games" / "*" / "build" / "*.nwa",
HOME_NWA / "*.nwa",
HOME_NWA / "apps" / "*.nwa",
)
# Path.glob does not accept absolute pattern strings; use glob.glob.
import glob
found: dict[str, Path] = {}
for pattern in patterns:
for name in glob.glob(str(pattern)):
path = Path(name).resolve()
if path.is_file():
found[str(path).lower()] = path
return sorted(found.values(), key=lambda p: p.stat().st_mtime_ns, reverse=True)
def nwlink_command() -> str | None:
if os.name == "nt":
return shutil.which("nwlink.cmd") or shutil.which("nwlink.exe")
for p in (shutil.which("nwlink"), Path.home() / ".numplay" / "node_modules" / ".bin" / "nwlink",
REPO_ROOT / "games" / "numdash" / "node_modules" / ".bin" / "nwlink"):
if p and Path(p).exists():
return str(p)
return None
def fingerprint(path: Path) -> tuple[int, int] | None:
try:
s = path.stat()
return (s.st_size, s.st_mtime_ns)
except OSError:
return None
def rgb565_to_photo_bytes(pixels: bytes) -> Image.Image:
a = np.frombuffer(pixels, dtype="<u2").reshape(240, 320)
r = ((a >> 11) & 31) * 255 // 31
g = ((a >> 5) & 63) * 255 // 63
b = (a & 31) * 255 // 31
rgb = np.stack((r, g, b), axis=-1).astype(np.uint8)
return Image.fromarray(rgb, "RGB")
class FidelityFont:
"""Draw EADK firmware text with real glyphs, even without EPSILON_FONTS.
emu.Font used empty glyph dictionaries whenever EPSILON_FONTS was unset,
and only populated ASCII 32..126 when it was set. That rendered valid
firmware draw_string calls as blank foreground-free rectangles. We prefer
locally supplied Epsilon TTFs and use installed system fonts otherwise.
No fonts are downloaded or redistributed.
"""
def __init__(self):
configured = Path(emu.FONT_DIR).expanduser() if emu.FONT_DIR else None
repo_fonts = (REPO_ROOT / "tools" / "fonts", REPO_ROOT / "fonts",
Path.home() / ".numplay-emulator" / "fonts")
system_fonts = (
Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts" / "segoeui.ttf",
Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts" / "arial.ttf",
Path("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"),
Path("/System/Library/Fonts/Supplemental/Arial.ttf"),
Path("/Library/Fonts/Arial.ttf"),
Path("/System/Library/Fonts/Helvetica.ttc"),
)
self.cells = {}
self.cache = {}
self.sources = []
for large, (filename, size, width, height) in (
(False, ("SmallFont.ttf", 12, 7, 14)),
(True, ("LargeFont.ttf", 16, 10, 18)),
):
candidates = []
if configured:
candidates.append(configured / filename)
candidates.extend(folder / filename for folder in repo_fonts)
candidates.extend(system_fonts)
# Pillow ships/locates DejaVu Sans on most installations. Prefer
# this over the 1-bit PIL fallback if no system font can be found.
candidates.append("DejaVuSans.ttf")
font = None
source = None
for location in candidates:
try:
font = ImageFont.truetype(str(location), size)
source = str(location)
break
except (OSError, ValueError):
pass
if font is None:
try:
font = ImageFont.load_default(size=size)
except TypeError:
font = ImageFont.load_default()
source = "Pillow default fallback"
self.cells[large] = (width, height, font)
self.cache[large] = {}
self.sources.append(f"{'large' if large else 'small'}: {source}")
print("[NumPlay fonts] " + " | ".join(self.sources), file=sys.stderr, flush=True)
if not configured:
print("[NumPlay fonts] Exact Epsilon fonts are optional: set EPSILON_FONTS "
"to a directory containing SmallFont.ttf and LargeFont.ttf.",
file=sys.stderr, flush=True)
def _glyph(self, char: str, large: bool) -> bytes:
cache = self.cache[large]
if char not in cache:
w, h, f = self.cells[large]
img = Image.new("L", (w, h), 0)
asc = f.getmetrics()[0] if hasattr(f, "getmetrics") else h - 2
# Maintain the baseline used by emu.Font; match fixed EADK cells.
y = h - 3 - asc + (1 if large else 0)
if char not in ("\n", "\r", "\t"):
ImageDraw.Draw(img).text((0, y), char, font=f, fill=255)
if len(cache) >= 512:
cache.clear()
cache[char] = img.tobytes()
return cache[char]
def draw(self, screen: bytearray, text: str, x: int, y: int,
large: bool, fg: int, bg: int) -> int:
w, h, _ = self.cells[large]
fg &= 0xffff
bg &= 0xffff
# Precalculate the 256 RGB565 alpha blends once per call, not once
# per pixel; retain the backend's own interpolation semantics.
palette = []
for t in range(256):
out = 0
for shift, mask in ((11, 31), (5, 63), (0, 31)):
a = (bg >> shift) & mask
b = (fg >> shift) & mask
out |= ((a * (255 - t) + b * t) // 255) << shift
palette.append(struct.pack("<H", out))
cx = int(x)
for char in text:
if cx >= 320:
break
x0, x1 = max(0, -cx), min(w, 320 - cx)
y0, y1 = max(0, -y), min(h, 240 - y)
if x0 < x1 and y0 < y1:
glyph = self._glyph(char, large)
for j in range(y0, y1):
beg = j * w + x0
end = j * w + x1
dst = ((y + j) * 320 + cx + x0) * 2
screen[dst:dst + (end - beg) * 2] = b"".join(palette[v] for v in glyph[beg:end])
cx += w
return cx
class TracedCalculator(emu.Calculator):
"""Keep the headless emulator intact, but yield on time-changing syscalls.
In 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
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:
# 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
# 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().
# (CPU cycles spent before the SVC remain an approximation.)
self.now_ms -= 1.0
uc.emu_stop()
return result
class EmulatorWorker(threading.Thread):
def __init__(self, app_path: Path, nwlink: str, events: queue.Queue,
stop: threading.Event, paused: threading.Event,
pressed: set[str], pressed_lock: threading.Lock, save_dir: Path,
model: str = "n0120", system: str = "epsilon",
clock_mhz: list[int] | None = None,
auto_clock: list[bool] | None = None,
max_sleep_ms: int = 0,
profile_speed: bool = False):
super().__init__(daemon=True)
self.app_path, self.nwlink, self.events = app_path, nwlink, events
self.stop_requested, self.paused = stop, paused
self.pressed, self.pressed_lock = pressed, pressed_lock
self.save_dir = save_dir
self.model, self.system = model, system
self.max_sleep_ms = max_sleep_ms
self.profile_speed = profile_speed
# The UI may change this list's sole int while the worker runs.
# Access is atomic under Python's GIL; only this worker calls emu.run().
self.clock_mhz = clock_mhz if clock_mhz is not None else [216]
self.auto_clock = auto_clock if auto_clock is not None else [True]
self.end_reason: str | None = None
self.last_sleep_delta_ms = 0.0
self.last_svc_detail = None
self.last_sleep_detail = None
# Plain Python attributes: GUI only reads them; the worker only writes.
# These distinguish an overloaded Unicorn call from a legitimate EADK sleep.
self.phase = "initializing"
self.phase_since_wall = time.monotonic()
self.last_progress_wall = self.phase_since_wall
self.last_progress_ms = 0.0
self.last_cpu_seconds = 0.0
self.last_virtual_delta = 0.0
def set_phase(self, name: str):
if name != self.phase:
self.phase = name
self.phase_since_wall = time.monotonic()
def emit(self, kind: str, *payload):
if kind == "frame":
try:
self.events.put_nowait((kind, *payload))
except queue.Full:
# Drop an old screen rather than lagging behind the real app.
try:
self.events.get_nowait()
except queue.Empty:
pass
try:
self.events.put_nowait((kind, *payload))
except queue.Full:
pass
else:
# A small event queue is enough, even if frame production is fast.
while True:
try:
self.events.put_nowait((kind, *payload))
break
except queue.Full:
try:
self.events.get_nowait()
except queue.Empty:
pass
def storage_path(self) -> Path:
# Keep saves for separate .nwa names in a stable user directory.
import hashlib
unique = hashlib.sha256(str(self.app_path).lower().encode("utf-8")).hexdigest()[:10]
return self.save_dir / f"{self.app_path.stem}-{unique}.bin"
def read_keyboard(self) -> int:
with self.pressed_lock:
names = tuple(self.pressed)
state = 0
for k in names:
state |= 1 << emu.KEYS[k]
return state
def run(self):
app = None
save_path = self.storage_path()
try:
self.save_dir.mkdir(parents=True, exist_ok=True)
self.emit("status", f"Linking {self.app_path.name} with nwlink")
emu.configure(self.model, self.system)
app = TracedCalculator(str(self.app_path), storage_file=str(save_path),
nwlink=self.nwlink, max_sleep_ms=self.max_sleep_ms)
# Avoid rewriting a save file 30 times per second; save on stop.
app.storage_file = None
app.keyboard_state = self.read_keyboard
self.emit("status", f"Running {self.app_path.name}")
# Run ARM instructions in *small* virtual-time slices. A full 33ms
# emu.Calculator.run() was blocking the only CPU worker for seconds
# in expensive games and at module transitions. A 2ms slice limits
# the time before the next keyboard/frame/stop check. It preserves
# the backend's instruction-count and EADK msleep clock model.
was_paused = False
clock_anchor = time.monotonic()
last_frame_wall = clock_anchor
last_frame_virtual = float(app.now_ms)
last_frame_revision = -1
def publish_lcd(pixels, virtual_ms, revision):
# Called synchronously from the ARM worker's display hook.
# The event carries a *copy*; the emulator can continue drawing
# while Tk consumes it asynchronously. No fabricated swipe.
nonlocal last_frame_wall, last_frame_virtual, last_frame_revision
if self.stop_requested.is_set():
return
self.emit("frame", bytes(pixels), int(virtual_ms))
last_frame_wall = time.monotonic()
last_frame_virtual = float(virtual_ms)
last_frame_revision = revision
app.on_lcd_write = publish_lcd
rate_wall = clock_anchor
rate_virtual = float(app.now_ms)
busy_wall = busy_virtual = 0.0
last_auto_adjust = clock_anchor
smoothed_load = None
self.last_progress_wall = clock_anchor
self.last_progress_ms = float(app.now_ms)
profile_start = clock_anchor
profile_start_virtual = float(app.now_ms)
profile_start_frames = app.complete_display_frames
profile_start_blits = app.fullwidth_blits
profile_start_copy_seconds = app.fullwidth_copy_seconds
profile_cpu_seconds = 0.0
profile_wait_seconds = 0.0
while not self.stop_requested.is_set() and not app.exited:
if self.paused.is_set():
self.set_phase("paused")
was_paused = True
self.stop_requested.wait(0.035)
continue
if was_paused:
# Re-anchor; never run faster to pay back paused/late frames.
clock_anchor = time.monotonic()
last_auto_adjust = rate_wall = clock_anchor
app._next_lcd_notice_wall = 0.0
# Show the last completed image when resuming from pause.
app.publish_lcd_if_ready(force=True)
rate_virtual = float(app.now_ms)
busy_wall = busy_virtual = 0.0
smoothed_load = None
was_paused = False
profile_start = clock_anchor
profile_start_virtual = float(app.now_ms)
profile_start_frames = app.complete_display_frames
profile_start_blits = app.fullwidth_blits
profile_start_copy_seconds = app.fullwidth_copy_seconds
profile_cpu_seconds = profile_wait_seconds = 0.0
emu.CPU_HZ = max(27, min(550, int(self.clock_mhz[0]))) * 1_000_000
started = time.monotonic()
self.set_phase("running ARM CPU")
before_ms = float(app.now_ms)
before_sleep_ms = float(app.slept_ms)
before_sleep_count = app.long_sleep_count
before_yield_count = app.svc_yield_count
app.run(app.now_ms + STEP_VIRTUAL_MS)
work_seconds = max(0.0, time.monotonic() - started)
profile_cpu_seconds += work_seconds
delta_ms = max(0.0, float(app.now_ms) - before_ms)
slept_ms = max(0.0, float(app.slept_ms) - before_sleep_ms)
active_ms = max(0.0, delta_ms - min(delta_ms, slept_ms))
self.last_cpu_seconds = work_seconds
self.last_virtual_delta = delta_ms
self.last_sleep_delta_ms = slept_ms
self.last_sleep_detail = (app.last_long_sleep
if app.long_sleep_count != before_sleep_count else None)
self.last_svc_detail = (app.last_svc_yield
if app.svc_yield_count != before_yield_count else None)
self.last_progress_wall = time.monotonic()
self.last_progress_ms = float(app.now_ms)
if self.stop_requested.is_set() or app.exited:
break
# A large emulated sleep is not evidence that the CPU is slow.
# In particular, don't downclock because a single emulated
# millisecond of ARM work accompanied a six-second SVC sleep.
if self.auto_clock[0] and active_ms >= 0.5 and slept_ms < 250:
busy_wall += work_seconds
busy_virtual += active_ms
# Fallback for apps that paint isolated patches but don't
# sleep, request events or end with a full-width bottom strip.
# Avoid showing intermediate top-to-bottom redraw strips:
# require a quiet window after the most recent LCD write.
# The stale timeout guarantees that even unconventional games
# eventually show progress, at the cost of an occasional tear.
wall_now = time.monotonic()
if (app.lcd_revision != app.lcd_last_published_revision and
wall_now - last_frame_wall >= LCD_UPDATE_INTERVAL_S and
(wall_now - app.lcd_last_write_wall >= LCD_QUIET_INTERVAL_S or
wall_now - last_frame_wall >= LCD_STALE_FRAME_S)):
app.publish_lcd_if_ready()
# One simulated millisecond must never take *less* than one
# actual millisecond. Sleep overestimated virtual time, but
# stop waiting as soon as Reload, Pause or Power is requested.
# Keep a continuous timeline when on time; erase lateness
# beyond 40ms so there are NO catch-up bursts.
clock_anchor = max(clock_anchor, started - 0.040)
clock_anchor += delta_ms / 1000.0
wait_started = time.monotonic()
while not self.stop_requested.is_set() and not self.paused.is_set():
remaining = clock_anchor - time.monotonic()
if remaining <= 0:
break
self.set_phase("waiting for app sleep" if slept_ms >= 250
else "waiting for emulated time")
self.stop_requested.wait(min(remaining, 0.015))
profile_wait_seconds += max(0.0, time.monotonic() - wait_started)
if self.stop_requested.is_set():
break
if self.paused.is_set():
was_paused = True
continue
self.set_phase("running ARM CPU")
wall_now = time.monotonic()
if self.profile_speed and wall_now - profile_start >= 5.0:
seconds = wall_now - profile_start
frames = app.complete_display_frames - profile_start_frames
blits = app.fullwidth_blits - profile_start_blits
simulated = float(app.now_ms) - profile_start_virtual
# One full-width bottom strip generally completes one
# NumDrive 3D image. Report graphics throughput *separately*
# from how quickly the emulated virtual clock advances.
copied_ms = (app.fullwidth_copy_seconds -
profile_start_copy_seconds) * 1000.0
avg_frame_ms = (f"{1000*profile_cpu_seconds/frames:.1f}"
if frames else "n/a")
print(f"[NumPlay speed profile] "
f"render_fps~{frames/seconds:.1f}; "
f"virtual_rate={simulated/(1000*seconds):.2f}x; "
f"ARM_work={100*profile_cpu_seconds/seconds:.0f}%; "
f"wall_wait={100*profile_wait_seconds/seconds:.0f}%; "
f"CPU={int(self.clock_mhz[0])}MHz "
f"({'auto' if self.auto_clock[0] else 'manual'}); "
f"fullwidth_blits={blits}; "
f"copy_ms={copied_ms:.1f}; "
f"avg_ARM_ms_per_frame={avg_frame_ms}",
file=sys.stderr, flush=True)
profile_start = wall_now
profile_start_virtual = float(app.now_ms)
profile_start_frames = app.complete_display_frames
profile_start_blits = app.fullwidth_blits
profile_start_copy_seconds = app.fullwidth_copy_seconds
profile_cpu_seconds = profile_wait_seconds = 0.0
# Calibrate based on actual Unicorn throughput, separately
# from time spent inside EADK sleep. Earlier 1.25s sampling
# intervals could take far longer in a busy scene. Faster
# sampling and bounded steps make this responsive without a
# constantly oscillating MHz value.
if self.auto_clock[0] and wall_now - last_auto_adjust >= 0.45:
if busy_virtual >= 8.0:
load = busy_wall / max(0.001, busy_virtual / 1000.0)
smoothed_load = (load if smoothed_load is None else
0.65 * smoothed_load + 0.35 * load)
old = int(self.clock_mhz[0])
if smoothed_load > 1.05:
new = max(27, int(old * 0.80))
elif smoothed_load < 0.58 and old < 216:
new = min(216, max(old + 1, int(old * 1.05)))
else:
new = old
self.clock_mhz[0] = new
busy_wall = busy_virtual = 0.0
last_auto_adjust = wall_now
elif not self.auto_clock[0]:
busy_wall = busy_virtual = 0.0
smoothed_load = None
last_auto_adjust = wall_now
if wall_now - rate_wall >= 1.0:
rate = (float(app.now_ms) - rate_virtual) / (1000.0 * (wall_now - rate_wall))
self.emit("pace", round(rate, 2), int(self.clock_mhz[0]), bool(self.auto_clock[0]))
rate_wall, rate_virtual = wall_now, float(app.now_ms)
if app.exited:
self.set_phase("exited")
# The caller must blank the screen; the final framebuffer is
# NOT a valid representation of a powered-off calculator.
self.end_reason = "exited"
self.emit("ended", "The app quit. Press On/Off or Restart to start it again")
except Exception:
self.set_phase("error")
error_report = traceback.format_exc()
# Preserve the complete traceback even if the GUI dialog is closed.
# Never allow a diagnostic logging error to hide the original fault.
try:
error_log = SAVE_DIR.parent / "last-error.txt"
error_log.parent.mkdir(parents=True, exist_ok=True)
error_log.write_text(error_report, encoding="utf-8")
except OSError:
error_log = None
print(error_report, file=sys.stderr, flush=True)
if error_log is not None:
print(f"[NumPlay emulator] Full traceback: {error_log}",
file=sys.stderr, flush=True)
self.emit("error", error_report)
finally:
if not app or not app.exited:
if self.phase != "error":
self.set_phase("stopped")
if app is not None:
try:
save_path.write_bytes(app.storage_bytes())
except Exception as exc:
self.emit("error", f"Could not save emulated storage:\n{exc}")
class LiveApp:
def __init__(self, root: tk.Tk, initial: Path | None, nwlink: str,
model: str, system: str, auto_follow: bool,
max_sleep_ms: int = 0, profile_speed: bool = False):
validate_layout()
self.root, self.nwlink = root, nwlink
self.model, self.system = model, system
self.max_sleep_ms = max_sleep_ms
self.profile_speed = profile_speed
# Match the requested calculator model by default. For N0120 the
# measured integer test was 58ms at 550MHz (52ms on physical hardware).
# This is a stable virtual-clock baseline, not a cycle-accurate model.
self.clock_mhz = [550 if model == "n0120" else 216]
# Host-adaptive mode dynamically changes the virtual clock and can
# distort game timing; make it opt-in, not the release default.
self.auto_clock = [False]
self.powered_off = False
self._power_key_held = False
self.root.title("NumPlay emulator")
self.root.configure(bg=BG)
self.root.minsize(690, 820)
self.root.protocol("WM_DELETE_WINDOW", self.on_close)
self.worker: EmulatorWorker | None = None
self.stop_event = threading.Event()
self.pause_event = threading.Event()
self.messages: queue.Queue = queue.Queue(maxsize=3)
self.pressed: set[str] = set()
self.pressed_pc: dict[str, str] = {}
self.mouse_pressed: str | None = None
self.pressed_lock = threading.Lock()
self.key_widgets: dict[str, tk.Label] = {}
self.current: Path | None = None
self.pending: Path | None = None
self.current_stamp: tuple[int, int] | None = None
self.watch_candidate: tuple[tuple[str, tuple[int, int]], int] | None = None
self.watch_var = tk.BooleanVar(value=True)
self.follow_var = tk.BooleanVar(value=auto_follow)
self.status = tk.StringVar(value="Drop a .nwa on the calculator, or choose Open")
self.file_label = tk.StringVar(value="No application loaded")
self.time_label = tk.StringVar(value="0 ms")
self._screen_rgb: Image.Image | None = None
self._photo = None
self._closing = False
self._last_frame_wall = time.monotonic()
self._last_stall_log_wall = 0.0
self.input_status = tk.StringVar(value="Keys: ready")
self._build_ui()
self.root.bind_all("<KeyPress>", self.on_pc_down, add="+")
self.root.bind_all("<KeyRelease>", self.on_pc_up, add="+")
self.root.bind_all("<ButtonRelease-1>", self.on_mouse_up, add="+")
self.root.bind("<FocusOut>", self.on_focus_out, add="+")
self.root.bind("<FocusIn>", self.on_focus_in, add="+")
self.root.bind("<Map>", self.on_window_map, add="+")
if DND_FILES is not None:
for widget in (self.root, self.screen_label, self.drop_line):
widget.drop_target_register(DND_FILES)
widget.dnd_bind("<<Drop>>", self.on_drop)
self._poll_id = self.root.after(UI_POLL_MS, self.poll)
self._watch_id = self.root.after(WATCH_MS, self.watch)
if initial is not None:
self.root.after(150, lambda: self.load(initial))
elif not getattr(self, "_simple_mode_ui", False):
latest = find_nwas()
if latest:
self.root.after(150, lambda: self.load(latest[0]))
else:
self.root.after(250, self.open_file)
def _build_ui(self):
top = tk.Frame(self.root, bg=BG)
top.pack(fill="x", padx=12, pady=(12, 4))
tk.Label(top, text="NumPlay emulator", bg=BG, fg=FG,
font=font(17, "bold")).pack(side="left")
tk.Label(top, textvariable=self.time_label, bg=BG, fg=MUTED,
font=font(10)).pack(side="right")
actions = tk.Frame(self.root, bg=BG)
actions.pack(fill="x", padx=10, pady=6)
for title, cb in (("Open .nwa", self.open_file), ("Find newest", self.find_latest),
("Reload", self.reset), ("Pause", self.toggle_pause),
("Screenshot", self.screenshot), ("Keymap", self.show_keymap)):
button = tk.Button(actions, text=title, command=cb, bg=PANEL_2, fg=FG,
activebackground=HOVER, activeforeground=FG,
relief="flat", bd=0, padx=9, pady=7, font=font(9))
button.pack(side="left", padx=2)
if title == "Pause":
self.pause_button = button
choices = tk.Frame(self.root, bg=BG)
choices.pack(fill="x", padx=12, pady=(0, 6))
for var, label in ((self.watch_var, "Auto-reload changed .nwa"),
(self.follow_var, "Follow newest local build")):
tk.Checkbutton(choices, text=label, variable=var, bg=BG, fg=MUTED,
activebackground=BG, activeforeground=ACCENT,
selectcolor=PANEL, font=font(9)).pack(side="left", padx=4)
path_panel = tk.Frame(self.root, bg=PANEL, padx=10, pady=7)
path_panel.pack(fill="x", padx=12, pady=2)
tk.Label(path_panel, textvariable=self.file_label, bg=PANEL, fg=FG,
anchor="w", font=font(9)).pack(fill="x")
center = tk.Frame(self.root, bg=BG)
center.pack(fill="x", padx=12, pady=8)
self._screen_rgb = Image.new("RGB", (320, 240), (235, 235, 235))
self._photo = ImageTk.PhotoImage(self._screen_rgb.resize((640, 480), Image.Resampling.NEAREST))
self.screen_label = tk.Label(center, image=self._photo, bg="#050505", bd=7, relief="flat")
self.screen_label.pack(anchor="center")
self.drop_line = tk.Label(center, text=("Drop a .nwa here, " if DND_FILES else "") +
"click a key or use your PC keyboard", bg=BG, fg=MUTED,
font=font(9), pady=4)
self.drop_line.pack()
keyboard = tk.Frame(self.root, bg=BG)
keyboard.pack(fill="both", expand=True, padx=12, pady=5)
for col in range(6):
keyboard.grid_columnconfigure(col, weight=1, uniform="numworks")
for i, row in enumerate(KEY_ROWS):
keyboard.grid_rowconfigure(i, weight=1)
for j, key in enumerate(row):
if key is None:
continue
bg = ACCENT if key in ("ok", "exe") else (SELECT if key in
("left", "right", "up", "down") else PANEL_2)
if key in ("home", "onoff", "shift", "alpha"):
bg = HOVER
w = tk.Label(keyboard, text=LABEL.get(key, key), bg=bg, fg=FG,
relief="flat", bd=0, font=font(10, "bold"),
padx=5, pady=5, cursor="hand2")
w.grid(row=i, column=j, sticky="nsew", padx=3, pady=3)
w.bind("<ButtonPress-1>", lambda e, k=key: self.on_mouse_down(k))
w.bind("<ButtonRelease-1>", self.on_mouse_up)
self.key_widgets[key] = w
status = tk.Label(self.root, textvariable=self.status, bg=PANEL, fg=ACCENT,
anchor="w", padx=12, pady=7, font=font(9))
status.pack(fill="x", side="bottom")
self.root.focus_force()
def set_status(self, msg: str):
self.status.set(msg)
def open_file(self):
path = filedialog.askopenfilename(parent=self.root, title="Open a NumWorks application",
filetypes=[("NumWorks apps", "*.nwa"), ("All files", "*.*")],
initialdir=str(HOME_NWA if HOME_NWA.exists() else REPO_ROOT))
if path:
self.follow_var.set(False)
self.load(Path(path))
def on_drop(self, event):
for s in self.root.tk.splitlist(event.data):
if s.lower().endswith(".nwa"):
self.follow_var.set(False)
self.load(Path(s))
return
self.set_status("Drop a .nwa file from File Explorer.")
def find_latest(self):
found = find_nwas()
if found:
self.load(found[0])
else:
messagebox.showinfo("No .nwa found", "Build a .nwa or drop one here.\n"
"Searches build/, games/*/output/ and Downloads/nwa/.")
def load(self, path: Path):
path = path.expanduser().resolve()
if path.suffix.lower() != ".nwa" or not path.is_file():
self.set_status(f"Not a valid .nwa file: {path}")
return
self.pending = path
self.pause_event.clear()
self.pause_button.configure(text="Pause")
self.clear_keys()
if self.worker is not None and self.worker.is_alive():
self.stop_event.set()
self.set_status(f"Reloading {path.name}")
else:
self.start_pending()
def start_pending(self):
path = self.pending
if path is None:
return
self.pending = None
self.current = path
self._last_frame_wall = time.monotonic()
self._last_stall_log_wall = 0.0
self.current_stamp = fingerprint(path)
self.watch_candidate = None
self.file_label.set(str(path))
self.time_label.set("0 ms")
self.messages = queue.Queue(maxsize=3)
self.stop_event = threading.Event()
self.powered_off = False
self.worker = EmulatorWorker(path, self.nwlink, self.messages, self.stop_event,
self.pause_event, self.pressed, self.pressed_lock,
SAVE_DIR, self.model, self.system,
self.clock_mhz, self.auto_clock,
self.max_sleep_ms, self.profile_speed)
self.worker.start()
def reset(self):
if self.current:
self.load(self.current)
else:
self.find_latest()
def present_screen(self):
"""Display the current RGB screen; overridden by the skinned GUI."""
if self._screen_rgb is None:
return
self._photo = ImageTk.PhotoImage(self._screen_rgb.resize((640, 480), Image.Resampling.NEAREST))
self.screen_label.configure(image=self._photo)
def black_screen(self, reason: str):
self.powered_off = True
self._screen_rgb = Image.new("RGB", (320, 240), (0, 0, 0))
self.present_screen()
self.time_label.set("Powered off")
self.set_status(reason)
def power_button(self):
"""Power button is a frontend power toggle, not a stuck ARM key.
Epsilon's power-off firmware isn't emulated. Sending the raw on/off
key can leave the app waiting forever for firmware wakeup, so blank
the screen and stop the worker. Click again to boot the .nwa anew.
"""
if self.powered_off:
self.reset()
else:
self.pending = None
self.stop_event.set()
self.pause_event.clear()
self.pause_button.configure(text="Pause")
self.clear_keys()
self.black_screen("Turned off. Press On/Off or Restart to start again")
def toggle_pause(self):
if self.pause_event.is_set():
self.pause_event.clear()
self.pause_button.configure(text="Pause")
self.set_status("Resumed")
else:
self.pause_event.set()
self.pause_button.configure(text="Resume")
self.set_status("Paused (emulated clock stopped)")
def screenshot(self):
if self._screen_rgb is None:
return
directory = REPO_ROOT / "build" / "data" / "emulator"
directory.mkdir(parents=True, exist_ok=True)
path = directory / f"{self.current.stem if self.current else 'screen'}-{int(time.time())}.png"
self._screen_rgb.save(path)
self.set_status(f"Screenshot saved: {path}")
def on_mouse_down(self, key: str):
if key == "onoff":
self.power_button()
return
if self.powered_off:
return
if self.mouse_pressed is not None:
self.on_mouse_up()
self.mouse_pressed = key
self.input_status.set(f"Keys: {key}")
self.refresh_pressed()
def on_mouse_up(self, event=None):
if self.mouse_pressed is not None:
self.mouse_pressed = None
self.refresh_pressed()
def on_pc_down(self, event):
# Don't send keyboard shortcuts from another Toplevel (e.g. Keymap).
if event.widget.winfo_toplevel() is not self.root:
return None
if sys.platform == "darwin" and event.state & 0x8: # (Command: a menu's shortcut)
return None
sym = event.keysym.lower()
key = PC_KEYSYM.get(sym)
if key == "onoff":
if not self._power_key_held:
self._power_key_held = True
self.power_button()
return "break"
if self.powered_off:
return "break" if key else None
if key:
self.pressed_pc[sym] = key
self.input_status.set(f"Keys: {key}")
self.refresh_pressed()
# ALL NumWorks keys must be intercepted, not just Space. Otherwise
# Tk buttons/dropdowns can steal arrow keys after a focus change.
return "break"
return None
def on_pc_up(self, event):
if event.widget.winfo_toplevel() is not self.root:
return None
sym = event.keysym.lower()
if PC_KEYSYM.get(sym) == "onoff":
self._power_key_held = False
return "break"
if sym in self.pressed_pc:
self.pressed_pc.pop(sym, None)
self.refresh_pressed()
return "break"
return None
def on_focus_out(self, event):
# Releasing Alt, Shift or directions in another window does not produce
# KeyRelease events here. Prevent ghost keys when returning to the game.
if event.widget is self.root:
self.clear_keys()
self.input_status.set("Keys: released")
def on_focus_in(self, event):
if event.widget is self.root:
self.root.after(60, self.refocus_input)
def on_window_map(self, event):
if event.widget is self.root:
self.root.after(80, self.refocus_input)
def refocus_input(self):
"""Give keyboard events to the calculator after a dialog or Alt-Tab.
Use focus_set (not focus_force), to avoid grabbing focus away from
other Windows applications when we're in the background.
"""
if self._closing or not hasattr(self, "canvas"):
return
try:
if self.root.focus_displayof() is not None:
self.canvas.focus_set()
self.input_status.set("Keys: ready")
except tk.TclError:
pass
def clear_keys(self):
self.pressed_pc.clear()
self.mouse_pressed = None
self._power_key_held = False
self.refresh_pressed()
def refresh_pressed(self):
names = set(self.pressed_pc.values())
if self.mouse_pressed is not None:
names.add(self.mouse_pressed)
with self.pressed_lock:
self.pressed.clear()
self.pressed.update(names)
for k, widget in self.key_widgets.items():
if k in names:
widget.configure(bg=ACCENT, fg=FG)
else:
widget.configure(fg=FG, bg=(ACCENT if k in ("ok", "exe") else
SELECT if k in ("left", "right", "up", "down") else
HOVER if k in ("home", "onoff", "shift", "alpha") else PANEL_2))
def show_keymap(self):
w = tk.Toplevel(self.root)
w.title("PC keyboard shortcuts")
w.configure(bg=BG)
w.geometry("615x430")
lines = [
"ALL calculator keys are clickable on the main window.",
"Hold mouse button for continuous keypress (e.g. duck).",
"", "Arrows = ← ↑ ↓ → Enter / Space = OK Numpad Enter = EXE",
"Esc = Back Home / F1 = Home Backspace / Delete = ⌫",
"Shift = Shift Alt = Alpha F8 = Power",
"", "F2 Back F3 Shift F4 Alpha F5 Toolbox",
"F6 var F7 x,n,t F9 ans F10 EXE",
"F11 = Fullscreen in skinned UI (√ in plain UI) F12 = x²", "",
"Digits 0–9, numpad, + - * / , . ( ) ^ work as expected.",
"", "x=x,n,t v=var b=Toolbox e=eˣ l=ln g=log",
"i=i s=sin c=cos t=tan p=π q=√",
"w=x² r=^ n=×10ⁿ a=ans", "",
"Drag any .nwa into the window or click Open .nwa.",
"Single file: no automatic builds or reloads.",
"Live development: compiles sources and reloads after a successful build.",
"Emulated saves persist in ~/.numplay-emulator/saves/.",
]
tk.Label(w, text="\n".join(lines), justify="left", bg=BG, fg=FG,
font=mono(10), padx=18, pady=14).pack(anchor="nw")
def poll(self):
if self._closing:
return
newest_frame = None
last_status = None
ended = None
error = None
while True:
try:
m = self.messages.get_nowait()
except queue.Empty:
break
if m[0] == "frame":
newest_frame = m
elif m[0] == "status":
last_status = m[1]
elif m[0] == "ended":
ended = m[1]
elif m[0] == "error":
error = m[1]
if last_status and not self.powered_off:
self.set_status(last_status)
if not self.powered_off and newest_frame and not ended:
_, raw, elapsed = newest_frame
try:
self._screen_rgb = rgb565_to_photo_bytes(raw)
self.present_screen()
self.time_label.set(f"{elapsed:,} ms (virtual)")
except Exception as exc:
self.set_status(f"Display error: {exc}")
if ended and not self.powered_off:
self.black_screen(ended)
elif (self.worker is not None and self.worker.end_reason == "exited"
and not self.powered_off):
# Also handle a full message queue dropping an end notification.
self.black_screen("The app quit. Press Restart to start it again")
if error and not self.powered_off:
self.set_status("The emulator stopped with an error")
messagebox.showerror("NumPlay emulator", error)
if self.pending is not None and (self.worker is None or not self.worker.is_alive()):
self.start_pending()
self._poll_id = self.root.after(UI_POLL_MS, self.poll)
def watch(self):
if self._closing:
return
try:
if self.follow_var.get():
latest = find_nwas()
if latest and (self.current is None or latest[0] != self.current):
# Switch only when a new build is stable across checks.
self._maybe_reload(latest[0])
elif self.current is not None and self.watch_var.get():
self._maybe_reload(self.current)
elif self.current is not None and self.watch_var.get():
self._maybe_reload(self.current)
except OSError as exc:
self.set_status(f"Auto-reload check: {exc}")
self._watch_id = self.root.after(WATCH_MS, self.watch)
def _maybe_reload(self, path: Path):
stamp = fingerprint(path)
if stamp is None:
return
if path == self.current and stamp == self.current_stamp:
self.watch_candidate = None
return
marker = (str(path), stamp)
if self.watch_candidate is None or self.watch_candidate[0] != marker:
self.watch_candidate = (marker, 1)
return
self.watch_candidate = None
self.load(path)
def on_close(self):
self._closing = True
self.stop_event.set()
self.clear_keys()
# Worker is a daemon; allow a short non-blocking poll to save storage.
self._close_deadline = time.monotonic() + 3.0
self._finish_close()
def _finish_close(self):
if self.worker is None or not self.worker.is_alive() or time.monotonic() > self._close_deadline:
for callback in (self._poll_id, self._watch_id):
try:
self.root.after_cancel(callback)
except tk.TclError:
pass
self.root.destroy()
else:
self.root.after(100, self._finish_close)
# ---------- The calculator: a picture of a NumWorks N0120, its screen and keys measured on it ----------
CALCULATOR = Path(__file__).resolve().parent / "emu_live_calculator.webp"
CALCULATOR_SIZE = (1018, 2000)
# (x, y, width, height) in the picture's pixels; the arrows' middle does nothing, as on the calculator
SCREEN_PX = (148, 154, 722, 542)
KEYS_PX = {
"up": (191, 799, 74, 88), "down": (191, 960, 74, 88), "left": (105, 887, 86, 73), "right": (265, 887, 88, 73),
"home": (439, 816, 139, 90), "onoff": (439, 941, 139, 90), "ok": (664, 866, 109, 112),
"back": (803, 866, 109, 112),
}
FUNCTIONS = (
"shift", "alpha", "xnt", "var", "toolbox", "backspace",
"exp", "ln", "log", "i", "comma", "power",
"sin", "cos", "tan", "pi", "sqrt", "square",
)
DIGITS = (
"7", "8", "9", "lparen", "rparen",
"4", "5", "6", "mul", "div",
"1", "2", "3", "plus", "minus",
"0", "dot", "ee", "ans", "exe",
)
for _row, (_y0, _y1) in enumerate(((1094, 1168), (1204, 1280), (1316, 1392))):
for _col, (_x0, _x1) in enumerate(((105, 214), (244, 354), (384, 493), (524, 633), (664, 773), (803, 912))):
KEYS_PX[FUNCTIONS[_row * 6 + _col]] = (_x0, _y0, _x1 - _x0, _y1 - _y0)
for _row, (_y0, _y1) in enumerate(((1431, 1517), (1556, 1641), (1678, 1766), (1805, 1890))):
for _col, (_x0, _x1) in enumerate(((105, 239), (273, 407), (442, 576), (610, 744), (779, 912))):
KEYS_PX[DIGITS[_row * 5 + _col]] = (_x0, _y0, _x1 - _x0, _y1 - _y0)
def _fraction(box):
x, y, w, h = box
return (x / CALCULATOR_SIZE[0], y / CALCULATOR_SIZE[1], w / CALCULATOR_SIZE[0], h / CALCULATOR_SIZE[1])
SCREEN = _fraction(SCREEN_PX)
HOTSPOTS = {key: _fraction(box) for key, box in KEYS_PX.items()}
assert set(HOTSPOTS) == set(emu.KEYS), (set(emu.KEYS) - set(HOTSPOTS))
class FlatButton(tk.Label):
"""A plain button that keeps its colours on every system (a Mac's tk.Button ignores them): grey, or NumWorks
yellow for the one main action; greyed out when disabled. Takes text=, state= and command= like tk.Button."""
def __init__(self, parent, text, command, primary=False):
self._bg = ACCENT if primary else PANEL_2
super().__init__(parent, text=text, bg=self._bg, fg=("#34343a" if primary else FG), font=font(10, "bold" if primary else "normal"),
pady=8, cursor="hand2", disabledforeground="#b5b5b5")
self._command = command
self.bind("<Enter>", lambda e: self._enabled() and super(FlatButton, self).configure(
bg="#ffc85c" if self._bg == ACCENT else HOVER))
self.bind("<Leave>", lambda e: super(FlatButton, self).configure(bg=self._bg))
self.bind("<ButtonRelease-1>", lambda e: self._enabled() and self._command and self._command())
def _enabled(self):
return str(self.cget("state")) != "disabled"
def configure(self, cnf=None, **kw):
if "command" in kw:
self._command = kw.pop("command")
return super().configure(cnf, **kw)
config = configure
def _safe_window_geometry(placement, root):
"""Ignore invalid/off-screen saved placements after a display change."""
if not isinstance(placement, dict):
return None
values = [placement.get(k) for k in ("width", "height", "x", "y")]
if any(type(v) is not int or abs(v) > 100000 for v in values):
return None
width, height, x, y = values
if width < 400 or height < 250:
return None
screen_w, screen_h = root.winfo_screenwidth(), root.winfo_screenheight()
if min(screen_w, screen_h) <= 0:
return None
width = min(width, screen_w)
height = min(height, screen_h)
# A title bar and at least a strip of the window should remain accessible.
if x + width < 160 or x > screen_w - 160 or y + height < 60 or y > screen_h - 60:
x = max(0, (screen_w - width) // 2)
y = max(0, (screen_h - height) // 2)
else:
x = max(0, min(x, screen_w - 160))
y = max(0, min(y, screen_h - 60))
return (width, height, x, y, placement.get("maximized") is True)
# ---------- Keys pressed: each sinks in, in its own shape ----------
def _key_radius(key, w, h):
"""The corner radius of a key's face, in the same units as w and h (None: it's round)."""
if key in ("ok", "back"):
return None
if key in ("up", "down", "left", "right"):
return min(w, h) * 0.3
return h * (0.42 if key in DIGITS else 0.5)
def key_sprite(key, w, h, state):
"""A see-through picture laid over a key: "pressed" darkens its face and shades its top edge inside, as a
key pushed in; "hover" shades it a little."""
k = 4 # (drawn 4 times bigger, then made smaller: smooth edges)
mask = Image.new("L", (w * k, h * k), 0)
d = ImageDraw.Draw(mask)
r = _key_radius(key, w * k, h * k)
if r is None:
d.ellipse((0, 0, w * k - 1, h * k - 1), fill=255)
else:
d.rounded_rectangle((0, 0, w * k - 1, h * k - 1), radius=r, fill=255)
mask = mask.resize((w, h), Image.Resampling.LANCZOS)
m = np.asarray(mask, dtype=np.float32) / 255
if state == "hover":
alpha = m * 0.06
out = np.zeros((h, w, 4), np.float32)
out[..., 3] = alpha
return Image.fromarray((out * 255).astype(np.uint8), "RGBA")
# the shadow under the top edge: the face less itself moved down, blurred, kept inside the face
drop = max(1, round(h * 0.08))
moved = np.zeros_like(m)
moved[drop:] = m[:-drop]
edge = Image.fromarray((np.clip(m - moved, 0, 1) * 255).astype(np.uint8), "L")
edge = edge.filter(ImageFilter.GaussianBlur(max(1.0, h * 0.07)))
shade = np.asarray(edge, dtype=np.float32) / 255 * m
dark = np.clip(m * 0.15 + shade * 0.6, 0, 0.8)
# a thin light line along the bottom edge, inside
up = np.zeros_like(m)
up[:-1] = m[1:]
light = np.clip(m - up, 0, 1) * 0.35
layer = lambda rgb, a: Image.merge("RGBA", [Image.new("L", (w, h), c) for c in rgb] +
[Image.fromarray((a * 255).astype(np.uint8), "L")])
return Image.alpha_composite(layer((16, 18, 24), dark), layer((255, 255, 255), light))
# what a computer key is called on its key cap, for the badge over the calculator key it presses
PC_GLYPH = {"return": "⏎", "kp_enter": "⌅", "escape": "esc", "left": "←", "right": "→", "up": "↑",
"down": "↓", "shift_l": "⇧", "shift_r": "⇧", "alt_l": "⌥", "alt_r": "⌥", "space": "space",
"delete": "⌫", "backspace": "⌫", "home": "home", "plus": "+", "kp_add": "+", "minus": "−",
"kp_subtract": "−", "asterisk": "*", "kp_multiply": "*", "slash": "/", "kp_divide": "/",
"period": ".", "kp_decimal": ".", "comma": ",", "parenleft": "(", "parenright": ")",
"asciicircum": "^"}
# the calculator keys by name, where their label is a symbol
KEY_NAMES = {"left": "Left", "right": "Right", "up": "Up", "down": "Down", "ok": "OK", "back": "Back",
"home": "Home", "onoff": "On/Off", "shift": "Shift", "alpha": "Alpha", "backspace": "Delete",
"exe": "EXE", "toolbox": "Toolbox"}
def pc_glyph(sym):
if sym in PC_GLYPH:
return PC_GLYPH[sym]
if sym.startswith("kp_"):
return sym[3:]
if len(sym) == 1:
return sym.upper()
return sym.upper() if re.fullmatch(r"f\d+", sym) else sym
def round_rect(canvas, x0, y0, x1, y1, r, **kw):
"""A rounded rectangle on a Tk canvas (a smoothed polygon)."""
pts = [x0 + r, y0, x1 - r, y0, x1, y0, x1, y0 + r, x1, y1 - r, x1, y1, x1 - r, y1, x0 + r, y1, x0, y1,
x0, y1 - r, x0, y0 + r, x0, y0]
return canvas.create_polygon(pts, smooth=True, **kw)
class CalculatorSkinApp(LiveApp):
"""NumWorks skin with mutually exclusive file and live-development modes.
Only this GUI runs the watcher; the existing Makefiles/build script and
emu.Calculator backend are deliberately untouched.
"""
def __init__(self, root, initial, nwlink, model, system, auto_follow,
art_path: Path, max_sleep_ms: int = 0,
profile_speed: bool = False, start_live: bool = False):
self.art_path = art_path
self._art_rgba = Image.open(art_path).convert("RGBA") # (its corners and shadow are see-through)
self.art = self._art_on(BG)
self.art_px = self.art.size
self._canvas_image = None
self._canvas_screen = None
self._bg_photo = None
self._art_geometry = (0, 0, 0, 0)
self._hover = None
self._last_canvas_size = None
self.fullscreen = False
self.f11_down = False
self.rate_label = tk.StringVar(master=root, value="Emulator ready")
# Display choice and build choice are independent: neither view switch
# restarts Unicorn nor starts/stops the compiler.
self.view_var = tk.StringVar(master=root, value="calculator")
self._native_geometry = None
self.mode_var = tk.StringVar(master=root, value="live" if start_live else "file")
self.build_status = tk.StringVar(master=root, value="Choose a .nwa to play")
self.build_detail = tk.StringVar(master=root, value="No compiler process running")
self.build_process = None
self._builder_generation = 0
self._builder_events = queue.Queue()
self._builder_log = deque(maxlen=850)
self._build_log_window = None
self._build_log_text = None
self._builder_has_error = False
self._builder_ready = False
self._builder_busy = False
self._builder_stopping = False
self._simple_mode_ui = True
# A physical USB flash must never be triggered by auto-build/reload.
self._upload_running = False
self._upload_events = queue.Queue()
self._upload_log = deque(maxlen=120)
self._upload_start_wall: float | None = None
self._upload_progress_is_reported = False
self._upload_log_window = None
self._upload_log_text = None
self.upload_status = tk.StringVar(master=root, value="Installs the open app on a calculator plugged in "
"with USB")
self.upload_activity = tk.StringVar(master=root, value="")
self.upload_elapsed = tk.StringVar(master=root, value="")
self.appearance = _read_settings().get("theme", "system")
if self.appearance not in ("system", "light", "dark"):
self.appearance = "system"
self._sprites = {}
self._sprite_photos = []
self._speed_hist = deque(maxlen=60)
self._snap_id = None
self._look_checked = 0.0
super().__init__(root, initial, nwlink, model, system, False,
max_sleep_ms=max_sleep_ms, profile_speed=profile_speed)
# Avoid the original fallback's ambiguous 'newest local file' behavior.
self.watch_var.set(False)
self.follow_var.set(False)
self._builder_poll_id = self.root.after(120, self._poll_builder)
self._upload_poll_id = self.root.after(160, self._poll_upload)
self._set_appearance(self.appearance, initial=True)
self._apply_interface_theme()
self._restore_window_placement()
self.root.bind("<Configure>", self._remember_window_geometry, add="+")
if start_live:
self.root.after(260, self._start_builder)
def _art_on(self, bg):
return Image.alpha_composite(Image.new("RGBA", self._art_rgba.size, bg), self._art_rgba).convert("RGB")
def _restore_window_placement(self):
placement = _safe_window_geometry(_read_settings().get("window"), self.root)
self._window_last_normal = None
self._window_restoring = bool(placement)
if placement is None:
return
width, height, x, y, maximized = placement
self._window_last_normal = (width, height, x, y)
self.root.geometry(f"{width}x{height}+{x}+{y}")
if maximized:
self.root.after(110, self._restore_window_maximized)
self.root.after(200, self._finish_window_restoring)
def _restore_window_maximized(self):
try:
self.root.state("zoomed")
except tk.TclError:
try:
self.root.attributes("-zoomed", True)
except tk.TclError:
pass
def _finish_window_restoring(self):
self._window_restoring = False
def _remember_window_geometry(self, event=None):
if event is not None and event.widget is not self.root:
return
if getattr(self, "_window_restoring", False) or self.fullscreen:
return
try:
if self.root.state() == "normal":
width, height = self.root.winfo_width(), self.root.winfo_height()
if width >= 400 and height >= 250:
self._window_last_normal = (width, height,
self.root.winfo_x(), self.root.winfo_y())
except tk.TclError:
pass
def _save_window_placement(self):
try:
state = self.root.state()
if state == "normal" and not self.fullscreen:
self._remember_window_geometry()
if self._window_last_normal is None:
return
width, height, x, y = self._window_last_normal
_save_setting("window", {"width": width, "height": height,
"x": x, "y": y,
"maximized": state == "zoomed" and not self.fullscreen})
except (OSError, ValueError, tk.TclError) as exc:
print(f"[NumPlay] Could not save window placement: {exc}", file=sys.stderr)
INSPECTOR_W = 280
MODELS = (("N0120", "n0120"), ("N0110 or N0115", "n0110"))
SYSTEMS = (("Epsilon", "epsilon"), ("Upsilon", "upsilon"))
SPEEDS = ("Like the calculator", "Like this computer (less exact)", "108 MHz", "54 MHz", "27 MHz")
def _build_ui(self):
aqua = self.root.tk.call("tk", "windowingsystem") == "aqua"
self._aqua = aqua
if aqua: # (the system font, San Francisco)
global UI_FAMILY
UI_FAMILY = tkfont.nametofont("TkDefaultFont").actual("family")
self._cmd = "Command" if aqua else "Control"
self.root.title("NumPlay Simulator")
# the window holds the calculator and the inspector, no more: the calculator as tall as fits
dev_h = max(560, min(860, self.root.winfo_screenheight() - 150))
dev_w = round(dev_h * self.art_px[0] / self.art_px[1])
self.root.geometry(f"{dev_w + 1 + self.INSPECTOR_W}x{dev_h + 47}")
self.root.minsize(520, 560)
self.live_var = tk.BooleanVar(master=self.root, value=self.mode_var.get() == "live")
self.model_var = tk.StringVar(master=self.root, value=dict((v, k) for k, v in self.MODELS)[self.model])
self.system_var = tk.StringVar(master=self.root, value=dict((v, k) for k, v in self.SYSTEMS)[self.system])
self.speed_var = tk.StringVar(master=self.root, value=self.SPEEDS[0])
self.appearance_var = tk.StringVar(master=self.root, value=self.appearance)
self.speed_value = tk.StringVar(master=self.root, value="")
self.speed_detail = tk.StringVar(master=self.root, value="Not running")
self._app_name = None
self._update_subtitle()
self._build_menus()
toolbar = tk.Frame(self.root, bg=PANEL)
toolbar.pack(fill="x", side="top")
bar = tk.Frame(toolbar, bg=PANEL)
bar.pack(fill="x", padx=10, pady=7)
self.shot_button = ttk.Button(bar, text="Screenshot", command=self._focus_after(self.screenshot))
self.shot_button.pack(side="right", padx=(6, 0))
self.reload_button = ttk.Button(bar, text="Restart", command=self._focus_after(self.reset))
self.reload_button.pack(side="right", padx=(6, 0))
self.pause_button = ttk.Button(bar, text="Pause", command=self._focus_after(self.toggle_pause))
self.pause_button.pack(side="right", padx=(6, 0))
self.pick_button = ttk.Button(bar, text="Open…", command=self._focus_after(self.open_file))
self.pick_button.pack(side="left")
tk.Frame(self.root, bg=LINE, height=1).pack(fill="x", side="top")
body = tk.Frame(self.root, bg=BG)
body.pack(fill="both", expand=True)
sidebar = tk.Frame(body, bg=PANEL, width=self.INSPECTOR_W)
sidebar.pack(side="right", fill="y")
sidebar.pack_propagate(False)
tk.Frame(body, bg=LINE, width=1).pack(side="right", fill="y")
self.canvas = tk.Canvas(body, bg=BG, bd=0, highlightthickness=0, takefocus=1)
self.canvas.pack(side="left", fill="both", expand=True)
self.screen_label = self.canvas
self.canvas.bind("<Configure>", self._resize)
self.canvas.bind("<ButtonPress-1>", self._mouse_press)
self.canvas.bind("<Motion>", self._mouse_move)
self.canvas.bind("<Leave>", self._mouse_leave)
self.root.bind("<Configure>", self._schedule_snap, add="+")
inner = tk.Frame(sidebar, bg=PANEL)
inner.pack(fill="both", expand=True, padx=16, pady=(12, 12))
wrap = self.INSPECTOR_W - 34
# Device
self._section(inner, "Device", first=True)
grid = tk.Frame(inner, bg=PANEL)
grid.pack(fill="x")
grid.grid_columnconfigure(1, weight=1)
for row, (label, var, values, command) in enumerate((
("Model", self.model_var, [k for k, _ in self.MODELS], self._change_model),
("Software", self.system_var, [k for k, _ in self.SYSTEMS], self._change_system),
("Speed", self.speed_var, list(self.SPEEDS), self._change_speed))):
tk.Label(grid, text=label, bg=PANEL, fg=FG, font=font(10), anchor="w").grid(
row=row, column=0, sticky="w", pady=3)
menu = ttk.OptionMenu(grid, var, var.get(), *values, command=lambda _v, c=command: c())
menu.grid(row=row, column=1, sticky="e", pady=3)
# Quick compiled app picker (only files from build/compiled).
self._section(inner, "Compiled Games")
self._compiled_choice = tk.StringVar(master=self.root, value="NumPlay.nwa")
self._compiled_picker = ttk.Combobox(inner, textvariable=self._compiled_choice,
state="readonly", width=30)
self._compiled_picker.pack(fill="x", pady=(2, 4))
self._compiled_picker.bind("<Button-1>", lambda _e: self._refresh_compiled_games())
self._compiled_picker.bind("<<ComboboxSelected>>", self._on_compiled_selection_changed)
self._refresh_compiled_games()
actions = tk.Frame(inner, bg=PANEL)
actions.pack(fill="x", pady=(0, 3))
ttk.Button(actions, text="Run", command=self._run_compiled_selection).pack(side="left")
ttk.Button(actions, text="Build + Run", command=self._build_compiled_selection).pack(side="left", padx=(5, 0))
# Live Build
self._section(inner, "Live Build")
ttk.Checkbutton(inner, text="Rebuild and reload when I save", variable=self.live_var,
command=self._live_checked).pack(anchor="w")
state = tk.Frame(inner, bg=PANEL)
state.pack(fill="x", pady=(6, 0))
self.build_dot = tk.Canvas(state, width=8, height=8, bg=PANEL, bd=0, highlightthickness=0)
self.build_dot.pack(side="left", padx=(1, 7))
self.build_dot_item = self.build_dot.create_oval(0, 0, 7, 7, fill=MUTED, outline="")
self.build_status_label = tk.Label(state, textvariable=self.build_status, bg=PANEL, fg=FG, font=font(10),
anchor="w", justify="left", wraplength=wrap - 16)
self.build_status_label.pack(side="left", fill="x")
self.build_info = tk.Label(inner, textvariable=self.build_detail, bg=PANEL, fg=MUTED, font=font(8),
anchor="w", justify="left", wraplength=wrap)
self.build_info.pack(fill="x", pady=(2, 0))
self.progress = ttk.Progressbar(inner, mode="indeterminate")
self.progress_after = self.build_info
log_row = tk.Frame(inner, bg=PANEL)
log_row.pack(fill="x", pady=(6, 0))
self.build_log_button = ttk.Button(log_row, text="Build Log", command=self._show_build_log)
self.build_log_button.pack(side="left")
# Speed
self._section(inner, "Speed")
speed = tk.Frame(inner, bg=PANEL)
speed.pack(fill="x")
tk.Label(speed, textvariable=self.speed_value, bg=PANEL, fg=FG, font=font(18, "bold"),
anchor="w").pack(side="left")
self.spark = tk.Canvas(speed, width=110, height=28, bg=PANEL, bd=0, highlightthickness=0)
self.spark.pack(side="right")
tk.Label(inner, textvariable=self.speed_detail, bg=PANEL, fg=MUTED, font=font(8), anchor="w",
justify="left", wraplength=wrap).pack(fill="x", pady=(2, 0))
# Keys Held
self._section(inner, "Keys Held")
self.chips = tk.Canvas(inner, height=24, bg=PANEL, bd=0, highlightthickness=0)
self.chips.pack(fill="x")
tk.Frame(inner, bg=PANEL).pack(fill="both", expand=True)
# Calculator: sending the app to a real one, only when asked
self._section(inner, "Calculator")
self.upload_status_label = tk.Label(inner, textvariable=self.upload_status, bg=PANEL, fg=MUTED,
font=font(8), wraplength=wrap, justify="left", anchor="w")
self.upload_status_label.pack(fill="x")
# (nwlink's own percentage when it gives one, else a bar that only says it is still running)
self.upload_progress_panel = tk.Frame(inner, bg=PANEL)
self.upload_progress = ttk.Progressbar(self.upload_progress_panel, mode="indeterminate", maximum=100)
self.upload_progress.pack(fill="x", pady=(5, 3))
tk.Label(self.upload_progress_panel, textvariable=self.upload_elapsed, bg=PANEL, fg=MUTED,
font=font(8), anchor="w").pack(fill="x")
tk.Label(self.upload_progress_panel, textvariable=self.upload_activity, bg=PANEL, fg=MUTED,
font=font(8), anchor="w", justify="left", wraplength=wrap).pack(fill="x", pady=(2, 0))
self.upload_button = ttk.Button(inner, text="Install on Calculator…", command=self._push_current_build)
self.upload_button.pack(anchor="w", pady=(6, 0))
tk.Frame(inner, bg=LINE, height=1).pack(fill="x", pady=(12, 8))
self.drop_line = tk.Label(inner, textvariable=self.status, bg=PANEL, fg=MUTED, font=font(8),
anchor="w", justify="left", wraplength=wrap)
self.drop_line.pack(fill="x")
self.status.set("Drop a .nwa on the calculator, or choose Open")
self._configure_mode_panel()
self._update_upload_controls()
self._draw_chips()
self.root.focus_force()
self.root.after(150, self.refocus_input)
def _build_menus(self):
"""The menu bar: what the app can do, where a Mac app keeps it."""
cmd, mac = self._cmd, self._aqua
acc = (lambda keys: keys) if mac else (lambda keys: keys.replace("Command-", "Ctrl+"))
bar = tk.Menu(self.root)
if mac:
app = tk.Menu(bar, name="apple", tearoff=0)
app.add_command(label="About NumPlay Simulator",
command=lambda: webbrowser.open("https://github.com/Mason363/NumPlay"))
bar.add_cascade(menu=app)
def bind(seq, action):
self.root.bind_all(f"<{cmd}-{seq}>", lambda e: (action(), "break")[1])
m = tk.Menu(bar, tearoff=0)
m.add_command(label="Open App…", accelerator=acc("Command-O"), command=self._focus_after(self.open_file))
m.add_command(label="Take Screenshot", accelerator=acc("Command-S"), command=self._focus_after(self.screenshot))
m.add_separator()
m.add_command(label="Install on Calculator…", accelerator=acc("Command-I"), command=self._push_current_build)
m.add_command(label="Show Built Apps", command=self._open_dist)
bar.add_cascade(label="File", menu=m)
bind("o", self.open_file)
bind("s", self.screenshot)
bind("i", self._push_current_build)
m = tk.Menu(bar, tearoff=0)
m.add_radiobutton(label="Calculator", variable=self.view_var, value="calculator",
accelerator=acc("Command-1"), command=self._switch_view)
m.add_radiobutton(label="Screen Only, Actual Size", variable=self.view_var, value="screen",
accelerator=acc("Command-2"), command=self._switch_view)
m.add_separator()
look = tk.Menu(m, tearoff=0)
for label, value in (("Like the System", "system"), ("Light", "light"), ("Dark", "dark")):
look.add_radiobutton(label=label, variable=self.appearance_var, value=value,
command=lambda: self._set_appearance(self.appearance_var.get()))
m.add_cascade(label="Appearance", menu=look)
m.add_separator()
m.add_command(label="Enter Full Screen", accelerator=acc("Command-F"), command=self.toggle_fullscreen)
bar.add_cascade(label="View", menu=m)
bind("1", lambda: (self.view_var.set("calculator"), self._switch_view()))
bind("2", lambda: (self.view_var.set("screen"), self._switch_view()))
bind("f", self.toggle_fullscreen)
m = tk.Menu(bar, tearoff=0)
m.add_command(label="Home", accelerator=acc("Shift-Command-H"), command=lambda: self._tap("home"))
m.add_command(label="Restart App", accelerator=acc("Command-R"), command=self._focus_after(self.reset))
m.add_command(label="Pause or Resume", accelerator=acc("Command-P"), command=self.toggle_pause)
m.add_command(label="Turn Off or On", command=self.power_button)
m.add_separator()
sub = tk.Menu(m, tearoff=0)
for label, _ in self.MODELS:
sub.add_radiobutton(label=label, variable=self.model_var, value=label, command=self._change_model)
m.add_cascade(label="Model", menu=sub)
sub = tk.Menu(m, tearoff=0)
for label, _ in self.SYSTEMS:
sub.add_radiobutton(label=label, variable=self.system_var, value=label, command=self._change_system)
m.add_cascade(label="Software", menu=sub)
sub = tk.Menu(m, tearoff=0)
for label in self.SPEEDS:
sub.add_radiobutton(label=label, variable=self.speed_var, value=label, command=self._change_speed)
m.add_cascade(label="Speed", menu=sub)
bar.add_cascade(label="Device", menu=m)
self.root.bind_all(f"<Shift-{cmd}-H>", lambda e: (self._tap("home"), "break")[1])
self.root.bind_all(f"<Shift-{cmd}-h>", lambda e: (self._tap("home"), "break")[1])
bind("r", self.reset)
bind("p", self.toggle_pause)
m = tk.Menu(bar, tearoff=0)
m.add_checkbutton(label="Rebuild and Reload When I Save", variable=self.live_var,
accelerator=acc("Command-B"), command=self._live_checked)
m.add_command(label="Show Build Log", accelerator=acc("Command-L"), command=self._show_build_log)
m.add_command(label="Show USB Log", command=self._show_upload_log)
bar.add_cascade(label="Build", menu=m)
bind("b", lambda: (self.live_var.set(not self.live_var.get()), self._live_checked()))
bind("l", self._show_build_log)
if mac:
bar.add_cascade(menu=tk.Menu(bar, name="window", tearoff=0), label="Window")
m = tk.Menu(bar, name="help" if mac else None, tearoff=0)
m.add_command(label="Keyboard Shortcuts", command=self.show_keymap)
m.add_command(label="Make Your Own Game",
command=lambda: webbrowser.open("https://github.com/Mason363/NumPlay/blob/main/docs/make-a-game.md"))
m.add_command(label="NumWorks Web Installer", command=lambda: webbrowser.open("https://my.numworks.com/apps"))
bar.add_cascade(label="Help", menu=m)
self.root.configure(menu=bar)
self._menubar = bar
def _tap(self, key):
"""A calculator key pressed for a moment (the menus' Home)."""
self.on_mouse_down(key)
self.root.after(120, self.on_mouse_up)
def _update_subtitle(self):
"""The window's title: the app, then the calculator it runs on (as Simulator names its device)."""
model = dict((v, k) for k, v in self.MODELS)[self.model]
system = dict((v, k) for k, v in self.SYSTEMS)[self.system]
device = f"NumWorks {model} · {system}"
self.root.title(f"{self._app_name} · {device}" if self._app_name else device)
def _change_model(self):
self.model = dict(self.MODELS)[self.model_var.get()]
self._update_subtitle()
self._change_speed(quiet=True)
self._restart_for_device(f"Now an {self.model_var.get()}")
def _change_system(self):
self.system = dict(self.SYSTEMS)[self.system_var.get()]
self._update_subtitle()
self._restart_for_device(f"Now running {self.system_var.get()}")
def _restart_for_device(self, message):
if self.current is not None:
self.load(self.current)
self.set_status(message)
def _change_speed(self, quiet=False):
choice = self.speed_var.get()
self.auto_clock[0] = choice == self.SPEEDS[1]
if self.auto_clock[0]:
# (the adaptive clock was tuned around 216 MHz: it starts there, not with a jump from 550)
self.clock_mhz[0] = 216
elif choice == self.SPEEDS[0]:
self.clock_mhz[0] = 550 if self.model == "n0120" else 216
else:
self.clock_mhz[0] = int(choice.split()[0])
if not quiet:
self.set_status("Speed follows this computer, so timing may differ from a calculator"
if self.auto_clock[0] else f"The processor runs at {self.clock_mhz[0]} MHz")
def _live_checked(self):
self.mode_var.set("live" if self.live_var.get() else "file")
self._switch_mode()
def _set_appearance(self, choice, *, initial=False):
"""Light, dark, or the system's: the window, its controls (aqua) and the colours drawn here."""
self.appearance = choice
if self._aqua:
try:
self.root.tk.call("::tk::unsupported::MacWindowStyle", "appearance", self.root._w,
{"light": "aqua", "dark": "darkaqua"}.get(choice, "auto"))
except tk.TclError:
pass
if not initial:
try:
_save_setting("theme", choice)
except OSError as exc:
self.set_status(f"Could not keep the appearance for next time: {exc}")
self._follow_appearance()
def _is_dark(self):
if self.appearance in ("light", "dark"):
return self.appearance == "dark"
if self._aqua:
try:
return bool(int(self.root.tk.call("::tk::unsupported::MacWindowStyle", "isdark", self.root._w)))
except (tk.TclError, ValueError):
return False
return False
def _follow_appearance(self):
want = "dark" if self._is_dark() else "light"
if want != CURRENT_THEME:
self._apply_interface_theme(want)
def _apply_interface_theme(self, requested=None, *, initial=False):
"""Repaint the Tk widgets in the other palette, without restarting the emulator or the builder."""
previous = THEME_PALETTES[CURRENT_THEME]
if requested is not None:
_activate_theme_palette(requested)
updated = THEME_PALETTES[CURRENT_THEME]
mapping = {old.lower(): updated[key] for key, old in previous.items()}
tk_options = ("background", "foreground", "activebackground", "activeforeground", "selectcolor",
"disabledforeground", "highlightbackground", "highlightcolor", "insertbackground",
"troughcolor")
visited = set()
def paint(widget):
if str(widget) in visited:
return
visited.add(str(widget))
try:
options = set(widget.keys())
changes = {}
for option in tk_options:
if option in options:
value = str(widget.cget(option)).lower()
if value in mapping and mapping[value] != value:
changes[option] = mapping[value]
if changes:
widget.configure(**changes)
for child in widget.winfo_children():
paint(child)
except tk.TclError:
pass
paint(self.root)
self.root.configure(bg=BG)
if not getattr(self, "_aqua", False):
try:
style = ttk.Style(self.root)
style.theme_use("clam")
style.configure(".", background=PANEL, foreground=FG)
style.configure("TButton", background=PANEL_2, foreground=FG)
style.map("TButton",
foreground=[("disabled", MUTED), ("pressed", FG), ("active", FG)],
background=[("pressed", SELECT), ("active", HOVER)])
style.configure("TCheckbutton", background=PANEL, foreground=FG)
style.map("TCheckbutton",
foreground=[("disabled", MUTED), ("active", FG)],
background=[("active", PANEL)])
style.configure("TMenubutton", background=PANEL_2, foreground=FG)
style.map("TMenubutton",
foreground=[("disabled", MUTED), ("pressed", FG), ("active", FG)],
background=[("pressed", SELECT), ("active", HOVER)])
style.configure("TCombobox", foreground=FG, fieldbackground=PANEL_2,
background=PANEL_2, arrowcolor=FG)
style.map("TCombobox", foreground=[("readonly", FG), ("disabled", MUTED)],
fieldbackground=[("readonly", PANEL_2)],
background=[("active", HOVER)])
style.configure("Horizontal.TProgressbar", background=ACCENT, troughcolor=PANEL_2)
except tk.TclError:
pass
# the calculator's picture on the new background (its edges are see-through), the rest drawn again
self.art = self._art_on(BG)
self._art_geometry = (0, 0, 0, 0)
try:
self.build_dot.itemconfigure(self.build_dot_item, fill=self._dot_colour())
self._draw_spark()
self._draw_chips()
self._resize()
self.canvas.itemconfigure("native-border", outline=LINE)
self._draw_highlight()
except (tk.TclError, AttributeError):
pass
def _section(self, parent, title, first=False):
if not first:
tk.Frame(parent, bg=LINE, height=1).pack(fill="x", pady=(14, 10))
label = tk.Label(parent, text=title, bg=PANEL, fg=FG, font=font(10, "bold"), anchor="w")
label.pack(fill="x", pady=(0, 6))
return label
def _button(self, parent, label, callback, primary=False):
return ttk.Button(parent, text=label, command=self._focus_after(callback))
def _focus_after(self, action):
def call():
try:
action()
finally:
self.root.after(75, self.refocus_input)
return call
def _configure_mode_panel(self):
live = self.mode_var.get() == "live"
self.live_var.set(live)
if not live:
self._set_build_state("Off", "Opens one .nwa. Turn this on to build NumPlay again each time you save "
"a file, and reload it.")
def _compiled_choices(self):
"""Offer every known app before it has been built, not just files on disk.
A game is built on demand by `tools/build.py --game ID`. Discover its
release filename from the manifest and the same APP_ assignments used
by the root Makefile, including special-layout games.
"""
root = REPO_ROOT / "build" / "compiled"
filenames = [
"NumPlay.nwa", "NumPlay-Invisible.nwa", "NumPlay-Matrices.nwa",
"NumPlay-Upsilon.nwa", "NumPlay-French.nwa", "NumPlay-Chinese.nwa",
]
manifest = json.loads((REPO_ROOT / "games" / "games.json").read_text(encoding="utf-8"))
game_names = {record["app"] for record in manifest if record.get("app")}
makefile = (REPO_ROOT / "Makefile").read_text(encoding="utf-8")
game_names.update(re.findall(
r"(?m)^APP_\w+\s*=\s*[^:\n]+:(\S+\.nwa)\s*$", makefile))
filenames.extend("games/" + name for name in sorted(game_names, key=str.casefold))
# Keep any existing nonstandard exported files reachable, too.
filenames.extend(p.relative_to(root).as_posix() for p in root.glob("NumPlay-*.nwa") if p.is_file())
filenames.extend(p.relative_to(root).as_posix() for p in (root / "games").glob("*.nwa") if p.is_file())
return [root / name for name in dict.fromkeys(filenames)]
def _refresh_compiled_games(self):
paths = self._compiled_choices()
self._compiled_paths = {str(p.relative_to(REPO_ROOT / "build" / "compiled")): p for p in paths}
self._compiled_picker.configure(values=list(self._compiled_paths))
if not self._compiled_choice.get() or self._compiled_choice.get() not in self._compiled_paths:
if self._compiled_paths:
self._compiled_choice.set(next(iter(self._compiled_paths)))
def _on_compiled_selection_changed(self, _event=None):
"""Retarget an active live watcher; never let two builds run together."""
if self.mode_var.get() != "live" or self._closing:
return
selected = self._compiled_choice.get()
self._stop_builder()
self._set_build_state("Switching live target", selected, busy=True)
# _start_builder waits for the stopped process tree on Windows before
# starting a new compiler. It reads the *current* selection then.
self._start_builder()
def _selected_compiled_path(self):
return (REPO_ROOT / "build" / "compiled" / self._compiled_choice.get()).resolve()
def _game_id_for_compiled(self, path):
import json
if path.parent.name != "games":
return None
manifest = json.loads((REPO_ROOT / "games" / "games.json").read_text(encoding="utf-8"))
for record in manifest:
if record.get("app") == path.name:
return record["id"]
for item in re.finditer(r"(?m)^APP_(\w+)\s*=\s*[^:\n]+:(\S+\.nwa)\s*$",
(REPO_ROOT / "Makefile").read_text(encoding="utf-8")):
if item.group(2) == path.name:
return item.group(1)
return None
def _run_compiled_selection(self):
path = self._selected_compiled_path()
if not path.is_file():
self._set_build_state("Not built yet", "Build the selected app first", error=True)
return
self.mode_var.set("file")
self._switch_mode()
self.load(path)
def _build_compiled_selection(self):
if self.mode_var.get() == "live":
self._stop_builder()
self.mode_var.set("live")
self.live_var.set(True)
self._switch_mode()
def _switch_mode(self):
self._configure_mode_panel()
self.watch_candidate = None
self.follow_var.set(False)
if self.mode_var.get() == "live":
self.watch_var.set(True)
self._start_builder()
else:
self.watch_var.set(False)
self._stop_builder()
self._configure_mode_panel()
self._update_upload_controls()
self.root.after(75, self.refocus_input)
def open_file(self):
if self.mode_var.get() != "file":
self.mode_var.set("file")
self._switch_mode()
# Calling the existing picker preserves file handling and focus.
super().open_file()
def on_drop(self, event):
if self.mode_var.get() != "file":
self.mode_var.set("file")
self._switch_mode()
super().on_drop(event)
def watch(self):
"""Never search for a vague newest build or reload single-file mode."""
if self._closing:
return
if (self.mode_var.get() == "live" and self.watch_var.get() and
self._builder_ready and self.current == self._selected_compiled_path()):
try:
self._maybe_reload(self._selected_compiled_path())
except OSError as exc:
self.build_status.set("Live reload check failed")
self.build_detail.set(str(exc)[:140])
self._watch_id = self.root.after(WATCH_MS, self.watch)
def _set_build_state(self, status, detail="", *, busy=False, error=False):
self.build_status.set(status)
self.build_detail.set(detail)
self._build_error = error
try:
self.build_dot.itemconfigure(self.build_dot_item, fill=self._dot_colour(busy))
self.build_status_label.configure(fg=RED if error else FG)
except (tk.TclError, AttributeError):
pass
if busy != self._builder_busy:
self._builder_busy = busy
if busy:
self.progress.pack(fill="x", pady=(6, 0), after=self.progress_after)
self.progress.start(11)
else:
self.progress.stop()
self.progress.pack_forget()
def _dot_colour(self, busy=None):
busy = self._builder_busy if busy is None else busy
if getattr(self, "_build_error", False):
return RED
if busy:
return ORANGE
if self.mode_var.get() == "live" and self.build_process is not None:
return GREEN
return MUTED
def _toggle_builder(self):
if self.build_process and self.build_process.poll() is None:
self._stop_builder()
self._set_build_state("Watcher stopped", "Turn Rebuild and reload back on to start again")
else:
self._start_builder()
def _start_builder(self):
if self._closing or self.mode_var.get() != "live":
return
if self.build_process is not None and self.build_process.poll() is None:
return
if not BUILD_SCRIPT.is_file():
self._set_build_state("Builder not found", f"Expected tools/{BUILD_SCRIPT.name}", error=True)
messagebox.showerror("Live build", f"Missing build script:\n{BUILD_SCRIPT}")
return
# A previous process may still be shutting down. Never run concurrent
# builds of the same directory.
if self._builder_stopping:
self.root.after(200, self._start_builder)
return
self._builder_generation += 1
generation = self._builder_generation
self._builder_ready = False
self._builder_has_error = False
self._builder_log.clear()
self.watch_candidate = None
self.watch_var.set(True)
selected = self._selected_compiled_path()
game_id = self._game_id_for_compiled(selected) if selected else None
if selected.parent.name == "games" and not game_id:
self._set_build_state("Unknown standalone game", selected.name, error=True)
return
cmd = [sys.executable, "-u", str(BUILD_SCRIPT), "--watch", "-j2"]
if game_id:
# Only this game's sources compile; no full NumPlay launcher rebuild.
cmd.extend(["--game", game_id])
else:
cmd.append("--launcher-only")
if selected.name not in ("NumPlay-French.nwa", "NumPlay-Chinese.nwa"):
cmd.append("--skip-languages")
flags = subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
try:
self.build_process = subprocess.Popen(cmd, cwd=str(REPO_ROOT),
stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
text=True, encoding="utf-8", errors="replace",
bufsize=1, creationflags=flags,
start_new_session=(os.name != "nt"))
except OSError as exc:
self._set_build_state("Cannot start compiler", str(exc), error=True)
self.build_process = None
return
self._set_build_state("Starting the compiler", "Checking dependencies", busy=True)
thread = threading.Thread(target=self._read_builder_output,
args=(generation, self.build_process), daemon=True)
thread.start()
def _read_builder_output(self, generation, process):
"""Read compiler output off Tk's thread; never block the calculator UI."""
try:
if process.stdout is not None:
for line in process.stdout:
self._builder_events.put((generation, "line", line.rstrip("\r\n")))
except (OSError, ValueError) as exc:
self._builder_events.put((generation, "line", f"Compiler output error: {exc}"))
finally:
rc = process.wait()
self._builder_events.put((generation, "ended", rc))
def _stop_builder(self):
process = self.build_process
self._builder_generation += 1 # Ignore stale lines from a stopped watch.
self._builder_ready = False
self.watch_var.set(False)
self.watch_candidate = None
self.build_process = None
self._set_build_state("Stopped" if self.mode_var.get() == "live" else "Off",
"Not building" if self.mode_var.get() == "live" else self.build_detail.get(), busy=False)
if process is None or process.poll() is not None:
return
self._builder_stopping = True
# Start terminating the process tree *before* closing Tk. If shutdown
# were deferred entirely to a daemon thread, the Python process could
# exit first and leave an orphaned Windows watcher running.
try:
if os.name == "nt":
subprocess.Popen(["taskkill", "/PID", str(process.pid), "/T", "/F"],
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
else:
os.killpg(process.pid, signal.SIGTERM)
except OSError:
try:
process.terminate()
except OSError:
pass
def wait_for_stopped():
try:
process.wait(timeout=7)
except subprocess.TimeoutExpired:
try:
process.kill()
process.wait(timeout=2)
except (OSError, subprocess.TimeoutExpired):
pass
finally:
self._builder_events.put((None, "stopped", None))
threading.Thread(target=wait_for_stopped, daemon=True).start()
def _poll_builder(self):
if self._closing:
return
count = 0
while count < 240:
try:
generation, kind, value = self._builder_events.get_nowait()
except queue.Empty:
break
count += 1
if kind == "stopped":
self._builder_stopping = False
continue
if generation != self._builder_generation:
continue
if kind == "ended":
self.build_process = None
self.watch_var.set(False)
if value != 0:
self._set_build_state("Compiler stopped unexpectedly",
f"Exit code {value}. See the Build Log", error=True)
else:
self._set_build_state("Watcher stopped", "No longer monitoring edits")
continue
line = value
self._builder_log.append(line)
self._append_log(line)
if "Detected edits (" in line:
self._builder_has_error = False
self._set_build_state("Changes detected", "Rebuilding NumPlay", busy=True)
elif "Building:" in line:
self._set_build_state("Compiling NumPlay", "Source files and game modules", busy=True)
elif "Preparing temporary Windows nwlink" in line:
self._set_build_state("Preparing compiler", "Rust and ARM tools", busy=True)
elif "SUCCESS: organized" in line:
self._set_build_state("Publishing compiled app", "Finishing the live .nwa", busy=True)
elif "Stable live-emulator input:" in line:
self._builder_has_error = False
self._builder_ready = True
self._set_build_state("Built", f"Reloading {self._compiled_choice.get()}", busy=False)
if self.mode_var.get() == "live" and self._selected_compiled_path().is_file():
# Emulation runs in its own thread and will stop gracefully
# before loading the atomically replaced file.
self.load(self._selected_compiled_path())
elif ("Build failed;" in line or "Initial build failed" in line or
"Windows build failed:" in line):
self._builder_has_error = True
self._set_build_state("Build failed", "The last good app stays. See the Build Log",
busy=False, error=True)
elif "Watching for the next edit" in line or "Watching NumPlay source files" in line:
if self._builder_has_error:
self._set_build_state("Build failed, watching", "Fix and save code to retry",
busy=False, error=True)
else:
self._set_build_state("Watching for changes", "Edit and save a game to rebuild",
busy=False)
self._update_upload_controls()
self._builder_poll_id = self.root.after(120, self._poll_builder)
def _append_log(self, line):
box = self._build_log_text
if box is not None:
try:
box.configure(state="normal")
box.insert("end", line + "\n")
# Trim long-running logs to avoid unbounded Tk memory usage.
if int(box.index("end-1c").split(".")[0]) > 870:
box.delete("1.0", "120.0")
box.see("end")
box.configure(state="disabled")
except tk.TclError:
self._build_log_text = None
def _show_build_log(self):
if self._build_log_window is not None:
try:
self._build_log_window.lift()
self._build_log_window.focus_set()
return
except tk.TclError:
self._build_log_window = None
win = tk.Toplevel(self.root)
win.title("Build log")
win.geometry("790x480")
win.configure(bg=BG)
frame = tk.Frame(win, bg=BG)
frame.pack(fill="both", expand=True, padx=8, pady=8)
scroll = tk.Scrollbar(frame)
scroll.pack(side="right", fill="y")
box = tk.Text(frame, bg=PANEL, fg=FG, relief="flat", bd=0,
font=mono(9), padx=10, pady=10, wrap="none",
yscrollcommand=scroll.set)
box.pack(side="left", fill="both", expand=True)
scroll.configure(command=box.yview)
box.insert("end", "\n".join(self._builder_log) or "No compilation output yet.")
box.configure(state="disabled")
self._build_log_window = win
self._build_log_text = box
def close():
self._build_log_window = None
self._build_log_text = None
win.destroy()
win.protocol("WM_DELETE_WINDOW", close)
def _open_dist(self):
path = REPO_ROOT / "build" / "compiled"
path.mkdir(parents=True, exist_ok=True)
if os.name == "nt":
os.startfile(str(path))
elif sys.platform == "darwin":
subprocess.Popen(["open", str(path)])
else:
self.set_status(f"Compiled files: {path}")
def _upload_source(self):
"""Choose exactly what the user is looking at, never a random newest app."""
if self.mode_var.get() == "live":
if self._builder_busy or not self._builder_ready:
return None
return self._selected_compiled_path()
return self.current
def _update_upload_controls(self):
if not hasattr(self, "upload_button"):
return
source = self._upload_source()
available = (not self._upload_running and source is not None
and source.is_file() and source.suffix.lower() == ".nwa")
self.upload_button.configure(state="normal" if available else "disabled",
text="Installing…" if self._upload_running else "Install on Calculator…")
def _show_upload_log(self):
"""A small live log for USB details that nwlink prints to stdout."""
if self._upload_log_window is not None:
try:
self._upload_log_window.lift()
self._upload_log_window.focus_force()
return
except tk.TclError:
self._upload_log_window = None
win = tk.Toplevel(self.root)
win.title("USB log")
win.geometry("680x350")
win.configure(bg=BG)
frame = tk.Frame(win, bg=BG)
frame.pack(fill="both", expand=True, padx=8, pady=8)
scroll = tk.Scrollbar(frame)
scroll.pack(side="right", fill="y")
box = tk.Text(frame, bg=PANEL, fg=FG, relief="flat", bd=0,
font=mono(9), padx=10, pady=10, wrap="word",
yscrollcommand=scroll.set)
box.pack(side="left", fill="both", expand=True)
scroll.configure(command=box.yview)
box.insert("end", "\n".join(self._upload_log) or "No USB install activity yet.")
box.configure(state="disabled")
self._upload_log_window = win
self._upload_log_text = box
def close():
self._upload_log_window = None
self._upload_log_text = None
win.destroy()
win.protocol("WM_DELETE_WINDOW", close)
def _append_upload_log(self, line: str):
self._upload_log.append(line)
box = self._upload_log_text
if box is not None:
try:
box.configure(state="normal")
box.insert("end", line + "\n")
box.see("end")
box.configure(state="disabled")
except tk.TclError:
self._upload_log_window = None
self._upload_log_text = None
def _push_current_build(self):
"""Physical USB install: deliberately NEVER called by the build watcher."""
if self._upload_running:
return
source = self._upload_source()
if source is None or not source.is_file() or source.suffix.lower() != ".nwa":
messagebox.showwarning("Push to NumWorks", "No finished .nwa is ready.\n\n"
"Choose a file or finish a successful Live build first.",
parent=self.root)
return
try:
source = source.resolve(strict=True)
if source.stat().st_size < 1024:
raise ValueError("The .nwa file is unusually small")
# Snapshot BEFORE confirmation; a concurrent compiler can publish a
# new file without changing the exact bytes chosen for this push.
snapshot_dir = tempfile.TemporaryDirectory(prefix="numplay-usb-push-")
snapshot = Path(snapshot_dir.name) / source.name
shutil.copy2(source, snapshot)
except (OSError, ValueError) as exc:
try:
snapshot_dir.cleanup()
except (NameError, OSError):
pass
messagebox.showerror("Push to NumWorks", f"Cannot prepare .nwa:\n{exc}",
parent=self.root)
return
warning = (
f"Send {source.name} ({snapshot.stat().st_size:,} bytes) to your real NumWorks?\n\n"
"WARNING: nwlink install-nwa REPLACES the calculator's installed "
"third-party applications; it does not just patch NumPlay. "
"Saved application data may be affected.\n\n"
"Back up important data and keep copies of any other apps you want to reinstall.\n\n"
"Connect the calculator with USB and leave it on its CONNECTED screen. "
"Close any NumWorks browser tab that is using the USB connection. "
"Do NOT unplug the cable until installation finishes.\n\n"
"Proceed with this potentially destructive USB installation?"
)
if not messagebox.askyesno("Confirm calculator installation", warning,
icon="warning", parent=self.root, default="no"):
snapshot_dir.cleanup()
return
self._upload_running = True
self._upload_start_wall = time.monotonic()
self._upload_progress_is_reported = False
self._upload_log.clear()
self._append_upload_log(f"Installing {source.name} ({snapshot.stat().st_size:,} bytes)")
self.upload_status.set("Starting USB installer")
self.upload_activity.set("Waiting for nwlink to connect to the calculator")
self.upload_elapsed.set("Elapsed: 0 s, Keep USB connected")
self.upload_progress.configure(mode="indeterminate")
self.upload_progress_panel.pack(fill="x", pady=(2, 7), after=self.upload_status_label)
self.upload_progress.start(12)
self.set_status("Installing on the calculator. Keep it plugged in")
self._update_upload_controls()
threading.Thread(target=self._upload_worker,
args=(snapshot, snapshot_dir), daemon=True).start()
def _upload_worker(self, snapshot: Path, snapshot_dir):
"""Run the installer off Tk's thread, STREAMING its output to the UI.
nwlink's CLI may suppress numeric progress when stdout isn't a TTY;
in that case the UI uses a genuine indeterminate activity bar instead
of inventing completion percentages.
"""
try:
cmd = [self.nwlink, "install-nwa", str(snapshot)]
flags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
with subprocess.Popen(cmd, cwd=str(REPO_ROOT),
stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
text=True, encoding="utf-8", errors="replace",
stdin=subprocess.DEVNULL, creationflags=flags,
bufsize=1) as proc:
self._upload_events.put(("started", None))
if proc.stdout is not None:
for raw in proc.stdout:
# Strip ANSI sequences and control chars. Progress
# tools sometimes redraw a line with CR rather than NL.
for part in re.split(r"[\r\n]+", raw):
part = re.sub(r"\x1b\[[0-9;]*[A-Za-z]", "", part).strip()
if part:
self._upload_events.put(("line", part[-450:]))
returncode = proc.wait()
self._upload_events.put(("done", returncode))
except Exception as exc:
self._upload_events.put(("error", str(exc)))
finally:
snapshot_dir.cleanup()
def _poll_upload(self):
if self._closing:
return
# A clock is honest even if nwlink doesn't print transfer progress.
if self._upload_running and self._upload_start_wall is not None:
elapsed = int(max(0, time.monotonic() - self._upload_start_wall))
self.upload_elapsed.set(f"Elapsed: {elapsed} s, Keep USB connected")
while True:
try:
kind, value = self._upload_events.get_nowait()
except queue.Empty:
break
if kind == "started":
self.upload_status.set("USB installer running")
self.upload_activity.set("Connecting / transferring, Waiting for nwlink")
continue
if kind == "line":
line = str(value)
self._append_upload_log(line)
# Honor a real percentage IF nwlink prints one. It describes
# the CURRENT CLI operation, not necessarily whole-file upload.
match = re.search(r"(?<!\d)(100|[1-9]?\d)(?:\.\d+)?\s*%", line)
if match:
pct = int(match.group(1))
if not self._upload_progress_is_reported:
self.upload_progress.stop()
self.upload_progress.configure(mode="determinate", value=pct)
self._upload_progress_is_reported = True
else:
self.upload_progress.configure(value=pct)
self.upload_activity.set(f"nwlink reports {pct}% for its current operation")
else:
self.upload_activity.set(f"nwlink: {line[:130]}")
continue
self._upload_running = False
self._upload_start_wall = None
self.upload_progress.stop()
self.upload_progress_panel.pack_forget()
if kind == "done":
code = int(value)
if code == 0:
self.upload_status.set("Installed on the calculator")
self.set_status("NumWorks installation reported success")
self._append_upload_log("nwlink exited with code 0 (success)")
messagebox.showinfo("NumWorks", "nwlink reported a successful upload.\n\n"
"Check the calculator for the newly installed app.",
parent=self.root)
else:
self.upload_status.set(f"USB install failed (exit {code})")
self._append_upload_log(f"nwlink exited with code {code}")
self._upload_failure("\n".join(list(self._upload_log)[-14:]) or
f"nwlink exited with code {code}")
elif kind == "error":
self.upload_status.set("USB install could not start")
self._append_upload_log(f"Error: {value}")
self._upload_failure(str(value))
self._update_upload_controls()
self._upload_poll_id = self.root.after(160, self._poll_upload)
def _upload_failure(self, detail):
self.set_status("The install didn't finish. The .nwa is still safe on this computer")
msg = ("The USB installer reported a problem:\n\n" + detail[-1700:] +
"\n\nCheck the cable and calculator connection. "
"The NumWorks website is an alternative.\n\n"
"Open https://my.numworks.com/apps now?")
if messagebox.askyesno("USB upload failed", msg, parent=self.root):
webbrowser.open("https://my.numworks.com/apps")
def on_close(self):
if self._upload_running:
messagebox.showwarning("USB installation in progress",
"Please let nwlink finish before closing the emulator. "
"Do NOT unplug the NumWorks during installation.",
parent=self.root)
return
self._save_window_placement()
try:
self.root.after_cancel(self._upload_poll_id)
except (tk.TclError, AttributeError):
pass
self._stop_builder()
try:
self.root.after_cancel(self._builder_poll_id)
except (tk.TclError, AttributeError):
pass
super().on_close()
def toggle_fullscreen(self):
self.fullscreen = not self.fullscreen
self.root.attributes("-fullscreen", self.fullscreen)
# Force the image to refit after the window manager changes its size.
self.root.after(50, self._resize)
def on_pc_down(self, event):
if event.keysym.lower() == "f11":
if not self.f11_down:
self.f11_down = True
self.toggle_fullscreen()
return "break"
return super().on_pc_down(event)
def on_pc_up(self, event):
if event.keysym.lower() == "f11":
self.f11_down = False
return "break"
return super().on_pc_up(event)
def change_clock(self, selected):
if self.auto_clock[0]:
return
self.clock_mhz[0] = int(selected.split()[0])
self.rate_label.set("Measuring real-time speed")
self.set_status(f"Manual CPU clock set to {self.clock_mhz[0]} MHz")
def _switch_view(self):
"""Switch the viewport only; the running game/keyboard/build are untouched."""
self._hover = None
# A held mouse key was pressed on a key that disappears in screen view.
# Release it to avoid a stuck calculator button.
self.on_mouse_up()
self.canvas.configure(cursor="arrow")
self._native_geometry = None
self._art_geometry = (0, 0, 0, 0)
self._canvas_screen = None
self._canvas_image = None
self._bg_photo = None
self.canvas.delete("all")
self._resize()
self.refocus_input()
def present_screen(self):
self._display_screen()
def _resize(self, event=None):
ww = self.canvas.winfo_width()
hh = self.canvas.winfo_height()
if ww < 20 or hh < 20:
return
if self.view_var.get() == "screen":
# A native 320x240 LCD. Its bitmap is NEVER resized, even if the
# window is larger, smaller, or maximized. Only its position moves.
x = (ww - LCD_WIDTH) // 2
y = (hh - LCD_HEIGHT) // 2
geom = (x, y)
if geom != self._native_geometry:
self._native_geometry = geom
# A one-pixel surround is outside the image; the image itself
# contains exactly 320x240 framebuffer pixels.
self.canvas.delete("native-border")
self.canvas.create_rectangle(x-1, y-1, x+LCD_WIDTH, y+LCD_HEIGHT,
outline=LINE, width=1,
tags="native-border")
self._display_screen()
return
# the calculator as big as its side of the window holds, edge to edge
ratio = self.art_px[0] / self.art_px[1]
art_w = max(1, int(min(ww, hh * ratio)))
art_h = max(1, int(art_w / ratio))
x0 = (ww - art_w) // 2
y0 = (hh - art_h) // 2
geom = (x0, y0, art_w, art_h)
if geom == self._art_geometry:
return
self._art_geometry = geom
self._bg_photo = ImageTk.PhotoImage(self.art.resize((art_w, art_h), Image.Resampling.LANCZOS))
self.canvas.delete("all")
self._canvas_image = self.canvas.create_image(x0, y0, image=self._bg_photo, anchor="nw", tags="art")
self._canvas_screen = None
self._sprites.clear()
if self._screen_rgb is None:
sx, sy, sw, sh = self._rect(SCREEN)
self.canvas.create_text(sx + sw // 2, sy + sh // 2, tags="hint", fill="#8e8e93", font=font(10),
width=sw - 40, justify="center",
text="Drop a .nwa here, or choose Open")
self._display_screen()
self._draw_highlight()
def _rect(self, rect):
x0, y0, aw, ah = self._art_geometry
x, y, w, h = rect
return (round(x0 + x * aw), round(y0 + y * ah),
max(1, round(w * aw)), max(1, round(h * ah)))
def _display_screen(self):
if self._screen_rgb is None:
return
if self.view_var.get() == "screen":
# No PIL resize (not even NEAREST): one bitmap pixel maps to one
# Tk image pixel. The native framebuffer must be exactly 320x240.
if self._screen_rgb.size != (LCD_WIDTH, LCD_HEIGHT):
raise ValueError(f"Expected 320x240 LCD; got {self._screen_rgb.size}")
if self._native_geometry is None:
return
x, y = self._native_geometry
photo = ImageTk.PhotoImage(self._screen_rgb)
else:
x, y, w, h = self._rect(SCREEN)
photo = ImageTk.PhotoImage(self._screen_rgb.resize((w, h), Image.Resampling.NEAREST))
self._photo = photo
self.canvas.delete("hint")
if self._canvas_screen is None or not self.canvas.find_withtag("screen"):
self._canvas_screen = self.canvas.create_image(x, y, image=photo, anchor="nw", tags="screen")
else:
self.canvas.itemconfigure(self._canvas_screen, image=photo)
self.canvas.coords(self._canvas_screen, x, y)
def _key_at(self, x, y) -> str | None:
if self.view_var.get() == "screen" or self._art_geometry[2] == 0:
return None
# A few nav keys' rectangular touch regions overlap: choose the closest
# *center* of a containing key, consistent with the visible button art.
matched = []
for key, bounds in HOTSPOTS.items():
bx, by, bw, bh = self._rect(bounds)
if bx <= x <= bx + bw and by <= y <= by + bh:
center_distance = ((x - bx - bw / 2) / bw) ** 2 + ((y - by - bh / 2) / bh) ** 2
matched.append((center_distance, key))
return min(matched)[1] if matched else None
def _sprite(self, key, state, w, h):
cache = (key, state, w, h)
if cache not in self._sprites:
self._sprites[cache] = ImageTk.PhotoImage(key_sprite(key, w, h, state))
return self._sprites[cache]
def _draw_highlight(self):
self.canvas.delete("key-light")
if self.view_var.get() == "screen" or not self._art_geometry[2]:
return
held = set(self.pressed_pc.values())
if self.mouse_pressed:
held.add(self.mouse_pressed)
for key in sorted(held):
if key in HOTSPOTS:
x, y, w, h = self._rect(HOTSPOTS[key])
self.canvas.create_image(x, y, image=self._sprite(key, "pressed", w, h), anchor="nw",
tags="key-light")
if self._hover and self._hover in HOTSPOTS and self._hover not in held:
x, y, w, h = self._rect(HOTSPOTS[self._hover])
self.canvas.create_image(x, y, image=self._sprite(self._hover, "hover", w, h), anchor="nw",
tags="key-light")
badge = font(8, "bold")
measure = tkfont.Font(root=self.root, font=badge)
for sym, key in sorted(self.pressed_pc.items()):
if key not in HOTSPOTS:
continue
x, y, w, h = self._rect(HOTSPOTS[key])
text = pc_glyph(sym)
tw = measure.measure(text) + 12
th = measure.metrics("linespace") + 4
cx, top = x + w / 2, y - th - 3
round_rect(self.canvas, cx - tw / 2, top, cx + tw / 2, top + th, th / 2, fill="#1d1d1f", outline="",
tags="key-light")
self.canvas.create_text(cx, top + th / 2, text=text, fill="#ffffff", font=badge, tags="key-light")
self.canvas.tag_raise("key-light")
def _draw_chips(self):
"""Keys Held: each key down, and the computer key it comes from."""
c = self.chips
c.delete("all")
held = []
name = lambda key: KEY_NAMES.get(key, LABEL.get(key, key))
for sym, key in sorted(self.pressed_pc.items()):
held.append(f"{name(key)} {pc_glyph(sym)}")
if self.mouse_pressed and self.mouse_pressed not in self.pressed_pc.values():
held.append(name(self.mouse_pressed))
if not held:
c.create_text(0, 12, text="None", anchor="w", fill=MUTED, font=font(8))
return
chip = font(8)
measure = tkfont.Font(root=self.root, font=chip)
x = 1
for text in held:
w = measure.measure(text) + 16
round_rect(c, x, 2, x + w, 22, 6, fill=CHIP, outline=LINE)
c.create_text(x + w / 2, 12, text=text, fill=FG, font=chip)
x += w + 6
def _draw_spark(self):
c = self.spark
c.delete("all")
values = list(self._speed_hist)
if len(values) < 2:
return
w, h = int(c.cget("width")), int(c.cget("height"))
top = max(1.2, max(values))
c.create_line(0, h - 2 - (h - 4) / top, w, h - 2 - (h - 4) / top, fill=LINE, dash=(2, 3))
pts = []
for i, v in enumerate(values):
pts += [w * i / (len(values) - 1), h - 2 - (h - 4) * min(v, top) / top]
c.create_line(*pts, fill=ACCENT, width=1.6, smooth=True)
def _schedule_snap(self, event=None):
if event is not None and event.widget is not self.root:
return
if self._snap_id is not None:
self.root.after_cancel(self._snap_id)
self._snap_id = self.root.after(300, self._snap_to_device)
def _snap_to_device(self):
"""After the window is resized, its width follows the calculator again: no empty space beside it."""
self._snap_id = None
if self.fullscreen or self.view_var.get() != "calculator":
return
try:
if self.root.state() != "normal":
return
ch, cw = self.canvas.winfo_height(), self.canvas.winfo_width()
except tk.TclError:
return
if ch < 100:
return
want = int(ch * self.art_px[0] / self.art_px[1])
if abs(cw - want) > 2:
self.root.geometry(f"{self.root.winfo_width() - cw + want}x{self.root.winfo_height()}")
def _mouse_press(self, event):
# Crucial on Windows: clicking the calculator after using a sidebar
# button must direct the NEXT real keyboard press to the calculator.
self.canvas.focus_set()
key = self._key_at(event.x, event.y)
if key:
self.on_mouse_down(key)
return "break"
return None
def _mouse_move(self, event):
self._hover = self._key_at(event.x, event.y)
self.canvas.configure(cursor="hand2" if self._hover else "arrow")
self._draw_highlight()
def _mouse_leave(self, event):
self._hover = None
self._draw_highlight()
def refresh_pressed(self):
names = set(self.pressed_pc.values())
if self.mouse_pressed is not None:
names.add(self.mouse_pressed)
with self.pressed_lock:
self.pressed.clear()
self.pressed.update(names)
if hasattr(self, "canvas"):
self._draw_highlight()
self._draw_chips()
def poll(self):
if self._closing:
return
newest_frame = None
last_status = None
latest_pace = None
ended = None
error = None
while True:
try:
m = self.messages.get_nowait()
except queue.Empty:
break
if m[0] == "frame":
newest_frame = m
elif m[0] == "status":
last_status = m[1]
elif m[0] == "pace":
latest_pace = m
elif m[0] == "ended":
ended = m[1]
elif m[0] == "error":
error = m[1]
if last_status and not self.powered_off:
self.set_status(last_status)
if latest_pace and not self.powered_off:
_, factor, mhz, auto = latest_pace
self.rate_label.set(f"Speed {factor:.2f}x, CPU: {mhz} MHz" +
(" (auto)" if auto else " (manual)"))
self._speed_hist.append(factor)
self.speed_value.set(f"{factor:.2f}×")
self.speed_detail.set(f"of the calculator's own speed, with the processor at {mhz} MHz" +
(" (following this computer)" if auto else ""))
self._draw_spark()
if self.current and self._app_name != self.current.stem:
self._app_name = self.current.stem
self._update_subtitle()
if self.appearance == "system" and time.monotonic() - self._look_checked > 1.5:
self._look_checked = time.monotonic()
self._follow_appearance()
if (self.worker is not None and self.worker.is_alive() and
not self.powered_off and not self.pause_event.is_set() and
time.monotonic() - self._last_frame_wall > 3.0):
phase = self.worker.phase
age = time.monotonic() - self.worker.phase_since_wall
if phase == "running ARM CPU":
self.rate_label.set(f"Slow ARM emulation: {age:.1f}s in CPU step")
elif phase == "waiting for app sleep":
detail = self.worker.last_svc_detail
if detail:
svc, where, duration = detail
self.rate_label.set(f"Pacing {duration:.0f}ms SVC {svc} at 0x{where:x}")
else:
self.rate_label.set("Waiting for emulated app timing")
elif phase == "waiting for emulated time":
self.rate_label.set("Pacing virtual clock (not an ARM crash)")
else:
self.rate_label.set(f"Worker: {phase} ({age:.1f}s)")
# If a real .nwa still wedges, this tells us *where*, without
# printing private save data or flooding PowerShell each frame.
now = time.monotonic()
if ((self.profile_speed or (phase == "running ARM CPU" and age >= 3.0))
and now - self._last_stall_log_wall > 5.0):
self._last_stall_log_wall = now
print(f"[NumPlay emulator diagnostic] no frame for "
f"{now-self._last_frame_wall:.1f}s; phase={phase}; "
f"phase_age={age:.1f}s; virtual_ms={self.worker.last_progress_ms:.0f}; "
f"last_cpu_step={self.worker.last_cpu_seconds:.3f}s; "
f"last_virtual_step={self.worker.last_virtual_delta:.1f}ms; "
f"app_sleep_step={self.worker.last_sleep_delta_ms:.1f}ms; "
f"last_svc={self.worker.last_svc_detail}; "
f"CPU={self.clock_mhz[0]}MHz; auto={self.auto_clock[0]}",
file=sys.stderr, flush=True)
if newest_frame and not self.powered_off and not ended:
self._last_frame_wall = time.monotonic()
_, raw, elapsed = newest_frame
try:
self._screen_rgb = rgb565_to_photo_bytes(raw)
self.present_screen()
self.time_label.set(f"{elapsed:,} ms (virtual)")
except Exception as exc:
self.set_status(f"Display error: {exc}")
if ended and not self.powered_off:
self.black_screen(ended)
elif (self.worker is not None and self.worker.end_reason == "exited"
and not self.powered_off):
self.black_screen("The app quit. Press On/Off or Restart to start it again")
if error and not self.powered_off:
self.set_status("The emulator stopped with an error")
messagebox.showerror("NumPlay emulator", error)
if self.pending is not None and (self.worker is None or not self.worker.is_alive()):
self.start_pending()
self._poll_id = self.root.after(UI_POLL_MS, self.poll)
def main():
ap = argparse.ArgumentParser(description="NumWorks-shaped .nwa emulator: single-file and live-build modes, on macOS, Linux and Windows")
ap.add_argument("nwa", nargs="?", type=Path, help="optional .nwa path, or drop it after launching")
ap.add_argument("--nwlink", default=nwlink_command())
ap.add_argument("--model", choices=("n0120", "n0110"), default="n0120")
ap.add_argument("--system", choices=("epsilon", "upsilon"), default="epsilon")
ap.add_argument("--live", action="store_true", help="open Live development mode and start the build watcher inside the GUI")
ap.add_argument("--follow-newest", action="store_true", help="legacy alias for --live (no ambiguous newest-file scanning)")
ap.add_argument("--profile-speed", action="store_true",
help="print a measured ARM/render/pacing speed report every 5 seconds")
ap.add_argument("--max-sleep-ms", type=int, default=0, metavar="MS",
help="EXPERIMENTAL: cap any EADK app sleep to MS milliseconds; "
"0 (default) preserves exact emulator behavior")
args = ap.parse_args()
if args.max_sleep_ms < 0 or args.max_sleep_ms > 10000:
ap.error("--max-sleep-ms must be between 0 and 10000")
if args.max_sleep_ms:
print(f"[NumPlay diagnostic] EXPERIMENTAL sleep guard ON: "
f"sleep calls over {args.max_sleep_ms}ms will be shortened. "
"Game timing may differ from the calculator.", file=sys.stderr)
if not args.nwlink:
ap.error("nwlink not found. Run: npm install -g [email protected]")
art = CALCULATOR
if os.name == "nt":
# Avoid Windows silently bitmap-scaling the *whole* Tk window at 125%/
# 150% display scale, which would defeat the native 1:1 LCD view.
# Call before Tk creates its first window; keep a safe fallback.
try:
import ctypes
ctypes.windll.shcore.SetProcessDpiAwareness(2) # per-monitor aware
except (AttributeError, OSError):
try:
ctypes.windll.user32.SetProcessDPIAware()
except (AttributeError, OSError):
pass
if TkinterDnD:
root = TkinterDnD.Tk()
else:
root = tk.Tk()
print("Tip: pip install tkinterdnd2 for .nwa drag-and-drop.")
start_live = args.live or args.follow_newest
if start_live and args.nwa:
print("[NumPlay] --live uses build/compiled/NumPlay.nwa; ignoring the supplied single-file path.")
CalculatorSkinApp(root, None if start_live else args.nwa, args.nwlink,
args.model, args.system, False, art,
max_sleep_ms=args.max_sleep_ms, profile_speed=args.profile_speed,
start_live=start_live)
root.mainloop()
# Previous headless CLI flags continue to work with this single file.
def _run_headless_cli():
options = ("--ms", "--keys", "--shots", "--gif", "--fps", "--out",
"--storage", "--flash-start", "--ram-length", "--records",
"--frames", "--profile")
return "--headless" in sys.argv or any(arg.split("=", 1)[0] in options for arg in sys.argv[1:])
if __name__ == "__main__":
if _run_headless_cli():
if "--headless" in sys.argv:
sys.argv.remove("--headless")
emu.main()
else:
main()