Struct World 

pub struct World { /* private fields */ }

Owns a set of Bodies and advances them through time. 持有一组 Body 并推进它们的时间演化。

A World knows nothing about rendering. It never sees an ObjectId, a Scene, or a Transform; a Body’s placement is a position and an orientation, and the application owns the link between a Body and whatever draws it. See CONTEXT.md and docs/adr/0001. World 对渲染一无所知。它永远看不到 ObjectId、Scene 或 Transform；Body 的摆放 是位置与朝向，而 Body 与“画它的东西“之间的联系由应用拥有。见 CONTEXT.md 与 docs/adr/0001。

Examples

示例

use he3d_math::Vec3;
use he3d_physics::{BodyDesc, Shape, World};

let mut world = World::new();
let ball = world.add_body(BodyDesc::dynamic(Shape::sphere(0.5), 1.0).at(Vec3::new(0.0, 5.0, 0.0)));
for _ in 0..60 {
    world.step(1.0 / 60.0);
}
let y = world.position(ball).expect("the ball exists").y;
assert!(y < 5.0, "the ball should have fallen, got y={y}");

Implementations

impl World

pub fn new() -> Self

An empty World under DEFAULT_GRAVITY. 处于 DEFAULT_GRAVITY 下的空 World。

pub fn gravity(&self) -> Vec3

The current gravity vector. 当前重力向量。

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

Override the gravity vector. Non-finite input is ignored. 覆盖重力向量。非有限输入会被忽略。

pub fn set_broadphase_cell_size(&mut self, cell_size: f32)

The edge length of a broadphase cell. 宽阶段单元格的边长。

It should be near the size of a typical Body. 它应接近典型 Body 的尺寸。

pub fn set_velocity_iterations(&mut self, iterations: u32)

Velocity iterations per step. 每步的速度迭代次数。

pub fn set_static_friction(&mut self, friction: f32)

Friction of Static geometry, combined with each Body’s own. Static geometry 的摩擦系数，与各 Body 自身的系数合并。

It is not a per-mesh property: terrain is usually one material, and a Body’s own coefficient already varies per Body. 它不是逐网格属性：地形通常只有一种材质，而 Body 自身的系数已经逐 Body 变化。

pub fn add_static_mesh(&mut self, positions: &[Vec3]) -> Option<StaticMeshId>

Register immovable triangle geometry and return its handle. 注册不可移动的三角形几何并返回其句柄。

positions is a flat list in which every three consecutive entries form one triangle — the layout he3d_math::Vec3 arrays use everywhere else. Every registered mesh welds into one shared topology, so an edge that lies between two separate meshes still counts as an Internal edge; that is what keeps a Body sliding across streamed terrain from catching on the seam between two tiles. positions 是扁平列表，每三个连续条目构成一个三角形——与其他地方使用 he3d_math::Vec3 数组的布局一致。每个已注册网格都焊接进同一套共享拓扑，因此 位于两个独立网格之间的边仍算作 Internal edge；这正是让划过流式地形的 Body 不会卡在 瓦片接缝上的原因。

Returns None for malformed input: an empty list, a length that is not a multiple of three, or a coordinate that is not finite. 畸形输入返回 None：空列表、长度不是三的倍数，或存在非有限坐标。

pub fn remove_static_mesh(&mut self, id: StaticMeshId) -> bool

Remove a piece of Static geometry, invalidating its handle. 移除一块 Static geometry 并使其句柄失效。

Its triangles release their edges from the shared topology, so a tile that is streamed out stops making its neighbour’s boundary look internal. 它的三角形会从共享拓扑中释放各自的边，因此被流式卸载的瓦片不再让邻居的边界显得像 内部边。

pub fn contains_static_mesh(&self, id: StaticMeshId) -> bool

Whether a handle still addresses a registered Static mesh. 句柄是否仍指向一块已注册的 Static mesh。

pub fn static_mesh_count(&self) -> usize

How many pieces of Static geometry are registered. 已注册的 Static geometry 数量。

pub fn contacts(&self) -> &[Contact]

The Contacts found by the most recent World::step. 最近一次 World::step 发现的 Contact。

The list is rebuilt on every step, so it must be read before the next one. 该列表每步重建，因此必须在下一步之前读取。

pub fn len(&self) -> usize

The number of live Bodies. 存活 Body 的数量。

pub fn is_empty(&self) -> bool

Whether the World holds no Bodies. World 是否不持有任何 Body。

pub fn add_body(&mut self, desc: BodyDesc) -> BodyId

Insert a Body and return its handle. 插入一个 Body 并返回其句柄。

Panics

Panics once the World holds more than u32::MAX Bodies. That is unreachable in practice, since every Body occupies a slot in a Vec that could not grow that large on any real machine. 当 World 持有的 Body 数超过 u32::MAX 时 panic。实践中不可达：每个 Body 占用 Vec 中的一个槽位，没有任何真实机器能让它增长到那么大。

pub fn remove_body(&mut self, id: BodyId) -> bool

Remove a Body, invalidating its handle. Returns whether it existed. 移除一个 Body 并使其句柄失效。返回它原先是否存在。

pub fn contains(&self, id: BodyId) -> bool

Whether a handle still addresses a live Body. 句柄是否仍指向一个存活的 Body。

pub fn ids(&self) -> impl Iterator<Item = BodyId> + '_

Every live Body’s handle, in slot order. 所有存活 Body 的句柄，按槽位顺序。

Panics

Panics once the World holds more than u32::MAX Bodies; see World::add_body. 当 World 持有的 Body 数超过 u32::MAX 时 panic；见 World::add_body。

pub fn shape(&self, id: BodyId) -> Option<Shape>

The Body’s shape. Body 的形状。

pub fn motion(&self, id: BodyId) -> Option<MotionType>

The Body’s motion mode. Body 的运动模式。

pub fn mass_properties(&self, id: BodyId) -> Option<MassProperties>

The Body’s mass properties. Body 的质量属性。

pub fn position(&self, id: BodyId) -> Option<Vec3>

The Body’s position. Body 的位置。

pub fn orientation(&self, id: BodyId) -> Option<Quat>

The Body’s orientation. Body 的朝向。

pub fn aabb(&self, id: BodyId) -> Option<Aabb>

The Body’s world-space bounding box. Body 的世界空间包围盒。

pub fn velocity(&self, id: BodyId) -> Option<Vec3>

The Body’s linear velocity. Body 的线速度。

pub fn angular_velocity(&self, id: BodyId) -> Option<Vec3>

The Body’s angular velocity. Body 的角速度。

pub fn friction(&self, id: BodyId) -> Option<f32>

The Body’s friction coefficient. Body 的摩擦系数。

pub fn restitution(&self, id: BodyId) -> Option<f32>

The Body’s restitution. Body 的弹性。

pub fn is_sleeping(&self, id: BodyId) -> Option<bool>

Whether the Body is currently asleep. Body 当前是否处于睡眠。

pub fn set_pose( &mut self, id: BodyId, position: Vec3, orientation: Quat, ) -> bool

Move a Body to a position and orientation, waking it. 将 Body 移动到某位置与朝向，并唤醒它。

Returns whether the Body exists and accepts the change. A Static Body is repositioned but stays static, and a non-finite or degenerate input is rejected. 返回 Body 是否存在并接受该改动。Static Body 会被重新摆放但仍保持静止；非有限或 退化的输入会被拒绝。

pub fn set_velocity(&mut self, id: BodyId, velocity: Vec3) -> bool

Set a Body’s linear velocity, waking it. 设置 Body 的线速度，并唤醒它。

pub fn set_angular_velocity( &mut self, id: BodyId, angular_velocity: Vec3, ) -> bool

Set a Body’s angular velocity, waking it. 设置 Body 的角速度，并唤醒它。

pub fn set_friction(&mut self, id: BodyId, friction: f32) -> bool

Set a Body’s friction coefficient, clamped to be non-negative. 设置 Body 的摩擦系数，钳制为非负。

pub fn set_restitution(&mut self, id: BodyId, restitution: f32) -> bool

Set a Body’s restitution, clamped to be non-negative. 设置 Body 的弹性，钳制为非负。

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

Set a Body’s linear and angular damping, clamped to be non-negative. 设置 Body 的线性与角阻尼，钳制为非负。

pub fn set_gravity_scale(&mut self, id: BodyId, scale: f32) -> bool

Change how much of the World’s gravity reaches a Body. 改变 World 的重力有多少作用于此 Body。

The live counterpart of BodyDesc::with_gravity_scale, for a Body whose owner changes its mind mid-scene — a flight model that hands the aircraft back to gravity when it crashes, for instance. BodyDesc::with_gravity_scale 的运行时对应物，用于所有者在中途改变主意的 Body ——例如飞行模型在飞机坠毁时把它交还给重力。

Returns false for a dead handle. Negative or non-finite values are clamped to zero, and a zero scale wakes the Body, since a Body asleep under no gravity is not necessarily asleep under the new one. 句柄失效时返回 false。负值或非有限值被钳制为零；系数为零时会唤醒该 Body，因为在无 重力下睡着的 Body 在新重力下未必还该睡。

pub fn apply_force(&mut self, id: BodyId, force: Vec3) -> bool

Add a force at the Body’s center of mass, acting for the next step only. 在 Body 质心施加一个只作用于下一步的力。

Only a Dynamic Body accumulates force; Static and Kinematic Bodies ignore gravity and forces entirely. 只有 Dynamic Body 会累积力；Static 与 Kinematic 完全忽略重力与力。

pub fn apply_torque(&mut self, id: BodyId, torque: Vec3) -> bool

Add a torque, acting for the next step only. 施加一个只作用于下一步的力矩。

pub fn apply_impulse(&mut self, id: BodyId, impulse: Vec3) -> bool

Apply an instantaneous linear impulse at the center of mass. 在质心施加一个瞬时线冲量。

pub fn apply_angular_impulse(&mut self, id: BodyId, impulse: Vec3) -> bool

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

pub fn wake(&mut self, id: BodyId) -> bool

Return a sleeping Body to simulation. 将处于睡眠的 Body 唤回模拟。

pub fn clear_forces(&mut self)

Clear the force and torque accumulators of every Body. 清空所有 Body 的力与力矩累积。

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

Advance the simulation by one fixed time step. 以固定步长推进模拟一步。

Non-finite or non-positive input is ignored, so a caller handing over a degenerate frame delta cannot corrupt the World. Forces and torques accumulated before the call act for exactly this step and are then cleared. 非有限或非正输入会被忽略，因此调用方传入退化的帧间隔也不会破坏 World。调用前累积 的力与力矩恰好作用这一步，随后被清除。

Trait Implementations

impl Clone for World

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for World

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for World

fn default() -> Self

Returns the “default value” for a type.