API Reference

Core Classes

Base Classes

Bases: ABC

Abstract base class for all pSim VSSS environments.

This class defines the core interface and shared functionality that must be implemented by all VSSS environment types (SimpleVSSSEnv, VSSSGymEnv, VSSSPettingZooEnv).

Core Components: - Simulator: Physics simulation (Box2D) - ConfigManager: Configuration file management - GameSetup: Initial robot/ball positioning - RewardSystem: Reward calculation and episode management

Subclasses must implement: - step(): Execute one simulation step - reset(): Reset environment to initial state - render(): Display/return visual representation

Parameters:

Name	Type	Description	Default
`render_mode`	`str`	Rendering mode ("human", "rgb_array", or None)	`'human'`
`scenario`	`str`	Scenario name from configuration	`'formation'`
`num_agent_robots`	`int`	Number of agent robots	`1`
`num_adversary_robots`	`int`	Number of adversary robots	`0`
`color_team`	`str`	Team color ("blue" or "yellow")	`'blue'`
`truncated_time`	`int`	Maximum episode length	`3600`
`**kwargs`	`Any`	Additional arguments for subclasses	`{}`

`close()`

Clean up environment resources.

This method should be called when done with the environment to properly clean up rendering resources.

`get_reward()`

Get reward and termination info. Override this method for custom rewards.

Returns:

Type	Description
`Tuple[float, bool, bool]`	Tuple of (reward, terminated, truncated)

`render(mode=None)` `abstractmethod`

Render the environment.

Parameters:

Name	Type	Description	Default
`mode`	`Optional[str]`	Render mode override. If None, uses self.render_mode.	`None`

Returns:

Type	Description
`Optional[ndarray]`	RGB array if mode="rgb_array", None if mode="human".

`reset(seed=None)` `abstractmethod`

Reset environment to initial state.

Parameters:

Name	Type	Description	Default
`seed`	`Optional[int]`	Random seed for reproducibility	`None`

Returns:

Type	Description
`Any`	Tuple of (initial_observation, info_dict).
`Dict`	Formats depend on subclass.

`set_ball_velocity(vx, vy)`

Set the velocity of the ball directly.

Parameters:

Name	Type	Description	Default
`vx`	`float`	Velocity in x direction	required
`vy`	`float`	Velocity in y direction	required

`step(action)` `abstractmethod`

Execute one simulation step.

Parameters:

Name	Type	Description	Default
`action`	`Any`	Action(s) to execute. Format depends on subclass.	required

Returns:

Type	Description
`Any`	Tuple containing (observation, reward, terminated, truncated, info).
`...`	Specific formats depend on subclass (single vs multi-agent).

Environment Classes

Bases: BaseVSSSEnv

Simple VSSS Environment for traditional control algorithms.

This environment provides a clean interface for testing PID controllers and other traditional control algorithms. All agent robots are controlled simultaneously through actions defined by the control algorithm.

Parameters:

Name	Type	Description	Default
`render_mode`	`str`	Render mode ("human", "rgb_array", or None).	`'human'`
`num_agent_robots`	`int`	The number of agent robots in the simulation.	`1`
`num_adversary_robots`	`int`	The number of adversary robots in the simulation.	`0`
`color_team`	`str`	The color of the agent team ("blue" or "yellow").	`'blue'`
`scenario`	`str`	Game scenario to use from config file.	`'formation'`
`truncated_time`	`int`	Maximum steps before truncation.	`3600`
`**kwargs`	`Any`	Additional arguments passed to BaseEnv.	`{}`

`close()`

Close the environment and cleanup resources.

`render(mode=None)`

Render the environment.

Parameters:

Name	Type	Description	Default
`mode`	`Optional[str]`	Render mode ("human", "rgb_array", or None). If None, uses default render_mode.	`None`

Returns:

Type	Description
`Optional[ndarray]`	If mode is "rgb_array", returns numpy array of RGB image.
`Optional[ndarray]`	If mode is "human", displays the environment and returns None.

`reset(seed=None)`

Reset the environment to initial state.

Parameters:

Name	Type	Description	Default
`seed`	`Optional[int]`	Optional seed for random number generator.	`None`

Returns:

Type	Description
`Tuple[Dict[str, ndarray], Dict]`	Tuple of (initial_observation, info_dict).

`step(action, adversary_actions=None)`

Perform one step in the environment.

Parameters:

Name	Type	Description	Default
`action`	`ndarray`	Action array with shape (num_agent_robots, 2) containing [v, w] for each agent robot.	required
`adversary_actions`	`Optional[ndarray]`	Optional action array for adversary robots.	`None`

Returns:

Type	Description
`Tuple[Dict[str, ndarray], float, bool, bool, Dict]`	Tuple of (observation, reward, terminated, truncated, info).

Bases: BaseVSSSEnv, Env

Custom Gymnasium Environment for Very Small Size Soccer (VSSS). Provides a standardized Gymnasium interface for reinforcement learning.

This environment simulates a VSSS match, allowing AI agents to control robots and interact with a ball within a defined field.

Parameters:

Name	Type	Description	Default
`render_mode`	`Optional[str]`	The rendering mode. Can be "human" for display or "rgb_array" for returning RGB images.	`None`
`scenario`	`str`	The game scenario to use ("formation" or "full_random").	`'formation'`
`num_agent_robots`	`int`	The number of agent robots in the simulation.	`1`
`num_adversary_robots`	`int`	The number of adversary robots in the simulation.	`0`
`color_team`	`str`	The color of the agent team ("blue" or "yellow").	`'blue'`

`close()`

Closes the Pygame window and quits Pygame.

`render()`

Renders the environment.

Returns:

Type	Description
`Optional[ndarray]`	An RGB array if render_mode is "rgb_array", otherwise None.

`reset(seed=None, options=None)`

Resets the environment to an initial state.

Parameters:

Name	Type	Description	Default
`seed`	`Optional[int]`	An optional seed for the random number generator.	`None`

Returns:

Type	Description
`Tuple[Any, Dict[Any, Any]]`	A tuple containing the initial observation and an info dictionary.

`step(action, adversary_actions=None)`

Performs one step in the environment using the given action.

Parameters:

Name	Type	Description	Default
`action`	`ndarray`	The action to be taken by the agent(s).	required
`adversary_actions`	`Optional[ndarray]`	Optional action array for adversary robots.	`None`

Returns:

Type	Description
`Tuple[tuple, float, bool, bool, Dict[Any, Any]]`	A tuple containing the observation, reward, terminated flag, truncated flag, and info dictionary.

Bases: BaseVSSSEnv, ParallelEnv

PettingZoo environment for Very Small Size Soccer (VSSS).

This environment provides a multi-agent interface compatible with PettingZoo for training multiple agents simultaneously using MADRL algorithms.

Parameters:

Name	Type	Description	Default
`render_mode`	`Optional[str]`	Rendering mode ("human", "rgb_array", or None)	`None`
`scenario`	`str`	Game scenario to use ("formation" or "full_random")	`'formation'`
`num_agent_robots`	`int`	Number of agent robots	`1`
`num_adversary_robots`	`int`	Number of adversary robots	`0`
`color_team`	`str`	Color of agent team ("blue" or "yellow")	`'blue'`

`action_space(agent)` `cached`

Get action space for a specific agent.

`observation_space(agent)` `cached`

Get observation space for a specific agent.

`render()`

Render the environment.

Returns:

Type	Description
`Optional[ndarray]`	RGB array if render_mode is "rgb_array", otherwise None.

`reset(seed=None, options=None)`

Reset environment to initial state.

Parameters:

Name	Type	Description	Default
`seed`	`Optional[int]`	Random seed for reproducibility	`None`
`options`	`Optional[Dict]`	Additional reset options (unused)	`None`

Returns:

Type	Description
`tuple`	Tuple of (observations, infos)

`step(actions, adversary_actions=None)`

Execute one simulation step.

Parameters:

Name	Type	Description	Default
`actions`	`Dict[str, ndarray]`	Dictionary mapping agent names to actions	required
`adversary_actions`	`Optional[ndarray]`	Optional action array for adversary robots.	`None`

Returns:

Type	Description
`tuple`	Tuple of (observations, rewards, terminations, truncations, infos)

Modules Classes

Human-Machine Interface for robot simulation control. Supports keyboard and universally mapped joystick inputs.

Parameters:

Name	Type	Description	Default
`dead_zone`	`float`	The dead zone threshold for joystick analog inputs (0.0 to 1.0).	`0.1`

`call()`

Processes input and returns the current control state.

This method makes the HMI instance callable and should be used in the main control loop. It processes all pending events and updates control variables.

Returns:

Type	Description
`Dict[str, Any]`	Dictionary containing:
`Dict[str, Any]`	actions: numpy array [linear_velocity, angular_velocity]
`Dict[str, Any]`	reset_commanded: boolean indicating if reset was requested
`Dict[str, Any]`	active: boolean indicating if the system should continue running
`Dict[str, Any]`	current_team: string ("blue" or "yellow")
`Dict[str, Any]`	current_robot_id: int
`Dict[str, Any]`	ball_control_mode: boolean

`quit()`

Cleans up and shuts down the HMI system.

`update_robot_list(agent_team_color, agent_movement_types, adversary_movement_types)`

Update the list of controllable robots.

Parameters:

Name	Type	Description	Default
`agent_team_color`	`str`	Color of agent team ("blue" or "yellow")	required
`agent_movement_types`	`List[str]`	List of movement types for agent robots	required
`adversary_movement_types`	`List[str]`	List of movement types for adversary robots	required

API Reference

Core Classes

Base Classes

close()

get_reward()

render(mode=None) abstractmethod

reset(seed=None) abstractmethod

set_ball_velocity(vx, vy)

step(action) abstractmethod

Environment Classes

close()

render(mode=None)

reset(seed=None)

step(action, adversary_actions=None)

close()

render()

reset(seed=None, options=None)

step(action, adversary_actions=None)

action_space(agent) cached

observation_space(agent) cached

render()

reset(seed=None, options=None)

step(actions, adversary_actions=None)

Modules Classes

__call__()

quit()

update_robot_list(agent_team_color, agent_movement_types, adversary_movement_types)

`close()`

`get_reward()`

`render(mode=None)` `abstractmethod`

`reset(seed=None)` `abstractmethod`

`set_ball_velocity(vx, vy)`

`step(action)` `abstractmethod`

`close()`

`render(mode=None)`

`reset(seed=None)`

`step(action, adversary_actions=None)`

`close()`

`render()`

`reset(seed=None, options=None)`

`step(action, adversary_actions=None)`

`action_space(agent)` `cached`

`observation_space(agent)` `cached`

`render()`

`reset(seed=None, options=None)`

`step(actions, adversary_actions=None)`

`call()`

`quit()`

`update_robot_list(agent_team_color, agent_movement_types, adversary_movement_types)`