Profiling PhysX Physics Simulations

Overview

Physics simulation of objects via the PhysX physics engine during play can add a great deal of realism and visual polish to your game, but it also has the potential to affect performance. In order to monitor and analyze the physics simulation, Unreal Engine 3 provides some built-in features to visualize and output information. Third party tools are also provided by nVidia which enable very detailed profiling capabilities.

STAT Comannds

STAT commands are one of the most useful and common methods of profiling. By using the STAT commands, you can view a group of statistics on the screen giving a realtime snapshot of what is going on under the hood. This makes it extremely easy to go to a specific trouble spot in the game and see immediately what might be the issue.

STAT PHYSICS

The STAT PHYSICS command shows statistics about the PhysX phsyics engine.

• Novodex Allocator Time - Allocating memory to PhysX.
• Physics Stats Time - Capturing stats for the physics system.
• Fluid Mesh Emitter Time -
• Broadpahse GetPairs Time -
• Broadphase Update Time -
• Nearphase Time -
• Solver Time -
• Substep Time - Average substep time.
• Phys LineCheck Time -
• Phys Wait Time -
• Phys Events Time -
• Fetch Results -
• Start Physics Time -
• Total Dynamics Time -

• Novodex Allocation Size - Total amount of memory allocated to PhysX.

• Novodex Allocation Count - Total memory allocations to PhysX.
• Num Substeps - The number of sub steps the time step is divided into.
• Total SW Dynamic Bodies - Number of dynamic actors present in the scene for the current simulation step.
• Awake SW Dynamic Bodies - Number of dynamic actors which are not part of a sleeping group(island).
• Solver Bodies - Number of solver bodies present in the current step(i.e. the number of bodies subject to constraints). Not supported in 2.6.
• Num Pairs - Number of shape pairs present in the scene for the current simulation step.
• Num Contacts - Number of contacts present in the scene for the current simulation step. Not supported in 2.6.
• Num Joints - Number of joints in the scene. Note that this number also includes all "dead joints" in the scene (see NxScene.releaseActor).
• Num ConvexMesh - Total number of PhysX convex meshes in the scene.
• num TriMesh - Total number of PhysX triangle meshes in the scene.

STAT PHYSICSCLOTH

The STAT PHYSICSCLOTH command shows information about PhysX cloth simulations.

• Total Cloths - Total cloth simulations.
• Active Cloths - Active cloth simulations.
• Active Cloth Vertices - Number of vertices being simulated in active cloth simulations.
• Total Cloth Vertices - Total cloth vertices in all cloth simulations.
• Active Attached Cloth Vertices - Number of attached vertices in active cloth simulations.
• Total Attached Cloth Vertices - Total attached vertices in all cloth simulations.

STAT PHYSICSFIELDS

The STAT PHYSICSFIELDS command shows information about PhysX force fields.

• CylindricalForceFieldTick - Ticking cylinder force fields.
• RadialForceFieldTick - Ticking radial force fields.

STAT PHYSICSFLUID

The STAT PHYSICSFLUID command shows information about PhysX fluid emitters.

• PhysXEmitterVertical Tick Time -
• PhysXEmitterVertical Sync Time -

• Total Fluids - Total PhysX fluid simulations.
• Total Fluid Emitters - Total PhysX fluid emitters.
• Active Fluid Particles - Number of fluid particles in active simulations.
• Total Fluid Particles - Total fluid particles.
• Total Fluid Packets - Total fluid packets.

In-Game Visualization

The NXVIS command can be used with one of a great deal of options to display various data of the physics simulation directly in the viewport during play. This provides the ability to see exactly what is going on with complete interactive control.

For example, physics collision primitives can be displayed by using the NXVIS COLLISION command:

A complete list of the available options for the NXVIS command and descriptions of each can be found in the Physics Commands section of the Console Commands page.

PhysX Visual Debugger

The PhysX Visual Debugger is an application provided by nVidia that can be used to capture and analyze data from the physics simulation(s) being run during play in Unreal Engine 3.

Download and Installation

The PhysX Visual Debugger can be obtained from nVidia's Developer Support site. Simply navigate to the following location:

• Online Support > Downloads > PhysX Tools
  

Note: Access to the download for the PhysX Visual Debugger is restricted to registered developers. You can request an account from the Sign In page of the Developer Support site.

Once installed, the PhysX Visual Debugger can be run from the Start Menu (Start > All Programs > NVIDIA Corporation > NVIDIA PhysX Visual Debugger) or by navigating to the directory the application was installed to and running the .exe from there.

Performing a Debugging Session

With the application open, you can connect to the debugger from the game using the following console command:

• Original Command
  • nxvrd connect [IP address of host] - Provides object debugging

• New commands
  • nxpvd connect_object [IP address of host] - provides object debugging
  • nxpvd connect_profile [IP address of host] - provides profiling debugging for APEX

The IP address of the host is only needed when running on console (which needs an additional ini setting to work - the PC version will have the same physics object data, though not performance, so let's start there). When running on PC, it knows just to connect locally. This will begin recording a "clip" that we can inspect later. When the recording starts, there will be a long initial pause, then minimal runtime impact afterward. When you're ready to stop recording a clip, type:

• Original Command
  • nxvrd disconnect

• New commands
  • nxpvd disconnect

The scene should be populated with a representation of the map being run in the game.

You can now analyze the PhysX data in the debugger (you might need to scrub using the slider to make things appear). One of the easiest things to look for that will be a good initial indicator of performance spikes is the number of actors in the scene. Big jumps up are unavoidable but not great, but huge drops are actually more problematic for performance, so keep an eye out for those. To bring up the object count window, do the following:

1. Open the All Objects panel or tab if it is not already visible.
   
2. Expand the NxScene item in the list view and select "Scene stats"
   
3. In the Inspector window in the left, find "Number of actors"
   
4. Select "Graph Number of actors for Scene stats"
   
5. This should bring up a new tab on the right that shows a timeline of the number of physics actors are in the scene.
   

The commands below can be useful during a profiling session. With an actor selected:

In the Dynamic Commands menu there are several other useful commands that can be used during a debugging session such as Graph contact characteristics, Graph inner/outer frame times (PhysX 3.0), etc.

Annotations

Annotations allow you to mark interesting frames and properties so they can be quickly jumped to and viewed at any time. This is useful if you want to pass PVD files around (to the PhysX Support team), people can just click the annotation and the PVD will jump to that interesting frame. E.g "Box starts to penetrate from this frame".

To create an Annotation:

1. Go to the frame where something interesting occurs and press Ctrl + Alt + A. The Create Annotation dialog will appear:
   
2. Enter the Name and Description for the new annotation:
   
3. Click the button to create the annotation. It will then be visible in the Annotations panel:
   

Preferences

The preferences panel in the PhysX Visual Debugger allows you to configure the display of additional info int he viewports, where files are saved, how viewport navigation works, and much more.

The Preferences panel can be accessed from the View menu:

Capture & Playback

The Capture & Playback preferencesallow you to configure how data is captured and displayed. The settings that are of particular interest here are:

• Temp Directory - This allows you to specify the directory where the temporary files are created and stored.
• Navigation Scheme - This sets how the viewport is navigated. The Maya scheme makes selecting actors a simple one-click operation, which can be helpful.

Visualization

The settings in the Visualization section control what additional data is displayed along wiith other viewport-specific options.

• Contacts - Display collision contacts.
• Bounding Boxes - Display bounding boxes for actors.
  
• Center of Mass - Display the centers of mass for actors.
  
• Frames - Display coordinate reference frames.
  
• Velocities - Display velcoties for moving actors.
  
• Transparency - Draw actors as transparent.
• Transparency Amount - Determines how transparent actors are drawn when using transparency.
  
• Gizmo Scale - The size of the gizmos used when drawing frames, centers of mass, etc.
  
• Culling Far Distance - How far away objects are drawn in the viewport.
• Culling Near Distance - How close objects are drawn in the viewport.
• Camera Speed Scale - The speed at which the camera moves when navigating the viewport.

Coordinates

• Orientation - Sets the orientation to left- or right-handed.
• Up Axis - Sets which axis is used as the up axis in the viewport.

For more information on the settings available, please see the help file accessed through the Help menu.