CliFrotz
--------

CliFrotz is a port of the Frotz v2.43 interpreter for the PalmOS devices.
Frotz is an Interactive Fiction interpreter that plays ZMachine (Infocom,
Inform) games such as Zork and HitchHiker's Guide.  

It requires a Hires screen, OS4 or later, an expansion card and the large
dynamic memory area available from OS4 onwards. If your handheld does not meet
these requirements then try FrobNitz or PilotFrotz.

CliFrotz supports V1-V8 games and V6 MG1 graphics.


Installing
----------

Hotsync the CliFrotz-Installer.prc file on your PalmOS handheld. This will 
install and configure CliFrotz on your Palm, make sure the expansion card
is inserted before you install. 

Copy your Story files into the \Frotz\ directory on the expansion card using 
a flash card reader or the Clie "MS Import" utility.  Your save files will go 
into \Frotz\Save.  These are Quetzal saves so that they can be exchanged with 
games played on your PC. Story files should _not_ be converted PDB files, 
such as those used in Frobnitz. 

If you want V6 graphics files for the games Arthur, Shogun, Journey, ZorkZero
and Beyond Zork, then you need to copy the MG1 files into the \Frotz\
directory. The file names should match the equivalent story files, i.e.  the
graphics file for Shogun.z6 should be Shogun.mg1 These files are available
from: http://ifarchive.org/if-archive/infocom/media/mcga/

**NOTE for Tungsten T3 users only** Install the AppSlipRotate.prc and
StatusBarLib.prc files (they MUST be installed together) from the PalmOne web
site if they haven't already been installed.  This will enable widescreen
support.  


Landscape Support
-----------------

At the present time the Tungsten T3, T5, UX50/40 and Tapwave Zodiac support
full landscape mode. 

You will not be able to change the orientation when the game is playing. This
is because the Frotz engine does not like the screen size to be changed during
a game.  There is an option in the preferences to allow portrait mode. When
using this option, change it and restart CliFrotz for it to take effect. On
the Tungsten T3 and T5 the screen is forced to landscape widemode even when
the slider is shut,


Using
-----

Infocom games are still copyrighted so you'll need to buy them from somewhere.
There are still Infocom collections available but I don't know where. The Zork
games are now freely available but they aren't particularly good IF games.
There are lots of great free Inform/Infocom games available from:
http://ifarchive.org/if-archive/games/zcode/

When first starting CliFrotz it is best to set the "Num cols:" value to match
the "Act cols:" so that games will look best on your screen. If you do not
have a landscape mode Palm or Clie then you may need to set the "Num cols:" to
a value of 63 or more for some games to play. When changing font sizes you will 
need to exit and restart CliFrotz for the changes to take affect.

When running CliFrotz for the first time on a PDA, check the "Free Heap RAM" menu
to see if you have enough RAM available. If you have less than 800KBytes free
then you will most likely have problems running many larger IF games. This free
RAM is not the same as shown in the Application launcher. Pictures may not be
drawn if the RAM is low. 

If you have lots of free heap RAM available then the picture file will automatically
be cached in memory resulting in a speedup, on OS5 ARM devices this speedup is 
substantial.

When playing a game, tapping on a word will bring up a menu allowing quick word
entry. Tapping anywhere there isn't a word brings up the command list menu.
You can scroll backwards by dragging the screen. Some games support a "Mouse"
such as Journey and Zork Zero. CliFrotz emulates mouse "clicks" by tapping on
the screen, e.g. you can tap on a word in Journey.

The 'Hotkey' menu enables access to the Frotz Hotkey functions such as undo, record,
playback and debugging. When using record and playback the file is put into
the \Frotz\Misc directory, the name is automatically generated from the Story
filename. For example to use a playback file for story Zork1.z3, name the playback
file Zork1.rec

Transcriptions, i.e. the "script/unscript" command also go into the
\Frotz\Misc directory. They will have the extension .scr, the files generated
are text files.

If you have problems running CliFrotz with it crashing before a game starts, try
freeing up some internal memory. If it keeps crashing and you can't get the game
to start then try deleting the CliFrotzAS and CliFrotzDB files using a File
Manager utility.

When quitting a game, CliFrotz always exits to the app launcher not the story
selection screen. This is done to improve the stability of the program.


Some technical notes
--------------------

CliFrotz makes use of the larger dynamic memory available on OS4 and later
devices, so the program could make use of an unmodified Frotz core.  The
original Tungsten T & T2 may not have enough dynamic memory to use this
program.  Virtually all OS5 devices have large dynamic memory, most OS4
devices don't with the exception of a number of Clies. Hires support was a
fundamental design goal of this project, so it includes support for Clie & OS5
HiRes and landscape screens such as the UX50 and Tungsten T3.


Change History
--------------

v1.6 24/03/05
* Added support for the TH55 landscape utility
* Speedup for Zodiac screen display
* Fixes to word popup on command line
* Fixes to more prompt

v1.5 25/01/05
* Fixed Tungsten T5 and W recognition
* Zodiac joystick support and grafitti window event fix
* Zodiac disable landscape option added
* Clie double event on jog dial fixed
* Reinstated Function Key menus
* Popup Words menu is now free floating instead of using the button bar.
* Added Carriage Return button to button bar
* Saved games list now displays dates instead of sizes
* Removed Hotsync registrations due to instability issues - PalmOS bug?
* Fixes to popup word tapping

v1.4 14/03/04
* Added "mouse" support for Journey, ZorkZero etc, to use tap the screen
* Added ARMlet for pictures, gives faster picture drawing on OS5 and later
* Picture file now cached in memory if lots of free heap RAM for speedup.
* Fixed crashes and improved expansion card support
* Added Hotsync registrations for story and graphics files
* Fixed TH55 screen size
* T3 screen slide redraw fix

v1.3 04/03/04
* Fixed menu problems with OS4 devices
* Fixed ROM version checking for devices such as 610C
* Added memory card selection to preferences
* Some screen drawing speed ups

v1.2 25/02/04
* Added V6 Graphics (MG1) support!!!
* Added option for UX50 to disable wide landscape support
* Fixed messy screen clearing on some games
* Fixed line input erasing and cursor positioning
* Fixed Shogun ZC_GAP displaying, gets rid of square character
* Save files automatically have ".sav" appended

v1.1 09/02/04
* Change to line input event processing to fix issues with menu shortcuts, etc.
* Added transcription support, i.e. "script/unscript" command.
* Added Frotz Hotkey support with Debugging, Recording and Playback.
* Fixed colour issues with popupforms, DIA and terpetude.
* Fixes to Clie NX display and DIA.
* Fixes to Insertion Point, and changed its colour to stop it disappearing.
* Added "Free Heap RAM" menu option.

v1.0 24/01/04
* First release


Building the code 
----------------- 

CliFrotz is built using Codewarrior. There is no Makefile for GCC but it should
be possible to build it in that environment.
Libraries required are:
ClieSDK 5.0, PalmSG SDK, PalmOSGlue, PalmOS SDK5r3
IMPORTANT - Do not switch on the compiler optimiser, causes strange problems with 
various games (i.e. Shogun)


Issues
------
* Word popup doesn't work correctly with V6 games, i.e. Shogun, Arthur. This
is due to the window management in these games being different.
* Rogue locks up, no solution found yet.
* KeyQuick can cause the Return key to generate double events, causing page
scrolling to skip a page. Solution is to delete the Return key entry from
KeyQuick.
* Transcription isn't automatically switched off/on on autosave. Workaround 
is to "unscript" before switching applications.
* Shogun saves get corrupted if you save at the "Save this game position",
instead do a "Save" command during the game. This is a Frotz issue not a CliFrotz
issue.
* No flashing input cursor appears on the CobaltOS (OS6) devices (are there any?)
as OS support was removed(!) for the function calls CliFrotz uses.


Thanks
------

Thanks to everyone who posted bugs on Sourceforge. Thanks also to Rick
Reynolds, Paul Margrave, Jeff Mitchell and Stefan Jokisch (for the Frotz
engine).

CliFrotz uses code from PalmFrotz, by Rick Reynolds, and PilotFrotz, by Paul
Margrave.


Support
-------

Go to the CliFrotz Sourceforge homepage at http://clifrotz.sourceforge.net.
Remember a project I do in my free time (which is pretty limited). Any help is
appreciated. The source code is available on this site in the CVS.  Please
don't email me directly (they'll more than likely be deleted) with bugs etc,
please post to the Sourceforge web site instead.


Enjoy
Fangorn
Great Britain
