A-code library mode interface

Normally, A-code games drive their own main loop, but various app frameworks insist on taking this functionality over. To cater for implementations based on such frameworks, A-code kernel has a library mode. When compiled in this mode, instead of having main(), it has a function called advturn(), which takes as its sole character string argument a a request (e.g. a player's command), and returns as its value a pointer to the game's response.

char *advturn(char *command)

Examples of such builds are the emscripten-based HTML/JavaScript build of Adv770 and Brian Ball's iOS build of the same game. The advbld script can be used to build test library mode versions of game executables. It uses the libtest.c wrapper provided with the kernel sources.

At present, there is one important restriction on A-code games to be built using the library mode: they cannot use the QUERY directive. Reasons for this restriction, as well as a workaround, can be found in the section describing the A-code CONTEXT mechanism.

The advturn function takes a character string as its single argument and returns a pointer to a character string. This pointer is maintained by the kernel and should not be manipulated by the calling code.

Once the game is running, the argument string contains a game command obtained from the player and the returned pointer points to the game's response to that command. However, there are also other special values that the argument string can have:

"_INFO_"

Requests game's info. The returned string contains game's name, version and date.

"_LIST_"

Requests the list of saved games separated with '|' (vertical bar) used as a separator. If there is a game-in-progress save, it heads the list under the name of the game prefixed with a dot (e.g. .adv770).

"_START_[{TEXT_|HTML_}]"

Requests a new game to be started. The optional "TEXT_" or "HTML _" force use of plain text or HTML output, as appropriate. The default is HTML.

"_RESUME_[{TEXT_|HTML_}]"

Requests the game-in-progress (if any) to be resumed. Text or HTML output can be nominated in the same manner as for _START_.

"_LOAD_[{TEXT_|HTML_}]<save_name>"

Requests the nominated saved game to be restarted. Here too, "TEXT_" or "HTML_" can be used to force the desired output format, e.g. "_LOAD_HTML_mygame".

Except for the above special cases, the argument string is interpreted as the player's next command to be processed by the game. The output string contains the full game's response, prefixed with a single character indicating the type of the response:

• 'f' means this is the final response – the game is over
• 'q' means the response is a query of some sort (not necessarily a yes/no one)
• 't' signals just ordinary text, which should be followed by a prompt before requesting player's next command
• 'n' signals null response (this happens if the command string is null). The rest of the response is unchanged from the previous non-null command.

The simple libtest.c wrapper program supplied with the A-code kernel sources provides an example of using the library mode.