SHTAP

Welcome to the SHTAP game engine, a.k.a. the SHell Text Adventure Player. You can use it to make (and play) interactive fiction on Linux and BSD, using only a text editor and a terminal. SHTAP is written in Bash (version 4 and newer), and self-contained in a single file, along with the data.

Download

Any adventure you make with SHTAP belongs to you. The only requirement is to preserve this three-line comment near the top:

# Made with the SHTAP game engine, a.k.a. the SHell Text Adventure Player.
# You can use SHTAP to make your own games; just replace the game data.
# If you do, please keep this notice so that other authors may benefit too.

See the included read-me file for contact information, and on the wiki for how to support this project.

How to use

Look through the included cloak.sh, a Cloak of Darkness port. You can play it first, to see what it's like. There's a two-word parser, but it's easy to add synonyms, and the usual shortcuts work. To actually write your own adventure, it may be easier to start from the minimal template in shtap.sh.

A manual is yet to be written, but as of 11 June 2020 there's a long-form article explaining how this type of engine works.

Frequently Asked Questions

Goals and motivations

What is this exactly?

This is the SHTAP game engine, a.k.a. the SHell Text Adventure Player: an interactive fiction authoring system self-contained in a single shell script. Or rather, a template: you create your own by replacing the content of an existing adventure. There's no need to touch the engine itself, though you can do that too if you know how.

Is this a joke?

No, it's an honest attempt to create a reusable text adventure engine in Bash 4. Esoteric, but real.

Why Bash 4?

Because I had to pick one. The advanced features needed for this engine don't work the same across shells. And Bash 4 is the one I'm most familiar with, as a long-time Linux user.

That said, easy portability is a primary goal: things should be done in a portable way whenever possible. Zsh and ksh93, at the very least, are obvious targets to keep in mind.

But why shell script and not some other language?

Because a shell is always there by definition. Other languages may not be. Besides, Bash is smaller than other scripting languages. Yes, Awk is even smaller, and also always there, but it has the wrong texture for this kind of game. Bash simply fits.

That said, Tcl would also be a good fit. A port isn't out of the question.

Is there even a point to it?

Well, it was a fun thing to try. And hey, imagine being able to make your own interactive fiction on a default Termux install, without having to first build Inform 6 or the like. There aren't many solutions like that for Linux and BSD, while Windows enjoys a good selection of easy-to-use retro authoring systems.

Usage

Where's the SCRIPT ON command?

There isn't one built in (yet). At a Linux command prompt, you can make your own:

./shtap.sh | tee transcript.txt

Built-in support may be added later if it doesn't complicate things too much and a good case can be made.

How to define a new verb?

There are two ways. If you just want to add another phrasing to an existing verb, just do:

verb[read]=examine

You can also use synonym instead of verb, but that applies to nouns as well.

Now, if you want to make a whole new verb from scratch, it's a bit more involved:

typeset -A text

function do_read {
    if [ -n "${text[$1]}" ]; then
        echo "${text[$1]}"
    else
        echo "There's nothing written on the ${name[$1]}."
    fi
    moves+=1
}

verb[read]=do_read

(Careful about naming the function, read is a shell builtin. And yes, I just cloned examine with a few changes. That's one of the most common kinds.)