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; see See section Files and Directories for more detail.

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: `program-version` versions

This property dentifies Xconq versions for which this module is appropriate. If specified, then players will get a warning if they attempt to use this module with an inappropriate version of Xconq. Possible forms include a string, which allows the module only for exactly matching version of Xconq, and `(comparison version)`, which allows versions satisfying the comparison test, which may only be `>=` or `<=`. So for instance

    (game-module "foo" (program-version (>= "7.0.3")))

is claimed to only work for versions 7.0.3 or later. Defaults to `""`, which means that the module is appropriate for any version of Xconq.

Notes that the `program-version` is strictly a heuristic to forewarn players; in practice it can be very difficult to know which modules work with which programs. (The problems are similar to those encountered by programmers using different compiler versions on their programs.)

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 this module is given as the "top-level" module, such as via `-g` on a command line.

This is to prevent disasters when a library module that is used only by other modules is instead loaded as if it were a full game design.

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
- Including Other Modules
- Conditional Loading

### 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. The items have the form `([ name ] type [ range/default ] [ clauses ])`. The name is a string or symbol used to identify the choice to the players, the type says what sort of change is being enabled, range/default supplies a range of values and a default value among them, and clauses is a list of the form `(value forms...`. 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.

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.

### 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.