Sophie: xconq-7.5.0-1.20050612.5mdv2009.1 i586

xconq-7.5.0-1.20050612.5mdv2009.1.i586.rpm

<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.39
     from ./xcdesign.texi on 12 June 2005 -->

<TITLE>Designing Games with Xconq - Game Module Forms</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="xcdesign_1.html">first</A>, <A HREF="xcdesign_31.html">previous</A>, <A HREF="xcdesign_33.html">next</A>, <A HREF="xcdesign_61.html">last</A> section, <A HREF="xcdesign_toc.html">table of contents</A>.
<HR>


<H2><A NAME="SEC140" HREF="xcdesign_toc.html#SEC140">Game Module Forms</A></H2>

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

</P>
<P>
<U>Form:</U> <B><CODE>game-module</CODE></B> <I>[ name ] properties...</I><P>
<A NAME="IDX26"></A>
This form defines the properties of this game module.  The optional
<VAR>name</VAR> is a string that will be used to look up the module in
libraries.  If the <VAR>name</VAR> is supplied, then this form is considered
to be the definition of the module, and overwrites any
<CODE>game-module</CODE> form previously appearing in this file.  If
<VAR>name</VAR> 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, <I>Xconq</I> may
warn about a name that does not match the name of the file containing
these forms.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>title</CODE></B> <I>string</I><P>
<A NAME="IDX27"></A>
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.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>blurb</CODE></B> <I>string</I><P>
<A NAME="IDX28"></A>
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:

<PRE>
Welcome to my nightmare! (version 1.0 with stronger goblins)
</PRE>

<P>

<U>ModuleProperty:</U> <B><CODE>picture-name</CODE></B> <I>string</I><P>
<A NAME="IDX29"></A>
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.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>base-game</CODE></B> <I>t/f</I><P>
<A NAME="IDX30"></A>

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>instructions</CODE></B> <I>strings...</I><P>
<A NAME="IDX31"></A>
This property is a list of strings that are the instructions on how to
play the game.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>notes</CODE></B> <I>strings...</I><P>
<A NAME="IDX32"></A>
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.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>design-notes</CODE></B> <I>strings...</I><P>
<A NAME="IDX33"></A>
This property is a list of strings that are notes addressed to game
designers.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>version</CODE></B> <I>string</I><P>
<A NAME="IDX34"></A>
This property is the version of the module.  Defaults to <CODE>""</CODE>,
which indicates that the module's version is undefined.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>base-module</CODE></B> <I>name</I><P>
<A NAME="IDX35"></A>
This property is the name of a module that must be loaded first.  It is
similar in effect to <CODE>include</CODE>.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>default-base-module</CODE></B> <I>name</I><P>
<A NAME="IDX36"></A>
This property specifies the name of a module that will be loaded if when
this module is loaded, no types are defined yet.

</P>
<P>
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.

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>original-module</CODE></B> <I>name</I><P>
<A NAME="IDX37"></A>
<U>ModuleProperty:</U> <B><CODE>original-version</CODE></B> <I>string</I><P>
<A NAME="IDX38"></A>
<U>ModuleProperty:</U> <B><CODE>original-variants</CODE></B> <I>list</I><P>
<A NAME="IDX39"></A>
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.

</P>

<UL>
<LI><A HREF="xcdesign_32.html#SEC141">Module Variants</A>
<LI><A HREF="xcdesign_32.html#SEC142">Including Other Modules</A>
<LI><A HREF="xcdesign_32.html#SEC143">Conditional Loading</A>
</UL>



<H3><A NAME="SEC141" HREF="xcdesign_toc.html#SEC141">Module Variants</A></H3>

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

</P>
<P>
<U>ModuleProperty:</U> <B><CODE>variants</CODE></B> <I>items...</I><P>
<A NAME="IDX40"></A>
This property defines named variants on this module.  Variants appear as
startup options for the game.  Each item has the form

<PRE>
([ <VAR>name</VAR> ] <VAR>type</VAR> [ <VAR>help</VAR> ] [ <VAR>range/default</VAR> ] [ <VAR>clauses</VAR> ])
</PRE>

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

</P>
<P>
A number of commonly useful variant types are predefined.

</P>
<P>
<U>VariantType:</U> <B><CODE>world-size</CODE></B> <I>[ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]</I><P>
<A NAME="IDX41"></A>
This variant allows players to choose the size of the world.  The sizes
will default to the values in this variant's data.  (<VAR>width</VAR> and
<VAR>height</VAR> can be lists of the form <CODE>(lo dflt hi)</CODE>, with the
obvious interpretation??)

</P>
<P>
<U>VariantType:</U> <B><CODE>world-seen</CODE></B> <I>[ dflt ] [ clauses ]</I><P>
<A NAME="IDX42"></A>
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 <CODE>dflt</CODE>, which may be either <CODE>true</CODE> or <CODE>false</CODE>.

</P>
<P>
<U>VariantType:</U> <B><CODE>see-all</CODE></B> <I>[ dflt ] [ clauses ]</I><P>
<A NAME="IDX43"></A>
This variant allows players to choose whether everything will be seen
always, as with the global variable <CODE>see-all</CODE>.  The default is set
by <CODE>dflt</CODE>.

</P>
<P>
<U>VariantType:</U> <B><CODE>sequential</CODE></B> <I>[ dflt ] [ clauses ]</I><P>
<A NAME="IDX44"></A>
This variant allows players to choose whether to move simultaneously
during a turn, or one at a time.  The default is set by <VAR>dflt</VAR>.  The
variant works by setting <CODE>use-side-priority</CODE>.

</P>
<P>
<U>VariantType:</U> <B><CODE>real-time</CODE></B> <I>[ total [ perside [ perturn ] ] ] [ clauses ]</I><P>
<A NAME="IDX45"></A>
This variant allows players to choose realtime limits on the game.  The
value will default to the values in this variant's data.

</P>
<P>
<U>VariantType:</U> <B><CODE>economy</CODE></B><P>
<A NAME="IDX46"></A>
This variant enables/disables the backdrop economy.

</P>
<P>
<U>VariantType:</U> <B><CODE>supply</CODE></B><P>
<A NAME="IDX47"></A>
This variant enables/disables the advanced supply line system.

</P>



<H3><A NAME="SEC142" HREF="xcdesign_toc.html#SEC142">Including Other Modules</A></H3>

<P>
You can include one game module in another.

</P>
<P>
<U>Form:</U> <B><CODE>include</CODE></B> <I>module-name [ variant-settings ]</I><P>
<A NAME="IDX48"></A>
This form has the effect of inserting the contents of <VAR>module-name</VAR>
into the current position in the module.  <CODE>game-module</CODE> forms in
the included module are not inserted, although they are remembered and
may appear in displays.  <I>Xconq</I> will fail completely if the included
module cannot be found.

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

</P>
<P>
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.

</P>



<H3><A NAME="SEC143" HREF="xcdesign_toc.html#SEC143">Conditional Loading</A></H3>

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

</P>
<P>
<U>Form:</U> <B><CODE>if</CODE></B> <I>test-form sym</I><P>
<A NAME="IDX49"></A>
<U>Form:</U> <B><CODE>else</CODE></B> <I>sym</I><P>
<A NAME="IDX50"></A>
<U>Form:</U> <B><CODE>end-if</CODE></B> <I>sym</I><P>
<A NAME="IDX51"></A>
If <VAR>test-form</VAR> evaluates to <CODE>true</CODE>, then all subsequent forms,
up until the matching <CODE>else</CODE> or <CODE>end-if</CODE>, will be evaluated.
If <CODE>false</CODE>, then the forms will be read but not evaluated.  All
forms inside the conditional must be syntactically correct.

</P>

<HR>
Go to the <A HREF="xcdesign_1.html">first</A>, <A HREF="xcdesign_31.html">previous</A>, <A HREF="xcdesign_33.html">next</A>, <A HREF="xcdesign_61.html">last</A> section, <A HREF="xcdesign_toc.html">table of contents</A>.
</BODY>
</HTML>