Skip to content

Configuration

Jump to bottom
Stone Tao edited this page Jan 31, 2021 · 19 revisions

This page is dedicated to explaining some the important configurations for Dimensions

Dimension Configs

Link to Documentation

We pass in configurations as so

const Dimension = require('dimensions-ai');
let myDimension = Dimension.create(yourDesign, dimensionConfigs);

These are the following fields you can put into the dimensionConfigs object

  • secureMode: boolean - This is by default false. When set to true, every single match and tournament matches are run in secure mode by default. This also requires you to setup security appropriately. See https://github.com/StoneT2000/Dimensions/wiki/Security for details

Design Options

Link to Documentation

The design options are typically used to configure the match engine and to set the default engine options for all matches.

We pass in configurations as so

const MyDesign = require('./MyDesign');
const myDesign = new MyDesign('name-of-design', designOptions)

These are the following fields you can put into the designOptions object engineOptions and override. See the Engine Options section for details on the engine. See below for info on the override field. Note that typically you should not be passing in the override field to a design built with Dimensions, it's used for custom designs only.

Override Options

Link to Documentation

The override options are for configuring a custom design and you pass override options as so

const MyDesign = Dimension.Design.createCustom('name-of-design', overrideOptions);

These are the following fields for the overrideOptions object

  • active: boolean - This is default true when using createCustom and otherwise false. Indicates whether we are running custom designs or not

  • command: string - This is the command to run that will run a match and send to the standard out any updates and match conclusion data. This is always executed in the same directory the dimension is created in.

  • arguments: string[] - This is an array of strings that will always get passed into the command provided. There are a few special strings documented here that will get replaced with dynamic data such as the ID of the agents in a match, the match ID, player names etc.

  • resultHandler: function - This is a function that will take an array of result strings outputted by the command run with the above arguments as input. All output after the command run outputs D_MATCH_FINISHED are considered result strings and stored into the array that will then be sent to the resultHandler. This function is the replacement for the getResults function used typically in a Dimensions design, and whatever results the function returns will be the results resolved from running a match and the results passed into the tournament resultHandler.

Engine Options

Link to Documentation

The engine options dictate how the engine handles communication between agents and handle the agent processes. They are typically passed to the design constructor as discussed in the design options section but can also be passed in at the match and tournament level to override options set at the design level.

Examples:

let rpsDesign = new RockPaperScissorsDesign('RPS', {
  engineOptions: yourEngineOptions,
});

myDimension.runMatch(botList, {
  engineOptions: yourEngineOoptions,
});

These are the following (notable) fields of the engineOptions configuration object

  • commandDelimiter: string - The delimiter to use to split messages sent by agents to then send to the update function in a Design, by default this is ,. For example, if an agent sent move a b 3,run 24 d,t 3 and the delimiter is ',' then the Design.update function will receive commands 'move a b 3' and 'run 24 d' and 't 3'

  • commandFinishPolicy: string - The method of which to use to determine when an agent is done sending commands and is ready for next turn. By default this is 'finish_symbol'. It can also be 'line_count'. If an agent is not marked as being ready for the next turn, and enough time passes, it will be seen as having timed out.

    • For 'finish_symbol', the engine will wait for the agent to send the commandFinishSymbol stored in the engine options. By default, it expects for 'D_FINISH'.
    • For 'line_count', the engine will wait for the agent to send a specified number of lines of messages before marking the agent having finished their move. Or if the agent sends the commandFinishSymbol, the agent will be marked as having finished its move. See the documentation for the commandLines field for settings available for this finish policy

  • memory: object - Configurations related to memory when running a match.

    • memory.active: boolean - if true (the default), then Dimensions will monitor the memory of the agent.
    • memory.limit: number - is the number of bytes allowed for each agent. If an agent goes over this limit, the memory.memoryCallback function is called
    • memory.memoryCallback: function - is the callback function called if an agent goes over the memory limit. By default, this kills the agent with the Match kill function, terminating the agent process. See documentation for function parameters

  • noStdErr: boolean - Whether agents output to standard error is logged to the console by the match engine or not. Default is true, so no output to standard error is logged to the console. However, this is still logged to a file if the match configuration has storeErrorLogs set to true.

  • timeout: object - Configurations related to timeouts when running a match

    • timeout.active: boolean - if true (the default), then if agent goes over a set max time, we call the timeoutCallback function
    • timeout.max: number - the max time in milliseconds allowed for each agent before the timeoutCallback function is called
    • timeout.timeoutCallback: function - is the callback function called if an agent does not finish its move in time as determined by the commandFinishPolicy used. By default, this kills the agent with the Match kill function, terminating the agent process. See documentation for function parameters.

Match Options

Link to Documentation

Configurations are passed in as defaultMatchConfigs at the dimension or tournament level of which they will be used for every match unless overridden. Can also be passed to individual created matches using Dimension.createMatch or Dimension.runMatch

Example:

let RPSTournament = myDimension.createTournament(botList, {
  ...,
  defaultMatchConfigs: yourDefaultMatchConfigs
  ...
});

myDimension.runMatch(botList, yourDefaultMatchConfigs);

These are the following (notable) fields of the configuration object for matches.

  • agentOptions: object - Agent configurations to use for every agent in a match, see this for details. Default is whatever is set during creation of Design.
  • engineOptions: object - Engine configurations to use for the match, see this for details. Default is whatever is set during creation of Design.
  • loggingLevel: number - The logging level to use in the match. Default is whatever is set for the dimension, which is by default Logger.LEVEL.INFO (equal to 3)
  • name: string - The name for the match
  • secureMode: boolean - Whether to use secureMode in this match, default is whatever is set for the dimension, which is by default false
  • storeErrorDirectory: string - Directory to store error logs locally. When a Storage plugin is used, this indicates the path in the bucket to store the log in, and removes the local copy.
  • storeErrorLogs: boolean - Whether to store error output for each Match
  • storeReplay: boolean - Whether or not to store a replay file if match results indicate a replay file was stored
  • storeReplayDirectory: string - Used only when a Storage plugin is used. Indicates the directory to use to store onto the storage. (Typically some path in the bucket).

Any other field name can be mapped to any value you would like. Your custom fields in the match configs can then be read by the Design by looking at match.configs. E.g., the rock paper scissors example uses a bestOf field to determine how many rounds of RPS to run.

Agent Options

Link to Documentation

Configurations for agents are passed in as part of the match configuration object detailed above.

These are the following (notable) fields of the configuration object for agents.

  • compileCommands: object - A map from an extension string, e.g. .js, .py to an array of strings forming a list of commands used to compile this agent instead of the defaults. When there is no mapping, default compilation commands are used.
  • runCommands: object - A map from an extension string, e.g. .js, .py to an array of strings forming a list of commands used to run this agent instead of the defaults. When there is no mapping, default run commands are used.
  • image: string - For use in secureMode. This is the docker image every agent will run on. The default is docker.io/stonezt2000/dimensions_langs, a standard image that contains all of the necessary build tools needed by all supported languages.
  • maxCompileTime: number - Maximum time in milliseconds allowed for the compile stage of a bot. Default is 1 minute (60,000 ms)
  • maxInstallTime: number - Maximum time allowed for an agent to spend on the installing step. This stage is always activated and used whenever a bot provides a install.sh file in the root of their directory. Default is 5 minutes (300,000 ms)

Clone this wiki locally