simvx.core.physics.material

Role

A plain VALUE resource (not a Node) carried by a Property on a body, mirroring how :class:~simvx.core.physics.shapes.Shape resources are carried. It groups the four surface coefficients (friction, restitution, and an independent combine mode for each) so a single resource serialises as one nested value and can be shared across many bodies for a common surface.

This is the NEW system’s material, deliberately SEPARATE from the OLD physics/_material.py PhysicsMaterial (which carries a density field and defaults restitution to 0.3). The two classes coexist by design during the staged rewrite; this one is never imported from the old module. The key default difference: this material defaults restitution to 0.0, so adding materials to an existing scene does NOT silently start bouncing previously-inelastic bodies.

Combine modes (the differentiator over Godot / Jolt)

Friction and restitution combine INDEPENDENTLY, each with one of Unity’s four modes (AVERAGE / MIN / MAX / MULTIPLY). Godot and Jolt hardcode a single rule for both; exposing two independent modes is the design’s deliberate edge.

When the two contacting materials request DIFFERENT modes for the same coefficient, the higher-priority mode wins (Unity’s documented priority order): MAX > MIN > MULTIPLY > AVERAGE. The least-surprising authoring behaviour: a deliberately grippy / bouncy surface dominates a neutral one. See :func:_combine.

PhysicsMaterial: surface friction + restitution + combine modes (Stage T1d).

Module Contents

Classes

CombineMode	How two materials’ coefficients combine at a contact (Unity’s four modes).
PhysicsMaterial	Surface material: friction + restitution + per-coefficient combine modes.

Data

__all__
DEFAULT_PHYSICS_MATERIAL

API

simvx.core.physics.material.__all__

[‘CombineMode’, ‘PhysicsMaterial’]

class simvx.core.physics.material.CombineMode

Bases: enum.Enum

How two materials’ coefficients combine at a contact (Unity’s four modes).

String values (parity with :class:~simvx.core.physics.world.BodyMode), so it serialises and inspects cleanly. NOT an IntEnum: the differing-mode priority is an explicit dict (:data:_PRIORITY), never the enum ordinal, so reordering the members can never silently change priority.

AVERAGE

‘average’

MIN

‘minimum’

MAX

‘maximum’

MULTIPLY

‘multiply’

__new__(value)

__repr__()

__str__()

__dir__()

__format__(format_spec)

__hash__()

__reduce_ex__(proto)

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.physics.material.PhysicsMaterial

Surface material: friction + restitution + per-coefficient combine modes.

A mutable value resource (slots, not frozen): the inspector edits a body’s own instance in place, so each body owns its own material via the body Property’s default_factory (a shared mutable default would alias edits across bodies). The module-level :data:DEFAULT_PHYSICS_MATERIAL singleton is the never-mutated seam fallback for a body with no material set.

Attributes: friction: Coulomb friction coefficient mu (>= 0; no hard upper bound). 0 is frictionless; ~0.5 is a sensible default. restitution: Bounciness in [0, 1]. 0 is fully inelastic (the engine default: adding a material never starts bouncing an existing scene); 1 is a perfectly elastic bounce. friction_combine: How this material’s friction combines with a contacting material’s (see :class:CombineMode). restitution_combine: How this material’s restitution combines, independent of friction_combine (the Godot / Jolt-beating differentiator).

friction: float

0.5

restitution: float

0.0

friction_combine: simvx.core.physics.material.CombineMode

None

restitution_combine: simvx.core.physics.material.CombineMode

None

__post_init__() → None

simvx.core.physics.material.DEFAULT_PHYSICS_MATERIAL

‘PhysicsMaterial(…)’