Skip to main content

SteeringComponent.ixx File

Component for managing entity heading and rotation physics. 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.core.units.Unit> #include <helios.math> #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​

classSteeringComponent

Component that manages the heading (orientation) of an entity. More...

Description​

Component for managing entity heading and rotation physics.

File Listing​

The file content with the documentation metadata removed is:

1/**
2 * @file SteeringComponent.ixx
3 * @brief Component for managing entity heading and rotation physics.
4 */
5module;
6
7#include <algorithm>
8#include <cassert>
9#include <cmath>
10#include <memory>
11
12export module helios.engine.modules.physics.motion.components.SteeringComponent;
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 that manages the heading (orientation) of an entity.
28 *
29 * @details
30 * This component handles the rotational physics of an entity, including
31 * turning towards a target direction, rotation speed limits, and dampening.
32 * It maintains the current and target rotation angles and is used by the
33 * SteeringSystem to update the entity's orientation.
34 */
35 class SteeringComponent {
36
37 protected:
38
39 /**
40 * @brief Default maximum rotation speed in degrees per second.
41 */
42 static constexpr float DEFAULT_ROTATION_SPEED = 560.0f;
43
44 /**
45 * @brief Default minimum rotation speed before rotation stops completely.
46 */
47 static constexpr float DEFAULT_ROTATION_SPEED_THRESHOLD = 0.1f;
48
49 /**
50 * @brief Default exponential decay factor for rotation when input stops.
51 */
52 static constexpr float DEFAULT_ROTATION_DAMPENING = 0.0001f;
53
54 /**
55 * @brief Maximum rotation speed in degrees per second.
56 */
57 float rotationSpeed_ = DEFAULT_ROTATION_SPEED;
58
59 /**
60 * @brief Minimum rotation speed before rotation stops completely.
61 */
62 float rotationSpeedThreshold_ = DEFAULT_ROTATION_SPEED_THRESHOLD;
63
64 /**
65 * @brief Exponential decay factor for rotation when input stops.
66 */
67 float rotationDampening_ = DEFAULT_ROTATION_DAMPENING;
68
69 /**
70 * @brief Current rotation angle in degrees.
71 */
72 float currentRotationAngle_ = 0;
73
74 /**
75 * @brief Target rotation angle derived from input direction.
76 */
77 float targetRotationAngle_ = 0;
78
79 /**
80 * @brief Shortest angular distance to target rotation.
81 */
82 float rotationAngleDelta_ = 0;
83
84 /**
85 * @brief Current rotation speed after applying input and dampening.
86 */
87 float currentRotationSpeed_ = 0.0f;
88
89 /**
90 * @brief Indicates whether input is currently being received.
91 */
92 bool stateChanged_ = true;
93
94 /**
95 * @brief Intensity of the turn input, typically from 0 to 1.0.
96 *
97 * @details Derived from the magnitude of the input direction vector.
98 * Used to modulate rotation speed based on stick deflection.
99 */
100 float turnIntensity_ = 0.0f;
101
102 /**
103 * @brief Current steering input as 2D direction vector.
104 */
105 helios::math::vec3f steeringInput_;
106
107 /**
108 * @brief The axis around which rotation occurs.
109 *
110 * @details Defaults to Z-axis for 2D top-down rotation.
111 */
112 helios::math::vec3f rotationAxis_ = helios::math::Z_AXISf;
113
114 /**
115 * @brief Flag for instant rotation mode.
116 *
117 * @details When true, the entity snaps to the target rotation instantly
118 * rather than smoothly interpolating.
119 */
120 bool useInstantRotation_ = false;
121
122 /**
123 * @brief Flag indicating if the direction component should be updated from steering.
124 *
125 * @details If true, the DirectionComponent of the entity will be synchronized
126 * with the steering input direction.
127 */
128 bool directionFromSteering_ = false;
129
130 /**
131 * @brief Whether this component is enabled.
132 */
133 bool isEnabled_ = true;
134
135 public:
136
137 /**
138 * @brief Checks whether this component is enabled.
139 *
140 * @return True if enabled, false otherwise.
141 */
142 [[nodiscard]] bool isEnabled() const noexcept {
143 return isEnabled_;
144 }
145
146 /**
147 * @brief Enables this component.
148 */
149 void enable() noexcept {
150 isEnabled_ = true;
151 }
152
153 /**
154 * @brief Disables this component.
155 */
156 void disable() noexcept {
157 isEnabled_ = false;
158 }
159
160 /**
161 * @brief Default constructor.
162 */
163 SteeringComponent() = default;
164
165 /**
166 * @brief Constructs a SteeringComponent with specified settings.
167 *
168 * @param useInstantRotation If true, rotation snaps instantly to target.
169 * @param directionFromSteering If true, synchronizes DirectionComponent with steering.
170 */
171 explicit SteeringComponent(bool useInstantRotation, bool directionFromSteering = false) :
172 useInstantRotation_(useInstantRotation), directionFromSteering_(directionFromSteering) {}
173
174 /**
175 * @brief Copy constructor.
176 *
177 * @param other The component to copy from.
178 */
179 SteeringComponent(const SteeringComponent& other) :
180 useInstantRotation_(other.useInstantRotation_),
181 rotationSpeed_(other.rotationSpeed_),
182 directionFromSteering_(other.directionFromSteering_),
183 rotationSpeedThreshold_(other.rotationSpeedThreshold_),
184 rotationDampening_(other.rotationDampening_),
185 rotationAxis_(other.rotationAxis_) {}
186
187 SteeringComponent& operator=(const SteeringComponent&) = default;
188 SteeringComponent(SteeringComponent&&) noexcept = default;
189 SteeringComponent& operator=(SteeringComponent&&) noexcept = default;
190
191 /**
192 * @deprecated Use setSteeringIntent instead.
193 */
194 void setHeading(helios::math::vec3f direction, float turnIntensity) {
195 setSteeringIntent(direction, turnIntensity);
196 }
197
198 /**
199 * @brief Sets whether the direction component should be updated from steering.
200 *
201 * @param directionFromSteering True to enable synchronization, false to disable.
202 */
203 void setDirectionFromSteering(const bool directionFromSteering) noexcept {
204 directionFromSteering_ = directionFromSteering;
205 }
206
207 /**
208 * @brief Checks if direction synchronization is enabled.
209 *
210 * @return True if DirectionComponent is updated from steering, false otherwise.
211 */
212 bool directionFromSteering() const noexcept {
213 return directionFromSteering_;
214 }
215
216 /**
217 * @brief Returns whether instant rotation mode is enabled.
218 *
219 * @return True if rotation snaps instantly, false for smooth interpolation.
220 */
221 [[nodiscard]] bool useInstantRotation() const noexcept {
222 return useInstantRotation_;
223 }
224
225 /**
226 * @brief Sets the instant rotation mode.
227 *
228 * @param useInstantRotation True to snap instantly to target rotation, false for interpolation.
229 */
230 void setUseInstantRotation(const bool useInstantRotation) noexcept {
231 useInstantRotation_ = useInstantRotation;
232 }
233
234
235 /**
236 * @brief Sets the heading direction and turn intensity from input.
237 *
238 * @details Updates the heading input vector and turn intensity. If the
239 * turn intensity is below the epsilon threshold, input is deactivated
240 * and the heading is reset to zero.
241 *
242 * @param direction Normalized direction vector representing the desired heading.
243 * @param turnIntensity Magnitude of the input (0.0 to 1.0).
244 *
245 * @pre direction must be a normalized vector (length ~= 1.0).
246 */
247 void setSteeringIntent(helios::math::vec3f direction, float turnIntensity) {
248
249 steeringInput_ = direction;
250 turnIntensity_ = turnIntensity;
251 stateChanged_ = true;
252
253 if (turnIntensity_ <= helios::math::EPSILON_LENGTH) {
254 steeringInput_ = {0.0f, 0.0f, 0.0f};
255 stateChanged_ = false;
256 turnIntensity_ = 0.0f;
257 return;
258 }
259
260 assert(direction.isNormalized() && "Unexpected direction vector - not normalized");
261 }
262
263 /**
264 * @brief Returns the axis around which rotation occurs.
265 *
266 * @details For 2D gameplay on the XY plane, this is typically the Z-axis.
267 *
268 * @return The rotation axis as a unit vector.
269 */
270 [[nodiscard]] helios::math::vec3f rotationAxis() const noexcept {
271 return rotationAxis_;
272 }
273
274 /**
275 * Resets this component to its default values.
276 */
277 void reset() noexcept {
278 currentRotationAngle_ = 0.0f;
279 targetRotationAngle_ = 0.0f;
280 rotationAngleDelta_ = 0.0f;
281 currentRotationSpeed_ = 0.0f;
282 stateChanged_ = true;
283 turnIntensity_ = 0.0f;
284 steeringInput_ = {0.0f, 0.0f, 0.0f};
285 }
286
287 /**
288 * @brief Sets the current rotation speed.
289 *
290 * @param speed The new rotation speed.
291 */
292 void setCurrentRotationSpeed(float speed) noexcept {
293 currentRotationSpeed_ = speed;
294 }
295
296 /**
297 * @brief Returns the current rotation speed.
298 *
299 * @return The current rotation speed.
300 */
301 [[nodiscard]] float currentRotationSpeed() const noexcept {
302 return currentRotationSpeed_;
303 }
304
305 /**
306 * @brief Returns the angular distance to the target rotation.
307 *
308 * @return The angle delta in degrees.
309 */
310 [[nodiscard]] float rotationAngleDelta() const noexcept {
311 return rotationAngleDelta_;
312 }
313
314 /**
315 * @brief Returns the current rotation angle.
316 *
317 * @return The current rotation angle in degrees.
318 */
319 [[nodiscard]] float currentRotationAngle() const noexcept {
320 return currentRotationAngle_;
321 }
322
323 /**
324 * @brief Returns the target rotation angle.
325 *
326 * @return The target rotation angle in degrees.
327 */
328 [[nodiscard]] float targetRotationAngle() const noexcept {
329 return targetRotationAngle_;
330 }
331
332 /**
333 * @brief Sets the target rotation angle.
334 *
335 * @param angle The new target rotation angle in degrees.
336 */
337 void setTargetRotationAngle(float angle) noexcept {
338 targetRotationAngle_ = angle;
339 }
340
341 /**
342 * @brief Sets the current rotation angle.
343 *
344 * @param angle The new rotation angle in degrees.
345 */
346 void setCurrentRotationAngle(float angle) noexcept {
347 currentRotationAngle_ = angle;
348 }
349
350 /**
351 * @brief Sets the angular distance to the target rotation.
352 *
353 * @param delta The new angle delta in degrees.
354 */
355 void setRotationAngleDelta(float delta) noexcept {
356 rotationAngleDelta_ = delta;
357 }
358
359 /**
360 * @brief Checks if input is currently active.
361 *
362 * @return True if input is active, false otherwise.
363 */
364 [[nodiscard]] bool stateChanged() const noexcept {
365 return stateChanged_;
366 }
367
368 /**
369 * @brief Returns the current steering input direction.
370 *
371 * @return Const reference to the 2D steering input vector.
372 */
373 [[nodiscard]] const helios::math::vec3f& steeringInput() const noexcept {
374 return steeringInput_;
375 }
376
377 /**
378 * @brief Returns the current steering intent (alias for steeringInput).
379 *
380 * @return Const reference to the steering input vector.
381 */
382 [[nodiscard]] const helios::math::vec3f& steeringIntent() const noexcept {
383 return steeringInput_;
384 }
385
386 /**
387 * @brief Returns the maximum rotation speed in degrees per second.
388 *
389 * @return Maximum rotation speed value.
390 */
391 [[nodiscard]] float rotationSpeed() const noexcept { return rotationSpeed_; }
392
393 /**
394 * @brief Returns the minimum rotation speed threshold.
395 *
396 * @return Rotation speed threshold below which rotation stops.
397 */
398 [[nodiscard]] float rotationSpeedThreshold() const noexcept { return rotationSpeedThreshold_; }
399
400 /**
401 * @brief Returns the rotation dampening factor.
402 *
403 * @return Exponential decay factor for rotation.
404 */
405 [[nodiscard]] float rotationDampening() const noexcept { return rotationDampening_; }
406
407 /**
408 * @brief Sets the maximum rotation speed in degrees per second.
409 *
410 * @param value New rotation speed value.
411 */
412 void setRotationSpeed(float value) noexcept { rotationSpeed_ = value; }
413
414
415
416 /**
417 * @brief Sets the minimum rotation speed threshold.
418 *
419 * @param value New threshold value.
420 */
421 void setRotationSpeedThreshold(float value) noexcept {
422 rotationSpeedThreshold_ = value;
423 }
424
425 /**
426 * @brief Sets the rotation dampening factor.
427 *
428 * @param value New dampening factor (exponential decay).
429 */
430 void setRotationDampening(float value) noexcept {
431 rotationDampening_ = value;
432 }
433
434 /**
435 * @brief Returns the current turn intensity.
436 *
437 * @return Turn intensity value, typically from 0 to 1.0.
438 */
439 [[nodiscard]] float turnIntensity() const noexcept {
440 return turnIntensity_;
441 }
442
443 // ========================================
444 // Reset to Defaults
445 // ========================================
446
447 /**
448 * @brief Resets all physics parameters to their default values.
449 */
450 void resetToDefaults() noexcept {
451 rotationSpeed_ = DEFAULT_ROTATION_SPEED;
452 rotationSpeedThreshold_ = DEFAULT_ROTATION_SPEED_THRESHOLD;
453 rotationDampening_ = DEFAULT_ROTATION_DAMPENING;
454 }
455 };
456
457
458}
459

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.