Skip to content

About

An emulator for the Mattel HyperScan. Both Retroarch cores and standalone are supported.

Topics

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

HyperScanEmu — A Mattel HyperScan emulator written in Rust

HyperScanEmu

Website CI Gitlab Pipeline Status Release Downloads Quality Gate Status License: BSD 3-Clause Discord QQ Group

HyperScanEmu is an evidence-driven, clean-room Rust emulator for the Mattel HyperScan. It boots the retail BIOS and reaches a retail game's loading screen with real media attached. Opening animation, title/menu, and retail gameplay are not yet validated.

The HyperScan is a 2006 Mattel home console built around the Sunplus SPG290 SoC (S+Core 7 CPU). Games ship on CD with optional RFID save cards. The selected strategy is low-level emulation of the firmware-visible hardware.

Features

  • SPG290 LLE core — checked memory bus, S+Core 7 interpreter, deterministic peripheral scheduling
  • Firmware boot — 32 KiB internal ROM plus 1 MiB HyperScan BIOS with structured unknown-instruction / MMIO stops
  • Disc packages — raw MODE1/2352 BIN, single-track CUE, and ZIP loading with ISO/UDF validation
  • CD servo — timed sector DMA, analog feedback, and single-track Q subchannel synthesis
  • Display — TVE direct frames plus PPU bitmap, character, and sprite layers (640×480 output)
  • Input — dual I²C controllers with buttons, analog axes, and checksums
  • Audio — 54 MHz DAC ring-buffer DMA (16-bit PCM); hardware synthesizer not yet implemented
  • RFID cards — 120-byte card protocol on GPIO with dirty tracking
  • Standalone frontend — resizable window, fullscreen, keyboard gamepads, PNG screenshots
  • libretro core — RetroArch integration with firmware from the system directory
  • Browser play — EmulatorJS core compiled to WebAssembly, with a ready-to-use online player that runs firmware and BIN/CUE images without uploading them
  • Headless diagnostics — --inspect, --trace, and headless frame runs without window or audio devices

Usage

Standalone Mode

There are no subcommands. Pass the media path first:

cargo run -p hyperscanemu --release -- game.cue
cargo run -p hyperscanemu --release -- "game.zip" --system-dir system --scale 2

Firmware is loaded from <system-dir>/hyperscanemu/ with fixed, case-sensitive names:

system/hyperscanemu/spg290.bin       32768 bytes
system/hyperscanemu/hyperscan.bin  1048576 bytes

See the Standalone Emulator guide for options, keyboard controls, headless capture, and diagnostic CLI workflows.

RetroArch Mode

Build the libretro core, rename it to hyperscanemu_libretro.<ext>, and place legally dumped firmware in the frontend system directory:

<system>/hyperscanemu/spg290.bin       32768 bytes
<system>/hyperscanemu/hyperscan.bin  1048576 bytes

The folder and file names are case-sensitive and the loader never searches other locations.

See the RetroArch Core guide for installation, loading content, and current limitations. Mobile and TV targets: Android, iOS.

Browser (EmulatorJS)

Open https://AloysHF.github.io/HyperScanEmu/play.html, pick a firmware ZIP containing hyperscanemu/spg290.bin and hyperscanemu/hyperscan.bin, then a .bin or CUE/BIN .zip disc image. Both run locally in the browser through the HyperScanEmu WebAssembly core; nothing is uploaded. See the EmulatorJS Core guide for embedding the core in your own EmulatorJS deployment, bundle contents, firmware placement, and controls.

Diagnostic CLI

cargo run -p hyperscanemu -- <media.bin|media.cue|media.zip> --inspect
cargo run -p hyperscanemu -- --system-dir system --trace <steps>
cargo run -p hyperscanemu -- <media> --system-dir system \
  --headless --frames <N> --output frame.ppm
cargo run -p hyperscanemu -- <media> --system-dir system \
  -S startup.png --screenshot-frames 300

Building

Requires Rust (stable).

Standalone

cargo build -p hyperscanemu --release

The binary is produced at target/release/hyperscan-emu.

Libretro Core

cargo build -p hyperscanemu-libretro --release

Rename the output to hyperscanemu_libretro.<ext> before installing it into RetroArch's cores/ directory. See RetroArch Core.

EmulatorJS Core (for the browser)

The browser core links the libretro core into EmulatorJS's RetroArch fork. It needs an activated emsdk, p7zip, and the pinned nightly toolchain:

cargo +nightly build -p hyperscanemu-libretro \
  --target wasm32-unknown-emscripten --profile wasm-release \
  -Zbuild-std=std,panic_abort

scripts/build-emulatorjs-core.sh

The bundle is written to out/hyperscan-emu-emulatorjs.zip. See EmulatorJS Core for details.

Architecture

crates/
├── hyperscanemu-core/      # Platform-independent emulator state and execution
├── hyperscanemu-media/     # Checked BIN/CUE/ZIP host-media loading
├── hyperscanemu/           # Headless/standalone host adapter
└── hyperscanemu-libretro/  # libretro ABI boundary

Details: Architecture, Hardware, Game File Formats, Game Compatibility.

Testing

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

Firmware and game media are not included and cannot run in CI. Boot milestones and title progress are tracked in Game Compatibility.

Validate media without firmware:

cargo run -p hyperscanemu -- <media.bin|media.cue|media.zip> --inspect

Contributing

Contributions are welcome. See CONTRIBUTING.md for code style, validation commands, and areas that need help.

License

This project is licensed under the BSD 3-Clause License.

About

An emulator for the Mattel HyperScan. Both Retroarch cores and standalone are supported.

Topics

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages