Omni PhysX Character Controller

The omni.physxcct extension adds support for a capsule-based kinematic character controller i.e. a way for a user controlled character to move through a scene using a collide-and-slide collision algorithm. Character controller is represented by the PhysxCharacterControllerAPI in the PhysxSchema schema (see our USD schema documentation)

For a wide array of CCT usage see the “Python” or “Action Graph” demos in the Demos/Character Controller category (CharacterControllerDemo.py, CharacterControllerActionGraph.py).

Setup and Controls

from omni.physxcct.scripts import utils

# set up a base capsule
utils.spawn_capsule(stage, cct_path, position)

# start first-person CCT control with gravity
utils.activate_cct(stage, cct_path, "/OmniverseKit_Persp", True)

# activate default controls (keyboard/mouse or gamepad)
control_state = utils.setup_controls(cct_path, speed)

Manual Setup

from omni.physxcct import get_physx_cct_interface
from pxr import UsdGeom, PhysxSchema

# set up a base capsule
capsule_geom = UsdGeom.Capsule.Define(stage, capsule_path)
capsule_geom.CreateHeightAttr(50.0)
capsule_geom.CreateRadiusAttr(25.0)
capsule_geom.CreateAxisAttr(UsdGeom.GetStageUpAxis(stage))

# apply CCT API
capsule_prim = stage.GetPrimAtPath(capsule_path)
cct = PhysxSchema.PhysxCharacterControllerAPI.Apply(capsule_prim)

# start first-person CCT control with gravity
physx_cct = get_physx_cct_interface()
physx_cct.enable_first_person(self._path_cct, True)
physx_cct.enable_gravity(self._path_cct)
physx_cct.set_current_camera("/OmniverseKit_Persp")

Manual Controls

# multiply speed constant with current frametime
speed = 10 * dt

# add up directions and normalize to account for possible diagonal movement
x = control_up + control_down * -1
y = control_left + control_right * -1
move = Gf.Vec3f(x * speed, y * speed, 0).GetNormalized()

# set move to usd
get_physx_cct_interface().set_move(state.cct_path, (move[0], move[1], move[2]))

Note that the CharacterControllerAPI:MoveTarget attribute is by default considered a local space vector of either the CCT Capsule prim or the CCT first person camera prim (when in first person mode). To consider it as a world space vector call (use_worldspace_move(True)).

Python API

Python Bindings API

pybind11 carb.physx.cct bindings

class omni.physxcct.bindings._physxCct.CctEvent

Cct events used by Cct event stream.

Members:

COLLISION_DOWN : Character controller collision down event, during the last cct move a collision below the CCT was found and the status changed; contains the following in a dictionary:

'cctPath':int2 - Usd path to the CCT decoded into two ints. PhysicsSchemaTools.decodeSdfPath will return SdfPath.
'collision':bool - Reports current collision with CCT.

COLLISION_UP : Character controller collision down event, during the last cct move a collision above the CCT was found and the status changed; contains the following in a dictionary:

'cctPath':int2 - Usd path to the CCT decoded into two ints. PhysicsSchemaTools.decodeSdfPath will return SdfPath.
'collision':bool - Reports current collision with CCT.

COLLISION_SIDES : Character controller collision down event, during the last cct move a collision on a side of the CCT was found and the status changed; contains the following in a dictionary:

'cctPath':int2 - Usd path to the CCT decoded into two ints. PhysicsSchemaTools.decodeSdfPath will return SdfPath.
'collision':bool - Reports current collision with CCT.
COLLISION_DOWN = <CctEvent.COLLISION_DOWN: 0>
COLLISION_SIDES = <CctEvent.COLLISION_SIDES: 2>
COLLISION_UP = <CctEvent.COLLISION_UP: 1>
property name
property value
class omni.physxcct.bindings._physxCct.IPhysxCct
activate_cct(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → None

Adds character controller to the manager. Use if not calling any of the other methods at least once.

Parameters

path – Path of the controller’s prim.

disable_first_person(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → None

Disable first person camera support.

Parameters

path – Path of the controller’s prim.

disable_gravity(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → None

Disables gravity set through apply_gravity or apply_custom_gravity.

Parameters

path – Path of the controller’s prim.

enable_custom_gravity(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: carb._carb.Double3) → None

Adds custom gravity to the controller’s move vector.

Parameters

  • path – Path of the controller’s prim.

  • gravity – Custom gravity vector.

enable_first_person(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: str) → None

Enable first person camera support for a controller. Hides mouse cursor, sets the controller’s capsule as a guide and uses the controller’s camera transformation when transforming move vector in local space mode. If you want to use multiple controllers at the same time use setViewportIndex.

Parameters

  • path – Path of the controller’s prim.

  • camera_path – Camera path.

enable_gravity(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → None

Adds current PhysicsScene’s gravity to the controller’s move vector.

Parameters

path – Path of the controller’s prim.

enable_worldspace_move(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: bool) → None

Sets if PhysxCharacterControllerAPI:MoveTarget attribute will be considered as a local or world space vector. Local space move vector is transformed with the controller’s capsule transformation (or camera transformation in the case of first person mode).

Parameters

use – World space is used when true, local space if false.

get_cct_event_stream(self: omni.physxcct.bindings._physxCct.IPhysxCct) → carb.events._events.IEventStream

Simulation event stream sending various simulation events defined in SimulationEvent enum.

Returns

Event stream sending the simulation events.

get_controller_height(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → float

Gets controller’s height.

Parameters

path – Path of the controller’s prim.

Returns

The height of the controller.

Return type

float

has_gravity_enabled(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → bool

Gets if gravity is being added to the controller’s move vector.

Parameters

path – Path of the controller’s prim.

remove_cct(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str) → None

Removes a character controller’s data from the manager.

Parameters

path – Path of the controller’s prim.

set_controller_height(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: float) → None

Set the controller’s height. This does not check for collisions.

Parameters

  • path – Path of the controller’s prim.

  • val – New controller height.

set_move(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: carb._carb.Float3) → None

Move a controller by a given vector each frame (internally sets CharacterControllerAPI:MoveTarget). The vector is transformed from local to world space by either the controller’s capsule or camera (if in first person mode) transformation. Use enable_worldspace_move to skip the local->world transform.

Parameters

  • path – Path of the controller’s prim.

  • displacement – Displacement vector.

set_position(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: carb._carb.Double3) → None

Set the position of the center of the controller’s collision. This does not check for collisions.

Parameters

  • path – Path of the controller’s prim.

  • position – New center position of the controller.

omni.physxcct.bindings._physxCct.acquire_physx_cct_interface(plugin_name: str = None, library_path: str = None) → omni.physxcct.bindings._physxCct.IPhysxCct
omni.physxcct.bindings._physxCct.release_physx_cct_interface(arg0: omni.physxcct.bindings._physxCct.IPhysxCct) → None

OmniGraph Nodes