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 * @brief Sets the current rotation speed.
276 *
277 * @param speed The new rotation speed.
278 */
279 void setCurrentRotationSpeed(float speed) noexcept {
280 currentRotationSpeed_ = speed;
281 }
282
283 /**
284 * @brief Returns the current rotation speed.
285 *
286 * @return The current rotation speed.
287 */
288 [[nodiscard]] float currentRotationSpeed() const noexcept {
289 return currentRotationSpeed_;
290 }
291
292 /**
293 * @brief Returns the angular distance to the target rotation.
294 *
295 * @return The angle delta in degrees.
296 */
297 [[nodiscard]] float rotationAngleDelta() const noexcept {
298 return rotationAngleDelta_;
299 }
300
301 /**
302 * @brief Returns the current rotation angle.
303 *
304 * @return The current rotation angle in degrees.
305 */
306 [[nodiscard]] float currentRotationAngle() const noexcept {
307 return currentRotationAngle_;
308 }
309
310 /**
311 * @brief Returns the target rotation angle.
312 *
313 * @return The target rotation angle in degrees.
314 */
315 [[nodiscard]] float targetRotationAngle() const noexcept {
316 return targetRotationAngle_;
317 }
318
319 /**
320 * @brief Sets the target rotation angle.
321 *
322 * @param angle The new target rotation angle in degrees.
323 */
324 void setTargetRotationAngle(float angle) noexcept {
325 targetRotationAngle_ = angle;
326 }
327
328 /**
329 * @brief Sets the current rotation angle.
330 *
331 * @param angle The new rotation angle in degrees.
332 */
333 void setCurrentRotationAngle(float angle) noexcept {
334 currentRotationAngle_ = angle;
335 }
336
337 /**
338 * @brief Sets the angular distance to the target rotation.
339 *
340 * @param delta The new angle delta in degrees.
341 */
342 void setRotationAngleDelta(float delta) noexcept {
343 rotationAngleDelta_ = delta;
344 }
345
346 /**
347 * @brief Checks if input is currently active.
348 *
349 * @return True if input is active, false otherwise.
350 */
351 [[nodiscard]] bool stateChanged() const noexcept {
352 return stateChanged_;
353 }
354
355 /**
356 * @brief Returns the current steering input direction.
357 *
358 * @return Const reference to the 2D steering input vector.
359 */
360 [[nodiscard]] const helios::math::vec3f& steeringInput() const noexcept {
361 return steeringInput_;
362 }
363
364 /**
365 * @brief Returns the current steering intent (alias for steeringInput).
366 *
367 * @return Const reference to the steering input vector.
368 */
369 [[nodiscard]] const helios::math::vec3f& steeringIntent() const noexcept {
370 return steeringInput_;
371 }
372
373 /**
374 * @brief Returns the maximum rotation speed in degrees per second.
375 *
376 * @return Maximum rotation speed value.
377 */
378 [[nodiscard]] float rotationSpeed() const noexcept { return rotationSpeed_; }
379
380 /**
381 * @brief Returns the minimum rotation speed threshold.
382 *
383 * @return Rotation speed threshold below which rotation stops.
384 */
385 [[nodiscard]] float rotationSpeedThreshold() const noexcept { return rotationSpeedThreshold_; }
386
387 /**
388 * @brief Returns the rotation dampening factor.
389 *
390 * @return Exponential decay factor for rotation.
391 */
392 [[nodiscard]] float rotationDampening() const noexcept { return rotationDampening_; }
393
394 /**
395 * @brief Sets the maximum rotation speed in degrees per second.
396 *
397 * @param value New rotation speed value.
398 */
399 void setRotationSpeed(float value) noexcept { rotationSpeed_ = value; }
400
401
402
403 /**
404 * @brief Sets the minimum rotation speed threshold.
405 *
406 * @param value New threshold value.
407 */
408 void setRotationSpeedThreshold(float value) noexcept {
409 rotationSpeedThreshold_ = value;
410 }
411
412 /**
413 * @brief Sets the rotation dampening factor.
414 *
415 * @param value New dampening factor (exponential decay).
416 */
417 void setRotationDampening(float value) noexcept {
418 rotationDampening_ = value;
419 }
420
421 /**
422 * @brief Returns the current turn intensity.
423 *
424 * @return Turn intensity value, typically from 0 to 1.0.
425 */
426 [[nodiscard]] float turnIntensity() const noexcept {
427 return turnIntensity_;
428 }
429
430 // ========================================
431 // Reset to Defaults
432 // ========================================
433
434 /**
435 * @brief Resets all physics parameters to their default values.
436 */
437 void resetToDefaults() noexcept {
438 rotationSpeed_ = DEFAULT_ROTATION_SPEED;
439 rotationSpeedThreshold_ = DEFAULT_ROTATION_SPEED_THRESHOLD;
440 rotationDampening_ = DEFAULT_ROTATION_DAMPENING;
441 }
442 };
443
444
445}
446

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.