Support arbitrary damage type as the "death type"

[efrec]

Since #1638, we have envDamageTypes for games to define their own damage types as custom weaponDefIDs. This has a lot of crossover with defining death types, which game code can interpret already via weaponDefID.

Currently, though a game can add CullingStrike:

envTypes.CullingStrike = envTypes.KilledByLua - 1

And knows how to listen to one, it's unclear how to cause one.

There are a couple of ways we might try, both with issues:

• Spring.DestroyUnit hardcodes a single damage type.

  RecoilEngine/rts/Lua/LuaSyncedCtrl.cpp

  Line 1986 in 9b4be36

  unit->ForcedKillUnit(attacker, selfDestr, reclaimed, -CSolidObject::DAMAGE_KILLED_LUA);

• Spring.AddUnitDamage takes any negative weaponDefID but passes reclaimed = false, so can't be used for a reclaimed/atomized death type.

  RecoilEngine/rts/Sim/Units/Unit.cpp

  Line 1373 in 9b4be36

  KillUnit(attacker, false, false, weaponDefID);

  We also have to be careful that the damage event goes through and the amount is lethal.

So the ask is to add a params table to Spring.DestroyUnit like so:

Spring.DestroyUnit(unitID, {
    reclaimed   = true,
    weaponDefID = Game.envDamageTypes.Reclaimed,
})

And possibly allow more clear keys like noDeathExplosion and noWreck etc for the keys.

Maybe related to #2772, killing factories with ForcedKillUnit skips CFactory::KillUnit, for some discussion on whether the engine or the game holds these behaviors consistent (or some mix).

[sprunk]

Adding some way for a weaponDefID to end up in UnitDestroyed via a callout sounds good.

I am unsure about it specifically being Spring.DestroyUnit(unitID, {table}) though, that would be an overload and these are annoying to work with. There aren't also necessarily that many args beyond what exists to warrant it.

On clear keys: right now the reclaimed arg has little to do with reclaim itself, it means "no wreck and no explosion" and the connection is mostly that reclaim also kills units like that. Being able to control wreck and explosion directly would be nice, yes.

How about this?

• add Spring.SetUnitDead(unitID, bool = true, weaponDefID = KILLED_BY_LUA) to set the internal "dead" flag, with no wreck, no explosion, and no death animation (equivalent to reclaimed = true in DestroyUnit) and just the UnitDestroyed callin.
• if a game wants the unit to drop a wreck, it can call the already-existing Spring.CreateUnitWreck(unitID, ...) which also gives neat control over a bunch of the wreck's traits.
• if a game wants the unit to explode, it can call Spring.SpawnExplosion which also lets it control the explosion in detail.
• if a game wants to run the "dying" animation it can call it via Spring.UnitScript.CallAsUnit(unitID, killedFunc) for LUS or Spring.CallCOBScript("Killed") for COB.

[efrec]

The new callout would work. The only reason to overload DestroyUnit was to cover adding more params over time, potentially, but moving to a new interface seems more appropriate. Thanks.

I am interested in what bool = false would mean, then. A unit that is dead can revive and pass back through some callin?

[sprunk]

Initially bool = false would just result in an error but yes, perhaps reviving "dead"-but-not-wrecked units could become a thing if it turns out there aren't actually any invariants (and I don't think there are from the engine, existing Lua wupgetry is a different story though).

This is also so far an initial pitch for the "let's add a bunch of primitive functions, rather than a single monster function with a bunch of magic args" approach, I didn't think that much about it so further details (e.g. how to get rid of a "dead" unit afterwards) would still need to be worked out and problems foreseen.

[sprunk]

If by the time you run into really needing it and it's still not done the fancy way above, then the lazy option of just cramming weaponDefID at the end of Spring.DestroyUnit is also alright.