@node X11 Xconq, , Top, Top

@chapter X11 Xconq

@i{Xconq} includes an interface to the X Window System.  Since it is
only for version 11 of X, we will call it @i{X11 Xconq}.  The interface
is graphical, can work with either monochrome or color displays, and is
capable of opening multiple displays, one for each player, if desired.
It uses the Xt toolkit and Athena widgets.

@menu
* Installing X11 Xconq::
* Viewing and Printing the Documentation on Unix::
* An Introductory Game with X11 Xconq::
* Starting a New X11 Xconq Game::
* X11 Xconq Maps::
* X11 Xconq Play::
* Troubleshooting X11 Xconq::
@end menu

@node Installing X11 Xconq, Viewing and Printing the Documentation on Unix, , X11 Xconq

@section Installing X11 Xconq

The usual @samp{make} and @samp{make install} will generate and install
the executable and library into @file{usr/games/bin} and
@file{usr/games/lib/xconq}, respectively.  (See the file @file{INSTALL}
in the main source directory for more detailed instructions.)

The name of the executable is @file{xconq}.

@c As with most X programs, you can customize @i{X11 Xconq} by using
@c resources.

@node Viewing and Printing the Documentation on Unix, An Introductory Game with X11 Xconq, Installing X11 Xconq, X11 Xconq

@section Viewing and Printing the Documentation on Unix

The source form of all the documentation is ``Texinfo'', which is based
on TeX but is like HTML in many ways.  Texinfo files are readable text
files themselves, and there are tools to translate them into various
viewing formats.

The standard distribution comes with documentation in the form of HTML
files, which you can look at using your favorite Web browser.  You can
also print them out using the browser.

The next easiest option is to look at the ``info'' files, ideally with
Emacs so as to get the hypertext abilities, but any other text viewer
will do.

For printing, if you can find a preformatted version in PostScript(tm),
and have a PostScript printer, then you can send that directly to the
printer using @samp{lpr}.

To make a nicely printed manual from the sources, you will need a
version of TeX.  TeX is widely available.

Note that all the information in the manual is in a portable form, so if
you have access to another computer system with a faster or
easier-to-use formatting and printing setup, you can use that instead.

@node An Introductory Game with X11 Xconq, Starting a New X11 Xconq Game, Viewing and Printing the Documentation on Unix, X11 Xconq

@subsection An Introductory Game with X11 Xconq

To begin an introductory game, give the command @samp{xconq -g intro}.
You will get some chatter on the console as the game starts up, then
a large window with lots of panes.

The middle of the window is the most interesting part; it is a map of
the game world.  It's also almost entirely black, representing the
unknown.  In the middle you should see a small picture of skyscrapers,
representing your first city ``Jinod'', and right below a small picture
representing the soldiers of your 1st infantry.  Your infantry is framed
by a blinking square, which indicates that it is your ``current unit'';
the unit to which commands will apply.  Your units are in a green
hexagon, which is their ``cell'', and the cell is surrounded on five
sides by green cells.  All of these represent plains.  To the east there
is a brown patterned cell, which means mountains.

When the mouse pointer is over the map, you see that it looks like a
gunsight with cross hairs.  This means that you're in ``move mode'', and
that if you click on a location, the unit will try to move there.

Click on the cell east (right) of the city and infantry.  Hey, something
happened!  Your infantry is now out in the open, and it's discovered the
sea to the east and northeast.  At the same time, there is another
infantry inside the city, but it looks fuzzy; that's because it is
``incomplete''.  Your city Jinod will continue to work on the new
infantry while you move around.  Also note that the turn is now 5, when
it was 4 before.  An infantry gets to move once/turn, so when it moved,
it was done for the turn, and since there was nothing else to do,
@i{Xconq} automatically went to the next turn.  Your 1st infantry is the
only unit not doing something already, so it gets to be the current unit
again.

Your infantry can't go into the water (try it, you'll get beeped), so
instead click on the land cell to the northwest, then northeast, just
following the water's edge.  Click to move east; you then discover
another city!  While your own units have a little ``1'' in the upper
right corner, this city (which is named Mebnels) has no such emblem,
which means that it is independent.  Since you know the city is about to
be taken over by the evil robots, try to capture it -- click on the
city.  The city may resist successfully, in which case you'll have to
keep trying, once each turn.

At some point during this, you'll find that the current unit is no
longer your 1st infantry!  Jinod has been quietly working on your 2nd
infantry all along, and the new unit is now ready for orders.  @i{Xconq}
automatically jumps you to it when the 1st infantry is done for the
turn.  Click on the cell @i{immediately west of Mebnels}; you'll see
your 2nd infantry appear to jump two cells, then highlight the 1st
infantry.  What actually happened was that you gave a ``move to''
task to the 2nd; it moved once, the turn ended and a new turn started,
the 2nd moved again because it wasn't at the destination yet, and
then since 1st wasn't doing anything, it became the current unit.

Continue trying to capture Mebnels.  When the 2nd infantry arrives west
of Mebnels, you can click on Mebels to have it attack there as well.
This is crucial, because the robots are coming...

In the turn after you've captured Mebnels, you'll see that Mebnels
itself becomes the current unit.  Now, cities can't move around, but
they can produce new units; type @samp{P}.  You will get a prompt asking
to choose from a list of letters.  To see what they mean, type @samp{?}
to get an explanation.  You can choose by either clicking on the unit
icons on the right side of the window, or by typing one of the letters.
Armor will come in handy shortly, so type @samp{a}.  You will see a
small gray tank picture appear underneath Mebnels' picture.

Continue moving your 1st and 2nd infantry east.  You'll find that they
can't both be in the same cell; most @i{Xconq} games allow ``stacking'',
but it makes the display more complicated, so this game allows only one
unit per cell.  You can have several units @i{inside} a city however.
For this game, just move northeast when east is blocked.

When you get your 3rd infantry, click anywhere near the location of your
1st or 2nd infantry.  The 3rd will work its way up to the others
eventually.

Some time about now you'll start seeing units with the emblem ``2''.
Those are the enemy; attack!  As with Mebnels, you just have to click
on the enemy unit when your current unit is adjacent to it.  Keep an
eye on the notices at the top of the window, they will tell you about
how the fighting is going.

Since the game is so simple, there is not a lot of strategy to winning
it.  You need to capture as many cities as possible (search around your
first city to find others), and you need to wear down the enemy by
capturing its cities.  Eventually either the AI will dominate and
eventually wipe you out, or you will defeat all its armies and capture
all its cities.  The AI does not cheat, and doesn't get any special
advantage, so if you lose to a mere machine, well...

@node Starting a New X11 Xconq Game, X11 Xconq Maps, An Introductory Game with X11 Xconq, X11 Xconq

@subsection Starting a New X11 Xconq Game

To play @i{X11 Xconq}, just type @samp{xconq}.  You will get the default
game, which has you and a single AI as the two opposing players, in a
randomly generated 60x30 area that is mostly unexplored.  The game
design in effect is called @samp{standard}.  It is a generic ``Empire''
type game, with cities, armies, airplanes, and ships of various types.

If you're new to @i{Xconq}, and find that @samp{standard} is too
complicated and/or confusing, try the introductory game @samp{intro}
instead; type @samp{xconq -g intro} to get it.  @samp{intro} is
generally like @samp{standard}, but it has fewer types of units and
terrain, the world is predefined, you start with only one city, and the
one city is preset to build infantry.

By default, the X11 interface opens up windows on the display named in
the environment variable @code{DISPLAY}, and connects it with the first
side and player in the game.

@menu
* Xconq Command Options::
* New Game Dialogs::
@end menu

@node Xconq Command Options, New Game Dialogs, Starting a New X11 Xconq Game, Starting a New X11 Xconq Game

@subsection Xconq Command Options

The arguments to an @i{Xconq} command consist of a list of player
specifications and possibly some additional options.

@table @code

@item [@var{name}[,@var{ai}][/@var{config}]@@]@var{display}[+@var{adv}]
Attempt to open a display on @var{display} and assign a player/side to
it.  Options include naming the player @var{name}, adding an AI of type
@var{ai}, using the side config file @i{config} and asking for an
advantage of @var{adv}.  @var{adv} defaults to 1.  If @var{name} is not
supplied, then @var{name} is assumed to be the display name.  A display
named just @code{"_"} is equivalent to the default display, as in the
value of the environment variable @code{DISPLAY}.

@end table

You can get a variety of uses out of player specs.  For instance,
the player spec @code{,ai+4} asks for an AI, of a default type
appropriate to its side, with a starting advantage of 4.
If you want to give yourself an advantage, just specify @code{+4}
anywhere on the command line.

The following options are always available:

@table @code

@item -c @var{n}
Write a checkpoint every @var{n} turns.

@item -design
Make every side in the game be a designer.

@item -e[,@var{ai}][+@var{adv}] @var{n}
Create @var{n} sides and AIs to play them, using the optional @var{ai}
and @var{adv} to set the AI type and advantage of each.

@item -f @var{filename}
Play the game found in @var{filename}.

@item -g @var{gamename}
Play the game @var{gamename}, if one by that name exists in the library
(the default, or the location specified with @code{-L}.

@item -h @var{n}
Wait for @var{n} human players to join.

@item -help, --help
List all of the options.  If a game was loaded using @code{-g} or
@code{-f}, also list all of the variants for the game.

@item -host @var{name}
Set up a network game named @var{name}.  @var{name} must currently
have the form @var{host}:@var{port}, where @var{host} is the name
of a host, and @var{port} is a TCP port number.  The port number
should not already be in use; good choices are 4-digit numbers
like 1539 (@code{'^X' << 6 + '^C'}).

@item -join @var{name}
Connect to an existing game named @var{name}.

@item -L @var{directory}
Search in @var{directory} for game modules.

@item -noai
Suppress all AI creation during game setup.

@item -pre @var{form}
@item -post @var{form}
Evaluate the GDL form @var{form} before or after all game modules have
been read in.  These are primarily of interest to game designers and
testers.

@item -r
Do not add a player on a default display.  If you use this, you must
list every player on the command line explicitly.

@item --version
Display version information.

@item -w
Suppress all warnings, both during startup and during the game.

@item -x
Bring up a set of new game, variant, and player setup dialogs.

@end table

The following options only work if the game allows for the corresponding
variants.  In each case, the option corresponds to a particular setting
of a particular variant, as seen in the online help info.

@table @code

@item -M @var{width}[x@var{height}][W@var{circumf}][+@var{lat}][+@var{long}]
Set the size and position of the game area.  If only @var{width} is
given, then the @var{height} defaults to the same as @var{width}.
Circumference (@var{circumf}) defaults to 360, @var{lat} and @var{lon}
default to 0.  The name of the variant is @code{world-size}.

@item -seq
Set sides to move in sequence, one at a time.  The variant name is
@code{sequential}, with a value of 1.

@item -sim
Set sides to all move simultaneously.  The variant is @code{sequential},
with a value of 0.

@item -tgame @var{mins}
Set the maximum total number of real minutes that a game may last.
The variant is @code{real-time}.

@item -tside @var{mins}
Set the maximum total number of real minutes allowed for each side's
play.  (This is like a chess clock.)  The variant is @code{real-time}.

@item -tturn @var{mins}
Set the maximum numbers of real minutes for each turn.  When the maximum
is reached, each side automatically finishes, as per the command, and
the next turn begins.  The variant is @code{real-time}.

@item -v
Set the world to have been seen already.  The variant is
@code{world-seen}, with a value of 1.

@item -v[@var{name}][=@var{value}]
Set the variant named @var{name} to have the value @var{value}.  If the
@var{value} is not supplied, it defaults to 1 (@code{true}).

@item -vhelp
Display variant help info only.  This lists the available variants as
@code{-help} does.

@item -V
Set everything to be seen all the time.  The variant is @code{see-all},
with a value of 1 (@code{true}).

@item -V0, -Vfalse
Set everything not to be seen all the time.  The variant is @code{see-all},
with a value of 0 (@code{false}).

@end table

If debugging has been compiled in, then the options @code{-D}
and @code{-R} are also available.
See the hacking chapter of the manual for more detail.

The following options apply only to the default X11 display:

@table @code

@item -bg @var{color}
Set the background color for each window.

@item -display @var{displayname}
Open the given display for the default player.

@item -fg @var{color}
Set the foreground color for each window.

@item -geometry @var{geometry}
Set the geometry of the initial window.

@item -name @var{name}
Set the name of the application to use when looking up resources.

@end table

@node New Game Dialogs,  , Xconq Command Options, Starting a New X11 Xconq Game

@subsection New Game Dialogs

If you give the command line option @code{-x}, @i{Xconq} will
display a series of dialogs that you can use to set up a game
interactively.  The dialogs should be self-explanatory.

@c but explain them anyway, once redesigned.

@node X11 Xconq Maps, X11 Xconq Play, Starting a New X11 Xconq Game, X11 Xconq

@section X11 Xconq Maps

Once the game has started, you have at least one ``map window'' open.
(For brevity, these can be called just ``maps'').  Each map window has
identical capabilities, so you can play by using just one, or have one
for each area of interest, or have some of them serve specialized
purposes.  For instance, you can have a map window that shows the entire
world.

@menu
* Map Parts::
* Scrolling Maps::
* View Control Popup::
@end menu

@node Map Parts, Scrolling Maps, X11 Xconq Maps, X11 Xconq Maps

@subsubsection Map Parts

Each map window consists of a number of panes, whose size you may
adjust by dragging the small square grips that may be seen on the
the pane boundaries.

@example
----------------------------------------------------------
|                                     |                  |
|           history/notices           |                  |
|                                     |                  |
|-------------------------------------|     sides        |
|           command prompt            |                  |
|-------------------------------------|                  |
|             turn/date               |------------------|
|-------------------------------------|                  |
|       |                             |                  |
|       |      unit/cell info         |                  |
|       |                             |                  |
|       |-----------------------------|                  |
|       |                             |    unit types    |
|       |                             |                  |
| ctrl  |                             |                  |
| panel |                             |                  |
|       |                             |                  |
|       |         map view            |                  |
|       |                             |                  |
|       |                             |------------------|
|       |                             |                  |
|       |                             |                  |
|       |                             |     panner       |
|       |                             |                  |
|       |                             |                  |
----------------------------------------------------------
@end example
@c should prevent break across pages here

The map view is the actual display of the world.

Each map may have one @i{current position} and one @i{current unit}.
The current position is specially highlighted, and the info subwindow
displays information about it.  If in addition there is a current unit
at the current position, then it will be highlighted rather than the
entire cell, and the info pane will describe it in detail.  The current
unit is the one to which your commands apply; it will always be a unit
that you control.  If the current position includes a picture of someone
else's unit, the info will describe its type and owner but no more.

The info pane has the general form
@example
<unit owner, type, name>       <hp> <acp>|<cp> <cxp>
<location>                     <other units here>
<occupants>                    <supply>
<plan>                         <more supply>
<tasks>                        <even more supply>
@end example
Items like @code{<hp>} and @code{acp} have the form
@code{@var{current}/@var{max}}, so that you can get an idea
of how the value compares to what it could be.

@node Scrolling Maps, View Control Popup, Map Parts, X11 Xconq Maps

@subsection Scrolling Maps

It will nearly always be the case that the world is too large to be seen
all at once.  You can scroll around in two ways.  First, if you are in
survey mode, and click near any edge of the view, @i{Xconq} will put the
position you clicked at the center of the view.  By clicking in the same
place repeatedly, you can ``walk'' the view in any desired direction.

If you want to go directly to a particular part of the world, use the
panner in the bottom right corner of the map window.  To use the panner,
click and drag the shadowed box inside the panner.  The panner is sized
to match the map, and the shadowed box is sized to match the view, so
you can get a general idea of of where the map is within the world.

@node View Control Popup,  , Scrolling Maps, X11 Xconq Maps

@subsection View Control Popup

If you click the button labelled ``More...'' in the leftside controls,
you will get a popup dialog that is a full set of viewing controls.
Unlike the leftside view controls, these do not act at once; instead,
you toggle them on or off, then click on ``Apply'' or ``Done'' to see
the effects.  This allows you to make a number of changes, but only
redraw the map once when you are ready to see the results.  ``Apply''
leaves the popup in place, while ``Done'' makes it go away.  You can
leave the popup up permanently and continue play, if you like.

Note that each map will have its own separate view control popup, and
that they're not clearly distinguished from each other.  Fortunately,
these only affect display, not the game itself.

@node X11 Xconq Play, Troubleshooting X11 Xconq, X11 Xconq Maps, X11 Xconq

@section X11 Xconq Play

The basic idea of play is to be in move mode, let the program select the
next unit to do something, then give it a command, either by clicking
the mouse or by typing on the keyboard.

Each map may be in either survey or move mode (@xref{Modes})
independently of the others.  In survey mode, the default actions are
not to do anything, while in move mode, the default actions are to do
things.  This principle applies to both mouse and keyboard commands.
For instance, 'h' in survey mode moves the current position west by one
cell, but in move mode it causes the current unit to try to move west by
one cell.

@menu
* Using the Mouse::
* Using the Keyboard::
* Saving and Restoring Games::
@end menu

@node Using the Mouse, Using the Keyboard, X11 Xconq Play, X11 Xconq Play

@subsection Using the Mouse, excuse me, Pointer

Although in classic X style, all the actions may be arbitrarily
rebound, for simplicity the default @i{Xconq} setup uses the
left button for the most important actions.

@node Using the Keyboard, Saving and Restoring Games, Using the Mouse, X11 Xconq Play

@subsection Using the Keyboard

The general commands (@xref{Standard Keyboard Commands}) all work.

Commands that operate on units will be applied to the current unit of
the map.  If the map has no current unit, then you will get an error
message.

Commands that need further input will generally request it from the
prompt subwindow that is sandwiched between the history subwindow and
the date subwindow.  You do not need to put the cursor over the prompt
window to type into it however; when a prompt is up, any typed
characters will be considered to be part of the answer to the prompt.
You can type in an escape (@samp{C-[}) character to cancel the command
and clear the prompt.

If the request is for a unit type, such as when choosing a type to
construct, you can choose the type either by typing its character, or by
clicking on its entry in the unit type list.

The X11 interface defines these options to the @samp{map} command:

@table @code

@item @code{close}
Close a map window.

@item @code{meridians}
Toggle display of meridians.  Prefix argument sets spacing in arc minutes.

@item @code{rv}
Switch to reverse video.

@item @code{pattern}
Prefer patterns for drawing terrain.

@item @code{solid}
Prefer solid colors for drawing terrain.

@item @code{mono}
Switch to monochrome display. (debugging)
@ifset FULL
This is really meant for debugging only, and is only available if
debugging was compiled in.
@end ifset

@end table

@node Saving and Restoring Games,  , Using the Keyboard, X11 Xconq Play

@subsection Saving and Restoring Games

The save command @samp{S} saves games to @samp{~/.xconq/save.xconq}.
The saved game is a normal text file.  To restore the game, give the
command @samp{xconq -f ~/.xconq/save.xconq}.  The saved game preserves
all of the player information, including display names, so the restored
game will use all of the same displays as before.

If the environment variable @samp{SAVEDIR} is set, then @i{Xconq} will
use that for the directory in which to save, instead of @samp{~/.xconq/}.

You can change which displays go with which sides by using @code{-r}
to suppress the addition of a default player, and listing all of the
players explicitly, in the order desired.  For instance, suppose that
the original 5-player game was started with the arguments
@code{foo:0.0 joe@@bar:0.0 -e 2}, then to just change the displays,
restore with
@code{-f save.xconq -r baz:0.0 weeble:0.0 joe@@andros:0.0}.
This puts the original person who started the game onto @code{baz:0.0},
and the other two humans on @code{weeble:0.0} and @code{andros:0.0},
while leaving the two AIs unaffected.

This ability is also useful for swapping sides, although it can be
tricky to get right.  For instance,
@code{-f save.xconq -r ,ai ,ai ,ai ,@@foo:0.0 joe,@@bar:0.0}
restores the game, but gives the first three sides to the default
AI, and the last two (which had been played by AIs) to humans, and
disables the AIs that had been running them.  (The @code{,@@} sequence
effectively asks for an AI with an empty type name, which is interpreted
to mean ``no AI''; otherwise the displays would have been opened, with
an AI moving the units.)

@node Troubleshooting X11 Xconq, , X11 Xconq Play, X11 Xconq

@section Troubleshooting X11 Xconq

By far the most common problem with the X11 interface is setting up a
game with multiple displays.
