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 two PhysxSchema APIs: CharacterControllerAPI and PhysxCharacterControllerAPI (see our USD schema documentation)

For a wide array of CCT usage see the “Arena” demo in the Demos/Character Controller category (CharacterControllerDemo.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

class omni.physxcct.scripts.utils.ControlFlag(value)

Flags for activating features in setup_controls.

DEFAULT = 7: Default setup with both keyboard/mouse and gamepad

GAMEPAD = 4: Use gamepad controls

GAMEPAD_DEFAULT = 5: Default setup with gamepad only

KBD_MOUSE = 2: Use keyboard and mouse controls

KBD_MOUSE_DEFAULT = 3: Default setup with keyboard/mouse only

VERTICAL_MOVEMENT = 1: Full vertical movement with gravity off, jumping with gravity on.

class omni.physxcct.scripts.utils.ControlState(speed, with_camera): Keeps track of cct controls internal state.

omni.physxcct.scripts.utils.spawn_capsule(stage, path, pos, height=50, radius=25): Capsule prim creation helper.

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

COLLISION_SIDES = CctEvent.COLLISION_SIDES

COLLISION_UP = CctEvent.COLLISION_UP

property name

handle) -> str

Type: (self

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.

register_gamepad_action(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: carb.input.GamepadInput, arg2: int) → None

Registers a gamepad action mapping. The action will be active only during simulation mode in first person mode and conflicting actions would be automatically disabled.

Parameters

action_name – Name of the action.
input – Gamepad input to activate the action with.
index – Gamepad index.

register_keyboard_action(self: omni.physxcct.bindings._physxCct.IPhysxCct, arg0: str, arg1: carb.input.KeyboardInput, arg2: int) → None

Registers a keyboard action mapping. The action will be active only during simulation mode in first person mode and conflicting actions would be automatically disabled.

Parameters

action_name – Name of the action.
input – Keyboard input to activate the action with.
modifiers – Keyboard modifier.

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.

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

Unregisters an action mapping registered with either register_keyboard_action or register_gamepad_action.

Parameters: action_name – Name of the action.

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