Two-Phase Step
PyBulletFleet’s step_once() exposes a two-phase pose-commit contract.
This page explains that contract, the following synchronization work, and what
they mean for callback / plugin authors.
If you only call high-level APIs (
Agent.add_action,controller.set_velocity,agent.get_pose), the two-phase split is fully transparent — you do not need to change any code. This page is for callback / plugin / ROS-bridge authors who interact with poses or PyBullet directly inside a step.
Design rationale
Separating base-pose computation from the corresponding PyBullet C-API writes lets the simulator:
batch pose writes for N agents in one pass (
set_poses()),vectorize per-agent compute with NumPy across N agents,
guarantee that collision detection always sees a consistent world snapshot (all writes applied, all AABBs refreshed) within a single step.
Two-phase pose commit in the full step timeline
step_once()
├── PHASE 1 — UPDATE (base-pose writes are buffered)
│ ├── pre_step event (before the clock advances; three tiers, in this order)
│ │ ├── handlers (events.on(SimEvents.PRE_STEP, ...), by priority)
│ │ ├── user callbacks (register_callback(..., phase="pre_step"), registration order)
│ │ └── plugin on_step hooks (plugins with step_phase "pre_step", load order)
│ ├── clock advances (sim_time and step_count of the new state)
│ ├── for manager with a batch controller: batch_advance(dt)
│ ├── for obj in sim_objects: obj.update(dt)
│ │ └── controller.compute → agent.set_pose(...) ← buffered
│ └── step event (one event, three tiers, in this order)
│ ├── handlers (events.on(SimEvents.STEP, ...), by priority)
│ ├── user callbacks (register_callback(...), registration order)
│ └── plugin on_step hooks (plugins with step_phase "step", the default; load order)
│
├── PHASE 2 — POSE FLUSH (tight C-API loop)
│ └── for obj_id in _pending_pose_ids:
│ p.resetBasePositionAndOrientation(...)
│ └── recompute and flush link-attached children after their parent moves
│
├── stepSimulation() (only when physics is enabled)
│ └── refresh AABBs + spatial grid for physics-driven objects
│
├── POST-COMMIT SYNCHRONIZATION
│ └── for each flushed kinematic object:
│ refresh AABB (p.getAABB)
│ update spatial-hash grid
│
├── check_collisions (frequency-gated; sees up-to-date AABBs/grid)
├── post_step event (three tiers, in this order)
│ ├── handlers (events.on(SimEvents.POST_STEP, ...), by priority)
│ ├── user callbacks (register_callback(..., phase="post_step"), registration order)
│ └── plugin on_step hooks (plugins with step_phase "post_step", load order)
└── monitor update
The set of objects with pending base-pose writes (_pending_pose_ids) is built
up during Phase 1, snapshotted for pose commit and post-commit synchronization,
and then cleared. Link-attached
children may add a second, internal flush after their parent’s new base pose is
visible to PyBullet.
set_pose() behaviour: buffered vs immediate
Calls to SimObject.set_pose() (and agent.set_pose_raw()) behave
differently depending on when they are made:
When |
Behaviour |
|---|---|
Outside |
Immediate — writes to PyBullet right away. |
Inside |
Buffered — only the cache is updated; the actual PyBullet base pose is written at Phase 2 later in the same step. |
The buffering rule applies to every movable SimObject that calls set_pose()
inside the step, including a physics-driven object that is explicitly
teleported. In normal use, kinematic objects are moved through this path;
physics-driven bodies should be allowed to move through stepSimulation()
instead of receiving repeated pose writes.
For a buffered kinematic write, the framework cache is the source of truth mid-step, so:
✅
agent.get_pose()/sim_object.get_pose()— returns the new cached pose.⚠️
p.getBasePositionAndOrientation(object_id)— returns the previous step’s pose during Phase 1, because PyBullet hasn’t been written yet.⚠️ PyBullet AABB queries and the framework collision/spatial-grid caches are not a same-step pose API. The framework refreshes kinematic AABBs and grid entries during post-commit synchronization, after the base-pose flush.
Rule of thumb
Inside a callback or plugin
on_step, always use the framework getter (agent.get_pose(),sim_object.get_pose()), never the raw PyBullet API.
If you genuinely need PyBullet to reflect the latest pose mid-step (e.g. for a
raycast against just-moved agents), subscribe to the POST_STEP event or defer
the operation to the next step — by then Phase 2 has flushed:
from pybullet_fleet.events import SimEvents
sim.events.on(SimEvents.POST_STEP, on_post_step)
register_callback() runs in Phase 1 by default. Pass
phase=CallbackPhase.POST_STEP (or "post_step") for
a callback that runs right after the POST_STEP event, with its own
frequency – for example to publish or record each step’s outcome at a fixed
rate. Its schedule runs on sim_time, the time of the state it sees, so a 10 Hz
post-step callback runs when the poses reach 0.1 s, 0.2 s, …
set_pose() from a POST_STEP handler or a post-step callback writes to
PyBullet at once, but the step’s collision check has already run. A collision
such a write causes is found by the next collision check.
Which time a pose belongs to
One rule: sim_core.sim_time (and step_count) is the time (and step) of
the state you see. step_once() advances the clock and the step counter
right after the pre_step event, before anything computes the new state:
Where |
|
State it describes |
|---|---|---|
|
previous step, |
the previous step’s state |
object update, |
new step, |
being computed for |
collision check, |
|
the step’s result |
outside a step |
completed step, |
the completed step’s result |
pre_step is the only place that still sees the previous step. Everything
read anywhere else – a pose, an action’s start or end time, a collision
observation – is stamped correctly with sim_time.
A step that raises (an exception from a Phase-1 callback, say) propagates the exception and leaves the simulation in an unspecified state; nothing is rolled back.
sim_time is a read-only view of the simulation’s single clock. Outside a step it
equals the completed boundary returned by get_completed_step_boundary(). The
only supported way to move the clock is restore_completed_step_boundary(),
when resuming a fresh simulation from a checkpoint.
Position controllers evaluate their trajectories at sim_time, so the pose a
step ends with is the trajectory at the end of the step, the same rule
kinematic joints follow. A trajectory started now begins at sim_time: a path
set in a pre_step subscriber therefore moves in that same step; one set later
in the step, or outside it, moves from the next step. With Agent.set_path()’s
default auto_approach=True (which set_goal_pose() uses), a goal more than
0.5 m away gets the current pose as a zero-length first waypoint, and that
waypoint takes the first step.
A goal replaced mid-motion continues from the speed of the pose in effect at
sim_time.
Frequency-limited handlers
Callbacks and plugins with a frequency, collision_check_frequency and the
DataMonitor refresh run on a fixed grid of simulated time, k / frequency
seconds from the start of the run: on the first step at or after each due
time, at most once per step. A handler registered mid-run first runs at the
next due time; missed due times never cause a burst of runs. The schedule
reads the time as the step count times the timestep (counted again from any
change of timestep or restore) rather than the accumulated simulation time,
whose float error grows with the run, and tolerates the rounding left. So a
10 Hz handler on a 0.1 s timestep runs every step, however long the run, and
an interval that is not a whole number of timesteps does not drift.
What Phase 1 does not promise
Phase 1 batches framework base-pose writes. It is not a general prohibition on PyBullet calls: joint control may issue PyBullet calls, and application callbacks/plugins can call PyBullet directly. Framework extensions should avoid direct base-pose and AABB reads/writes in Phase 1 when they require a same-step-consistent scene; use the framework pose APIs and the post-step event instead.
Profiling
The per-step profiling dict (returned by MultiRobotSimulationCore.get_profiling_stats())
exposes the phase split:
Key |
What it measures |
|---|---|
|
End-to-end Phase 1 wall time (pre-step events → batch-controller advance → object update loop → callbacks → plugin hooks). Framework base-pose writes are buffered, but joint-control or user PyBullet calls may still occur. |
|
Time spent writing buffered poses to PyBullet ( |
|
|
|
Time spent refreshing AABBs and spatial-hash grid entries for the kinematic objects flushed in Phase 2. This is the implementation/profiling key; conceptually it is post-commit synchronization, not a third public phase. |
|
Time spent in the per-object |
See also
PyBulletFleet - Design Documentation — overall architecture
Custom Class Profiling Guide — adding your own profiling metrics