Proposed RFC Feature : PhysX Gem 4/5 Split

[spham-amzn]

Summary:

The PhysX gem currently supports either the PhysX 4 or PhysX 5 library from NVIDIA. However, the version of PhysX that the gem links against is determined by a cmake switch at project generation time, meaning that only one of the versions is available. This puts a restriction on the engine to be either built with PhysX 4 or PhysX 5, and new projects generated from the Project Manager will be restricted to this fixed version as well. This RFC is a proposal to split the PhysX gem into two distinct gems: one for PhysX 4, and one for PhysX 5.

What is the relevance of this feature?

PhysX 5 is a major release from NVIDIA and brings improvements for the physics simulations space. PhysX 5 is particularly important for the ROS gem and robotics simulation due to new features that it supports. For projects that were formerly based on PhysX 4, an extensive migration is necessary. Rather than forcing an update for all projects that were formerly using PhysX 4 to PhysX 5, O3DE supports both versions. However, rather than supporting both versions concurrently, the version is determined by the CMake variable AZ_USE_PHYSX5.

The problems of having a CMake variable determine the version of PhysX at project generation are:

• The variable AZ_USE_PHYSX5 couples the specifics of the particular gem to the engine. It also implies that O3DE only supports the PhysX gem as the physics engine, which defeats the intent of having the modular Gems system.
• The variable is also not a scalable solution, in case there are future versions of PhysX that will be supported.
• The version of PhysX is only known at project generation time. It is not mentioned anywhere else nor are there any apparent definitions that describe which version of PhysX the gem is using.
• Placing the restriction at project generation time for the engine means that the engine that is built for the SDK only supports either PhysX 4 or PhysX 5. This restriction is carried over to the pre-built SDK, thus requiring the need to build an SDK for PhysX 4 and PhysX 5 separately.
• The current O3DE SDK installers only support PhysX 4. The only way to support PhysX 5 is to build a separate SDK installer for PhysX 5, and for every platform. The problem is further magnified if newer major versions of PhysX is supported, which will require the need to build individual SDK installs for every version of PhysX.

Splitting the single PhysX gem into version specific ones will solve these issues:

• The AZ_USE_PHYSX5 variable is no longer needed since both a PhysX 4 and PhysX 5 gem will always be defined. Removing it decouples this flag to the PhysX gem.
• Both PhysX 4 and PhysX 5 gems will be available (Although only one can be enabled, details in the feature design description)
• Since both PhysX 4 and PhysX 5 gems are available, the choice of versions is no longer needed at engine or SDK installer build time.
• Separate versions of the SDK Installer for both versions are no longer necessary.

Feature design description:

Additional Gems

Currently, PhysX 5 is an opt-in flag. By default, PhysX 4 is the version of Phys X that the gem will use. Since the version is determined by this opt-in flag, the single PhysX gem will be built with either version but will not be reflected in the gem description. Not only is the PhysX gem affected by this, but also the PhysXDebug gem as well. When configuring the gems for the project, the PhysX and PhysXDebug gems are listed with their basic information, but not with any information regarding the version of PhysX they represent.

We will split the gem into a PhysX & PhysX5 gem (and PhysXDebug & PhysX5Debug respectively). For backwards compatibility, the PhysX for version 4 gem will not be renamed to PhysX4 since all of the existing SDK were built with version 4 being the default version. Instead, the PhysX version 4 gem will only be updated with the gem description, while the PhysX/PhysXDebug gem will be named PhysX5/PhysX5Debug along with the version information in its description.

Current Workflow

The current workflow to create a project that utilizes PhysX 4 or PhysX 5 requires that the Physx version decision to be made at the engine project generation time. The following describes the workflow based on a source build of the engine. For SDK builds, they currently only support PhysX 4, so those workflows will be omitted here.

1. Clone o3de from github.com

2. Register the o3de engine
   o3de.bat register --this-engine 

3. Create a new project from the O3DE CLI (see 'Creating Projects on Windows') using the DefaultProject Template.
   scripts\o3de.bat create-project --project-path %USERPROFILE%\O3DE\Projects\MyProject 

4. Go to the new project project folder
   cd %USERPROFILE%\O3DE\Projects\MyProject

5. Run the cmake generation from the project folder
   cmake -B build/windows 

The DefaultProject template will have the PhysX gem enabled. And since PhysX 4 is the default, there is no special flag that needs to be set at this point.

Source Build PhysX 5

The steps to build a new project with PhysX 5 is the same as the Source Build PhysX 4 steps, except for step #5 will add the AZ_USE_PHYSX5 flag

cmake -B build/windows -DAZ_ENABLE_PHYSX5=TRUE 

Installed SDK Builds

The workflow using the O3DE Project Manager from the installation of the O3DE SDKs only support PhysX 4. There is no support for PhysX 5 due to the fact that there are no PhysX 5 specific installers currently.

Switching PhysX versions

Switching the version of PhysX requires a rebuild of the project with the AZ_ENABLE_PHYSX5  argument reversed, and then the project / engine rebuilt.

Workflow Improvements

Splitting the PhysX gem will improve workflow such that the choice of which PhysX version to use for PhysX is not made at compile time for source builds. It also allows for the creation of a single installed SDK build will support more than just one version of PhysX at the same time.

Technical design description:

PhysX version 5 argument removal and 3rd Party Updates

The AZ_USE_PHYSX5 CMake variable will be removed. This will mean that the ly_associate_package calls for PhysX4 vs PhysX5 based on this argument will no longer be gated on this condition. Both 3rd Party PhysX4 and Physx5 packages will exist simultaneously. That means that instead of a single 3rdParty:PhysX package target, there will be two:

• 3rdParty::PhysX4
• 3rdParty::PhysX5

The individual PhysX4 and PhysX5 gems will depend on their corresponding 3rdParty package equivalent. This also means that the 3rd Party package's FindPhysX.cmake will be changed to FindPhysX4.cmake and FindPhysX5.cmake respectively. The location of the ly_associate_package call to bring in PhysX will be removed from the global BuiltinPackages_<platform>.cmake  file and into each split gem's platform specific PAL cmake file, depending on the version.

CMake Target Hierarchy

The relevant CMake target dependency hierarchy currently has the single PhysX Gem that links against NVIDIA PhysX4 or PhysX5 based only on the AZ_USE_PHYSX5 flag, so it gives no indication of which version is actually built after the variable is set.

Current PhysX Hierarchy

Splitting the gem will require that all of the previous PhysX targets that had any dependencies on the PhysX 3rd Party package will need to be separated into a PhysX and PhysX5  version each. (See the feature design description section for why we are not renaming to PhysX4). Only PhysX.NumericalMethods and PhysX.Mocks do not need to be split since they do not have any upstream dependency to the 3rd Party PhysX, and thus can be shared across both gems.

Proposed Hierarchy

Additional Details

• Each individual PhysX gem will be stored under its own sub folder under the current Gem/PhysX folder.
  • Gems/PhysX/PhysX4
  • Gems/PhysX/PhysX5
• Within each of the PhysX version specific gem folder, it will have:
  • CMakeLists.txt
    A copy of the CMakeLists.txt from the original PhysX gem, but with the renamed targets described above where applicable
  • gem.json
    A copy of the gem.json from the original PhysX gem, but with details specific to the version of PhysX that is being used
  • preview.png
    A copy of the preview image for PhysX from the original gem. This file can remain unchanged, pending UX signoff
• New PhysXCommon Gem
  • The PhysXCommon gem will be defined and placed in a new PhysX/Common folder. This gem will be a downstream dependency of each of the PhysX4/PhysX5 gem.
  • A new CMakeLists.txt will be created with the target definitions for PhysX.NumericalMethods  and PhysX.Mocks
  • The PhysX/Assets and PhysX/Registry folders will be moved under the new PhysX/Common folder.
  • The PhysXCommon gem will have its own gem.json and preview.png.
• The PhysXDebug gem will require a similar split of definitions since they have an upstream dependency to the specific PhysX gem.
• The Code folder will remain mostly intact
  • The CMake file lists that exist currently will remain intact. They will be referenced as needed by the new PhysX specific Targets from their corresponding folders.
  • The CMakeList.txt file in this folder is no longer needed and will be removed
• While both versions of the PhysX gems will be available, only one can be enabled at a time per project. This will require a mechanism to prevent certain classes of gems to be enabled simultaneously. This can be done by add a concept of a 'Unique Feature Type` to the gem definitions. The PhysX gems can be tagged with a unique feature tag of `PhysX` so that when enabling from either project manager or the command line, it will prevent both PhysX gems to be active on the same project.
• Even if only one 'unique feature type' can be enabled for a project at the same time, it does not prevent the other gem from being built individually. It is still possible to build individual gems specifically even if they are never loaded in the project. This presents a problem with 3rd party libraries for PhysX that get copied to the binary output folder for the project since they are named the same for both PhysX versions. This will need to be resolved by patching the 3rd party build script for PhysX 5 so that the output libraries will be named PhysX5*  instead of PhysX*  to prevent them overwritting each other.
• The Multiplayer  gem currently has dependency on the PhysX gem's static library. This will remain unchanged, expect for the addition of making the PhysX4 gem a dependency of this gem. For now, the multiplayer gem will only support PhysX 4. If the need to support PhysX 5 for this gem occurs in the future, the Multiplayer gem will need to perform a similar split.
• The ROS gem in the o3de-extras repo will need to be updated to depend on the PhysX 5 gem, since PhysX 5 is more suited for robotic simulations than PhysX 4.
• As with how the AZ_USE_PHYSX5 flag is implemented today, there should be no API changes necessary.

What are the advantages of the feature?

The advantages of splitting the PhysX gem are:

• Decouples the global AZ_USE_PHYSX5 flag from deciding how to build a specific Gem.
• Removes the need to make the decision of which version of PhysX to use at engine project generation time.
• Removes the need to make separate SDK installers if we want to have a PhysX5 compatible engine.

What are the disadvantages of the feature?

• Increases the size of the installer by including both Gems
• Increases the size of the 3rd party package binaries since both versions of PhysX 3rd Party will be downloaded
• Current and future gems that depend on PhysX will need to either decide which version the gem is compatible with, or do a split per version as well.

How will this be implemented or integrated into the O3DE environment?

The details of implementation are mostly described in the technical design description section. The updates will be made in the following repos

• https://github.com/o3de/o3de.git
• https://github.com/o3de/o3de-extras.git
• https://github.com/o3de/3p-package-source

The ROS2 gem will be updated to depend on PhysX 5.

The PhysX 3rd party packages for version 4 and 5 will be updated and rebuilt for all supported platforms to support the name change for FindPhysX.cmake  to FindPhysX<ver>.cmake  as well

Are there any alternatives to this feature?

• The PhysX5 gem can be placed outside of main o3de repo and into the o3de-extras repo. This will keep the existing PhysX gem definition intact, but the disadvantage of this approach is that there will be a duplicate code base for the gem. All the targets inside the original PhysX gem will also be duplicated in another repo, which presents a maintenance challenge.
• One of the reasons why the naming needs to be split for the gem and all of its dependent targets is that the build system identifies all of its gems through gem json files, but will evaluate every gem target and other targets in its definition regardless of whether or not it is enabled for a project. Enabling a gem dependency for a game project simply adds the gem as a build dependency, it doesn't necessarily exclude it from building. When you build the any of the project related targets (Editor, Asset Processor, Game Launcher, etc), it maps the enabled gem(s) to its build dependencies so that only they are built as needed. Because of this, the target name must be unique even if not all targets are enabled. We can reduce this some of this complexity by changing the build system to also exclude reading in the gem's target CMakeLists.txt file when it is not selected for a project, but instead only evaluate gem targets that are enabled. This will also allow us to use cmake aliases based on the selected version of PhysX so that any downstream dependencies will not have to create separate physX versions either. This however, will require a more fundamental change to the build system and may introduce more risk.

How will users learn this feature?

• For existing game developers, this will not impact their project since the PhysX4 gem will be mostly the same. 
• For new game developers, they will see both PhysX and PhysX5 gems in the available gems when configuring a new project
• For existing simulation developers, they will need to re-sync with the o3de-extras repo to get the dependency update for the ROS2 gem and rebuild their project.
• For new simulation developers, as with new game developers, they will see both PhysX and PhysX5 gems in the available gems when configuring a new project. However, when they select the ROS2 gem, they will see that only PhysX 5 is a required dependency, and will not be able to select PhysX 4.

Are there any open questions?

• Why not just support PhysX5 only?
  PhysX5 introduces a lot of features and improvements for physics simulations, and is not as optimized for gaming as the previous release was. Their press release even states that they are no longer supporting game console builds for PhysX 5.
• What are the specific versions of NVidia's PhysX libraries that the major version represent? For PhysX4, it is based on PhysX 4.1.2. For PhysX5, it is based on PhysX 5.1.1. Additional platform support for Android, Oos, and Mac are implemented in an O3DE fork of PhysX, based on version 5.1.1.

[adamdbrw]

Great work @spham-amzn! I believe this is very much needed.

[adamdbrw]

Great work! It would be very useful to clarify PhysX 5 fork situation, schedule for updating to upstream etc.

[nick-l-o3de]

Looks good to me - it may be possible to avoid downloading both 3rd party libraries, though (at least, on a per-user basis). This is because the 3rd Party system only actually fetches a library if a target being built actually depends on that library. So if the two 3rd party libraries are separate downloads (as in, .tar.xz files in the 3p system CDN) then only actually linking to the target in your project will cause it to fetch.

The installer would have to include both binaries though, but not the entirety of both 3p sdks.

[lgleim]

Technically, this looks like a very nice proposal to me and it has got my support. I am however wondering about the longer-term perspective of this proposal, since this will mean maintaining both PhysX4 and PhysX5 in parallel for the foreseeable future. Does this proposal come with such a commitment?

Deprecating support for Multiplayer with PhysX5 also appears like a significant regression. I would prefer to see all core Gems updated between major releases when moving forward.

Finally, which should be the default PhysX version for newly created projects in the future? Or will this vary by template?

[spham-amzn]

The decision to deprecate PhysX version 4 is not part of the scope of this RFC. This RFC is meant to fix the current situation of how we handle both major versions. I would agree that it would be better not to support dual major versions, but I think that will require an in-depth analysis of PhysX5 and the gaps that it has with PhysX4, and that would be require another RFC. And also, the default version of the PhysX gem will be dictated by the template that is used to create the project.

[spham-amzn]

This feature has been merged into o3de and o3de-extras