Zaytun Project

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.

Why the name Zaytun?

For most of its life it was called Loom. The compiler was loomc, the player was loomplay, games were written in .loom files, and the four bytes at the front of every compiled game said LOOM. It carried that name for a long time before anybody else saw it.

Loom was a good name for what the project looked like from the inside: a game here is warp and weft, rooms crossing with the things that happen in them, and a language for weaving one out of the other. The trouble is that it described the making and said nothing about the thing made — and there are a great many looms in software already.

So it became Zaytun. An olive tree is slow, it is not much to look at, it is famously hard to kill, and it outlives the person who planted it by centuries — you plant one for somebody you will not meet. That is a fair description of what this project is trying to be: plain text and plain C, no dependencies to rot, a game file you can hand to somebody in ten years and expect to open. It is also a tree that grows where this was written, which the loom was not.

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 nine 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. The Crooked Measure is the shortest by a long way, and the least like the others: a shop to keep solvent for twelve days, with nothing to fight and nothing to unlock. Ravenscar is the hardest, and says so: finite ammunition, creatures that hunt you across the map, and five endings you can reach badly. All nine 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:

A complete two-room game.
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.

Compiling a game and playing 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.

Is there editor support?

Yes, for three editors. All three give you syntax highlighting that knows where a word is rather than only what it is, and — the part that saves the most time — the compiler's own errors reported in the editor rather than read off a terminal. What each adds beyond that differs, and the editor support page compares them properly.

None of them is required. Zaytun is plain text and the compiler reports errors as file:line: message, which any editor can already jump to.

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 Web 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.

Can I add a game I wrote to the games list on this site?

Yes — ask, and it will be read. The games page is not an upload form: every game on it has its own repository under codeberg.org/zaytun-project, and this site serves a compiled copy that is rebuilt from that source and compared byte for byte before it goes up. So adding one is a short conversation rather than a button, and the contact page is where it starts. Send a link to your source, or the game itself.

Three things make that conversation short, and none of them is a judgement about how good the game is:

You do not need this list in order to publish. A .zaytunb is just a file: put it on your own site, send it to people, sell it. Anyone can open it in the Zaytun Web Player without an account and without uploading anything. The list here is a shelf, not a gate.

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 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:

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 eight 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 and 64-bit ARM. 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.

Why is there no macOS download?

Not because it cannot be built. It can, and it has been: an arm64 macOS build of both programs cross-compiles cleanly from Linux, using a toolchain that supplies the two things the job needs — a linker that emits Mach-O, and a stub of macOS's own libSystem to link against. The results are well-formed Apple Silicon executables, correctly ad-hoc signed, which matters because an Apple Silicon machine refuses to run an unsigned one at all.

The reason there is no download is simpler and harder to fix: nobody has run it.

Every binary on the downloads page was executed before it was published. The x86 Linux and FreeBSD builds ran on real machines, and the ARM builds — the two for Linux and the one for FreeBSD — were tested on a Raspberry Pi; only the two Windows builds ran under emulation, in their case Wine. There is no Mac here, and a Mach-O binary will not run under emulation on Linux, so a macOS download would be the only one on that page that had never once been started. That is a worse thing to offer than nothing — a binary that has never run is a guess with a checksum.

There is a second obstacle even once it works. A downloaded binary that is only ad-hoc signed is quarantined by Gatekeeper and refused on first launch; getting past that properly means notarising it, which needs a paid Apple developer account and a Mac to do it from.

In the meantime, build it. The toolchain is standard C11 with no dependencies, and macOS ships everything it needs already — clang and make are in the Command Line Tools. It is the same two commands as everywhere else, and there is nothing to configure. If you do that and it works, or if it does not, say so: a single report from somebody with a Mac is the whole of what stands between this and an eighth download.

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.

Running the browser player from your own machine.
git clone https://codeberg.org/zaytun-project/zaytun-web-player
xdg-open zaytun-web-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.

How does the compiler work?

In five passes. Each one hands its work to the next, and none of them reaches back:

What happens between your source and the game file.
lex        one file's text   ->  its words and symbols
parse      those             ->  that file's own tree
module     the trees         ->  one program
validate                         names, types, meaning
bytecode                         the .zaytunb

The part worth knowing is the third line. A game split across several files is not stitched into one long text before being read. Every file is read on its own, into its own tree, and include survives that as a declaration like any other; a later pass replaces each one with the contents of the file it names. That is how Java, Go, Rust and Python handle their imports, and it is the opposite of what C does with #include, which pastes the named file in where it stands.

Zaytun sits with the imports rather than with the pasting because its include always behaved like one: a file is included at most once however many times it is named, a cycle between two files is an error rather than an infinite loop, and a path is read relative to the file that names it. Those are the rules C spent thirty years arriving at from the other direction.

What you get from it is better errors. Because a file is parsed by itself, a mistake in one file cannot derail the reading of another, so the compiler reports everything wrong with your game in one go — several bad names and several unparsable files together, each with its own file and line, in the order you wrote them — rather than stopping at the first and making you compile again to find the second. It is also what makes local possible, which keeps a name inside one file so two areas of a large game can both have a gate; there is only one moment in the whole compiler at which this file's declarations is a thing that can be pointed at, and it is between parsing a file and merging it.

None of this changes what a game that compiles turns into. It is the same .zaytunb, byte for byte.

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 seventeen 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:

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.