[3.3.2] PxActorFlag::eDISABLE_SIMULATION needs explanation in docs

Gaming and Visualization Technologies APIs Physics Modeling (closed)
1

As stated, enabling eDISABLE_SIMULATION puts the actor to sleep and any subsequent calls to PxRigidDynamic::putToSleep and PxRigidDynamic::wakeUp are invalid. Namely, most of the functions affected by this flag are already marked as invalid or contains information in the current PhysX documentation.

However, PxRigidActor::setGlobalPos doesn’t have any information or warning in the documents, although it is also affected by this flag. (Docs link for PxRigidActor::setGlobalPos) For example, following simple code causes assertion error:

PxScene *scene;

// create new scene...

PxRigidDynamic *actor = physx->createRigidDynamic(PxTransform(PxIDENTITY()));
actor->setActorFlag(PxActorFlag::eDISABLE_SIMULATION, true);

scene->addActor(*actor);

actor->setGlobalPos(PxTransform(PxVec3(3, 2, 1)) /*, true*/);

// assertion fails:
// !(body.getActorFlags() & PxActorFlag::eDISABLE_SIMULATION) || 
// body.isSleeping()
scene->removeActor(*actor);

The assertion fails because of default wakeup argument of setGlobalPos. Even though wakeup should be invalid or ignored, it wakes the actor up (at least changes its internal state). This results in a failed assertion in PxScene::removeActor.

Using following lines might be the workaround for this issue:

actor->setGlobalPos(PxTransform(PxVec3(3, 2, 1)), !(actor->getActorFlags() & PxActorFlag::eDISABLE_SIMULATION));
// OR if you're sure that your actor's simulation is disabled
actor->setGlobalPos(PxTransform(PxVec3(3, 2, 1)), false);

However, in any case, there should be a warning or explanation in the document about this conflict.
(Docs link for PxRigidActor::setGlobalPos)