cz.cuni.amis.pogamut.ut2004.tournament.match
Class UT2004Match<CONFIG extends UT2004MatchConfig,RESULT extends UT2004MatchResult>

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

All Implemented Interfaces:

Runnable, Callable<RESULT>

Direct Known Subclasses:

UT2004CaptureTheFlag, UT2004DeathMatch

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

static class

UT2004Match.Bots

Field Summary

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

Constructor Summary

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

Method Summary

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(UCCWrapper ucc, String fileName, File outputDirectory) Optional (usually) STEP 11 ... moves replay file to desired directory.
protected void	createGB2004Ini() Usually STEP 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 void	changeBotTeam(UT2004Server server, cz.cuni.amis.pogamut.unreal.communication.messages.UnrealId botId, int desiredTeam)
boolean	isTeamMatch() Whether team / inidividuals are fighting in this match.
protected void	matchIsAboutToBegin(UCCWrapper ucc, UT2004Server server, UT2004Analyzer analyzer, UT2004Match.Bots bots) Optional (usually) STEP 7 ... set up any listeners needed.
protected abstract void	outputResults(UCCWrapper ucc, UT2004Server server, 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(UT2004Server server, String fileName) Optional (usually) STEP 9 ... begin recording UT2004 replay
protected void	restartMatch(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.
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(UCCWrapper ucc, UT2004Server server, UT2004Analyzer analyzer, UT2004Match.Bots bots) Usually STEP 13 ... shutdowns everything
protected UT2004Analyzer	startAnalyzer(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(UCCWrapper ucc, UT2004Server server) Usually STEP 5 ... starts all custom & native bots + changes their teams if needed.
protected UT2004Server	startControlServer(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 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 abstract UT2004MatchResult	waitMatchFinish(UCCWrapper ucc, UT2004Server server, 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

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 / inidividuals are fighting in this match.

True == team match, False = match of inidividual bots.

Returns:

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:

getGB2004IniFile

protected File getGB2004IniFile()

Returns file that is pointing to GameBots2004.ini that will be used by ucc.exe.

Returns:

createGB2004Ini

protected void createGB2004Ini()

Usually STEP 2 ... it overwrites the GameBots2004.ini file that is present in UT2004 home.

Raises exception in case of any error.

startUCC

protected 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 UT2004Server startControlServer(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.

Parameters:

ucc - MUST NOT BE NULL

Returns:

running control server

changeBotTeam

protected void changeBotTeam(UT2004Server server,
                             cz.cuni.amis.pogamut.unreal.communication.messages.UnrealId botId,
                             int desiredTeam)

startBots

protected UT2004Match.Bots startBots(UCCWrapper ucc,
                                     UT2004Server server)

Usually STEP 5 ... 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

startAnalyzer

protected UT2004Analyzer startAnalyzer(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(UCCWrapper ucc,
                                   UT2004Server server,
                                   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(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(UT2004Server server,
                            String fileName)

Optional (usually) STEP 9 ... begin recording UT2004 replay

Parameters:

server -

fileName -

waitMatchFinish

protected abstract UT2004MatchResult waitMatchFinish(UCCWrapper ucc,
                                                     UT2004Server server,
                                                     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)

restoreGB2004IniBackup

public void restoreGB2004IniBackup()

Usually STEP 10.

Overwrites current GameBots2004.ini with GameBots2004.ini.backup that was created during createGB2004Ini().

copyReplay

protected void copyReplay(UCCWrapper ucc,
                          String fileName,
                          File outputDirectory)

Optional (usually) STEP 11 ... moves replay file to desired directory.

Parameters:

ucc -

fileName -

outputResults

protected abstract void outputResults(UCCWrapper ucc,
                                      UT2004Server server,
                                      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(UCCWrapper ucc,
                           UT2004Server server,
                           UT2004Analyzer analyzer,
                           UT2004Match.Bots bots)

Usually STEP 13 ... shutdowns everything

Parameters:

ucc -

closeLogger

protected void closeLogger()

Usually STEP 14 that close logging to file.