rapier2d/dynamics/joint/
prismatic_joint.rs

1use crate::dynamics::integration_parameters::SpringCoefficients;
2use crate::dynamics::joint::{GenericJoint, GenericJointBuilder, JointAxesMask};
3use crate::dynamics::{JointAxis, MotorModel};
4use crate::math::{Point, Real, UnitVector};
5
6use super::{JointLimits, JointMotor};
7
8#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
9#[derive(Copy, Clone, Debug, PartialEq)]
10#[repr(transparent)]
11/// A sliding joint that allows movement along one axis only (like a piston or sliding door).
12///
13/// Prismatic joints lock all motion except sliding along a single axis. Use for:
14/// - Pistons and hydraulics
15/// - Sliding doors and drawers
16/// - Elevator platforms
17/// - Linear actuators
18/// - Telescoping mechanisms
19///
20/// You can optionally add:
21/// - **Limits**: Restrict sliding distance (min/max positions)
22/// - **Motor**: Powered sliding with target velocity or position
23///
24/// The axis is specified when creating the joint and is expressed in each body's local space.
25pub struct PrismaticJoint {
26    /// The underlying joint data.
27    pub data: GenericJoint,
28}
29
30impl PrismaticJoint {
31    /// Creates a new prismatic joint allowing only relative translations along the specified axis.
32    ///
33    /// This axis is expressed in the local-space of both rigid-bodies.
34    pub fn new(axis: UnitVector<Real>) -> Self {
35        let data = GenericJointBuilder::new(JointAxesMask::LOCKED_PRISMATIC_AXES)
36            .local_axis1(axis)
37            .local_axis2(axis)
38            .build();
39        Self { data }
40    }
41
42    /// The underlying generic joint.
43    pub fn data(&self) -> &GenericJoint {
44        &self.data
45    }
46
47    /// Are contacts between the attached rigid-bodies enabled?
48    pub fn contacts_enabled(&self) -> bool {
49        self.data.contacts_enabled
50    }
51
52    /// Sets whether contacts between the attached rigid-bodies are enabled.
53    pub fn set_contacts_enabled(&mut self, enabled: bool) -> &mut Self {
54        self.data.set_contacts_enabled(enabled);
55        self
56    }
57
58    /// The joint’s anchor, expressed in the local-space of the first rigid-body.
59    #[must_use]
60    pub fn local_anchor1(&self) -> Point<Real> {
61        self.data.local_anchor1()
62    }
63
64    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
65    pub fn set_local_anchor1(&mut self, anchor1: Point<Real>) -> &mut Self {
66        self.data.set_local_anchor1(anchor1);
67        self
68    }
69
70    /// The joint’s anchor, expressed in the local-space of the second rigid-body.
71    #[must_use]
72    pub fn local_anchor2(&self) -> Point<Real> {
73        self.data.local_anchor2()
74    }
75
76    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
77    pub fn set_local_anchor2(&mut self, anchor2: Point<Real>) -> &mut Self {
78        self.data.set_local_anchor2(anchor2);
79        self
80    }
81
82    /// The principal axis of the joint, expressed in the local-space of the first rigid-body.
83    #[must_use]
84    pub fn local_axis1(&self) -> UnitVector<Real> {
85        self.data.local_axis1()
86    }
87
88    /// Sets the principal axis of the joint, expressed in the local-space of the first rigid-body.
89    pub fn set_local_axis1(&mut self, axis1: UnitVector<Real>) -> &mut Self {
90        self.data.set_local_axis1(axis1);
91        self
92    }
93
94    /// The principal axis of the joint, expressed in the local-space of the second rigid-body.
95    #[must_use]
96    pub fn local_axis2(&self) -> UnitVector<Real> {
97        self.data.local_axis2()
98    }
99
100    /// Sets the principal axis of the joint, expressed in the local-space of the second rigid-body.
101    pub fn set_local_axis2(&mut self, axis2: UnitVector<Real>) -> &mut Self {
102        self.data.set_local_axis2(axis2);
103        self
104    }
105
106    /// The motor affecting the joint’s translational degree of freedom.
107    #[must_use]
108    pub fn motor(&self) -> Option<&JointMotor> {
109        self.data.motor(JointAxis::LinX)
110    }
111
112    /// Set the spring-like model used by the motor to reach the desired target velocity and position.
113    pub fn set_motor_model(&mut self, model: MotorModel) -> &mut Self {
114        self.data.set_motor_model(JointAxis::LinX, model);
115        self
116    }
117
118    /// Sets the motor's target sliding speed.
119    ///
120    /// Makes the joint slide at a desired velocity (like a powered piston or conveyor).
121    ///
122    /// # Parameters
123    /// * `target_vel` - Desired velocity in units/second
124    /// * `factor` - Motor strength
125    pub fn set_motor_velocity(&mut self, target_vel: Real, factor: Real) -> &mut Self {
126        self.data
127            .set_motor_velocity(JointAxis::LinX, target_vel, factor);
128        self
129    }
130
131    /// Sets the motor's target position along the sliding axis.
132    ///
133    /// Makes the joint slide toward a specific position using spring-like behavior.
134    ///
135    /// # Parameters
136    /// * `target_pos` - Desired position along the axis
137    /// * `stiffness` - Spring constant
138    /// * `damping` - Resistance to motion
139    pub fn set_motor_position(
140        &mut self,
141        target_pos: Real,
142        stiffness: Real,
143        damping: Real,
144    ) -> &mut Self {
145        self.data
146            .set_motor_position(JointAxis::LinX, target_pos, stiffness, damping);
147        self
148    }
149
150    /// Configures both target position and target velocity for the motor.
151    pub fn set_motor(
152        &mut self,
153        target_pos: Real,
154        target_vel: Real,
155        stiffness: Real,
156        damping: Real,
157    ) -> &mut Self {
158        self.data
159            .set_motor(JointAxis::LinX, target_pos, target_vel, stiffness, damping);
160        self
161    }
162
163    /// Sets the maximum force the motor can deliver.
164    pub fn set_motor_max_force(&mut self, max_force: Real) -> &mut Self {
165        self.data.set_motor_max_force(JointAxis::LinX, max_force);
166        self
167    }
168
169    /// The limit distance attached bodies can translate along the joint’s principal axis.
170    #[must_use]
171    pub fn limits(&self) -> Option<&JointLimits<Real>> {
172        self.data.limits(JointAxis::LinX)
173    }
174
175    /// Sets the `[min,max]` limit distances attached bodies can translate along the joint’s principal axis.
176    pub fn set_limits(&mut self, limits: [Real; 2]) -> &mut Self {
177        self.data.set_limits(JointAxis::LinX, limits);
178        self
179    }
180
181    /// Gets the softness of this joint’s locked degrees of freedom.
182    #[must_use]
183    pub fn softness(&self) -> SpringCoefficients<Real> {
184        self.data.softness
185    }
186
187    /// Sets the softness of this joint.
188    #[must_use]
189    pub fn set_softness(&mut self, softness: SpringCoefficients<Real>) -> &mut Self {
190        self.data.softness = softness;
191        self
192    }
193}
194
195impl From<PrismaticJoint> for GenericJoint {
196    fn from(val: PrismaticJoint) -> GenericJoint {
197        val.data
198    }
199}
200
201/// Create prismatic joints using the builder pattern.
202///
203/// A prismatic joint locks all relative motion except for translations along the joint’s principal axis.
204#[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
205#[derive(Copy, Clone, Debug, PartialEq)]
206pub struct PrismaticJointBuilder(pub PrismaticJoint);
207
208impl PrismaticJointBuilder {
209    /// Creates a new builder for prismatic joints.
210    ///
211    /// This axis is expressed in the local-space of both rigid-bodies.
212    pub fn new(axis: UnitVector<Real>) -> Self {
213        Self(PrismaticJoint::new(axis))
214    }
215
216    /// Sets whether contacts between the attached rigid-bodies are enabled.
217    #[must_use]
218    pub fn contacts_enabled(mut self, enabled: bool) -> Self {
219        self.0.set_contacts_enabled(enabled);
220        self
221    }
222
223    /// Sets the joint’s anchor, expressed in the local-space of the first rigid-body.
224    #[must_use]
225    pub fn local_anchor1(mut self, anchor1: Point<Real>) -> Self {
226        self.0.set_local_anchor1(anchor1);
227        self
228    }
229
230    /// Sets the joint’s anchor, expressed in the local-space of the second rigid-body.
231    #[must_use]
232    pub fn local_anchor2(mut self, anchor2: Point<Real>) -> Self {
233        self.0.set_local_anchor2(anchor2);
234        self
235    }
236
237    /// Sets the principal axis of the joint, expressed in the local-space of the first rigid-body.
238    #[must_use]
239    pub fn local_axis1(mut self, axis1: UnitVector<Real>) -> Self {
240        self.0.set_local_axis1(axis1);
241        self
242    }
243
244    /// Sets the principal axis of the joint, expressed in the local-space of the second rigid-body.
245    #[must_use]
246    pub fn local_axis2(mut self, axis2: UnitVector<Real>) -> Self {
247        self.0.set_local_axis2(axis2);
248        self
249    }
250
251    /// Set the spring-like model used by the motor to reach the desired target velocity and position.
252    #[must_use]
253    pub fn motor_model(mut self, model: MotorModel) -> Self {
254        self.0.set_motor_model(model);
255        self
256    }
257
258    /// Sets the target velocity this motor needs to reach.
259    #[must_use]
260    pub fn motor_velocity(mut self, target_vel: Real, factor: Real) -> Self {
261        self.0.set_motor_velocity(target_vel, factor);
262        self
263    }
264
265    /// Sets the target angle this motor needs to reach.
266    #[must_use]
267    pub fn motor_position(mut self, target_pos: Real, stiffness: Real, damping: Real) -> Self {
268        self.0.set_motor_position(target_pos, stiffness, damping);
269        self
270    }
271
272    /// Configure both the target angle and target velocity of the motor.
273    #[must_use]
274    pub fn set_motor(
275        mut self,
276        target_pos: Real,
277        target_vel: Real,
278        stiffness: Real,
279        damping: Real,
280    ) -> Self {
281        self.0.set_motor(target_pos, target_vel, stiffness, damping);
282        self
283    }
284
285    /// Sets the maximum force the motor can deliver.
286    #[must_use]
287    pub fn motor_max_force(mut self, max_force: Real) -> Self {
288        self.0.set_motor_max_force(max_force);
289        self
290    }
291
292    /// Sets the `[min,max]` limit distances attached bodies can translate along the joint's principal axis.
293    #[must_use]
294    pub fn limits(mut self, limits: [Real; 2]) -> Self {
295        self.0.set_limits(limits);
296        self
297    }
298
299    /// Sets the softness of this joint’s locked degrees of freedom.
300    #[must_use]
301    pub fn softness(mut self, softness: SpringCoefficients<Real>) -> Self {
302        self.0.data.softness = softness;
303        self
304    }
305
306    /// Builds the prismatic joint.
307    #[must_use]
308    pub fn build(self) -> PrismaticJoint {
309        self.0
310    }
311}
312
313impl From<PrismaticJointBuilder> for GenericJoint {
314    fn from(val: PrismaticJointBuilder) -> GenericJoint {
315        val.0.into()
316    }
317}
rapier2d/dynamics/joint/prismatic_joint.rs

rapier2d/dynamics/joint/
prismatic_joint.rs
