Getting started

Nothing at all is needed to play a game: the browser player is a web page, and a .zaytunb opened in it never leaves your machine — see In a browser.

To write one you need two programs, zaytunc to compile and one of the players to play what it wrote. Either take them ready-built, or build them from source; both routes end at the same two files and neither needs administrator rights.

Ready-built

The compiler and the terminal player are published together as one archive per platform — Linux, Windows and FreeBSD, on x86 and on ARM — at

https://zaytun-project.codeberg.page/downloads.html

Every archive holds the same four things and nothing else: zaytunc, zaytunplay, this handbook and the licence. There is no installer and nothing to configure. Both programs are single files that need nothing beyond the system C library, so unpack the archive anywhere and either put them on your PATH or run them where they are:

tar xzf zaytun-1.1.0-linux64.tar.gz
cd zaytun-linux64
./zaytunc mygame.zaytun
./zaytunplay mygame.zaytunb

A SHA256SUMS file is published beside the archives, so a download can be checked before it is run:

sha256sum -c SHA256SUMS 2>/dev/null | grep zaytun-1.1.0-linux64

From source

Every part of the project is on Codeberg under https://codeberg.org/zaytun-project, and each part is a repository of its own:

The first two are enough to write and play a game. Clone them side by side into one directory even so: nothing has to be installed for the parts to find each other, and several of them expect to be neighbours. The players' cross-runtime test looks for zaytun-web-player beside zaytunplay, this handbook's own suite looks for a built zaytunc beside it, and each published game's makefile looks for ../zaytunc/zaytunc.

mkdir zaytun && cd zaytun
git clone https://codeberg.org/zaytun-project/zaytunc.git
git clone https://codeberg.org/zaytun-project/zaytunplay.git
git clone https://codeberg.org/zaytun-project/zaytun-web-player.git

Then build the two C programs. Both are C11 with no dependency beyond a libc, and there is no configure step and nothing to fetch:

make -C zaytunc
make -C zaytunplay

That produces zaytunc/zaytunc and zaytunplay/zaytunplay, which run perfectly well where they are. GNU make and BSD make both understand these Makefiles, so on FreeBSD, NetBSD and OpenBSD the system make is enough and gmake is not wanted. To put them on the system instead, each has an install target that installs the binary and its manual page under PREFIX, which defaults to /usr/local; DESTDIR is honoured, for packagers:

sudo make -C zaytunc install
sudo make -C zaytunplay install
make -C zaytunc install PREFIX=~/.local        # ...or somewhere that needs no sudo

Each repository carries its own tests, and they are worth running once after a build. The compiler's — make -C zaytunc check — needs nothing but the compiler it just built. The players' — make -C zaytunplay check — plays a seeded game through both runtimes and diffs the transcripts, which is what keeps the two implementations one runtime; that half needs node and a zaytun-web-player checkout beside it, and says so and skips rather than failing when there is neither.

Compiling and playing

The two programs are written plainly here — zaytunc and zaytunplay — which is how they are spelled once they are on your PATH. If they are not, spell the path to them instead: ./zaytunc in an unpacked archive, zaytunc/zaytunc and zaytunplay/zaytunplay from a source tree. It is the same program either way, and the rest of this handbook uses whichever spelling is clearer where it stands.

Compiling a game is one command, and it behaves like any other compiler — errors on stderr, nonzero exit code:

zaytunc mygame.zaytun                    # writes mygame.zaytunb

It takes three options and no more, each with a short spelling and a long one: -o, --output <file> to write the bytecode somewhere else, -v, --version for its version and the bytecode format it writes — see Versions and compatibility — and -h, --help. zaytunplay spells --version the same way.

The short spelling was -V in 1.0.0 and is -v from 1.1.0. -V is not an option any more and is refused the way any unrecognised one is, so a script carrying the old spelling stops working and has to be changed to -v.

To play what it wrote, either load the .zaytunb into the browser player at https://zaytun-project.codeberg.page/zaytun-web-player/ — nothing to install, and the file never leaves your machine — or play it in the terminal:

zaytunplay mygame.zaytunb

The terminal player also takes commands non-interactively, which is handy while writing:

zaytunplay mygame.zaytunb -c "use stone" -c "north" -c "east"

The loop while you are writing is: edit, recompile, reload the page. The player has no compiler in it, so a .zaytunb is the only thing it ever sees.