Module MatchRunner

Executes BerryBots matches and returns the results. Matches are queued asynchronously and run multi-threaded.

Functions

empty () Checks if the match queue is empty.
nextResult () Returns the next available match result.
queueMatch (stage, ships) Queues a match.
saveReplay () Saves the replay from the previous result.
setThreadCount (threadCount) Sets the number of threads.

Tables

MatchResult Specifies the results of a BerryBots match.
TeamResult Specifies the rank, score, and statistics for a ship or team.


Functions

empty ()

Checks if the match queue is empty.

Return value:

true if the match queue is empty, false otherwise.
nextResult ()

Returns the next available match result. This is a blocking call - it waits until the next match result is available.

Return value:

The next available match result, or nil if there are no matches queued.

See also:

queueMatch (stage, ships)

Queues a match. This is a non-blocking call - it returns immediately. To block and wait for the next available match result, see nextResult.

Parameters

  • stage: The filename of the stage - e.g., "sample/battle1.lua".
  • ships: A table of one or more ship filenames - e.g., {"sample/chaser.lua", "sample/randombot.lua"}.
saveReplay ()

Saves the replay from the previous result. Replays are HTML5 and should be viewable in most modern browsers.

Return value:

The filename of the replay in the BerryBots replays directory, or nil if no replay was saved.
setThreadCount (threadCount)

Sets the number of threads. This is the maximum number of BerryBots matches that will be run in parallel. This should probably be less than or equal to the number of CPU cores on your system.

Parameters

  • threadCount: The number of threads.

Tables

MatchResult

Specifies the results of a BerryBots match.

Fields:

  • stage: The filename of the stage.
  • errored: Whether the match was aborted due to errors.
  • errorMessage: A message describing the error, or nil if the match completed successfully.
  • winner: The filename of the ship program that won the match. If no winner is set, the winner is set to the team with rank 1, or nil if there is no such team.
  • teams: A table of TeamResult tables with the score details for each ship or team.
TeamResult

Specifies the rank, score, and statistics for a ship or team.

Fields:

  • name: The filename of the ship or team.
  • rank: The rank of the team, or 0 if no rank was set. E.g., 1 if this team was the winner. If no ranks are set by the stage, ranks are set according to highest scores.
  • score: The score of the team, or nil if no score was set for any team in the match.
  • stats: A table with key/value pairs of statistics for this team, or nil if no statistics were set.