A-code documentation

Though A-code is not by any stretch of imagination (and despite its virtues) a popular IF language, you never know – the built-in browser mode, plus the ability to create pure HTML/Javascript versions might attract a brave soul or two. Hence this page.

Contents

Not included are a few things, which as a putative user you are expected to provide on your own:

• A text editor of your choice
• An ANSI C compiler
• And if you wish to try your hand in creating new games: a dash of creative imagination.

A-code sources

Complete A-code system sources and documentation are supplied as a single tarball (mipmip.org/acode/acode-12.85.tgz). Please see the tarball description document for information on its contents.

Building games from source

Firstly, let's deal with building runnable games from A-code source files and the ways of running such games, once built.

A-code build types explained
Acode games can be built in five distinct ways: console, combined browser/console, single-turn (for running in a cloud in a CGI, PHP or similar wrapper), HTML/JavaScript and library test. This document explains what all these build types are are and what they are for.

Using the advbld script to build A-code games
Since this file is a part of my A-code framework bundle, you clearly have the advbld script installed. This document explains how to use the script to build A-code games in various modes, so you don't have to bother with the "how" of it.

Running A-code games
The A-code kernel understands a number of command line options, though some of these need active support from the A-code source. E.g. adv550 does not understand the name of a game save-file to restore being supplied on the command line, and may land the player in limbo, with no source of light.

If you cannot or do not wish to use the advbld script for building games, here are a couple of document explaining how to do it in a more "manual" manner.

Translating A-code source into compilable C code
To build an A-code game from its A-code sources (files suffixed with .acd), you first have to use the acdc translator to create derived C sources. This document explains how.

Creating an executable from derived C sources
Once you have created (or downloaded) derived C sources of an A-code game, you are ready to create various modes of executables. This document explains how. (See a separate document for an explanation of build modes.)

Debugging A-code games
Since A-code sources get converted into C for building an executable, there are two distinct levels on which games can be debugged: C or A-code.

C level debugging is generally only required for kernel development and standard C debugging tools can be used for the purpose. On hopefully very rare occasions it may be desirable to trace C-level execution of a misbehaving game. To assist with this, A-code source lines can be added as comments to translated C sources.

A-code level debugging is dione by adding wizard mode tools by means of the optional include directive. Such tools may generally depend on the specifics of a given game, but a good selection can be found in debug.acd supplied with sources of Adv770. The above linked document provides a more detailed explanation.

The A-code language

A-code 12 guide Explains the concepts of the language and provides a reference guide to its components.

A-code parser
This document describes A-code parser, which has some unusual features.

A-code texts
This document explains the details of A-code texts in all their unique glory. A minimal understanding of the A-code language is helpful but not essential.

A-code vocabulary
This document explains the unique aspects of A-code vocabulary handling.

Diving deeper...

The next group of documents discusses some aspects of the language in a greater depth.

The UNDO and REDO directives
The A-code UNDO and REDO directives explained.

The library mode interface
In the ADVLIB mode, the A-code kernel presents itself as a function called advturn. This document describes its functionality and calling sequence.

The CONTEXT mechanism
If an A-code game is to run in a cloud, which is very useful for beta-testing, it must not use the the QUERY directive. This document explains how the CONTEXT variable can be used to avoid use of QUERY. (The no-QUERY restriction may be removed in a future version of A-code, in which case this page will become obsolete.)

Upward compatibility of saved games
A-code is unusual in that with a little care a game author can ensure that saved games are upward compatible and can be loaded by later game versions. This document explains how.

Writing games in other languages
A-code permits game to be written in languages other than English, provided
(a) ASCII conventions are used in separating words (blanks, octal 32) and lines (line-feeds, octal 12, optionally prefixed by carriage-return, octal 15).
(b) text is parsed left to right.

A-code debugging
Sorry, this document is yet to be written.

A-code history

Finally, some history...

Differences between A-code styles
A-code has mutated over time and this documentation reflects its current state. Anybody looking at older games written in the language (particularly Platt's Adv550 (style 1) and the Goetz variant Adv580 (style 2)) will see some notable differences. This documents attempts to summaruse differences between different styles.

A-code history
This document describes post-Platt/Goetz development of the language as I recall it.