A Z-code engine for playing interactive fiction games.
A particular goal of Zif is portability between different platforms and specifically portability to the third generation Kindle, aka Kindle Keyboard. The Kindle keyboard appears as an ideal platform for playing interactive fiction.
Zif includes an optional terminal emulator and a basic curses style front-end menu to select story files. So when running on a Kindle, a third-party terminal emulator and launcher is not necessary.
Excellent Z-code engines already exist and some have already been ported to the Kindle.
The application is currently beta quality. It has been built and seen to run on various platforms. Almost all Z-code files, .z# and .zblorb, downloaded from the interactive fiction archive, start to run as expected. (819/817) Although further testing is necessary, initial indications are that there is enough functionality in place to play most of the available games.
| Target | Build | Run |
|---|---|---|
| Linux | OK | OK |
| macOS | OK | OK |
| Kindle3 | OK | OK |
| Android | OK | Only using third party terminal e.g. --term |
| Emscripten | OK | Not working, only simple command line options --help etc. |
| iOS | Links (but no app yet) | - |
Zif should be run from the directory where it was installed. Starting Zif without any command line arguments will start the front-end menu using the built-in terminal emulator. The games available from the menus should be stored under the Games sub-directory and need to be listed in the file "Games/list".
The command line option --help (or -h) provides a list of the command line options. Supplying a Z-code game file as a command line argument will load and run the game file directly bypassing the front-end menus.
Graham Nelson for his "Z-Machine Standards Document" and test programs. Andrew Plotkin for his "Z-machine Exerciser". The contributers to Frotz, which has been an invaluable reference of correct Z-Machine behaviour. The Z-Code authors, and everyone else involved, for enabling their Z-code files to be freely available at the Interactive Fiction Archive (http://ifarchive.org/) and the Interactive Fiction Database (http://ifdb.tads.org/).
This repo uses git sub-modules, so checkout using --recurse to clone all the dependent source...
git clone --recurse https://github.com/AnotherJohnH/Zif.git
or
git clone --recurse ssh://[email protected]/AnotherJohnH/Zif.git
| Package | Min. Version | MacOS | Linux | Kindle3 |
|---|---|---|---|---|
| C++ compiler | c++11 | Y | Y | Y |
| GNU Make | 3.81 | Y | Y | Y |
| Python | 3 | Y | Y | Y |
| cmake | 3.10.2 | Y | Y | Y |
| SDL | 2.0.10 | Y | Y |
The build is CMake based so the usual CMake instructions apply...
mkdir build_native
cd build_native
cmake -DCMAKE_BUILD_TYPE=Release ..
make
A "helper" Makefile is provided in the main project directory so that the commands above can also be invoked just with...
make
This Makefile also provides some phony targets including "clean" and "debug"
The build files will determine whether the host system is Linux or MacOS and configure the build environment for the host system as the target. This automatic target selection can be overriden by setting the PROJ_TARGET environment variable. e.g.
PROJ_TARGET=macOS
or
PROJ_TARGET=Linux
Cross targets are also selected via the PROJ_TARGET environment variable. e.g.
PROJ_TARGET=Kindle3
The BUILD_... .sh scripts are provided to initialise PROJ_TARGET and set other environment variables required by each specific build. These scripts should be sourced and then the top level SConstruct invoked in the normal way.
Requires gcc built for arm-linux-gnueabihf and a set of headers and static runtime libraries that are compatible with the Linux installed on the Kindle3. The original ARMv6 Raspberry Pi running a Debian based Linux has been found to be suitable platform to build the Kindle3 version.
-
Install a Kindle3 Jailbreak (see https://www.mobileread.com/forums/showthread.php?t=122519)
-
Install and configure the usbnetwork package (see https://www.mobileread.com/forums/showpost.php?p=973688&postcount=1)
-
Make sure that remote ssh access is up and running and is available by default after a reboot
-
Really make sure that you completed step 3.
-
Install the Zif to the Kindle.
scp <tgz-file> root@<kindle-hostname>:/mnt/us
ssh root@<kindle-hostname>
cd /mnt/us
mkdir Zif
cd Zif
mv ../<tgz-file> .
gunzip <tgz-file>
tar xvf <tar-file>
- Kill the Amazon Kindle ebook framework. (It will restart when the Kindle next re-boots)
ssh root@<kindle-hostname> # if not already logged in
killall start.sh cvm
NOTE: If you want to restart the kindle and get the Kindle ebook framework back
shutdown -r now
- Check Zif works
cd /mnt/us/Zif
./zif --version
./zif
- An easy way to automatically start Zif on boot up is to modify the start script /opt/amazon/ebook/bin/start.sh. Find the "START OF SCRIPT LINE" which is around line 225 and then add the following lines before the while loop e.g.
cd /mnt/us/Zif
./zif
i.e.
cd /opt/amazon/ebook/bin
mntroot rw
vi start.sh
mntroot ro
shutdown -r now
This will mean that Zif will start automatically on boot and on quiting Zif the normal Amazon Kindle startup will resume.
Uses the SDL2 library supplied with Emscripten. Some re-work/conditonal compilation will be required to make it work. (TODO)
Requires access to a source installation of SDL2 which is built into a linSDL2.a as part of the application build process.
Build of an actual app has not been achieved yet, and may not be easily achievable without an Xcode project file.
Requires an NDK installation. Currently builds as a console only app as an integration with an Android build of SDL2 has not been achieved yet.
Regression testing is mostly achieved via the ZifTest project.
The source is modern-ish C++ with the following attributes...
- 3 space indent, no TABs
- vertically aligned braces
- use of C stdio API