Sema-tawy: the docs

Sema-tawy

A tomb by torchlight: a deep stack with gold, veiled, sealed and covered amulets and rubble

Sema-tawy is a mahjong journey through ancient Egypt, with the amulets of Amulets of Anubis. Its name is the sema-tawy, the union of the Two Lands: the lotus of the south and the papyrus of the north tied together, two made one, as every pair is. Take pairs of matching amulets off a stack shaped like a pyramid, a temple, a cat, the sun or Giza’s three pyramids, until the table is clear. An amulet can be taken when nothing lies on top of it and it has nothing beside it on at least one side.

Play a single stack whenever you like, try the stack of the day, or set out on a journey up the Nile through three seasons, with markets, shrines, tombs, oases and the river in between, boons to use, relics to keep and omens to brave.

The whole game is a single HTML file. There is nothing to install and no account to make. It never goes online: no ads, no tracking and no update that changes it behind your back. Open the file in a browser and it works, and it should still work in twenty years. There is an Android app too, and programs for Windows, macOS and Linux.

We also wanted it to be easy to change. The stacks, the boons and relics, the river’s stories, every word on screen, every number and every picture are small text files that explain themselves. You can make your own version without writing any code.

What’s in it

There are more pictures on the screenshots page.

Playing it

Build it once (see below), then open dist/sema-tawy.html in a browser. That one file is the entire game, so you can copy it anywhere and keep it.

Note: Your progress is saved in the browser you play in. A journey is kept when you close the page and picked up where you left it.

Building it

All you need is Python 3, and Node.js so the build can check that every stack can be cleared.

python3 build.py            # or double-click build.bat on Windows

The build checks every content file before it writes anything. If something is wrong, it tells you which file and which line in plain words and leaves your last working game alone. Otherwise it writes dist/sema-tawy.html.

A few other commands come in handy while you work:

CommandWhat it does
python3 build.py --checkchecks the content without writing anything
python3 build.py --watchbuilds again every time you save a file
python3 build.py --debugalso writes dist/sema-tawy-debug.html, which keeps a play log on the device (saved as a file from its menu, sent nowhere)
python3 engine/tools/new.pystarts a new stack, boon, relic, omen, river event or tile look from a ready-made file (tools/new.bat on Windows)
dist/sema-tawy.html?tryopens the game in try-out mode, with its own save and every stack open; ?try&layout=cat goes straight to a stack, ?try&run to a journey

python3 engine/tools/build-android.py builds the Android app and python3 engine/tools/build-desktop.py the desktop programs. The build guide says what they need.

Making it your own

Most of the game is content rather than code:

To changeEdit
the stacksone small file each in content/layouts/ (or draw them in tools/draw-layouts.py)
boons, relics, omens, places on the map, river eventsone small file each in content/
how hard it is: the levels, the map, the money, the helpcontent/settings.jsonc
tile looks, picture sets, page styles, tablesa file in content/ and a stylesheet in web/
the words on every screen, How to play, the tutorial, the sounds and effectsedition.jsonc
every picturefiles in images/ (SVG, see images/README.md)

If you have never programmed, start with the first part of the manual. It walks you through changing words, pictures and numbers and adding a new stack and a new boon.

How it is made

The game is built on Plinth, an engine for games of taking pairs off a stack that knows nothing of Egypt, with the sound and the music. Plinth has a repository of its own; the game keeps a copy in engine/. The rules run without a browser, so a bot can play them: node engine/tools/sim.js plays every stack, node engine/tools/run-sim.js whole journeys and node engine/tools/difficulty.js measures every level. The second part of the manual and the code map explain the rest.

Documentation

The manualin two parts: making things (for everyone) and the engine (for programmers)
How hard it iswhat makes a journey hard, what we measured and what moves it, on a phone and on a computer
Reading the codea gentle way into the code, for a first reader
Content referenceevery field of every kind of content file
A map of the codewhat each file of the engine is for and what’s in it
Build guidethe Android app and the desktop programs
Screenshotspictures of the game
AGENTS.mdthe rules for contributors and AI agents
PLAN.mdwhat comes next
Decisionsevery decision made along the way, newest last

Where things are

FolderWhat is in it
content/everything a player sees or reads that isn’t a rule, one small file each, and the settings
images/the pictures (amulets, cards, covers, tables, scenery) and where they came from
web/the game’s stylesheets: its skin, tile looks, page styles, tables, scenery, cards
engine/Plinth: the rules, the page, the build and the tools that test them
platforms/the Android app and the desktop programs
tools/helpers: the drawing scripts, update-plinth.py, the docs’ pictures, the website
docs/the manual, the build guide, the screenshots and the history of every decision
dist/what the build makes (not kept in git)

Private. Its one remote is on the owner’s own server.