{"record":{"id":"2e50f8745805472a","repo":"stride3d/stride","slug":"a-gear-constraint-requires-two-rigidbodies","errorCode":null,"errorMessage":"A Gear constraint requires two rigidbodies.","messagePattern":"A Gear constraint requires two rigidbodies\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Physics/Constraints/GearConstraintDesc.cs","lineNumber":57,"sourceCode":"        /// <userdoc>\n        /// Axis on which the gear will rotate relative to body B.\n        /// </userdoc>\n        [Display(1)]\n        public Quaternion AxisInB { get; set; } = Quaternion.Identity;\n\n        /// <summary>\n        /// Size ratio between the gears (rotating a bigger gear will rotate smaller gear quicker).\n        /// </summary>\n        /// <userdoc>\n        /// Size ratio between the gears (rotating a bigger gear will rotate smaller gear quicker).\n        /// </userdoc>\n        [Display(2)]\n        public float Ratio { get; set; } = 1;\n\n        /// <inheritdoc/>\n        public Constraint Build(RigidbodyComponent bodyA, RigidbodyComponent bodyB)\n        {\n            if (bodyB == null) throw new System.InvalidOperationException(\"A Gear constraint requires two rigidbodies.\");\n\n            var axis = Vector3.UnitX;\n            AxisInA.Rotate(ref axis);\n            var frameA = Matrix.Translation(axis);\n\n            axis = Vector3.UnitX;\n            AxisInB.Rotate(ref axis);\n            var frameB = Matrix.Translation(axis);\n\n            var gear = Simulation.CreateConstraint(ConstraintTypes.Gear, bodyA, bodyB, frameA, frameB) as GearConstraint;\n\n            gear.Ratio = Ratio;\n\n            return gear;\n        }\n    }\n}\n","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Physics/Constraints/GearConstraintDesc.cs#L39-L75","documentation":"GearConstraintDesc.Build() builds a Bullet gear constraint, which by definition couples two rigidbodies via an axis and ratio. If bodyB is null it throws InvalidOperationException because a gear constraint cannot exist with a single body.","triggerScenarios":"Assigning a GearConstraintDesc to a RigidbodyComponent's Constraints without assigning a second Body (BodyB), or leaving the constraint's second body unassigned at build time.","commonSituations":"Configuring constraints in the editor/scene where only one body is wired up; copying constraint configs where the paired body reference was lost; dynamic spawning where bodyB is set later than Build.","solutions":["Assign a valid second RigidbodyComponent as BodyB on the constraint before the simulation starts","Verify the constraint's second body reference is not null after scene load","If you only have one body, use a different constraint type (e.g. a joint) instead of Gear"],"exampleFix":"// before\nrigidbody.Constraints.Add(new GearConstraintDesc { Ratio = 2f });\n// after\nvar gear = new GearConstraintDesc { Ratio = 2f, Body = otherRigidbody };\nrigidbody.Constraints.Add(gear); // Body (second rigidbody) must be set","handlingStrategy":"validation","validationCode":"if (desc.Body == null) throw new ArgumentException(\"Gear constraint requires a second rigidbody (Body).\");","typeGuard":null,"tryCatchPattern":"try { constraint.Build(bodyA, bodyB); }\ncatch (InvalidOperationException) { /* bodyB missing; fix config */ }","preventionTips":["Always assign both rigidbodies when using GearConstraintDesc","Validate constraint configs at scene load","Use editor references, not late runtime assignment, for paired bodies"],"tags":["physics","constraints","csharp"],"backgroundTag":"null-argument","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}