textovka (Czech deminutivum for text-base game) is a side project I tried to develop when also trying to finish my Bachelor thesis. It is designed as singleplayer adventure game.

The project is divided into three isolated subprojects:

api (application programming interface)

Testing instance runs at text.n0p.cz (may not be available 24/7).

Server-side subproject is the game engine itself acting also as simple REST JSON API. At the moment, it uses only query strings and therefore accepts HTTP GET requests only.

It is written in pure PHP8 as a simple game engine. The engine itself acts like a JSON parser (maps and players data are in JSON format only).

query string variablebrief descriptionexample
registerused for user registration, takes user_name as a parameterregister=krusty
apikeyuser’s API key/token, required for further playing, needs to be set for each requestapikey=xFSd92
actioninteractive action prompt variable, used to the playing itselfaction=go-north

This subproject is written for docker too, so one only needs to clone the repo, and then execute this command in terminal window:

1

make start

tui (text/terminal user interface)

Client-side subproject is a simple attempt on how to link some kind of “frontend” with REST JSON API server. This subproject is written in Python3.7 with npyscreen and requests packages as dependecies. Also, this subproject is directly compatible with docker engine, so the TUI would work on “any” machine without the need to install Python at all.

Running client TUI in Linux/macOS terminal is simple as:

1

make run

Makefile builds the docker image, runs a basic check for local tmp/apikey file, and if this one exists, it sends an initial GET request to the server and starts the UI. Otherwise (when file does not exist) it prompts user for username, and then executes a GET request with register query string (see above).

TUI itself shows basic player variables like player’s nickname, HP (health), items in inventory. Moreover, API version, played map and room, and user’s ping are displayed too.

Fig. 1: textovka TUI after autologin showing demo map initial room settings.

Next, room description as message is printed into an isolated box. Below this box, action set is printed too. Basic directions are always displayed, but it is up to the map designer, if those directions are implemented or not.

If there is room-implemented action available, it is shown in this list too. Action can be selected using Enter or Space keys, then followed by Tab and Enter to send the action GET request to the server.

Fig. 2: textovka TUI showing extra action to be present in the specific room.

Some rooms can be dangerous – like wells, which are rooms with no exit. Danger itself could manifest with a slight HP depression, or the presence there could be directly fatal/lethal.

Fig. 3: textovka TUI showing game-over state of game.

TUI is closed by hitting CTRL+C key combination.

map (map generator)

This subproject is meant to serve as game map (skeleton) generator. It is written in pure Golang (1.16 and higher). The package itself uses only system libraries, therefore the binary is just about 2.5 MB in size.

1
2
3
4
5

Usage of ./textovka-map:
  -mapName string
    	a string, name of the new map (default "testMap")
  -roomCount int
    	an int, number of rooms to be generated (default 10)

The binary writes to standard output (stdout) and prints indented JSON (thus can be routed to .json file directly).