README.md1# jgenesis 2 3Cross-platform multi-console emulator supporting a number of 8-bit and 16-bit gaming consoles. 4 5Linux, Windows, and web (WASM) are officially supported. Other platforms may work but have not been tested. 6 7## Features 8 9* Emulation for the following consoles: 10 * Sega Genesis / Mega Drive 11 * Sega CD / Mega CD 12 * Sega 32X / Mega 32X 13 * SG-1000 14 * Sega Master System / Mark III 15 * Game Gear 16 * Nintendo Entertainment System (NES) / Famicom 17 * Super Nintendo Entertainment System (SNES) / Super Famicom 18 * Game Boy / Game Boy Color 19 * Game Boy Advance 20 * PC Engine / TurboGrafx-16 (No CD-ROM<sup>2</sup> support yet) 21* GPU-based renderer with integer prescaling and optional linear interpolation 22* Configurable pixel aspect ratio for each console with several different options: accurate to original hardware/TVs, square pixels, and stretched to fill the window 23* Support for the Sega Master System FM sound unit expansion 24* Support for the Sega Genesis SVP chip, used in _Virtua Racing_ 25* Support for the most common NES mappers, plus a number of less common mappers 26* Support for most SNES coprocessors (e.g. Super FX, SA-1, DSP-1, CX4, S-DD1, SPC7110) 27* Support for both 3-button and 6-button Genesis controllers 28* Support for keyboard controls and DirectInput gamepad controls 29* Save states, fast forward, and rewind 30* Some simple horizontal blur and naive anti-dither shaders for blending dithered pixel patterns, which were extremely common on these consoles due to limited color palettes and lack of hardware-supported transparency 31* Optional CPU overclocking for Sega Master System, Game Gear, and Genesis emulation 32* Optional 2-4x GSU overclocking for SNES Super FX games 33* Can run the Titan Overdrive and Titan Overdrive 2 demos for the Mega Drive 34 35## System Requirements 36 37* **CPU**: Published release builds require a 64-bit x86 CPU with SSE4.2 support (every x86 CPU made since ~2011 should have this) 38 * Builds from source have no particular CPU requirements 39* **GPU**: Must support Vulkan (cross-platform) or DirectX 12 (Windows 10+) 40* **RAM**: 300 MB free or so should be enough with default settings 41 * Some settings can significantly increase RAM usage, e.g. increasing rewind buffer length or loading CD-ROM images into RAM 42 43## Dev Builds 44 45The GitHub Actions workflow compiles release builds on every commit, which will stay available for 90 days afterwards: 46https://github.com/jsgroth/jgenesis/actions 47 48Note that these builds are not always well-tested and may have bugs. 49 50## Build & Run 51 52See [BUILD.md](BUILD.md) 53 54## License 55 56All code in this repository is licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) unless explicitly stated otherwise at the top of the file (for example, some shader files are MIT-licensed). 57 58## Screenshots 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74## Sources 75 76### Sega Master System / Game Gear 77* Z80 User Manual: <https://map.grauw.nl/resources/cpu/z80.pdf> 78* The Undocumented Z80 Documented: http://www.myquest.nl/z80undocumented/z80-documented-v0.91.pdf 79* Sega Master System architecture: <https://www.copetti.org/writings/consoles/master-system/> 80* Sega Master System / Game Gear documentation: <https://www.smspower.org/Development/Documents> 81* YM2413 application manual: <https://www.smspower.org/maxim/Documents/YM2413ApplicationManual> 82* Reverse engineering of the YM2413: <https://github.com/andete/ym2413> 83 84### Sega Genesis / Mega Drive 85* M68000 Family Programmer's Reference Manual: <https://www.nxp.com/docs/en/reference-manual/M68000PRM.pdf> 86* Motorola 68000 Opcodes: http://goldencrystal.free.fr/M68kOpcodes.pdf 87* Mega Drive / Genesis architecture: <https://www.copetti.org/writings/consoles/mega-drive-genesis/> 88* Mega Drive official documentation: <https://segaretro.org/Mega_Drive_official_documentation> 89* Sega Genesis hardware notes by Charles MacDonald: <https://gendev.spritesmind.net/mirrors/cmd/gen-hw.txt> 90* Aggregating Community Research: <https://gendev.spritesmind.net/forum/viewtopic.php?f=2&t=2227> 91* Mega Drive video timings: <https://gendev.spritesmind.net/forum/viewtopic.php?f=22&t=519> 92* Genesis ROM header reference: <https://plutiedev.com/rom-header> 93* Genesis - Going beyond 4MB: <https://plutiedev.com/beyond-4mb> 94* SEGA Mega Drive / Genesis hardware notes by Kabuto: <https://plutiedev.com/mirror/kabuto-hardware-notes> 95* Huge thread discussing and detailing the YM2612: <https://gendev.spritesmind.net/forum/viewtopic.php?f=24&t=386> 96* Genesis EEPROM games: <https://gendev.spritesmind.net/forum/viewtopic.php?f=25&t=206> 97* SVP documentation by notaz, as well as earlier documentation work by Tasco Deluxe: <https://notaz.gp2x.de/docs/svpdoc.txt> 98 99### Sega CD / Mega CD 100* Mega CD official documentation: <https://segaretro.org/Mega-CD_official_documentation> 101* ECMA-130 standard: <https://www.ecma-international.org/publications-and-standards/standards/ecma-130/> 102* Thread discussing details of Mega CD emulation: <https://gendev.spritesmind.net/forum/viewtopic.php?t=3020> 103 104### 32X 105* 32X official documentation: <https://segaretro.org/32X_official_documentation> 106* SH-1/SH-2 programming manual: <https://antime.kapsi.fi/sega/files/h12p0.pdf> 107* SH7604 hardware manual: <https://segaretro.org/images/2/2c/SH7604_Hardware_Manual.pdf> 108 109### NES 110* 6502 Instruction Set: <https://www.masswerk.at/6502/6502_instruction_set.html> 111* 6502 Hardware Manual: <https://web.archive.org/web/20120227142944if_/http://archive.6502.org:80/datasheets/synertek_hardware_manual.pdf> 112* Documentation for the NMOS 65xx/85xx Instruction Set: <https://www.nesdev.org/6502_cpu.txt> 113* Nintendo Entertainment System (NES) architecture: <https://www.copetti.org/writings/consoles/nes/> 114* NESDev NES reference guide: <https://www.nesdev.org/wiki/NES_reference_guide> 115 116### SNES 117* A 65816 Primer: <https://softpixel.com/~cwright/sianse/docs/65816NFO.HTM> 118* Super Nintendo architecture: <https://www.copetti.org/writings/consoles/super-nintendo/> 119* fullsnes - nocash SNES hardware specifications: <https://problemkaputt.de/fullsnes.htm> 120* Anomie's SNES documents: <https://www.romhacking.net/?page=documents&category=&platform=&game=&author=&perpage=20&level=&title=anomie&docsearch=Go> 121* SFC Development Wiki: <https://wiki.superfamicom.org/> 122 123### Game Boy / Game Boy Color 124* Game Boy CPU (SM83) Instruction Set: <https://gbdev.io/gb-opcodes/optables/> 125* Pan Docs: <https://gbdev.io/pandocs/> 126* Game Boy Complete Technical Reference: <https://gekkio.fi/files/gb-docs/gbctr.pdf> 127* Gameboy Sound Hardware: <https://gbdev.gg8.se/wiki/articles/Gameboy_sound_hardware> 128* The Cycle-Accurate Game Boy Docs: <https://github.com/geaz/emu-gameboy/blob/master/docs/The%20Cycle-Accurate%20Game%20Boy%20Docs.pdf> 129 * This contains some outdated/incorrect information but is still useful 130 131### Game Boy Advance 132* Game Boy Advance Architecture: <https://www.copetti.org/writings/consoles/game-boy-advance/> 133* ARM7TDMI Technical Reference Manual: <https://www.csd.uoc.gr/~hy428/reading/ARM7TDMI_Technical_Reference_Manual.pdf> 134* GBATEK - GBA/NDS technical info: <https://problemkaputt.de/gbatek.htm> 135* Tonc - GBA programming guide: <https://gbadev.net/tonc/foreword.html> 136* mGBA blog: <https://mgba.io/tag/development/> 137* NanoBoyAdvance hardware documentation: <https://nba-emu.github.io/hw-docs/foreword.html> 138 139### PC Engine / TurboGrafx-16 140* PC Engine / TurboGrafx-16 Architecture: <https://www.copetti.org/writings/consoles/pc-engine/> 141* PC Engine Developer Documentation: <https://archive.org/details/PCEDev> 142* HuC6280 opcode matrix: <https://www.chrismcovell.com/PCEdev/HuC6280_opcodes.html> 143* TurboGrafx-16 Hardware Notes by Charles MacDonald: <https://www.romhacking.net/documents/302/> 144* [Screen Resolution, VDC Setup, and Sprite Limits](https://web.archive.org/web/20250903193836/https://pcengine.proboards.com/thread/639/screen-resolution-setup-sprite-limits) 145* [Mednafen](https://mednafen.github.io/) and [Mesen](https://mesen.ca/) as references for some poorly-documented edge case behaviors