pSim 0.2.4

A pythonic Very Small Size Soccer (VSSS) simulation environment for reinforcement learning research.

pSim

pSim: Very Small Size Soccer Simulation Environment

Comprehensive simulation platform for autonomous robotic soccer development

---

Welcome to pSim

pSim is a comprehensive, pythonic simulation environment specifically designed for the Very Small Size Soccer (VSSS) competition. It provides researchers, students, and developers with powerful tools to develop, test, and validate autonomous robotic soccer strategies and algorithms.

Whether you're working on traditional control algorithms, reinforcement learning, or multi-agent coordination, pSim offers the flexibility and performance you need.

---

Quick Start

Installation

pSim uses uv for fast, reliable package management. See the installation guide for complete setup instructions including uv installation.

# Quick install with uv
uv venv --python 3.12
uv pip install pSim[all] --upgrade

# Or, after venv only install a specific dependency
uv pip install pSim[gym]   # For Gymnasium support
uv pip install pSim[zoo]   # For PettingZoo support
uv pip install pSim[all]   # For both Gymnasium and PettingZoo

First Simulation

from pSim import SimpleVSSSEnv
import numpy as np

# Create your first simulation with custom robot counts
env = SimpleVSSSEnv(
    render_mode="human",
    scenario="formation",
    num_agent_robots=2,      # Number of controllable robots
    num_adversary_robots=3   # Number of opponent robots
)
obs, info = env.reset()

# Run simulation steps with random actions
for step in range(1000):
    # Generate random actions for all agent robots [v, w] (velocity, angular velocity)
    action = np.random.uniform(-1, 1, (env.num_agent_robots, 2))
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()

env.close()

---

Environment Types

pSim provides three main environment types, each designed for different use cases:

• SimpleVSSSEnv: For traditional control and testing.

Single robot simulation environment

Full team match with complete team

• VSSSGymEnv: For reinforcement learning with Gymnasium compatibility.

Single robot reinforcement learning

Single robot in competition

• VSSSPettingZooEnv: For multi-agent reinforcement learning with PettingZoo compatibility.

Cooperative Two Agents

Competitive Three Agents

Three vs Three Roles

Competitive Two Agents

Features

Traditional Control

• PID controllers, MPC, and other traditional methods
• Path planning and trajectory optimization
• Formation control and cooperative behaviors

Reinforcement Learning

• Compatible with Stable Baselines 3, Ray RLlib, and other RL libraries
• Customizable reward functions and observation spaces
• Curriculum learning through scenario configuration

Research & Education

• Multi-agent coordination studies
• Emergent behavior analysis
• Algorithm benchmarking and comparison

Competition Preparation

• Strategy development and testing
• Opponent modeling and adaptation
• Performance analysis and optimization

Realistic Physics

Box2D-powered physics simulation with customizable parameters for accurate robot and ball dynamics.

Human-Machine Interface

• Keyboard Controls: Full keyboard input with intuitive mappings
• Joystick Support: Universal controller compatibility
• Robot Switching: Dynamic selection between controllable robots
• Team Management: Control different teams independently
• Ball Control Mode: Direct ball manipulation

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation

---

Contributing

We welcome contributions! Please see our Contributing Guide for details.