physics
Generated Rust API reference for byte_engine.
Module physics
Physics contracts and the built-in Dynabit simulation.
Create a Physics system on the world scope and step it from the application loop.
Create Body payloads for entities that participate in simulation. Collider
geometry uses LocalSpace, while simulated positions, velocities, and contacts
remain in the engine world space. Publish a transform under the same entity handle
to place the body in the world. Create a Constraint to hold two bodies to each
other. Create a RayQuery to learn which body a ray or a segment meets first, and
read the answer from a RayQueryResponse.
Quick Reference
| Item | Kind | Description |
|---|---|---|
LocalSpace | struct | The LocalSpace struct brands coordinates stored relative to a collider's origin. |
ContactScratch | struct | |
RayHit | struct | |
RayQuery | struct | |
RayQueryResponse | struct | |
Physics | struct |
Structs
LocalSpace
struct LocalSpace;Defined in crates/byte-engine/src/physics/mod.rs:32
The LocalSpace struct brands coordinates stored relative to a collider's origin.
Trait Implementations
impl ArchivePointee for LocalSpace
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for LocalSpace
impl Clone for LocalSpace
-
fn clone(&self) -> LocalSpaceRelated:
LocalSpace
impl Copy for LocalSpace
impl Debug for LocalSpace
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for LocalSpace
-
fn default() -> LocalSpaceRelated:
LocalSpace
impl Downcast for LocalSpace
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for LocalSpace
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for LocalSpace
impl<K> Equivalent for LocalSpace
-
fn equivalent(&self, key: &K) -> bool
impl Hash for LocalSpace
-
fn hash<__H: hash::Hasher>(&self, state: &mut __H)
impl Instrument for LocalSpace
impl LayoutRaw for LocalSpace
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for LocalSpace
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for LocalSpace
-
fn eq(&self, other: &LocalSpace) -> boolRelated:
LocalSpace
impl Pointee for LocalSpace
-
type Metadata = ()
impl Read for LocalSpace
impl<R> ReadPrimitive for LocalSpace
impl StructuralPartialEq for LocalSpace
impl WithSubscriber for LocalSpace
ContactScratch<Space>
struct ContactScratch<Space> {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/physics/epa.rs:33-40
The ContactScratch struct keeps the working storage that finding how deep two shapes are in each other needs,
so that only the first few contacts found with it allocate.
Keep one for every thread that finds contacts, and pass it to crate::physics::shapes_contact or
crate::physics::rounded_shapes_contact each time. It carries nothing over from one contact to the next but
its storage.
Trait Implementations
impl ArchivePointee for ContactScratch<Space>
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for ContactScratch<Space>
impl<Space> Default for ContactScratch<Space>
-
fn default() -> Self
impl Downcast for ContactScratch<Space>
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for ContactScratch<Space>
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for ContactScratch<Space>
impl LayoutRaw for ContactScratch<Space>
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for ContactScratch<Space>
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for ContactScratch<Space>
-
type Metadata = ()
impl Read for ContactScratch<Space>
impl<R> ReadPrimitive for ContactScratch<Space>
impl WithSubscriber for ContactScratch<Space>
RayHit
struct RayHit {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/physics/ray_query.rs:79-84
The RayHit struct describes where a queried ray first meets a body, so that gameplay can act on that body and
place things on its surface.
A ray that starts inside a body, or on its surface, meets it at a distance of zero, with a normal that leads back along the ray.
Implementations
-
fn body(&self) -> HandleReturns the handle the body was created with.
-
fn distance(&self) -> f32Returns how far along the ray it meets the body.
-
fn point(&self) -> PointReturns where the ray meets the body, in world space.
-
fn normal(&self) -> UnitVectorReturns the body's outward surface normal where the ray meets it.
Trait Implementations
impl ArchivePointee for RayHit
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RayHit
impl Clone for RayHit
-
fn clone(&self) -> RayHitRelated:
RayHit
impl Copy for RayHit
impl Debug for RayHit
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for RayHit
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for RayHit
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for RayHit
impl LayoutRaw for RayHit
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RayHit
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for RayHit
-
fn eq(&self, other: &RayHit) -> boolRelated:
RayHit
impl Pointee for RayHit
-
type Metadata = ()
impl Read for RayHit
impl StructuralPartialEq for RayHit
impl WithSubscriber for RayHit
RayQuery
struct RayQuery {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/physics/ray_query.rs:13-16
The RayQuery struct asks the physics world which body a ray or a segment meets first, for gameplay that needs
to know what lies along a line, such as the ground under a character or what a shot hits.
Create it on the world scope with crate::core::factory::Creator::create, and keep the handle that
returns. The physics world answers every
query once, after its next step, by creating a RayQueryResponse that carries the query's handle. Read the
responses from a listener of the world's factory for RayQueryResponse, created before the query.
Implementations
-
fn new(ray: Ray, max_distance: f32) -> SelfCreates a query for the first body that
raymeets withinmax_distanceof its origin. Pass infinity for aray without an end.
-
fn segment(start: Point, end: Point) -> Result<Self, NormalizationError>Creates a query for the first body that the segment from
starttoendmeets, counted fromstart.Returns an error when
startandendare at the same place, which leaves the segment without adirection.
-
fn ray(&self) -> RayReturns the ray the query is made along.
-
fn max_distance(&self) -> f32Returns how far along the ray the query looks.
Trait Implementations
impl ArchivePointee for RayQuery
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RayQuery
impl Clone for RayQuery
-
fn clone(&self) -> RayQueryRelated:
RayQuery
impl Copy for RayQuery
impl Debug for RayQuery
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for RayQuery
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for RayQuery
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for RayQuery
impl LayoutRaw for RayQuery
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RayQuery
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for RayQuery
-
fn eq(&self, other: &RayQuery) -> boolRelated:
RayQuery
impl Pointee for RayQuery
-
type Metadata = ()
impl Read for RayQuery
impl StructuralPartialEq for RayQuery
impl WithSubscriber for RayQuery
RayQueryResponse
struct RayQueryResponse {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/physics/ray_query.rs:51-54
The RayQueryResponse struct answers a RayQuery, so that the gameplay that asked can match the answer to its
question by the query's handle.
The physics world creates one for every query, with a handle of its own. Read the query's handle with
Self::query, and what the ray met with Self::hit.
Implementations
-
fn query(&self) -> HandleReturns the handle the answered
RayQuerywas created with. -
fn hit(&self) -> Option<RayHit>Related:
RayHitReturns where the ray first met a body, or
Nonewhen it met none within its length.
Trait Implementations
impl ArchivePointee for RayQueryResponse
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for RayQueryResponse
impl Clone for RayQueryResponse
-
fn clone(&self) -> RayQueryResponseRelated:
RayQueryResponse
impl Copy for RayQueryResponse
impl Debug for RayQueryResponse
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for RayQueryResponse
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for RayQueryResponse
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for RayQueryResponse
impl LayoutRaw for RayQueryResponse
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for RayQueryResponse
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for RayQueryResponse
-
fn eq(&self, other: &RayQueryResponse) -> boolRelated:
RayQueryResponse
impl Pointee for RayQueryResponse
-
type Metadata = ()
impl Read for RayQueryResponse
impl StructuralPartialEq for RayQueryResponse
impl WithSubscriber for RayQueryResponse
Physics
struct Physics {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/physics/system.rs:33-39
The Physics struct simulates the bodies of a world scope and publishes where they move on its transform route.
Create it with Self::new before the bodies it must simulate, then call Self::step once per
simulation step, after everything that posts transforms for that step, and Self::flush_deletions where
deleted bodies should leave the simulation, such as the start of the next step. It dereferences to the
dynabit::World it steps for settings such as dynabit::World::set_sleeping.
Configuration
Read from the parameters the caller routes to it, usually app.parameters().scope("physics"):
step-lanes: Replaces how many lanes a step runs on, asbodies:lanespairs such as512:2,4000:4: steps of at least 512 bodies run on two lanes and steps of at least 4,000 on four. Smaller steps, and steps given one lane, run on the calling thread, so0:1keeps every step there. The default suits the machine: it never uses more lanes than the processor's fastest cores have hardware threads; seeStepLanes::for_machine. Set it per machine, such as with theBE_PHYSICS__STEP_LANESenvironment variable, when measurements there show better counts.
Implementations
-
fn new(scope: &MessageScope, parameters: impl Parameters) -> SelfRelated:
MessageScopeCreates a simulation of the bodies, constraints, and ray queries published in
scopefrom now on, set upfrom
parameters, the physics subtree of the application's. -
fn step(&mut self, time: Time, alley: &mut Alley)Related:
TimeAdvances the simulation by
time, running the step as one execution ofalley.The step runs on as many of
alley's lanes as its size pays for; seedynabit::World::update. No otherdispatch of
alleymay be running, so call it outside lane executions such as -
fn flush_deletions(&mut self)Removes the bodies and constraints of every deletion published since the last call.
Call it where other systems have finished reading the deleted bodies, such as the start of a step.
Trait Implementations
impl ArchivePointee for Physics
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Physics
impl Deref for Physics
-
type Target = World -
fn deref(&self) -> &<Self as >::Target
impl DerefMut for Physics
-
fn deref_mut(&mut self) -> &mut <Self as >::Target
impl Downcast for Physics
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for Physics
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Physics
impl LayoutRaw for Physics
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Physics
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Physics
-
type Metadata = ()
impl Read for Physics
impl Receiver for Physics
-
type Target = T