Ammo Approaches Detailed
This is the definition for all your approaches. You will only have one of these in an ammo definition. If your ammo does not use approaches then you can safely delete this wrapper and everything inside it.
This is the definition for each individual approach. You can have as many approaches as you need for your ammo to do what it wants. Normally, approaches will execute in order, one after the other until the end condition of the final approach is met. If the projectile is still alive when the end condition of the final approach is met, then the projectile will revert to normal Smart projectile behaviour. This usually means homing in on the target and hitting it.
Sometimes it's fine to just let your approaches run from start to finish in the order you specify. Other times, you will want to reuse some approaches to set up a "pattern" of behaviour for your projectile. An example would be a "drone" type projectile that orbits the target, occasionally turning towards the target to strafe it with guns or missiles, and then returning to orbit it again. You may want to run this multiple times and Restart is the key to that.
This tells the approach what to do if the end condition is met before the start condition. For example, your approach uses DistanceToPositionC, where PositionC is the enemy target, as a start condition and EnemyTargetLoss as an end condition. If the target is destroyed and there are no more targets for the projectile then the start condition cannot be met. Then end condition can, however, be met and so RestartCondition tells the approach what to do next. The options for RestartCondition are as follows:
Wait: The default setting, this will pause the approaches.
MoveToPrevious: Go back to the approach before this one. Be careful not to get into an endlessly cycling loop.
MoveToNext: The most commononly used option, this will simply move on to the next approach.
ForceRestart: This option allows you to jump around your approach list depending on how you set up the RestartList. It's like a GOTO command.
This is where you tell the approach where to GOTO when it reaches its end condition.
RestartList = new[] { },
This is the definition for the restart "destinations", i.e. which approach you want to GOTO from here. You will have one of these in each approach.
new WeightedIdListDef { },
This is the definition for each "GOTO destination". What's inside this definition will define which approach you will jump to, how many times, and how often. the options to set inside the wrapper are as follows:
ApproachId: The number of the approach that you want to to jump to when restart is triggered. Remember that your first approach is number 0. A value of -1 here will disable this definition.
MaxRuns: How many times you want the approach in ApproachId to be "jumped to".
Weight= Random(X, Y): Think of this as a set of dice. All the definitions inside RestartList roll a number between X and Y whenever the restart is triggered. Whichever definition rolls the highest number, that is the ApproachId that will be jumped to.
EndWeightMod: This is a way of assigning importance to each of the three end conditions within this specific definition. If you're only using one end condition then you can leave this set to 0. If you're using two or three end conditions, however, you can use these weightings to tell the definition which of the end conditions is more important for this particular definition. If two or more end conditions are met then you can use these weightings in different definitions to assign different approaches to jump to depending on which end condition was met.
Because you have two start and three end conditions available to use, you will need to tell your approach how to decide whether it has in fact started or ended. You can use a variety of AND and OR operators; these work exactly as it sounds
CanExpireOnceStarted: The default is false which means the approach will run as specified until an end condition is met. If set to true, the approach can end without and end condition being met.
ForceRestart: If set to true, this makes the approach activate the RestartCondition as soon as the end conditions are met, even if no start conditions were met. The approach will then check what is specified in RestartCondition and take action accordingly. Set this to true to activate the RestartList and jump to another approach that may not necessarily be the next one in the sequence. If you have MoveToNext set in RestartCondition then typically you would set this to false.
You have two Start and three End conditions, so a total of five conditions, available to control when an approach will start and when it will end. Any of the available options may be used in any of the start or end conditions but never use the same condition for more than one start or more than one end condition in the same approach.
At this point it may be helpful to understand what the three basic positions are in approaches:
PositionA: This is the current position of your projectile, so in essence your projectile is always at PositionA.
PositionB: This is the point your projectile was at when the approach started.
PositionC: This is the point that your projectile is aiming for; it could be the physical target grid but it could also be a point in space.
What the approach mechanics attempt to do is guide your projectiles from PositionB to PositionC; taking into account the various variables that you will specify later on in the approach.
The options for start and end are as follows:
-
Ignore: Use this to effectively disable a start or end condition. Obviously don't use Ignore for all five conditions because then the approach will never run.
-
DistanceFromPositionC: This is a <= condition, which means it will trigger when the projectile is less than or equal to the specified distance from PositionC.
-
DistanceToPositionC: This is a >= condition, which means it will trigger when the projectile is greater than or equal to the specified distance from PositionC.
-
DistanceFromPositionB: This is a <= condition, which means it will trigger when the projectile is less than or equal to the specified distance from PositionB.
-
DistanceToPositionB: This is a >= condition, which means it will trigger when the projectile is greater than or equal to the specified distance from PositionB.
-
DistanceFromTarget: This is a <= condition, which means it will trigger when the projectile is less than or equal to the specified distance from the physical target.
-
DistanceToTarget: This is a >= condition, which means it will trigger when the projectile is greater than or equal to the specified distance from the physical target.
-
DistanceFromEndTrajectory: This is a <= condition, measured from the current position of the projectile to the current position of the original target entity
-
DistanceToEndTrajectory: This is a >= condition, measured from the current position of the projectile to the current position of the original target entity
-
Lifetime: This is a >= condition, which means it will trigger when the projectile has been alive for a total time greater than or equal to the number specified (this is in game ticks, not seconds). MaxLifeTime specified in Trajectory is used for this option.
-
DeadTime: This is a <= condition, which means it will trigger when the projectile has less a lifetime left that is less than or equal to the number specified (this is in game ticks, not seconds). MaxLifeTime specified in Trajectory is used for this option.
-
MinTravelRequired: This is a >= condition, which means it will trigger when the projectile has travelled a distance, in this approach alone, greater than or equal to the specified distance (in metres).
-
MaxTravelRequired: This is a <= condition, which means it will trigger when the projectile has travelled a distance, in this approach alone, less than or equal to the specified distance (in metres).
-
Spawn: Triggers when the projectile spawns. If using a multi-stage vehicle then this can be used per stage spawn, not just at the initial shooting point.
-
DesiredElevation: This condition will trigger when the projectile has reached the specified elevation relative to the elevation reference specified later on in the approach.
-
NextTimedSpawn: This is a <= condition, which means it will trigger when the projectile's next timed fragment spawn is due to happen in a time less than or equal to the time specified (this is in game ticks, not seconds).
-
SinceTimedSpawn: This is a >= condition, which means it will trigger when the projectile's last timed fragment spawn happened in a time greater than or equal to the time specified (this is in game ticks, not seconds). Useful for checking out of ammo.
-
RelativeLifetime: This is a >= condition, which means it will trigger when the projectile has been in this approach for a time greater than or equal to the time specified (this is in game ticks, not seconds).
-
RelativeDeadTime: NEEDS EXPLANATION
-
RelativeSpawns: This is a >= condition, which means it will trigger when the projectile has spawned a number of timed fragment spawns greater than or equal to the specified number.
-
EnemyTargetLoss: This is a >= condition, which means it will trigger when the projectile has had no target for a time greater than or equal to the time specified (this is in game ticks, not seconds).
-
RelativeHealthLost: This is a >= condition, which means it will trigger when the projectile has taken damage greater than or equal to the specified number. The Health specified at the start of the ammo definition is used for this condition.
-
HealthRemaining: This is a <= condition, which means it will trigger when the projectile has health less than or equal to the specified number. The Health specified at the start of the ammo definition is used for this condition.
These conditions may be used in many different combinations, in conjunction with Operators, as options in the following variables:
StartCondition1 StartCondition2 EndCondition1 EndCondition2 EndCondition3
Once the conditions have been set, values need to be assigned to each one so that the approach can decide when conditions are met. All distance values are in metres and all time values are in game ticks (60 ticks per second). Values are entered into:
Start1Value Start2Value End1Value End2Value End3Value
There are two special events in each approach that can be used. They are:
StartEvent: A trigger when the approach starts.
EndEvent: A trigger when the approach ends.
A number of different special actions can be assigned to each of these events as follows:
-
DoNothing: Does nothing; this is the default.
-
EndProjectile: Despawns the projectile; does not trigger end of life AOE.
-
EndProjectileOnRestart: Despawns the projectile if Restart is triggered.
-
StorePositionA: Stores the current position of the projectile.
-
StorePositionB: Stores the position the projectile was at when the approach started.
-
StorePositionC: Stores the position the projectile was at when the approach ended.
-
Refund: Refunds heat to the weapon (reduces weapon heat) by the amount specified in HeatRefund and / or refunds a reload if MaxReloads is specified in the weapon.cs file.
It makes sense to use StorePositionB with StartEvent and StorePositionC with EndEvent.
When flying an approach, the projectile needs to know which way is up, which way is forward and where to measure elevation from. This is less important in space but still needs to be specified.
Forward is specified as follows:
- ForwardElevationDirection: Forward is defined relative to the elevation reference.
- ForwardRelativeToBlock: The forward direction of the block the projectile originated from. This is not updated if the block position changes.
- ForwardRelativeToShooter: The forward direction of the block the projectile originated from. This is updated if the block position changes.
- ForwardRelativeToGravity: The pull of gravity (if any) defines the forward direction. Will not work in artificial gravity.
- ForwardTargetDirection: The direction the target is travelling defines forward. This could be constantly changing and may therefore produce odd results.
- ForwardTargetVelocity: The velocity of the target defines forward. This could be constantly changing and may therefore produce odd results.
- ForwardStoredStartPosition: If a start position was saved at StartEvent then forward can be oriented to it. This position is absolute and will not update if the launcher's position changes.
- ForwardStoredEndPosition: If an end position was saved at EndEvent then forward can be oriented to it. This position is absolute and will not update if the launcher's position changes.
- ForwardStoredStartLocalPosition: If a local start position was saved at StartEvent then forward can be oriented to it. This position is relative and will update if the launcher's position changes.
- ForwardStoredEndLocalPosition: If a local end position was saved at EndEvent then forward can be oriented to it. This position is relative and will update if the launcher's position changes.
- ForwardOriginDirection: Orients forward to whatever the forward direction was at the time of the projectile's origin (may be different if multi-stage is used).
Up is speciified in much the same way:
- UpRelativeToBlock: The up direction of the block the projectile originated from. This is not updated if the block position changes.
- UpRelativeToShooter: The up direction of the block the projectile originated from. This is updated if the block position changes.
- UpRelativeToGravity: The pull of gravity (if any) defines the up direction. Will not work in artificial gravity.
- UpTargetDirection: The direction the target is travelling defines up. This could be constantly changing and may therefore produce odd results.
- UpTargetVelocity: The velocity of the target defines forward. This could be constantly changing and may therefore produce odd results.
- UpStoredStartPosition: If a start position was saved at StartEvent then up can be oriented to it. This position is absolute and will not update if the launcher's position changes.
- UpStoredEndPosition: If an end position was saved at EndEvent then up can be oriented to it. This position is absolute and will not update if the launcher's position changes.
- UpStoredStartLocalPosition: If a local start position was saved at StartEvent then up can be oriented to it. This position is relative and will update if the launcher's position changes.
- UpStoredEndLocalPosition: If a local end position was saved at EndEvent then up can be oriented to it. This position is relative and will update if the launcher's position changes.
- UpOriginDirection: Orients up to whatever the up direction was at the time of the projectile's origin (may be different if multi-stage is used).
- UpElevationDirection: Up is defined relative to the elevation reference.
PositionB, PositionC and Elevation can all be specified using the same set of options as follows:
- Origin: Where the projectile originated from. If using multi-stage projectiles this may not be the shooter block.
- Shooter: The actual weapon that fired the projectile. This position is updated if the shooter moves.
- Target: The actual physical grid target.
- Surface: Typically the surface of a planet.
- MidPoint: A point half way between PositionB and PositionC.
- PositionA: The projectile's current position.
- Nothing: Don't use any reference. Elevation should be set to this in space.
- StoredStartPosition: The position stored at the start of the approach by StartEvent. This position is absolute and will not update if the launcher's position changes.
- StoredEndPosition: The position stored at the end of the approach by EndEvent. This position is absolute and will not update if the launcher's position changes.
- StoredStartLocalPosition: The local position stored at the start of the approach by StartEvent. This position is relative and will update if the launcher's position changes.
- StoredEndLocalPosition: The local position stored at the end of the approach by EndEvent. This position is relative and will update if the launcher's position changes.
There are a number of variables that can be configured to adjust the reference points during an approach.
AdjustForward: Whether to adjust the forward direction during the approach.
AdjustUp: Whether to adjust the up direction during the approach.
AdjustPositionB: Whether to adjust the approach's start position over time.
AdjustPositionC: Whether to adjust the approach's end position over time.
LeadRotateElevatePositionB: Will change PositionB by adding lead distance, rotation and elevation to it.
LeadRotateElevatePositionC: Will change PositionC by adding lead distance, rotation and elevation to it.
TrajectoryRelativeToB: Temporarily change the projectile's trajectory to be relative to PositionB if A is closer to B than C.
ElevationRelativeToC: Temporarily change the projectile's elevation to be relative to PositionC if A is closer to C than B.
These options will allow you to alter the behaviour of the projectile on a per-approach basis as follows:
AngleOffset: This will change the up and forward directions for this approach. A one time only adjustment between 0 and 1. Start by using small values such as 0.2 as large values can have unpredictable results, especially when orbiting.
AngleVariance: Set a random variance for the AngleOffset; again start with small values such as 0.1 and adjust as necessary.
ElevationTolerance: If elevation is set as a start or end condition, then this number will increase the margin around the elevation where the approach will consider the condition met.
TrackingDistance: How far the projectile will travel before turning to fly from PositionB to PositionC.
DesiredElevation: How far above the specified elevation reference you want your projectile to fly duing this approach.
Each approach is capable of storing two positions. One can be stored at the start and one can be stored at the end. While the most obvious use case may seem like storing start and end positions, there are other options that are available as well. These stored positions can then be accessed by any other approach and this section is used to specify that as follows:
StoredStartId: Which approach did you store a position using StartEvent. Remember, the first approach is 0 (zero).
StoredEndId: Which approach did you store a position using EndEvent.
StoredStartType: What type of position was stored at StartEvent. This uses the same list of values as PositionB / PositionC / Elevation and could be fixed position or a local position which will update.
StoredEndType: What type of position was stored at EndEvent, using the same list as StoredStartType.
LeadDistance: This will alter PositionC by the specified number of metres in the forward direction.
PushLeadByTravelDistance: As the projectile travels, the lead point will move further proportional to the distance travelled.
This section allows you to modify the speed and acceleration values of the projectile on a per-approach basis. This is very useful when constructing "drones" or terminal stages.
AccelMulti: Multiply your projectile's acceleration by this value. Values smaller than 1 will decrease acceleration.
DeAccelMulti: Multiply your projectile's deacceleration by this value. Values smaller than 1 will decrease acceleration.
TotalAccelMulti: Multiply your projectile's total acceleration by this value. Values smaller than 1 will decrease acceleration.
SpeedCapMulti: Multiply your projectile's speed by this value. Values smaller than 1 will decrease speed.
Any changes to acceleration will also have the effect of changing the turning characteristics of your projectile.
Here you can tell the projectile to orbit PositionC at a given distance. That distance can be varied "randomly" using offsets. Be careful making the offsets too large as this could have unintended side effects, especially if the orbit radius is small.
Orbit: A simple boolean to instruct the projectile to orbit PositionC.
OrbitRadius: How far away from PositionC to orbit.
OffsetMinRadius: The minimum amount to offset the orbit by.
OffsetMaxRadius: The maximum amount to offset the orbit by.
OffsetTime: How often to change the orbit offset.
Here are the miscellaneous settings that don't really fit anywhere else but can have a big impact on your projectile's performance.
NoTimedSpawns: If your projectile used timed fragment spawns, for example a "drone" with guns, then you can set this to false to tell it not to shoot in this approach, or true if you want it to shoot.
DisableAvoidance: If you want the projectile to stop actively trying to avoid the target or home grid. Useful for recovery and docking of "drones", otherwise leave as false.
IgnoreAntiSmart: If true, will make your projectile ignore countremeasures that would otherwise attempt to change your projectile's target. Again, for simulating piloted fighter craft you can set this to true.
HeatRefund: How much heat to refund (subtract) from the firing weapon if Refund was specified in StartEvent or EndEvent.
ReloadRefund: If Refund was specified in StartEvent or EndEvent, then use this boolean to subtract one reload from the running reload counter. Related to MaxReload in the weapon.cs file.
ToggleIngoreVoxels: Swap the IgnoreVoxels value set earlier in the ammo defintion. If it was set to true, then setting this to true as well will make IgnoreVoxels false for this approach only.
SelfAvoidance: Setting this to true will make the projectile try its best to not fly into its parent grid. Set to false for recovery and docking procedures.
TargetAvoidance: Setting this to true will make the projectile actively avoid flying into the target. Again, set to false for recovery and docking procedures.
SelfPhasing: If set to true, the projectile will phase through the parent grid. Use this whenever you like but consider the realism aspect; best used on launch and docking of "fighter craft" or "drones".
SwapNavigationType: Switches between ProNav and ZeroEffort depending on what was set in Smarts -> AltNavigation. Generally you should use ProNav but some precise maneuvers like launch and docking may benefit from ZeroEffort.
These work exactly the same as the default particle for the projectile that you will specify further down in the ammo definition. What these do, however, is allow you to change that default particle on a per-approach basis. This means that you could specify different exhaust colors / sizes for different approaches. For example, a missile could have a long smoke filled exhaust plume at launch and then a smaller, hotter exhaust plume in a later approach stage.
StartParticle is a further option for customising your projectile. This is a particle that will spawn when the approach begins. A use case for this could be the separation of a rocket's second stage from its first stage. In addition to a different exhaust plume you could also specify a quick "explosion" type particle to further embellish the splitting of the two stages.
AlternateModel: Allows you to specify a different MWM model for use in this stage. A good example of this would be a "fighter craft" that has fired its missiles and is returning home. A model with empty underwing pylons could be used for this and subsequent approaches. It's the little details that count.
AlternateSound: This could be a different travel sound to use for this stage, or even a once off "shot" sound for a short stage like booster separation.
ModelRotateTime: This is a time, in game ticks, during the which the model will visually rotate to face the target. This does not change the trajectory of the projectile, only its visual orientation. Using this, you can set up satrfing maneuvers while orbiting a ship for example. If you set it to 0 then no rotation will take place. If you set it to 1, the projectile will instantly snap to face the target. This can look a little jarring so a value of around 30 - 60 is recommended, depending on the size of the projectile and the effect you're trying to achieve. If you have two successive approaches that both require the projectile to face the target, then the second approach should have a ModelRotateTime that is smaller than the first one. That way, the approach considers that the second turn to target has already been achieved and will not try to turn it again. Once the approaches with positive ModelRotateTime(s) are complete the model will turn back to point in its original direction. It will do so using the longest time specified when turning towards the target in previous approaches.
If you have suggestions or implementations, please raise them in the Discord! Thank you!
Please donate to DarkStar's Patreon!
