ke.physics

Low-level PhysX world, rigid body, articulation, and visual sync APIs.

API overview

PhysicsConfig

PhysX world configuration including timestep, up axis, and reporting.

PhysicsWorld

PhysX simulation world.

ArticulationConfig

PhysX articulation construction settings.

Articulation

PhysX articulation wrapper.

PhysicsBridge

Sync PhysX articulation state into scene/render visuals.

GpuPhysicsConfig

Configuration for explicit GPU physics state synchronization.

PhysicsGpuSystem

Explicit GPU physics synchronization wrapper.

Wrapper and lifetime policy

The Python low-level physics API is exposed through thin wrapper classes around native pybind11 objects. The wrapper classes remain importable for stable IDE completion and API documentation even when KangEngine is built without PhysX; constructing or using a PhysX-backed object in such a build raises a runtime error.

Use the .native property only when deliberately dropping to native parity. Helper code that accepts either wrapper or native objects should normalize with unwrap_native(obj).

Contact queries and GPU state views expose backend-owned state. Treat PhysicsWorld.get_contacts(), PhysicsWorld.get_contact_forces(...), and PhysicsGpuSystem.views() conservatively: later simulation, synchronization, refresh, or clear operations may update or invalidate the underlying storage. Copy returned array-like data explicitly when a stable snapshot is required.

Return and error contracts

API

Contract

PhysicsGpuSystem.views() and GPU buffer accessors

Borrowed device storage owned by the GPU system. Fetch and apply methods update it; releasing or invalidating the system invalidates the view.

PhysicsWorld.get_contacts() and get_contact_forces(...)

Current-query data only. Copy values that must remain stable across later simulation or clear operations.

Resource and actor wrappers

Native handles tied to their owning world. Using them after world release raises RuntimeError or results in an invalid native handle.

Invalid indices and names generally raise KeyError or IndexError; invalid shapes and configuration values raise ValueError; unavailable PhysX/CUDA features and invalid lifecycle state raise RuntimeError.

class kangengine.physics.PhysicsConfig[native]

PhysX world configuration including timestep, up axis, and reporting.

__init__(
*,
dt: float = 1.0 / 60.0,
solver_type: int = 1,
static_friction: float = 1.0,
dynamic_friction: float = 1.0,
restitution: float = 0.0,
enable_gpu: bool = False,
gpu_dynamics: PhysicsGpuDynamicsConfig = PhysicsGpuDynamicsConfig(),
enable_contact_reports: bool = True,
enable_body_accelerations: bool = False,
cpu_dispatcher_threads: int = 4,
bounce_threshold_velocity: float = 2.0,
friction_offset_threshold: float = 0.03999999910593033,
friction_correlation_distance: float = 0.02500000037252903,
enable_stabilization: bool = False,
)

Create physics configuration from keyword arguments.

property bounce_threshold_velocity

Relative speed below which contacts do not bounce.

property cpu_dispatcher_threads

Worker threads used by the PhysX CPU dispatcher.

property dt

Simulation timestep in seconds.

property dynamic_friction

Default material dynamic friction.

property enable_body_accelerations

Enable PhysX rigid-body acceleration state.

property enable_contact_reports

Enable contact collection during simulation.

property enable_gpu

Enable PhysX GPU features when available.

property enable_stabilization

Enable the PhysX scene stabilization pass.

property friction_correlation_distance

Distance used to correlate friction patches.

property friction_offset_threshold

Contact separation threshold for friction anchors.

property gpu_dynamics

GPU dynamics memory capacities used at scene creation.

property restitution

Default material restitution.

property solver_type

0 for PGS, 1 for TGS.

Type:

Solver type

property static_friction

Default material static friction.

static y_up() → PhysicsConfig

Create configuration for a Y-up world.

static z_up() → PhysicsConfig

Create configuration for a Z-up world.

class kangengine.physics.PhysicsGpuDynamicsConfig[native]

PhysX GPU dynamics buffer capacities used during scene creation.

__init__(
*,
temp_buffer_capacity: int = 67108864,
max_rigid_contact_count: int = 4194304,
max_rigid_patch_count: int = 524288,
heap_capacity: int = 268435456,
found_lost_pairs_capacity: int = 4194304,
found_lost_aggregate_pairs_capacity: int = 33554432,
total_aggregate_pairs_capacity: int = 2097152,
collision_stack_size: int = 268435456,
max_num_partitions: int = 8,
)

Create GPU dynamics capacities from keyword arguments.

property collision_stack_size

GPU collision stack size in bytes.

property found_lost_aggregate_pairs_capacity

Capacity for found and lost aggregate pairs.

property found_lost_pairs_capacity

Capacity for found and lost rigid pairs.

property heap_capacity

GPU dynamics heap capacity in bytes.

property max_num_partitions

Maximum GPU dynamics partition count.

property max_rigid_contact_count

Maximum rigid contact count.

property max_rigid_patch_count

Maximum rigid contact patch count.

property temp_buffer_capacity

Temporary GPU buffer capacity in bytes.

property total_aggregate_pairs_capacity

Capacity for all aggregate pairs.

class kangengine.physics.PhysicsMaterialDesc[native]

PhysX material factors used by collision shapes.

as_tuple() → tuple[float, float, float]

Return (static_friction, dynamic_friction, restitution).

property dynamic_friction

PhysX dynamic friction coefficient.

property restitution

PhysX restitution coefficient.

property static_friction

PhysX static friction coefficient.

class kangengine.physics.CollisionMaterialOverride[native]

Collision material override matched by body/geom name or index. Later overrides win.

static all_geoms(
material: object,
) → CollisionMaterialOverride

Override every collision geom in the built actor/articulation.

property body_index

Matched body index, or -1 for name/all matching.

property body_name

Matched body name, or empty for all bodies.

static for_body(
body_name: str,
material: object,
) → CollisionMaterialOverride

Override every collision geom on a named body.

static for_geom(
body_name: str,
geom_name: str,
material: object,
) → CollisionMaterialOverride

Override one named collision geom on a named body.

static for_indices(
body_index: int,
geom_index: int,
material: object,
) → CollisionMaterialOverride

Override by imported body index and collision geom index.

property geom_index

Matched geom index inside the body, or -1.

property geom_name

Matched geom name, or empty for all geoms.

property material

Override material.

class kangengine.physics.ContactPoint[native]

Contact point reported by the PhysX world.

property impulse

Contact impulse.

property normal

World-space contact normal.

property position

World-space contact position.

property separation

Contact separation distance.

class kangengine.physics.RigidDynamic(*args, **kwargs)[python]
kangengine.physics.unwrap_native(obj: Any) → Any[python]

Return obj._native when obj is a KangEngine Python wrapper.

Return type:

Any

kangengine.physics.mjcf_friction_to_physx(
friction: collections.abc.Sequence[float],
) → PhysicsMaterialDesc[native]

Map MJCF geom friction values to KangEngine’s PhysX material descriptor.

class kangengine.physics.PhysicsWorld(config: PhysicsConfig | None = None)[python]

Bases: _NativeWrapper

PhysX simulation world.

The class is always importable. Constructing it requires a KangEngine build with PhysX bindings. The wrapper owns a native _ke.physics.PhysicsWorld and forwards calls directly.

add_default_ground() → None
Return type:

None

add_heightfield(
heights: Any,
rows: int,
cols: int,
horizontal_scale: float = 1.0,
up_axis: Any = None,
center: bool = True,
register_as_ground: bool = True,
material: PhysicsMaterialDesc | None = None,
) → bool
Return type:

bool

add_heightmap_collision(
path: str,
up_axis: Any = None,
horizontal_scale: float = 1.0,
height_scale: float = 64.0,
height_offset: float = -16.0,
sample_stride: int = 1,
center: bool = True,
register_as_ground: bool = True,
material: PhysicsMaterialDesc | None = None,
) → bool
Return type:

bool

add_static_box(
half_extents: Sequence[float],
pos: Sequence[float],
rot_xyzw: Sequence[float] = (0.0, 0.0, 0.0, 1.0),
register_as_ground: bool = True,
) → None
Return type:

None

clear_contacts() → None
Return type:

None

clear_ground_actors() → None
Return type:

None

create_dynamic_box(
half_extents: Sequence[float],
pos: Sequence[float],
rot_xyzw: Sequence[float] = (0.0, 0.0, 0.0, 1.0),
density: float = 1.0,
) → RigidDynamic
Return type:

RigidDynamic

create_dynamic_convex_compound(
parts: Sequence[ConvexMeshPart],
pos: Any,
rot_xyzw: Any = (0.0, 0.0, 0.0, 1.0),
density: float = 1.0,
cooking: ConvexCookingOptions | None = None,
material: PhysicsMaterialDesc | None = None,
collision_group: int = 0,
contact_offset: float = 0.02,
rest_offset: float = 0.0,
) → RigidDynamic

Cook convex parts as shapes on one dynamic rigid body.

Return type:

RigidDynamic

create_dynamic_rigid(
data: Any,
pos: Any,
rot_xyzw: Any = (0.0, 0.0, 0.0, 1.0),
density: float = 1.0,
collision_group: int = 0,
contact_offset: float = 0.02,
rest_offset: float = 0.0,
material_overrides: Sequence[CollisionMaterialOverride] = (),
) → RigidDynamic
Return type:

RigidDynamic

create_dynamic_sphere(
radius: float,
pos: Sequence[float],
rot_xyzw: Sequence[float] = (0.0, 0.0, 0.0, 1.0),
density: float = 1.0,
) → RigidDynamic
Return type:

RigidDynamic

create_static_convex_compound(
parts: Sequence[ConvexMeshPart],
pos: Any = (0.0, 0.0, 0.0),
rot_xyzw: Any = (0.0, 0.0, 0.0, 1.0),
cooking: ConvexCookingOptions | None = None,
material: PhysicsMaterialDesc | None = None,
collision_group: int = 0,
contact_offset: float = 0.02,
rest_offset: float = 0.0,
register_as_ground: bool = False,
) → Any

Cook convex parts as shapes on one static rigid body.

Return type:

Any

get_contact_forces(
articulation: Articulation | Articulation,
ground_only: bool = False,
) → Any

Return contact-force data for an articulation.

The concrete return type is backend-dependent. Treat array-like results as borrowed or refreshable data unless you explicitly copy them; later simulation steps or synchronization calls may update the underlying storage.

Return type:

Any

get_contacts() → Sequence[ContactPoint]

Return the latest contact records from the native physics backend.

Treat the returned data conservatively: depending on the active backend, contact records may reference native buffers or describe only the most recent simulation synchronization point. Do not assume they remain unchanged after later step(), sync(), or clear_contacts() calls.

Return type:

Sequence[ContactPoint]

get_ground_contact_forces(
articulation: Articulation | Articulation,
) → Any
Return type:

Any

get_rigid_contact_force(
rigid: RigidDynamic,
ground_only: bool = False,
) → Any
Return type:

Any

get_rigid_ground_contact_force(
rigid: RigidDynamic,
) → Any
Return type:

Any

num_body_actors() → int
Return type:

int

num_cached_materials() → int
Return type:

int

num_contacts() → int
Return type:

int

num_ground_actors() → int
Return type:

int

set_dt(dt: float) → None
Return type:

None

set_rigid_collision_material(
rigid: RigidDynamic,
material: PhysicsMaterialDesc,
) → int
Return type:

int

set_rigid_collision_material_overrides(
rigid: RigidDynamic,
data: Any,
material_overrides: Sequence[CollisionMaterialOverride],
) → int
Return type:

int

step() → None

Advance simulation by one configured timestep.

Return type:

None

class kangengine.physics.ArticulationConfig[native]

PhysX articulation construction settings.

__init__(
*,
fix_base: bool = True,
disable_self_collision: bool = True,
use_aggregate: bool = False,
solver_position_iteration_count: int = 16,
solver_velocity_iteration_count: int = 1,
collision_group: int = 0,
root_linear_damping: float = 0.0,
root_angular_damping: float = 0.05000000074505806,
link_linear_damping: float = 0.0,
link_angular_damping: float = 0.05000000074505806,
max_angular_velocity: float = 100.0,
max_depenetration_velocity: float = 1.0000000331813535e+32,
sleep_threshold: float = 0.004999999888241291,
stabilization_threshold: float = 0.0005000000237487257,
enable_gyroscopic_forces: bool = False,
contact_offset: float = 0.019999999552965164,
rest_offset: float = 0.0,
material_overrides: collections.abc.Sequence[CollisionMaterialOverride] = [],
enable_ccd: bool = False,
)

Create articulation configuration from keyword arguments.

add_material_override(
self: ArticulationConfig,
override: CollisionMaterialOverride,
) → ArticulationConfig

Append a build-time collision material override. Later overrides win.

clear_material_overrides(
self: ArticulationConfig,
) → ArticulationConfig

Remove all collision material overrides.

property collision_group

Collision group bit used for created actors.

property contact_offset

PhysX contact offset.

property disable_self_collision

Disable self collision between articulation links.

property enable_ccd

Enable continuous collision detection.

property enable_gyroscopic_forces

Enable gyroscopic forces on articulation links.

property fix_base

Whether the root body is fixed.

static fixed_base() → ArticulationConfig

Create configuration for a fixed-base articulation.

static free_base() → ArticulationConfig

Create configuration for a free-base articulation.

Angular damping for child links.

Linear damping for child links.

property material_overrides

Build-time collision material overrides.

property max_angular_velocity

Maximum angular velocity for links.

property max_depenetration_velocity

Maximum depenetration velocity for links.

property rest_offset

PhysX rest offset.

property root_angular_damping

Angular damping for the root link.

property root_linear_damping

Linear damping for the root link.

property sleep_threshold

Articulation sleep threshold.

property solver_iterations

Compatibility alias for solver_position_iteration_count.

property solver_position_iteration_count

Position solver iteration count.

property solver_velocity_iteration_count

Velocity solver iteration count.

property stabilization_threshold

Articulation stabilization threshold.

property use_aggregate

Group articulation links into one PhysX broadphase aggregate.

class kangengine.physics.Articulation(native_articulation: Any | None = None)[python]

Bases: _NativeWrapper

PhysX articulation wrapper.

static build(
physics: PhysicsWorld | PhysicsWorld,
data: Any,
config: ArticulationConfig | None = None,
) → Articulation
Return type:

Articulation

Return type:

list[int]

num_dofs() → int
Return type:

int

Return type:

int

release() → None
Return type:

None

set_collision_material(
physics: PhysicsWorld | PhysicsWorld,
material: PhysicsMaterialDesc,
) → int
Return type:

int

set_collision_material_overrides(
physics: PhysicsWorld | PhysicsWorld,
material_overrides: Sequence[CollisionMaterialOverride],
) → int
Return type:

int

class kangengine.physics.PhysicsBridge → None[python]

Bases: _NativeWrapper

Sync PhysX articulation state into scene/render visuals.

add(
artic: Articulation | Articulation,
skel_bridge: Any,
) → None
Return type:

None

add_collision_visuals(
artic: Articulation | Articulation,
scene: Any,
path: str = '/collision',
visible_by_default: bool = False,
)
set_collision_visible(visible: bool) → None
Return type:

None

sync() → None
Return type:

None

class kangengine.physics.GpuPhysicsConfig[native]

Configuration for explicit GPU physics state synchronization.

__init__(
*,
cuda_device_id: int = 0,
max_contact_pairs: int = 65536,
max_contact_points: int = 262144,
)

Create GPU synchronization configuration from keyword arguments.

property cuda_device_id

CUDA device ordinal used by GPU physics.

property max_contact_pairs

Maximum mirrored contact pair count.

property max_contact_points

Maximum mirrored contact point count.

class kangengine.physics.PhysicsGpuStateViews[native]

Backend-owned GPU state and command-buffer views. State buffers are refreshed by the corresponding fetch methods; command buffers are submitted by apply methods. The views become invalid when their PhysicsGpuSystem is released.

property articulation_centroidal_bias_forces
property articulation_centroidal_momentum_matrices
property articulation_com_root
property articulation_com_world
property articulation_coriolis_forces
property articulation_dense_jacobians
property articulation_gravity_forces
property articulation_joint_accelerations

Articulation joint-acceleration state.

property articulation_joint_forces

Articulation joint-force state.

property articulation_joint_positions

Articulation joint-position state.

property articulation_joint_velocities

Articulation joint-velocity state.

Articulation link pose and velocity state.

Incoming joint-force state for articulation links.

property articulation_mass_matrices
property articulation_target_joint_positions

Joint-position target command buffer.

property articulation_target_joint_velocities

Joint-velocity target command buffer.

property contact_pair_body_refs

Body references for packed contact pairs.

property contact_pair_count

Number of valid packed contact pairs.

property contact_pair_headers

Headers describing packed contact-pair ranges.

property contact_pairs

Packed contact-pair state buffer.

property contact_point_count

Number of valid packed contact points.

property contact_point_pair_indices

Contact-pair index for each packed contact point.

property contact_points

Packed contact-point state buffer.

property rigid_accelerations

Rigid COM linear/angular acceleration state.

property rigid_data

Rigid pose and velocity state refreshed by fetch_rigid_data().

property rigid_force

Rigid force command buffer submitted by apply_rigid_force().

property rigid_torque

Rigid torque command buffer submitted by apply_rigid_torque().

class kangengine.physics.PhysicsGpuSystem(
world: PhysicsWorld | PhysicsWorld,
config: GpuPhysicsConfig | None = None,
)[python]

Bases: _NativeWrapper

Explicit GPU physics synchronization wrapper.

articulation_row(
articulation: Articulation | Articulation,
) → int
Return type:

int

rigid_row(rigid: RigidDynamic) → int
Return type:

int

views() → PhysicsGpuStateViews

Return borrowed GPU state views owned by this PhysicsGpuSystem.

The returned object may reference buffers managed by the native GPU physics system. Keep this PhysicsGpuSystem alive while using the views, and do not assume values remain unchanged after later simulation, synchronization, or refresh operations.

Return type:

PhysicsGpuStateViews

kangengine.physics.aggregate_contact_sensors_cuda(...)[native]

Aggregates contact sensor outputs on the GPU. Available only in CUDA-enabled builds.

Collision visual notes

PhysicsBridge.add_collision_visuals(...) creates optional SceneGraph debug prims for articulation collision shapes. These prims mirror the existing PhysX collision descriptors and carry scene-side CollisionShapeComponent metadata; they do not create additional simulation shapes.

MJCF primitive collision geoms are imported directly. Collidable MJCF mesh geoms are not cooked yet; bodies with unsupported collidable mesh geoms may receive KangEngine fallback boxes. Visual-only mesh geoms remain render-only.