Experimental feature: GameSet bundle defining the tools and rules for a given game

[stephanzlatarev]

📓 The idea is a refinement of aiarena/aiarena-client#2 (Implement .meta folder)

Let's introduce entity GameSet - a bundle that contains the tools and rules that define the overall context for a game. For a StarCraft II game, the bundle may contain the SC2Map file, a descriptor of special rules or victory conditions, and helper metadata files for the bots. For a poker game, the bundle may contain a descriptor of the rules and the picture of the poker table to be used when streaming the game.

Properties of the GameSet

The gameset is a single file with the following properties stored in AI Arena:

• name - The name of the gameset.
• description - Short description of the gameset.
• game - Reference to a Game in AI Arena that can use this gameset.
• author - The author of the gameset. Used for filtering purposes.
• tags - Keywords used for filtering purposes.

The file is in ZIP or SC2Map (for compatibility with existing competitions) format. The contents of the ZIP format are described in the description property of the gameset.

Relationship to other entities

• A Game (e.g. StarCraft II, Poker) may have a pool of GameSet. Anyone can create a gameset and associate it with a game in AI Arena.
• A competition owner may create a Competition for a game with a selection of GameSets from the available pool for this game. The owner would use the name, description, author and tags to search and filter the pool for gamesets.
• Every Match in a competition is played using one GameSet of those in the competition.
• The Bots playing the match receive the gameset as input at the start of the match in a folder named by an environment variable.

Use in AI Arena competitions

1. When Arena Web creates a new round for a competition, it will select a random gameset for each match aiarena/aiarena-web/aiarena/core/services/matches.py.
2. When Arena Client starts a new match, it will fetch the gameset via "/api/arenaclient/matches/" in the API sc2-ai-match-controller/proxy_controller/src/matches/sources/aiarena_api/mod.rs.
3. When the gameset is a ZIP file, Arena Client will unzip it in folder "/aiarena/gameset/" for each bot in its Bot Controller container.
4. Finally, Arena Client will set environment variable AI_ARENA_GAMESET to "/aiarena/gameset/" for the Bot Controller containers so that the bots can find the folder sc2-ai-match-controller/k8s_controller/templates/ac-job.yaml.

Use in requested matches in AI Arena

1. The request match page will offer the option to select a gameset instead of a map when requesting a match.
2. When gameset is chosen, the page will allow to select one of the gamesets in the pool for the game.

Use in local play vs built-in AI

1. Download the chosen gameset from the competition page in Arena Web.
2. Unzip to a folder in the local file system.
3. Set environment variable AI_ARENA_GAMESET to this folder when starting the bot.

Use in local play with local-play-bootstrap

1. Download the chosen gameset from the competition page in Arena Web.
2. Unzip to a folder in the local file system.
3. Update docker-compose.yml with environment variable AI_ARENA_GAMESET to this folder aiarena/local-play-bootstrap/docker-compose.yml.

Use in local play with AI Arena GUI

❓ Is the GUI still used?

Use in bot frameworks

Authors of bot frameworks may check for environment variable AI_ARENA_GAMESET. When it exists and points to an existing folder, the framework may use well known files in this folder.

Considerations and next steps

1. The introduction of GameSet must not break active competitions or existing bots.
2. It can be introduced as an experimental feature for 6 months. If not successful or not popular, it can be safely removed after this period.
3. The first gamesets will contain the SC2 maps for he next season along with a file listing the depot locations and their distances from the starting locations. This is useful for selecting expansion locations.
4. A future feature that is helped by this feature is input information about the opponent in the context of the gameset of a given match. It may include information as number of played games, win rate by tags, etc.