gale.ai.targeting module

This file contains helpers to aim projectiles: predict_intercept_time solves the classic “lead the target” problem for a constant-speed, drag-free projectile; ballistic_position gives a projectile’s position under gravity alone; simulate_drag_trajectory numerically integrates one under gravity and linear drag, for which no closed-form solution exists; and iterative_targeting_angle searches for the launch angle that hits a target under either model.

Author: Alejandro Mujica (aledrums@gmail.com)

gale.ai.targeting.predict_intercept_time(shooter_position, target_position, target_velocity, projectile_speed)[source]

Solve for how long a constant-speed, drag-free, gravity-free projectile fired now would take to reach a target moving at a constant velocity – the smallest positive root of the quadratic formed by requiring the projectile’s and target’s distance to close exactly as fast as the projectile can travel.

Parameters:

  • shooter_position (Vector2) – Position the projectile is fired from.

  • target_position (Vector2) – The target’s current position.

  • target_velocity (Vector2) – The target’s current velocity.

  • projectile_speed (float) – Speed of the projectile.

Returns:

Time (in seconds) until interception, or None if the target cannot be intercepted (it outruns the projectile in every direction, or projectile_speed is not positive).

Return type:

float | None

gale.ai.targeting.ballistic_position(origin, velocity, gravity, t)[source]
Parameters:

  • origin (Vector2) – The projectile’s launch position.

  • velocity (Vector2) – The projectile’s initial velocity.

  • gravity (Vector2) – Constant acceleration applied to the projectile (typically pointing down).

  • t (float) – Time (in seconds) since launch.

Returns:

The projectile’s position at time t, assuming no drag.

Return type:

Vector2

gale.ai.targeting.simulate_drag_trajectory(origin, velocity, gravity, drag, dt, steps)[source]

Numerically integrate a projectile’s trajectory under constant gravity and linear drag (a deceleration proportional to speed), for which no closed-form position formula exists.

Parameters:

  • origin (Vector2) – The projectile’s launch position.

  • velocity (Vector2) – The projectile’s initial velocity.

  • gravity (Vector2) – Constant acceleration applied to the projectile (typically pointing down).

  • drag (float) – Linear drag coefficient; the deceleration applied each step is -drag * velocity.

  • dt (float) – Time step (in seconds) used for the integration.

  • steps (int) – Number of steps to simulate.

Returns:

The projectile’s position at launch and after each of the steps that follow (steps + 1 points in total).

Return type:

List[Vector2]

gale.ai.targeting.iterative_targeting_angle(origin, target_position, speed, gravity, drag=0.0, dt=0.016666666666666666, max_time=5.0, iterations=8)[source]

Search for the launch angle (relative to the direction facing the target) that lands a projectile of the given speed on target_position, by ternary-searching between that direction and straight up (-gravity) and simulating each candidate trajectory (via simulate_drag_trajectory) to see how close it lands. Works with or without drag, which is the point: unlike a closed-form ballistic solution, this keeps working once drag makes one unavailable.

Parameters:

  • origin (Vector2) – The projectile’s launch position.

  • target_position (Vector2) – The position to hit.

  • speed (float) – Speed of the projectile.

  • gravity (Vector2) – Constant acceleration applied to the projectile (typically pointing down).

  • drag (float) – Linear drag coefficient. The default value is 0 (no drag).

  • dt (float) – Time step used to simulate each candidate trajectory. The default value is 1/60.

  • max_time (float) – Maximum flight time to simulate per candidate, in seconds. The default value is 5.

  • iterations (int) – Number of ternary-search refinements to perform. The default value is 8.

Returns:

The launch angle (in radians, measured from the straight line to target_position, rotating towards -gravity) that comes closest to hitting target_position, or None if origin and target_position coincide.

Return type:

float | None