How-to Guides

Practical guides for common tasks.

📘 For Simulation Users — building and configuring your own simulation:

Guide	What It Covers
Collision Configuration	Detection method, per-object modes, margin, cell size, multi-cell threshold
Controller Configuration	controller argument forms, motion_mode vs controller.type, batch controllers (auto-registration, coexistence, direction, action system), custom controllers
Custom Profiling	Adding your own profiling metrics via Agent/SimulationCore subclasses
Capturing Demos	Recording demo videos, demos.yaml format, centralized defaults (_defaults.py)

🔧 For PyBulletFleet Developers — developing and debugging the framework:

Guide	Measures	Detects	Tool	Overhead
Time Profiling	Execution time (ms)	Performance bottlenecks	time.perf_counter()	< 0.1% CPU
Memory Profiling	Memory usage (MB)	Memory leaks, high usage	tracemalloc (built-in)	~5–10% memory
Logging	Log messages	Configuration & runtime issues	Python logging	Negligible

Tip: Time and memory profiling can be enabled simultaneously for comprehensive analysis. Both share the profiling_interval setting.

For Simulation Users

• Collision Configuration Guide
  • Quick Decision Guide
  • Collision Detection Method
  • Per-Object Collision Mode
  • Collision Margin
  • Spatial Hash Cell Size
  • Multi-Cell Threshold
  • Complete YAML Reference
  • See Also
• Controller Configuration
  • TL;DR — Five ways to specify a controller
  • Recommended pattern — pick by use case
  • The five accepted forms of controller
  • Two-step build inside Agent.__init__
  • motion_mode vs controller.type
  • ControllerParams — shared parameters for every controller
  • Passing the same controller value at every layer
  • Batch Controllers
  • Adding a custom controller
• Custom Class Profiling Guide
  • Overview
  • Approach 1: Built-in Profiling (Recommended First Step)
  • Approach 2: cProfile (Find Slow Custom Functions)
  • Approach 3: Standalone perf_counter (Per-Agent, Non-Integrated)
  • Comparing Custom vs Base Performance
  • Tips
  • See Also
• Capturing Demo Videos
  • Capture Pipeline Overview
  • Python API
  • Environment Variable
  • Batch Capture Scripts

For PyBulletFleet Developers

• Time Profiling User Guide
  • Overview
  • Quick Start
  • Configuration Reference
  • Interpreting Results
  • Programmatic Access
  • Best Practices
  • Troubleshooting
  • Benchmark scripts
  • References
• Memory Profiling User Guide
  • Overview
  • Quick Start
  • API Reference
  • Understanding Memory Statistics
  • Use Case: Detecting Memory Leaks in Long-Running Simulations
  • Best Practices
  • Performance Impact
  • Troubleshooting
  • Example Output
  • References
• Logging Utilities - Usage Guide
  • Overview
  • Performance Impact
  • When to Use Lazy Logging
  • Usage Examples
  • API Reference
  • Testing
  • Best Practices
  • Performance Tips
  • Migration Checklist
  • Related Files