WQXEmu — Wenquxing Emulator
A Wenquxing (文曲星) electronic dictionary emulator written in Rust, using Low-Level Emulation (LLE) to run real firmware. Supports NC1020, PC1000, CC800, NC2000, and NC3000 models.
Features
- 6502/W65C02 CPU emulation — cycle-accurate instruction execution with BCD support
- Bank-switched memory — full memory map with NOR/NAND flash, RAM, and IO registers
- Multi-model architecture — shared
Machine trait with NC1020 / PC1000 / CC800 / NC2000 / NC3000 backends (PC1000 and CC800 boot to the main menu; NC2000/NC3000 boot to the clock screen with standby/wake)
- LCD display — 160×80 pixel display with model-correct framebuffer placement, 4 grayscale levels, and ghosting effects
- Keyboard input — complete QWERTY keyboard matrix emulation
- Device skins and virtual keypad — choose the original model-specific image or a fully code-drawn skin; both embed the live LCD and support clickable keys, PC keyboard input, and pressed-key highlighting
- Audio system — SPDS104A DSP emulation with tone generation
- Timer system — multiple timer sources with interrupt generation
- Persistent sessions — optional compressed state files resume any supported model without modifying source dumps
- RetroArch integration — libretro core for use with RetroArch frontend
- Browser play — EmulatorJS/WebAssembly core that runs from a firmware ZIP without installing anything
- Cross-platform — Windows, macOS, Linux, Android, iOS, webOS, and the browser
Usage
Standalone Mode
Download the latest binary from the Releases page and run:
wqx-emu --model nc1020 --rom-dir tmp/roms/nc1020
The code-drawn skin is used by default. Pass --skin image to use the
original model photograph instead, retaining the same LCD placement and
clickable key geometry. Pass --dump-skin out.png to export the selected
skin bitmap to a PNG file.
Point --rom-dir at a directory containing the firmware dumps for one device; files are discovered by extension (.rom/.bin for the system ROM, .fls/.nor for NOR Flash, .nand and .nand0 for NAND). The required combination depends on the selected model.
| Model | Required firmware | Optional firmware |
|---|
| NC1020 | ROM + NOR | — |
| PC1000 | ROM + NOR | — |
| CC800 | ROM + NOR | — |
| NC2000 | NOR + NAND + NAND0 | — |
| NC3000 | NOR + NAND | NAND0 |
See the Standalone Emulator guide for installation, keyboard controls, headless mode, screenshots, and all command-line options.
RetroArch Mode
Install the core, place the firmware set under RetroArch's system/WQXEmu/<model>/
directory (files are discovered by the same extension rules as --rom-dir), select
the machine in Core Options, and use Start Core. Firmware
is system data rather than game content, so the core intentionally does not accept
files through Load Content.
See the RetroArch Core guide for installation, supported platforms, RetroPad mapping, and features.
Browser Mode (EmulatorJS)
Open https://AloysHF.github.io/WQXEmu/play.html and select a firmware ZIP.
The page runs the WebAssembly core locally; nothing is uploaded and no firmware
is hosted on the site.
The ZIP carries the dumps for one model, optionally inside a folder named after
it (nc1020, pc1000, cc800, nc2000, nc3000):
nc1020.zip
nc1020/
obj_lu.bin # system ROM (.rom / .bin)
nc1020.fls # NOR Flash (.fls / .nor)
The required dump set matches standalone mode. Without a recognized folder
name the core auto-detects the model from the dumps. Self-hosting instructions
and the full archive rules are in the
EmulatorJS Core guide.
Building
Requires Rust (stable).
Standalone Mode (Default)
cargo build --release
cargo run -p wqxemu --release -- --model nc1020 --rom-dir tmp/roms/nc1020
The binary is produced at target/release/wqx-emu (or wqx-emu.exe on Windows).
Libretro Core (for RetroArch)
cargo build -p wqxemu-libretro --release
The compiled core (wqxemu.dll / libwqxemu.so / libwqxemu.dylib) can be loaded in RetroArch. Rename to wqxemu_libretro.<ext> if your RetroArch setup expects that name.
For Android cross-compilation, see Android Libretro Core.
For iOS, see iOS Libretro Core.
EmulatorJS Core (for the browser)
cargo +nightly build -p wqxemu-libretro \
--target wasm32-unknown-emscripten --profile wasm-release \
-Zbuild-std=std,panic_abort
scripts/build-emulatorjs-core.sh
The script needs an activated emsdk (emmake), p7zip, and zip; it writes
out/wqxemu-emulatorjs.zip, which contains the wqxemu-wasm.data and
wqxemu-legacy-wasm.data bundles. See the
EmulatorJS Core guide for the runtime layout and
site setup.
Testing
Run the unit tests:
cargo test --workspace
There is also a smoke test that loads every available game, runs it for a number of frames, and checks that the emulator neither panics nor produces a blank frame. It needs the (non-distributed) game assets, so it is #[ignore]d by default and only runs on demand:
# Uses <repo>/tmp/games by default, or set WQX_GAME_DIR
cargo test -p wqxemu-core --test smoke -- --ignored --nocapture
Architecture
crates/
├── wqxemu-core/ # Platform-independent emulator engine (library)
│ └── src/
│ ├── lib.rs # Crate root
│ ├── emulator.rs # Main emulator orchestrator
│ ├── cpu.rs # 6502/W65C02 CPU emulation
│ ├── memory.rs # Memory bus with bank switching
│ ├── lcd.rs # LCD framebuffer (160×80, 4 grayscale)
│ ├── input.rs # Keyboard input handling
│ ├── audio.rs # Audio tone generation
│ ├── timer.rs # Timer system with interrupts
│ ├── flash.rs # NOR/NAND flash controller
│ ├── io.rs # IO register handling
│ ├── save.rs # Save state serialization
│ └── machines/ # Per-model implementations
│ ├── nc1020.rs # NC1020 model
│ ├── pc1000.rs # PC1000 model
│ ├── cc800.rs # CC800 model
│ ├── nc2000.rs # NC2000 model
│ └── nc3000.rs # NC3000 model
├── wqxemu/ # Standalone binary (→ wqx-emu)
│ └── src/
│ └── main.rs # Window loop and CLI frontend
└── wqxemu-libretro/ # libretro cdylib/staticlib (→ wqxemu.{dll,so,dylib},
# or the EmulatorJS wasm staticlib)
└── src/
└── lib.rs # libretro API implementation
For detailed architecture information, see ARCHITECTURE.md.
Compatibility
| Model | Status | Screenshot | Notes |
|---|
| NC1020 | ✅ Working | | Boots to menu, keyboard and NOR work |
| PC1000 | ✅ Working | | Boots to menu, keyboard and NOR work |
| CC800 | ✅ Working | | Boots to menu, keyboard and NOR work |
| NC2000 | ✅ Working | | Boots to clock screen, standby/wake works |
| NC3000 | ✅ Working | | Boots to clock screen, standby/wake works |
| Status | Description |
|---|
| ✅ Working | Model boots and runs correctly |
| ⚠️ Partial | Model boots but has issues |
| ❌ Not Working | Model does not boot or crashes |
Contributing
Contributions are welcome! Whether you're interested in fixing bugs, adding features, improving documentation, or testing game compatibility, we'd love your help. See CONTRIBUTING.md for details.
Acknowledgments
License
This project is licensed under the GNU General Public License v3.0 or later.
