Class PlayableGame
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
envIEnvThe env; its render mode must be
rgb_arrayorrgb_array_list, and it must render now (after a reset).keysToActionobjectA 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.zoomdouble?Scales the window; null keeps the frame's size. Must be positive.
viewerFactoryEnvViewerFactoryThe window's factory; null takes the context's ViewerFactory, then
Gymnasium.HumanViewerFactory.contextPygameContextThe display and event queue the game uses (DR-41); null is Default, the static Display and EventQueue.
Exceptions
- ArgumentNullException
Thrown when
envis 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
Env
The env being played (env).
public IEnv Env { get; }
Property Value
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
PressedKeys
The relevant keys held down now (pressed_keys), as the events gave them.
public ISet<object?> PressedKeys { get; }
Property Value
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
Running
Whether the game goes on (running); Escape (when not mapped), Quit, or you, set it false.
public bool Running { get; set; }
Property Value
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
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
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
eventEventThe 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
eventis null.- AttributeError
Thrown when a key event has no
key, or a resize noxory('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).