diesel-net / kiwi-8

CHIP-8 interpreter for Windows and MacOS

fleet

Leveraging Docker Engine's built-in Swarm Mode on Ubuntu Server LTS Virtual Machines. This is the first piece of code that should be executed against a fresh host on the diesel.net domain

Checking-In New Hosts

To add a new host (or set of hosts) create a new local branch name with the pattern check-in/*, add the new hosts and their configuration to the inventory, then push. Please delete your check-in/* branch after merging.

Bootstrapping Hosts

Pushes to stable branches will trigger the entire fleet to be bootstrapped.

Updating Hosts

You will need the following installed:

Python 3.11+

1. Create a Python Virtual Environment (venv) and activate it.

   python3 -m venv venv

   source venv/bin/activate

2. Install Ansible.

   pip install --upgrade pip setuptools wheel pip-tools

   pip install ansible==7.2.0

3. Install Ansible roles.

   ansible-galaxy install --force --role-file .ansible/roles/check-in_requirements.yaml --roles-path .ansible/roles

4. Update all the Ubuntu hosts's Apt packages and reboot if necessary.

   ansible-playbook --inventory .ansible/inventories/dev  --inventory .ansible/inventories/prod --extra-vars auto_reboot=yes .ansible/update.yaml

kiwi-8's Issues

SDL2 Fullscreen Toggling on MacOS

Full screen toggling using SDL2 is very buggy on MacOS right now. Switching to fullscreen when a ROM is in at the "end state" (infinite loop, no more rendering to be done, etc.) causes the image to appear for a split second. The issue is resolved by cmd+tabbing out and back into the window.

TODO:
Update both Windows and MacOS frameworks to the latest version of SDL2

Linux?

I'll get to it eventually.

Code Style

This is a reminder for me to fix the style of functions or function calls that have parameters which cause the call to span multiple lines. The indentation is inconsistent.

Audio

No audio has been implemented yet.

Timing of checking the input

Need to confirm and research relative timings of checking the keypad

Text in "Animal Race" is incorrect

If you load up "Animal Race", the text is not correct. The first sprite of the text seems to be repeated.

Reported by @cassianoperin here in #9.

Timing

CPU timing and Sound timers not implemented. Games might not work at all or appear to run faster/slower than intended.

High CPU Usage

Hovering around (13% - Windows) and (99% - MacOS) which confirms the program is maxing out an entire core. Windows and Mac OS X report CPU usage differently. Windows reports it as a true percentage between all of the cores while Mac OS X reports it as a percentage of a single core being used.

Suggested to go back and try using SDL_Delay(), to truly eliminate the "busy-waiting" for-loop.

Reddit discussion reference:
https://www.reddit.com/r/EmuDev/comments/5zb6w0/c_chip_8_emulator_high_cpu_usage/

Switch from ANSI/ASCII to UNICODE

Areas affected.

• program arguments
• open file dialog filenames

This is a reminder to switch to unicode before the next release.

File Menu

Add a file menu to support toggling certain features on/off. This should also allow the user to change the foreground/background colors.

Backwards Compatibility for older Windows and MacOS versions

I haven't tested the binaries on other systems than my own. I know for a fact that I need to add the linker flag: -mmacosx-version-min=10.5 to make sure the MacOS app can run on older versions of MacOS.

Add CI/CD build pipelines for Windows/MacOS/Linux

• Would be cool to have them automatically publish somewhere as well. Itch.io?

Opcode 0xFX55

If any ROM uses this opcode, Soft-resetting will most likely result in buggy behavior (e.g. pixels rendered where they are not supposed to be). This is due to the fact that soft-resetting clears everything BUT the memory in the current implementation. I originally thought I could get away with this, but the entire memory should be cleared and the rom copied back at offset 0x200 every time.

DXYN Vertical Wrapping

Add a toggle to allow turning vertical wrapping on or off. Some games break with it on, some games break with it off.

ROM compatibility (tentative)

Here is an incomplete list of known CHIP-8 programs that require special settings to run properly, those that have unresolved issues with my emulator, or those that simply have issues in general. Some of these settings or "quirks" will apply to other CHIP-8 emulators as well so I wanted to take this chance to document something that should've been documented a long time ago. Hopefully this will shed some light on the discrepancies between the various CHIP-8 documents and opcode implementations that you will find all over the web.

• Astro Dodge [Revival Studios, 2008]
  • Problem: Garbage on sides of screen, score won't increment.
  • Fix: load_store_quirk = 1
• Tic-Tac-Toe [David Winter]
  • Problem: Score won't increment.
  • Fix: load_store_quirk = 1
• Animal Race [Brian Astle]
  • Problem: Rendered Garbage, text unreadable.
  • Fix:
  • Problem: Animal sprites are all messed up.
  • Fix: load_store_quirk = 0
• BMP Viewer - Hello (C8 example) [Hap, 2005]
  • Problem: Renders jumbled garbage on a single row at the top of the screen.
  • Fix: shift_quirk = 1
• Space Invaders [David Winter]
  • Problem: Aliens disappear and reappear in pairs when you hit only one.
  • Fix: shift_quirk = 1
• Blinky [Hans Christian Egeberg, 1991]
  • Problem: map is rendered improperly, unplayable.
  • Fix: shift_quirk = 1
  • Problem: Game freezes (ends) as soon as you hit a wall
  • Fix: load_store_quirk = 1
• Stars [Sergey Naydenov, 2010]
  • Problem: Stars don't start flashing, only dots appear.
  • Fix: load_store_quirk = 1
• Missile [David Winter]
  • Problem: Sprite disappears when it start moving too fast.
  • Fix: Run the interpreter at anything <=720 instr/sec.
• Space Intercept [Joseph Weisbecker, 1978]
  • Problem: Ship flickers and goes away for a few seconds at a time.
  • Fix: Run the interpreter at anything <=600 instr/sec.
• Connect 4 [David Winter]
  • Problem: Game pieces overwrite each other and only stack diagonally.
  • Fix: load_store_quirk = 1
• Keypad Test [Hap, 2006]
  • Problem: keypad does not render properly
  • Fix: shift_quirk = 1
• Hidden [David Winter, 1996]
  • Problem: The last two tiles left are different, so you can't beat the game.
  • Fix: load_store_quirk = 1

Deadlock

Occasional deadlock after new implementation which reduces CPU usage

Most important issue right now. Currently using a recursive mutex which implies that locking more than once should be OK, however results are iffy.

Switch to using SemVer

• on next release?

opcode 0x0NNN not implemented

0nnn - SYS addr
Jump to a machine code routine at nnn.

This instruction is only used on the old computers on which Chip-8 was originally implemented. It is ignored by modern interpreters.

*0x02D8 opcode found in "Clock Program [Bill Fisher, 1981].ch8"

Config Files

Add support for creation and modification of config files for first launch of game. If config file already exists then use the settings applied in the file.

Debugger

GUI debugger would be nice.

60 FPS Limit enabled, but displays 62 FPS?

This is most likely due to the fact that I am currently using SDL_GetTicks() for timing control. This function has a nasty precision of about 10ms. I would need to switch to high performance timers for more accurate timing of the frame-rate as well as the emulator itself. The current FPS display is an average, so it isn't too accurate just by nature and is more of a debugging tool.

Edit: I think I may actually be rednering a few extra frames, this is a reminder to look into this.

ZXYN opcode

TODO: Use modulo to wrap around the the edges of the screen

Opcode 0xFX0A

This opcode is supposed to pause emulation until a key is pressed. I just realized that its simply returning without updating the Program Counter until a key is pressed. This is incorrect and could explain the input issues with the Rom's Connect4 and ClockProgram.