api

Submodules

• api.config
• api.rlgym
• api.typing
• api.version

Attributes

__version__
AgentID
ObsType
ActionType
EngineActionType
RewardType
StateType
ObsSpaceType
ActionSpaceType

Classes

RLGym	The main RLGym class. This class is responsible for managing the environment and the interactions between
ActionParser	The action parser. This class is responsible for receiving actions from the agents and parsing them into a format
DoneCondition	A termination/truncation condition. This class is responsible for determining when an episode should end for each agent.
ObsBuilder	The observation builder. This class is responsible for building observations for each agent in the environment.
Renderer	The renderer class. This class is responsible for rendering a state.
RewardFunction	The reward function. This class is responsible for computing the reward for each agent in the environment.
StateMutator	The state mutator class. This class is responsible for modifying the state of the environment.
TransitionEngine	The Transition Engine class. This class is responsible for managing the state of the environment and stepping the
SharedInfoProvider	The shared information provider. This class is responsible for managing shared information across all config objects.

Package Contents

api.__version__ = '2.0.0'

class api.RLGym(state_mutator: api.config.StateMutator[api.typing.StateType], obs_builder: api.config.ObsBuilder[api.typing.AgentID, api.typing.ObsType, api.typing.StateType, api.typing.ObsSpaceType], action_parser: api.config.ActionParser[api.typing.AgentID, api.typing.ActionType, api.typing.EngineActionType, api.typing.StateType, api.typing.ActionSpaceType], reward_fn: api.config.RewardFunction[api.typing.AgentID, api.typing.StateType, api.typing.RewardType], transition_engine: api.config.TransitionEngine[api.typing.AgentID, api.typing.StateType, api.typing.EngineActionType], termination_cond: api.config.DoneCondition[api.typing.AgentID, api.typing.StateType] | None = None, truncation_cond: api.config.DoneCondition[api.typing.AgentID, api.typing.StateType] | None = None, shared_info_provider: api.config.SharedInfoProvider[api.typing.AgentID, api.typing.StateType] | None = None, renderer: api.config.Renderer[api.typing.StateType] | None = None)

Bases: Generic[api.typing.AgentID, api.typing.ObsType, api.typing.ActionType, api.typing.EngineActionType, api.typing.RewardType, api.typing.StateType, api.typing.ObsSpaceType, api.typing.ActionSpaceType]

The main RLGym class. This class is responsible for managing the environment and the interactions between the different components of the environment. It is the main interface for the user to interact with an environment.

state_mutator

obs_builder

action_parser

reward_fn

transition_engine

termination_cond = None

truncation_cond = None

renderer = None

shared_info_provider = None

shared_info

property agents: List[api.typing.AgentID]

property action_spaces: Dict[api.typing.AgentID, api.typing.ActionSpaceType]

property observation_spaces: Dict[api.typing.AgentID, api.typing.ObsSpaceType]

property state: api.typing.StateType

action_space(agent: api.typing.AgentID) → api.typing.ActionSpaceType

observation_space(agent: api.typing.AgentID) → api.typing.ObsSpaceType

set_state(desired_state: api.typing.StateType) → Dict[api.typing.AgentID, api.typing.ObsType]

reset() → Dict[api.typing.AgentID, api.typing.ObsType]

step(actions: Dict[api.typing.AgentID, api.typing.ActionType]) → Tuple[Dict[api.typing.AgentID, api.typing.ObsType], Dict[api.typing.AgentID, api.typing.RewardType], Dict[api.typing.AgentID, bool], Dict[api.typing.AgentID, bool]]

render() → Any

close() → None

class api.ActionParser

Bases: Generic[api.typing.AgentID, api.typing.ActionType, api.typing.EngineActionType, api.typing.StateType, api.typing.ActionSpaceType]

The action parser. This class is responsible for receiving actions from the agents and parsing them into a format supported by the TransitionEngine.

abstract get_action_space(agent: api.typing.AgentID) → api.typing.ActionSpaceType

Function that returns the action space type. It will be called during the initialization of the environment.

Returns:

The type of the action space

abstract reset(agents: List[api.typing.AgentID], initial_state: api.typing.StateType, shared_info: Dict[str, Any]) → None

Function to be called each time the environment is reset.

Parameters:

• agents – List of AgentIDs for which this ActionParser will receive actions

• initial_state – The initial state of the reset environment.

• shared_info – A dictionary with shared information across all config objects.

abstract parse_actions(actions: Dict[api.typing.AgentID, api.typing.ActionType], state: api.typing.StateType, shared_info: Dict[str, Any]) → Dict[api.typing.AgentID, api.typing.EngineActionType]

Function that parses actions from the action space into a format that rlgym understands. The expected return value is a numpy float array of size (n, 8) where n is the number of agents. The second dimension is indexed as follows: throttle, steer, yaw, pitch, roll, jump, boost, handbrake. The first five values are expected to be in the range [-1, 1], while the last three values should be either 0 or 1.

Parameters:

• actions – An dict of actions, as passed to the env.step function.

• state – The GameState object of the current state that were used to generate the actions.

• shared_info – A dictionary with shared information across all config objects.

Returns:

the parsed actions in the rlgym format.

class api.DoneCondition

Bases: Generic[api.typing.AgentID, api.typing.StateType]

A termination/truncation condition. This class is responsible for determining when an episode should end for each agent.

abstract reset(agents: List[api.typing.AgentID], initial_state: api.typing.StateType, shared_info: Dict[str, Any]) → None

Function to be called each time the environment is reset.

Parameters:

• agents – List of AgentIDs for which this DoneCondition will be evaluated

• initial_state – The initial state of the reset environment.

• shared_info – A dictionary with shared information across all config objects.

abstract is_done(agents: List[api.typing.AgentID], state: api.typing.StateType, shared_info: Dict[str, Any]) → Dict[api.typing.AgentID, bool]

Function to determine if a game state is terminal. This will be called once per step, and must return either True or False if the current episode should be terminated at this state.

Parameters:

• agents – List of AgentIDs for which this DoneCondition should be evaluated

• state – The current state of the game.

• shared_info – A dictionary with shared information across all config objects.

Returns:

Dict of bools representing whether the current state meets this done condition for each AgentID in agents.

class api.ObsBuilder

Bases: Generic[api.typing.AgentID, api.typing.ObsType, api.typing.StateType, api.typing.ObsSpaceType]

The observation builder. This class is responsible for building observations for each agent in the environment.

abstract get_obs_space(agent: api.typing.AgentID) → api.typing.ObsSpaceType

Function that returns the observation space type. It will be called during the initialization of the environment.

Returns:

The type of the observation space

abstract reset(agents: List[api.typing.AgentID], initial_state: api.typing.StateType, shared_info: Dict[str, Any]) → None

Function to be called each time the environment is reset. Note that this does not need to return anything, the environment will call build_obs automatically after reset, so the initial observation for a policy will be constructed in the same way as every other observation.

Parameters:

• agents – List of AgentIDs for which this ObsBuilder will return an Obs

• initial_state – The initial game state of the reset environment.

• shared_info – A dictionary with shared information across all config objects.

abstract build_obs(agents: List[api.typing.AgentID], state: api.typing.StateType, shared_info: Dict[str, Any]) → Dict[api.typing.AgentID, api.typing.ObsType]

Function to build observations for N agents. This is where observations will be constructed every step and every reset. This function is given the current state, and it is expected that the observations returned by this function will contain information from the perspective of each agent. This function is called only once per step.

Parameters:

• agents – List of AgentIDs for which this ObsBuilder should return an Obs

• state – The current state of the game.

• shared_info – A dictionary with shared information across all config objects.

Returns:

An dictionary of observations, one for each AgentID in agents.

class api.Renderer

Bases: Generic[api.typing.StateType]

The renderer class. This class is responsible for rendering a state.

abstract render(state: api.typing.StateType, shared_info: Dict[str, Any]) → Any

abstract close()

class api.RewardFunction

Bases: Generic[api.typing.AgentID, api.typing.StateType, api.typing.RewardType]

The reward function. This class is responsible for computing the reward for each agent in the environment.

abstract reset(agents: List[api.typing.AgentID], initial_state: api.typing.StateType, shared_info: Dict[str, Any]) → None

Function to be called each time the environment is reset. This is meant to enable users to design stateful reward functions that maintain information about the game throughout an episode to determine a reward.

Parameters:

• agents – List of AgentIDs for which this RewardFunc will return a Reward

• initial_state – The initial state of the reset environment.

• shared_info – A dictionary with shared information across all config objects.

abstract get_rewards(agents: List[api.typing.AgentID], state: api.typing.StateType, is_terminated: Dict[api.typing.AgentID, bool], is_truncated: Dict[api.typing.AgentID, bool], shared_info: Dict[str, Any]) → Dict[api.typing.AgentID, api.typing.RewardType]

Function to compute the reward for a player. This function is given a player argument, and it is expected that the reward returned by this function will be for that player.

Parameters:

• agents – List of AgentIDs for which this RewardFunc should return a Reward

• state – The current state of the game.

• is_terminated – TODO.

• is_truncated – TODO.

• shared_info – A dictionary with shared information across all config objects.

Returns:

A dict of rewards, one for each AgentID in agents.

class api.StateMutator

Bases: Generic[api.typing.StateType]

The state mutator class. This class is responsible for modifying the state of the environment.

abstract apply(state: api.typing.StateType, shared_info: Dict[str, Any]) → None

Function to be called each time the environment is reset. This function should change any desired values of the State. The values within State are sent to the transition engine to set up the initial state.

Parameters:

• state – State object to be modified with desired state values.

• shared_info – A dictionary with shared information across all config objects.

class api.TransitionEngine

Bases: Generic[api.typing.AgentID, api.typing.StateType, api.typing.EngineActionType]

The Transition Engine class. This class is responsible for managing the state of the environment and stepping the environment forward in time.

property agents: List[api.typing.AgentID]

Abstractmethod:

property max_num_agents: int

Abstractmethod:

property state: api.typing.StateType

Abstractmethod:

property config: Dict[str, Any]

Abstractmethod:

abstract step(actions: Dict[api.typing.AgentID, api.typing.EngineActionType], shared_info: Dict[str, Any]) → api.typing.StateType

abstract create_base_state() → api.typing.StateType

abstract set_state(desired_state: api.typing.StateType, shared_info: Dict[str, Any]) → api.typing.StateType

abstract close() → None

class api.SharedInfoProvider

Bases: Generic[api.typing.AgentID, api.typing.StateType]

The shared information provider. This class is responsible for managing shared information across all config objects.

abstract create(shared_info: Dict[str, Any]) → Dict[str, Any]

Function to be called before anything else each time the environment is set to a particular state, either via set_state, reset or __init__.

Parameters:

shared_info – The previous shared information dictionary

abstract set_state(agents: List[api.typing.AgentID], initial_state: api.typing.StateType, shared_info: Dict[str, Any]) → Dict[str, Any]

Function to be called each time the environment is set to a particular state (either via set_state or reset), right after the transition engine is called.

Parameters:

• agents – List of AgentIDs for which this SharedInfoProvider will manage the SharedInfo

• initial_state – The initial state of the environment

• shared_info – The previous shared information dictionary

abstract step(agents: List[api.typing.AgentID], state: api.typing.StateType, shared_info: Dict[str, Any]) → Dict[str, Any]

Function to be called each time the environment is stepped, right after the transition engine is called.

Parameters:

• agents – List of AgentIDs for which this SharedInfoProvider should manage the SharedInfo

• state – The new state of the environment

• shared_info – The previous shared information dictionary

api.AgentID

api.ObsType

api.ActionType

api.EngineActionType

api.RewardType

api.StateType

api.ObsSpaceType

api.ActionSpaceType