stride3d/stride · error · Exception

Cannot perform this action when the physics engine is set…

Error message

Cannot perform this action when the physics engine is set to CollisionsOnly

What it means

AddRigidBody registers a rigid body with the discrete dynamics world, which only exists when the Simulation is created in full-simulation mode. When the physics engine is configured as CollisionsOnly, discreteDynamicsWorld is null because no dynamics simulation runs, so adding a rigid body is unsupported and throws.

Solutions

Change the physics simulation mode away from CollisionsOnly (remove the CollisionsOnly flag in the physics settings / Simulation creation) so dynamic bodies are supported.
If CollisionsOnly is required, replace RigidbodyComponent usage with static colliders or trigger-only components.
Guard rigid-body registration code with a check that the simulation supports dynamics before calling AddRigidBody.

Example fix

// before
simulation.AddRigidBody(rigidBody, CollisionFilterGroupFlags.DefaultFilter, CollisionFilterGroupFlags.DefaultFilter);
// after
if (simulation.DiscreteDynamicsWorld != null)
    simulation.AddRigidBody(rigidBody, CollisionFilterGroupFlags.DefaultFilter, CollisionFilterGroupFlags.DefaultFilter);
else
    throw new NotSupportedException("Dynamic bodies require a full physics simulation, not CollisionsOnly");

Defensive patterns

Strategy: validation

Validate before calling

bool supportsDynamics = simulation.DiscreteDynamicsWorld != null; // check before AddRigidBody

Type guard

bool IsFullSimulation(Simulation s) => s?.DiscreteDynamicsWorld != null;

Try / catch

try { simulation.AddRigidBody(rb, g, m); } catch (Exception ex) when (ex.Message.Contains("CollisionsOnly")) { /* fall back to collider-only setup */ }

Prevention

Verify physics settings mode matches the components your scene uses.
Audit scenes for rigid bodies before enabling CollisionsOnly.
Centralize physics registration behind a helper that checks capability once.

When it happens

Trigger: Calling simulation.AddRigidBody(rigidBody, group, mask) (directly or via adding a RigidbodyComponent to a scene) while the Simulation was created with CollisionsOnly flag.

Common situations: Project configured with physics CollisionsOnly for raycast/trigger-only gameplay, then a dynamic rigid body or character is added at runtime; copying physics setup code between projects with different simulation modes.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/27373f91a0a7802c. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Physics/Simulation.cs:576

                processor.RenderColliderShapes(value);
            }
        }

        public RenderGroup ColliderShapesRenderGroup { get; set; } = RenderGroup.Group0;

        internal void AddCollider(PhysicsComponent component, CollisionFilterGroupFlags group, CollisionFilterGroupFlags mask)
        {
            collisionWorld.AddCollisionObject(component.NativeCollisionObject, (BulletSharp.CollisionFilterGroups)group, (BulletSharp.CollisionFilterGroups)mask);
        }

        internal void RemoveCollider(PhysicsComponent component)
        {
            collisionWorld.RemoveCollisionObject(component.NativeCollisionObject);
        }

        internal void AddRigidBody(RigidbodyComponent rigidBody, CollisionFilterGroupFlags group, CollisionFilterGroupFlags mask)
        {
            if (discreteDynamicsWorld == null) throw new Exception("Cannot perform this action when the physics engine is set to CollisionsOnly");

            discreteDynamicsWorld.AddRigidBody(rigidBody.InternalRigidBody, (short)group, (short)mask);
        }

        internal void RemoveRigidBody(RigidbodyComponent rigidBody)
        {
            if (discreteDynamicsWorld == null) throw new Exception("Cannot perform this action when the physics engine is set to CollisionsOnly");

            discreteDynamicsWorld.RemoveRigidBody(rigidBody.InternalRigidBody);
        }

        internal void AddCharacter(CharacterComponent character, CollisionFilterGroupFlags group, CollisionFilterGroupFlags mask)
        {
            if (discreteDynamicsWorld == null) throw new Exception("Cannot perform this action when the physics engine is set to CollisionsOnly");

            var collider = character.NativeCollisionObject;
            var action = character.KinematicCharacter;
            discreteDynamicsWorld.AddCollisionObject(collider, (BulletSharp.CollisionFilterGroups)group, (BulletSharp.CollisionFilterGroups)mask);

View on GitHub (pinned to 96fad776d2)