What is it?

Vinegar is a CHIP-8 and SCHIP 'emulator'/interpreter.

CHIP-8 was a simple language interpreter found on some early home computers, and has a very small instruction set. The machines it ran on had a 64x32 resolution display; they also had a simple hex keypads (a 4x4 grid of keys 0 to F) for input, which might explain the odd key layout this program uses.

CHIP-8 was revisited in the 1990s thanks to an interpeter for the HP48 calculator. The instruction set was extended and the screen resolution doubled to 128x64, but is fully backwards compatible with the original CHIP-8. This is the "SUPER-CHIP" (SCHIP) part of this interpreter.

It is easy to find programs in CHIP-8 or SCHIP, and using the command script file included you can easily convert the files to a format that can be sent to your calculator.

Features

• Almost complete CHIP-8 and SCHIP opcode support.
• 128x64 SCHIP mode is either presented in pan-and-scan or squashed 96x64 resolution to fit it on the small calculator display.
• Detailed configuration screen allows you to fine-tune speed of the simulation.
• Sound.
• Error trapping.

Limitations

• No 1802 emulation (the PC CHIP-8 emulators I've used ignore this as well).
• Games must be loaded at $200. I store the font data in the first 512 bytes, as this saves me from having to allocate even more memory than the already generous 5KB required. There is only one ROM, to my knowledge, that requires to be loaded to $000 (the CHIP-8 editor that allows you to type in CHIP-8 code and then execute it).
• As sound is done in software, emulation slows down when the sound is playing.
• I have no idea what the HP48 flags are meant to do. You can copy registers V0 to V7 to and from them in Vinegar, so if a program uses them as temporary storage then that's all well and good.
• As the CHIP-8 display is handled at a 1:1 resolution, not stretched to 2:1, half-pixel scrolls don't work.

Usage

This package comes with 3 binaries; one for TI-83, and two for TI-83 Plus. Send the one that best matches your calculator model and shell to your calculator using your linking program.

You won't be able to use this interpreter without having a few CHIP-8 programs installed. I've included a rather large number of them in the ROMs subfolder of this package. Note that ones with (CHIP-8) in their name are CHIP-8 programs, and that ones with (SCHIP) in their name are SCHIP programs.

If you run the program, you should be able to see the installed program in a list, a bit like Ion's main view. Highlight the program you wish to start, then press 2nd or Enter to run it.

The key layout is a little odd; here is a CHIP-8 keypad and a TI-83 keypad for comparison.

The other keys for this program are:

The settings screen (Alpha) is very useful when it comes to setting the speed of the simulation.

The various options can be summarised thusly:

• Instruction delay - the length of the delay after each instruction. This can be useful to throttle games that run too quickly.
• Frame skip - the number of instructions executed per frame.
• Timer speed - the speed of the CHIP-8 timers in Hertz.
• Always refresh LCD - refresh the LCD, regardless of whether a sprite was drawn or not. Disabling this makes the simulation faster, but makes the timing more inconsistent.
• 96x64 SCHIP mode - enabling this squashes the display from pan-and-scan 128x64 mode to 96x64 mode. Due to the aliasing caused by the squashing, the squashing is altered slightly every other frame to create a greyscale effect. Therefore it is recommended that you leave Always refresh LCD enabled in this mode. Naturally, the squashing process slows the simulation down a little, so it is recommended that you use a larger frame skip.
• Invert colours - draw as white-on-black, rather than black-on-white.
• Ignore errors - if the simulation encounters an error (see below), do not display a prompt - just carry on. For some games, this doesn't appear to have an effect, but certain games depend on an unsupported instruction and will "crash" inside the simulation.
• Enable sound - when enabled, you can plug a pair of headphones via an adapter into the calculator's link port and hear the CHIP-8 beep.

In terms of general speed settings, the fastest possible simulation is to have an Instruction delay of 0, a Frame skip of 255, and Always refresh LCD and sound disabled. The slowest is to have a delay of 255, a skip of 0, LCD refreshing and sound on.

Here is a comparison between the 128x64 and 96x64 SCHIP modes (the game is "Joust"):

128x64	96x64

The timer speed only applies to games that use it (such as Joust) to throttle their speed. It is in Hertz; the original CHIP-8 was 60Hz.

Note that games can only check for it to go zero; if the emulation is running slowly (long delays, low frame skip, always refresh LCD) then it might reach zero a long time before the game gets a chance to read it. However, speeding up the emulation (low delays, high frame skip) will not cause this timer to finish earlier, and it caps the speed.

I calibrated the speed using a program on my PC to time the interrupt rate of my calculator (~110Hz), and it ticks at as close to 60Hz as you're going to get by default. Different hardware and battery levels will skew the rate slightly. I'd be interested to see how this works on a crystal-based calculator, as I believe you can adjust the rate of the interrupts more precisely.

Errors

CHIP-8 is a high-level low-level language, and as such can potentially muck up whatever it is you are running it on.

Vinegar checks the stack level, data pointer, current instruction and program counter whenever it's about to use them for something potentially dangerous. If it senses that something is wrong, you'll end up with a screen like the following:

The three reported value are program counter, opcode and index register. The different errors are:

• Instruction - the current instruction is not recognised or supported.
• Stack - the stack has underflowed or overflowed. It is suggested that implementations support 16 levels; Vinegar has 64, so I hope that's enough.
• PC - the program counter has ambled out of the ~3.5KB allowed memory space.
• Data - the program was about to copy data to memory outside of the allowed memory space.

You can disable this error screen on the settings page; beware that this will cause some simulated programs to 'crash' (there should be no danger to your calculator).

Converting

In the root of this zip file is a Windows application, CHIP-8 Converter. If you download a CHIP-8/SCHIP game you want to play on your calculator, drag-and-drop it on top of the EXE file and it will output two calculator files (8xp and 83p) for use with Vinegar.

If you feel bold and daring, run this program from your command-line with the syntax:

"CHIP-8 Converter.exe" filename programname caption

...where filename is the name of the CHIP-8 program, programname is the name of the program on the calculator, and caption is the caption displayed by Vinegar.

Thanks

• David Winter - CHIP-8/SCHIP documentation, author of a lot of the bundled ROMs.
• hap - large font is from his Fish 'N' Chips emulator, the ROMs are also the ones bundled with said emulator.