Table of Contents

Class PlayableGame

Namespace
Gym.Utils
Assembly
Gym.Rendering.dll

An env being played from the keyboard, as Gymnasium's PlayableGame: it opens its context's display at the size of the env's frame (times the zoom), knows which keys matter, and tracks which of them are held as ProcessEvent(Event) reads key events. Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) builds one and drives it; build one directly to run a loop of your own.

public class PlayableGame
Inheritance
PlayableGame
Inherited Members
Extension Methods

Remarks

Constructing it opens the display of its Context (pygame's set_mode), replacing any window open there; call the context's Quit() (Quit() for the default context) when done, as Gymnasium's tests call pygame.quit(). Not thread-safe: process events from the thread that plays.

The key sets hold keys with Python's equality and hashing (an event's 97.0 matches a relevant 97); PressedKeys holds the event's own key objects, as Python's set does.

Reference: gymnasium/utils/play.py.

Constructors

PlayableGame(IEnv, object?, double?, EnvViewerFactory?, PygameContext?)

Opens the display for env: checks the render mode and the zoom, collects the relevant keys, renders once to size the window, then opens it.

public PlayableGame(IEnv env, object? keysToAction = null, double? zoom = null, EnvViewerFactory? viewerFactory = null, PygameContext? context = null)

Parameters

env IEnv

The env; its render mode must be rgb_array or rgb_array_list, and it must render now (after a reset).

keysToAction object

A dictionary whose keys are key combinations, tuples of key codes ((KeyCode.A,), (275, 276)), or null to ask the env (get_keys_to_action, found through any wrapper). Only the keys' elements are read here; Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) converts strings and single codes into such tuples first.

zoom double?

Scales the window; null keeps the frame's size. Must be positive.

viewerFactory EnvViewerFactory

The window's factory; null takes the context's ViewerFactory, then Gymnasium.HumanViewerFactory.

context PygameContext

The display and event queue the game uses (DR-41); null is Default, the static Display and EventQueue.

Exceptions

ArgumentNullException

Thrown when env is null.

ValueError

Thrown for another render mode (PlayableGame wrapper works only with rgb_array and rgb_array_list render modes, but your environment render_mode = None.) or a zoom that is not positive (Zoom must be a positive float, got 0.0), with Gymnasium's messages; also for a NaN zoom, when the size is computed.

MissingKeysToAction

Thrown when no mapping is given and the env has none.

AssertionError

Thrown, with an empty message as Python's bare assert, when the env has no mapping and no spec either, or when its render is not an array.

TypeError

Thrown when the mapping is not a dictionary, or a key is not iterable (an int).

IndexError

Thrown for a one-dimensional render (tuple index out of range) or an empty frame list (list index out of range).

OverflowError

Thrown, as Python's OverflowError, for an infinite zoom.

ArgumentOutOfRangeException

Thrown when the window's size comes out zero, which pygame would turn into a desktop-sized window (not modelled).

DependencyNotInstalled

Thrown when no viewer factory is given or set.

Properties

Context

The display and event queue this game uses (DR-41): its window is the context's display, and Run(IEnv, bool?, double?, double?, PlayCallback?, object?, BigInteger?, object?, bool, EnvViewerFactory?, PygameContext?) reads the context's queue. Not one of Gymnasium's attributes.

public PygameContext Context { get; }

Property Value

PygameContext

Env

The env being played (env).

public IEnv Env { get; }

Property Value

IEnv

OriginalVideoSize

The frame's size times the zoom, (width, height) (original_video_size); every resize scales from it.

public (int Width, int Height) OriginalVideoSize { get; }

Property Value

(int Width, int Height)

PressedKeys

The relevant keys held down now (pressed_keys), as the events gave them.

public ISet<object?> PressedKeys { get; }

Property Value

ISet<object>

RelevantKeys

Every key that appears in a combination of the mapping (relevant_keys): only these are tracked as pressed. With Python's equality; modifying it changes which keys are tracked.

public ISet<object?> RelevantKeys { get; }

Property Value

ISet<object>

Running

Whether the game goes on (running); Escape (when not mapped), Quit, or you, set it false.

public bool Running { get; set; }

Property Value

bool

Screen

The display surface (screen), read from the context's GetSurface() each time, because a resize of the window replaces it (pygame swaps the surface behind the same object).

public Surface Screen { get; }

Property Value

Surface

Exceptions

SdlError

Thrown after the context's display quit, with pygame's message: display Surface quit.

VideoSize

The size frames are scaled to (video_size): OriginalVideoSize until the window is resized, then the largest size of the same aspect that fits the window.

public (int Width, int Height) VideoSize { get; set; }

Property Value

(int Width, int Height)

Methods

ProcessEvent(Event)

Applies one event (process_event): a relevant key's press or release updates PressedKeys, Escape (when it is not relevant) and Quit stop the game, and WindowResized refits VideoSize; anything else is ignored.

public void ProcessEvent(Event @event)

Parameters

event Event

The event.

Remarks

A held key that repeats (several presses, one release) is released by its one release; a release of a key never pressed does nothing. A resize keeps the frame's aspect: the scale is the smaller of the two axes' ratios, and each side is rounded half to even, as Python's round.

Exceptions

ArgumentNullException

Thrown when event is null.

AttributeError

Thrown when a key event has no key, or a resize no x or y ('pygame.event.Event' object has no attribute 'key').

TypeError

Thrown for a key Python cannot hash (unhashable type: 'list'), or a resize size that is no number.

ZeroDivisionError

Thrown, as Python's ZeroDivisionError, for a resize of a game whose frame is zero pixels wide or high.

ValueError

Thrown for a NaN resize size (cannot convert float NaN to integer).

OverflowError

Thrown, as Python's OverflowError, for an infinite resize size.

OverflowException

Thrown for a resize size beyond an int (Gym.NET's limit; Python's ints are unbounded).