Go to the first, previous, next, last section, table of contents.

Game Module Forms

The game module declaration supplies information about the file as a whole. It is optional; if missing, Xconq will get the module's name from its file name, and supply defaults for the other properties.

Form: game-module [ name ] properties...

This form defines the properties of this game module. The optional name is a string that will be used to look up the module in libraries. If the name is supplied, then this form is considered to be the definition of the module, and overwrites any game-module form previously appearing in this file. If name is missing, then this form will modify the existing description of the module. Although are currently no restrictions enforced on the length or character set of a module name, Xconq may warn about a name that does not match the name of the file containing these forms.

ModuleProperty: title string

If defined, this property is the name by which the module will be displayed to players. It is not used internally, so the name can be modified freely (unlike the module's name, which may appear in other modules). Defaults to the module's name.

ModuleProperty: blurb string

This property is a one-line description that users will see when they are deciding whether to play the module. It will be displayed without any modification:

Welcome to my nightmare! (version 1.0 with stronger goblins)

ModuleProperty: picture-name string

This property is the name of a picture that may be displayed along with the module's blurb, by those interfaces that support such pictures.

ModuleProperty: base-game t/f

ModuleProperty: instructions strings...

This property is a list of strings that are the instructions on how to play the game.

ModuleProperty: notes strings...

This property is a list of strings comprising the set of detailed player's notes for the module. Both the list and each string in the list can be of any length. When displayed, the strings are all concatenated together, so the division into strings here is just for convenience. How these are displayed is up to the interface, but in general an empty string signals a new paragraph.

ModuleProperty: design-notes strings...

This property is a list of strings that are notes addressed to game designers.

ModuleProperty: version string

This property is the version of the module. Defaults to "", which indicates that the module's version is undefined.

ModuleProperty: base-module name

This property is the name of a module that must be loaded first. It is similar in effect to include.

ModuleProperty: default-base-module name

This property specifies the name of a module that will be loaded if when this module is loaded, no types are defined yet.

This is to allow a module to be used both as a standalone game and as a data source for other games. This is true of many maps, for instance.

ModuleProperty: original-module name

ModuleProperty: original-version string

ModuleProperty: original-variants list

These properties record the module's name, version, and variant selections before a game save. They are needed to record the game in the scorefile usefully.

Module Variants

Variants are options chosen by players at the start of a game. A generic variant includes information that will be used for displaying the choice to players, the acceptable range of choices, a default choice, and additional forms that may be evaluated if particular values were chosen. Variant values are always numbers.

ModuleProperty: variants items...

This property defines named variants on this module. Variants appear as startup options for the game. Each item has the form

([ name ] type [ help ] [ range/default ] [ clauses ])

The optional name is a string used to identify the choice to the players, the type says what sort of change is being enabled, help is an optional help string, range/default supplies a range of values and a default value among them, and clauses is a list of the form (value forms...), where the forms are executed while reading if the value of the variant was chosen to be value. A game module may specify any number of variants. Defaults to ().

A number of commonly useful variant types are predefined.

VariantType: world-size [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]

This variant allows players to choose the size of the world. The sizes will default to the values in this variant's data. (width and height can be lists of the form (lo dflt hi), with the obvious interpretation??)

VariantType: world-seen [ dflt ] [ clauses ]

This variant allows players to choose whether the terrain of the world will be known at the start of the game. The default setting will be the value dflt, which may be either true or false.

VariantType: see-all [ dflt ] [ clauses ]

This variant allows players to choose whether everything will be seen always, as with the global variable see-all. The default is set by dflt.

VariantType: sequential [ dflt ] [ clauses ]

This variant allows players to choose whether to move simultaneously during a turn, or one at a time. The default is set by dflt. The variant works by setting use-side-priority.

VariantType: real-time [ total [ perside [ perturn ] ] ] [ clauses ]

This variant allows players to choose realtime limits on the game. The value will default to the values in this variant's data.

VariantType: economy

This variant enables/disables the backdrop economy.

VariantType: supply

This variant enables/disables the advanced supply line system.

Including Other Modules

You can include one game module in another.

Form: include module-name [ variant-settings ]

This form has the effect of inserting the contents of module-name into the current position in the module. game-module forms in the included module are not inserted, although they are remembered and may appear in displays. Xconq will fail completely if the included module cannot be found.

Unlike C etc, the same module cannot be included more than once; you will get a warning and the module will not be loaded.

Note that the module names are not file names, so that system-specific features like directories and devices cannot be included. The mapping between module name and file name is interface-specific, so if you want to distribute a module, you should make sure all the module names don't have anything nonportable embedded. Alphanumeric characters and hyphens are guaranteed to be portable; mixed-case names are not.

Conditional Loading

You can control which forms in a module are actually evaluated by using conditional loading.

Form: if test-form sym

Form: else sym

Form: end-if sym

If test-form evaluates to true, then all subsequent forms, up until the matching else or end-if, will be evaluated. If false, then the forms will be read but not evaluated. All forms inside the conditional must be syntactically correct.


Go to the first, previous, next, last section, table of contents.