mirror of
https://github.com/orange-cpp/omath.git
synced 2026-02-13 15:03:27 +00:00
Orange
95c0873b8c
Adds documentation for the `omath::ViewAngles` struct, clarifying its purpose, common usage patterns, and the definition of the types of pitch, yaw and roll. Also, adds short explanations of how to use ViewAngles and what tradeoffs exist between using raw float types and strongly typed Angle<> types.
97 lines
3.2 KiB
Markdown
97 lines
3.2 KiB
Markdown
# `omath::projectile_prediction::Projectile` — Projectile parameters for aim solvers
|
||
|
||
> Header: `omath/projectile_prediction/projectile.hpp`
|
||
> Namespace: `omath::projectile_prediction`
|
||
> Used by: `ProjPredEngineInterface` implementations (e.g., `ProjPredEngineLegacy`, `ProjPredEngineAvx2`)
|
||
|
||
`Projectile` is a tiny data holder that describes how a projectile is launched: **origin** (world position), **launch speed**, and a **gravity scale** (multiplier applied to the engine’s gravity constant).
|
||
|
||
---
|
||
|
||
## API
|
||
|
||
```cpp
|
||
namespace omath::projectile_prediction {
|
||
|
||
class Projectile final {
|
||
public:
|
||
Vector3<float> m_origin; // Launch position (world space)
|
||
float m_launch_speed{}; // Initial speed magnitude (units/sec)
|
||
float m_gravity_scale{}; // Multiplier for global gravity (dimensionless)
|
||
};
|
||
|
||
} // namespace omath::projectile_prediction
|
||
```
|
||
|
||
---
|
||
|
||
## Field semantics
|
||
|
||
* **`m_origin`**
|
||
World-space position where the projectile is spawned (e.g., muzzle or emitter point).
|
||
|
||
* **`m_launch_speed`**
|
||
Initial speed **magnitude** in your world units per second. Direction is determined by the solver (from yaw/pitch).
|
||
|
||
* Must be **non-negative**. Zero disables meaningful ballistic solutions.
|
||
|
||
* **`m_gravity_scale`**
|
||
Multiplies the engine’s gravity constant provided to the solver (e.g., `g = gravity_constant * m_gravity_scale`).
|
||
|
||
* Use `1.0f` for normal gravity, `0.0f` for no-drop projectiles, other values to simulate heavier/lighter rounds.
|
||
|
||
> Units must be consistent across your project (e.g., meters & seconds). If `gravity_constant = 9.81f`, then `m_launch_speed` is in m/s and positions are in meters.
|
||
|
||
---
|
||
|
||
## Typical usage
|
||
|
||
```cpp
|
||
using namespace omath::projectile_prediction;
|
||
|
||
Projectile proj;
|
||
proj.m_origin = { 0.0f, 1.6f, 0.0f }; // player eye / muzzle height
|
||
proj.m_launch_speed = 850.0f; // e.g., 850 m/s
|
||
proj.m_gravity_scale = 1.0f; // normal gravity
|
||
|
||
// With an aim solver:
|
||
auto aim = engine->maybe_calculate_aim_point(proj, target);
|
||
if (aim) {
|
||
// rotate/aim toward *aim and fire
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## With gravity-aware solver (outline)
|
||
|
||
Engines typically compute the firing angles to reach a predicted target position:
|
||
|
||
* Horizontal distance `x` and vertical offset `y` are derived from `target - m_origin`.
|
||
* Gravity used is `g = gravity_constant * m_gravity_scale`.
|
||
* Launch direction has speed `m_launch_speed` and angles solved by the engine.
|
||
|
||
If `m_gravity_scale == 0`, engines usually fall back to straight-line (no-drop) solutions.
|
||
|
||
---
|
||
|
||
## Validation & tips
|
||
|
||
* Keep `m_launch_speed ≥ 0`. Negative values are nonsensical.
|
||
* If your weapon can vary muzzle speed (charge-up, attachments), update `m_launch_speed` per shot.
|
||
* For different ammo types (tracers, grenades), prefer tweaking **`m_gravity_scale`** (and possibly the engine’s gravity constant) to match observed arc.
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
* `ProjPredEngineInterface` — common interface for aim solvers
|
||
* `ProjPredEngineLegacy` — trait-based, time-stepped ballistic solver
|
||
* `ProjPredEngineAvx2` — AVX2-accelerated solver with fixed-time pitch solve
|
||
* `Target` — target state consumed by the solvers
|
||
* `Vector3<float>` — math type used for positions and directions
|
||
|
||
---
|
||
|
||
*Last updated: 1 Nov 2025*
|