quickstart.txt

I. Quickstart
==========

1. Copy necessary files

    - copy the `.u` files into to the `System/` folder

    - copy the `.int` file also into the `System/` folder

    - copy the configuration `.ini` file:
        - on Windows this is the `System/` folder
        - on Linux `~/.utpg/System` unless `-nohomedir` is specified

2. Add the client package to ServerPackages inside UnrealTournament.ini:

    ServerPackages=MVE2dev

3. Start your server with the mapvote mutator from a command line:

    ucc server DM-Deck16][?Mutator=MVES.MapVote

OR install as a server actor:

    ServerActors=MVES.MapVote

OR add it to LocalMap:

    LocalMap=DM-Fractal?Mutator=MVES.MapVote

OR add as mutator from the GUI:
    - from Practice Session 
    - from Start New Multiplayer Game

4. Join the server with a client. Whenever you want the map list to be 
updated you need to run the reload command the reload command will re-scan 
paths for maps and will match them against filters:

    adminlogin yoursecretpassword
    mutate bdbmapvote reload

5. Now you should be able to bring up the mapvote vote window either by 
typing `!v` in chat or `mutate bdbmapvote votemenu` in console. If everything 
went well you'll have a default starter setup with some gametypes and maps.

If things did not go well and mapvote window is not showing up or the map
lists are empty then skip down below to troubleshooting.

Mapvote can take control over settings like FragLimit and TickRate. You will 
need to configure the settings that you want for your server. To get started 
with configuration skip down below to the configuration section.


II. Updating
============

When updating from older version mapvote to a newer one, start by making a 
backup so that you can roll back if something goes wrong. You should at least 
back up MVE_Config.ini and UnrealTournament.ini

1. Copy necessary files

    - copy the `.u` files into to the `System/` folder

2. Update the client package to ServerPackages inside UnrealTournament.ini:

    ServerPackages=MVE2dev

The new version will pick up the existing MVE_Config configuration but it may 
also add new options to the configuration. These would show up at the end of 
each ini section and you may want to re-arrange to keep the config nice and clean.

Please refer to the provided changelog to see what changed.


III. Troubleshooting
====================


1. Map vote window does not show up:

    A. Check for `[MVE] Map Vote Extended version:` in the server log. If you do
    not see this log then the server component of mapvote did not start. Check 
    your server startup script and make sure it contains `?Mutator=MVES.MapVote`

    B. Check that ServerPackages from UnrealTournament.ini contains MVE2dev.
    This package contains the vote window. If it's missing then clients will 
    not download and are not able to display the mapvote window in game.

    C. Do or did you have another mapvote? It's possible that some part of it
    is still active and that it's blocking some functionality of this mapvote. 
    Make sure that the other mapvote doesn't start. 
    Try installing MVE to a clean version of UT99 


2. Map vote window shows up but it's empty:

    A. Did you copy the `MVE_Config.ini`? If you did not then you'll start
    with an empty config without any map filters. This also an okay way to start
    you can copy parts from the `MVE_Config.ini` provided in the zip.

    B. Is `MVE_Config.ini` is in the right place? It's possible that it's not
    getting loaded. Try setting `bReloadOnNextRun=True` and run the server again
    The next run should set `bReloadOnNextRun` back to `False` if it doesn't then
    you're editing the wrong configuration file.

    C. Double check your map filters. Use the example config file from the zip
    file should at least match all maps starting with DM-* and those should be 
    visible. Run `mutate bdbmapvote reload` this will re-scan your disk and it 
    also print any errors to the server log. Check the server log for errors
    MVE will print out configuration problems found during map list reload.


3. When joining the game players have wrong skin/texture:

    A. Is `bOverrideServerPackages` inside `MVE_Config.ini` set to `True`?
    This changes how ServerPackages are managed, only enable it if you 
    understand what it does, for troubleshooting purposes disable it first
    by setting it to `bOverrideServerPackages=False`

    B. In `UnrealTournament.ini` verify that your `ServerPackages` are correcly
    set up. If they are not players will not be able to use even the stok skins.
    Restore this configuration from a stock install of UT99 if needed to.


4. Map vote is crash looping trying to switch to map

    A. The most likely cause that triggers this is a missing map or missing 
    packages. Please investigate the server log for problems. Delete the 
    `MVE_Travel.ini` to reset mapvote's state.


IV. Additional Support
======================

If the above did not work you can reach out to the community. 
You can report bugs or ask for help in the thread:

https://ut99.org/viewtopic.php?t=15657

Or ask in the ut99.org discord inside the #ut-server-help channel

https://discord.com/invite/6CP2UjZ


V. Configuration
================

To make good use of this mapvote you need to edit `MVE_Config.ini` You will 
need to learn how to use the config file. This can only be done through 
experiment and practice. 

Mapvote set FragLimit, TickRate and just about any other setting a gametype
has. It can also load extra mutators and extra server actors. You will also 
need to manage map lists so that your mapvote is populated with maps.

Always make small changes and test it.

Make a backup copy once you have good stable settings.

Please refer to the provided manual for more configration options it goes more
in depth into some subjects and contains configuration snippets and examples.


1. Adding More Maps


New maps you add to the game are not automatically detected. 

If you add a new map then you need to reload the map list.
If you do not reload, the same old map list is sent to the players.
The classic way is running the `mutate bdbmapvote reload` command.
To run it you need to be logged in as admin.

    adminlogin yoursecretpassword
    mutate bdbmapvote reload

Alternatively a reload can be triggered from the config file MVE_Config.ini 
This is useful so that you can reload the map list without entering the game.

    bReloadOnNextRun=True

It can also be done from the admin tab when logged in as admin inside the 
mapvote window.


2. Adding Custom Gametypes


New game types are not automatically detected.
You need to edit MVE_Config and define the new gametypes. 
The easiest way is to copy paste an existing one and edit it.

To set up a different gametype you need to set the correct GameClass.
For CTF4 this could be GameClass="CTF4.CTF4Game" but depends on which CTF4 you're using

Here is the modified gametype below

    CustomGame[4]=(bEnabled=True,GameClass="CTF4.CTF4Game",...)

If you make a change then again you need to reload the map list.
If you do not reload then the same old games list is sent to players.


3. Useful Keybinds


I recommend setting up 3 keybinds. These are optional you can do everything
without them, but it speeds things up a bit.

    set input f8 mutate bdbmapvote votemenu
    set input f9 adminlogin yoursecretpassword
    set input f10 mutate bdbmapvote reload

Now press the f9 key and then press f10 key to quickly reload the map list 
when you install or remove maps.

You can also press f8 to bring up the vote menu in game at any moment without
having to wait for the match to end.

You can ofcourse choose different keys to bind to.

Note: if you logged in as admin, you can force a map swicth!


4. Advanced Tip & Tricks


- If bOverrideServerPackages=True then MapVote will manage ServerPackages for
you and will automatically add the user interface package MVE2dev to ServerPackages
By default bOverrideServerPackages=False because this is more work to set up 
corectly. It will also allow you to configure ServerPackages separately for 
every custom gametype you set up. This is a good optimization if to only make
client download the packages needed for the currently playing gametype.


- MapVote can be installed both in mutator or server actor mode. When run as a
server actor mapvote will run in special "background" mode until the first map 
is voted. This is a choice for you to use whichever mode is more comfortable 
working with. Here are some ways you can run MapVote:

    1) as server actor, edit UnrealTournament.ini add the following:

    [Engine.GameEngine]
    ServerActors=MVES.MapVote

    1) as server mutator start the server with the following:
    
    ucc server DM-Agony?mutator=MVES.MapVote

    2) single player / standalone you can run the game with arguments:

    UnrealTournament.exe CityIntro?mutator=MVES.MapVote -log


- The installation package should come with a MVE_Config.ini file. This is 
provided as a convenience of good defaults and a baseline configuration. If
you feel lost or misconfigured something, you can use it as a reference to 
set things back to good defaults. If you already have a configuration file 
make sure you don't override it when installing updates. It's also a good 
practice to keep backups of this file or to put it under version control.


- If you use Notepad++ to edit your configuration files then we have a 
user defined language configuration for MVE_Config.ini which has better 
delimitation of key-values, brackets and parenthesis and it also identifies 
known mapvote configuration properties. To install it, go to the menu
Language > User Defined Language > Define your language... and then
import `Map Vote Extended Notepad++.xml`


Good luck!