Frequently Asked Questions

Questions that come up often, with straight answers. Every question is its own heading, so you can move through them by heading rather than reading the whole page.

Getting started

What is Zaytun?

Two things that fit together. Zaytun is a small programming language for writing text-adventure games — you describe rooms, objects and characters, and the compiler turns that description into a playable game. Zaytun Project is the language, the tools around it, and the games written in it, all free software.

A text adventure has no graphics. The game describes where you are, you type what you want to do, and it tells you what happened. That is the whole interface, and it is the reason this project exists: a game made entirely of words is playable by anybody who can read words, however they read them.

What does “Zaytun” mean?

زيتون — zaytūn — is the Arabic word for the olive: both the fruit and the tree it grows on.

Do I need to install anything to play?

No. Every game on the games page has a link that opens it in your browser and starts it. There is no download, no account, and nothing is sent anywhere — the page fetches the game file and runs it on your own machine.

You need to install something only if you want to play in a terminal instead, or write a game of your own.

Which game should I start with?

The Sundered Dawnstone is the most conventional adventure of the five and assumes the least. The Last Witness is the longest and most demanding: a murder mystery that expects you to take notes and reach a conclusion, and will let you reach the wrong one. All five are described on the games page, with what each one is like before you commit to it.

Playing the games

What can I type?

Type help and the game will tell you. The usual commands work — look, go north (or just north, or n), take, drop, examine, inventory, talk to — and individual games add their own.

help lists only the commands the game you are playing actually uses. A game with nothing to fight will not offer you attack, and a game with nothing to unlock will not offer you open. This is not a menu of everything the language can do; it is a menu of what is worth trying here.

How do I save, and can I come back later?

In a terminal, save mygame.save writes a file and restore mygame.save reads it back. In a browser, the save button produces a block of text — copy it and keep it somewhere, and paste it back in later to carry on. The browser version works this way deliberately: your save belongs to you, in a form you can read, back up and email to yourself, rather than living in browser storage that a cleared cache will take with it.

Can I move a save between the browser and the terminal?

Yes, in both directions. A save is plain JSON describing the state of your game, and the two players write the same thing, so a save file written by the terminal player can be pasted into the browser player and a save string from the browser can be written to a file and restored in a terminal. Start a game on a train and finish it at a desk.

A save also names the game it came from, and either player will refuse one belonging to a different game and tell you which game that is. It is not being fussy: a save is full of names of rooms and objects, those names mean different things in different games, and loading the wrong one would put you somewhere that does not exist.

The game did not understand what I typed. Is it broken?

Usually not — most often the game does understand the idea and wants different words for it, or the thing you are naming is not in the room with you. Try look to see what is actually there, and the exact words the game used to name it, since those words always work.

But a command that clearly ought to work and does not is a bug worth telling us about, and so is a description that reads as though something should be there when it is not. See where to report a bug below.

Accessibility

Does Zaytun work with a screen reader?

Yes, and that is the point of it rather than a feature added afterwards. In a terminal a game is an ordinary stream of text and a prompt, which is the easiest thing there is to read with a screen reader. In a browser the game is a text field and a transcript in a live region, so new text is announced as it arrives without you having to go looking for it.

Is there anything I need to be able to see?

No. There are no images, no maps to read, no colour-coded status, no timed sequences, and nothing that depends on reflexes or on recognising a shape. Nothing is signalled by colour alone, or by layout, or by anything other than words. Where you are, what you are carrying and what you have learned are all sentences you can ask for at any time.

Is this website accessible too?

It would be a poor argument for accessible games if it were not. The site is built to the standard it describes: proper landmarks, a skip link first in the tab order, one heading per page with no skipped levels, link text that means something read out of context, colour contrast at or above WCAG AA in both light and dark, and reflow without horizontal scrolling at 320 pixels and at 200% zoom.

All of that is checked automatically before anything is published, and the checker fails the build rather than warning. If something here is nonetheless awkward to use, that is a bug in the site and worth reporting — the reasoning behind all this is on the page about why the project exists.

Writing your own game

Do I need to know how to program?

Not really. Zaytun was designed so that describing a game reads much like describing it in English, and most of a game is descriptions and conditions rather than logic. If you can write clearly and think carefully about what happens when, you can write a Zaytun game.

What does a game look like?

Like this. That is a complete, working game — two rooms, one object you can pick up:

title: "The Lantern"
start: cellar

room cellar "The Cellar" {
  description: "Stone steps go up into the dark. Something drips."
  exit up -> kitchen
  item lantern
}

room kitchen "The Kitchen" {
  description: "A cold hearth, an empty table, and a door you cannot open."
  exit down -> cellar
}

item lantern "a brass lantern" {
  aliases: "lantern", "lamp"
  examine: "Heavy, and still full of oil."
}

From there the language adds characters who answer questions, flags that remember what you have done, conditions that change a description once you know more, and endings. The Zaytun language page covers what the language can do, and the language guide teaches it from an empty file upward. Every example in the guide compiles.

How do I turn that into something playable?

Two commands. The compiler reads your source and writes a game file; the player plays it.

zaytunc mygame.zaytun        # writes mygame.zaytunb
zaytunplay mygame.zaytunb    # plays it

Both programs are on the downloads page, ready built. That same .zaytunb file is what the browser player loads, so a game you compile at home is a game you can put on the web.

Can I play a game I wrote in the browser?

Yes, and you do not have to publish it anywhere first. There is a link on the home page that opens the Zaytun Player, and the player has a file picker: choose the .zaytunb file you compiled and it starts. This is the same player the games on this site run in, so what you see is what anybody else would see.

Your game is not uploaded. The picker hands the file to the page, the page reads it in your browser, and nothing is sent anywhere — once the player has loaded you can turn the network off and keep playing. There is no account, and nothing is stored on any server.

Who owns a game I write?

You do. The tools are free software, and using a compiler does not give anybody a claim on what you compile with it — the five games here are freely licensed because that was their author's choice, not because the compiler required it. You choose your own licence, and you are not obliged to choose this one.

Can I sell a game I created with Zaytun?

Yes. Nothing here takes a cut, asks permission, or has to be told about it. Free software means free as in freedom rather than free of charge, and that applies to what you build with these tools as much as to the tools themselves.

Your .zaytun source and the .zaytunb the compiler produces from it are your work. The compiler puts none of its own code into what it writes — a .zaytunb is a description of your game and nothing else — in the same way that a C compiler has no claim on the programs it builds.

Two situations do involve somebody else's licence, and it is worth knowing which is which before you decide how to sell it:

• Shipping a player alongside your game, so buyers do not have to install anything, means you are passing on the compiler or a player as well. Those are under the GPL. You may sell them, and charge whatever you like, but you have to pass the same freedoms on for those programs: keep their licence and notices, and make their source available to whoever you gave them to. None of that reaches your game, which is still yours on your own terms.
• Building the engine into your own program — linking libzaytun.so into an app, for instance — is a different matter. The result counts as one combined program under the GPL, so the whole of it would have to be released under the GPL too. There is no linking exception. If you want a closed-source app with a Zaytun engine inside it, that is worth asking about first rather than discovering afterwards.

The simplest route avoids both: sell the game file itself, and let people play it with a player they downloaded here. Then the only licence involved is the one you choose.

This is a description of how the licence works and not legal advice. If real money is involved and you are unsure where you stand, ask before you publish — it is a short conversation beforehand and an awkward one afterwards.

Installing and platforms

Which systems are supported?

Ready-built programs are published for seven platforms: Linux on 64-bit and 32-bit x86, Linux on 64-bit and 32-bit ARM, Windows 64-bit and 32-bit, and FreeBSD on 64-bit x86. Every one of them is listed on the downloads page with its size and checksum.

If your system is not on that list, you can almost certainly still build it: the whole toolchain is standard C and needs a C compiler and nothing else — no libraries, no build system to install, no configure step.

Do I need to be online?

Only to fetch the game in the first place. Once a page or a game file has loaded, nothing else is requested and nothing is sent back: no accounts, no telemetry, no analytics, no tracking of what you play or how far you get. A game running in your browser is running on your machine, and a game running in your terminal never touches the network at all.

Can I run the browser version locally?

Yes. The browser player is a handful of ordinary files with no build step, no bundler and no server: clone it and open index.html by double-clicking it, or with the command below, and it runs straight off your disk.

git clone https://codeberg.org/zaytun-project/zaytun-player
xdg-open zaytun-player/index.html

Then load a game with the file picker, exactly as on the hosted copy. Note that naming a game in the URL does not work from a local copy — browsers refuse to let a page opened from disk fetch other files off the disk, so the player says so instead of showing an error. The file picker is the way in, and it always works.

This is deliberate rather than a happy accident: the player is written as plain scripts specifically so that opening the file works without a web server. The full details are in the browser player's repository.

Why is there no installer?

Because there is nothing to install. Each archive holds two programs, the language guide and the licence. Unpack it anywhere, and either put the two programs somewhere on your PATH or run them from where they are. Deleting the folder uninstalls it completely.

How it is built

Why are there two players?

Because the two do genuinely different jobs: one plays a game in a terminal, the other in a browser with nothing installed. Neither can do the other's job well.

Two independent implementations of one language are only safe if they agree exactly, so they are tested against each other: the same game is played through both and the transcripts are compared. They currently match line for line across every scripted playthrough of the longest game, on Linux and on FreeBSD alike. That check has already caught a real bug that only one of the two had.

What is a .zaytunb file?

The compiled game. Your .zaytun source is the text you write; the .zaytunb file is what the compiler produces and what either player loads. It is compact, it is checked for consistency before it is written, and it is identical whichever platform compiled it — a game built on a Raspberry Pi is byte for byte the game built on a server.

Why is the toolchain written in C?

Because it runs almost everywhere and stays useful for decades. A toolchain built today should still work ten years from now, on hardware that does not exist yet, without requiring extra runtimes, package managers, or large dependencies. C with minimal dependencies is one of the simplest things to ask of a future machine, which is why the toolchain builds unchanged on 32-bit ARM devices, Windows systems, FreeBSD machines, and many other platforms.

The project itself

Who makes Zaytun?

One person: Ali Miracle, who is blind, and who built it because the games he wanted to play should not have required sight in the first place. The longer version of that answer is on the page about why the project exists.

Is it finished? Is it maintained?

The language, both players and all five complete games are finished in the sense that matters — complete, working, and released. It is also still being worked on: the most recent additions to the language exist because a game being written needed them and not because they sounded useful in the abstract.

Where do I report a bug?

On the issue tracker for the part that is misbehaving, which is where the person who can fix it will look:

• A game that will not compile, or a confusing error message, or anything about the language — the compiler's issue tracker.
• A game that compiles but misbehaves when you play it in a terminal, or anything about saving and restoring — the terminal player's issue tracker.
• Anything that goes wrong playing in a browser, including with a screen reader or the keyboard — the browser player's issue tracker.

If a game itself is at fault — a room you cannot leave, a clue that never appears — each game has its own repository, linked from the games page. If you are not sure which is right, pick the closest and say so; being in the wrong place is easy to fix and is nobody's fault. For anything that is not a bug, the contact page has an email address that reaches a person.

Can I contribute?

Yes. Bug reports are worth as much as patches, and accessibility reports are worth more than either, because they are the ones hardest to find without you. Everything lives at codeberg.org/zaytun-project, each component in its own repository, and all of it — the tools, the games and this website — is free software under version 3 of the GNU General Public License.