bevy_rapier3d/dynamics/
rope_joint.rs

1use crate::dynamics::{GenericJoint, GenericJointBuilder};
2use crate::math::{Real, Vect};
3use rapier::dynamics::{JointAxesMask, JointAxis, JointLimits, JointMotor, MotorModel};
4
5use super::{SpringCoefficients, TypedJoint};
6
7#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
8#[derive(Copy, Clone, Debug, PartialEq)]
9#[repr(transparent)]
10/// A rope joint, limits the maximum distance between two bodies
11pub struct RopeJoint {
12    /// The underlying joint data.
13    pub data: GenericJoint,
14}
15
16impl RopeJoint {
17    /// Creates a new rope joint limiting the max distance between to bodies
18    pub fn new(max_dist: Real) -> Self {
19        let data = GenericJointBuilder::new(JointAxesMask::empty())
20            .coupled_axes(JointAxesMask::LIN_AXES)
21            .build();
22        let mut result = Self { data };
23        result.set_max_distance(max_dist);
24        result
25    }
26
27    /// Are contacts between the attached rigid-bodies enabled?
28    pub fn contacts_enabled(&self) -> bool {
29        self.data.contacts_enabled()
30    }
31
32    /// Sets whether contacts between the attached rigid-bodies are enabled.
33    pub fn set_contacts_enabled(&mut self, enabled: bool) -> &mut Self {
34        self.data.set_contacts_enabled(enabled);
35        self
36    }
37
38    /// The spring coefficients controlling the softness of this joint’s locked degrees of freedom.
39    #[must_use]
40    pub fn softness(&self) -> SpringCoefficients<Real> {
41        self.data.softness()
42    }
43
44    /// Sets the spring coefficients controlling the softness of this joint’s locked degrees of freedom.
45    pub fn set_softness(&mut self, softness: SpringCoefficients<Real>) -> &mut Self {
46        self.data.set_softness(softness);
47        self
48    }
49
50    /// The joint’s anchor, expressed in the local-space of the first rigid-body.
51    #[must_use]
52    pub fn local_anchor1(&self) -> Vect {
53        self.data.local_anchor1()
54    }
55
56    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
57    pub fn set_local_anchor1(&mut self, anchor1: Vect) -> &mut Self {
58        self.data.set_local_anchor1(anchor1);
59        self
60    }
61
62    /// The joint’s anchor, expressed in the local-space of the second rigid-body.
63    #[must_use]
64    pub fn local_anchor2(&self) -> Vect {
65        self.data.local_anchor2()
66    }
67
68    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
69    pub fn set_local_anchor2(&mut self, anchor2: Vect) -> &mut Self {
70        self.data.set_local_anchor2(anchor2);
71        self
72    }
73
74    /// The principal axis of the joint, expressed in the local-space of the first rigid-body.
75    #[must_use]
76    pub fn local_axis1(&self) -> Vect {
77        self.data.local_axis1()
78    }
79
80    /// Sets the principal axis of the joint, expressed in the local-space of the first rigid-body.
81    pub fn set_local_axis1(&mut self, axis1: Vect) -> &mut Self {
82        self.data.set_local_axis1(axis1);
83        self
84    }
85
86    /// The principal axis of the joint, expressed in the local-space of the second rigid-body.
87    #[must_use]
88    pub fn local_axis2(&self) -> Vect {
89        self.data.local_axis2()
90    }
91
92    /// Sets the principal axis of the joint, expressed in the local-space of the second rigid-body.
93    pub fn set_local_axis2(&mut self, axis2: Vect) -> &mut Self {
94        self.data.set_local_axis2(axis2);
95        self
96    }
97
98    /// The motor affecting the joint’s translational degree of freedom.
99    #[must_use]
100    pub fn motor(&self, axis: JointAxis) -> Option<&JointMotor> {
101        self.data.motor(axis)
102    }
103
104    /// Set the spring-like model used by the motor to reach the desired target velocity and position.
105    pub fn set_motor_model(&mut self, model: MotorModel) -> &mut Self {
106        self.data.set_motor_model(JointAxis::LinX, model);
107        self
108    }
109
110    /// Sets the target velocity this motor needs to reach.
111    pub fn set_motor_velocity(&mut self, target_vel: Real, factor: Real) -> &mut Self {
112        self.data
113            .set_motor_velocity(JointAxis::LinX, target_vel, factor);
114        self
115    }
116
117    /// Sets the target angle this motor needs to reach.
118    pub fn set_motor_position(
119        &mut self,
120        target_pos: Real,
121        stiffness: Real,
122        damping: Real,
123    ) -> &mut Self {
124        self.data
125            .set_motor_position(JointAxis::LinX, target_pos, stiffness, damping);
126        self
127    }
128
129    /// Configure both the target angle and target velocity of the motor.
130    pub fn set_motor(
131        &mut self,
132        target_pos: Real,
133        target_vel: Real,
134        stiffness: Real,
135        damping: Real,
136    ) -> &mut Self {
137        self.data
138            .set_motor(JointAxis::LinX, target_pos, target_vel, stiffness, damping);
139        self
140    }
141
142    /// Sets the maximum force the motor can deliver.
143    pub fn set_motor_max_force(&mut self, max_force: Real) -> &mut Self {
144        self.data.set_motor_max_force(JointAxis::LinX, max_force);
145        self
146    }
147
148    /// The limit distance attached bodies can translate along the joint’s principal axis.
149    #[must_use]
150    pub fn limits(&self, axis: JointAxis) -> Option<&JointLimits<Real>> {
151        self.data.limits(axis)
152    }
153
154    /// Sets the maximum allowed distance between the attached bodies.
155    ///
156    /// The `max_dist` must be strictly greater than 0.0.
157    pub fn set_max_distance(&mut self, max_dist: Real) -> &mut Self {
158        self.data.set_limits(JointAxis::LinX, [0.0, max_dist]);
159        self
160    }
161
162    /// The maximum distance between the attached bodies.
163    pub fn max_distance(&self) -> Real {
164        self.data
165            .limits(JointAxis::LinX)
166            .map(|l| l.max)
167            .unwrap_or(Real::MAX)
168    }
169}
170
171impl From<RopeJoint> for GenericJoint {
172    fn from(joint: RopeJoint) -> GenericJoint {
173        joint.data
174    }
175}
176
177/// Create rope joints using the builder pattern.
178///
179/// A rope joint, limits the maximum distance between two bodies.
180#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
181#[derive(Copy, Clone, Debug, PartialEq)]
182pub struct RopeJointBuilder(RopeJoint);
183
184impl RopeJointBuilder {
185    /// Creates a new builder for rope joints.
186    pub fn new(max_dist: Real) -> Self {
187        Self(RopeJoint::new(max_dist))
188    }
189
190    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
191    #[must_use]
192    pub fn local_anchor1(mut self, anchor1: Vect) -> Self {
193        self.0.set_local_anchor1(anchor1);
194        self
195    }
196
197    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
198    #[must_use]
199    pub fn local_anchor2(mut self, anchor2: Vect) -> Self {
200        self.0.set_local_anchor2(anchor2);
201        self
202    }
203
204    /// Sets the principal axis of the joint, expressed in the local-space of the first rigid-body.
205    #[must_use]
206    pub fn local_axis1(mut self, axis1: Vect) -> Self {
207        self.0.set_local_axis1(axis1);
208        self
209    }
210
211    /// Sets the principal axis of the joint, expressed in the local-space of the second rigid-body.
212    #[must_use]
213    pub fn local_axis2(mut self, axis2: Vect) -> Self {
214        self.0.set_local_axis2(axis2);
215        self
216    }
217
218    /// Set the spring-like model used by the motor to reach the desired target velocity and position.
219    #[must_use]
220    pub fn motor_model(mut self, model: MotorModel) -> Self {
221        self.0.set_motor_model(model);
222        self
223    }
224
225    /// Sets the target velocity this motor needs to reach.
226    #[must_use]
227    pub fn motor_velocity(mut self, target_vel: Real, factor: Real) -> Self {
228        self.0.set_motor_velocity(target_vel, factor);
229        self
230    }
231
232    /// Sets the target angle this motor needs to reach.
233    #[must_use]
234    pub fn motor_position(mut self, target_pos: Real, stiffness: Real, damping: Real) -> Self {
235        self.0.set_motor_position(target_pos, stiffness, damping);
236        self
237    }
238
239    /// Configure both the target angle and target velocity of the motor.
240    #[must_use]
241    pub fn set_motor(
242        mut self,
243        target_pos: Real,
244        target_vel: Real,
245        stiffness: Real,
246        damping: Real,
247    ) -> Self {
248        self.0.set_motor(target_pos, target_vel, stiffness, damping);
249        self
250    }
251
252    /// Sets the maximum force the motor can deliver.
253    #[must_use]
254    pub fn motor_max_force(mut self, max_force: Real) -> Self {
255        self.0.set_motor_max_force(max_force);
256        self
257    }
258
259    /// Sets the maximum allowed distance between the attached bodies.
260    ///
261    /// The `max_dist` must be strictly greater than 0.0.    
262    #[must_use]
263    pub fn max_distance(mut self, max_dist: Real) -> Self {
264        self.0.set_max_distance(max_dist);
265        self
266    }
267
268    /// Sets whether contacts between the attached rigid-bodies are enabled.
269    #[must_use]
270    pub fn contacts_enabled(mut self, enabled: bool) -> Self {
271        self.0.set_contacts_enabled(enabled);
272        self
273    }
274
275    /// Sets the spring coefficients controlling the softness of this joint’s locked degrees of freedom.
276    #[must_use]
277    pub fn softness(mut self, softness: SpringCoefficients<Real>) -> Self {
278        self.0.set_softness(softness);
279        self
280    }
281
282    /// Builds the rope joint.
283    #[must_use]
284    pub fn build(self) -> RopeJoint {
285        self.0
286    }
287}
288
289impl From<RopeJointBuilder> for TypedJoint {
290    fn from(joint: RopeJointBuilder) -> TypedJoint {
291        joint.0.into()
292    }
293}
294
295impl From<RopeJoint> for TypedJoint {
296    fn from(joint: RopeJoint) -> TypedJoint {
297        TypedJoint::RopeJoint(joint)
298    }
299}
bevy_rapier3d/dynamics/rope_joint.rs

bevy_rapier3d/dynamics/
rope_joint.rs
