Quick Start

This guide walks you through installing PyBulletFleet, running your first simulation, and understanding the key configuration options.

Prerequisites

Make sure you have the following installed:

Python 3.10+
PyBullet — physics engine backend
NumPy — numerical operations
PyYAML — configuration file parsing

All dependencies are installed automatically during the package install step below.

Installation

From PyPI (recommended)

pip install pybullet-fleet

From source (for development)

Clone the repository and install in editable mode with development dependencies:

git clone https://github.com/yuokamoto/PyBulletFleet.git
cd PyBulletFleet
pip install -e ".[dev]"

This makes the pybullet_fleet package importable from anywhere while keeping the source editable.

Running Your First Simulation

Launch the 100-robot grid demo:

python examples/scale/100robots_grid_demo.py

You should see a PyBullet GUI window open with 100 robots spawned in a grid formation. Each robot navigates toward a randomly assigned goal using kinematic teleportation.

YAML Configuration Basics

Simulation behaviour is controlled via YAML config files. The default configuration lives at config/config.yaml.

Key settings you will want to tweak:

Setting	Type	Default	Description
`gui`	bool	`true`	Open the PyBullet GUI window
`target_rtf`	float	`100`	Target Real-Time Factor (1.0 = real time, 0 = max speed)
`timestep`	float	`0.1`	Seconds per simulation step
`physics`	bool	`false`	Enable PyBullet physics engine (off for pure kinematic mode)
`collision_detection_method`	string	`"closest_points"`	`"closest_points"`, `"contact_points"`, or `"hybrid"`
`collision_safety_margin`	float	`0.02`	Safety buffer in metres for near-miss detection
`monitor`	bool	`true`	Enable the real-time data monitor
`enable_time_profiling`	bool	`true`	Print step-timing reports
`enable_floor`	bool	`true`	Load the default ground plane (`plane.urdf`). Set `false` for custom floor handling

Example — run headless at 10× real-time with physics enabled:

gui: false
target_rtf: 10
physics: true
collision_detection_method: "contact_points"

See config/config.yaml for the full list of parameters — every key is documented with inline comments.

Keyboard Controls

When running with gui: true, the following shortcuts are available:

Key	Action	Description
`SPACE`	Pause / Resume	Toggle simulation pause
`v`	Visual shapes	Toggle visual shapes ON/OFF
`c`	Collision shapes	Toggle collision wireframes ON/OFF
`t`	Transparency	Toggle structure transparency ON/OFF

Note

The t key toggles transparency one object at a time. For scenes with hundreds of objects this can be slow — prefer setting enable_structure_transparency in the config file instead.

Examples

All example scripts live in the examples/ directory, organised by category. For step-by-step walkthroughs, see the Tutorials page.

Basics (`examples/basics/`)

Script	Description
`robot_demo.py`	Basic robot creation with `Agent.from_mesh()` / `Agent.from_urdf()`
`action_system_demo.py`	High-level action system (MoveTo, Pick, Drop, Wait)
`collision_features_demo.py`	Spatial-hash collision detection features and visualisation
`memory_profiling_demo.py`	Memory usage tracking and profiling utilities

Arm (`examples/arm/`)

Script	Description
`pick_drop_arm_demo.py`	Single arm robot performing pick-and-drop operations
`pick_drop_arm_action_demo.py`	Arm robot using the action system for pick-and-drop
`pick_drop_arm_ee_demo.py`	Arm end-effector control via IK (low-level callback)
`pick_drop_arm_ee_action_demo.py`	Arm EE control using PoseAction (action queue)
`rail_arm_demo.py`	Rail arm (prismatic + revolute) pick-and-drop with EE control
`mobile_manipulator_demo.py`	Kinematic mobile manipulator — IK-based pick/drop with arm + base movement

Mobile (`examples/mobile/`)

Script	Description
`path_following_demo.py`	Compares omnidirectional and differential-drive motion modes

Scale (`examples/scale/`)

Script	Description
`100robots_grid_demo.py`	Grid-based multi-agent demo — best starting point
`100robots_cube_patrol_demo.py`	100 agents patrolling between cubes
`pick_drop_arm_100robots_demo.py`	100 arm robots with synchronised pick-and-drop
`pick_drop_mobile_100robots_demo.py`	100 mobile robots picking and dropping objects

Models (`examples/models/`)

Script	Description
`resolve_urdf_demo.py`	URDF resolution patterns — by name, by path, and listing all models
`model_catalog_demo.py`	Visual grid catalog of all registered models from `KNOWN_MODELS`
`robot_descriptions_demo.py`	Using Tier 3 models from the `robot_descriptions` pip package

Run any example with:

python examples/<category>/<script_name>.py

Next Steps

Architecture overview — Architecture Overview explains the core abstractions (simulation core, agents, actions, collision).
How-to guides — see the docs/ directory for topic-specific guides (collision tuning, memory profiling, performance optimisation).
Configuration reference — config/config.yaml documents every YAML key with inline comments. See also the Configuration Files Guide.
API reference — auto-generated from docstrings (coming soon).