Enum WorldSnapshotError 

#[non_exhaustive]
pub enum WorldSnapshotError {
    Truncated,
    BadMagic,
    UnsupportedVersion {
        found: u16,
        supported: u16,
    },
    ReservedNotZero,
    TrailingBytes {
        extra: usize,
    },
    ChecksumMismatch {
        stored: u64,
        computed: u64,
    },
    InvalidValue {
        section: &'static str,
    },
    DanglingIndex {
        section: &'static str,
        index: usize,
        len: usize,
    },
    SdfFieldCountMismatch {
        snapshot: usize,
        world: usize,
    },
    CallbackCountMismatch {
        section: &'static str,
        snapshot: usize,
        world: usize,
    },
    ParticipantMismatch(ParticipantMismatch),
    ParticipantState {
        index: usize,
        error: StateError,
    },
    FieldState(StateError),
    SemanticsMismatch {
        stored: [u8; 32],
        expected: [u8; 32],
    },
    LawIdMismatch {
        stored: [u8; 32],
        expected: [u8; 32],
    },
}

Why PhysicsWorld::restore_world / PhysicsWorld::from_world_snapshot rejected a blob. The target world is unchanged in every case.

Which input gives which error

input	error
fewer than 24 bytes, a version 4 blob of fewer than 88 bytes, or shorter than the declared payload	Self::Truncated
wrong magic	Self::BadMagic
version 0 or above PhysicsWorld::WORLD_SNAPSHOT_VERSION	Self::UnsupportedVersion
reserved bytes not 0	Self::ReservedNotZero
longer than the declared payload	Self::TrailingBytes
checksum differs	Self::ChecksumMismatch
version 4 header semantics_id differs from this binary’s crate::PHYSICS_SEMANTICS_ID	Self::SemanticsMismatch
version 4 header law_id differs from the one passed to PhysicsWorld::restore_world_checked	Self::LawIdMismatch
unknown enum tag / non-boolean byte / unrepresentable value inside the payload	Self::InvalidValue
material table with 0 or more than 65,536 materials, or a material whose id is not its index	Self::InvalidValue (section: "material_table")
a joint / constraint / contact / SDF collider / batch / proxy index past its target	Self::DanglingIndex
target world holds a different number of SDF fields	Self::SdfFieldCountMismatch
target world holds a different number of hooks / modifiers / bridges	Self::CallbackCountMismatch
target world holds other participants (count, kinds, order)	Self::ParticipantMismatch
a participant of the target world refuses its payload	Self::ParticipantState
the target world declares other shared fields	Self::FieldState
unknown fault code / participant fault tag, field mode or layout tag	Self::InvalidValue

On every error the target world is left untouched.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Truncated

The blob ends before the header or the declared payload does.

BadMagic

The first 4 bytes are not PhysicsWorld::WORLD_SNAPSHOT_MAGIC.

UnsupportedVersion

The version is not one this build reads (1 to PhysicsWorld::WORLD_SNAPSHOT_VERSION).

Fields

found: u16

Version stored in the blob.

supported: u16

Version this build reads.

ReservedNotZero

The reserved header bytes are not 0.

TrailingBytes

Bytes remain after the checksum, or after the last payload section.

Fields

extra: usize

Number of unread bytes.

ChecksumMismatch

The stored checksum differs from the one computed over the blob.

Fields

stored: u64

Checksum stored in the blob.

computed: u64

Checksum of the bytes as received.

InvalidValue

A value inside the payload is not valid for its field (unknown enum tag, a boolean byte other than 0 / 1, a count that does not fit usize, invalid metric weights, a material table holding 0 or more than 65,536 materials or a material whose id is not its index).

Fields

section: &'static str

Section the value was read in.

DanglingIndex

An index refers past the end of what it indexes (for example a joint naming a body the snapshot does not hold).

Fields

section: &'static str

Section holding the index.

index: usize

The index.

len: usize

Length of what it indexes.

SdfFieldCountMismatch

The snapshot holds a different number of SDF colliders than the target world holds SDF fields (fields are code and are not in the blob).

Fields

snapshot: usize

SDF colliders in the snapshot.

world: usize

SDF colliders in the target world.

CallbackCountMismatch

The snapshot was taken with a different number of pre-solve hooks, contact modifiers or installed GPU bridges than the target world has.

Fields

section: &'static str

"pre_solve_hooks", "contact_modifiers" or "gpu_solver_bridge".

snapshot: usize

Count in the snapshot.

world: usize

Count in the target world.

ParticipantMismatch(ParticipantMismatch)

The target world’s participants differ from the snapshot’s in number, kinds or order (participants are code and are not in the blob; the target world must already hold the same ones).

ParticipantState

Participant index of the target world refused its payload (crate::world_participant::Participant::check_state). Every payload is checked before any is read.

Fields

index: usize

Registration index of the participant.

error: StateError

Why it refused.

FieldState(StateError)

The snapshot’s shared fields do not match the target world’s declared fields (ids, modes, layouts; crate::world_participant::FieldBoard::check_values).

SemanticsMismatch

A version 4 blob was written under other stepping semantics: its header semantics_id is not this binary’s crate::PHYSICS_SEMANTICS_ID, so a restored world would not step the way the writer’s did. Checked after the checksum.

Fields

stored: [u8; 32]

semantics_id stored in the blob’s header.

expected: [u8; 32]

crate::PHYSICS_SEMANTICS_ID of this binary.

LawIdMismatch

The version 4 blob’s header law_id differs from the identifier passed to PhysicsWorld::restore_world_checked.

Fields

stored: [u8; 32]

law_id stored in the blob’s header.

expected: [u8; 32]

The identifier the caller expected.

Trait Implementations

impl Clone for WorldSnapshotError

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for WorldSnapshotError

impl Debug for WorldSnapshotError

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

Formats the value using the given formatter.

impl Display for WorldSnapshotError

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

Formats the value using the given formatter.

impl Eq for WorldSnapshotError

impl Error for WorldSnapshotError

Available on crate feature std only.

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for WorldSnapshotError

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for WorldSnapshotError