boxddd

https://docs.rs/boxddd/0.4.0/boxddd/
Admin
boxddd provides safe, ergonomic Rust bindings for the Box3D physics simulation engine.
Tokens:62,137
Snippets:682
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize and use a RecordingSession

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.RecordingSession.html

Demonstrates how to initialize a foundation, create a world, and start a recording session. Note that attempting to record the same world twice will result in an error.

```rust
use boxddd::{Foundation, Recording};

let foundation = Foundation::initialize_default().unwrap();
let mut world = foundation.create_world(foundation.world_def()).unwrap();
let mut recording = Recording::new().unwrap();
let mut session = world.record(&mut recording).unwrap();
let _second = world.record(&mut recording);
session.finish().unwrap();
```

--------------------------------

### Cloning Result Contents

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Examples of using .cloned() on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Copying Result Contents

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Examples of using .copied() on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### HeightField::builder

Source: https://docs.rs/boxddd/0.4.0/boxddd/shapes/struct.HeightField.html

Starts a height-field builder from row count, column count, and samples.

```APIDOC
## pub fn builder(row_count: i32, column_count: i32, heights: impl Into<Vec<f32>>) -> HeightFieldBuilder

### Description
Starts a height-field builder from row count, column count, and samples.
```

--------------------------------

### Flattening Nested Results

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Examples of flattening nested Result structures.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Conditional Result Checking

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Example of using is_ok_and to check a Result against a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Checking Result Status

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Examples of checking if a Result is Ok or Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Transposing Result

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### Parallel Joint Spring Configuration

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/struct.World.html

Methods for getting and setting physical properties of parallel joints, such as spring frequency, damping ratio, and torque limits.

```APIDOC
## pub fn set_parallel_joint_spring_hertz(&mut self, joint_id: JointId, hertz: f32) -> Result<()>

### Description
Tries to set the spring frequency, in hertz, on a parallel joint. Returns Error::InvalidValue if the joint_id belongs to another joint family, or StaleHandle/ForeignHandle for invalid handles.

## pub fn parallel_joint_spring_hertz(&self, joint_id: JointId) -> Result<f32>

### Description
Returns the spring frequency, in hertz, of a parallel joint.

## pub fn set_parallel_joint_spring_damping_ratio(&mut self, joint_id: JointId, damping_ratio: f32) -> Result<()>

### Description
Tries to set the dimensionless spring damping ratio on a parallel joint.

## pub fn parallel_joint_spring_damping_ratio(&self, joint_id: JointId) -> Result<f32>

### Description
Returns the dimensionless spring damping ratio of a parallel joint.

## pub fn set_parallel_joint_max_torque(&mut self, joint_id: JointId, torque: f32) -> Result<()>

### Description
Tries to set the maximum spring torque, in newton-meters, on a parallel joint.

## pub fn parallel_joint_max_torque(&self, joint_id: JointId) -> Result<f32>

### Description
Returns the maximum spring torque, in newton-meters, of a parallel joint.
```

--------------------------------

### Initialize and simulate a basic Box3D world

Source: https://docs.rs/boxddd

Demonstrates initializing a foundation, creating a world with gravity, adding a static ground body, a dynamic cube body, and performing a simulation step.

```rust
use boxddd::{BodyType, BoxHull, Foundation, Vec3};

let foundation = Foundation::initialize_default()?;
let mut world = foundation.create_world(
    foundation
        .world_def_builder()
        .gravity(Vec3::new(0.0, -10.0, 0.0))
        .build()?,
)?;
let ground = world.create_body(foundation.body_def())?;
world.create_hull_shape(
    ground,
    &foundation.shape_def(),
    &BoxHull::new(8.0, 0.5, 8.0)?,
)?;
let body = world.create_body(
    foundation
        .body_def_builder()
        .body_type(BodyType::Dynamic)
        .position([0.0, 4.0, 0.0])
        .build()?,
)?;
world.create_hull_shape(
    body,
    &foundation.shape_def_builder().density(1.0).build()?,
    &BoxHull::cube(0.5)?,
)?;
world.step(1.0 / 60.0, 4)?;
assert!(world.body_position(body)?.y < 4.0);
```

--------------------------------

### Foundation::get

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.Foundation.html

Retrieves the already initialized process Foundation.

```APIDOC
## pub fn get() -> Result<&'static Self>

### Description
Returns the explicitly initialized process Foundation without attempting to initialize it.
```

--------------------------------

### Foundation::initialize

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.Foundation.html

Initializes and freezes process-wide Box3D settings. This must be the first safe operation performed in the library.

```APIDOC
## pub fn initialize(config: FoundationConfig) -> Result<&'static Self>

### Description
Initializes and freezes process-wide Box3D settings until process exit. This must be the first safe operation that can enter Box3D.

### Parameters
- **config** (FoundationConfig) - Required - The configuration settings to apply.
```

--------------------------------

### Foundation::initialize_default

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.Foundation.html

Initializes the process-lifetime Foundation with default settings (one unit per meter, no stall reports).

```APIDOC
## pub fn initialize_default() -> Result<&'static Self>

### Description
Initializes the process-lifetime Foundation with one unit per meter and no stall reports. This is an explicit first-use initialization.
```

--------------------------------

### HeightFieldBuilder::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/shapes/struct.HeightFieldBuilder.html

Initializes a new instance of the HeightFieldBuilder.

```APIDOC
## pub fn new(row_count: i32, column_count: i32, heights: impl Into<Vec<f32>>) -> Self

### Description
Starts a height-field builder from row count, column count, and samples.

### Parameters
- **row_count** (i32) - Required - The number of rows in the height field.
- **column_count** (i32) - Required - The number of columns in the height field.
- **heights** (impl Into<Vec<f32>>) - Required - The height samples.
```

--------------------------------

### ShapeCastPairInput::with_options

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.ShapeCastPairInput.html

Creates a new instance of ShapeCastPairInput with explicit configuration options.

```APIDOC
## pub fn with_options(proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform, translation_b: impl Into<Vec3>, max_fraction: f32, can_encroach: bool) -> Result<Self>

### Description
Creates a pair shape-cast input with explicit options.

### Parameters
- **proxy_a** (ShapeProxy) - First proxy, expressed in frame A.
- **proxy_b** (ShapeProxy) - Second proxy, expressed in frame B.
- **transform_b_to_a** (Transform) - Transform that moves points from frame B into frame A.
- **translation_b** (impl Into<Vec3>) - Translation applied to proxy B.
- **max_fraction** (f32) - Maximum fraction of the translation to consider.
- **can_encroach** (bool) - Whether the cast may start slightly encroached.
```

--------------------------------

### Get allocated byte count in Rust

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/fn.allocated_byte_count.html

Returns the number of bytes currently allocated by Box3D as a Result.

```rust
pub fn allocated_byte_count() -> Result<i32>
```

--------------------------------

### ShapeCastPairInput::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.ShapeCastPairInput.html

Creates a new instance of ShapeCastPairInput with default options.

```APIDOC
## pub fn new(proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform, translation_b: impl Into<Vec3>) -> Result<Self>

### Description
Creates a pair shape-cast input with default options.

### Parameters
- **proxy_a** (ShapeProxy) - First proxy, expressed in frame A.
- **proxy_b** (ShapeProxy) - Second proxy, expressed in frame B.
- **transform_b_to_a** (Transform) - Transform that moves points from frame B into frame A.
- **translation_b** (impl Into<Vec3>) - Translation applied to proxy B.
```

--------------------------------

### Recording::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.Recording.html

Creates a new recording buffer with the default initial capacity.

```APIDOC
## pub fn new() -> Result<Self>

### Description
Creates a recording buffer with Box3D’s default initial capacity.
```

--------------------------------

### Foundation::create_replay_player

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.Foundation.html

Creates a replay player with exclusive Foundation activity.

```APIDOC
## pub fn create_replay_player(&'static self, bytes: &[u8], worker_count: i32) -> Result<RecPlayer>

### Description
Creates a replay player that owns exclusive Foundation activity until native destruction.

### Parameters
- **bytes** (&[u8]) - Required - The replay data.
- **worker_count** (i32) - Required - The number of workers to use for replay playback.
```

--------------------------------

### Sphere implementation methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/shapes/struct.Sphere.html

Methods for creating and interacting with Sphere instances.

```rust
pub fn new(center: impl Into<Vec3>, radius: f32) -> Self
```

```rust
pub const fn from_raw(raw: b3Sphere) -> Self
```

```rust
pub const fn raw(&self) -> &b3Sphere
```

```rust
pub fn validate(&self) -> Result<()>
```

--------------------------------

### pub fn version() -> Result<Version>

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/fn.version.html

Returns the Box3D runtime version.

```APIDOC
## Function: version

### Description
Returns the Box3D runtime version.

### Signature
`pub fn version() -> Result<Version>`

### Returns
- **Result<Version>** - A result containing the current runtime version or an error if the operation fails.
```

--------------------------------

### Create BoxCastInput instances

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.BoxCastInput.html

Constructors for creating a new BoxCastInput with default or explicit maximum fraction values.

```rust
pub fn new(aabb: Aabb, translation: impl Into<Vec3>) -> Result<Self>
```

```rust
pub fn with_max_fraction( aabb: Aabb, translation: impl Into<Vec3>, max_fraction: f32, ) -> Result<Self>
```

--------------------------------

### ExplosionDefBuilder::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/struct.ExplosionDefBuilder.html

Creates a new instance of the builder with default settings.

```APIDOC
### pub fn new() -> Self

Creates a new value with default settings.
```

--------------------------------

### Foundation::create_world

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.Foundation.html

Creates a new World instance using the Foundation's activity.

```APIDOC
## pub fn create_world(&'static self, def: WorldDef) -> Result<World>

### Description
Creates a World that retains ordinary Foundation activity until native destruction.

### Parameters
- **def** (WorldDef) - Required - The definition used to create the world.
```

--------------------------------

### ShapeCastInput::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.ShapeCastInput.html

Creates a new shape-cast input instance with default options.

```APIDOC
## pub fn new(proxy: ShapeProxy, translation: impl Into<Vec3>) -> Result<Self>

### Description
Creates a shape-cast input with default options for sweeping a convex proxy.

### Parameters
- **proxy** (ShapeProxy) - Required - The convex proxy to sweep.
- **translation** (impl Into<Vec3>) - Required - The translation vector for the cast.
```

--------------------------------

### DynamicTree Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/dynamic_tree/struct.DynamicTree.html

Methods for initializing, managing, and querying the DynamicTree structure.

```APIDOC
## DynamicTree::new()
Creates an empty dynamic tree.

## DynamicTree::with_capacity(proxy_capacity: usize)
Creates an empty dynamic tree with an initial proxy capacity hint.

## DynamicTree::create_proxy(aabb: Aabb, user_data: u64)
Inserts a proxy with default category bits and caller-owned user_data.

## DynamicTree::create_proxy_with_category_bits(aabb: Aabb, category_bits: u64, user_data: u64)
Inserts a proxy with explicit category bits and caller-owned user_data.

## DynamicTree::destroy_proxy(proxy_id: DynamicTreeProxyId)
Removes a proxy from the tree.

## DynamicTree::move_proxy(proxy_id: DynamicTreeProxyId, aabb: Aabb)
Moves an existing proxy to a new AABB.

## DynamicTree::enlarge_proxy(proxy_id: DynamicTreeProxyId, aabb: Aabb)
Enlarges an existing proxy AABB without rebuilding the tree.

## DynamicTree::set_category_bits(proxy_id: DynamicTreeProxyId, category_bits: u64)
Replaces the category bits for a proxy.

## DynamicTree::category_bits(proxy_id: DynamicTreeProxyId)
Returns the category bits currently stored by Box3D for a proxy.

## DynamicTree::proxy(proxy_id: DynamicTreeProxyId)
Returns the Rust-side snapshot for a live proxy.

## DynamicTree::contains_proxy(proxy_id: DynamicTreeProxyId)
Returns true when proxy_id still refers to a live proxy in this tree.

## DynamicTree::proxy_count()
Returns the number of live proxies stored in the native tree.

## DynamicTree::byte_count()
Returns the native heap memory currently owned by the tree, in bytes.

## DynamicTree::height()
Returns the current height of the native AABB tree.

## DynamicTree::area_ratio()
Returns the tree area ratio reported by Box3D.

## DynamicTree::root_bounds()
Returns the root AABB, or None when the tree has no proxies.

## DynamicTree::rebuild(full_build: bool)
Rebuilds the native tree and returns the number of boxes sorted by Box3D.

## DynamicTree::validate()
Runs Box3D’s internal dynamic-tree validation checks.

## DynamicTree::validate_no_enlarged()
Runs Box3D validation that asserts no enlarged nodes remain.
```

--------------------------------

### BoxCastInput::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.BoxCastInput.html

Creates a new BoxCastInput instance with the maximum fraction set to 1.0.

```APIDOC
## pub fn new(aabb: Aabb, translation: impl Into<Vec3>) -> Result<Self>

### Description
Creates a box-cast input with `max_fraction` set to 1.0.

### Parameters
- **aabb** (Aabb) - The box bounds at the start of the cast.
- **translation** (impl Into<Vec3>) - The cast translation vector.
```

--------------------------------

### ShapeCastInput::with_options

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.ShapeCastInput.html

Creates a new shape-cast input instance with explicit configuration options.

```APIDOC
## pub fn with_options(proxy: ShapeProxy, translation: impl Into<Vec3>, max_fraction: f32, can_encroach: bool) -> Result<Self>

### Description
Creates a shape-cast input with explicit options for fine-tuning the sweep behavior.

### Parameters
- **proxy** (ShapeProxy) - Required - The convex proxy to sweep.
- **translation** (impl Into<Vec3>) - Required - The translation vector for the cast.
- **max_fraction** (f32) - Required - Maximum fraction of the translation to consider.
- **can_encroach** (bool) - Required - Whether the cast may start slightly encroached on the target.
```

--------------------------------

### FoundationActivity Struct Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.FoundationActivity.html

The primary structure definition for tracking process activity metrics.

```rust
pub struct FoundationActivity {
    pub ordinary_owners: u32,
    pub transient_calls: u32,
    pub replay_active: bool,
}
```

--------------------------------

### CollisionPlane::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.CollisionPlane.html

Creates a new collision plane with zero initial push.

```APIDOC
## pub fn new(plane: Plane, push_limit: f32, clip_velocity: bool) -> Result<Self>

### Description
Creates a collision plane with zero initial push.

### Parameters
- **plane** (Plane) - The plane equation.
- **push_limit** (f32) - Maximum push distance allowed for this plane.
- **clip_velocity** (bool) - Whether velocity should be clipped by this plane.
```

--------------------------------

### JointTuning::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/joints/struct.JointTuning.html

Creates a new instance of JointTuning with specified frequency and damping ratio.

```APIDOC
## pub const fn new(hertz: f32, damping_ratio: f32) -> Self

### Description
Creates a new JointTuning instance with the provided frequency and damping parameters.

### Parameters
- **hertz** (f32) - Constraint frequency in hertz.
- **damping_ratio** (f32) - Non-negative damping ratio.
```

--------------------------------

### WorldRawParts Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/raw/struct.WorldRawParts.html

Methods for interacting with the raw world bundle, including guard creation, world reconstitution, and manual destruction.

```rust
pub unsafe fn world_guard(&mut self) -> Result<WorldRawGuard<'_>>
```

```rust
pub unsafe fn into_world(self) -> Result<World>
```

```rust
pub unsafe fn destroy(self)
```

--------------------------------

### CollisionPlane::with_options

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.CollisionPlane.html

Creates a collision plane with explicit solver state.

```APIDOC
## pub fn with_options(plane: Plane, push_limit: f32, push: f32, clip_velocity: bool) -> Result<Self>

### Description
Creates a collision plane with explicit solver state.

### Parameters
- **plane** (Plane) - The plane equation.
- **push_limit** (f32) - Maximum push distance allowed for this plane.
- **push** (f32) - Push distance accumulated by the solver.
- **clip_velocity** (bool) - Whether velocity should be clipped by this plane.
```

--------------------------------

### Create DistanceInput instances

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.DistanceInput.html

Methods for initializing a new DistanceInput instance, either with default radius handling or explicit configuration.

```rust
pub fn new( proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform, ) -> Result<Self>
```

```rust
pub fn with_options( proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform, use_radii: bool, ) -> Result<Self>
```

--------------------------------

### RayCastInput::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.RayCastInput.html

Creates a new ray-cast input instance with the max_fraction field defaulted to 1.0.

```APIDOC
## pub fn new(origin: impl Into<Vec3>, translation: impl Into<Vec3>) -> Result<Self>

### Description
Creates a ray-cast input with `max_fraction` set to `1.0`.

### Parameters
- **origin** (impl Into<Vec3>) - Required - The starting point of the ray.
- **translation** (impl Into<Vec3>) - Required - The ray translation vector.
```

--------------------------------

### into_world

Source: https://docs.rs/boxddd/0.4.0/boxddd/raw/struct.WorldRawParts.html

Reconstitutes the safe owner after a raw handoff. This method is unsafe and requires the caller to guarantee no structural native mutation occurred while the bundle was raw-owned.

```APIDOC
## pub unsafe fn into_world(self) -> Result<World>

### Description
Reconstitutes the safe owner after a raw handoff.

### Safety
The caller must guarantee that no structural native mutation occurred while the bundle was raw-owned, no native callback or task can still enter, and no copied raw ID will be used after this call.
```

--------------------------------

### Fallback with or

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Returns the current result if it is Ok, otherwise returns the provided alternative result. Arguments are evaluated eagerly.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

--------------------------------

### ContactBeginTouch Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/events/struct.ContactBeginTouch.html

Methods available on the ContactBeginTouch struct to retrieve contact information.

```APIDOC
## pub fn shape_a(&self) -> Result<ShapeId>

### Description
Returns the first shape in the contact pair.

## pub fn shape_b(&self) -> Result<ShapeId>

### Description
Returns the second shape in the contact pair.

## pub fn contact_id(&self) -> Result<ContactId>

### Description
Returns the transient contact identifier for the pair. Note that the identifier should be validated before use, as Box3D may destroy contacts when the world is stepped or modified.
```

--------------------------------

### Provide default with unwrap_or

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Returns the contained Ok value or a provided default value. Arguments are evaluated eagerly.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Recording::load_from_file

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.Recording.html

Loads a recording buffer from a file path.

```APIDOC
## pub fn load_from_file(path: impl AsRef<Path>) -> Result<Self>

### Description
Loads a recording buffer from a file.
```

--------------------------------

### Recording::bytes

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.Recording.html

Borrows the raw recording bytes.

```APIDOC
## pub fn bytes(&self) -> Result<&[u8]>

### Description
Borrows the raw recording bytes. Returns Error::RecordingInUse while a world is writing to this recording.
```

--------------------------------

### Sphere::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/shapes/struct.Sphere.html

Creates a new sphere instance from a center point and a radius.

```APIDOC
## pub fn new(center: impl Into<Vec3>, radius: f32) -> Self

### Description
Creates a sphere from a center point and positive radius.

### Parameters
- **center** (impl Into<Vec3>) - The center point of the sphere.
- **radius** (f32) - The radius of the sphere (must be positive).
```

--------------------------------

### Recording::with_capacity

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.Recording.html

Creates a new recording buffer with a specified initial byte capacity.

```APIDOC
## pub fn with_capacity(byte_capacity: usize) -> Result<Self>

### Description
Creates a recording buffer with an optional initial byte capacity.
```

--------------------------------

### Calculate Product of Result Iterator

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Demonstrates using the product method on an iterator of Results, which short-circuits on the first Err encountered.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### Create blocking-thread scheduler

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.TaskSystem.html

Creates a scheduler where each Box3D task runs on a dedicated OS thread.

```rust
pub fn blocking_threads() -> Result<Self>
```

--------------------------------

### pub fn clear(&mut self)

Source: https://docs.rs/boxddd/0.4.0/boxddd/debug_draw/struct.DebugDrawFrame.html

Clears all events, commands, and diagnostics from the frame while preserving the allocated capacity.

```APIDOC
## pub fn clear(&mut self)

### Description
Clears all events, commands, and diagnostics while preserving capacity.
```

--------------------------------

### ContactBeginTouchEvent Struct Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/events/struct.ContactBeginTouchEvent.html

The structure definition for the contact begin-touch event, containing identifiers for the two shapes involved and the contact itself.

```rust
pub struct ContactBeginTouchEvent {
    pub shape_a: ShapeId,
    pub shape_b: ShapeId,
    pub contact_id: ContactId,
}
```

--------------------------------

### CollisionPlane Constructors

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.CollisionPlane.html

Methods to initialize a CollisionPlane, either with default zero push or explicit solver state.

```rust
pub fn new(plane: Plane, push_limit: f32, clip_velocity: bool) -> Result<Self>
```

```rust
pub fn with_options( plane: Plane, push_limit: f32, push: f32, clip_velocity: bool, ) -> Result<Self>
```

--------------------------------

### Sweep::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.Sweep.html

Creates a new validated Sweep instance.

```APIDOC
## pub fn new(local_center: Vec3, c1: Vec3, c2: Vec3, q1: Quat, q2: Quat) -> Result<Self>

### Description
Creates a new validated Sweep instance for use in time-of-impact queries.

### Parameters
- **local_center** (Vec3) - The local center of mass.
- **c1** (Vec3) - Center position at the start of the sweep.
- **c2** (Vec3) - Center position at the end of the sweep.
- **q1** (Quat) - Rotation at the start of the sweep.
- **q2** (Quat) - Rotation at the end of the sweep.

### Returns
- **Result<Self>** - A new validated Sweep instance or an error if validation fails.
```

--------------------------------

### ShapeProxy::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.ShapeProxy.html

Creates a new ShapeProxy from a collection of support points and a specified radius.

```APIDOC
## pub fn new(points: impl Into<Vec<Vec3>>, radius: f32) -> Result<Self>

### Description
Creates a proxy from support points and a non-negative radius.

### Parameters
- **points** (impl Into<Vec<Vec3>>) - The support points for the convex shape.
- **radius** (f32) - The non-negative radius applied around each support point.
```

--------------------------------

### PrismaticJointDef Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/joints/struct.PrismaticJointDef.html

Methods available for configuring a PrismaticJointDef instance.

```APIDOC
## pub const fn new(body_a: BodyId, body_b: BodyId) -> Self
Creates a new definition for a prismatic joint connecting two bodies.

## pub fn spring(self, enabled: bool, hertz: f32, damping_ratio: f32) -> Self
Enables or disables the spring and sets frequency in hertz and a dimensionless damping ratio.

## pub fn target_translation(self, target: f32) -> Self
Sets the target translation in world length units.

## pub fn limit(self, enabled: bool, lower: f32, upper: f32) -> Self
Enables or disables translation limits in world length units; `lower` must not exceed `upper`.

## pub fn motor(self, enabled: bool, speed: f32, max_force: f32) -> Self
Enables or disables the motor. `speed` is world length units per second and `max_force` is typically in newtons.

## pub fn body_ids(self, body_a: BodyId, body_b: BodyId) -> Self
Replaces the two bodies connected by the joint.

## pub fn local_frame_a(self, frame: Transform) -> Self
Sets the local constraint frame on body A.

## pub fn local_frame_b(self, frame: Transform) -> Self
Sets the local constraint frame on body B.

## pub fn collide_connected(self, enabled: bool) -> Self
Controls whether the connected bodies may collide.

## pub fn force_threshold(self, threshold: f32) -> Self
Sets the force threshold used to emit joint events, typically in newtons.

## pub fn torque_threshold(self, threshold: f32) -> Self
Sets the torque threshold used to emit joint events, typically in newton-meters.

## pub fn constraint_tuning(self, tuning: JointTuning) -> Self
Sets common constraint frequency in hertz and its dimensionless damping ratio.

## pub fn draw_scale(self, draw_scale: f32) -> Self
Overrides the length-unit-derived native debug draw scale.
```

--------------------------------

### WheelJointDef Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/joints/struct.WheelJointDef.html

Methods available for configuring a WheelJointDef instance.

```APIDOC
## WheelJointDef Methods

### new(body_a: BodyId, body_b: BodyId) -> Self
Creates a new definition for two bodies.

### suspension(enabled: bool, hertz: f32, damping_ratio: f32) -> Self
Enables or disables suspension and sets frequency in hertz and a dimensionless damping ratio.

### suspension_limit(enabled: bool, lower: f32, upper: f32) -> Self
Enables or disables an ordered suspension range in world length units.

### spin_motor(enabled: bool, speed: f32, max_torque: f32) -> Self
Enables or disables the spin motor. `speed` is radians per second and `max_torque` is typically in newton-meters.

### steering(enabled: bool, hertz: f32, damping_ratio: f32) -> Self
Enables or disables steering and sets frequency in hertz and a dimensionless damping ratio.

### steering_limit(enabled: bool, lower: f32, upper: f32) -> Self
Enables or disables an ordered steering range in radians.

### target_steering(angle: f32, max_torque: f32) -> Self
Sets target steering angle in radians and maximum steering torque, typically in newton-meters.

### body_ids(body_a: BodyId, body_b: BodyId) -> Self
Replaces the two bodies connected by the joint.

### local_frame_a(frame: Transform) -> Self
Sets the local constraint frame on body A.

### local_frame_b(frame: Transform) -> Self
Sets the local constraint frame on body B.

### collide_connected(enabled: bool) -> Self
Controls whether the connected bodies may collide.

### force_threshold(threshold: f32) -> Self
Sets the force threshold used to emit joint events, typically in newtons.

### torque_threshold(threshold: f32) -> Self
Sets the torque threshold used to emit joint events, typically in newton-meters.

### constraint_tuning(tuning: JointTuning) -> Self
Sets common constraint frequency in hertz and its dimensionless damping ratio.

### draw_scale(draw_scale: f32) -> Self
Overrides the length-unit-derived native debug draw scale.
```

--------------------------------

### visit_cast_ray

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/struct.World.html

Visits hits from a ray cast through the world using a callback.

```APIDOC
## pub fn visit_cast_ray<F>(&self, origin: impl Into<Pos>, translation: impl Into<Vec3>, filter: QueryFilter, visitor: F) -> Result<TreeStats> where F: FnMut(RayHit) -> f32

### Description
Visits hits from a ray cast through the world. The callback returns a fraction to control traversal: -1.0 to ignore, 0.0 to terminate, or a fraction to clip the ray.
```

--------------------------------

### ContactBeginIter Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/events/struct.ContactBeginIter.html

The structure definition for the iterator over contact begin-touch events.

```rust
pub struct ContactBeginIter<'a> { /* private fields */ }
```

--------------------------------

### RecPlayer Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/recording/struct.RecPlayer.html

Methods available for interacting with a RecPlayer instance to manage replay state and retrieve recording data.

```APIDOC
## RecPlayer Methods

### world_id
Returns the world id owned by the replay player.

### step_frame
Steps the replay by one recorded frame. Returns a Result<bool> indicating success and if the end was reached.

### sub_step_frame
Advances one replay frame in two phases, pausing after body creation.

### restart
Restarts replay from the first recorded frame.

### seek_frame
Seeks replay to a specific recorded frame index (i32).

### frame
Returns the current replay frame index.

### frame_count
Returns the total number of recorded frames.

### is_at_end
Returns whether the replay has reached the end of the recording.

### is_at_pre_step
Returns whether a sub-stepped replay is paused before the world step.

### has_diverged
Returns whether the replay has diverged from the recorded state.

### info
Returns metadata for the loaded recording as RecPlayerInfo.

### diverge_frame
Returns the first frame where replay diverged, if any.

### set_worker_count
Sets the worker count (i32).

### set_keyframe_policy
Sets the keyframe policy using budget_bytes (usize) and min_interval_frames (i32).

### keyframe_budget
Returns the configured replay keyframe memory budget.

### keyframe_min_interval
Returns the minimum frame interval between replay keyframes.

### keyframe_interval
Returns the current frame interval between replay keyframes.

### keyframe_bytes
Returns the bytes currently used by replay keyframes.

### body_count
Returns the number of bodies in the replay world.

### body_id
Returns a body id from the replay world by index (i32).

### frame_query_count
Returns the number of queries captured for the current replay frame.

### frame_query
Returns metadata for a captured query in the current replay frame by index (i32).

### frame_query_hit
Returns a hit recorded for a captured frame query by query_index (i32) and hit_index (i32).

### draw_frame_queries_collect
Collects debug draw commands for recorded frame queries.

### draw_frame_queries_collect_into
Collects debug draw commands for recorded frame queries into a provided vector.

### draw_frame_queries
Draws recorded frame queries with a custom debug draw sink.

### close
Destroys the native player and restores the Foundation scale.
```

--------------------------------

### TimeOfImpactInput Constructors

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.TimeOfImpactInput.html

Methods to instantiate TimeOfImpactInput with either a default or explicit maximum fraction.

```rust
pub fn new( proxy_a: ShapeProxy, proxy_b: ShapeProxy, sweep_a: Sweep, sweep_b: Sweep, ) -> Result<Self>
```

```rust
pub fn with_max_fraction( proxy_a: ShapeProxy, proxy_b: ShapeProxy, sweep_a: Sweep, sweep_b: Sweep, max_fraction: f32, ) -> Result<Self>
```

--------------------------------

### Chain results with and

Source: https://docs.rs/boxddd/0.4.0/boxddd/error/type.Result.html

Returns the provided result if the current result is Ok, otherwise returns the current Err.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));

let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));

let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### DistanceInput::new

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.DistanceInput.html

Creates a new DistanceInput instance that includes proxy radii by default.

```APIDOC
## pub fn new(proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform) -> Result<Self>

### Description
Creates a new distance input configuration that includes proxy radii in the distance calculation.

### Parameters
- **proxy_a** (ShapeProxy) - The first proxy, expressed in frame A.
- **proxy_b** (ShapeProxy) - The second proxy, expressed in frame B.
- **transform_b_to_a** (Transform) - The transform that moves points from frame B into frame A.
```

--------------------------------

### pub fn with_contact_events_view<T>

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/struct.World.html

Borrows contact begin, end, and hit events for the duration of the provided closure.

```APIDOC
## pub fn with_contact_events_view<T>( &self, f: impl FnOnce(ContactBeginIter<'_>, ContactEndIter<'_>, ContactHitIter<'_>) -> T, ) -> Result<T>

### Description
Borrows contact begin, end, and hit events for the duration of the provided closure. The borrowed iterators view Box3D’s transient event arrays.
```

--------------------------------

### RevoluteJointDef Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/joints/struct.RevoluteJointDef.html

Methods available for configuring a RevoluteJointDef instance.

```APIDOC
## pub const fn new(body_a: BodyId, body_b: BodyId) -> Self
Creates a new definition for a revolute joint connecting two bodies.

## pub fn spring(self, enabled: bool, hertz: f32, damping_ratio: f32) -> Self
Enables or disables the spring and sets frequency in hertz and a dimensionless damping ratio.

## pub fn target_angle(self, target_angle: f32) -> Self
Sets the target angle in radians.

## pub fn limit(self, enabled: bool, lower: f32, upper: f32) -> Self
Enables or disables an ordered angular range in radians.

## pub fn motor(self, enabled: bool, speed: f32, max_torque: f32) -> Self
Enables or disables the motor with specified speed and max torque.

## pub fn body_ids(self, body_a: BodyId, body_b: BodyId) -> Self
Replaces the two bodies connected by the joint.

## pub fn local_frame_a(self, frame: Transform) -> Self
Sets the local constraint frame on body A.

## pub fn local_frame_b(self, frame: Transform) -> Self
Sets the local constraint frame on body B.

## pub fn collide_connected(self, enabled: bool) -> Self
Controls whether the connected bodies may collide.

## pub fn force_threshold(self, threshold: f32) -> Self
Sets the force threshold used to emit joint events.

## pub fn torque_threshold(self, threshold: f32) -> Self
Sets the torque threshold used to emit joint events.

## pub fn constraint_tuning(self, tuning: JointTuning) -> Self
Sets common constraint frequency in hertz and its dimensionless damping ratio.

## pub fn draw_scale(self, draw_scale: f32) -> Self
Overrides the length-unit-derived native debug draw scale.
```

--------------------------------

### ParallelJointDef Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/joints/struct.ParallelJointDef.html

Methods available for configuring a ParallelJointDef instance.

```APIDOC
## ParallelJointDef::new(body_a: BodyId, body_b: BodyId)

Creates a new definition for a parallel joint connecting two bodies.

## ParallelJointDef::spring(hertz: f32, damping_ratio: f32, max_torque: f32)

Sets the spring frequency (hertz), damping ratio, and maximum torque for the joint.

## ParallelJointDef::body_ids(body_a: BodyId, body_b: BodyId)

Replaces the two bodies connected by the joint.

## ParallelJointDef::local_frame_a(frame: Transform)

Sets the local constraint frame on body A.

## ParallelJointDef::local_frame_b(frame: Transform)

Sets the local constraint frame on body B.

## ParallelJointDef::collide_connected(enabled: bool)

Controls whether the connected bodies are allowed to collide.

## ParallelJointDef::force_threshold(threshold: f32)

Sets the force threshold (in newtons) used to emit joint events.

## ParallelJointDef::torque_threshold(threshold: f32)

Sets the torque threshold (in newton-meters) used to emit joint events.

## ParallelJointDef::constraint_tuning(tuning: JointTuning)

Sets the common constraint frequency and damping ratio.

## ParallelJointDef::draw_scale(draw_scale: f32)

Overrides the default debug draw scale.
```

--------------------------------

### pub fn steiner_inertia(mass: f32, origin: impl Into<Vec3>) -> Result<Matrix3>

Source: https://docs.rs/boxddd/0.4.0/boxddd/types/fn.steiner_inertia.html

Applies the Steiner theorem to compute inertia for a point mass at a given origin.

```APIDOC
## steiner_inertia

### Description
Applies the Steiner theorem to compute inertia for a point mass at `origin`.

### Signature
`pub fn steiner_inertia(mass: f32, origin: impl Into<Vec3>) -> Result<Matrix3>`

### Parameters
- **mass** (f32) - The mass of the point.
- **origin** (impl Into<Vec3>) - The position of the point mass.

### Returns
- **Result<Matrix3>** - The resulting inertia matrix.
```

--------------------------------

### FoundationConfig Struct Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.FoundationConfig.html

The primary structure used for configuring process-wide Box3D settings.

```rust
pub struct FoundationConfig {
    pub length_units_per_meter: f32,
    pub stall_threshold: StallThreshold,
}
```

--------------------------------

### RayCastInput::with_max_fraction

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.RayCastInput.html

Creates a new ray-cast input instance with an explicitly defined maximum fraction.

```APIDOC
## pub fn with_max_fraction(origin: impl Into<Vec3>, translation: impl Into<Vec3>, max_fraction: f32) -> Result<Self>

### Description
Creates a ray-cast input with an explicit maximum fraction.

### Parameters
- **origin** (impl Into<Vec3>) - Required - The starting point of the ray.
- **translation** (impl Into<Vec3>) - Required - The ray translation vector.
- **max_fraction** (f32) - Required - Maximum fraction of the translation to consider.
```

--------------------------------

### SensorBeginTouch Struct Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/events/struct.SensorBeginTouch.html

The definition of the SensorBeginTouch struct.

```rust
pub struct SensorBeginTouch<'a> { /* private fields */ }
```

--------------------------------

### Retrieve TaskSystem statistics

Source: https://docs.rs/boxddd/0.4.0/boxddd/struct.TaskSystem.html

Returns diagnostic counters for the task system.

```rust
pub fn stats(&self) -> TaskSystemStats
```

--------------------------------

### SensorBeginTouchEvent Struct Definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/events/struct.SensorBeginTouchEvent.html

The structure definition for SensorBeginTouchEvent, which holds the IDs for the sensor and visitor shapes.

```rust
pub struct SensorBeginTouchEvent {
    pub sensor_shape: ShapeId,
    pub visitor_shape: ShapeId,
}
```

--------------------------------

### Hull::from_points

Source: https://docs.rs/boxddd/0.4.0/boxddd/shapes/struct.Hull.html

Builds a convex hull from a collection of points with an upper bound on the number of generated vertices.

```APIDOC
## pub fn from_points(points: impl AsRef<[Vec3]>, max_vertex_count: i32) -> Result<Self>

### Description
Builds a convex hull from a set of points with an upper bound on the number of vertices generated.

### Parameters
- **points** (impl AsRef<[Vec3]>) - The input points to build the hull from.
- **max_vertex_count** (i32) - The maximum number of vertices allowed in the resulting hull.
```

--------------------------------

### Body Mass and Damping Methods

Source: https://docs.rs/boxddd/0.4.0/boxddd/world/struct.World.html

Methods for managing mass data, linear damping, angular damping, and gravity scale for physical bodies.

```APIDOC
## body_mass_data(body_id: BodyId) -> Result<MassData>
## set_body_mass_data(body_id: BodyId, mass_data: MassData) -> Result<()>
## body_linear_damping(body_id: BodyId) -> Result<f32>
## set_body_linear_damping(body_id: BodyId, damping: f32) -> Result<()>
## body_angular_damping(body_id: BodyId) -> Result<f32>
## set_body_angular_damping(body_id: BodyId, damping: f32) -> Result<()>
## body_gravity_scale(body_id: BodyId) -> Result<f32>
## set_body_gravity_scale(body_id: BodyId, scale: f32) -> Result<()>
```

--------------------------------

### Profile struct definition

Source: https://docs.rs/boxddd/0.4.0/boxddd/types/struct.Profile.html

The structure definition containing timing metrics for physics simulation steps.

```rust
pub struct Profile {Show 23 fields
    pub step: f32,
    pub pairs: f32,
    pub collide: f32,
    pub solve: f32,
    pub solver_setup: f32,
    pub constraints: f32,
    pub prepare_constraints: f32,
    pub integrate_velocities: f32,
    pub warm_start: f32,
    pub solve_impulses: f32,
    pub integrate_positions: f32,
    pub relax_impulses: f32,
    pub apply_restitution: f32,
    pub store_impulses: f32,
    pub split_islands: f32,
    pub transforms: f32,
    pub sensor_hits: f32,
    pub joint_events: f32,
    pub hit_events: f32,
    pub refit: f32,
    pub bullets: f32,
    pub sleep_islands: f32,
    pub sensors: f32,
}
```

--------------------------------

### DistanceInput::with_options

Source: https://docs.rs/boxddd/0.4.0/boxddd/collision/struct.DistanceInput.html

Creates a new DistanceInput instance with explicit control over radius handling.

```APIDOC
## pub fn with_options(proxy_a: ShapeProxy, proxy_b: ShapeProxy, transform_b_to_a: Transform, use_radii: bool) -> Result<Self>

### Description
Creates a new distance input configuration with explicit control over whether proxy radii should be included in the distance result.

### Parameters
- **proxy_a** (ShapeProxy) - The first proxy, expressed in frame A.
- **proxy_b** (ShapeProxy) - The second proxy, expressed in frame B.
- **transform_b_to_a** (Transform) - The transform that moves points from frame B into frame A.
- **use_radii** (bool) - Whether proxy radii should be included in the distance result.
```
Tokens:
Raw