UT2004Match (ut2004-tournament 3.8.1-SNAPSHOT API)

java.lang.Object
- cz.cuni.amis.pogamut.ut2004.tournament.match.UT2004Match<CONFIG,RESULT>

All Implemented Interfaces:

Runnable, Callable<RESULT>

Direct Known Subclasses:

UT2004CaptureTheFlag, UT2004DeathMatch, UT2004TeamDeathMatch
```
public abstract class UT2004Match<CONFIG extends UT2004MatchConfig,RESULT extends UT2004MatchResult>
extends Object
implements Callable<RESULT>, Runnable
```
This class serves as a gateway for creating various matches using custom bots.
The class is sought to be inherited and its abstract method be additionally defined.
It also defines may handful methods that can be used to create required GameBots2004.ini file, start UCC, start all bots with observers / change their team / restart match.

Author:

Jimmy

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class UT2004Match.Bots

Nested Classes
Modifier and Type	Class and Description
`static class`	`UT2004Match.Bots`

Field Summary

Fields
Modifier and Type	Field and Description
`protected CONFIG`	`config` Configuration of the match, it contains all information that is needed to start the match.
`protected Throwable`	`exception`
`protected cz.cuni.amis.pogamut.base.utils.logging.LogHandler`	`fileHandler`
`protected File`	`gb2004FileBackup` Where we have backed up the GB2004.ini file...
`protected cz.cuni.amis.pogamut.base.utils.logging.LogCategory`	`log`
`protected RESULT`	`result`
`protected boolean`	`teamMatch`
`protected File`	`ut2004FileBackup` Where we have backed up the UT2004.ini file...

Constructor Summary

Constructors
Constructor and Description
`UT2004Match(boolean teamMatch, CONFIG config, cz.cuni.amis.pogamut.base.utils.logging.LogCategory log)` Construct the match with provided configuration.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`RESULT`	`call()`
`void`	`cleanUp()` WARNING: this method will delete the whole directory where results are stored!
`protected void`	`closeLogger()` Usually STEP 14 that close logging to file.
`protected void`	`copyReplay(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, String fileName, File outputDirectory)` Optional (usually) STEP 11 ... moves replay file to desired directory.
`protected void`	`createGB2004Ini()` Usually STEP 2.2 ... it overwrites the GameBots2004.ini file that is present in UT2004 home.
`protected void`	`createUT2004Ini()` Usually STEP 2.2 ... it overwrites the GameBots2004.ini file that is present in UT2004 home.
`protected abstract RESULT`	`execute()` Performs the match and return the result (or throw an exception in case of error).
`CONFIG`	`getConfig()` Returns configuration of the match.
`static String`	`getCurrentDate()` May be used for file names.
`Throwable`	`getException()` If exception occures during the match execution, it is stored and made available through this method.
`protected File`	`getGB2004IniFile()` Returns file that is pointing to GameBots2004.ini that will be used by ucc.exe.
`cz.cuni.amis.pogamut.base.utils.logging.LogCategory`	`getLog()` Returns logger used for outputting stuff.
`cz.cuni.amis.utils.token.IToken`	`getMatchId()` Returns ID of the match.
`File`	`getOutputPath()` Parent path of all files that should be output by the class as results.
`File`	`getOutputPath(String relativePath)` Returns path relative to `getOutputPath()`.
`RESULT`	`getResult()` Returns result of the match (if it was performed by either calling `run()` or `call()`).
`protected File`	`getUccHome()` Returns file that is pointing to a directory that contains ucc.exe.
`protected File`	`getUT2004IniFile()` Returns file that is pointing to GameBots2004.ini that will be used by ucc.exe.
`protected void`	`changeBotTeam(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, cz.cuni.amis.pogamut.unreal.communication.messages.UnrealId botId, int desiredTeam)`
`static boolean`	`isHumanPlayer(cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Player player)`
`boolean`	`isTeamMatch()` Whether team / individuals are fighting in this match.
`protected void`	`matchIsAboutToBegin(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer, UT2004Match.Bots bots)` Optional (usually) STEP 7 ... set up any listeners needed.
`protected abstract void`	`outputResults(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer, UT2004Match.Bots bots, UT2004MatchResult result, File outputDirectory)` Usually STEP 12 ... concludes the match by producing/presenting whatever statistics needed about the match.
`protected void`	`recordReplay(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, String fileName)` Optional (usually) STEP 9 ... begin recording UT2004 replay
`protected void`	`restartMatch(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, UT2004Match.Bots bots)` Usually STEP 8 ... restarts the match (in order to reinitialize the environment and restart all bots).
`void`	`restoreGB2004IniBackup()` Usually STEP 10.2 Overwrites current GameBots2004.ini with GameBots2004.ini.backup that was created during `createGB2004Ini()`.
`void`	`restoreUT2004IniBackup()` Usually STEP 10.1 Overwrites current UT2004.ini with UT2004.ini.backup that was created during `createUT2004Ini()`.
`void`	`run()` Runs the match, its result is than available through `getResult()`.
`protected void`	`setupLogger()` Usually STEP 0 that set up logger to output to file.
`protected void`	`shutdownAll(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer, UT2004Match.Bots bots)` Usually STEP 13 ... shutdowns everything
`protected cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer`	`startAnalyzer(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, UT2004Match.Bots bots, File outputDirectory, boolean humanLikeObserving)` Optional (usually) STEP 6 ... it is nice to collect some data about bots, that is done by the analyzer that automatically observe any custom-bot.
`protected UT2004Match.Bots`	`startBots(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server)` Usually STEP 5.1 ... starts all custom & native bots + changes their teams if needed.
`protected cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server`	`startControlServer(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc)` Usually STEP 4 ... after the UCC has started up, you usually want to connect to it to confirm it is up and running and be able to observe any changes in the environment / alter the environment, etc.
`protected cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper`	`startUCC()` Usually STEP 3 ... it starts up the UCC, it is a blocking method that waits until UCC is up and running.
`String`	`toString()`
`void`	`validate()` Usually STEP 1 in match execution ... it validates the contents of `config`.
`protected void`	`waitHumanPlayers(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, UT2004Match.Bots bots)` Usually STEP 5.2 ... wait till all human players gets connected to the game.
`protected abstract UT2004MatchResult`	`waitMatchFinish(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc, cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server, cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer, UT2004Match.Bots bots, long timeoutInMillis)` Usually STEP 10 ... you wait for a predefined time (blocking method) for the match to finish.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - config
```
protected CONFIG extends UT2004MatchConfig config
```
    Configuration of the match, it contains all information that is needed to start the match.
  - log
```
protected cz.cuni.amis.pogamut.base.utils.logging.LogCategory log
```
  - result
```
protected RESULT extends UT2004MatchResult result
```
  - exception
```
protected Throwable exception
```
  - teamMatch
```
protected boolean teamMatch
```
  - fileHandler
```
protected cz.cuni.amis.pogamut.base.utils.logging.LogHandler fileHandler
```
  - ut2004FileBackup
```
protected File ut2004FileBackup
```
    Where we have backed up the UT2004.ini file...
  - gb2004FileBackup
```
protected File gb2004FileBackup
```
    Where we have backed up the GB2004.ini file...
- Constructor Detail
  - UT2004Match
```
public UT2004Match(boolean teamMatch,
                   CONFIG config,
                   cz.cuni.amis.pogamut.base.utils.logging.LogCategory log)
```
    Construct the match with provided configuration.
    
    Parameters:
    
    config - MUST NOT BE NULL
- Method Detail
  - isTeamMatch
```
public boolean isTeamMatch()
```
    Whether team / individuals are fighting in this match.
    True == team match, False = match of individual bots.
    
    Returns:
  - isHumanPlayer
```
public static boolean isHumanPlayer(cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Player player)
```
  - getResult
```
public RESULT getResult()
```
    Returns result of the match (if it was performed by either calling run() or call()).
  - getException
```
public Throwable getException()
```
    If exception occures during the match execution, it is stored and made available through this method.
    
    Returns:
  - run
```
public void run()
```
    Runs the match, its result is than available through getResult().
    
    Specified by:
    
    run in interface Runnable
  - call
```
public RESULT call()
```
    Specified by:
    
    call in interface Callable<RESULT extends UT2004MatchResult>
  - execute
```
protected abstract RESULT execute()
```
    Performs the match and return the result (or throw an exception in case of error).
    It is called by run() that is used by call().
    
    Returns:
  - getCurrentDate
```
public static String getCurrentDate()
```
    May be used for file names.
    
    Returns:
  - getConfig
```
public CONFIG getConfig()
```
    Returns configuration of the match.
    
    Returns:
  - getMatchId
```
public cz.cuni.amis.utils.token.IToken getMatchId()
```
    Returns ID of the match.
    
    Returns:
  - getLog
```
public cz.cuni.amis.pogamut.base.utils.logging.LogCategory getLog()
```
    Returns logger used for outputting stuff.
    
    Returns:
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getOutputPath
```
public File getOutputPath()
```
    Parent path of all files that should be output by the class as results.
    
    Returns:
  - getOutputPath
```
public File getOutputPath(String relativePath)
```
    Returns path relative to getOutputPath().
    
    Parameters:
    
    relativePath -
    
    Returns:
  - setupLogger
```
protected void setupLogger()
```
    Usually STEP 0 that set up logger to output to file.
  - validate
```
public void validate()
```
    Usually STEP 1 in match execution ... it validates the contents of config.
    Raises exception in case of error.
    As it is public, you may also use it prior the match execution by yourself to ensure that the match is correctly configured.
  - cleanUp
```
public void cleanUp()
```
    WARNING: this method will delete the whole directory where results are stored! IT WILL DELETE IT COMPLETELY! DO NOT USE IT ON A WHIM... be sure you're using separate directories for all matches.
  - getUccHome
```
protected File getUccHome()
```
    Returns file that is pointing to a directory that contains ucc.exe.
    
    Returns:
  - getUT2004IniFile
```
protected File getUT2004IniFile()
```
    Returns file that is pointing to GameBots2004.ini that will be used by ucc.exe.
    
    Returns:
  - getGB2004IniFile
```
protected File getGB2004IniFile()
```
    Returns file that is pointing to GameBots2004.ini that will be used by ucc.exe.
    
    Returns:
  - createUT2004Ini
```
protected void createUT2004Ini()
```
    Usually STEP 2.2 ... it overwrites the GameBots2004.ini file that is present in UT2004 home.
    Raises exception in case of any error.
  - createGB2004Ini
```
protected void createGB2004Ini()
```
    Usually STEP 2.2 ... it overwrites the GameBots2004.ini file that is present in UT2004 home.
    Raises exception in case of any error.
  - startUCC
```
protected cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper startUCC()
```
    Usually STEP 3 ... it starts up the UCC, it is a blocking method that waits until UCC is up and running.
    Raises exception in case of any error.
    
    Returns:
    
    started wrapper of the ucc process
  - startControlServer
```
protected cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server startControlServer(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc)
```
    Usually STEP 4 ... after the UCC has started up, you usually want to connect to it to confirm it is up and running and be able to observe any changes in the environment / alter the environment, etc.
    This method may need to be override to provide custom implementation of UT2004Server interface, i.e., provide your custom control server. Current implementation is using UT2004Server.
    Raises exception in case of any error.
    If UT2004MatchConfig.isStartTCServer() it will start UT2004TCServer instead of plain UT2004Server.
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    Returns:
    
    running control server
  - changeBotTeam
```
protected void changeBotTeam(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                             cz.cuni.amis.pogamut.unreal.communication.messages.UnrealId botId,
                             int desiredTeam)
```
  - startBots
```
protected UT2004Match.Bots startBots(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                                     cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server)
```
    Usually STEP 5.1 ... starts all custom & native bots + changes their teams if needed.
    Raises exception in case of any error.
    Note that the inner implementation is pretty complex... if you need to alter the method, copy-paste it and dig in.
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    server - MUST NOT BE NULL
    
    analyzer - may be NULL
    
    Returns:
    
    context of bot executions
  - waitHumanPlayers
```
protected void waitHumanPlayers(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                                UT2004Match.Bots bots)
```
    Usually STEP 5.2 ... wait till all human players gets connected to the game.
    Raises exception in case of any error.
    Note that the inner implementation is pretty complex... if you need to alter the method, copy-paste it and dig in.
    
    Parameters:
    
    server - MUST NOT BE NULL
  - startAnalyzer
```
protected cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer startAnalyzer(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                                                                            UT2004Match.Bots bots,
                                                                            File outputDirectory,
                                                                            boolean humanLikeObserving)
```
    Optional (usually) STEP 6 ... it is nice to collect some data about bots, that is done by the analyzer that automatically observe any custom-bot.
    This method may need to be override to provide custom implementation of UT2004Analyzer interface, i.e., provide your custom control server. Current implementation is using UT2004Analyzer.
    Fills data UT2004Match.Bots.botObservers.
    Raises exception in case of any error.
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    bots -
    
    outputDirectory - where to output data about bots, MUST NOT BE NULL
    
    humanLikeObserving - whether to produce output for "HumanLikeBot project" analysis
    
    Returns:
  - matchIsAboutToBegin
```
protected void matchIsAboutToBegin(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                                   cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                                   cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer,
                                   UT2004Match.Bots bots)
```
    Optional (usually) STEP 7 ... set up any listeners needed.
    Current implementation is empty.
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    server - MUST NOT BE NULL
    
    analyzer - may be null
    
    bots - MUST NOT BE NULL
  - restartMatch
```
protected void restartMatch(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                            UT2004Match.Bots bots)
```
    Usually STEP 8 ... restarts the match (in order to reinitialize the environment and restart all bots).
    Blocks until the match is restarted.
    Raises exception in case of any error.
    
    Parameters:
    
    server - MUST NOT BE NULL
  - recordReplay
```
protected void recordReplay(cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                            String fileName)
```
    Optional (usually) STEP 9 ... begin recording UT2004 replay
    
    Parameters:
    
    server -
    
    fileName -
  - waitMatchFinish
```
protected abstract UT2004MatchResult waitMatchFinish(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                                                     cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                                                     cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer,
                                                     UT2004Match.Bots bots,
                                                     long timeoutInMillis)
```
    Usually STEP 10 ... you wait for a predefined time (blocking method) for the match to finish.
    This method may need to be override to provide correct MATCH-FINISHED detecting routine.
    Always abide the timeout!
    Don't forget to observe whether all 'custom bots' are running! Use UT2004BotExecution.getRunning() flag and FlagListener.
    Raises exception in case of any error / timeout
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    server - MUST NOT BE NULL
    
    analyzer - may be null
    
    bots - MUST NOT BE NULL
    
    timeoutInMillis - must be specified correctly
    
    Returns:
    
    who has won (or null in case of failure / timeout)
  - restoreUT2004IniBackup
```
public void restoreUT2004IniBackup()
```
    Usually STEP 10.1
    Overwrites current UT2004.ini with UT2004.ini.backup that was created during createUT2004Ini().
  - restoreGB2004IniBackup
```
public void restoreGB2004IniBackup()
```
    Usually STEP 10.2
    Overwrites current GameBots2004.ini with GameBots2004.ini.backup that was created during createGB2004Ini().
  - copyReplay
```
protected void copyReplay(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                          String fileName,
                          File outputDirectory)
```
    Optional (usually) STEP 11 ... moves replay file to desired directory.
    
    Parameters:
    
    ucc -
    
    fileName -
  - outputResults
```
protected abstract void outputResults(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                                      cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                                      cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer,
                                      UT2004Match.Bots bots,
                                      UT2004MatchResult result,
                                      File outputDirectory)
```
    Usually STEP 12 ... concludes the match by producing/presenting whatever statistics needed about the match. Everything should be outputted to 'outputDirectory'.
    Raises exception in case of any error / timeout
    
    Parameters:
    
    ucc - MUST NOT BE NULL
    
    server - MUST NOT BE NULL
    
    analyzer - may be null
    
    bots - MUST NOT BE NULL
    
    result - MUST NOT BE NULL
    
    outputDirectory - MUST NOT BE NULL
  - shutdownAll
```
protected void shutdownAll(cz.cuni.amis.pogamut.ut2004.utils.UCCWrapper ucc,
                           cz.cuni.amis.pogamut.ut2004.server.impl.UT2004Server server,
                           cz.cuni.amis.pogamut.ut2004.analyzer.UT2004Analyzer analyzer,
                           UT2004Match.Bots bots)
```
    Usually STEP 13 ... shutdowns everything
    
    Parameters:
    
    ucc -
  - closeLogger
```
protected void closeLogger()
```
    Usually STEP 14 that close logging to file.

Class UT2004Match<CONFIG extends UT2004MatchConfig,RESULT extends UT2004MatchResult>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

config

log

result

exception

teamMatch

fileHandler

ut2004FileBackup

gb2004FileBackup

Constructor Detail

UT2004Match

Method Detail

isTeamMatch

isHumanPlayer

getResult

getException

run

call

execute

getCurrentDate

getConfig

getMatchId

getLog

toString

getOutputPath

getOutputPath

setupLogger

validate

cleanUp

getUccHome

getUT2004IniFile

getGB2004IniFile

createUT2004Ini

createGB2004Ini

startUCC

startControlServer

changeBotTeam

startBots

waitHumanPlayers

startAnalyzer

matchIsAboutToBegin

restartMatch

recordReplay

waitMatchFinish

restoreUT2004IniBackup

restoreGB2004IniBackup

copyReplay

outputResults

shutdownAll

closeLogger