=======================================================================================
XMaps 205                                                                     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 64
maps per list and 64 custom lists that can be used for any game type or mod. XMaps also
supports Mutator lists that can be set up for 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 64 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.

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 A Decent Setup Window
    ---------------------

    XMaps has an advanced 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 64 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 64 'Extended' Custom Map Lists
    ------------------------------

    'Extended' map lists are the real advance in XMaps - and there are 64 of them
    that you can assign to any game type or mod. The lists are 'extended' because
    they'll hold up to 64 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.


  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 Load Different Mutators in Different Game Types
    -----------------------------------------------

    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.


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, 11th March 2001.


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

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

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 the first time. 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).


=================================
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 two parts - the Setup window that configures the way XMaps picks
maps, and the Game Options window where you set up 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 categories - Map Selection, Game Switching and Player Matching,
all described below.

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, then tick the 'Auto-open Game Options window' check-box in
the Game Options window.

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 the Player Matching or Game Switching features of XMaps, 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 - 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 will not automatically switch game types at the end of the first
part of an Assault game.

See 'Game Switching Page' for details on how to choose the game types and set how
often XMaps will switch. See 'Mutators Page' for details on setting up 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 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 split into two parts - the list of
Game Types installed, 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, XMaps 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 64 lists can be created - the number in use is shown in the middle of the window.
If you use all 64, 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 you've uninstalled a game type or mod, then the Purge Unused Lists button will be
enabled. Use this button to remove any Extended Map Lists for the uninstalled games,
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 UnrealTournament so that you have something to
start with.

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 or Remove 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 button
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.

To create a new list for any game type, click the New button. If all 64 Extended map
lists are in use, the New 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 64 Favourites
for each game type. Favourites lists can be played with both types of XMaps map
selection, Extended and Random.

At the bottom of the window 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 in Random games, 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 time to switch. If XMaps isn't going to
switch game types, then the game ends normally - UT has control. If XMaps is going to
switch games, then when it's ready, XMaps issues a five-second countdown before it
kicks in and switches the game over.

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. Also note
that XMaps will not automatically switch game types at the end of the first part of
an Assault game.

Remember that you need to tick Switch Game Types in the Setup window for XMaps to
automatically switch game types.


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

The Mutators page only contains one 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'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 Mutate Commands and Key Bindings
======================================
                  
XMaps supports four 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 ... 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.

The commands aren't case-sensitive, so "Mutate XMaps SKIP" is the same as "mutate xmaps
skip".

To make using these commands a bit easier, XMaps has key bindings that you can configure
using the UnrealTournament Preferences dialog. 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 keys you want to use for the Mutate commands.
                  
   Binding...                ...is the same as...
   ----------                ----------------------------------
   Restart current level     mutate xmaps restart
   Show map name             mutate xmaps mapname
   Skip current level        mutate xmaps skip
   Switch game types         mutate xmaps switch

Unlike automatic game switching, XMaps will abort an Assault game in either part.


==================
Uninstalling XMaps
==================

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.

This is 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 XMaps act as a server, everything worked fine ... if you get any similar problems,
you may want to try this out.


====================================================
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 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:

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

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.

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@zen.co.uk.

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.

At the time of writing (11th March, 2001), XMaps has been invited to join PlanetUnreal
as a hosted site ... 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) ... I should be launching soon!


=========
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 205                                                                     XMaps.txt
=======================================================================================
