How to Create a Walkthrough with VICE's Event History
=====================================================

1. Basics:
----------
VICE supports recording an arbitrary session on the emulated machine and
playing back this session later. This is done by saving a snapshot at the beginning
of the recording session and then remembering all the user interaction such as
keyboard and joystick input. We call this an 'event history'.
The main purpose for having an event history is to create game sessions, e.g. recording 
how to solve a game. An example walkthrough for the well known game "Fort Apocalypse" is
available.
This brief document will advise you how to record and playback such a session.
Although it is based on the WinVICE x64 release and its user interface, histories may be
transferred to other machines and other ports that support event history, e.g. the
Unix port.

2. Recommended Settings
-----------------------
When using the event history feature it is possible that the playback session
differs from what was done at recording time. This might arise due to a problem 
in the initial snapshot or settings.
Here are some suggestions to minimize the chance of failures in the session:
a. Reset to default settings.
b. Choose refresh rate 1/1.
c. Choose joystick and Video/Doublesize settings as desired or needed.
d. SID engine must be reSID (which is the default).
Do not change any settings during recording or playback!

3. Recorded Events
------------------
The following is a list of the user interaction that will be recorded:
- Joystick movement and button
- Keyboard
- Resetting the machine (hard and soft)
- Attaching or detaching disk/tape images (see 8. Limitations)
- Datasette controls

4. Recording an Event History
-----------------------------
Recording an event history will create one or two files for a snapshot and
the list of the user events. First, create an empty directory in which these
files are to be saved and then select this directory via 'Snapshot//Select 
History directory'. Next, attach the disk or tape image with the game you 
want to record and load and run the game.
Start recording via 'Snapshot//Start/Stop Recording History'.
Play the game. All actions will be recorded.
After the game is finished, stop recording via 'Snapshot//Start/Stop
Recording History'. The selected directory should now contain the two
files start.vsf and end.vsf

5. Setting and Returning to Milestones
--------------------------------------
It is difficult to finish a game in one sitting and noone wants to
record all their mistakes and lost lives. Use the milestone feature in a
recording session in the following way:
Set a milestone when you have finished a level or completed a task
('Snapshot//Set recording milestone' or ALT-E). This will save the event
history and a snapshot of the machine to the file end.vsf but recording will
continue.
Return to the last milestone when you have made a mistake or lost a life
('Snapshot//Return to milestone' or ALT-U). This will reset the game and the
event history to the last milestone snapshot so that you can try again.

6. Continuing an Event History
------------------------------
If you have stopped a recording session and want to continue it later, you
should create a backup of your start.vsf and end.vsf files first to avoid
overwriting them by accident.
Then change the event history start mode: 'Snapshot//Recording start mode//Load
existing snapshot'. When you start recording now, you will continue where the
session was stopped last time.

7. Playing Back an Event History
--------------------------------
To play back an event history, select the directory with the history files
start.vsf and end.vsf via 'Snapshot//Select History directory' and start the
playback with 'Snapshot//Start/Stop Playback History'. Enjoy!
During playback any user interaction is disabled.
The playback stops when the end of the session is reached or if 
'Snapshot//Select History directory' is selected again.

8. Limitations and Suggestions
------------------------------
a. When playing back a session in which images were attached, those images
need to be in the same directory that they were located during recording.
This makes it difficult to distribute a walkthrough for games that need 
disk or tape changes. We will fix this later.
b. The names of the snapshot files start.vsf and end.vsf can be changed with
the resources EventStartSnapshot and EventEndSnapshot. However, we suggest 
keeping the defaults as there is no GUI support for changing them.
c. Snapshot files will be quite big (>1MB) if a disk image has been attached. 
If possible, use PRG or T64 images to reduce the size of snapshot files.
d. Snapshots may not be 100% accurate even with all the recommended settings.
