Game

Game is the main class you’ll use to create and run a game.

class retro.game.Game(agents, state, board_size=(64, 32), view_size=None, view_position=(0, 0), debug=False, framerate=24, color='white_on_black', wait_for_enter=False, dump_state=None, log_file=None, input_source=None, view=None, show_state=True)

Creates a playable game.

Parameters:

• agents (list) – A list of agents to add to the game.

• state (dict) – A dict containing the game’s initial state.

• board_size (int, int) – (Optional, default (64, 32)) The two-dimensional size of the game board.

• view_size (int, int) – (Optional, default is board_size) The two-dimensional size of the view.

• view_position (int, int) – (Optional) The (x, y) coordinates of the top left corner of the view. By default, this is (0, 0).

• debug (bool) – (Optional) Turn on debug mode, showing log messages while playing.

• framerate (int) – (Optional) The target number of frames per second at which the game should run.

• color (str) – (Optional) The game’s background color scheme.

• wait_for_enter (bool) – (Optional) If True, the game screen stays open after the game ends until Enter or Escape is pressed. Defaults to False.

• show_state (bool | list) – (Optional) Controls which state variables are displayed below the board during play. True (default) shows all state variables. None, False, or [] hides the state pane entirely. A list of strings names specific state keys to display.

• dump_state (str) – (Optional) A filename. If provided, the game state will be saved to that file as JSON when the game ends.

• log_file (str) – (Optional) A filename. If provided, all log messages are written to this file in real time.

• input_source – (Optional) An retro.input.InputSource instance. When provided, step() uses it for input instead of the terminal. Ignored by play(), which always uses terminal input.

• view – (Optional) A view instance (implements on_game_start and render). When provided, step() calls view.render(self) after each turn. Ignored by play(), which manages its own retro.views.TerminalView.

# Standard interactive play:
from retro.game import Game
from retro.agent import ArrowKeyAgent
game = Game([ArrowKeyAgent()], {})
game.play()

# Programmatic stepping (e.g. for training):
from retro.input import ProgrammaticInput
from retro.views import HeadlessView
inp = ProgrammaticInput()
view = HeadlessView()
game = Game([MyAgent()], {'score': 0}, input_source=inp, view=view)
game.start()
inp.press('KEY_RIGHT')
game.step()
board = view.board_characters

add_agent(agent)

Add an agent to the game.

Parameters:

agent – An instance of an agent class.

end()

End the game. No more turns will run.

get_agent_by_name(name)

Look up an agent by name.

Parameters:

name (str) – The agent’s name.

Returns:

An agent.

get_agents_by_position()

Return a dict mapping each occupied position to a list of agents there.

is_empty(position)

Check whether a position is unoccupied.

Parameters:

position (int, int) – The position to check.

Returns:

A bool

log(message)

Write a log message.

Parameters:

message (str) – The message to log.

on_board(position)

Check whether a position is on the game board.

Parameters:

position (int, int) – The position to check.

Returns:

A bool

on_view(position)

Check whether a position is within the current view.

Parameters:

position (int, int) – The position to check.

Returns:

A bool

play(input_source=None)

Start the game in a terminal with interactive input and rendering.

Parameters:

input_source – (Optional) An retro.input.InputSource to use instead of the keyboard. When omitted, arrow-key / character input is read from the terminal as normal.

remove_agent(agent)

Remove an agent from the game.

Parameters:

agent (Agent) – the agent to remove.

remove_agent_by_name(name)

Remove an agent from the game by name.

Parameters:

name (str) – the agent’s name.

start()

Initialize game state before the first step() call. Call this when using step() directly (without play()).

step()

Run one game turn: collect input, let each agent act, advance state.

Call start() before the first step(). After step() returns, self.playing reflects whether the game is still active. If a retro.views.View was provided at construction, its render() is called at the end of each step.

retro.game.agent_occupied_positions(agent)

Returns all board positions occupied by an agent.