Ballistics Data
This is a helper struct used in many of our tools and has a 2D variant: BallisticsData
encapsulates the core parameters needed to define and manipulate a projectile’s ballistic behavior. It holds the initial velocity vector and collision radius, and provides helper properties and methods for aiming (low‐ or high‐arc) and predicting full flight paths (used by BallisticPath
).
Public Fields
Velocity
public Vector3 velocity
The projectile’s current world‐space velocity vector (direction & magnitude).Initially set this to something like
transform.forward * muzzleSpeed
.
Radius
public float radius
Radius (in world units) of the projectile—used for sphere‐casting when predicting collisions or following a path.For a small bullet you might use
0.05f
; for a grenade,0.2f
, etc.
Public Properties
Speed
public float Speed { get; set; }
Getter: Returns
velocity.magnitude
(the current speed).Setter: Normalizes
velocity
and multiplies by the assigned speed.Designer Usage:
Direction
public Vector3 Direction { get; set; }
Getter: Returns
velocity.normalized
(unit direction).Setter: Keeps the current speed magnitude and replaces direction with the assigned vector.
Designer Usage:
Rotation
public Quaternion Rotation { get; set; }
Getter: Returns a
Quaternion
that looks alongDirection
(i.e.,Quaternion.LookRotation(Direction)
).Setter: Applies the assigned rotation’s forward vector (i.e.,
rotation * Vector3.forward
) multiplied by the currentSpeed
.Designer Usage:
Aiming Methods
All Aim
methods solve for a firing angle (using gravity or a constant acceleration) and immediately set Rotation
so that velocity
points along the chosen ballistic arc. They return true
if a valid solution exists.
public bool Aim(Vector3 from, Vector3 to)
Description: Computes a low‐arc firing solution from
from
(launch origin) toto
(target position), under Unity’s default gravity (Physics.gravity
).Success: If there is at least one valid trajectory, it chooses the lower‐angle solution, sets
Rotation
accordingly (so thatvelocity = forward * Speed
follows that arc), and returnstrue
.Failure: If no trajectory can hit the target (e.g., target out of range for the given
Speed
), returnsfalse
and leavesRotation
unchanged.
public bool Aim(Vector3 from, Vector3 to, Vector3 constantAcceleration)
Description: Same as above, but uses
constantAcceleration
instead ofPhysics.gravity
. Useful for custom gravity fields (e.g., 2D games, special zones).Usage:
public bool AimHigh(Vector3 from, Vector3 to)
Description: Computes a high‐arc firing solution under default gravity. Uses the “high‐angle” solution (steeper angle).
Usage:
public bool AimHigh(Vector3 from, Vector3 to, Vector3 constantAcceleration)
Description: High‐arc solve under a custom acceleration vector.
Usage:
Flight Prediction
public BallisticPath Predict(Vector3 from, Collider fromCollider, float resolution, float distanceLimit, LayerMask collisionLayers, QueryTriggerInteraction queryTriggerInteraction = QueryTriggerInteraction.UseGlobal, Vector3? constantAcceleration = null)
Purpose Simulate the projectile’s flight—sampling its position, velocity, and elapsed time at regular intervals—while also sphere‐casting to detect collisions (bounces or stops). Returns a
BallisticPath
struct containing all sampled steps, total distance, total time, and the first collision (if any).Parameters
Vector3 from
: World‐space launch position.Collider fromCollider
: Collider to ignore on the first cast (typically the shooter’s collider).float resolution
: Sample spacing (in world units). Smaller → more samples, higher fidelity, more CPU.float distanceLimit
: Max path length before giving up (e.g., 50m).LayerMask collisionLayers
: Layers to test for collisions.QueryTriggerInteraction queryTriggerInteraction
(optional): Whether to include triggers.Vector3? constantAcceleration
(optional): Overrides Unity’s gravity. Ifnull
, usesPhysics.gravity
.
Behavior
If
velocity == Vector3.zero
, returnsBallisticPath.Empty
(no path).Otherwise, calls the internal
API.Ballistics.SphereCast(...)
routine under the hood (usingvelocity
,acceleration
,radius
) to build a sampled path:steps[]
: Each entry is(position, velocity, time)
at that sample.flightDistance
: Total distance traveled to the last sample.flightTime
: Time of the last sample (taken fromsteps[^1].time
).impact
: If the sphere‐cast detected a hit, this is theRaycastHit
; otherwisenull
.
Returns A fully constructed
BallisticPath
, which you can then pass toBallisticPathFollow
or use for drawing/editing:
Designer & Programmer Tips
Initialize
velocity
Directly You can bypassSpeed
/Direction
and setvelocity
directly if you already know the full vector. Example:Using
Speed
,Direction
, andRotation
data.Speed = 20f;
→ Maintains current direction but changes speed to 20.data.Direction = Vector3.up;
→ Keeps the same speed, now pointing straight up.data.Rotation = Quaternion.Euler(0, 30, 0);
→ Setsvelocity
to(forward-of-30°) * existing Speed
.
Choosing Low vs. High Arc
Low Arc (
Aim
) → Flatter trajectory, faster time of flight, less drop—ideal for direct shots.High Arc (
AimHigh
) → Steeper trajectory, longer airtime—useful for clearing obstacles or firing over hills.
Custom Gravity
If you’re working in a space environment or simulating different gravitational pull, call the overload with
constantAcceleration
.E.g., for a moon‐like environment with weaker gravity:
Predicting Before Instantiation
Run
Predict(...)
in anOnDrawGizmos
or preview mode to display the full arc before actually spawning a physical projectile.Use the returned
BallisticPath
to draw lines, place UI markers, or schedule sounds/effects at predicted collision points.
Collision Radius
If your projectile is essentially a ray (e.g., bullet), set
radius = 0f
.For objects like grenades or balls, choose a radius matching the model’s approximate size (e.g.,
0.25f
).
Handling Zero‐Velocity
If you forget to set
Speed
(leavingvelocity == Vector3.zero
),Predict(...)
immediately returns an empty path—no crash, but nothing happens. Keep an eye on runtime logs or guard before calling.
Last updated