box2d_rust/world/
mod.rs

1// Port of the world data model from box2d-cpp-reference/src/physics_world.h
2// (b2World, b2TaskContext) plus b2Profile from types.h. Logic from
3// physics_world.c lands across the remaining bring-up commits.
4//
5// Porting decisions:
6// - C keeps a global world registry (b2_worlds[B2_MAX_WORLDS], ids into it).
7//   The Rust `World` is an owned object instead; `world_id`/`generation` are
8//   kept so body/shape/joint ids remain bit-compatible with C. A registry
9//   would force global mutable state through every call; ownership is the
10//   sound Rust equivalent with identical observable behavior inside a world.
11// - The arena allocator (b2Stack) is per-step scratch for performance; the
12//   Rust solver allocates its scratch as Vecs in the step, so there is no
13//   stack field.
14// - Scheduler/task-system fields (enqueueTask, finishTask, userTaskContext,
15//   userTreeTask, scheduler, activeTaskCount, taskCount) are deferred with the
16//   single-threaded port; worker_count is kept and clamped like C.
17// - b2Recording is the snapshot/replay subsystem, ported later; no field yet.
18// - Pre-solve and custom-filter callbacks keep the C shape as Option<fn> with
19//   a u64 context.
20//
21// SPDX-FileCopyrightText: 2023 Erin Catto
22// SPDX-License-Identifier: MIT
23
24use crate::bitset::BitSet;
25use crate::body::Body;
26use crate::broad_phase::BroadPhase;
27use crate::constraint_graph::ConstraintGraph;
28use crate::contact::Contact;
29use crate::events::{
30    BodyMoveEvent, ContactBeginTouchEvent, ContactEndTouchEvent, ContactHitEvent, JointEvent,
31    SensorBeginTouchEvent, SensorEndTouchEvent,
32};
33use crate::id::ShapeId;
34use crate::id_pool::IdPool;
35use crate::island::Island;
36use crate::joint::Joint;
37use crate::math_functions::{Pos, Vec2};
38use crate::sensor::{Sensor, SensorHit, SensorTaskContext};
39use crate::shape::{ChainShape, Shape};
40use crate::solver_set::SolverSet;
41use crate::types::{Capacity, FrictionCallback, RestitutionCallback};
42
43/// Prototype for a contact filter callback. Called when a contact pair is
44/// considered for collision, if one of the two shapes has custom filtering
45/// enabled. Return false to disable the collision. (b2CustomFilterFcn)
46pub type CustomFilterFcn = fn(ShapeId, ShapeId, u64) -> bool;
47
48/// Prototype for a pre-solve callback. Called after a contact is updated, only
49/// for awake dynamic bodies with pre-solve events enabled. Return false to
50/// disable the contact this step. (b2PreSolveFcn)
51pub type PreSolveFcn = fn(ShapeId, ShapeId, Pos, Vec2, u64) -> bool;
52
53/// Profiling data. Times are in milliseconds. (b2Profile)
54#[derive(Debug, Clone, Copy, PartialEq, Default)]
55pub struct Profile {
56    pub step: f32,
57    pub pairs: f32,
58    pub collide: f32,
59    pub solve: f32,
60    pub solver_setup: f32,
61    pub constraints: f32,
62    pub prepare_constraints: f32,
63    pub integrate_velocities: f32,
64    pub warm_start: f32,
65    pub solve_impulses: f32,
66    pub integrate_positions: f32,
67    pub relax_impulses: f32,
68    pub apply_restitution: f32,
69    pub store_impulses: f32,
70    pub split_islands: f32,
71    pub transforms: f32,
72    pub sensor_hits: f32,
73    pub joint_events: f32,
74    pub hit_events: f32,
75    pub refit: f32,
76    pub bullets: f32,
77    pub sleep_islands: f32,
78    pub sensors: f32,
79}
80
81/// Per thread task storage. (b2TaskContext)
82#[derive(Debug, Clone, Default)]
83pub struct TaskContext {
84    /// Collect per thread sensor continuous hit events.
85    pub sensor_hits: Vec<SensorHit>,
86
87    /// These bits align with the contact id capacity and signal a change in
88    /// contact status.
89    pub contact_state_bit_set: BitSet,
90
91    /// These bits align with the contact id capacity and signal a hit event.
92    pub hit_event_bit_set: BitSet,
93
94    /// Fast-path flag: true when this worker set at least one bit in
95    /// hit_event_bit_set this step.
96    pub has_hit_events: bool,
97
98    /// These bits align with the joint id capacity and signal a change in
99    /// joint status.
100    pub joint_state_bit_set: BitSet,
101
102    /// Used to track bodies with shapes that have enlarged AABBs. This avoids
103    /// a bit array that is very large when there are many static shapes.
104    pub enlarged_sim_bit_set: BitSet,
105
106    /// Used to put islands to sleep.
107    pub awake_island_bit_set: BitSet,
108
109    /// Per worker split island candidate.
110    pub split_sleep_time: f32,
111    pub split_island_id: i32,
112
113    /// Number of contacts recycled this step (collide pass).
114    pub recycled_contact_count: i32,
115}
116
117/// The world struct manages all physics entities, dynamic simulation, and
118/// asynchronous queries. (b2World)
119#[derive(Debug)]
120pub struct World {
121    pub broad_phase: BroadPhase,
122    pub constraint_graph: ConstraintGraph,
123
124    /// The body id pool allocates and recycles body ids. Body ids provide a
125    /// stable identifier for users. Aligns with `bodies`.
126    pub body_id_pool: IdPool,
127
128    /// Sparse array mapping body ids to the body data stored in solver sets.
129    pub bodies: Vec<Body>,
130
131    /// Provides free list for solver sets.
132    pub solver_set_id_pool: IdPool,
133
134    /// Solver sets store sims in contiguous arrays. Set 0 is static, set 1 is
135    /// disabled, set 2 is awake; the rest are sleeping islands.
136    pub solver_sets: Vec<SolverSet>,
137
138    /// Used to create stable ids for joints.
139    pub joint_id_pool: IdPool,
140
141    /// Sparse array mapping joint ids to joints in the constraint graph or
142    /// solver sets.
143    pub joints: Vec<Joint>,
144
145    /// Used to create stable ids for contacts.
146    pub contact_id_pool: IdPool,
147
148    /// Sparse array mapping contact ids to contacts in the constraint graph
149    /// or solver sets.
150    pub contacts: Vec<Contact>,
151
152    /// Used to create stable ids for islands.
153    pub island_id_pool: IdPool,
154
155    /// Persistent islands.
156    pub islands: Vec<Island>,
157
158    pub shape_id_pool: IdPool,
159    pub chain_id_pool: IdPool,
160
161    /// Sparse arrays that point into the pools above.
162    pub shapes: Vec<Shape>,
163    pub chain_shapes: Vec<ChainShape>,
164
165    /// Dense array of sensor data.
166    pub sensors: Vec<Sensor>,
167
168    /// Per thread storage (one entry in the single-threaded port).
169    pub task_contexts: Vec<TaskContext>,
170    pub sensor_task_contexts: Vec<SensorTaskContext>,
171
172    pub body_move_events: Vec<BodyMoveEvent>,
173    pub sensor_begin_events: Vec<SensorBeginTouchEvent>,
174    pub contact_begin_events: Vec<ContactBeginTouchEvent>,
175
176    /// End events are double buffered so that the user doesn't need to flush
177    /// events.
178    pub sensor_end_events: [Vec<SensorEndTouchEvent>; 2],
179    pub contact_end_events: [Vec<ContactEndTouchEvent>; 2],
180    pub end_event_array_index: i32,
181
182    pub contact_hit_events: Vec<ContactHitEvent>,
183    pub joint_events: Vec<JointEvent>,
184
185    /// Used to track debug draw.
186    pub debug_body_set: BitSet,
187    pub debug_joint_set: BitSet,
188    pub debug_contact_set: BitSet,
189    pub debug_island_set: BitSet,
190
191    /// Id that is incremented every time step.
192    pub step_index: u64,
193
194    /// Identify islands for splitting.
195    pub split_island_id: i32,
196
197    pub gravity: Vec2,
198    pub hit_event_threshold: f32,
199    pub restitution_threshold: f32,
200    pub max_linear_speed: f32,
201    pub contact_speed: f32,
202    pub contact_hertz: f32,
203    pub contact_damping_ratio: f32,
204    pub contact_recycle_distance: f32,
205
206    pub friction_callback: Option<FrictionCallback>,
207    pub restitution_callback: Option<RestitutionCallback>,
208
209    pub generation: u16,
210
211    pub profile: Profile,
212
213    pub max_capacity: Capacity,
214
215    pub pre_solve_fcn: Option<PreSolveFcn>,
216    pub pre_solve_context: u64,
217
218    pub custom_filter_fcn: Option<CustomFilterFcn>,
219    pub custom_filter_context: u64,
220
221    pub worker_count: i32,
222
223    pub user_data: u64,
224
225    /// Inverse sub-step, remembered for reporting forces and torques.
226    pub inv_h: f32,
227
228    /// Inverse full-step.
229    pub inv_dt: f32,
230
231    pub world_id: u16,
232
233    pub enable_sleep: bool,
234    pub locked: bool,
235    pub enable_warm_starting: bool,
236    pub enable_contact_softening: bool,
237    pub enable_continuous: bool,
238    pub enable_speculative: bool,
239    pub in_use: bool,
240}
241
242/// Default friction mixing: `sqrt(frictionA * frictionB)`.
243/// (static b2DefaultFrictionCallback)
244pub fn default_friction_callback(
245    friction_a: f32,
246    _material_a: u64,
247    friction_b: f32,
248    _material_b: u64,
249) -> f32 {
250    (friction_a * friction_b).sqrt()
251}
252
253/// Default restitution mixing: `max(restitutionA, restitutionB)`.
254/// (static b2DefaultRestitutionCallback)
255pub fn default_restitution_callback(
256    restitution_a: f32,
257    _material_a: u64,
258    restitution_b: f32,
259    _material_b: u64,
260) -> f32 {
261    crate::math_functions::max_float(restitution_a, restitution_b)
262}
263
264impl World {
265    /// Create a world. (b2CreateWorld)
266    ///
267    /// Differences from C, all documented in the module header: there is no
268    /// global world registry (the returned World is owned; `world_id` stays 0
269    /// unless the embedder assigns one), no arena stack, and the serial task
270    /// path is always used (worker_count = 1 with one task context), which is
271    /// the C fallback when no task system is supplied.
272    pub fn new(def: &crate::types::WorldDef) -> World {
273        use crate::constants::contact_recycle_distance;
274        use crate::constraint_graph::ConstraintGraph;
275        use crate::math_functions::max_int;
276
277        debug_assert!(def.internal_value == crate::core::SECRET_COOKIE);
278
279        let body_capacity = max_int(
280            16,
281            def.capacity.static_body_count + def.capacity.dynamic_body_count,
282        ) as usize;
283        let shape_capacity = max_int(
284            16,
285            def.capacity.static_shape_count + def.capacity.dynamic_shape_count,
286        ) as usize;
287        let contact_capacity = max_int(16, def.capacity.contact_count) as usize;
288
289        let mut solver_set_id_pool = IdPool::new();
290        let mut solver_sets: Vec<SolverSet> = Vec::with_capacity(8);
291
292        // add empty static, disabled, and awake body sets
293        // static set
294        let mut set = SolverSet {
295            set_index: solver_set_id_pool.alloc_id(),
296            ..Default::default()
297        };
298        set.body_sims
299            .reserve(max_int(16, def.capacity.static_body_count) as usize);
300        solver_sets.push(set);
301        debug_assert!(
302            solver_sets[crate::solver_set::STATIC_SET as usize].set_index
303                == crate::solver_set::STATIC_SET
304        );
305
306        // disabled set
307        solver_sets.push(SolverSet {
308            set_index: solver_set_id_pool.alloc_id(),
309            ..Default::default()
310        });
311        debug_assert!(
312            solver_sets[crate::solver_set::DISABLED_SET as usize].set_index
313                == crate::solver_set::DISABLED_SET
314        );
315
316        // awake set
317        let mut awake = SolverSet {
318            set_index: solver_set_id_pool.alloc_id(),
319            ..Default::default()
320        };
321        awake
322            .body_sims
323            .reserve(max_int(16, def.capacity.dynamic_body_count) as usize);
324        awake
325            .body_states
326            .reserve(max_int(16, def.capacity.dynamic_body_count) as usize);
327        awake.contact_sims.reserve(contact_capacity);
328        solver_sets.push(awake);
329        debug_assert!(
330            solver_sets[crate::solver_set::AWAKE_SET as usize].set_index
331                == crate::solver_set::AWAKE_SET
332        );
333
334        World {
335            broad_phase: BroadPhase::new(&def.capacity),
336            constraint_graph: ConstraintGraph::new(&def.capacity),
337            body_id_pool: IdPool::new(),
338            bodies: Vec::with_capacity(body_capacity),
339            solver_set_id_pool,
340            solver_sets,
341            joint_id_pool: IdPool::new(),
342            joints: Vec::with_capacity(16),
343            contact_id_pool: IdPool::new(),
344            contacts: Vec::with_capacity(contact_capacity),
345            island_id_pool: IdPool::new(),
346            islands: Vec::with_capacity(max_int(16, def.capacity.dynamic_body_count) as usize),
347            shape_id_pool: IdPool::new(),
348            chain_id_pool: IdPool::new(),
349            shapes: Vec::with_capacity(shape_capacity),
350            chain_shapes: Vec::with_capacity(4),
351            sensors: Vec::with_capacity(4),
352            // Serial fallback: one worker context. (b2CreateWorkerContexts)
353            task_contexts: vec![TaskContext::default()],
354            sensor_task_contexts: vec![SensorTaskContext::default()],
355            body_move_events: Vec::with_capacity(4),
356            sensor_begin_events: Vec::with_capacity(4),
357            contact_begin_events: Vec::with_capacity(4),
358            sensor_end_events: [Vec::with_capacity(4), Vec::with_capacity(4)],
359            contact_end_events: [Vec::with_capacity(4), Vec::with_capacity(4)],
360            end_event_array_index: 0,
361            contact_hit_events: Vec::with_capacity(4),
362            joint_events: Vec::with_capacity(4),
363            debug_body_set: BitSet::new(256),
364            debug_joint_set: BitSet::new(256),
365            debug_contact_set: BitSet::new(256),
366            debug_island_set: BitSet::new(256),
367            step_index: 0,
368            split_island_id: crate::core::NULL_INDEX,
369            gravity: def.gravity,
370            hit_event_threshold: def.hit_event_threshold,
371            restitution_threshold: def.restitution_threshold,
372            max_linear_speed: def.maximum_linear_speed,
373            contact_speed: def.contact_speed,
374            contact_hertz: def.contact_hertz,
375            contact_damping_ratio: def.contact_damping_ratio,
376            contact_recycle_distance: contact_recycle_distance(),
377            friction_callback: Some(def.friction_callback.unwrap_or(default_friction_callback)),
378            restitution_callback: Some(
379                def.restitution_callback
380                    .unwrap_or(default_restitution_callback),
381            ),
382            generation: 0,
383            profile: Profile::default(),
384            max_capacity: def.capacity,
385            pre_solve_fcn: None,
386            pre_solve_context: 0,
387            custom_filter_fcn: None,
388            custom_filter_context: 0,
389            worker_count: 1,
390            user_data: def.user_data,
391            inv_h: 0.0,
392            inv_dt: 0.0,
393            world_id: 0,
394            enable_sleep: def.enable_sleep,
395            locked: false,
396            enable_warm_starting: true,
397            enable_contact_softening: def.enable_contact_softening,
398            enable_continuous: def.enable_continuous,
399            enable_speculative: true,
400            in_use: true,
401        }
402    }
403
404    /// Validate the solver-set bookkeeping. (b2ValidateSolverSets)
405    ///
406    /// bring-up: the C version (physics_world.c, compiled only with
407    /// B2_ENABLE_VALIDATION) also cross-checks contacts, joints, and graph
408    /// colors; those checks are added as their slices land. This subset
409    /// validates the body <-> sim <-> set <-> island mapping.
410    pub fn validate_solver_sets(&self) {
411        use crate::core::NULL_INDEX;
412
413        let mut active_body_count = 0;
414        for (set_index, set) in self.solver_sets.iter().enumerate() {
415            if set.set_index == NULL_INDEX {
416                // free slot
417                debug_assert!(set.body_sims.is_empty());
418                debug_assert!(set.body_states.is_empty());
419                debug_assert!(set.island_sims.is_empty());
420                continue;
421            }
422
423            debug_assert!(set.set_index == set_index as i32);
424
425            if set_index == crate::solver_set::AWAKE_SET as usize {
426                debug_assert!(set.body_sims.len() == set.body_states.len());
427            } else {
428                debug_assert!(set.body_states.is_empty());
429            }
430
431            for (local_index, sim) in set.body_sims.iter().enumerate() {
432                let body = &self.bodies[sim.body_id as usize];
433                debug_assert!(body.set_index == set_index as i32);
434                debug_assert!(body.local_index == local_index as i32);
435                debug_assert!(body.id == sim.body_id);
436                let _ = (body, local_index);
437            }
438            active_body_count += set.body_sims.len() as i32;
439
440            for (local_index, island_sim) in set.island_sims.iter().enumerate() {
441                let island = &self.islands[island_sim.island_id as usize];
442                debug_assert!(island.set_index == set_index as i32);
443                debug_assert!(island.local_index == local_index as i32);
444                let _ = (island, local_index);
445            }
446        }
447
448        debug_assert!(active_body_count == self.body_id_pool.id_count());
449        let _ = active_body_count;
450    }
451}
452
453mod step;
454
455pub use step::*;
box2d_rust/world/mod.rs

box2d_rust/world/
mod.rs
