Skip to main content

Move2DComponent.ixx File

Component for 2D physics-based movement . More...

Included Headers​

#include <algorithm> #include <cassert> #include <cmath> #include <memory> #include <helios.engine.modules.scene.components.SceneNodeComponent> #include <helios.engine.ecs.GameObject> #include <helios.math> #include <helios.core.units.Unit> #include <helios.core.spatial.Transform> #include <helios.util.Guid> #include <helios.scene.SceneNode>

Namespaces Index​

namespacehelios
namespaceengine

Main engine module aggregating core infrastructure and game systems. More...

namespacemodules

Domain-specific components and systems. More...

namespacephysics

Physics simulation and collision detection subsystem for the game engine. More...

namespacemotion

Motion physics components and systems. More...

namespacecomponents

Physics and movement components for game entities. More...

Classes Index​

classMove2DComponent

Component for 2D physics-based movement. More...

Description​

Component for 2D physics-based movement .

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file Move2DComponent.ixx
3 * @brief Component for 2D physics-based movement .
4 */
5module;
6
7#include <algorithm>
8#include <cassert>
9#include <cmath>
10#include <memory>
11
12export module helios.engine.modules.physics.motion.components.Move2DComponent;
13
14import helios.scene.SceneNode;
15import helios.util.Guid;
16import helios.core.spatial.Transform;
17import helios.math;
18import helios.core.units.Unit;
19
20import helios.engine.ecs.GameObject;
21import helios.engine.modules.scene.components.SceneNodeComponent;
22
23
24export namespace helios::engine::modules::physics::motion::components {
25
26 /**
27 * @brief Component for 2D physics-based movement.
28 *
29 * @details
30 * Stores configuration and runtime state for 2D physics-based movement.
31 * This component is used by the Move2DSystem to apply smooth acceleration
32 * and deceleration to the entity.
33 *
34 * The component receives input via move() which sets target direction and throttle.
35 * The actual physics simulation (integration of velocity, application of dampening)
36 * is performed by the Move2DSystem.
37 *
38 * @note Rotation/heading is handled separately by SteeringComponent and SteeringSystem.
39 *
40 * @see helios::engine::modules::physics::motion::components::SteeringComponent
41 * @see helios::engine::modules::physics::systems::Move2DSystem
42 */
43 class Move2DComponent {
44
45 protected:
46
47
48 // ========================================
49 // Default Physics Constants
50 // ========================================
51
52
53 /**
54 * @brief Default minimum movement speed before the ship stops completely.
55 */
56 static constexpr float DEFAULT_MOVEMENT_SPEED_THRESHOLD = 0.1f;
57
58
59 /**
60 * @brief Default movement acceleration in units per second squared.
61 */
62 static constexpr float DEFAULT_MOVEMENT_ACCELERATION = 30.0f;
63
64 /**
65 * @brief Default base movement speed in units per second.
66 */
67 static constexpr float DEFAULT_MOVEMENT_SPEED = 30.0f;
68
69
70 /**
71 * @brief Default exponential decay factor for movement when input stops.
72 */
73 static constexpr float DEFAULT_MOVEMENT_DAMPENING = 0.1f;
74
75
76 // ========================================
77 // Configurable Physics Parameters
78 // ========================================
79
80 /**
81 * @brief Minimum movement speed before the ship stops completely.
82 */
83 float movementSpeedThreshold_ = DEFAULT_MOVEMENT_SPEED_THRESHOLD;
84
85 /**
86 * @brief Movement acceleration in units per second squared.
87 */
88 float movementAcceleration_ = DEFAULT_MOVEMENT_ACCELERATION;
89
90 /**
91 * @brief Base movement speed in units per second.
92 */
93 float movementSpeed_ = DEFAULT_MOVEMENT_SPEED;
94
95
96 /**
97 * @brief Exponential decay factor for movement when input stops.
98 */
99 float movementDampening_ = DEFAULT_MOVEMENT_DAMPENING;
100
101 // ========================================
102 // Runtime State Variables
103 // ========================================
104
105 /**
106 * @brief Current movement speed after applying input and dampening.
107 */
108 float currentMovementSpeed_ = 0.0f;
109
110 /**
111 * @brief Indicates whether input is currently being received.
112 */
113 bool stateChanged_ = true;
114
115
116 /**
117 * @brief Current throttle value from input (0.0 to 1.0).
118 */
119 float throttle_ = 0.0f;
120
121 /**
122 * @brief Current steering input as 2D direction vector.
123 */
124 helios::math::vec2f direction_;
125
126 /**
127 * @brief Current velocity vector in world space.
128 */
129 helios::math::vec3f velocity_;
130
131 /**
132 * @brief Inherited velocity from parent or external forces.
133 *
134 * @details Used for momentum inheritance when detaching from parent objects.
135 */
136 helios::math::vec3f inheritedVelocity_{0.0f};
137
138 /**
139 * @brief Flag for instant acceleration mode.
140 *
141 * @details When true, the entity accelerates instantly to target speed
142 * rather than smoothly ramping up.
143 */
144 bool useInstantAcceleration_ = false;
145
146 /**
147 * @brief Whether this component is enabled.
148 */
149 bool isEnabled_ = true;
150
151 /**
152 * @brief Resets this component's properties to default values.
153 */
154 void reset() {
155 currentMovementSpeed_ = 0.0f;
156 stateChanged_ = true;
157 throttle_ = 0.0f;
158 direction_ = {};
159 velocity_ = {};
160 inheritedVelocity_ = {};
161 }
162
163 public:
164
165 /**
166 * @brief Checks whether this component is enabled.
167 *
168 * @return True if enabled, false otherwise.
169 */
170 [[nodiscard]] bool isEnabled() const noexcept {
171 return isEnabled_;
172 }
173
174 /**
175 * @brief Enables this component.
176 */
177 void enable() noexcept {
178 isEnabled_ = true;
179 }
180
181 /**
182 * @brief Disables this component.
183 */
184 void disable() noexcept {
185 isEnabled_ = false;
186 }
187
188 /**
189 * @brief Default constructor with default physics parameters.
190 */
191 Move2DComponent() = default;
192
193 /**
194 * @brief Constructs a Move2DComponent with a specified movement speed.
195 *
196 * @param movementSpeed The maximum movement speed in units per second.
197 * @param movementAcceleration The acceleration rate (default: DEFAULT_MOVEMENT_ACCELERATION).
198 */
199 explicit Move2DComponent(
200 float movementSpeed,
201 float movementAcceleration = DEFAULT_MOVEMENT_ACCELERATION
202
203 ) :
204 movementSpeed_(movementSpeed), movementAcceleration_(movementAcceleration) {}
205
206 /**
207 * @brief Constructs a Move2DComponent with instant acceleration mode.
208 *
209 * @param movementSpeed The maximum movement speed in units per second.
210 * @param useInstantAcceleration If true, acceleration is instant.
211 */
212 explicit Move2DComponent(
213 float movementSpeed,
214 bool useInstantAcceleration
215
216 ) :
217 movementSpeed_(movementSpeed), useInstantAcceleration_(useInstantAcceleration) {}
218
219 /**
220 * @brief Copy constructor.
221 *
222 * @param other The component to copy from.
223 */
224 Move2DComponent(const Move2DComponent& other) :
225 useInstantAcceleration_(other.useInstantAcceleration_),
226 movementSpeed_(other.movementSpeed_),
227 movementSpeedThreshold_(other.movementSpeedThreshold_),
228 movementAcceleration_ (other.movementAcceleration_),
229 movementDampening_ (other.movementDampening_)
230 {}
231
232 Move2DComponent& operator=(const Move2DComponent&) = default;
233 Move2DComponent(Move2DComponent&&) noexcept = default;
234 Move2DComponent& operator=(Move2DComponent&&) noexcept = default;
235
236
237 /**
238 * @brief Sets the movement direction and throttle.
239 *
240 * @param direction Normalized 3D direction vector.
241 * @param throttle Magnitude of the stick input (0.0 to 1.0).
242 *
243 * @deprecated use setMoveIntent
244 */
245 void move(helios::math::vec3f direction, float throttle) {
246 setMoveIntent(direction, throttle);
247 }
248
249 /**
250 * @brief Sets the movement direction and throttle.
251 *
252 * @param direction Normalized 3D direction vector.
253 * @param throttle Magnitude of the stick input (0.0 to 1.0).
254 */
255 void setMoveIntent(helios::math::vec3f direction, float throttle) {
256
257 if (throttle <= helios::math::EPSILON_LENGTH) {
258 direction_ = helios::math::vec2f{0.0f, 0.0f};
259 throttle_ = 0.0f;
260 stateChanged_ = false;
261 return;
262 }
263
264 direction_ = direction.toVec2();
265 throttle_ = throttle;
266
267 assert(direction_.isNormalized() && "Unexpected direction vector - not normalized");
268
269 stateChanged_ = true;
270
271 currentMovementSpeed_ = movementSpeed_ * throttle_;
272 }
273
274 /**
275 * @brief Calls reset() when this Component is acquired.
276 *
277 * @see reset()
278 */
279 void onAcquire() noexcept {
280 reset();
281 }
282
283 /**
284 * @brief Calls reset() when this Component is released.
285 *
286 * @see reset()
287 */
288 void onRelease() noexcept {
289 reset();
290 }
291
292 /**
293 * @brief Returns whether instant acceleration mode is enabled.
294 *
295 * @return True if acceleration is instant, false for smooth ramping.
296 */
297 [[nodiscard]] bool useInstantAcceleration() const noexcept {
298 return useInstantAcceleration_;
299 }
300
301 /**
302 * @brief Sets the instant acceleration mode.
303 *
304 * @param useInstantAcceleration True to enable instant acceleration, false for smooth ramping.
305 */
306 void setUseInstantAcceleration(const bool useInstantAcceleration) noexcept {
307 useInstantAcceleration_ = useInstantAcceleration;
308 }
309
310 /**
311 * @brief Sets the inherited velocity from parent or external forces.
312 *
313 * @param inheritedVelocity The velocity vector to inherit.
314 */
315 void setInheritedVelocity(helios::math::vec3f inheritedVelocity) {
316 inheritedVelocity_ = inheritedVelocity;
317 }
318
319 /**
320 * @brief Returns the inherited velocity vector.
321 *
322 * @return The inherited velocity from parent or external forces.
323 */
324 [[nodiscard]] helios::math::vec3f inheritedVelocity() const noexcept {
325 return inheritedVelocity_;
326 }
327
328 /**
329 * @brief Sets the current velocity vector.
330 *
331 * @param velocity The new velocity vector.
332 */
333 void setVelocity(helios::math::vec3f velocity) noexcept {
334 velocity_ = velocity;
335 }
336
337 /**
338 * @brief Returns the current movement speed.
339 *
340 * @return The current movement speed.
341 */
342 [[nodiscard]] float currentMovementSpeed() const noexcept {
343 return currentMovementSpeed_;
344 }
345
346 /**
347 * @brief Sets the current movement speed.
348 *
349 * @param speed The new movement speed.
350 */
351 void setCurrentMovementSpeed(float speed) noexcept {
352 currentMovementSpeed_ = speed;
353 }
354
355 /**
356 * @brief Checks if input is currently active.
357 *
358 * @return True if input is active, false otherwise.
359 */
360 [[nodiscard]] bool stateChanged() const noexcept {
361 return stateChanged_;
362 }
363
364 /**
365 * @brief Returns the current steering input direction.
366 *
367 * @return Const reference to the 2D steering input vector.
368 */
369 [[nodiscard]] const helios::math::vec2f& direction() const noexcept {
370 return direction_;
371 }
372
373 /**
374 * @brief Returns the current throttle value (0.0 to 1.0).
375 *
376 * @return Current throttle magnitude from input.
377 */
378 [[nodiscard]] float throttle() const noexcept {
379 return throttle_;
380 }
381
382 /**
383 * @brief Returns the current velocity vector.
384 *
385 * @return Const reference to the 3D velocity vector in world space.
386 */
387 [[nodiscard]] const helios::math::vec3f& velocity() const noexcept {
388 return velocity_;
389 }
390
391 /**
392 * @brief Returns the current speed as a ratio of maximum speed.
393 *
394 * @return A value between 0 (stationary) and 1 (maximum speed).
395 */
396 [[nodiscard]] float speedRatio() const noexcept {
397 // Prevent division by zero if movementSpeed_ is zero or very close to zero
398 if (std::abs(movementSpeed_) < helios::math::EPSILON_LENGTH) {
399 return 0.0f;
400 }
401 return velocity_.length() / movementSpeed_;
402 }
403
404 // ========================================
405 // Physics Parameter Getters
406 // ========================================
407
408 /**
409 * @brief Returns the minimum movement speed threshold.
410 *
411 * @return Movement speed threshold below which movement stops.
412 */
413 [[nodiscard]] float movementSpeedThreshold() const noexcept { return movementSpeedThreshold_; }
414
415 /**
416 * @brief Returns the movement acceleration in units per second squared.
417 *
418 * @return Movement acceleration value.
419 */
420 [[nodiscard]] float movementAcceleration() const noexcept { return movementAcceleration_; }
421
422 /**
423 * @brief Returns the maximum movement speed in units per second.
424 *
425 * @return Maximum movement speed value.
426 */
427 [[nodiscard]] float movementSpeed() const noexcept { return movementSpeed_; }
428
429 /**
430 * @brief Returns the movement dampening factor.
431 *
432 * @return Exponential decay factor for movement.
433 */
434 [[nodiscard]] float movementDampening() const noexcept { return movementDampening_; }
435
436
437 // ========================================
438 // Physics Parameter Setters
439 // ========================================
440
441 /**
442 * @brief Sets the minimum movement speed threshold.
443 *
444 * @param value New threshold value.
445 */
446 void setMovementSpeedThreshold(float value) noexcept { movementSpeedThreshold_ = value; }
447
448
449 /**
450 * @brief Sets the movement acceleration in units per second squared.
451 *
452 * @param value New acceleration value.
453 */
454 void setMovementAcceleration(float value) noexcept { movementAcceleration_ = value; }
455
456 /**
457 * @brief Sets the maximum movement speed in units per second.
458 *
459 * @param value New maximum speed value.
460 */
461 void setMovementSpeed(float value) noexcept { movementSpeed_ = value; }
462
463 /**
464 * @brief Sets the movement dampening factor.
465 *
466 * @param value New dampening factor (exponential decay).
467 */
468 void setMovementDampening(float value) noexcept { movementDampening_ = value; }
469
470 // ========================================
471 // Reset to Defaults
472 // ========================================
473
474 /**
475 * @brief Resets all physics parameters to their default values.
476 */
477 void resetToDefaults() noexcept {
478 movementSpeedThreshold_ = DEFAULT_MOVEMENT_SPEED_THRESHOLD;
479 movementAcceleration_ = DEFAULT_MOVEMENT_ACCELERATION;
480 movementSpeed_ = DEFAULT_MOVEMENT_SPEED;
481 movementDampening_ = DEFAULT_MOVEMENT_DAMPENING;
482 }
483 };
484
485
486}
487

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.