[General Purpose] New Parabola trajectory (#1374)

- As the name says, this is a completely reset `Arcing` with different
enhanced functions. Without doubt, It supported linkage with
`Trajectory=Disperse`.
- `Trajectory.Parabola.DetonationDistance` controls the maximum distance
in cells from intended target (checked at start of each game frame,
before the projectile moves) at which the projectile will be forced to
detonate. Set to 0 to disable forced detonation.
- `Trajectory.Parabola.TargetSnapDistance` controls the maximum distance
in cells from intended target the projectile can be at moment of
detonation to make the projectile 'snap' on the intended target. Set to
0 to disable snapping.
- `Trajectory.Parabola.OpenFireMode` controls how should the projectile
be launched. This has the following 6 modes.
- Speed - Automatic calculation mode with fixed horizontal velocity,
using `Trajectory.Speed` and target coordinates as calculation
conditions, i.e. the flight time of the projectile is permanently fixed.
- Height - Automatic calculation mode with fixed maximum height, useing
`Trajectory.Parabola.ThrowHeight` and target coordinates as calculation
conditions, i.e. the detonation time of the projectile is relatively
fixed.
- Angle - Automatic calculation mode with fixed fire angle, useing
`Trajectory.Parabola.LaunchAngle` and target coordinates as calculation
conditions. In this mode, the performance consumption is high, and may
have no solution. It is not recommended to enable `SubjectToCliffs` or
enable `AA` with a smaller `MinimumRange` when using this mode.
- SpeedAndHeight - Fixed horizontal velocity and maximum height mode,
using `Trajectory.Speed` and `Trajectory.Parabola.ThrowHeight` as
calculation conditions, i.e. the trajectory will only undergo altitude
changes with the height of the target.
- HeightAndAngle - Fixed maximum height and fire angle mode, using
`Trajectory.Parabola.ThrowHeight` and `Trajectory.Parabola.LaunchAngle`
as calculation conditions, i.e. the trajectory will change horizontally
with the height of the target.
- SpeedAndAngle - Fixed horizontal velocity and fire angle mode, using
`Trajectory.Speed` and `Trajectory.Parabola.LaunchAngle` as calculation
conditions, i.e. the trajectory will be permanently fixed.
- `Trajectory.Parabola.ThrowHeight` controls the maximum height of the
projectile and is only used for modes 1, 3, or 4. The specific height
will be determined by taking the larger of the launch height and the
target height then increasing this value. Non positive numbers are not
supported.
- `Trajectory.Parabola.LaunchAngle` controls the fire angle of the
projectile and is only used for modes 2, 4, or 5. Only supports -90.0 ~
90.0 (Cannot use boundary values) in Mode 2 or 5, and 0.0 ~ 90.0 (Cannot
use boundary values) in Mode 4.
- `Trajectory.Parabola.LeadTimeCalculate` controls whether the
projectile need to calculate the lead time of the target when firing.
Note that this will not affect the facing of the turret.
- `Trajectory.Parabola.DetonationAngle` controls when the angle between
the projectile in the current velocity direction and the horizontal
plane is less than this value, it will detonate prematurely. Taking
effect when the value is at -90.0 ~ 90.0 (Cannot use boundary values).
- `Trajectory.Parabola.DetonationHeight` controls when the projectile is
in a descending state and below the height of the launch position plus
this value, it will detonate prematurely. Taking effect when it is set
to non negative value.
- `Trajectory.Parabola.BounceTimes` controls how many times can it
bounce back when the projectile hits the ground or cliff. Be aware that
excessive projectile speed may cause abnormal operation. And
`Trajectory.Parabola.DetonationDistance` do not conflict with this and
will take effect simultaneously. So if you want to explode the bullet
only after the times of bounces is exhausted, you should set
`Trajectory.Parabola.DetonationDistance` to a non positive value.
- `Trajectory.Parabola.BounceOnWater` controls whether it can bounce on
the water surface.
- `Trajectory.Parabola.BounceDetonate` controls whether it detonates the
warhead once extra during each bounce.
- `Trajectory.Parabola.BounceAttenuation` controls the attenuation
coefficient of projectile bounce damage, that is, how many times the
next damage after each bounce is the damage just caused. This will also
affect the damage of the final detonation.
- `Trajectory.Parabola.BounceCoefficient` controls the attenuation
coefficient of projectile bounce elasticity, that is, how many times the
speed after each bounce is the speed before bouncing.
- `Trajectory.Parabola.OffsetCoord` controls the offsets of the target.
Projectile will aim at this position to attack. It also supports
`Inaccurate=yes` and `Trajectory.Parabola.LeadTimeCalculate=true` on
this basis.
- `Trajectory.Parabola.RotateCoord` controls whether to rotate the
projectile's firing direction within the angle bisector of
`Trajectory.Parabola.OffsetCoord` according to the weapon's `Burst`. Set
to 0 to disable this function.
- `Trajectory.Parabola.MirrorCoord` controls whether
`Trajectory.Parabola.OffsetCoord` need to mirror the lateral value to
adapt to the current burst index. At the same time, the rotation
direction calculated by `Trajectory.Parabola.RotateCoord` will also be
reversed, and the rotation angle between each adjacent projectile on
each side will not change as a result.
- `Trajectory.Parabola.UseDisperseBurst` controls whether the
calculation of `Trajectory.Parabola.RotateCoord` is based on its
superior's `Trajectory.Disperse.WeaponBurst` of the dispersed
trajectory, rather than `Burst` of the weapon. If this value is not
appropriate, it will result in unsatisfactory visual displays.
- `Trajectory.Parabola.AxisOfRotation` controls the rotation axis when
calculating `Trajectory.Parabola.RotateCoord`. The axis will rotates
with the unit orientation or the vector that from target position to the
source position.

In `rulesmd.ini`:
```ini
Trajectory=Parabola                             ; Trajectory type
Trajectory.Parabola.DetonationDistance=0.4      ; floating point value
Trajectory.Parabola.TargetSnapDistance=0.5      ; floating point value
Trajectory.Parabola.OpenFireMode=speed          ; ParabolaFireMode value enumeration (speed|height|angle|speedandheight|heightandangle|speedandangle)
Trajectory.Parabola.ThrowHeight=600             ; integer
Trajectory.Parabola.LaunchAngle=30              ; floating point value
Trajectory.Parabola.LeadTimeCalculate=no        ; boolean
Trajectory.Parabola.DetonationAngle=-90.0       ; floating point value
Trajectory.Parabola.DetonationHeight=-1         ; integer
Trajectory.Parabola.BounceTimes=0               ; integer
Trajectory.Parabola.BounceOnWater=no            ; boolean
Trajectory.Parabola.BounceDetonate=no           ; boolean
Trajectory.Parabola.BounceAttenuation=0.8       ; floating point value
Trajectory.Parabola.BounceCoefficient=0.8       ; floating point value
Trajectory.Parabola.OffsetCoord=0,0,0           ; integer - Forward,Lateral,Height
Trajectory.Parabola.RotateCoord=0               ; floating point value
Trajectory.Parabola.MirrorCoord=yes             ; boolean
Trajectory.Parabola.UseDisperseBurst=no         ; boolean
Trajectory.Parabola.AxisOfRotation=0,0,1        ; integer - Forward,Lateral,Height
```

```{note}
- Compared to vanilla `Arcing`, this can also be used for aircrafts and airburst weapon.
- Certainly, `Gravity` can also affect the trajectory.
```

Author: CrimRecya

CREDITS.md

@@ -364,7 +364,7 @@ This page lists all the individual contributions to the project by their author.
   - `TurretOffset` support for SHP vehicles
   - Customizable rocker amplitude
   - Customizable wake anim
-  - Initial effort on optimization for crates' random distribution 
+  - Initial effort on optimization for crates' random distribution
 - **Fryone**
   - Customizable ElectricBolt Arcs
   - Sound entry on unit's creation
@@ -384,6 +384,7 @@ This page lists all the individual contributions to the project by their author.
   - Enhanced Straight trajectory
   - Enable Building Production Queue
   - Fix for sidebar not updating queued unit numbers when on hold
+  - New Parabola trajectory
 - **Ollerus**
   - Build limit group enhancement
   - Customizable rocker amplitude

Phobos.vcxproj

@@ -38,6 +38,7 @@
     <ClCompile Include="src\Ext\Bullet\Trajectories\BombardTrajectory.cpp" />
     <ClCompile Include="src\Ext\Bullet\Trajectories\PhobosTrajectory.cpp" />
     <ClCompile Include="src\Ext\Bullet\Trajectories\StraightTrajectory.cpp" />
+    <ClCompile Include="src\Ext\Bullet\Trajectories\ParabolaTrajectory.cpp" />
     <ClCompile Include="src\Ext\CaptureManager\Hooks.cpp" />
     <ClCompile Include="src\Ext\CaptureManager\Body.cpp" />
     <ClCompile Include="src\Ext\OverlayType\Body.cpp" />
@@ -199,6 +200,7 @@
     <ClInclude Include="src\Ext\Bullet\Trajectories\BombardTrajectory.h" />
     <ClInclude Include="src\Ext\Bullet\Trajectories\PhobosTrajectory.h" />
     <ClInclude Include="src\Ext\Bullet\Trajectories\StraightTrajectory.h" />
+    <ClInclude Include="src\Ext\Bullet\Trajectories\ParabolaTrajectory.h" />
     <ClInclude Include="src\Ext\OverlayType\Body.h" />
     <ClInclude Include="src\Ext\ParticleType\Body.h" />
     <ClInclude Include="src\Ext\Sidebar\Body.h" />

docs/New-or-Enhanced-Logics.md

@@ -737,7 +737,10 @@ Currently interceptor weapons with projectiles that do not have `Inviso=true` wi
 
 - Projectiles can now have customizable trajectories.
   - `Trajectory` should not be combined with original game's projectile trajectory logics (`Arcing`, `ROT`, `Vertical` or `Inviso`). Attempt to do so will result in the other logics being disabled and a warning being written to log file.
-  - Initial speed of the projectile is defined by `Trajectory.Speed`, which unlike `Speed` used by `ROT` > 0 projectiles is defined on projectile not weapon.
+  - The speed of the projectile is defined by `Trajectory.Speed`, which unlike `Speed` used by `ROT` > 0 projectiles is defined on projectile not weapon.
+    - In `Trajectory=Straight`, it refers to the whole distance speed of the projectile and it has no restrictions.
+    - In `Trajectory=Bombard`, it refers to the initial speed of the projectile and it has no restrictions.
+    - In `Trajectory=Parabola`, it refers to the horizontal velocity of the projectile and is only used for modes 0, 3, or 5 and it has no restrictions.
 
 In `rulesmd.ini`:
 ```ini
@@ -831,6 +834,63 @@ Trajectory=Bombard             ; Trajectory type
 Trajectory.Bombard.Height=0.0  ; double
 ```
 
+#### Parabola trajectory
+
+- As the name says, this is a completely reset `Arcing` with different enhanced functions. Without doubt, It supported linkage with `Trajectory=Disperse`.
+  - `Trajectory.Parabola.DetonationDistance` controls the maximum distance in cells from intended target (checked at start of each game frame, before the projectile moves) at which the projectile will be forced to detonate. Set to 0 to disable forced detonation. More specifically, when it is set to a negative value, if the target is movable, it will change its target to the cell where the target is located (This is a function expanded for `Disperse` and `Airburst` purposes).
+  - `Trajectory.Parabola.TargetSnapDistance` controls the maximum distance in cells from intended target the projectile can be at moment of detonation to make the projectile 'snap' on the intended target. Set to 0 to disable snapping.
+  - `Trajectory.Parabola.OpenFireMode` controls how should the projectile be launched. This has the following 6 modes.
+    - Speed - Automatic calculation mode with fixed horizontal velocity, using `Trajectory.Speed` and target coordinates as calculation conditions, i.e. the flight time of the projectile is permanently fixed.
+    - Height - Automatic calculation mode with fixed maximum height, useing `Trajectory.Parabola.ThrowHeight` and target coordinates as calculation conditions, i.e. the detonation time of the projectile is relatively fixed.
+    - Angle - Automatic calculation mode with fixed fire angle, useing `Trajectory.Parabola.LaunchAngle` and target coordinates as calculation conditions. In this mode, the performance consumption is high, and may have no solution. It is not recommended to enable `SubjectToCliffs` or enable `AA` with a smaller `MinimumRange` when using this mode.
+    - SpeedAndHeight - Fixed horizontal velocity and maximum height mode, using `Trajectory.Speed` and `Trajectory.Parabola.ThrowHeight` as calculation conditions, i.e. the trajectory will only undergo altitude changes with the height of the target.
+    - HeightAndAngle - Fixed maximum height and fire angle mode, using `Trajectory.Parabola.ThrowHeight` and `Trajectory.Parabola.LaunchAngle` as calculation conditions, i.e. the trajectory will change horizontally with the height of the target.
+    - SpeedAndAngle - Fixed horizontal velocity and fire angle mode, using `Trajectory.Speed` and `Trajectory.Parabola.LaunchAngle` as calculation conditions, i.e. the trajectory will be permanently fixed.
+  - `Trajectory.Parabola.ThrowHeight` controls the maximum height of the projectile and is only used for modes 1, 3, or 4. The specific height will be determined by taking the larger of the launch height and the target height then increasing this value. Non positive numbers are not supported.
+  - `Trajectory.Parabola.LaunchAngle` controls the fire angle of the projectile and is only used for modes 2, 4, or 5. Only supports -90.0 ~ 90.0 (Cannot use boundary values) in Mode 2 or 5, and 0.0 ~ 90.0 (Cannot use boundary values) in Mode 4.
+  - `Trajectory.Parabola.LeadTimeCalculate` controls whether the projectile need to calculate the lead time of the target when firing. Note that this will not affect the facing of the turret.
+  - `Trajectory.Parabola.DetonationAngle` controls when the angle between the projectile in the current velocity direction and the horizontal plane is less than this value, it will detonate prematurely. Taking effect when the value is at -90.0 ~ 90.0 (Cannot use boundary values).
+  - `Trajectory.Parabola.DetonationHeight` controls when the projectile is in a descending state and below the height of the launch position plus this value, it will detonate prematurely. Taking effect when it is set to non negative value.
+  - `Trajectory.Parabola.BounceTimes` controls how many times can it bounce back when the projectile hits the ground or cliff. Be aware that excessive projectile speed may cause abnormal operation. And `Trajectory.Parabola.DetonationDistance` do not conflict with this and will take effect simultaneously. So if you want to explode the bullet only after the times of bounces is exhausted, you should set `Trajectory.Parabola.DetonationDistance` to a non positive value.
+    - `Trajectory.Parabola.BounceOnWater` controls whether it can bounce on the water surface.
+    - `Trajectory.Parabola.BounceDetonate` controls whether it detonates the warhead once extra during each bounce.
+    - `Trajectory.Parabola.BounceAttenuation` controls the attenuation coefficient of projectile bounce damage, that is, how many times the next damage after each bounce is the damage just caused. This will also affect the damage of the final detonation.
+    - `Trajectory.Parabola.BounceCoefficient` controls the attenuation coefficient of projectile bounce elasticity, that is, how many times the speed after each bounce is the speed before bouncing.
+  - `Trajectory.Parabola.OffsetCoord` controls the offsets of the target. Projectile will aim at this position to attack. It also supports `Inaccurate=yes` and `Trajectory.Parabola.LeadTimeCalculate=true` on this basis.
+    - `Trajectory.Parabola.RotateCoord` controls whether to rotate the projectile's firing direction within the angle bisector of `Trajectory.Parabola.OffsetCoord` according to the weapon's `Burst`. Set to 0 to disable this function.
+    - `Trajectory.Parabola.MirrorCoord` controls whether `Trajectory.Parabola.OffsetCoord` need to mirror the lateral value to adapt to the current burst index. At the same time, the rotation direction calculated by `Trajectory.Parabola.RotateCoord` will also be reversed, and the rotation angle between each adjacent projectile on each side will not change as a result.
+    - `Trajectory.Parabola.UseDisperseBurst` controls whether the calculation of `Trajectory.Parabola.RotateCoord` is based on its superior's `Trajectory.Disperse.WeaponBurst` of the dispersed trajectory, rather than `Burst` of the weapon. If this value is not appropriate, it will result in unsatisfactory visual displays.
+    - `Trajectory.Parabola.AxisOfRotation` controls the rotation axis when calculating `Trajectory.Parabola.RotateCoord`. The axis will rotates with the unit orientation or the vector that from target position to the source position.
+
+In `rulesmd.ini`:
+```ini
+[SOMEPROJECTILE]                                ; Projectile
+Trajectory=Parabola                             ; Trajectory type
+Trajectory.Parabola.DetonationDistance=0.4      ; floating point value
+Trajectory.Parabola.TargetSnapDistance=0.5      ; floating point value
+Trajectory.Parabola.OpenFireMode=Speed          ; ParabolaFireMode value enumeration (Speed|Height|Angle|SpeedAndHeight|HeightAndAngle|SpeedAndAngle)
+Trajectory.Parabola.ThrowHeight=600             ; integer
+Trajectory.Parabola.LaunchAngle=30              ; floating point value
+Trajectory.Parabola.LeadTimeCalculate=no        ; boolean
+Trajectory.Parabola.DetonationAngle=-90.0       ; floating point value
+Trajectory.Parabola.DetonationHeight=-1         ; integer
+Trajectory.Parabola.BounceTimes=0               ; integer
+Trajectory.Parabola.BounceOnWater=no            ; boolean
+Trajectory.Parabola.BounceDetonate=no           ; boolean
+Trajectory.Parabola.BounceAttenuation=0.8       ; floating point value
+Trajectory.Parabola.BounceCoefficient=0.8       ; floating point value
+Trajectory.Parabola.OffsetCoord=0,0,0           ; integer - Forward,Lateral,Height
+Trajectory.Parabola.RotateCoord=0               ; floating point value
+Trajectory.Parabola.MirrorCoord=yes             ; boolean
+Trajectory.Parabola.UseDisperseBurst=no         ; boolean
+Trajectory.Parabola.AxisOfRotation=0,0,1        ; integer - Forward,Lateral,Height
+```
+
+```{note}
+- Compared to vanilla `Arcing`, this can also be used for aircrafts and airburst weapon.
+- Certainly, `Gravity` can also affect the trajectory.
+```
+
 ### Shrapnel enhancements
 
 ![image](_static/images/shrapnel.gif)

docs/Whats-New.md

@@ -319,6 +319,7 @@ New:
 - Custom exit cell for infantry factory (by Starkku)
 - Option for vehicles to keep target when issued move command (by Starkku)
 - Skip anim delay for burst fire (by TaranDahl)
+- New Parabola trajectory (by CrimRecya)
 
 Vanilla fixes:
 - Aircraft will now behave as expected according to it's `MovementZone` and `SpeedType` when moving onto different surfaces. In particular, this fixes erratic behavior when vanilla aircraft is ordered to move onto water surface and instead the movement order changes to a shore nearby (by CrimRecya)

src/Ext/Bullet/Hooks.cpp

@@ -292,7 +292,8 @@ DEFINE_HOOK(0x46902C, BulletClass_Explode_Cluster, 0x6)
 
 constexpr bool CheckTrajectoryCanNotAlwaysSnap(const TrajectoryFlag flag)
 {
-	return flag == TrajectoryFlag::Straight;
+	return flag == TrajectoryFlag::Straight
+		|| flag == TrajectoryFlag::Parabola;
 }
 
 DEFINE_HOOK(0x467CCA, BulletClass_AI_TargetSnapChecks, 0x6)