A-code tutorial

This tutorial will guide you through a basic A-code implementation of Roger Firth's nano-adventure "Cloak of Darkness". Here is Roger Firth's summary specification of the game:

• The Foyer of the Opera House is where the game begins. This empty room has doors to the south and west, also an unusable exit to the north. There is nobody else around.
• The Bar lies south of the Foyer, and is initially unlit. Trying to do anything other than return northwards results in a warning message about disturbing things in the dark.
• On the wall of the Cloakroom, to the west of the Foyer, is fixed a small brass hook.
• Taking an inventory of possessions reveals that the player is wearing a black velvet cloak which, upon examination, is found to be light-absorbent. The player can drop the cloak on the floor of the Cloakroom or, better, put it on the hook.
• Returning to the Bar without the cloak reveals that the room is now lit. A message is scratched in the sawdust on the floor.
• The message reads either "You have won" or "You have lost", depending on how much it was disturbed by the player while the room was dark.
• The act of reading the message ends the game.

First, however, a few words on style and terminology.

• Except in text messages to be displayed to players, A-code is completely case insensitive. As a personal convention, I use lower case in actual A-code code, except in declarations, where names of entites being declared are in upper case.
• When explaining code, I will be presenting code snippets in upper case in order to avoid excessive quoting.
• All declarative keywords (a.k.a. major directives) must start in column 1 (i.e. with no leadin spaces or tabs). A declaration is terminated by another non-comment) line starting in colum 1, or by the end of a file.
• A-code opcodes (a.k.a. minor directives) as well as any lines in declaration bodies must have at least one blank or tab preceding them. Beyond that, A-code does not care about levels of indentation.
• Comments are permitted everywhere, except within text declarations. The start of a comment is signalled by a hash (#) sign and A-code simply ignores the sign, any preceding blanks or tabs, and the rest of the line. (NB: Dave platt's version of A-code had a different comment convention.)

Once you have an acode source file, you will want to convert it into a game executable. Other than an ANSI C compier, you will find everything necessary in the acode-12.91.tgz tarball. If you can use the advbld bash script, just give it the name of the source file and it will do the rest. If you cannot use a bash script, you'll need to do it "manually". First run the acdc translator, giving it the source file name or pathname as an argument. Then use any ANSI C compiler on resulting .c and .h files together with the three kernel files: adv00.c adv01.c and adv0.h.

A link to the complete A-code source of the game developed in this tutorial will be given at the end of it, but if you prefer to see it sooner, the source can be found here.

Proceed to the tutorial