❯ Bringing CHIP-8 classics back to life — now in Kotlin
- 🔍 Overview
- ✨ Features
- 🏗️ Project Structure
- 🚀 Getting Started
- 🛣️ Project Roadmap
- 🤝 Contributing
- 📚 Reference
This implementation of the Chip-8 was a first step on my learning of emulation.
The main goal of this investigation process is to achieve a complete Game Boy Color emulator as it was one that gave me lots of happy times throughout my childhood. This is my way to push myself to further extents as a Recognition to all of those who came up with those emulators at the time
The main ideas behind the project were:
- Learn how a System can be modeled into an emulator
- Ignore the memory aspects with a high level language first to learn step-by-step about emulation itself
- Create an emulator that can work as a reference for others by creating an object-oriented solution
- Practice modularization of the project by using maven submodules
- Create the same emulator in a low level language (either c or rust) to make emphasis on memory management
- Create a Game Boy Color emulator in the low level language selected
- Make a project till the end :)
❯ Complete CHIP-8 Interpreter: Faithfully executes classic CHIP-8 ROMs.
❯ Written in Kotlin: Modern, concise, and expressive codebase.
❯ Object-Oriented Design: Modular and extensible architecture, easy to understand and maintain.
❯ Keyboard Input Handling: Maps CHIP-8 keys to your physical keyboard for interactive gameplay.
❯ Sound Support: Beep emulation for authentic CHIP-8 audio feedback.
❯ Test ROM Suite: Includes a comprehensive set of test ROMs to verify emulator correctness and compatibility.
❯ Maven Multi-Module Project: Clean separation of concerns between core, UI, controller, and system logic.
❯ Easy to Run & Extend: Simple entry point and clear structure for adding new features or learning about emulation.
❯ Open Source: MIT-licensed and open for contributions!
This Chip-8 project is divided into 4 Maven submodules.
└── Chip8-Kt/
├── chip8-app - This submodule only contains the Main file
├── controller - A mother board of sorts. Controls tickers and timers
├── ui - JavaFx UI implementation; Handles keyboard
├── roms - Rom selection
├── system - CPU implementation. Logic layer
└── pom.xml
To begin fiddling with the emulator I would suggest the system module.
The CPU class holds the state of the memory, registers, display, keyboard, etc.
The only method exposed by the cpu is the runCycle() where the cpu will fetch(), decode() and execute(command)
The Commands are implemented from an interface which only method is the execute()
Also, the system supports both the Chip-8 and Super-Chip-8 systems
CHIP8-KT/
chip8-app
src
main
kotlin
Main.kt ❯ Main File. The program runs from here
system
src
main
kotlin
com
tomassirio
emulation
chip8
system
memory
Memory.kt ❯ Chip8's Cpu Memory. 2048 bytespreload
FontSet.kt ❯ Fontset. Preloaded in the first 512 bytesfactory
MemoryFactory.kt ❯ Factory to create Memory instancesvalidator
MemoryValidator.kt ❯ Validates memory locking and overflowsaccessor
MemoryAccessor.kt ❯ Utility class to access Memory; Delegates responsibilitiesutil
MemoryUtils.kt ❯ Memory utility; Could be moved to Accessorconstants
Constants.kt ❯ System Constantsio
display
DisplayScroller.kt ❯ Takes responsibility for Scrolling; Super-Chip-8 featurePixelBuffer.kt ❯ Manages PixelsDisplayState.kt ❯ Facade for DisplayDisplayType.kt ❯ NORMAL/EXTENDED modesDisplayModeManager.kt ❯ Manages Display ModesSpriteDrawer.kt ❯ Draws Spriteskeyboard
KeyboardState.kt ❯ Holds state for keyboardcpu
CPUType.kt ❯ [CHIP-8/SUPER-CHIP-8]CPU.kt ❯ Main Class of the System. Fetches/Decodes/Executes codeopcode
Command.kt ❯ Command Interface. Executes commandsOpCodeTable.kt ❯ Holds mapping for all OpCodescommands
factory
CPUFactory.kt ❯ Creates CPU Instancesutils
SizedStack.kt ❯ Implementation of Stack with limited entriesregister
Register.kt ❯ [ByteRegister/ShortRegister/TimerRegister]Timer.kt ❯ Timer interface with Tick methodutils
RegisterSet.kt ❯ Util class
controller
src
main
kotlin
com
tomassirio
emulation
chip8
controller
SystemController.kt ❯ Facades the CPU; Works as a Main Boardsfx
SoundPlayer.kt ❯ Plays Sounds. Uses beep.wavloader
RomLoader.kt ❯ Loads Romsdebug
DebugLevel.kt ❯ [NONE/MINIMAL/FULL]CPUDebugger.kt ❯ Debugger class for CPUhandler
KeyHandler.kt ❯ Works on key eventsresources
beep.wav ❯ Sound resource
ui
src
main
kotlin
com
tomassirio
emulation
chip8
ui
EmulatorUI.kt ❯ Main Emulator classmapping
KeyMapper.kt ❯ Maps Keys to Chip8 keyboardparams
EmulatorParamsFactory.kt ❯ Gets parameters from ArgumentsEmulatorParams.kt ❯ Holds Emulator Paramspane
DebuggingPane.kt ❯ Dividing pane for CPU and Memory StateCPUStatePane.kt ❯ CPU State PaneMemoryPane.kt ❯ Memory Paneconstants
Constants.kt ❯ UI Constantsdebug
Debug.kt ❯ Debbugger interfacescene
MainScene.kt ❯ Main Scene where action happens
Before getting started with Chip8-Kt, ensure your runtime environment meets the following requirements:
- Programming Language: Kotlin
- Packaging: Maven
Install Chip8-Kt using one of the following methods:
Build from source:
- Clone the Chip8-Kt repository:
❯ git clone https://github.com/tomassirio/Chip8-Kt- Navigate to the project directory:
❯ cd Chip8-Kt- Install the project dependencies:
❯ mvn clean installIn order to run the project you will need a rom. This repository provides a selection of them in the /roms folder.
So after running mvn clean install you can just begin playing roms with
❯ java -jar chip8-app/target/chip8-app-1.0.0.jar --rom=roms/games/PONG This implementation of the Chip-8 console includes a few options you can play around with
--rom [Mandatory] declares path to rom
--cpu [CHIP8/SCHIP8](default=CHIP8) defines which system to emulate between the Chip-8 and Super-Chip
--debug [NONE/MINIMAL/FULL](default=NONE) debugging windows
--scale [Int](default=10) scale for the pixels in the screen
--fps [Int](default=15) Frames per second at which the rom will run
This project allows for two different types of testing. Both Unit tests and 'Rom-tests'
For the Unit tests you can test your project with
❯ mvn testor you can compile and test it with
❯ mvn clean verify The project can also be tested with the 'Rom-Tests' in the roms folder. Each of them can be ran as any other rom
❯ java -jar chip8-app/target/chip8-app-1.0.0.jar --rom=roms/test-suite/1-chip8-logo.ch8 roms test-suite
1-chip8-logo.ch8 ❯ Should print a Chip-8 logo2-ibm-logo.ch8 ❯ Should print an IBM logo3-corax+.ch8 ❯ Corax+ test ROM4-flags.ch8 ❯ Tests flag instructions5-quirks.ch8 ❯ Tests common CHIP-8 quirks6-keypad.ch8 ❯ Tests keypad input7-beep.ch8 ❯ Tests sound/beep functionality8-scrolling.ch8 ❯ Tests scrolling instructions
-
Task 1:Implement Chip-8 in Kotlin -
Task 2: Implement Chip-8 in Rust -
Bonus Task: Implement Nes in mmBASIC -
Task 3: Implement Gameboy Color in Rust
- 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
- 🐛 Report Issues: Submit bugs found or log feature requests for the
Chip8-Ktproject. - 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.
Contributing Guidelines
- Fork the Repository: Start by forking the project repository to your github account.
- Clone Locally: Clone the forked repository to your local machine using a git client.
git clone https://github.com/tomassirio/Chip8-Kt
- Create a New Branch: Always work on a new branch, giving it a descriptive name.
git checkout -b feature/[ticket#]new_feature_x
- Please use
feature/bugfix/hotfix/depending on the case
- Please use
- Make Your Changes: Develop and test your changes locally.
- Commit Your Changes: Commit with a clear message describing your updates.
git commit -m 'Implemented new feature x.' - Push to GitHub: Push the changes to your forked repository.
git push origin feature/[ticket#]new_feature_x
- Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
- Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
Contributor Graph
- Cowgod's Technical reference: http://devernay.free.fr/hacks/chip8/C8TECH10.HTM#2.2
- Wikipedia Chip 8 https://en.wikipedia.org/wiki/CHIP-8#Virtual_machine_description
- Timendus's Test suite https://github.com/Timendus/chip8-test-suite?tab=readme-ov-file#chip-8-splash-screen
- Devernay Super-Chip 8 http://devernay.free.fr/hacks/chip8/schip.txt