https://github.com/zeal8bit/zeal-webemulator
A browser-based emulator for Zeal 8-bit Computer
https://github.com/zeal8bit/zeal-webemulator
8-bit emulator retrocomputing z80
Last synced: about 1 year ago
JSON representation
A browser-based emulator for Zeal 8-bit Computer
- Host: GitHub
- URL: https://github.com/zeal8bit/zeal-webemulator
- Owner: Zeal8bit
- License: apache-2.0
- Created: 2022-09-08T12:01:06.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-02-15T02:49:32.000Z (over 1 year ago)
- Last Synced: 2025-03-29T23:08:28.192Z (about 1 year ago)
- Topics: 8-bit, emulator, retrocomputing, z80
- Language: JavaScript
- Homepage:
- Size: 3.24 MB
- Stars: 95
- Watchers: 9
- Forks: 25
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Zeal 8-bit Computer emulator
)
English | 简体中文
This project is a software emulator for Zeal 8-bit Computer: a homebrew 8-bit computer based on a Z80 CPU.
[Click here for a live demo](https://zeal8bit.github.io/Zeal-WebEmulator/)
## Why this project?
The goal of this project is to reproduce the same behavior as the real machine, to be able to execute and **debug** the programs written for it directly from a host computer. As such, there is no need to flash any EEPROM or NOR Flash to test programs. This makes development and test cycles much faster and more convenient.
## Why a web-based emulator? (HTML/CSS/JavaScript)
The main goal is to integrate this emulator as part of [zeal8bit.com](https://zeal8bit.com) website. Thus, choosing HTML/CSS and Javascript was a bit obvious on this side.
On the other side, another goal of this project is also to let anybody test or write programs for Zeal 8-bit Computer on any platform (Linux/Windows/Mac OS X) without the need of a toolchain installed.
The emulator has been tested on Opera, Google Chrome and Microsoft Edge.
## What about performance then?
The emulator implementation should now reach the native Zeal 8-bit Computer speed: 10MHz CPU and 60FPS. However, performance also depend on your computer and browser performances, as well as the emulated program. For example, a program that makes extensive use of the all the available sprites at each frame may result in slower execution. This is due to the overhead of Javascript itself and the way HTML canvas are implemented. Keep in mind the main purpose of this emulator is **debugging** programs and for this, there is no doubt it is efficient.
Writing a native emulator in **C** (w/ SDL) would cover the requirement of a full-speed emulator even on lower-spec computers. However, this needs some time investment. Feel free to contact me (or contribute directly) if such a project interest you.
## How to start using the emulator?
Several choices are offered to you:
* Use the live version of the emulator: [live version of the emulator](https://zeal8bit.github.io/Zeal-WebEmulator/). This will let you use the emulator without the need to install anything
* Clone this repository and open the `index.html` page with a web browser: Chrome or Opera preferred.
* Create an application out of this repo by using electron. More details below.
### Get started with electron?
#### Install dependencies
First of all, you will need to clone this current repository, after that use a package manager to install dependencies. If you are using `yarn`, use the following commands:
```bash
cd /path/to/Zeal-WebEmulator
yarn install
```
If you are using `npm`, the commands are as follows:
```bash
cd /path/to/Zeal-WebEmulator
npm install
```
If you encounter any issues, you can find more information on [the official electron forge website](https://www.electronforge.io/import-existing-project).
#### Running
Once the dependencies are ready, it can be executed thanks to `yarn start` or `npm start` commands.
#### Compiling
Supported architectures are the following: `win`, `win64`, and `linux`.
Choose your architecture and replace it in either `npm run dist-` or `yarn dist-` commands to compile the project.
For example, if you want to build for Windows x64, run the following command:
```bash
npm run dist-win64
```
or:
```bash
yarn dist-win64
```
## Supported Features
Currently, the following features from Zeal 8-bit Computer are emulated:
* Z80 CPU ([thanks to *Molly Howell*](https://github.com/DrGoldfire/Z80.js))
* Z80 PIO: all modes supported, both port A and B. Implementation is independent of connected devices.
* 22-bit MMU
* 256KB ROM
* 512KB RAM
* Zeal 8-bit **Video Card**: 640x480 and 320x240px modes, text mode, including cursor and scrolling, graphic modes, including sprites, X/Y flipping, palettes, 4-bit and 8-bit color modes
* PS/2 Keyboard, with interrupts
* UART: it is possible to send and receive bytes. It is also possible to send files. The baudrate can be changed from the GUI
* I2C: bus emulated, supporting write/read/write-read operations
* I2C RTC: always returns the current date
* I2C EEPROM: 24C512 is emulated, so hardcoded to be a 64KB EEPROM. Content can be loaded through the GUI.
Features of the emulator itself implemented:
* Debugger: breakpoints, step, step over instruction, continue until next breakpoint
* Disassembler: when the emulator reaches a breakpoint, the code at *Program Counter* is disassembled. Clicking on one of the instructions will toggle a breakpoint.
* Load a binary file, loaded into ROM directly
* Load a map file generated from `z88dk-z88dk` to view symbols in the assembly view when doing step-by-step debugging
* Set breakpoints with either a **hexadecimal** PC address or a symbol (from the map file)
* View memory content when doing step-by-step debugging
* Dedicated tab for the UART view: can send files to the emulated target
## TODO
On the emulation side, the remaining tasks to do are:
* I2C RTC set date. Currently, it always returns the current browser date, so writing to it will have no effect.
* Sound support (part of Zeal 8-bit Video Card) **IMPLEMENTED!** waveforms table and custom sample implemented! (noise still needs to be implemented)
* SD Card emulation (part of Zeal 8-bit Video Card)
* Video chip: 320x240 text mode, 320x240 graphic mode¹, sprites¹, 4-bit palettes¹, etc... **IMPLEMENTED!**
On the project/debugger side itself:
* A better way to **parse breakpoint input**. A known bug is that providing a label starting with a hexadecimal letter would be interpreted as a PC value instead of a label. For example, inputting *date_routine* as a label to break in would result in the addition of a breakpoint at address 0xda instead of the address of label *date_routine* (because *date* starts with hex letters *da*) **FIXED!**
## Contributing
Anyone can contribute to this project, contributions are welcome!
Feel free to fix any bug that you may see or encounter, implement any feature that is present in the TODO list or a new one that you find useful or important.
To contribute:
* Fork the Project
* Create your feature Branch (*optional*)
* Commit your changes. Please make a clear and concise commit message (*)
* Push to the branch
* Open a Pull Request
(*) A good commit message is as follows:
```plain
Module: add/fix/remove a from b
Explanation on what/how/why
```
For example:
```plain
Video chip: implement 320x240 text-mode
It is now possible to switch to 320x240 text-mode and display text.
```
## License
`Z80.js` file is distributed under the MIT licence (originated from Molly Howell repository: [Z80.js](https://github.com/DrGoldfire/Z80.js))
All the other files are distributed under the Apache 2.0 License. See `LICENSE` file for more information.
You are free to use it for personal and commercial use, the boilerplate present in each file must not be removed.
## Contact
For any suggestion or request, you can contact me at `contact [at] zeal8bit [dot] com`
For feature requests, you can also open an issue or a pull request.