1. INTRODUCTION
--------------------------------------------------------------------------------

Chippi is a CHIP-8 emulator for the Intellivision, Tutor-Pro with additional 
GRAM or Tutorvision.  It provides a fairly comprehensive implementation of the
baseline CHIP-8 architecture:

    * Full compatibility with CHIP-8 programs including shift, memory 
      and display wait "quirks" modes
    * Emulation speed control / throttling
    * 7-colour monochrome 64x32 resolution graphics
    * Double resolution SuperGRAFIX mode on Tutorvision and Tutor-Pro with 
      2K GRAM
    * 3-voice monotone sound with 8 different (dis)chords
    * Volume control
    * CHIP-8 and ECS keyboard layouts

Chippi requires an ECS in addition to your Master Component as it loads CHIP-8
programs from ECS tapes.  Although it should be possible to play it on real
hardware (WAV files of the ECS tapes are included), for the best experience it 
is recommended to play using Joe Zbiciak's excellent JzIntv emulator 
configured to mimic a Tutor-Pro...


2. STARTING CHIPPI
--------------------------------------------------------------------------------

To play using JzIntv with Tutor-Pro extended GRAM start JzIntv with the 
following command line:

    jzintv.exe -s1 -G2 -b5 -z3 -m2 chippi.bin

The flags have the following effect:

    -s1 = enable ECS (mandatory)
    -G2 = enable additional Tutorvision GRAM for SuperGRAPHIX! (optional)
    -b5 = configure a 5% border (optional)
    -z3 = set 1024x768 screen size (optional)
    -m2 = use the ECS keyboard as the default input (mandatory)

On starting, Chippi will check for the existence of an ECS and additional GRAM.
It will then ask for the name of an ECS tape to load.  


3. EMULATOR CONFIGURATION
--------------------------------------------------------------------------------

At the bottom of the screen 3 pieces of information are displayed.  From left
to right these are:

    * Keyboard mode (C or E), where 
        * C    = CHIP-8 layout
        * E    = ECS layout
        See Section 5 below for more details
    * Emulation speed where:
        * D    = default speed set by the game
        * 1-9  = target a specific speed. A value of 5 represents a target of
                 10 instructions per video frame or 600 instructions per second
        * F    = Full, unrestricted speed
    * Sound volume where:
        * 0    = off
        * 1    = quiet
        * 2    = medium
        * 3    = loud
    
In addition, Chippi supports 8 colour themes: Miami, Green Screen, Gas Plasma, 
BnW, Bubblegum, Terracotta, Ocean and Jungle, and eight different chords for
its beeper.  These aspects of Chippi's behaviour can be changed at any time 
using the following ECS keys:

    * SPACE     - change keyboard mode
    * < and >   - decrease or increase the emulator speed
    * DOWN      - change the sound volume
    * UP        - change the chord of the sound
    * ESC       - change the colour theme


4. LOADING TAPES
--------------------------------------------------------------------------------

Chippi loads CHIP-8 programs from tape.  Each program is given a name that
is exactly 4 upper case alphanumeric characters.  When running in JzIntv
tapes are loaded from the same directory as the Chippi ROM and have a name like
"ecs_tape_ABCD.ecs".  To load this tape, the name "ABCD" would be entered on 
the ECS keyboard when Chippi asks for the tape name.  Letters are automatically 
converted to upper case.

Chippi will then tell the user to "PRESS PLAY" on the tape.  When using a real
ECS, it will then listen for squeal of the program starting.  Once Chippi finds 
a program it will switch to "LOADING...".  If you run Chippi using JzIntv it
should find and load the program immediately.  Unfortunately, Chippi has no
way of knowing if the program was not found, and it will freeze at "PRESS PLAY"
if you type an incorrect program name.  If this occurs, just hit reset and 
enter the name again.

If you want to use a real Intellivision and ECS to play Chippi, you can 
connect a PC or phone to the ECS using a 3.5mm cable and then play a WAV file
for the program you're after into the ECS.  In this instance Chippi will load
the first program it finds regardless of the name.  WAV files for all nine
programs are also included in this archive.

Once a tape is successully loaded, the CHIP-8 program will start immediately.


5. CONTROLLING CHIP-8 PROGRAMS
--------------------------------------------------------------------------------

The CHIP-8 uses a 16-key keypad with the following layout:

    1 2 3 C
    4 5 6 D
    7 8 9 E
    A 0 B F
    
Chippi supports two different keyboard layouts to control CHIP-8 programs. The
current mode is shown on the bottom line of the screen as either (C)HIP-8 mode,
or (E)CS mode.  The ECS keyboard is laid out as follows.

CHIP-8 Mode - this is probably best for playing most games:

    1 2 3 4
    Q W E R
    A S D F
    Z X C V

ECS Mode - this is maps the ECS keys on to their CHIP-8 equivalent.  So 4 is 4,
C is C, etc.  Theoretically this should be better for typing data into Chippi
as you just hit the key you want.  However, I don't know of any programs that 
would actually benefit from this. 


6. CHIP-8 GAMES
--------------------------------------------------------------------------------

You can find a load of CHIP-8 games on the internet, but I've included eight 
common ones to get people started, I've also written an additional one myself.  
Other than PiiP-8 which I wrote, I don't claim authorship of these programs, 
they are provided simply to demonstrate the capabilities of Chippi.  I've also 
included instructions for creating tapes for other games in Section 7 below.


6.1. BLNK - Author: C. Egeberg, Size: 2.4KB
--------------------------------------------------------------------------------

Probably the best game included, BLINKY is a Pac-Man clone, complete with two 
rather dumb ghosts and power pills (no the sound is not broken).  BLINKY is 
probably best played at speed 8 or higher.

CONTROLS
3 = Up
6 = Down
7 = Left
8 = Right


6.2. BRIX - Author: unknown, Size: 0.3KB
--------------------------------------------------------------------------------

BRIX is a Breakout clone.  It's a pretty simple rendition that's best played 
at speed 6.

CONTROLS
4 = Left
6 = Right


6.3. INVD - Author: David Winter, Size: 1.3KB
--------------------------------------------------------------------------------

INVADERS is a Space Invaders clone by David Winter.  It seems to play OK at any 
speed above 7.  However, it has an annoying difficult spike at level 5 where 
all of a sudden the CHIP-8 architecture beccomes swamped with redrawing the 
invaders making the game really difficult.

CONTROLS
4 = Left
5 = Fire
6 = Right


6.4. PIIP - Author: decle, Size: 1.0KB
--------------------------------------------------------------------------------

PiiP-8 computes the digits of PI using Rabinowitz and Wagon's spigot algorithm:

https://www.cs.williams.edu/~heeringa/classes/cs135/s15/readings/spigot.pdf

You choose the number of digits of PI to compute and then they very slowly
scroll passed until it's done.  Note that the more digits you choose, the
longer it will take to compute EACH DIGIT.  It's definitely best to run this 
program at full speed.

CONTROLS
2 = Increase the number of digits to compute
5 = Decrease the number of digits to compute
F = Start computing


6.4. PONG - Author: unknown, Size: 0.3KB
--------------------------------------------------------------------------------

Two player Pong clone.  Owing to the way the CHIP-8 clips sprites, the wrap 
around of the paddles is a little weird.  But otherwise it's not bad when 
played on speed 7 or above.

CONTROLS
1 = Left Player Up
4 = Left Player Down
C = Right Player Up
D = Right Player Down


6.5. PUZZ - Author: unknown, Size: 0.2KB
--------------------------------------------------------------------------------

PUZZLE is the classic 15 piece sliding tile puzzle.  Having randomised the
pieces, slide tiles into the empty space to return the puzzle to the 0-9, A-F 
order from top left to bottom right.  It works well at speed 5 or above.  Is 
it just me, or are the horizontal and vertical controls inconsistent in this 
game?

CONTROLS
2 = Move piece above the hole down
4 = Move piece to the right of the hole left
6 = Move piece to the left of the hole right
8 = Move piece below the hole up


6.6. SYZY - Author: RTT, Size: 1.0KB
--------------------------------------------------------------------------------

SYZYGY is a snake game, and a pretty good one.  Grab the O to grow your snake, 
but try not to hit your tail.  Press E to start a game without a border, 
F for a game with a border.  Once the game is over press B to see your score 
and start a new game.  Seems to play fine on speed 5.

CONTROLS
3 = Up
6 = Down
7 = Left
8 = Right


6.7. TETR - Author: unknown, Size: 0.5KB
--------------------------------------------------------------------------------

TETRIS is your favourite tetrominoes game.  It's some way off the NES version.  
Emulation speed does not not seem to make much difference to the speed at which
pieces fall, but it's probably best to play on the fastest speed because 
checking for lines when pieces are dropped is faster.

4 = Spin piece
5 = Move piece left
6 = Move piece right
7 = Pull piece down


6.8. UFOO - Author: unknown, Size: 0.2KB
--------------------------------------------------------------------------------

UFO is similar to Carnival or Space War on the RCA Studio II.  Fire 15 missiles 
to hit as many of the moving targets as possible.  Unlike Space War you cannot 
steer your missiles once they've launched.  Just choose whether to launch left, 
right or straight up.

4 = Launch diagonally left
5 = Launch straight up
6 = Launch diagonally right


7. CREATING TAPES OF OTHER GAMES
--------------------------------------------------------------------------------

Included with this distribution is a Python program that will create an ECS 
tape for use with Chippi.  In theory the process is as easy as:

    * Grab a game ROM from the internet
    * Run the script to convert it to a tape with something like:

        python.exe chip8ToEcs.py someGame.c8 ABCD
    
This will create "ecs_tape_ABCD.ecs" ready for you to use.  However, there are 
a couple of complications.

The first is that the CHIP-8 architecture has been extended and enhanced in 
numerous ways by things like SUPER-CHIP and XO-CHIP.  Chippi only supports the 
basic, bog standard CHIP-8, not any of your shmancy pants extensions.  This 
means that some of the coolest looking games from Octojam 
(e.g. https://itch.io/jam/octojam-8) won't work.  Sorry, there is only so much 
I can do in a couple of weeks and 4K decles.

The second is that even when we talk about the basic version of CHIP-8 there 
are a number of common variations in expected behaviours (called quirks) that 
come about because the original documentation of the CHIP-8 specification was 
a bit vague.

Chippi supports three of these quirks, and whether or not they are turned on 
for a particular game is controlled by flags passed to chip8ToEcs.py.  In
addition we can set defaults for the colour scheme, sound chord and
emulation speed as follows:

    -c = sets the default colour scheme for the game.  Choose a value between
         0 and 7.  If no value is chosen, the default Miami theme will be
         selected as the default.
        
    -d = turns on the DISPLAY WAIT quirk, see:

         https://www.laurencescotford.net/2020/07/19/chip-8-on-the-cosmac-vip-drawing-sprites/
    
         The original CHIP-8 only allowed one sprite to be drawn per 60th/second
         video frame.  This can make some games feel s-l-o-w. If this is the 
         case, try setting this flag as it turns off this limitation.
    
    -m = turns on the memory or LD quirk, see:

         https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#fx55-and-fx65-store-and-load-memory

         This affects whether the load instructions change the I register. By 
         default they do, just like the original CHIP-8.  Setting the -l flag
         means they don't which can be needed by some games.
    
    -n = sets the default chord for the beeper.  Choose a value between
         0 and 7.  If no value is chosen the default A Major triad will be
         selected as the default.
        
    -s = turns on the SHIFT quirk, see:

         https://tobiasvl.github.io/blog/write-a-chip-8-emulator/#8xy6-and-8xye-shift
    
         This affects the shift operations.  It's the most common cause of 
         incompatibilities.  If your program displays a fault, try setting
         this flag first.
    
    -t = sets the default speed throttle for the emulator.  Choose a value 
         between 1 and 10.  Here each value equates to 2 instructions per video 
         frame or 120 instructions per second.  If a value of 10 is selected
         the emulator will run as quickly as possible.  If no value is 
         chosen the default value of 7 will be selected, this equals 14
         instructions per frame, or 840 instructions per second.
        
To create a game with the Green Screen colour theme and all three quirks turned 
on, you'd use the following command line:

    python.exe chip8ToEcs.py -c 1 -d -m -s someGame.c8 ABCD


7. CLOSING THOUGHTS
--------------------------------------------------------------------------------

If you made it this far, well done!  You have more fortitude than me.  As 
always, any feedback, problems, bugs, etc. are welcome.


Cheers

decle

