# Native TI game previews

This directory runs real TI-83 Plus Z80 programs using **tihle** by Peter
Marheine, with the emulator's own replacement system routines. No TI ROM,
TI-OS image, or user ROM upload is included or required. The color TI-84 Plus CE
uses a different CPU and is not supported by this player.

## Runtime and corresponding source

`vendor/tihle.js`, `tihle.wasm`, and `tihle.data` are unmodified files from
upstream GitLab Pages job **2553571154**, pipeline **557022049**, for commit
`81b2fa33a7fd798a34f5b0a7edece6c15275ef27`. They were checked byte for byte
against the currently deployed upstream demo. The original artifact URL and
all file hashes are in `provenance.json`.

The full corresponding source, including its build scripts, Cargo lockfile,
replacement OS sources, Z80 core, and Phoenix sources, is served in
`sources/tihle-source.tar.gz`. Build instructions are in that archive's
`README.md`, `Dockerfile.build`, and `dist/build-web.sh`. The runtime is
GPL-3.0-only; preserve `vendor/COPYING.txt`.

`player.html` and `player.js` are AgentCalc's GPL-3.0-only host adapter. They
configure the stock Emscripten module, place the selected program in its virtual
filesystem, and expose a small origin-checked message interface. The parent
creates this iframe only after Play and destroys it on Stop or Restart, freeing
its animation loop and WebGL context. The bundled `.data` includes upstream's
Phoenix and small GPL emulator test programs; it contains no proprietary TI OS.

## Games

- **Flappy Bird**, **Iron Pants**, **Fall**, **The Line**, and **Tunnel**: unmodified compiled programs from Scott
  Mangiapane's `ti-games`, commit `6c48442b2bf973734927166187287cac26571055`.
  GPL-3.0 license: `GAMES-LICENSE.txt`. Full upstream sources, including Axe
  source programs and text listings, are in `sources/ti-games-source.tar.gz`.
- **Phoenix 4.3** by Patrick Davidson: extracted unchanged from upstream's
  `tihle.data` (bytes 0 through 9031). Its source is in the emulator archive's
  `programs/phoenix/` directory. The author's full permissions and manual are in
  `PHOENIX-LICENSE-AND-MANUAL.txt`; they permit unrestricted use, copying, and
  modification of his code.

## Compatibility

The preview runs games, not TI-OS or its calculator apps. Saved scores and
AppVar storage are unavailable. Flappy Bird and Iron Pants end the emulated
program after a loss; their calculator score screens are not supported. Use
AgentCalc's Restart button to replay. Phoenix's menus and game run normally.

Fall starts immediately, uses left and right to move, and automatically starts
another run after the ball is lost. Its initial `ClrScrnFull` bcall is skipped
only on its first occurrence: the fresh isolated display is already blank
and its unsupported text-shadow buffer is unused. The program itself is unchanged.

The ignored `RunIndicOff` bcall only hides TI-OS's busy indicator. Other
unimplemented bcalls report an unsupported preview rather than silently showing
a broken game. Upstream logs about model-detection port 2 and clock port 20 are
not shown as user errors for these curated programs.

Investigation rejected 2048, Blox, and Snake from the same collection because
their OS calls or rendering were incomplete. They are not offered as playable
presets. Adding another program requires checking startup, input, gameplay,
exit/loss, and replay. Hardware compatibility follows the original authors;
AgentCalc's checks cover browser emulation, not physical calculators.

### The Line and Tunnel preview adaptations

The original downloads are unchanged. The browser runs `the-line-preview.8xp`
and `tunnel-preview.8xp`, reproducibly generated from the pinned originals by
`sources/build-preview.py`. Both substitute the supported LCD clear for
`ClrScrnFull` (the text shadow is unused), and end the run at a collision
before the unsupported high-score/AppVar code. Tunnel also replaces `BufClr`
with a small Z80 routine that clears the 768-byte buffer specified in HL.
Restart starts a fresh run; the original calculator programs retain their
score screens and replay behavior.

## Relaxed browser play

The player defaults to Relaxed (65%) speed and offers Original speed plus
Pause/Resume. `player.js` passes virtual animation timestamps to the stock
emulator using the shared `../calculator-games/playback.js` clock. This slows
emulated time independently of monitor refresh rate, freezes time while paused,
and avoids a catch-up jump on resume. Keyboard/touch state clears on pause.
The vendored emulator and downloadable TI binaries are unchanged.