A brief summary of A-code

PLACE +TUBE You're in lava tube at top of chimney. %You're at the top of a narrow chimney in the rock. A cylindrical tube composed of hardened lava leads south and northwest[/, from where comes some ][/silvery /day/orange ][/light, providing a dim illumination to this place].

OBJECT "nest with eggs in it", =NEST, =EGGS Nest with golden eggs %There is a large nest here, full of golden eggs! &The nest holding the eggs is lined with some sort of bird down - might be goose, but I am not sure. The eggs themselves gleam dully in the light with the unmistakable gleam of pure gold.

Each of the above "major directives" must appear in column 1. A major directive embraces all following lines up to but not including the next major directive statement (i.e., all lines in which column 1 is blank) or the end of the source file in which it occurs.

Special entities and flags

Not all entities or flags need to be declared explicitly. Some are "automatic" and some are "optional"

"Automatic" means that the entity is declared automatically. Automatic entities may be explicitly declared by the program, but if so, must be of the correct type. If an entity of that name is declared as some other type, this is treated as a compilation/translation error.

"Optional" means that the entity may but need not be declared by the program. If declared, it has a special meaning. An entity of that name but of a different type is treated as a compilation/translation error.

ARG1 – automatic variable

Use: set by the kernel to the refno of the player command's verb
Possible values:

BADWORD – automatic state

Use: set by the kernel if the word is not understood.

AMBIGWORD – automatic state

Use: set by the kernel if the player's word can be an abbreviation of more than one vocabulary word.

AMBIGTYPO – automatic state

Use: set by the kernel if the player's word can be matched as a typo in more than one way

SCENEWORD – automatic state

Use: set by the kernel if the player's word is not found in the vocabulary but matches a word (in excess of three characters) in the latest location description or in a text displayed since the last move.

ARG2 – automatic variable

Use: set by the kernel to the refno of the player's noun (if any) or zero otherwise.
States: (as ARG1)

ARG3 – automatic variable

Use: At present used solely for EXCEPT processing. If player's command is of the form "<verb> ALL EXCEPT <list>", ARG3 may be set by the kernel to BADWORD, AMBIGWORD or AMBIGTYPO, if appropriate.

CONTEXT – optional variable

Use: avoid use of the QUERY minor directive in game builds which require single-turn operation (see the section on A-code game build modes).
Value: If non-zero, indicates the current command to be a response to a query, the value (as set by the program) indicating the nature of the query.
Flags:

PROMPTED – automatic flag

Use: set by the kernel if the player has been prompted.

ENTNAME – optional variable

Use: when processed by the SAY directive, shows the symbolic name of the entity to which ENTNAME is set to point.
Value: a pointer to a named entity set by game's code.
Use of ENTNAME has the two side-effects:

It stops the dot character ('.') acting as a player command separator, permitting reference to entity names containing this character.
It a player command word is not found in the games vocabulary, game entity names are also searched by the parser; only exact matches are accepted – no abbreviations and no typo matching.

The variable is intended for game debugging in the wizard mode. See the section on debugging A-code games.

TYPO – optional text

Use: enables single-typo matching of player commands against the games vocabulary.

The TYPO text must contain a switch of 4 (or a multiple of four) components. It is used by the kernel to explain a typo match to the player. Regardless of the number of components, it must be declared as

FRAGMENT CYCLE TYPO

The first three components in each foursome must contain one word holder (#). The four switch components (in any of the switch quads if there are more than 4 components) are used by the kernel as follows:

Shows original player word that got typo-corrected
Shows the typo-corrected version for what the player gave
Shows the full non-abbreviated matched word if typo-corrected version is an abbreviation.
States that the corrected version is assumed

Here is an example from Adv770:

FRAGMENT cycle TYPO
    [Sorry, the word "#" is not familiar to me./ I'll just assume you
    meant "#"/, i.e. "#"/./
    Regretfully, I don't have "#" in my dictionary./ But I do know
    "#"/, as in "#"/, so I'll assume you meant that./
    The word "#" is not one I know./ Let's assume you meant "#"/,
    meaning "#"/./
    I wonder what "#" might be.../ I guess it could be mistyped
    "#"/, i.e. "#"/, so I'll assume that was what you meant.]

UNDO and REDO optional verbs.

Use:

Their presence activates the A-code undo/redo facility, enabling players to undo a specified number of last commands and, if necessary, undo some or all of this undoing. This is described in the section dealing with undo/redo.

UNDO.STATUS – optional variable

Use: set by the kernel to indicate the number of commands undone or re-done, which need not be the number requested by the player. If the variable is declared, the below flags are declared automatically:

UNDO.INFO – automatic flag

Use: Can be used by game code to note that player has been advised of rules for using undo; set to off by default and ignored by the kernel.

UNDO.TRIM – automatic flag

Use: maintained by the kernel: if set, the level of undo/redo was found to be excessive and had to be trimmed to match the existing undo history.

UNDO.INV – automatic flag

Use: maintained by the kernel: if set, the player's inventory has changed as the result of undo/redo.

UNDO.BAD – automatic flag

Use: maintained by the kernel: if set, undo/redo failed.

DWARVEN – optional variable

Use: If set to non-zero, all text output by the game is shifted circularly one position up in the alphabet and all player input is shifted one position down. If set to zero, any portion of game text delimited by % signs is output shifted one position up.

PROMPT – reserved optional variable

Use: none at present. Reserved for specifying non-standard prompt.

SCHIZOID an automatic object flag

Use: Indicates that the object is to be treated as present in its current location, and also in the immediately succeeding one (i.e. the one with the refno one higher).

Minor A-code directives (a.k.a. opcodes)

The actual A-code code consist of minor directives (or opcodes) followed by their arguments (if any). A line of code cannot have more than a single opcode line.

The following is a list of the available opcodes and a quickie description of what they do. As noted previously, in some cases if an argument is a variable, it is automatically de-referenced – i.e. the operation indicated by the opcode is applied not to the argument but to the entity referenced by the argument. Any such opcode arguments are denoted by a trailing asterisk in the following summaries.

Local variables

LOCAL varname [varname...]

Declares correspondingly named variables local to a procedure. It must immediately follow either the major directive declaring the procedure in question, or another LOCAL declaration. Local names pre-empt any identically named global variables. Local variables are dynamically initialised to zero value and zero bitscreen whenever the procedure is entered. They do not exist outside the procedure.

Local variables are not a part of the data set saved/restored by saving or restoring a game image. Thus they can be used to preserve some values over a game restore, instead of using the (now obsolete) EXEC 6 and EXEC 7.