Byte Engine Docs
View on docs.rs

physics

Generated Rust API reference for byte_engine.

byte_engine / physics


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

ItemKindDescription
LocalSpacestructThe LocalSpace struct brands coordinates stored relative to a collider's origin.
ContactScratchstruct
RayHitstruct
RayQuerystruct
RayQueryResponsestruct
Physicsstruct

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) -> LocalSpace

    Related: LocalSpace

impl Copy for LocalSpace
impl Debug for LocalSpace
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for 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) -> bool

    Related: 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) -> Handle

    Returns the handle the body was created with.

  • fn distance(&self) -> f32

    Returns how far along the ray it meets the body.

  • fn point(&self) -> Point

    Returns where the ray meets the body, in world space.

  • fn normal(&self) -> UnitVector

    Returns 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) -> RayHit

    Related: 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) -> bool

    Related: 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) -> Self

    Creates a query for the first body that ray meets within max_distance of its origin. Pass infinity for a

    ray without an end.

  • fn segment(start: Point, end: Point) -> Result<Self, NormalizationError>

    Creates a query for the first body that the segment from start to end meets, counted from start.

    Returns an error when start and end are at the same place, which leaves the segment without a

    direction.

  • fn ray(&self) -> Ray

    Returns the ray the query is made along.

  • fn max_distance(&self) -> f32

    Returns 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) -> RayQuery

    Related: 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) -> bool

    Related: 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) -> Handle

    Returns the handle the answered RayQuery was created with.

  • fn hit(&self) -> Option<RayHit>

    Related: RayHit

    Returns where the ray first met a body, or None when 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
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
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, as bodies:lanes pairs such as 512: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, so 0:1 keeps every step there. The default suits the machine: it never uses more lanes than the processor's fastest cores have hardware threads; see StepLanes::for_machine. Set it per machine, such as with the BE_PHYSICS__STEP_LANES environment variable, when measurements there show better counts.

Implementations

  • fn new(scope: &MessageScope, parameters: impl Parameters) -> Self

    Related: MessageScope

    Creates a simulation of the bodies, constraints, and ray queries published in scope from now on, set up

    from parameters, the physics subtree of the application's.

  • fn step(&mut self, time: Time, alley: &mut Alley)

    Related: Time

    Advances the simulation by time, running the step as one execution of alley.

    The step runs on as many of alley's lanes as its size pays for; see dynabit::World::update. No other

    dispatch of alley may be running, so call it outside lane executions such as

    GraphicsApplication::run_lanes.

  • 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
impl WithSubscriber for Physics

On this page

Module physicsQuick ReferenceStructsLocalSpaceTrait Implementationsimpl ArchivePointee for LocalSpaceimpl<ST> CastableFrom for LocalSpaceimpl Clone for LocalSpaceimpl Copy for LocalSpaceimpl Debug for LocalSpaceimpl Default for LocalSpaceimpl Downcast for LocalSpaceimpl DowncastSync for LocalSpaceimpl Eq for LocalSpaceimpl<K> Equivalent for LocalSpaceimpl Hash for LocalSpaceimpl Instrument for LocalSpaceimpl LayoutRaw for LocalSpaceimpl<T, N1> Niching for LocalSpaceimpl PartialEq for LocalSpaceimpl Pointee for LocalSpaceimpl Read for LocalSpaceimpl<R> ReadPrimitive for LocalSpaceimpl StructuralPartialEq for LocalSpaceimpl WithSubscriber for LocalSpaceContactScratch<Space>Trait Implementationsimpl ArchivePointee for ContactScratch<Space>impl<ST> CastableFrom for ContactScratch<Space>impl<Space> Default for ContactScratch<Space>impl Downcast for ContactScratch<Space>impl DowncastSync for ContactScratch<Space>impl Instrument for ContactScratch<Space>impl LayoutRaw for ContactScratch<Space>impl<T, N1> Niching for ContactScratch<Space>impl Pointee for ContactScratch<Space>impl Read for ContactScratch<Space>impl<R> ReadPrimitive for ContactScratch<Space>impl WithSubscriber for ContactScratch<Space>RayHitImplementationsTrait Implementationsimpl ArchivePointee for RayHitimpl<ST> CastableFrom for RayHitimpl Clone for RayHitimpl Copy for RayHitimpl Debug for RayHitimpl Downcast for RayHitimpl DowncastSync for RayHitimpl Instrument for RayHitimpl LayoutRaw for RayHitimpl<T, N1> Niching for RayHitimpl PartialEq for RayHitimpl Pointee for RayHitimpl Read for RayHitimpl StructuralPartialEq for RayHitimpl WithSubscriber for RayHitRayQueryImplementationsTrait Implementationsimpl ArchivePointee for RayQueryimpl<ST> CastableFrom for RayQueryimpl Clone for RayQueryimpl Copy for RayQueryimpl Debug for RayQueryimpl Downcast for RayQueryimpl DowncastSync for RayQueryimpl Instrument for RayQueryimpl LayoutRaw for RayQueryimpl<T, N1> Niching for RayQueryimpl PartialEq for RayQueryimpl Pointee for RayQueryimpl Read for RayQueryimpl StructuralPartialEq for RayQueryimpl WithSubscriber for RayQueryRayQueryResponseImplementationsTrait Implementationsimpl ArchivePointee for RayQueryResponseimpl<ST> CastableFrom for RayQueryResponseimpl Clone for RayQueryResponseimpl Copy for RayQueryResponseimpl Debug for RayQueryResponseimpl Downcast for RayQueryResponseimpl DowncastSync for RayQueryResponseimpl Instrument for RayQueryResponseimpl LayoutRaw for RayQueryResponseimpl<T, N1> Niching for RayQueryResponseimpl PartialEq for RayQueryResponseimpl Pointee for RayQueryResponseimpl Read for RayQueryResponseimpl StructuralPartialEq for RayQueryResponseimpl WithSubscriber for RayQueryResponsePhysicsConfigurationImplementationsTrait Implementationsimpl ArchivePointee for Physicsimpl<ST> CastableFrom for Physicsimpl Deref for Physicsimpl DerefMut for Physicsimpl Downcast for Physicsimpl DowncastSync for Physicsimpl Instrument for Physicsimpl LayoutRaw for Physicsimpl<T, N1> Niching for Physicsimpl Pointee for Physicsimpl Read for Physicsimpl Receiver for Physicsimpl WithSubscriber for Physics