{"record":{"id":"9239d7910edaf825","repo":"BabylonJS/Babylon.js","slug":"unsupported-physics-plugin-version","errorCode":null,"errorMessage":"Unsupported Physics plugin version.","messagePattern":"Unsupported Physics plugin version\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Physics/joinedPhysicsEngineComponent.pure.ts","lineNumber":119,"sourceCode":"    Scene.prototype.enablePhysics = function (gravity: Nullable<Vector3> = null, plugin?: IPhysicsEnginePluginV1 | IPhysicsEnginePluginV2): boolean {\r\n        if (this._physicsEngine) {\r\n            return true;\r\n        }\r\n\r\n        // Register the component to the scene\r\n        let component = this._getComponent(SceneComponentConstants.NAME_PHYSICSENGINE) as PhysicsEngineSceneComponent;\r\n        if (!component) {\r\n            component = new PhysicsEngineSceneComponent(this);\r\n            this._addComponent(component);\r\n        }\r\n\r\n        try {\r\n            if (!plugin || plugin?.getPluginVersion() === 1) {\r\n                this._physicsEngine = new PhysicsEngineV1(gravity, plugin as IPhysicsEnginePluginV1);\r\n            } else if (plugin?.getPluginVersion() === 2) {\r\n                this._physicsEngine = new PhysicsEngineV2(gravity, plugin as IPhysicsEnginePluginV2);\r\n            } else {\r\n                throw new Error(\"Unsupported Physics plugin version.\");\r\n            }\r\n            this._physicsTimeAccumulator = 0;\r\n            return true;\r\n        } catch (e) {\r\n            Logger.Error(e.message);\r\n            return false;\r\n        }\r\n    };\r\n\r\n    /**\r\n     * Disables and disposes the physics engine associated with the scene\r\n     */\r\n    Scene.prototype.disablePhysicsEngine = function (): void {\r\n        if (!this._physicsEngine) {\r\n            return;\r\n        }\r\n\r\n        this._physicsEngine.dispose();\r","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Physics/joinedPhysicsEngineComponent.pure.ts#L101-L137","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check plugin.getPluginVersion() and use a plugin version matching your Babylon.js version (V1 or V2 API).","Upgrade or downgrade the physics plugin package so its version is 1 or 2.","Update Babylon.js to a version that supports your plugin's version number."],"exampleFix":"// before: custom plugin returning version 3\ngetPluginVersion() { return 3; }\n// after: implement the V2 plugin API\ngetPluginVersion() { return 2; }","handlingStrategy":"validation","validationCode":"const version = plugin?.getPluginVersion?.();\nif (version !== 1 && version !== 2) {\n  throw new Error(`Physics plugin version ${version} unsupported; need 1 or 2`);\n}","typeGuard":"function isSupportedPlugin(p: any): p is IPhysicsEnginePluginV1 | IPhysicsEnginePluginV2 {\n  return p?.getPluginVersion?.() === 1 || p?.getPluginVersion?.() === 2;\n}","tryCatchPattern":"const ok = scene.enablePhysics(gravity, plugin); // returns false instead of throwing\nif (!ok) console.error(Logger.errors); // plugin logged the underlying issue","preventionTips":["Match physics plugin major version to your Babylon.js version.","Check plugin.getPluginVersion() after upgrading either library.","Keep plugin and Babylon versions listed together in package.json."],"tags":["physics","plugin-version","compatibility"],"backgroundTag":"incompatible-plugin-version","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}