BabylonJS/Babylon.js · error

Unsupported Physics plugin version.

Error message

Unsupported Physics plugin version.

What it means

RegisterJoinedPhysicsEngineComponent creates the appropriate physics engine wrapper based on the plugin's reported version: 1 uses PhysicsEngineV1, 2 uses PhysicsEngineV2. Any other value — including a missing plugin or a plugin returning an unrecognized version — is rejected with this error (then caught, logged, and reported as failure).

Source

Thrown at packages/dev/core/src/Physics/joinedPhysicsEngineComponent.pure.ts:119

    Scene.prototype.enablePhysics = function (gravity: Nullable<Vector3> = null, plugin?: IPhysicsEnginePluginV1 | IPhysicsEnginePluginV2): boolean {
        if (this._physicsEngine) {
            return true;
        }

        // Register the component to the scene
        let component = this._getComponent(SceneComponentConstants.NAME_PHYSICSENGINE) as PhysicsEngineSceneComponent;
        if (!component) {
            component = new PhysicsEngineSceneComponent(this);
            this._addComponent(component);
        }

        try {
            if (!plugin || plugin?.getPluginVersion() === 1) {
                this._physicsEngine = new PhysicsEngineV1(gravity, plugin as IPhysicsEnginePluginV1);
            } else if (plugin?.getPluginVersion() === 2) {
                this._physicsEngine = new PhysicsEngineV2(gravity, plugin as IPhysicsEnginePluginV2);
            } else {
                throw new Error("Unsupported Physics plugin version.");
            }
            this._physicsTimeAccumulator = 0;
            return true;
        } catch (e) {
            Logger.Error(e.message);
            return false;
        }
    };

    /**
     * Disables and disposes the physics engine associated with the scene
     */
    Scene.prototype.disablePhysicsEngine = function (): void {
        if (!this._physicsEngine) {
            return;
        }

        this._physicsEngine.dispose();

View on GitHub (pinned to 0592b347b8)

Solutions

1. Check plugin.getPluginVersion() and use a plugin version matching your Babylon.js version (V1 or V2 API).
2. Upgrade or downgrade the physics plugin package so its version is 1 or 2.
3. Update Babylon.js to a version that supports your plugin's version number.

Example fix

// before: custom plugin returning version 3
getPluginVersion() { return 3; }
// after: implement the V2 plugin API
getPluginVersion() { return 2; }

const version = plugin?.getPluginVersion?.();
if (version !== 1 && version !== 2) {
  throw new Error(`Physics plugin version ${version} unsupported; need 1 or 2`);
}

function isSupportedPlugin(p: any): p is IPhysicsEnginePluginV1 | IPhysicsEnginePluginV2 {
  return p?.getPluginVersion?.() === 1 || p?.getPluginVersion?.() === 2;
}

const ok = scene.enablePhysics(gravity, plugin); // returns false instead of throwing
if (!ok) console.error(Logger.errors); // plugin logged the underlying issue

When it happens

Trigger: Enabling the joined physics engine component with a plugin whose getPluginVersion() returns something other than 1 or 2, or passing no plugin at all (plugin falsy takes the V1 path, so this mainly fires for plugin.getPluginVersion() >= 3, 0, NaN, or non-numeric).

Common situations: Third-party/in-house physics plugins built against a newer or older API than the installed Babylon.js supports; mixing plugin versions with Babylon versions after a major upgrade; forgetting to install a physics plugin package so a stub returns an unexpected version.

Related errors

• Plugin version is incorrect. Expected version 2.
• Physics Engine ${this._physicsPlugin.name} cannot be found.
• Unknown motion type: ${type}
• No mesh provided to create physics shape.
• Missing required heightfield parameters

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/9239d7910edaf825. Report an issue: GitHub.