PyFrotz is a minimal Python wrapper around Frotz, a popular interpreter for Infocom's text adventure games. It complies with the Z-Machine Standard version 1.1, making it compatible with classic interactive fiction.

Get some classic games to try @The Obsessively Complete Infocom Catalog.

Source code for a lot of infocom games can be found @historicalsource

First, install the PyFrotz Python package via pip:

pip install pyfrotz

Additionally, ensure you have dfrotz installed on your system. It is often packaged as frotz-dumb in Linux distributions.

PyFrotz can be used programmatically or interactively in the command line interface (CLI).

from pyfrotz import Frotz

# Load your game file
data = '/path/to/your/game/data.z5'
game = Frotz(data)

# Interact with the game in your code
game_intro = game.get_intro()
room, description = game.do_command("look")
game.save()  # Optionally pass filename, default='save.qzl'
game.restore()  # Optionally pass filename, default='save.qzl'

You can also play games directly in the CLI:

from pyfrotz import Frotz

data = '/path/to/your/game/data.z5'

game = Frotz(data)
game.play_loop()

PyFrotz can be used as a voice interpreter for all Infocom and other Z-Machine games.

An OpenVoiceOS template class is provided to wrap games into a skill.

The FrotzSkill class is a template for creating conversational game skills based on PyFrotz. It simplifies the integration of Z-Machine games with OpenVoiceOS by handling game state, input/output, and optional auto-save features.

• Game Initialization: Automatically loads the game data and prepares the save file location.
• Intro Parser: Parses and announces the game's introductory text when starting a new game.
• Command Handling: Pipes user inputs to the game, processes the output, and optionally translates input/output for multilingual support.
• Save/Load Management: Handles game saving and restoring with customizable dialogs.
• GUI Integration: Updates the OVOS GUI with game-specific visuals during gameplay.
• Abandon Game Handling: Manages mid-interaction abandonment with optional auto-save.

Below is an example of how to use the FrotzSkill template to wrap a game like Zork into an OVOS skill.

from pyfrotz.ovos import FrotzSkill


class ZorkSkill(FrotzSkill):
    def __init__(self, *args, **kwargs):
        super().__init__(
            game_id="zork",
            game_data="/path/to/zork.z5",
            game_lang="en",
            skill_icon="/path/to/zork/icon.png",
            game_image="/path/to/zork/bg.png",
            *args, **kwargs
        )

To package this into an OVOS skill:

1. Set the game-specific parameters (game_id, game_data, game_lang, etc.).
2. Customize dialogs and GUI assets (e.g., images and icons) as needed.
3. Override methods like on_play_game, on_game_command, or on_abandon_game for additional functionality.
4. Include a {game_id}.voc file in the locale directory, listing various ways the game can be referred to by voice. The file name must match the game_id with a .voc suffix (e.g., zork.voc).

• on_play_game: Initializes the game and displays the introductory text.
• on_save_game: Saves the current game state to a file.
• on_load_game: Restores the game state from a save file.
• on_stop_game: Handles cleanup when the game ends.
• on_game_command(utterance, lang): Processes user commands, with optional language translation.

Several prebuilt OVOS skills based on PyFrotz are available:

• Planetfall Game
• Stationfall Game
• Starcross Game
• The Hitchhiker's Guide to the Galaxy
• White House Adventure
• Zork II
• Zork III
• Zork 0
• Colossal Cave Adventure

Enjoy bringing these timeless text-based adventures to life with PyFrotz!