=================================================================================
XMaps 208                                                               XMaps.txt
=================================================================================

                    XMaps: UT the way you want, when you want
                    =========================================

XMaps is designed to significantly extend UnrealTournament's map selection
capabilities in both stand-alone and multiplayer games. The original game
limits of 32 maps per list and one custom list per game type have been removed -
XMaps supports 100 custom map lists that can hold up 150 maps each, andcan be
used for any game type or mod. XMaps also supports Mutator lists that can be
set up for each map list and each type of game, and can match the number of
players in the game to whatever the map designer recommends. In team games,
XMaps can ensure that the number of players on each team is the same, even if
the map designer didn't recommend a number of players.

Random map selection is also included, and although it's based on the idea of
my Map Randomizer mutator, XMaps goes way beyond what that could do. Up to 150
Favourite maps can be set up for any game type, and you can set up specific
XMaps behaviour for all your favourite mods.

XMaps can also automatically switch between any Game Types or mods you select,
while using all of XMaps' other features at the same time. Key bindings allow
you to skip or repeat a level, or switch game types, while a level is playing.
An in-game HUD menu allows you to switch games or maps at any time.

So ... pick any UnrealTournament game, create a few map lists, pick your
favourite maps and the mutators you like; fire up UT and you never need to set
the Game options again. At the end of a level, XMaps will switch to your game
type, load one of your maps, automatically set up the right number of players
and then load each of your favourite Mutators...

I've added as many features as I could from the requests of existing XMaps
users; I'd like to thank all the people who took the time to mail me with
suggestions, feature requests and general comments - it's much appreciated.

XMaps' basic feature list is shown below. Check out the 'XMaps Setup Window'
and 'XMaps Game Options Window' sections of this file for detailed descriptons
of the features.


  o Decent Setup Windows
    --------------------

    XMaps has a series of Setup window to let you configure all of its features
    - no more mucking about with INI files. All the XMaps Setup windows support
    tooltip- style help on the UnrealTournament status bar - that should be
    enough to get you started.


  o Support for All Game Types
    --------------------------

    XMaps reads all the game types you have installed, including mods, by
    checking out your UnrealTournament installation. You can set up Extended
    map lists, Favourites and Mutators for absolutely any game type. What's
    more, if you want to set the Random Map Selection to only use specific map
    prefixes for a mod - for example, CTFM for MultiCTF - you can configure
    this in XMaps Game Options.


  o Game Type Switching
    -------------------

    XMaps can switch between any set of game types or mods you like, at random.
    All of the Extended map lists, Favourites and Mutators are supported while
    XMaps is switching games - you simply select the list of games types and
    mods that you'd like XMaps to switch between. As with all other XMaps
    features, this is both optional and completely configurable.


  o Improved Random Map Selection
    -----------------------------

    XMaps adds one very important feature to the 'Use All My Maps'
    functionality of Map Randomizer - a 'most recently used' (MRU) list. XMaps
    uses this MRU to track the random maps it picks, so you won't see the same
    map for quite some time. Guaranteed. Unless, of course, that's what you
    want. In which case, use...


  o Random Maps, with Favourites
    ----------------------------

    Random map selection is all very well, but what if you want to see some of
    your favourite maps every now and then? Well, you use XMaps Favourites -
    set up a list of up to 150 maps for any game type or mod, and XMaps will
    pick a map from that list every now and then.

    Just how often the Favourites are picked is controlled from the XMaps Game
    Options window - from every other map (or so) to every ten maps (or so).
    The frequency of Favourites is slightly randomised, so it won't feel too
    formulaic. XMaps still uses the MRU even when Favourites are on, so you won'
    t see maps repeated too often.


  o Change the Map, before it's finished
    ------------------------------------

    XMaps gives you complete control over a game using a series of key bindings.
    These allow you to skip or repeat a level, and even switch game types on
    the fly.


  o In-game HUD Menu
    ----------------

    XMaps supports an in-game HUD menu that you can use in stand-alone games to
    switch game types or pick a map from any of your lists - Favourites or
    Extended - for any game type. A number of XMaps options are also available:
    change the Extended map list for a game type, turn Game Switching on or off,
    change the XMaps map selection mode and add the current map to a suitable
    map list.

    Since the menus can hold a lot of options, the menu scroll buttons can be
    right-clicked as well as left-clicked. A right-click moves the menu down by
    a page.

    Assign a key binding in UT's Preferences menu to open the HUD menu. Use the
    Escape key or the Close option to close it.


  o 100 'Extended' Custom Map Lists
    -------------------------------

    Extended map lists are the real advance in XMaps - and there are 100 of
    them that you can assign to any game type or mod. The lists are called
    Extended because they'll hold up to 150 maps, instead of the built-in limit
    of 32 maps that UnrealTournament map lists support.

    Each map list can be individually named, and they can be played
    sequentially (where each map is selected in the order of the list), or at
    random (when no map will be picked again until all of the maps in the list
    have been picked). You can also use your Favourites when playing an XMaps'
    Extended map list, and set up a list of Mutators that XMaps will load when
    the Extended map list is in use.


  o Change the Number of Players to Match the Level Design
    ------------------------------------------------------

    When a level designer publishes a map, they usually recommend an 'ideal'
    number of players, sometimes a fixed number like "10", sometimes a range
    like "8-12", "12+" or "2 to 16". To get around the problem where you have
    too many players in a small map, or too few in a large map, XMaps can
    automatically change the number of players to match the level designer's
    recommendation.


  o Set up your Favourite Mutators
    ------------------------------

    If you're fed up of having to change your Mutators list every time you
    change game types, then XMaps' Mutators list is for you. Add as many
    Mutators as you like for each game type, and when it starts up, XMaps will
    load them for you.

    In addition to the game type Mutators, you can add as many Mutators as you
    like to each of your Extended map lists.


I hope that XMaps will improve your UnrealTournament experience - whether you
just play stand-alone practise sessions, or you run your own server. I'm keen
to add any features that make XMaps as useful as possible, so if you have any
ideas, drop me a line - check out the 'Contact Details' section below.

Happy gaming!!

TouchStone, 27th April 2001.


================
Installing XMaps
================

Umod Installer
--------------

Extract the XMaps.umod file from the file you've downloaded, and run it to
install or upgrade the Mutator. If you just get the File Associations dialog
box, check out the Installing Mutators section of the Mutators FAQ, which you
can find at http://www.planetunreal.com/mutation/FAQ/.

Non-umod Archive
----------------

Extract the contents of the archive into your UT directory; XMaps.u and XMaps.
int should be placed in your System directory, and XMaps.txt in your Help
directory.

Installation Notes
------------------

If you're upgrading from a version earlier than 201, then the first time you
use the Game Options button XMaps will upgrade your existing Extended and
Favourite map lists. This can sometimes take up to a minute or so, but usually
only takes a few seconds.

Since XMaps supports any game type installed in UnrealTournament, it can take a
short while to load the Game Options window (1) when you've installed XMaps for
the first time, or (2) when you upgrade from a pre-203 version. Once this is
complete, though, XMaps will have stored all the game-type information; it won'
t take more than a second or two to load Game Options after this. See 'XMaps
Game Options Window' for  information on what you should do in XMaps when you
install, uninstall or upgrade a mod that supports a new game type (such as
MultiCTF or Weaponer).

You can leave the Map Randomizer installed if you already have it; just don't
try to run both mutators at the same time. They both work the same way (see
Technical Notes below), so one of them won't work. To be blunt, XMaps does
everything Map Randomizer did better, and much more besides. So, you may as
well remove Map Randomizer - open Add/Remove Programs from the Control Panel,
select UnrealTournament and click the Add/Remove button. Check the Map
Randomizer option in the list presented, then click Next and remove the mod.

Note that, since XMaps remembers the size and position of its Setup windows,
you may find that you need to increase the size of the Game Options window when
you upgrade to a version that introduces a new Setup Page to XMaps.


========================================
Getting XMaps to run in UnrealTournament
========================================

The game must be set up to 'Auto Change Levels' for XMaps to work at all. In
versions 106 and later, XMaps automatically sets this up when it loads. The '
Auto Change Levels' option makes UnrealTournament read your map list when it
changes levels. XMaps sees this happening and jumps in to implement its map
selection features. Since XMaps takes over this feature, the Map List you
select in the 'Start Game' windows will have no effect on the game.

To use XMaps, select your game type as usual and select the Mutators button.
Add 'XMaps' to the Mutators Used list, and check the 'Always use this Mutator
configuration' box to make sure it's used each time the game switches levels.
Close the Configure Mutators window and Start the game. UnrealTournament
remembers these settings, so you only need to do it once.

If you run a server from the console, or a command-line, you can add the game
option string '?mutator=XMaps.XMapsControl' to the execution command instead (
without the quotes). If you're using XMaps to switch game types on a server,
then XMaps will recognise this and add itself to the game option string each
time a new game type is loaded.


=================================
XMaps Setup Window - Where Is It?
=================================

When UnrealTournament has one or more configurable mods installed, it adds a
Mod option to the main menu bar. When XMaps is installed, it adds an 'XMaps'
entry to that menu. So - bring up the main UnrealTournament menu, then select '
Mod'. Click on the XMaps entry, and there's the Setup window.

XMaps Setup is in three parts - the Setup window that configures the main XMaps
features you want to use, the Server Options for settings that only affect
servers, and the Game Options window where you set up Game Switching options,
Extended map lists, Favourites and Mutator lists for each game type.


==================
XMaps Setup Window
==================

This is where you choose the XMaps features that you want to use. The features
are divided into three main categories - Map Selection, Game Switching and
Player Matching, all described below. There's also a 'Large HUD font' option
that gets XMaps to use a large font when drawing the in-game HUD menu, and a '
Pause for HUD' option that makes XMaps pause UT when you use the in-game HUD
menu.

The Game Options button opens the Game Options window (see XMaps Game Options
Window below). If you want the Game Options window to open straight away when
you select XMaps from the Mod menu, tick the 'Auto-open Game Options window'
check-box in the Game Options window.

The Server Options button opens the Server Options window (see XMaps Server
Options Window below).

The Setup window also shows the version of XMaps that's installed.

-------------
Map Selection
-------------

XMaps offers four ways of selecting maps:

  o Random Maps

    XMaps will pick a map at random from your entire UnrealTournament
    installation, at the end of each level. The map selected will be suitable
    for the type of game being played, so if you're playing Capture the Flag,
    for example, any map name that starts "CTF..." could be chosen. Capture the
    Flag maps are said to have a map 'prefix' of "CTF".

    The same map-prefix matching applies when you're playing a mod - XMaps will
    choose maps that match the mod's prefix. For example, the MultiCTF mod
    specifies it's map prefix as "CTF", so any CTF map could be loaded, even
    maps that haven't been designed for MultiCTF. This is why XMaps allows you
    to specify the map prefix to use for mods when you're using its Random Maps
    mode.

    See 'Favourites Page' for details on how to change the Map Prefix for a mod.

  o Extended Map List, in order

    XMaps picks maps, in the order you set them up, from the Extended map list
    selected for the type of game playing.

    See 'Extended Map Lists Page' for details on how to set up Extended map
    lists.

  o Extended Map List, random order

    XMaps picks maps at random from the Extended map list selected for the type
    of game playing. When Extended map lists are played in random order, no map
    will be picked again until all of the maps in the list have been picked.

    See 'Extended Map Lists Page' for details on how to set up Extended map
    lists.

  o None

    XMaps doesn't pick maps at all. This option is provided for users who want
    to use other features of XMaps (such as Player Matching or Game Switching),
    without using the Map Selection features.


If you choose any type of Map Selection other than 'None', you can instruct
XMaps to Use Favourites while it's picking maps. If 'Use Favourites' is ticked,
and you've set up a list of favourite maps for the type of game that's playing,
then XMaps will pick one of those Favourites every now and then. This can
really improve your UT experience when playing in any Map Selection mode -
which ever type of Map Selection you choose, you'll get to see your all-time
Favourites every now and then.

See 'Favourites Page' for details on how to set up Favourites, the types of
maps that XMaps will pick (according to the Map Prefix), and just how often
Favourites will appear.


--------------
Game Switching
--------------

After a few Deathmatch games, perhaps you tend to feel like a bit of Assault ...
or maybe some Last Man Standing to really get the blood racing. Or even a
little Tournament Team Game action if you're feeling sociable...

To get XMaps to switch game types every now and then, tick the 'Switch game types'
check box. XMaps will switch between the game types you choose, at random, as
often as you like. All of your XMaps settings for the game types that get
switched will be loaded as usual - this is one of the reasons you may want to
set up a specific set of Mutators and Favourites for each game type.

Note that XMaps won't automatically switch game types at the end of the first
part of an Assault game, unless you configure it that way.

See 'Game Switching Page' for details on how to choose the game types, set how
often XMaps will switch and configure Assault switching behaviour. See '
Mutators Page' for details on setting up game type Mutator lists.


---------------
Player Matching
---------------

If you want XMaps to change the number of players in each level to match the
number that the map designer recommends, tick the 'Match players' check box.
When each level starts, XMaps sets the number of players as follows:

    Network games:      the minimum number of players is set to the level
                        designer's recommendation.

    Non-network games:  the number of bots is set to one less than the level
                        designer's recommendation. Then, the bots plus you
                        make up the ideal number of players.

Some maps are designed with a range of players in mind, such as "8-12". XMaps
allows you to choose which part of that range you want to match. When 'Match
players' is on, a slider lets you choose from the lowest number of players to
the highest. In the 8-12 players example, XMaps would set the number as follows:

    Slider value    Number of players
    ------------    -----------------
    Lowest...               8
    Lower...                9
    Average...              10
    Higher...               11
    Highest...              12

If the level doesn't recommend an ideal number of players, XMaps uses the user'
s configuration instead, as set in UnrealTournament's Start Game windows.

If 'Match players' is on, and you play a team game, then XMaps will make sure
that the number of players on each team is the same. If the map designer didn't
include a recommendation for the number of players in the map, XMaps will still
make sure that the teams are even.


===========================
XMaps Server Options Window
===========================

The Server Options window is where you set up the server-specific options for
XMaps. These options kept seperate because they only ever affect UT when you're
running XMaps on a server. Other XMaps options affect multiplayer and stand-
alone games (also known as Practice Sessions).

Many of XMaps' features, such as the Mutate commands that allow you to switch maps or
game types on the fly, will only work on a server if you are the admin user. In
the past, you would have to use the 'adminlogin' command each time the level
restarted to become an admin user (see the 'XMaps Mutate Commands and Key
Bindings' section below for more information).

The Admin Password edit box in the Server Options window gives you the chance
to tell XMaps what the adminlogin password is. If you enter your server
password here, then XMaps will automatically log you in when you want to use an
admin-level XMaps feature. If the password is correct, you'll be an admin user
as soon as you use any of these admin-level features.

==================================================
XMaps Game Options Window - What's All This, Then?
==================================================

The Game Options window is where you set up the Extended map lists, Favourite
maps and Mutators that you want for each game type. It's also where you
configure the way Game Switching will work. The window is split into two parts -
a list of the Game Types Xmaps knows abour, and a Setup Page for each of XMaps'
options. The settings shown in the Setup Pages refer to the Game Type selected
in the list. If you want to see or change any game options, select the Game
Type in the list and the Setup Pages will change to show those options. The
only exception to this rule is the Game Switching Page - those settings are the
same for all the Game Types.

Since XMaps used to take a long time to read all the Game Types available, it now
reads your UnrealTournament installation when it's installed, and saves the
Game Types for it's own use. That way, load times are significantly reduced.
The only disadvantage of this method is that XMaps won't automatically know
when you install, upgrade or uninstall a mod that supports a custom Game Type (
such as MultiCTF or Weaponer).

For this reason, there's a Refresh button in the list of Game Types. If you install,
upgrade or uninstall a mod that supports a custom Game Type, use this Refresh
button to update XMaps' stored information.

Note that, if a mod you've installed isn't in the list after you've installed
XMaps or done a Refresh, then it's a Mutator, not a Game Type, and can be added
using XMaps' Mutators lists.

If you want the Game Options window to open straight away when you select XMaps
from the Mod menu, then tick the 'Auto-open Game Options window' check-box at
the bottom of the window.


===================================================
XMaps Game Options Window - Extended Map Lists Page
===================================================

This page of the Game Options window sets the Extended map list that XMaps uses
for each game type you can play, and allows you to edit, remove, and create
Extended map lists. To check out the Extended map lists for a game type, select
the game type in the list on the left and select the Extended Map Lists page.

Up to 100 lists can be created - the number in use is shown in the middle of
the window. If you use all 100, you can Remove any of the lists by choosing it
from the list and using the Remove button. This will free it up, ready to be re-
used. Note that, if you remove all the maps from a list, it will automatically
be Removed from XMaps.

If there are any Extended map lists set up that XMaps can't use (for example,
if you've uninstalled a game type or mod), then the Purge Unused Lists button
will be enabled. Use this button to remove the unused Extended map lists, to
free up the space those lists are taking.

All game types have their own set of Extended map lists. When you install XMaps,
it will copy your Custom map lists from the built-in UnrealTournament game
types so that you have something to start with. If you want to create an
Extended map list from any map lists defined in UT, select it from the import
list and click the Import button. XMaps will create a new Extended map list
with which ever maps are currently in the UT list, ready for you to edit.

The combo box of map lists for each game type determines the map list that
XMaps uses for that game type, and also determines the map list that gets
edited when you use the Edit, Remove or Copy buttons. So, to edit an Extended
map list, select it from the combo box and click Edit. If you Remove all map
lists for a particular game type, the Edit, Remove and Copy buttons will be
disabled.

The combo box will offer you all Extended map lists that match the game type
selected. So, if you're setting up a mod that changes Capture The Flag, for
example, then any Extended map lists that support Capture The Flag will be
available. This means that you can choose mod-specific Extended map lists for
the unmodified game, and normal Extended map lists for the modified game.
Remember that the combo box includes all the suitable lists that are available -
you don't need to remove lists that are inappropriate for a particular game
type.

If you want XMaps to load a specific set of Mutators when it's using the
selected Extended map list, click the Mutators button and choose the Mutators
you want. The number of Mutators currently configured for the list is shown in
the button; for example, "Mutators [2]" indicates that there are two Mutators
that XMaps will load for the Extended map list. The Mutators you choose are
loaded in addition to any Mutators that you've configured for a game type or in
UnrealTournament's configuration.

When you run XMaps in either of the 'Extended Map List' modes of Map Selection,
it records the maps that get picked, so that random ordering can work
effectively. The maps are stored in a most-recently-used (MRU) list; if you
want to clear this list out and so start a 'clean' rotation of the maps in the
list, use the Clear MRU button. The Clear MRU button will be disabled if there
aren't any maps in the MRU.

To create a new list for any game type, click the New button. If all 100
Extended map lists are in use, the New button will be disabled.

To copy an existing list, click the Copy button. If all 100 Extended map lists
are in use, or you don't have an Extended list selected, the Copy button will
be disabled.

To import a map list from UnrealTournament, select it from the list and click
the Import button. If all 100 Extended map lists are in use, the Import button
will be disabled.

When editing or creating an Extended map list, you can change it's name at any
time. When you close the editing window, XMaps remembers it's name. The list
names are provided for your convenience, they aren't unique identifiers - in
other words, you can have any number of Extended map lists with the same name.

See 'Editing XMaps Map Lists' for details on the map list editing windows.

Remember that you need to set Map Selection in the Setup window to 'Extended
Map List, in order' or 'Extended Map List, random order' for XMaps to use these
lists.


===========================================
XMaps Game Options Window - Favourites Page
===========================================

The Favourites Page contains a slider to set how often a Favourite map gets
picked, and a button for editing the list of Favourites. The number of
Favourites for the game type selected is shown in the middle of the window; you
can have up to 150 Favourites for each game type, although XMaps can only store
a total of 100 Favourites lists at any one time. Favourites lists can be played
with both types of XMaps map selection, Extended and Random.

Below the Favourites button is a 'Map Prefix:...' button. This button shows the
map prefix that XMaps will use when you're playing Random games, and when you
edit the Favourites list. If the game type you're setting up is a built-in
UnrealTournament game type, then the button will be disabled. If the game type
is a mod, then you can specify the exact prefix that XMaps should use for it
when you set up Favourites or play Random XMaps games.

For example - when you play MultiCTF, the maps that support the mod properly
all have the prefix 'CTFM'. Normal Capture The Flag games use the prefix 'CTF',
and that's what XMaps would normally use when selecting Random maps and when
you set up Favourites, since that's what MultiCTF says it needs. However, you
may prefer to only play Random MultiCTF games with MultiCTF maps. In this case,
you'd click the Map Prefix:... button and change the prefix to 'CTFM'.

Note that the Map Prefix you choose only affects Random XMaps games and the
contents of your Favourites, NOT the Extended map lists.

Version 205 sees the introduction of the 'Only allow this prefix' option. When
this is on (i.e. the box is checked), then XMaps will only ever allow the exact
Map Prefix from the Map Prefix button to be used in Random XMaps games and
Favourites lists. You might use this feature to prevent, for example, MultiCTF
maps from being selected in a normal Capture the Flag game. By setting 'Only
allow this prefix' on, you're telling XMaps to only allow maps that start 'CTF-.
..', instead of maps that start 'CTF...'.

If you've uninstalled a game type or mod, then the Purge Unused Lists button
will be enabled. Use this button to remove any Favourites lists for the
uninstalled games, to free up the space those lists are taking.

See 'Editing XMaps Map Lists' for details on the map list editing windows.

Remember that you need to tick Use Favourites in the Setup window for XMaps to
use these lists.


===============================================
XMaps Game Options Window - Game Switching Page
===============================================

The Game Switching Page contains a slider to set how often XMaps should switch
game types, a Game Types button so you can choose which types of game or mod to
switch between, and a second slider which lets you set how long XMaps will wait
at the end of a game before switching to a new game type.

The Switch games slider has five possible settings which tells XMaps when to
switch game types. XMaps will choose a game type at random from the list you
set up using the Game Types button as follows:

    Slider value           XMaps' behaviour
    ------------           ----------------------------------------------------
    every game             switch to a different game type at the end of each
                           game
    every other game       play two games of the same type before switching to
                           a different game
    every 3 games or so    play about 3 games of the same type before switching
    every 4 games or so    play about 4 games of the same type before switching
    every 5 games or so    play about 5 games of the same type before switching

The last three options randomise the number of games played so things don't
feel too ordered when you're switching games. (To be specific, they randomise
between +1 and -1, so 'every 4 games or so' means every 3, 4 or 5 games.)

The Switch Games button gives you a list of all the Game Types and mods that
XMaps know about; set up the list to switch between in the same way as all the
other set-up lists in XMaps - double-click an item to move it from one list to
the other, or drag-and-drop an item from one list to the other.

The 'Restart game after' slider allows you to set just how long XMaps will wait
before switching game types, but only when it's controlling game switching. If
XMaps isn't set up to switch game types, then the game ends normally - UT has
control. If XMaps is going to switch games, then after the 'Restart game after'
pause, XMaps issues a five-second countdown before it kicks in and switches the
game over. You can disable the audible countdown using the checkbox at the
bottom of the Game Switching Page if you prefer.

Note that XMaps will use all your normal settings when it switches game types -
it's just as if you restarted UnrealTournament and selected a different game (
but a lot quicker). The only exception to this rule is at the end of the first
part of an Assault game. Normally, XMaps will not automatically switch game
types, so that you get the chance to play both the attacking and defending
parts of Assault. If you'd rather have XMaps switch games anyway, clear the "
Don't automatically switch games..." checkbox at the bottom of the Game
Switching Page.

Remember that you need to tick Switch Game Types in the Setup window for the
Game Switching settings to have any effect.


=========================================
XMaps Game Options Window - Mutators Page
=========================================

The Mutators page only contains one configuration control - the button that
opens the XMaps Mutators editing window. The number of Mutators that you've set
up in XMaps for the currently selected game type is shown underneath the button.

If you want XMaps to load some Mutators for a specific game type, click the Mutators
button and make your choices. When XMaps is running, it'll load the Mutators
you've selected if they're not already running. XMaps' Mutators list works in
addition to the list of Mutators you set up in UnrealTournament's Start Game
windows, so if there are any Mutators you want loaded in all game types (like
XMaps, for example ;-), then you may prefer to set them up there, and only add
game type-specific Mutators within XMaps.

If you also want to load some Mutators depending on the Extended map list that'
s running, set them up in the Extended Map Lists Page.

If you've uninstalled a game type or mod, then the Purge Unused Lists button
will be enabled. Use this button to remove any Mutator lists for the
uninstalled games, to free up the space those lists are taking.


=======================
Editing XMaps Map Lists
=======================

XMaps' map list editing windows are basically the same as the map list editor
that you get with UnrealTournament, but with a lot more 'knobs on'. The number
of maps in each list is shown, and you can only add as many maps as each list
supports.

If you want to add all the maps in the left-hand list to the right-hand list,
use the Add All button. If you want to remove all the maps from the right-hand
list, use the Remove All button.

To check out which map it is you're thinking of adding to the map lists, select
it and then click the Preview button underneath the list. XMaps will open a
Preview window to show you a shot of the map, if the map designer included one.
You can leave this Preview window open, move it where you like and resize it as
you see fit. XMaps will always open it in the same place for you.

If you have a PC that can handle it - and it doesn't take much - you may prefer
to set the Auto-preview option for the map lists. Then, whenever you click a
map in either of the lists, XMaps will show you a preview of it in the Preview
window. XMaps will close the Preview window when you close the map list editing
window.

The XMaps Map Preview window has a 'Preview on top' option. When checked, this
makes XMaps bring the Preview to the foreground whenever you Preview a map. If
you leave it unchecked, then the map list editing window stays in the
foreground ... it's up to you; just choose the behaviour you prefer.

XMaps also remembers the position and size of your map list editing windows, so
set them up with the Map Preview window in a convenient place, and browse your
map lists at leisure...


======================
XMaps In-Game HUD Menu
======================

XMaps supports an in-game HUD menu that you can use in stand-alone games to
switch game types, pick a map from any of your lists - Favourites or Extended -
for any game type, or change XMaps' Map Selection on the fly. You can also add
the map that's currently playing to your Favourites or any suitable Extended
map list. Since the menus can hold a lot of options, the menu scroll button can
be right-clicked as well as left-clicked. A right-click moves the menu by a
page, the left-click moves it by a single item.

To open the HUD menu, assign a key binding in UT's Preferences (see the 'XMaps
Mutate Commands and Key Bindings' section below). When the HUD menu opens, it
will pause the current game if you have configured it to do so (see the 'XMaps
Setup window' section above) so that you can browse the menu without worring
about getting killed ;-) Use the Escape key or the Close option (at the top
level of the menu) to close it.

The contents of the in-game HUD menu are shown below.

   ---------            ------------------------------------------------------
   Main Menu            Option Description
   ---------            ------------------------------------------------------
   Skip Map             Skips to the next map in your XMaps settings.
   Replay Map           Restarts the current game to replay the current map.
   Current Map List     Shows the contents of your Extended map list for the
                        current game type. Pick any map from the list, and
                        XMaps will load it. You can also add the current map
                        to the list.
   Favourites           Shows the contents of your Favourites list for the
                        current game type. Pick a map from the list, and XMaps
                        will load it. You can also add the current map to your
                        Favourites here.
   Matching Map Lists   Shows the names of all of your Extended map Lists for
                        the current game type, in alphabetical order. Pick
                        one, and the contents of the map list will be
                        displayed. Pick any map from the list, and XMaps will
                        load it. You can also add the current map to any of
                        the lists, and get XMaps to switch to any of the
                        lists (to change the running Extended map list).
   Game Types           Shows all the game types XMaps knows about from your
                        UT installation. Pick one to get to the Game Type
                        menu.
   Map Selection        Allows you to change the Map Selection mode that XMaps
                        is currently running in. This takes effect immediately
                        so the next map selected will be picked according to
                        the mode you select. The current mode is identified by
                        an (x) to it's left in the menu.


   ------------------   ------------------------------------------------------
   Game Type Menu       Option Description
   ------------------   ------------------------------------------------------
   Switch to...         Using this option will make XMaps switch to the
                        selected game type; XMaps will pick the next map from
                        your XMaps settings for the new game type and load it.
   <Map Lists>          XMaps shows the names of all the Extended map lists
                        for the game type selected, in alphabetical order.
                        Pick one, and the contents of the map list will be
                        displayed. Pickany map from the list, and XMaps will
                        switch to thecorrect game type and load the map you
                        selected.


Note that you can change the size of the font used in the HUD menu from Normal
to Large using the main Setup window (see the 'XMaps Setup Window' section
above).


======================================
XMaps Mutate Commands and Key Bindings
======================================

XMaps supports several commands that can be entered using the game console or
mini- console. Each command can be used while a map is already playing,
allowing you to find out which map you're playing, restart or skip the map, or
switch game types immediately. The commands are launched using the 'mutate'
instruction, but some can be launched using the key bindings that XMaps
supports. Select Options | Preferences from the UT menu, and select the
Controls tab in the dialog. You'll find an XMaps section where you can enter
the following bindings:

   Binding...                 ...is the same as...
   ----------                 ----------------------------------
   Open HUD Menu              mutate xmaps hudmenu
   Restart current level      mutate xmaps restart
   Show map name              mutate xmaps mapname
   Skip current level         mutate xmaps skip
   Switch game types          mutate xmaps switch

Alternatively, you can drop down the console or mini-console, and type one of
the following:

   Command                    Action
   -------                    -----------------------------------------------
   mutate xmaps restart       Restarts the current game.
   mutate xmaps mapname       Shows the name of the current map.
   mutate xmaps skip          Skips to the next map in your XMaps settings.
   mutate xmaps switch        Immediately switches game types according to
                              your XMaps settings.

There's also a series of XMaps mutate commands that are used by the in-game HUD
menu, but may turn out to be useful in their own right. Each of the commands
listed below must be preceded by "mutate xmaps" in the console or mini-console:

   Command                Action
   -------                ------------------------------------------------------
   gameonly <game>        Switches to the game class <game>. Note that this must
                          be a full class designation, for example:

                              mutate xmaps gameonly botpack.ctfgame

                          XMaps will pick the next map for the game type
                          according to your XMaps settings. XMaps assumes that
                          the <game>class designation you enter is valid.

   loadmap <map>          Loads the map <map>. For example:

                              mutate xmaps loadmap DM-Deck16][

                          XMaps assumes that the map is suitable for the game
                          type already playing. If it isn't, you should use
                          'fullmap'.

   fullmap <map>?<game>   Switches to the game class <game> and loads the map
                          <map>. The two designators must be seperated by '?'
                          for this to work. For example:

                            mutate xmaps fullmap CTF-Terra.unr?botpack.ctfgame

The commands aren't case-sensitive, so "Mutate XMaps SKIP" is the same as "
mutate xmaps skip". Note that the Unreal extension (.unr) doesn't need to be
present in the loadmap and fullmap commands.

Unlike automatic game switching, XMaps will abort an Assault game in either
part when you use the switch game types key binding or 'mutate' instruction.

Note that, if you're running a multiplayer game, you need to be an Admin user
to use the key bindings and/or mutate commands. If the game you're in is
running stand-alone, this won't happen, but if you're running a network game,
then XMaps makes sure you're 'allowed' to change the map or game type by
checking your Admin status.

For those of you who aren't familiar with the Admin user concept ... when you
start a network game, the Server tab gives you the chance to set up an Admin
password; this is the password you need to become recognised as the Admin User.
When the game is playing, you need to being down the console and enter the
command ADMINLOGIN password, where password is the Admin Password set up in the
Server tab. Then, you're the admin user and can do things like using XMaps to
switch the map or game type.

Or at least ... that's the way it used to be. Now, XMaps can enter the
ADMINLOGIN command for you if you set up the correct Admin password in the
Server Options window (see the 'XMaps Server Options Window' section above for
details).


===========================================
Uninstalling XMaps (Umod Installer Version)
===========================================

Open Add/Remove Programs from the Control Panel, select UnrealTournament and
click the Add/Remove button. Check the XMaps option in the list presented, then
click Next and remove the mod.


====================================================
Technical Notes - Using XMaps with Custom Game Types
====================================================

When a game starts, the Mutator (XMaps.Control) hijacks the map list type used
by the type of game you're playing (specifically DeathMatchPlus(Level.Game).
MapListType) in the call to Mutator.PostBeginPlay(). The Mutator sets up the
map list by calling Initialise() during this function; each of XMaps' map list
classes then override MapList.GetNextMap() to achieve extended list support,
random cycling or random map selection as necessary.

So, if you're playing a mod that overrides GetNextMap() from the standard
MapList class, it won't be called. It is, however, extremely unlikely that a
mod would need to override GetNextMap().

If you're putting together a mod and want to support XMaps, it's most likely
that it will work transparently - if you don't override GetNextMap(), XMaps
will do it's job alongside your mod. If you do need to override GetNextMap(),
you may wish to export the XMaps source and add your enhancements to the
GetNextMap() functions defined in each of the descendants of MapList there. If
you do, please check the 'Legal Bit' section towards the end of this file.


==========================================
Technical Notes - XMaps and Game-Switching
==========================================

To enable game switching, the XMaps mutator (XMaps.XmapsControl) jumps in
during the Mutator.HandleEndGame() call and sets DeathMatchPlus(Level.Game).
bDontRestart true so that it can handle the switch. This means that any Mutator
expecting to control restarts won't get control if XMaps is loaded first ...
similarly, if XMaps is loaded after a Mutator that traps the restart, it won't
be able to switch games.

Version 203 was the first release of XMaps to support game switching - if you
find there are any problems with XMaps 'co-operating' with another Mutator - or
vice-versa - let me know and I'll see if there's anything I can do about it.

Once thing I noticed during my testing, when XMaps was running on a dedicated
server, was that the game switching didn't work exactly as I expected if a
software firewall was preventing UT from accepting incoming connections. Once
the firewall was configured to let UT act as a server, everything worked fine ..
. if you get any similar problems, you may want to try this out.

There was also a problem in versions earlier than 206, where a dedicated server
INI file may be missing a MutatorList entry in a [UTMenu.UTStartGameCW] section
- or even missing the section altogether. In this case, if XMaps was loaded via
a command-line but then switched game types, it wouldn't reload itself (XMaps
uses the MutatorList key to set up the list of Mutators that should be loaded).
As of version 206, XMaps automatically adds itself to the game-start command to
make sure it re-loads if it was loaded by the server starter.


====================================================
Technical Notes - Upgrading from versions before 201
====================================================

Beginning with XMaps 201, XMaps matches game types by checking the name of the
game class (specifically DeathMatchPlus(Level.Game).Class). So, Extended and
Favourites lists for the mods XMaps used to support by name can only be
upgraded if the mod's game class is recognised by XMaps. Specifically, map
lists for the following mod versions will be upgraded automatically when
upgrading XMaps from versions earlier than 201:

   Conquest 1.21     (game type 'Conquest121.Conquest')
   DTF 0.1           (game type 'DominateTheFlagV01.DTFGame')
   Flag Domination   (game type 'FlagDom.FDGame')

Any Strike Force lists will automatically be removed by XMaps during the upgrade.


========================================
Technical Notes - XMaps and Map Prefixes
========================================

Beginning with XMaps 201, XMaps matches game types by checking the name of the
game class (specifically DeathMatchPlus(Level.Game).Class). The value is used
determine which Extended and/or Favourites list to use in the game.

When Map Selection is set to one of the Extended options, and no Extended map
list exists for the game type, XMaps searches for an Extended List that is
configured for the same map prefix as the game type that's playing and uses
that list.

When XMaps Selection is set to Random maps, XMaps uses the map prefix set in
the Favourites page of the Game Options window to determine which types of map
to load. If a prefix hasn't been set by the user, then XMaps uses the prefix
specified by the game.

If 'Use Favourites' is on, then the Favourites list for the game type that's
playing is used in addition to the Map Selection, if one exists.


===============
Release History
===============

Version 208
    o Increased the maximum number of maps in Extended and
      Favourite map lists to 150.
    o Increased the number of Extended and Favourite map lists
      that XMaps supports from 64 to 100.
    o Changed the HUD menu to pause the game while it's open.
    o Enhanced the HUD menu so that it can be closed using the
      Escape key or the Close button.
    o Enhanced the HUD menu to take account of the user's HUD
      preferences when opening or closing.
    o Changed the HUD menu map list sub-menus to sort their
      contents in alphabetical order.

Version 207
    o Greatly improved the handling of Assault games during game
      switching. XMaps' behaviour when you terminate an Assault
      game using the HUD menu or Mutate commands to switch games is
      now the same as UT. When automatic game switching kicks in
      after the first part of an Assault game, it's behaviour is
      configurable by the user.
    o Added an 'Import' button and list of UT map lists to the
      Extended Map Lists page. Any map list known to UT can now be
      imported into XMaps.
    o Added a number of commands to the HUD menu, and customised the
      textures to indicate sub-menu items.
    o Fixed the bug in Extended and Favourites map list storage where
      the fiftieth list got the settings of the fourtieth (and vice
      versa).
    o Fixed the Replay bug in the HUD menu (used to Skip instead of
      Replay).
    o Added a 'Copy' button to the Extended Map Lists page.
    o Added a 'Clear MRU' button to the Extended Map Lists page.
    o Increased the number of maps that Extended map lists and Favourites
      can hold from 64 to 128.
    o Increased the number of games that users can switch between to match
      the number of game types that XMapsGameInfo can support.
    o Increased the number of game-to-map-list settings that users can
      configure to match the number of game types that XMapsGameInfo can
      support.
    o Expanded the Mutator list support to match the number of game-types
      that XMaps supports.
    o Changed the game- and map-switching routines to restore the user's
      configuration of minimum players and/or bots. XMaps only used to
      do this at the end of a game (which doesn't happen when the map-
      and game-switching commands are used).
    o Fixed the bug where the wrong index was being saved for Favourites
      lists.

Version 206
    o Introduced the in-game HUD menu, with a key-binding for access and
      a 'large font' control in the Setup window.
    o Made XMaps add itself to the list of mutators automatically loaded
      when it switches game types. This solves the problem that occurs when
      a dedicated server INI file doesn't contain a mutator configuration,
      but XMaps is launched in the first game using the command line.

Version 205
    o Introduced 'Only allow this prefix' for Favourites and Random Map
      selection, so that users can set up completely mod-specific games.
    o Added a 'Disable announcer countdown' for those users who don't like
      the audible restart countdown.
    o Introduced Mutate strings and support for key bindings via the UT
      Preferences menu.
    o Changed game switching to check for Part 1 of an Assault game. If such
      a game ends, XMaps will not automatically switch game types, so that
      the second half of the game can be played.
    o Changed game switching to check whether the user has set up XMaps for
      a game type (e.g. an Extended map list). If not, XMaps chooses a map
      at random for the game type. This is one solution for switching to
      unconfigured game types ... it prevents XMaps from switching into a
      game type with the wrong type of map.
    o Changed the delimiter used for storing game info from '/' to '?'. This
      fixes the problems XMaps experiences caused by Game Types with '/' in
      their name (e.g. CTF/E).

Version 204
    o Increased the number of Game Types that XMaps stored from 64 to 256,
      and the number of maps read (when selecting at random) to 1,536.

Version 203
    o Implemented Game Switching in the Mutator and Setup windows.
    o Changed the Setup window to support Map selection and seperate 'Use
      Favourites' controls.
    o Added Purge Unused Lists buttons to the Favourites and Mutators setup
      windows.
    o Introduced XMaps' caching of Game Types data to reduce the load time
      of the Game Options window from about 90 seconds to 2 seconds. Nice.
    o Introduced the 'Preview on top' option to control the 202 behaviour.

Version 202
    o Changed the Map Preview window to always come to the foreground when
      a different map is previewed (for Scott).

Version 201
    o Added 'save position and size' for all Setup windows.
    o Added an 'Auto-preview' capability to the map list editing windows.
    o Added 'Auto-open Game Options' to the Game Options window.
    o Added the ability to change the map prefix that XMaps uses for Random
      games and Favourite map lists. This is only enabled for game types that
      do not ship with UnrealTournament.
    o Added Add All and Remove All buttons to the map list editing windows.
    o Added Map Preview capability to the map list editing windows.
    o Added XMaps.Install Version strings in the uMod wizard to get around
      the delay loading the XMaps setup windows when there aren't any INI
      files to read. These strings only extend existing files, so XMaps
      setup won't be overwritten if it's an upgrade.
    o Added an XMaps Selection of 'Extended - random cycling with Favourites'.
    o Added map counts to the map list editing windows.
    o Added a Mutators page to the Game Options window.
    o Made Favourites instances of XMapsList instead of the normal MapList,
      so 64 Favourites can now be configured.
    o Changed the Favourites setup window to support any game or mod that
      the user has installed.
    o Increased the number of Extended map lists from 48 to 64.
    o Changed the Extended Maps setup window to support any game or mod that
      the user has installed.
    o Split the Setup window into two parts (XMaps Setup and Game Options).
    o Added an XMaps Selection of 'None', so that users can get Match
      Players functionality without using Extended or Random XMaps map
      selection.
    o Added routines to balance the number of players in team games even when
      an ideal number of players is not specified by the map designer.

Version 109
    o Fixed the problem where XMaps tries to generate too many bots when a map
      designer uses the text "8 to 12" (for example) instead of "8 - 12", which
      is what XMaps expects.
    o Improved the random cycling of Extended map lists to take into account the
      map chosen by the user in the Start Game windows.
    o Improved the random map MRU to include maps chosen by the user when
      starting a game (the only time XMaps doesn't choose the map). This will
      stop XMaps picking that map again too soon.
    o Fixed the (annoying) problem where XMaps prevented the animation of a
      player's final frag when (a) the game has a frag limit and (b) the player
      is the winner.
    o Increased the number of random maps that XMaps reads from 512 to 1,024.
    o Added better support for 'Match Players' in MultiCTF.
    o Fixed the bug where 'Match Players' could generate uneven teams in team
      games.

Version 106
    o Added the ability to match the number of players in a game to the
      number recommended by the map designer.
    o Made XMaps automatically switch on 'Auto Change Levels' when it starts up.

Version 103
    o Improved support for Extended and Favourite lists of Strike Force
      maps.
    o Fixed the bug that caused Conquer, Dominate the Flag, Flag Domination
      and Strike Force Favourite lists to be ignored during 'Random - with
      Favourites' games.

Version 102
    o Added support for Conquer, Dominate the Flag, Flag Domination
      and Strike Force maps.
    o Added game type matching by map prefix instead of map list class.

Version 100
    o Initial release.


=======================
Sincere thanks go to...
=======================

*** MeltDown [meltdown@thirdtower.demon.nl]

    XMaps is built using UClasses 2.8.0. - check out Meltdown's pages at
    http://www.planetunreal.com/unrealtower.

*** E. Bruce Shankle III [bruce@epicgames.com]

    UnDox has to be the most useful UnrealScript documentation available. Using
    this automatic HTML-generating source tool, I was able to learn enough
    about the UnrealTournament user interface source to create XMaps'
    configuration windows. If you're contemplating working with UnrealScript,
    this is an absolute must-have. Check out the pages at http://www.
    planetunreal.com/undox/.

*** Ob1-Kenobi [ob1@planetunreal.com]

    The umod for the Mutator was created entirely using Ob1's umod Wizard, v1.
    26. Made my life easier, and yours too! The program can be downloaded from
    PlanetUnreal (http://www.planetunreal.com, as if you didn't know).

*** {AGUT}SDJ

    For coming up with a few important implementation ideas...

*** Scott Arnold

    For patiently and graciously letting me know which parts of XMaps needed
    improving, and testing out preview releases and bug fixes.

*** Andrew McDonald

    For important implementation ideas and invaluable testing effort.

*** Mental [http://planetunreal.com/mutationstation/]

    For testing out the change to map prefix matching.

*** Myrmecophagavir [http://www.geocities.com/myrmecophagavir]

    For coming up with the idea for 'Match players' and testing the results.

*** Doug Gibson and Peter Yu [http://www.planetunreal.com/modsquad]

    For the inspirational idea of the in-game HUD menu.

*** Bruce Bickar [http://www.planetunreal.com/BDBUnreal]

    For pointing me to the WRI used in MapVote for a networking model, and
    giving me the OK to use MapVote code if I need to.

*** Everyone on the XMaps mailing list...

    ... for their support and a seemingly endless stream of ideas for XMaps.
    Special thanks go to (in alphabetical order !) Lee Brink, Chris DeFrancisco,
    Brad Ford, Brian Latimer, Pedro Roque and Joseph Stanczak.


If you're looking into Mutator development yourself, take the time to check out
the Mutators forum over at mod central: http://unreal.infopop.net/.

And finally ... the biggest thanks of all go to Mary (once again). She still
has the patience of a saint ... well, if you've read this far, you must be a
readme-addict like me. At the risk of turning XMaps.txt into a soap opera, I'm
very happy to be able to tell you that we're now engaged to be married ... how
lucky can a guy get!?!


===============
Contact Details
===============

If you have any suggestions for XMaps, find something that doesn't work the way
you'd expect, or just want to drop me a line, send email to touchstone@
planetunreal.com.

My web site, G-Web, is at http://www.zen.co.uk/home/page/graham.thompson/gweb/.
You can find information about XMaps (and the Map Randomizer) by selecting the
links at the bottom of the menu on the left of the main page. The latest
version of XMaps will always be available from those pages. There are also
pages describing the contents of the XMaps INI files, and the beginnings of a
FAQ (which I hope to expand over time).

XMaps has been invited to join PlanetUnreal as a hosted site ... but it'll take
me a while to put the pages together and complete the site move.

When the move is complete, all the XMaps links in G-Web will still work, but
they'll send you to the XMaps site on PlanetUnreal. XMaps news will still be
available on G-Web, but the downloads and information will all be on
PlanetUnreal. Keep an eye on G-Web and the main PlanetUnreal page
(http://www.planetunreal.com) for the move...


=========
Legal Bit
=========

UnrealTournament (c)1999 Epic Megagames, Inc. All Rights Reserved. Distributed
by GT Interactive Software, Inc. under license.  UnrealTournament and the
UnrealTournament logo are registered trademarks of Epic Megagames, Inc. All
other trademarks and trade names are properties of their respective owners.

All of the contents of this package are created and owned by TouchStone subject
to the caveats mentioned above. You are allowed to use, copy or modify the code,
on the condition that no profit is made from the distribution of the resulting
package(s).

If you copy or modify the code, or any part of it, please email me, and give me
some credit for the hours spent sweating over an ash-stained keyboard.


=================================================================================
XMaps 208                                                               XMaps.txt
=================================================================================

