SDK reference

Classes

surrortg.config_parser

get_config(config_path, default_config_path='/etc/srtg/srtg.toml')

A separate static method makes testing easier

surrortg.game

class RobotType(value)

Bases: enum.Enum

An enumeration.

ROBOT = 'robot'
LOGICAL = 'logical'
class Game

Bases: object

A basis for all games on the Surrogate.tv platform

Game consists of callback methods, which are automatically called by the game engine during the game loop. All messaging with the game engine is done through GameIO class, which is accessed through self.io. The game loop is started with a run() call.

The players and admin panel configurations can be accessed through self.players and self.configs properties.

property io

Access to the GameIO object

GameIO is used for communication with the game engine.

Raises

RuntimeError – when accessed before run()

Returns

GameIO object instance

Return type

GameIO

property configs
Parameters

configs – A dictionary of admin panel configurations

Configs are available everywhere except during on_init.

Raises

RuntimeError – when accessed before run() or during on_init

Return type

dict

property players
Parameters

players – A list of player infos

The players are available only during on_pre_game, on_countdown, on_start and on_finish.

NOTE: because of the current implementation limitations, game.players could raise RuntimeError if preGame phase length is 0 seconds. The workaround is to set it for example to 2 seconds (the default is 0 seconds). This can be changed from the game’s Dashboard at www.surrogate.tv/game/<SHORT_ID>/settings > Settings > Game Engine.

Raises

RuntimeError – when accessed before run() or if not available

Return type

list[dict]

run(config_path=None, logging_level=20, socketio_logging_level=30, start_games_inputs_enabled=True, robot_type=<RobotType.ROBOT: 'robot'>, device_id=None)

Connect to the game engine and start the Game loop

Parameters
  • config_path (str/None, optional) – custom configuration file path, defaults to None

  • logging_level (int/None, optional) – logging level, defaults to logging.INFO

  • socketio_logging_level (Int, optional) – SocketIO logging level, defaults to logging.WARNING

  • start_games_inputs_enabled (bool, optional) – Decides whether the inputs are automatically enabled at the start of on_start method, defaults to True

  • robot_type (RobotType, optional) – Decides whether the python unit is a controllable robot unit, or a logical unit. Defaults to “robot”, for logical, use “logical”. Logical robot type is for advanced use only.

  • device_id (str/None, optional) – Overrides device_id from config file. Note: config file device_id is mandatory field even when this parameter is used

async on_init()

Initialize the game before connecting to the game engine

The input devices are registered here with a self.io.register_inputs({…}) call.

async on_config()

Do things before the game engine starts fetching new players

For example new inputs can be registered here if they change based on self.configs.

async on_prepare()

Do some preparations before the players connect

async on_pre_game()

Do some preparations after the players connect

The game won’t start before every robot has called self.io.send_pre_game_ready(), or maximum pre game time is reached. If the player inputs are needed here, they can be enabled with self.io.enable_inputs() call. On default all inputs are disabled here.

The return value of this method will set as the self._current_seat value (which is an integer).

async on_countdown()

Do things during the game countdown

async on_start()

Inputs are now enabled. Scores, laps and progress are counted.

self._current_seat is set to 0 by default, if it has not been set in on_pre_game().

The game engine will choose the winner based on the game type set on the admin panel. self.io.send_playing_ended() call can be used to signal the game engine that some seat has finished.

async on_finish()

Do something when the robot finishes the game

The game is finished for example when someone has enough score or laps or when the time is up. These rules can be set from the admin panel.

async on_exit(reason, exception)

This method is called just before the program exits

The exit reason code and exception are passed as parameters.

Exit reasons:

Code

Reason

-1

Unknown exit reason

0

Uncaught exception

1

Interrupted (SIGINT)

2

Terminated (SIGTERM)

3

Update (SIGUSR1)

Parameters
  • reason (int) – Reason code of the program exit.

  • exception (Exception/None) – Exception that caused the exit

surrortg.game_io

class ConfigType(value)

Bases: enum.Enum

An enumeration.

STRING = 'string'
NUMBER = 'number'
INTEGER = 'integer'
BOOLEAN = 'boolean'
class GameIO(ge_message_handler, robot_log_handler, config_path, socketio_logging_level, robot_type, device_id)

Bases: object

For communication between Python and the game engine

The class is accessed through Game.io.

register_config(name, value_type, default, is_robot_specific, minimum=None, maximum=None)

Registers custom configs

Registers a custom config variable which can be edited through the game’s settings page in surrogate.tv The config can either be specific for the robot or a game-wide setting. Config names must be unique, and configs can only be registered during on_init stage of the game loop.

Parameters
  • name (string) – Name of the config

  • value_type (ConfigType or "boolean" | "string" | "number" | "integer") – Type of the variable

  • default (Must be of the value_type, e.g. if value_type is string this must be string as well.) – Initial default value for the variable

  • is_robot_specific (boolean) – True if the config variable is for this robot only, False if this is game-wide variable

  • minimum (Number if value_type is number, int if value_type is integer. Otherwise this must be None) – Optional minimum value for numeric configs

  • maximum (Number if value_type is number, int if value_type is integer. Otherwise this must be None) – Optional maximum value for numeric configs

register_inputs(inputs, admin=False, bindable=True)

Registers inputs

Input names must be unique. If the same input name already exists, error is risen. The inputs can be registered only during on_init.

Parameters
  • inputs (dict{String: Input}) – A dictionary of input device names and objects.

  • admin (bool, optional) – Describes if the input is for admin use only, defaults to False

  • bindable – Describes if the input can be bound to user input. Defaults to True.

Raises
  • RuntimeError – if input names are not unique

  • RuntimeError – if called outside on_init

enable_inputs()

Enable all registered inputs

disable_inputs()

Disable all registered inputs

enable_input(seat)

Enable a single registered input

Parameters

seat (int) – Robot seat

disable_input(seat)

Disable a single registered input

Parameters

seat (int) – Robot seat

async reset_inputs(seat=None)

Reset registered inputs

If seat is not defined, resets all registered inputs, otherwise affects only the inputs with specified seat.

Parameters

seat (Int, optional) – seat number, defaults to None

async shutdown_inputs(seat=None)

Shutdown registered inputs

If seat is not defined, shuts down all registered inputs, otherwise affects only the inputs with specified seat.

Parameters

seat (Int, optional) – seat number, defaults to None

send_lap(seat=0)

Send a lap update to the game engine when lap is finished

Parameters

seat (int, optional) – seat number, defaults to 0

send_progress(progress, seat=0)

Send a progress update to the game engine

Parameters
  • progress (float) – progress amount between 0 and 1

  • seat (int, optional) – seat number, defaults to 0

send_score(score=None, scores=None, seat=0, final_score=False, seat_final_score=False)

Send a score update to the game engine

Send eiher a single score or multiple scores.

Parameters
  • score (int/float, optional) – score value, defaults to None

  • scores (dict/list, optional) – scores dictionary or list, defaults to None

  • seat (int, optional) – seat number, used only with a single score, defaults to 0

  • final_score (bool, optional) – signal to GE that there will not be more scores coming, defaults to False

  • seat_final_score (bool, optional) – signal to GE that there will not be more scores coming to the specified seats, defaults to False

send_state_alive(seat=0)

Send a state update: alive to the game engine

Parameters

seat (int, optional) – seat number, defaults to 0

send_state_dead(seat=0)

Send a state update: dead to the game engine

Parameters

seat (int, optional) – seat number, defaults to 0

send_state_unknown(seat=0)

Send a state update: unknown to the game engine

Parameters

seat (int, optional) – seat number, defaults to 0

send_pre_game_ready(seat=0)

Tell the GE that a seat is ready to finish on_pre_game

Parameters

seat (int, optional) – seat number, defaults to 0

send_pre_game_not_ready(seat=0)

Tell the GE that a seat is not ready to finish on_pre_game

Parameters

seat (int, optional) – seat number, defaults to 0

set_current_seat(seat)

Tell GE the currently playing seat

Parameters

seat (int) – current player seat

send_playing_ended()

Tell the GE that the Game is ready to move to on_finish

log_admin(message, also_log=False)