feat: scripted unit xp upgrades

[efrec]

This is step one toward creating new veterancies at rank-up, rather than continuously at each XP gain, by scripting the new wanted effects and adding a measure of support for unit script behaviors. GDD

1. Game-side experience bonuses. Replace engine XP with game XP. Make it tweakable and (chiefly) easy to balance test before/after. Minimize balance impact.
2. Game-side rank bonuses. Replace continuous XP with upgrades on rank-up. This has a large balance component.
3. Unify unit attribute modifiers. We will have codified sources for each modifier, tied to each rank and effect, so can track concrete effects in unit_attributes instead of handling them dynamically (as continuous XP would require us to do).

Work done

• Replaces engine XP bonuses with game-side bonuses. This is reversible via modoption (veterancy_upgrades = 0) to allow for balance A/B tests without jumping versions.
• Adds scaling for autoheal and damage on XP gain.
• Adds scaling for script-based weapon reload timers on XP gain.
• Rework the GUI displays for scaling unit stats.

As part of the above:

• The Whistler and Lasher gain reload time reduction from XP. Previously, this did not work.
• Other units with a restore_delay equal to their maximum reload time may need script changes similar to Whistler/Lasher.

Future considerations

There are a lot of TODOs throughout the unit_veterancy_upgrades file. Surfacing a few here:

• We cannot script unit power from Lua.
• We need to review unit scripts for animation timers based on the max reload time.
• Weapon-less weapondefs (submunitions e.g. clusters) are not scaled in the damages veterancy.
• Impulse and cratering scale with damage in the damages veterancy. Maybe unwanted.
• Very few weapons scale their vfx with damage for the damages veterancy to be visible to players.
• The range veterancy upgrade does not compensate with increases to TTL, projectile speed, etc.
• We cannot modify: predictSpeedMod, leadLimit, targetMoveError, movingAccuracy, wobble. This limits what we can do in the acc_weight veterancy.

Testing

Heatrays and the Beamer can gain +damage% instead of -reload%, which works well. There are other units with a constant rate of fire, also, like Razorbacks that could gain a similar bonus.

Damage increase is an interesting tradeoff with reload time decrease:

This is performant (too optimized for the need) and will be even lighter when upgrades are changed to be on rank-up. Here's a thousand units firing heat rays at each other:

[github-actions]

Integration Test Results

15 tests  ±0   7 ✅ ±0   3s ⏱️ ±0s
 1 suites ±0   8 💤 ±0 
 1 files   ±0   0 ❌ ±0 

Results for commit 4394276. ± Comparison against base commit ddff6cd.

♻️ This comment has been updated with latest results.

[efrec]

UI changes for +damage% alongside -reload%:

[efrec]

In addition to game-side XP upgrade, we may want to track unit XP ourselves. That depends on what we want out of the finished veterancy system.

We currently use engine-default XP. So:

• We don't gate XP gains behind line of sight, radar, etc.
• We don't cap the XP gains from a single shot.
• We don't grant XP for last-hitting on kills (and we track "kills" in a couple ways that disagree across the repo).
• We don't ignore damage to neutral units.
• We do ignore overkill damage, damage to units in death anims (assumed to be overkill), (non-paralysis) damage to crashing aircraft, and collision and crushing damages.
• We use the engine's power->xp ratio (0.1 * powerUnit/powerAttacker).
• +health% from unit XP decreases the XP gain rate of the unit's attackers.
• More quirks besides.

Which can produce odd results:

• Blind-firing over a hill produces battle-hardened Tremors.
• Shooting a newbie Tremor produces more XP than the veteran ones.
• High-range units and high-burst units gain high XP.
• At the same time, a Tick hits max rank in just a few shots on an AFUS.

Though these are mostly minor effects.

[efrec]

I added test scaling options, reload_then_burst and reload_then_damage, to handle cases where reload time < burst duration after XP gains.

Without this, the Razorback's 0.6s reload can't gain the full XP bonus (-50% ish) because its burst duration is 0.4s. With it, damage can continue to scale with XP:

[burnhamrobertp]

This (and FireWeapon2 below) calls ScriptReload without a weapon number, and ScriptReload only seems to sleep for weapon 1 or 2 - so wouldn't it skip both and not wait when nothing's passed? armsam passes the number, so I'm guessing cormist just didn't get the same change. The ResetAiming() up in AimWeapon1 looks like it might be the same thing.

[burnhamrobertp]

From what I can tell these only get set once the unit earns XP (through the SetReloadTime/SetMaxReloadTime calls) - so wouldn't a freshly built unit have them at 0 and end up sleeping for 0 in ScriptReload/ResetAiming/RestoreAfterDelay until its first XP? Might be worth setting them in Create()? (cormist too.)

[efrec]

Not sure how this will resolve, with #7961 handling attributes being sent to scripts, but veterancies needing it also.

[burnhamrobertp]

This value looks like it's stored per-unit but gets written once for each weapon, so wouldn't whichever weapon is last be the one that sticks? Probably fine for plain damages since every weapon scales the same, but reload_then_damages looks like it can give each weapon a different amount - and the stats panels seem to read this one value for all of them, so I'd expect them to show the wrong number for every weapon except the last.

[efrec]

True, these will need unique handling per-weapon. Will do.

The gui for handling these stats is in bad shape. I might have been hoping that the contradictions in it become so strong that we have no choice but to start replacing it.

[efrec]

Yeah no possibility to keep a lot of the gui code. I won't have time for that during daylight-hours, will address it.

[burnhamrobertp]

This runs before the check below that can remove the gadget - so if nothing ends up using veterancy, wouldn't the gadget pull itself out after it's already changed the game-wide XP setting? Might be better after that check (matches your "why in a gadget" note).

[efrec]

I wanted to make the setting independent. Experience grading is a general behavior that shouldn't depend on this gadget. It doesn't really belong in the file at all, then, but there was no good existing place for it.

I did not know if we would create a gadget for game-side XP tracking, either. If we do, then that is an okay place. It is still odd to include any game configuration in any gadget file imo.

[burnhamrobertp]

Edge case I think I'm seeing: if a unit turns on damage scaling but leaves reload scaling at 0, would a weapon whose reload is longer than its burst actually get the damage bump? The part that raises damage looks like it only runs once the reload's been pulled down to the burst length, which doesn't seem possible with reload scaling off - and the config still seems to get accepted, so it might just quietly do nothing.

[efrec]

Maybe a downgrade path for reload_then_xyz => xyz would be good for this. I don't mind saying "Configure it correctly" to our unit designers but modders will want something that is more robust.