rapier3d/dynamics/joint/
spherical_joint.rs

1use crate::dynamics::integration_parameters::SpringCoefficients;
2use crate::dynamics::joint::{GenericJoint, GenericJointBuilder, JointAxesMask};
3use crate::dynamics::{JointAxis, JointMotor, MotorModel};
4use crate::math::{Isometry, Point, Real};
5
6use super::JointLimits;
7
8#[cfg(doc)]
9use crate::dynamics::RevoluteJoint;
10
11#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
12#[derive(Copy, Clone, Debug, PartialEq)]
13#[repr(transparent)]
14/// A ball-and-socket joint that allows free rotation but no translation (like a shoulder joint).
15///
16/// Spherical joints keep two bodies connected at a point but allow them to rotate freely
17/// around that point in all directions. Use for:
18/// - Shoulder/hip joints in ragdolls
19/// - Ball-and-socket mechanical connections
20/// - Wrecking ball chains
21/// - Camera gimbals
22///
23/// The bodies stay connected at their anchor points but can rotate relative to each other.
24///
25/// **Note**: Only available in 3D. In 2D, use [`RevoluteJoint`] instead (there's only one rotation axis in 2D).
26pub struct SphericalJoint {
27    /// The underlying joint data.
28    pub data: GenericJoint,
29}
30
31impl Default for SphericalJoint {
32    fn default() -> Self {
33        SphericalJoint::new()
34    }
35}
36
37impl SphericalJoint {
38    /// Creates a new spherical joint locking all relative translations between two bodies.
39    pub fn new() -> Self {
40        let data = GenericJointBuilder::new(JointAxesMask::LOCKED_SPHERICAL_AXES).build();
41        Self { data }
42    }
43
44    /// The underlying generic joint.
45    pub fn data(&self) -> &GenericJoint {
46        &self.data
47    }
48
49    /// Are contacts between the attached rigid-bodies enabled?
50    pub fn contacts_enabled(&self) -> bool {
51        self.data.contacts_enabled
52    }
53
54    /// Sets whether contacts between the attached rigid-bodies are enabled.
55    pub fn set_contacts_enabled(&mut self, enabled: bool) -> &mut Self {
56        self.data.set_contacts_enabled(enabled);
57        self
58    }
59
60    /// The joint’s anchor, expressed in the local-space of the first rigid-body.
61    #[must_use]
62    pub fn local_anchor1(&self) -> Point<Real> {
63        self.data.local_anchor1()
64    }
65
66    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
67    pub fn set_local_anchor1(&mut self, anchor1: Point<Real>) -> &mut Self {
68        self.data.set_local_anchor1(anchor1);
69        self
70    }
71
72    /// The joint’s anchor, expressed in the local-space of the second rigid-body.
73    #[must_use]
74    pub fn local_anchor2(&self) -> Point<Real> {
75        self.data.local_anchor2()
76    }
77
78    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
79    pub fn set_local_anchor2(&mut self, anchor2: Point<Real>) -> &mut Self {
80        self.data.set_local_anchor2(anchor2);
81        self
82    }
83
84    /// Gets both the joint anchor and the joint’s reference orientation relative to the first
85    /// rigid-body’s local-space.
86    #[must_use]
87    pub fn local_frame1(&self) -> &Isometry<Real> {
88        &self.data.local_frame1
89    }
90
91    /// Sets both the joint anchor and the joint’s reference orientation relative to the first
92    /// rigid-body’s local-space.
93    pub fn set_local_frame1(&mut self, local_frame: Isometry<Real>) -> &mut Self {
94        self.data.set_local_frame1(local_frame);
95        self
96    }
97
98    /// Gets both the joint anchor and the joint’s reference orientation relative to the second
99    /// rigid-body’s local-space.
100    #[must_use]
101    pub fn local_frame2(&self) -> &Isometry<Real> {
102        &self.data.local_frame2
103    }
104
105    /// Sets both the joint anchor and the joint’s reference orientation relative to the second
106    /// rigid-body’s local-space.
107    pub fn set_local_frame2(&mut self, local_frame: Isometry<Real>) -> &mut Self {
108        self.data.set_local_frame2(local_frame);
109        self
110    }
111
112    /// The motor for a specific rotation axis of this spherical joint.
113    ///
114    /// Spherical joints can have motors on each of their 3 rotation axes (X, Y, Z).
115    /// Returns `None` if no motor is configured for that axis.
116    #[must_use]
117    pub fn motor(&self, axis: JointAxis) -> Option<&JointMotor> {
118        self.data.motor(axis)
119    }
120
121    /// Sets the motor model for a specific rotation axis.
122    ///
123    /// Choose between force-based or acceleration-based motor behavior.
124    pub fn set_motor_model(&mut self, axis: JointAxis, model: MotorModel) -> &mut Self {
125        self.data.set_motor_model(axis, model);
126        self
127    }
128
129    /// Sets target rotation speed for a specific axis.
130    ///
131    /// # Parameters
132    /// * `axis` - Which rotation axis (AngX, AngY, or AngZ)
133    /// * `target_vel` - Desired angular velocity in radians/second
134    /// * `factor` - Motor strength
135    pub fn set_motor_velocity(
136        &mut self,
137        axis: JointAxis,
138        target_vel: Real,
139        factor: Real,
140    ) -> &mut Self {
141        self.data.set_motor_velocity(axis, target_vel, factor);
142        self
143    }
144
145    /// Sets target angle for a specific rotation axis.
146    ///
147    /// # Parameters
148    /// * `axis` - Which rotation axis (AngX, AngY, or AngZ)
149    /// * `target_pos` - Desired angle in radians
150    /// * `stiffness` - Spring constant
151    /// * `damping` - Resistance
152    pub fn set_motor_position(
153        &mut self,
154        axis: JointAxis,
155        target_pos: Real,
156        stiffness: Real,
157        damping: Real,
158    ) -> &mut Self {
159        self.data
160            .set_motor_position(axis, target_pos, stiffness, damping);
161        self
162    }
163
164    /// Configure both the target angle and target velocity of the motor.
165    pub fn set_motor(
166        &mut self,
167        axis: JointAxis,
168        target_pos: Real,
169        target_vel: Real,
170        stiffness: Real,
171        damping: Real,
172    ) -> &mut Self {
173        self.data
174            .set_motor(axis, target_pos, target_vel, stiffness, damping);
175        self
176    }
177
178    /// Sets the maximum force the motor can deliver along the specified axis.
179    pub fn set_motor_max_force(&mut self, axis: JointAxis, max_force: Real) -> &mut Self {
180        self.data.set_motor_max_force(axis, max_force);
181        self
182    }
183
184    /// The limit distance attached bodies can translate along the specified axis.
185    #[must_use]
186    pub fn limits(&self, axis: JointAxis) -> Option<&JointLimits<Real>> {
187        self.data.limits(axis)
188    }
189
190    /// Sets the `[min,max]` limit angles attached bodies can translate along the joint’s principal
191    /// axis.
192    pub fn set_limits(&mut self, axis: JointAxis, limits: [Real; 2]) -> &mut Self {
193        self.data.set_limits(axis, limits);
194        self
195    }
196
197    /// Gets the softness of this joint’s locked degrees of freedom.
198    #[must_use]
199    pub fn softness(&self) -> SpringCoefficients<Real> {
200        self.data.softness
201    }
202
203    /// Sets the softness of this joint’s locked degrees of freedom.
204    #[must_use]
205    pub fn set_softness(&mut self, softness: SpringCoefficients<Real>) -> &mut Self {
206        self.data.softness = softness;
207        self
208    }
209}
210
211impl From<SphericalJoint> for GenericJoint {
212    fn from(val: SphericalJoint) -> GenericJoint {
213        val.data
214    }
215}
216
217/// Create spherical joints using the builder pattern.
218#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
219#[derive(Copy, Clone, Debug, Default, PartialEq)]
220pub struct SphericalJointBuilder(pub SphericalJoint);
221
222impl SphericalJointBuilder {
223    /// Creates a new builder for spherical joints.
224    pub fn new() -> Self {
225        Self(SphericalJoint::new())
226    }
227
228    /// Sets whether contacts between the attached rigid-bodies are enabled.
229    #[must_use]
230    pub fn contacts_enabled(mut self, enabled: bool) -> Self {
231        self.0.set_contacts_enabled(enabled);
232        self
233    }
234
235    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
236    #[must_use]
237    pub fn local_anchor1(mut self, anchor1: Point<Real>) -> Self {
238        self.0.set_local_anchor1(anchor1);
239        self
240    }
241
242    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
243    #[must_use]
244    pub fn local_anchor2(mut self, anchor2: Point<Real>) -> Self {
245        self.0.set_local_anchor2(anchor2);
246        self
247    }
248
249    /// Sets both the joint anchor and the joint’s reference orientation relative to the first
250    /// rigid-body’s local-space.
251    #[must_use]
252    pub fn local_frame1(mut self, frame1: Isometry<Real>) -> Self {
253        self.0.set_local_frame1(frame1);
254        self
255    }
256
257    /// Sets both the joint anchor and the joint’s reference orientation relative to the second
258    /// rigid-body’s local-space.
259    #[must_use]
260    pub fn local_frame2(mut self, frame2: Isometry<Real>) -> Self {
261        self.0.set_local_frame2(frame2);
262        self
263    }
264
265    /// Set the spring-like model used by the motor to reach the desired target velocity and position.
266    #[must_use]
267    pub fn motor_model(mut self, axis: JointAxis, model: MotorModel) -> Self {
268        self.0.set_motor_model(axis, model);
269        self
270    }
271
272    /// Sets the target velocity this motor needs to reach.
273    #[must_use]
274    pub fn motor_velocity(mut self, axis: JointAxis, target_vel: Real, factor: Real) -> Self {
275        self.0.set_motor_velocity(axis, target_vel, factor);
276        self
277    }
278
279    /// Sets the target angle this motor needs to reach.
280    #[must_use]
281    pub fn motor_position(
282        mut self,
283        axis: JointAxis,
284        target_pos: Real,
285        stiffness: Real,
286        damping: Real,
287    ) -> Self {
288        self.0
289            .set_motor_position(axis, target_pos, stiffness, damping);
290        self
291    }
292
293    /// Configure both the target angle and target velocity of the motor.
294    #[must_use]
295    pub fn motor(
296        mut self,
297        axis: JointAxis,
298        target_pos: Real,
299        target_vel: Real,
300        stiffness: Real,
301        damping: Real,
302    ) -> Self {
303        self.0
304            .set_motor(axis, target_pos, target_vel, stiffness, damping);
305        self
306    }
307
308    /// Sets the maximum force the motor can deliver along the specified axis.
309    #[must_use]
310    pub fn motor_max_force(mut self, axis: JointAxis, max_force: Real) -> Self {
311        self.0.set_motor_max_force(axis, max_force);
312        self
313    }
314
315    /// Sets the `[min,max]` limit distances attached bodies can rotate along the specified axis.
316    #[must_use]
317    pub fn limits(mut self, axis: JointAxis, limits: [Real; 2]) -> Self {
318        self.0.set_limits(axis, limits);
319        self
320    }
321
322    /// Sets the softness of this joint’s locked degrees of freedom.
323    #[must_use]
324    pub fn softness(mut self, softness: SpringCoefficients<Real>) -> Self {
325        self.0.data.softness = softness;
326        self
327    }
328
329    /// Builds the spherical joint.
330    #[must_use]
331    pub fn build(self) -> SphericalJoint {
332        self.0
333    }
334}
335
336impl From<SphericalJointBuilder> for GenericJoint {
337    fn from(val: SphericalJointBuilder) -> GenericJoint {
338        val.0.into()
339    }
340}
rapier3d/dynamics/joint/spherical_joint.rs

rapier3d/dynamics/joint/
spherical_joint.rs
