💾 Archived View for gemini.thegonz.net › static-sggs › game-protocol.gmi captured on 2023-06-16 at 16:23:15. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-06-14)
-=-=-=-=-=-=-
Games are implemented by commands which accept arguments and are expected to write to stdout and return exit codes as described below.
Commands will be run with current working directory a state directory specific to a single instance of the game.
Locking is dealt with, you may assume that commands will run sequentially.
All output is to stdout.
Internal errors may be written to stderr, they will go in the server log.
There are three kinds of command, split according to what filesystem operations they may use.
These commands should not access the filesystem.
Print a one-line description of the game.
Print long-form gemtext explanation of how to play the game.
This should discuss the rules, and optionally also detail init arguments and move syntax.
A title line "# Help on $game" will automatically be prepended.
PRE_ARG is a user-submitted string describing desired options for the game, or the empty string if the user has not selected any options.
Either return 0 and output ARG, a string which will be passed as an argument to 'init' and 'players',
or exit 1 and output a one-line prompt for input which will be passed as a new PRE_ARG parameter,
or exit 2 and output gemtext (with \n terminated lines), which may use link lines "=> ?[percent-encoded PRE_ARG]" to call setarg with a new parameter.
Whitespace will be stripped from the start and end of output to obtain ARG.
In the case of empty output, ARG is set to the empty string.
It is recommended to use this to denote default options.
In particular, if the game does not accept options, 'setarg' should just exit 0.
Output permitted number of players as a single positive integer.
If nothing is output, arbitrarily many players can be tried (the exit code of 'init' can then be used to enforce conditions on the number of players).
These commands may read from files in the working directory, but not outside it, and may not write to the filesystem.
Print gemtext document showing current state for player P,
or for a neutral observer if P=0.
Exit 5 if game is over.
Exit 4 if game is running, but player can't move now (or P=0).
Else exit 0, and optionally write gemtext providing links "=> move?[percent-encoded move]" for making a move;
default is "=> move Make move".
Output players who have won, separated by spaces.
These commands may use arbitrary filesystem operations within the working directory, but not outside it.
ARG is as set by setarg.
N is the number of players.
Set up state and exit 0,
or exit 4 and output an error message if N is bad,
or exit 5 if ARG is bad or there is some other error.
If MOVE can be interpreted as a currently valid move for player P, update state and exit 0.
Otherwise, exit 1 and output a one-line prompt for input which will be passed as a new MOVE parameter,
or exit 2 and output gemtext (with \n terminated lines), which can contain links "=> ?[percent-encoded move]" for trying a different MOVE parameter,
or exit 4 and output an error.
P is guaranteed to be a valid player.
Update state to reflect that player P has resigned.
P is guaranteed to be a valid player.
Exit 0 if game is now over, 1 otherwise.
The program must