Struct PhysicsWorld 

pub struct PhysicsWorld { /* private fields */ }

A physics world mapping render objects by stable ObjectId onto the standalone gp3d engine’s generational body handles. 一个通过稳定的 ObjectId 将渲染对象映射到独立 gp3d 引擎代际刚体句柄上的物理世界。

Bodies and colliders are owned by gp3d. 刚体和碰撞体由 gp3d 持有。 After stepping, call PhysicsWorld::synchronize to write body transforms back into the scene so the renderer sees the physics state. 步进后，调用 PhysicsWorld::synchronize 将刚体变换写回场景，使渲染器看到物理状态。

gp3d and he3d-math both wrap glam, so Vec3/Quat interoperate directly. gp3d 与 he3d-math 都包装 glam，因此 Vec3/Quat 可直接互操作。

Implementations

impl PhysicsWorld

pub fn new() -> Self

Create an empty world with the reference default gravity (0, -9.8, 0). 创建一个空世界，重力为参考默认值 (0, -9.8, 0)。

Examples

示例

use he3d_core::{Material, Mesh, RenderObject, Rgb, Scene, Transform};
use he3d_math::Vec3;
use he3d_physics::PhysicsWorld;

let mut scene = Scene::new();
let mesh = scene.meshes.insert(Mesh::cube(1.0, 1.0, 1.0)?);
let cube = scene.spawn(RenderObject {
   mesh,
   texture: None,
   transform: Transform::from_position(Vec3::new(0.0, 3.0, 0.0)),
   material: Material::new(Rgb::WHITE),
   visible: true,
});

let mut world = PhysicsWorld::new();
world.add_dynamic_box(cube, Vec3::splat(0.5), Transform::from_position(Vec3::new(0.0, 3.0, 0.0)));
for _ in 0..60 {
   world.step(1.0 / 120.0);
}
let y = world.transform(cube).unwrap().position.y;
assert!(y > 0.0 && y < 3.0, "cube fell part-way, got y={y}");

pub fn set_gravity(&mut self, gravity: Vec3)

Override the world gravity vector. 覆盖世界重力向量。

pub fn gravity(&self) -> Vec3

The current world gravity. 当前世界重力。

pub fn add_dynamic_box( &mut self, object: ObjectId, half_extents: Vec3, transform: Transform, ) -> bool

Returns false if the object already has a body, leaving the world unchanged. 若对象已拥有刚体则返回 false，世界保持不变。

pub fn add_static_box( &mut self, object: ObjectId, half_extents: Vec3, transform: Transform, ) -> bool

Returns false if the object already has a body, leaving the world unchanged. 若对象已拥有刚体则返回 false，世界保持不变。

pub fn add_kinematic_box( &mut self, object: ObjectId, half_extents: Vec3, transform: Transform, ) -> bool

Returns false if the object already has a body, leaving the world unchanged. 若对象已拥有刚体则返回 false，世界保持不变。

pub fn add_static_mesh( &mut self, object: ObjectId, mesh: &Mesh, transform: Transform, ) -> bool

Add a static triangle-mesh collider from a Mesh. The mesh vertices are copied; the reference MeshCollider reads live mesh geometry, and gp3d stores its own copy, so re-adding after the mesh changes is the norm. 从 Mesh 添加静态三角网格碰撞体。网格顶点会被复制；参考 MeshCollider 读取实时网格几何，而 gp3d 保存自己的副本，因此网格变化后重新添加是常态。

pub fn set_transform(&mut self, object: ObjectId, transform: Transform) -> bool

Teleport a body, keeping its velocity. Returns false for unknown objects. 瞬移刚体并保持其速度。对未知对象返回 false。

pub fn transform(&self, object: ObjectId) -> Option<Transform>

Read the current body transform. Returns None for unknown objects. 读取当前刚体变换。对未知对象返回 None。

pub fn set_material( &mut self, object: ObjectId, friction: f32, restitution: f32, ) -> bool

Override the body’s friction and restitution coefficients. 覆盖刚体的摩擦系数和恢复系数。

pub fn set_damping( &mut self, object: ObjectId, linear: f32, angular: f32, ) -> bool

Override the body’s linear and angular damping. 覆盖刚体的线性和角向阻尼。

pub fn has_contacts(&self, object: ObjectId) -> bool

Whether the body is currently touching another collider. 刚体当前是否与另一碰撞体接触。

pub fn remove_body(&mut self, object: ObjectId) -> bool

Remove a body. Returns false for unknown objects. 移除一个刚体。对未知对象返回 false。

pub fn has_body(&self, object: ObjectId) -> bool

Whether the object currently has a registered body. 对象当前是否注册了刚体。

pub fn set_velocity(&mut self, object: ObjectId, velocity: Vec3) -> bool

Override the body’s linear velocity. 覆盖刚体线速度。

pub fn velocity(&self, object: ObjectId) -> Vec3

The body’s linear velocity, or zero for unknown objects. 刚体线速度；未知对象返回零向量。

pub fn set_angular_velocity(&mut self, object: ObjectId, velocity: Vec3) -> bool

Override the body’s angular velocity. 覆盖刚体角速度。

pub fn angular_velocity(&self, object: ObjectId) -> Vec3

The body’s angular velocity, or zero for unknown objects. 刚体角速度；未知对象返回零向量。

pub fn add_force(&mut self, object: ObjectId, force: Vec3) -> bool

Apply an instantaneous force for the next step only. 施加仅作用于下一步的瞬时力。

pub fn add_torque(&mut self, object: ObjectId, torque: Vec3) -> bool

Apply an instantaneous torque for the next step only. 施加仅作用于下一步的瞬时力矩。

pub fn add_impulse(&mut self, object: ObjectId, impulse: Vec3) -> bool

Apply an instantaneous impulse. 施加瞬时冲量。

pub fn add_angular_impulse(&mut self, object: ObjectId, impulse: Vec3) -> bool

Apply an instantaneous angular impulse. 施加瞬时角冲量。

pub fn step(&mut self, delta_time: f32) -> StepResult

Advance the simulation by one fixed step using the reference default of 4 solver iterations. Forces and torques applied with PhysicsWorld::add_force / PhysicsWorld::add_torque act for one step only and are then cleared. 以参考默认的 4 次求解器迭代推进模拟。由 PhysicsWorld::add_force / PhysicsWorld::add_torque 施加的力与力矩只作用一步并被清除。

pub fn synchronize(&mut self, scene: &mut Scene)

Write body transforms back into the scene’s render objects. 将刚体变换写回场景的渲染对象。

Trait Implementations

impl Default for PhysicsWorld

fn default() -> Self

Returns the “default value” for a type.