https://github.com/wyattferguson/chip8-emulator
Chip-8 Emulator in Python
https://github.com/wyattferguson/chip8-emulator
chip8 chip8-emulator python python3
Last synced: about 1 month ago
JSON representation
Chip-8 Emulator in Python
- Host: GitHub
- URL: https://github.com/wyattferguson/chip8-emulator
- Owner: wyattferguson
- License: mit
- Created: 2023-05-21T19:53:51.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2026-04-20T08:25:23.000Z (about 1 month ago)
- Last Synced: 2026-04-20T08:28:14.912Z (about 1 month ago)
- Topics: chip8, chip8-emulator, python, python3
- Language: Python
- Homepage:
- Size: 131 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# :robot: Chip-8 Emulator
This is my Chip-8 emulator I built in Python. Created in 1977, CHIP-8 is the original fantasy console. Initially designed to ease game development for the COSMAC VIP kit computer. I built this as a learning project to learn the basics of emulation. A few notes:
- All 34 instructions are here +1 from the extended set.
- Some ROMS for testing have been included in the `/roms/` folder.
- A full battery of tests to veryify opcode and hardware function.
## Setup + Run Emulator
Installation is pretty straight forward, Im using [UV](https://docs.astral.sh/uv/) to manage everything.
To get it all running from scratch:
```bash
# spin up a virtual enviroment
uv venv
# activate virtual enviroment
.venv\Scripts\activate
# install all the cool dependancies
uv sync
# Run the default rom (particle.ch8)
task run
# You can pass another rom with the -r flag
task run -r ./roms/walk.ch8
# The screen scale can be adjusted with the -s flag (ie. -s 15 will scale is 15x the original resolution of 64x32)
task run -s 15
```
## Development Tools
I've included a few shortcuts for linting, formating, and tests.
```bash
# lint source
task lint
# format source with ruff
task format
# run full battery of pytests
task tests
```
## Chip8 Specifications
- Memory: CHIP-8 has direct access to up to 4 kilobytes of RAM
- Display: 64 x 32 pixels (or 128 x 64 for SUPER-CHIP) monochrome, ie. black or white
- A program counter, often called just “PC”, which points at the current instruction in memory
- One 16-bit index register called “I” which is used to point at locations in memory
- A stack for 16-bit addresses, which is used to call subroutines/functions and return from them
- An 8-bit delay timer which is decremented at a rate of 60 Hz (60 times per second) until it reaches 0
- An 8-bit sound timer which functions like the delay timer, but which also gives off a beeping sound as long as it’s not 0
- 16 8-bit (one byte) general-purpose variable registers numbered 0 through F hexadecimal, ie. 0 through 15 in decimal, called V0 through VF
- VF is also used as a flag register; many instructions will set it to either 1 or 0 based on some rule, for example using it as a carry flag
## Controls
For CHIP-8 emulators that run on modern PCs, it’s customary to use the left side of the QWERTY keyboard for this:
```bash
CHIP-8: 1 2 3 C Keyboard: 1 2 3 4
4 5 6 D Q W E R
7 8 9 E A S D F
A 0 B F Z X C V
```
## References
- Guide to making a CHIP-8 emulator ([https://tobiasvl.github.io/blog/write-a-chip-8-emulator/](https://tobiasvl.github.io/blog/write-a-chip-8-emulator/))
- Octo CHIP-8 Assember - ([https://johnearnest.github.io/Octo/](https://johnearnest.github.io/Octo/))
- CHIP-8 Wikipedia ([https://en.wikipedia.org/wiki/CHIP-8](https://en.wikipedia.org/wiki/CHIP-8))
- Bitwise Operators in Python ([https://realpython.com/python-bitwise-operators/#binary-number-representations](https://realpython.com/python-bitwise-operators/#binary-number-representations))
- Chip-8 Test Rom ([https://github.com/corax89/chip8-test-rom](https://github.com/corax89/chip8-test-rom))
- Chip-8 Variant Opcode Table ([https://chip8.gulrak.net/](https://chip8.gulrak.net/))
## License
[MIT license](https://github.com/wyattferguson/chip8-emulator/blob/master/LICENSE)
## Contact & Support
Created by [Wyatt Ferguson](https://github.com/wyattferguson)
For any questions or comments heres how you can reach me:
### :octocat: Follow me on [Github @wyattferguson](https://github.com/wyattferguson)
### :mailbox_with_mail: Email me at [wyattxdev@duck.com](wyattxdev@duck.com)
### :tropical_drink: Follow on [BlueSky @wyattf](https://wyattf.bsky.social)
If you find this useful and want to tip me a little coffee money:
### :coffee: [Buy Me A Coffee](https://www.buymeacoffee.com/wyattferguson)