{"id":25296695,"url":"https://github.com/zeal8bit/zeal-webemulator","last_synced_at":"2025-04-06T00:08:27.765Z","repository":{"id":151983785,"uuid":"534191686","full_name":"Zeal8bit/Zeal-WebEmulator","owner":"Zeal8bit","description":"A browser-based emulator for Zeal 8-bit Computer","archived":false,"fork":false,"pushed_at":"2025-02-15T02:49:32.000Z","size":3399,"stargazers_count":95,"open_issues_count":2,"forks_count":25,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-29T23:08:28.192Z","etag":null,"topics":["8-bit","emulator","retrocomputing","z80"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zeal8bit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-08T12:01:06.000Z","updated_at":"2025-02-19T14:45:20.000Z","dependencies_parsed_at":"2023-11-30T05:22:43.036Z","dependency_job_id":"e7c6047a-28e0-4379-9bbd-dfc55673e4d0","html_url":"https://github.com/Zeal8bit/Zeal-WebEmulator","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-WebEmulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-WebEmulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-WebEmulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zeal8bit%2FZeal-WebEmulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zeal8bit","download_url":"https://codeload.github.com/Zeal8bit/Zeal-WebEmulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["8-bit","emulator","retrocomputing","z80"],"created_at":"2025-02-13T02:59:02.212Z","updated_at":"2025-04-06T00:08:27.741Z","avatar_url":"https://github.com/Zeal8bit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eZeal 8-bit Computer emulator\u003c/h1\u003e\n\u003cp align=center\u003e\n    \u003cimg src=\"imgs/screenshot.png\" alt=\"screenshot\" /\u003e\n    \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"Licence\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://space.bilibili.com/1042658991?spm_id_from=333.337.0.0\"\u003e\n        \u003cimg alt=\"bilibili\" src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.swo.moe%2Fstats%2Fbilibili%2F1042658991\u0026query=count\u0026color=282c34\u0026label=bilibili\u0026labelColor=FE7398\u0026logo=bilibili\u0026logoColor=white\u0026logoSvg=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB2aWV3Qm94PSIwIDAgNTIgNTIiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI%2BPHBhdGggZD0iTTEuMzczNTIgMTcuMzUzMjJIOC4xMzUzMjNMMTcuMzUzMjIgMTYuNzUzMjF6IE0yLjEzNTMyIDMuMDAwMDJMMi4xMzUzMjIgMy4wMDAwMnoiLz48L3N2Zz4%3D)\"/\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nEnglish | \u003ca href=\"docs/README_zh_hans.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\nThis project is a software emulator for Zeal 8-bit Computer: a homebrew 8-bit computer based on a Z80 CPU.\n\n[Click here for a live demo](https://zeal8bit.github.io/Zeal-WebEmulator/)\n\n## Why this project?\n\nThe 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.\n\n## Why a web-based emulator? (HTML/CSS/JavaScript)\n\nThe 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.\n\nOn 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.\n\nThe emulator has been tested on Opera, Google Chrome and Microsoft Edge.\n\n## What about performance then?\n\nThe 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.\n\nWriting 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.\n\n## How to start using the emulator?\n\nSeveral choices are offered to you:\n\n* 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\n* Clone this repository and open the `index.html` page with a web browser: Chrome or Opera preferred.\n* Create an application out of this repo by using electron. More details below.\n\n### Get started with electron?\n\n#### Install dependencies\n\nFirst 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:\n\n```bash\ncd /path/to/Zeal-WebEmulator\nyarn install\n```\n\nIf you are using `npm`, the commands are as follows:\n\n```bash\ncd /path/to/Zeal-WebEmulator\nnpm install\n```\n\nIf you encounter any issues, you can find more information on [the official electron forge website](https://www.electronforge.io/import-existing-project).\n\n#### Running\n\nOnce the dependencies are ready, it can be executed thanks to `yarn start` or `npm start` commands.\n\n#### Compiling\n\nSupported architectures are the following: `win`, `win64`, and `linux`.\n\nChoose your architecture and replace it in either `npm run dist-\u003carch\u003e` or `yarn dist-\u003carch\u003e` commands to compile the project.\n\n\nFor example, if you want to build for Windows x64, run the following command:\n\n```bash\nnpm run dist-win64\n```\n\nor:\n\n```bash\nyarn dist-win64\n```\n\n## Supported Features\n\nCurrently, the following features from Zeal 8-bit Computer are emulated:\n\n* Z80 CPU ([thanks to *Molly Howell*](https://github.com/DrGoldfire/Z80.js))\n* Z80 PIO: all modes supported, both port A and B. Implementation is independent of connected devices.\n* 22-bit MMU\n* 256KB ROM\n* 512KB RAM\n* 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\n* PS/2 Keyboard, with interrupts\n* UART: it is possible to send and receive bytes. It is also possible to send files. The baudrate can be changed from the GUI\n* I2C: bus emulated, supporting write/read/write-read operations\n* I2C RTC: always returns the current date\n* I2C EEPROM: 24C512 is emulated, so hardcoded to be a 64KB EEPROM. Content can be loaded through the GUI.\n\nFeatures of the emulator itself implemented:\n\n* Debugger: breakpoints, step, step over instruction, continue until next breakpoint\n* Disassembler: when the emulator reaches a breakpoint, the code at *Program Counter* is disassembled. Clicking on one of the instructions will toggle a breakpoint.\n* Load a binary file, loaded into ROM directly\n* Load a map file generated from `z88dk-z88dk` to view symbols in the assembly view when doing step-by-step debugging\n* Set breakpoints with either a **hexadecimal** PC address or a symbol (from the map file)\n* View memory content when doing step-by-step debugging\n* Dedicated tab for the UART view: can send files to the emulated target\n\n## TODO\n\nOn the emulation side, the remaining tasks to do are:\n\n* I2C RTC set date. Currently, it always returns the current browser date, so writing to it will have no effect.\n* \u003cs\u003eSound support (part of Zeal 8-bit Video Card)\u003c/s\u003e **IMPLEMENTED!** waveforms table and custom sample implemented! (noise still needs to be implemented)\n* SD Card emulation (part of Zeal 8-bit Video Card)\n* \u003cs\u003eVideo chip: 320x240 text mode, 320x240 graphic mode¹, sprites¹, 4-bit palettes¹, etc...\u003c/s\u003e **IMPLEMENTED!**\n\n\nOn the project/debugger side itself:\n\n* \u003cs\u003eA 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*)\u003c/s\u003e **FIXED!**\n\n## Contributing\n\nAnyone can contribute to this project, contributions are welcome!\n\nFeel 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.\n\nTo contribute:\n\n* Fork the Project\n* Create your feature Branch (*optional*)\n* Commit your changes. Please make a clear and concise commit message (*)\n* Push to the branch\n* Open a Pull Request\n\n(*) A good commit message is as follows:\n\n```plain\nModule: add/fix/remove a from b\n\nExplanation on what/how/why\n```\n\nFor example:\n\n```plain\nVideo chip: implement 320x240 text-mode\n\nIt is now possible to switch to 320x240 text-mode and display text.\n```\n\n## License\n\n`Z80.js` file is distributed under the MIT licence (originated from Molly Howell repository: [Z80.js](https://github.com/DrGoldfire/Z80.js))\n\nAll the other files are distributed under the Apache 2.0 License. See `LICENSE` file for more information.\n\nYou are free to use it for personal and commercial use, the boilerplate present in each file must not be removed.\n\n## Contact\n\nFor any suggestion or request, you can contact me at `contact [at] zeal8bit [dot] com`\n\nFor feature requests, you can also open an issue or a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeal8bit%2Fzeal-webemulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeal8bit%2Fzeal-webemulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeal8bit%2Fzeal-webemulator/lists"}