Quickstart

This guide will help you build and run the TI-84 Plus CE emulator on your platform of choice. The emulator is cross-platform with native apps for Android, iOS, and web browsers.

You’ll need a TI-84 Plus CE ROM file to run the emulator. The ROM contains the calculator’s operating system and is not included with this project. You must obtain it legally from your own calculator.

Prerequisites

Before you begin, ensure you have the following installed:

Install Rust toolchain

The emulator core is written in Rust. Install it from rustup.rs:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Platform-specific tools

Choose based on your target platform:

Web
Android
iOS

Node.js 18+ for the web frontend
wasm-pack for building WebAssembly:

cargo install wasm-pack
rustup target add wasm32-unknown-unknown

Android Studio with NDK installed
Android SDK (API 24+)
Rust Android targets:

rustup target add aarch64-linux-android    # ARM64 (most devices)
rustup target add armv7-linux-androideabi  # ARM32 (older devices)
rustup target add x86_64-linux-android     # x86_64 emulator
rustup target add i686-linux-android       # x86 emulator

Xcode 15+ (macOS only)
Rust iOS targets:

rustup target add aarch64-apple-ios        # iOS device (arm64)
rustup target add aarch64-apple-ios-sim    # iOS Simulator (Apple Silicon)
rustup target add x86_64-apple-ios         # iOS Simulator (Intel)

Clone the repository

git clone https://github.com/yourusername/ti84-emulator.git
cd ti84-emulator

Building for Web

The web app runs entirely in your browser using WebAssembly. This is the fastest way to get started.

Build the WASM package and web app

Use the provided Makefile target:

make web

This command:

Compiles the Rust core to WebAssembly (~96KB gzipped)
Copies the WASM package to the web app directory
Installs npm dependencies
Builds the React frontend with Vite

Serve the web app

cd web
npx serve dist

Open your browser to the URL shown (typically http://localhost:3000).

Load your ROM

Click “Import ROM” in the web interface
Select your TI-84 Plus CE ROM file
Click “Run” to start emulation

Development mode with hot reload:

make web-dev

This starts a development server at http://localhost:5173 with automatic reloading when you edit the frontend code.

Web Keyboard Controls

The web app includes keyboard shortcuts for calculator keys:

Keyboard Key	Calculator Function
0-9	Number keys
+ - * /	Math operations
Enter	Enter
Backspace	Del
Arrow keys	Navigation
Shift	2nd
Alt	Alpha
O	ON
Space	Pause emulation
F1-F5	Y=/Window/Zoom/Trace/Graph

Building for Android

The Android app uses Kotlin with Jetpack Compose for the UI and the Rust core via JNI.

Build the APK

Use the build script for a streamlined build:

./scripts/build.sh android

This compiles the Rust core for ARM64 and builds a release APK.

Build options

The build script supports several options:

# Debug build
./scripts/build.sh android --debug

# Build and install to connected device
./scripts/build.sh android --install

# Build for all ABIs (arm64, arm32, x86_64, x86)
./scripts/build.sh android --all-abis

# Use CEmu reference backend instead of Rust
./scripts/build.sh android --cemu

Or use the Makefile shortcuts:

make android              # Release, arm64, Rust
make android-debug        # Debug build
make android-install      # Release + install (all ABIs)
make android-cemu         # Release with CEmu backend

Install the APK

Connect your Android device via USB with developer mode enabled, then:

./scripts/build.sh android --install

Or install manually:

cd android
./gradlew installRelease

Load your ROM

Open the app on your device
Tap “Import ROM”
Navigate to your ROM file
Tap “Run” to start emulation

Rapid development workflow:For fast iteration when changing Kotlin code:

cd android
./watch.sh

This watches for file changes and auto-deploys to your connected device. Requires fswatch (brew install fswatch on macOS).

Building for iOS

The iOS app uses Swift with SwiftUI for the UI. Building requires two steps: compiling the Rust backend library, then building the app in Xcode.

Build the backend library

For iOS Simulator (Apple Silicon Mac):

./scripts/build.sh ios --sim

For physical iOS devices:

./scripts/build.sh ios

This compiles the Rust core as a static library (.a) that Xcode will link against.

Build options

# Debug build for simulator
./scripts/build.sh ios --sim --debug

# Release build for device
./scripts/build.sh ios

# Use CEmu reference backend
./scripts/build.sh ios --sim --cemu

Makefile shortcuts:

make ios              # Release, device
make ios-sim          # Release, simulator
make ios-debug        # Debug, device
make ios-sim-cemu     # Simulator with CEmu backend

Open Xcode and build the app

open ios/Calc.xcodeproj

In Xcode:

Select your target device or simulator
Press Cmd+R to build and run
The app will launch on your selected target

Load your ROM

In the iOS app, tap “Import ROM”
Select your ROM file from Files
Tap “Run” to start emulation

The build script only compiles the emulator backend. Xcode handles building the Swift app and linking against the static library.

Testing the Rust Core

The Rust core includes a comprehensive test suite covering CPU instructions, memory subsystem, and peripherals.

cd core
cargo test

Available test commands

From the core/ directory, use these cargo aliases:

cargo boot      # Run boot test with progress reporting
cargo screen    # Render screen to PNG after boot
cargo vram      # Analyze VRAM colors
cargo trace     # Generate trace log (100k steps)
cargo dbg       # Show debug tool help
cargo t         # Run all tests
cargo rb        # Release build

These aliases are defined in core/.cargo/config.toml.

Using the CEmu Reference Backend

The apps can optionally be built with CEmu, the established open-source TI-84 Plus CE emulator, as the backend. This is useful for:

Parity testing - Compare Rust core behavior against known-correct emulation
Bug investigation - Determine if issues are in your code or inherent to the ROM
Feature development - Test UI features before Rust implementation is complete

Clone CEmu

git clone https://github.com/CE-Programming/CEmu.git cemu-ref

The cemu-ref/ directory is git-ignored and won’t be committed to your repository.

Build with CEmu backend

./scripts/build.sh android --cemu

The app behavior should be identical regardless of backend. If it differs, that’s a bug to investigate.

CEmu is written in C and compiled via Emscripten for web builds. The resulting WASM file is significantly larger than the Rust core.

Loading Programs (.8xp / .8xv)

The emulator supports loading TI-84 CE programs (.8xp) and AppVars (.8xv) into the calculator’s flash archive.

From the Apps

All three apps (web, Android, iOS) include file pickers for loading programs:

Use the “Load Program” or similar menu option
Select one or more .8xp or .8xv files
The files are injected into flash
Programs appear in the TI-OS program menu after reboot

From the Debug Tool

The Rust core includes CLI commands for loading programs:

cd core

# Inject a single program
cargo run --release --example debug -- sendfile DOOM.8xp

# Inject a program with its required C libraries
cargo run --release --example debug -- sendfile DOOM.8xp clibs/*.8xv

Programs built with the CE C toolchain (e.g., games using graphx) need their library .8xv files included. Common libraries: libload.8xv, graphx.8xv, keypadc.8xv, fileioc.8xv.

Next Steps

Architecture

Learn about the dual backend design, Rust core structure, and memory map

API Reference

Explore the C API for integrating the emulator core

Development

Dive into development workflows, debugging tools, and testing

Contributing

Learn how to contribute to the project

Troubleshooting

Android build fails with 'NDK not found'

Open Android Studio, go to SDK Manager → SDK Tools, and install:

NDK (Side by side)
CMake

Then set your NDK path in local.properties:

ndk.dir=/Users/yourname/Library/Android/sdk/ndk/25.2.9519653

iOS build fails with 'library not found'

Make sure you’ve run the build script before opening Xcode:

./scripts/build.sh ios --sim

The build script outputs the static library that Xcode expects to find.

Web build: 'wasm-pack not found'

Install wasm-pack:

cargo install wasm-pack
rustup target add wasm32-unknown-unknown

Emulator boots to black screen

This usually means:

ROM file is corrupted or invalid
ROM is for a different calculator model (need TI-84 Plus CE)

Try a different ROM file or re-extract from your physical calculator.

Tests fail with 'ROM not found'

Some tests require a ROM file. Place your ROM at:

TI-84 CE.rom

in the repository root, or specify the path via environment variable:

export ROM_PATH=/path/to/your/rom.rom
cargo test

Get Started

Platform Integration

Core Concepts

Building

Advanced

Quickstart

Quickstart

Prerequisites

Building for Web

Web Keyboard Controls

Building for Android

Building for iOS

Testing the Rust Core

Using the CEmu Reference Backend

Loading Programs (.8xp / .8xv)

From the Apps

From the Debug Tool

Next Steps

Architecture

API Reference

Development

Contributing

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Platform Integration

Core Concepts

Building

Advanced

​Quickstart

​Prerequisites

​Building for Web

​Web Keyboard Controls

​Building for Android

​Building for iOS

​Testing the Rust Core

​Using the CEmu Reference Backend

​Loading Programs (.8xp / .8xv)

​From the Apps

​From the Debug Tool

​Next Steps

Architecture

API Reference

Development

Contributing

​Troubleshooting

Build docs developers (and LLMs) love

Quickstart

Prerequisites

Building for Web

Web Keyboard Controls

Building for Android

Building for iOS

Testing the Rust Core

Using the CEmu Reference Backend

Loading Programs (.8xp / .8xv)

From the Apps

From the Debug Tool

Next Steps

Troubleshooting