Table of Contents
JSMoo is an attempt at making great emulators, in pure JavaScript and AssemblyScript. Currently that includes NES, SNES, ZX Spectrum, and Sega Master System, with many more planned.
I also hope to make retro systems more accessible in every possible way, as I get into more detail below. But first...
JSMoo was born out of reading the source to Higan and various articles on the difficulty of emulating the SNES accurately. I thought that a lot of structural and organizational mistakes were made that slowed the codebase down a lot. Full 100%-accurate SNES emulation took very powerful hardware, but - or so I reasoned - I could do it on mid-range hardware, in JavaScript, as a challenge for myself.
I was right. I got the proof-of-concept working. Fully cycle-accurate 65816 emulation, not-quite-cycle-accurate SPC700 (this will change to fully accurate in the future), scanline-based PPU rendering, and no DSP emulation, all aligned perectly by the cycle, running Super Mario World and Zelda: Link to the Past, fast, on old-ish PCs, in pure JavaScript (on Chrome), with lots of headroom to spare
Surely, there's a lot left to do, but since the concept is currently proved, I have a new goal.
The biggest hassle with the source code to any emulator you find is building it. Even if you have the specialized knowledge required for whatever language and platforms the included build systems support, it can be a huge pain to compile the source. This is doubly true for emulators that target WebAssembly. I'd like to make good, well-written and performant emulators in JavaScript, arguably the best language in the world if you want ANYONE to be able to make changes and play with the code.
I'd also like to make Easy6502-like pages for each of the processors, to aid others' learning.
Basically, I want to make it as easy as possible in every possible way for anyone to play and understand vintage systems, processors, and ways of thinking.
I believe that understanding the way at least one microcomputer, such as an NES or Commodore64, works - fully and completely - irrevocably increases your competence as a programmer. This is a deep topic in the philosophy of software development, and beyond the scope of this README.
If I get super ambitious, I may even start SNES, NES, etc. development IDEs, but that would be very far off in the future.
I also keep a blog about development of JSMoo and emulators in genral.
Currently, running JSMoo is a little bit of a pain.
Because we use SharedArrayBuffers and need high-precision timers, we need to include special HTTP headers. This means you can't just click on index.html and play it off your disk, it must be served to your browser.
I've included a simple Python script that will serve it to [::1]:8000, which is the IPv6 equivalent of localhost. Just run the simple_py_server.py, and navigate to [::1]:8000 in Chrome, and you're set!
The UI has seen drastic improvements recently. Switching between systems now works ("SYSTEM SELECT"), and controls can be remapped under the "Settings" tab.
To upload a ROM, make sure you have the correct system selected. Then scroll down, on the left, is a nav button named 'Upload'. Click it, then select and upload a file.
However, SMS and ZX Spectrum require BIOSes. These can be uploaded under Settings/BIOS.
As of this commit, keyboard input on the Spectrum is temporarily broken, as I have been re-writing the input system to support easily re-assignable controls and have only re-implemented joypads thus far.
As for game, etc. compatability, check COMPATABILITY.TXT for a info.
If you want to serve it locally using the script I included, you need Python3.
If you want it to run fast, you need Chrome. Sorry. I believe in the importance of Firefox, but finding information about how to optimize for SpiderMonkey is not easy. If you have experience here I'd be super happy to hear from you!
You need any applicable BIOSes for any systems that require them (currently SMS and ZX Spectrum).
- Clone the repo
git clone https://github.com/raddad772/jsmoo.git
- Run the Python script
python3 simple_py_serve.py
- Navigate Chrome to [::1]:8000
- Get Sega Master System working
- Overhaul the UI to make it more usable and flexible
- Find hosting for demo site (GitHub pages will not work due to required specialized HTTP headers)
- Basic Commodore64 support
- Potentially, PS1 emulation, which I now believe is possible
- Sega Genesis
- Set up an Easy6502-like suite for each of the processors
- Polish existing emulators to improve compatability and speed
- Probably at this point, some refactoring to make the code more uniform and easier to learn from
See the open issues for a full list of proposed features (and known issues).
You can do the fork and PR thing, but don't go too crazy. I'll gladly accept bug fixes, optimizations, code clean-ups, and other changes that improve the existing components. Or if you want to go ahead and do the UI re-design for me, I hate UI stuff.
However for someone writing a whole new processor or system for inclusion, I'd like to have more of a partnership with people who share my vision of making retro systems accessible in every way to everyone - and you must also have some ability to write fast JavaScript code. I'm happy to guide someone, but I don't want just anything tacked onto JSMoo (at this point).
If you think that sounds like a fit for you, go through the trouble of finding my email address via my commits.
Or, if you want to work on bug fixes, etc., here's how to. And don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt for more information.
Project Link: https://github.com/raddad772/jsmoo
- Near, for his amazing work on Higan and contribution to the preservation and emulation of the SNES and other systems. I may criticize it for some of its design choices, but he still made an amazing set of emulators.
- The emulation community in general, without whom this project would be totally impossible.
- Thomas Harte, whose ProcessorTests have made my life a thousand times easier. Unit tests for processor emulators? BRILLIANT!