Generic event handler template/entity

[Metadorius]

Description

Currently there is a lot of cases both in vanilla game, in existing and proposed features that can be described as "when X occurs, do Y". Each of the cases is usually implemented in it's own specific way, often not sharing common improvements with other cases even if it's beneficial. This proposal aims to solve that by introducing a new universal "event handler" type or a multitag construct (template, like Promotable), inspired by event pattern (can be observed in C#, for example).

For a vanilla example - think of DeathWeapon, but instead of a weapon you could choose an anim, or customize the consequence so that the weapon is fired on whoever killed it by specifying who owns the detonated weapon, etc.

Attaching a draft below.

INI code

; Variant 1, separate entity
[EventHandlerTypes]
0=SOMEHANDLER

[SOMEHANDLER]  ; EventHandlerType
Weapon=        ; WeaponType that will be fired when the event occurs
Warhead=       ; WarheadType that will be fired when the event occurs
Anim=          ; AnimType that will be created when the event occurs
Owner=         ; cause|victim, who will own the weapon/anim
Source=        ; cause|victim, where will the weapon fire from
Target=        ; cause|victim, where will the weapon/anim will go/spawn on

[SOMETECHNO]        ; TechnoType
; Killed is an example event, can be substituted with any other event name, for example TookDamage
Killed=SOMEHANDLER  ; array of EventHandlerTypes



; Variant 2, inline template
[SOMETECHNO]
; Killed is an example event, can be substituted with any other event name, for example TookDamage
Killed.Weapon=   ; WeaponType that will be fired when the event occurs
Killed.Warhead=  ; WarheadType that will be fired when the event occurs
Killed.Anim=     ; AnimType that will be created when the event occurs
Killed.Owner=    ; cause|victim, who will own the weapon/anim
Killed.Source=   ; cause|victim, where will the weapon fire from
Killed.Target=   ; cause|victim, where will the weapon/anim will go/spawn on

Additional context

Considerations and questions to iterate on:

• Variable conditions - what if there's someone else other than cause and victim? What if there's no cause or no victim?
• So far I've only considered Technos as the "actors", what should we do with another things, like Bullets or maybe Objects?

Checklist

• The suggestion is NOT related to functionality of Ares, HAres, Kratos or any other YR engine extension.
• The suggested feature / enhancement is NOT implemented in Ares/Phobos yet and the existing possibilites are not viable or good enough to achieve the wanted result.
• I agree to elaborate the details if requested and provide thorough testing if the feature is implemented.
• I added a very descriptive title to this topic.
• I used the GitHub search and read the topic list to find a similar topic and didn't find it.
• I thought out how the feature / enhancement should work and described it in the most detailed and clear way.

[Metadorius]

Tagging related PRs #1440 #1428 #1381 #1371 #1346

@Aephiex @chaserli @Starkku @ZivDero @Coronia @FS-21 and others, what do you think?

[Metadorius]

@CrimRecya @TaranDahl too

[Aephiex]

That one looks good, but some events might need some specific customization, that merging them into a template might make it look somewhat confusing.

1. My WhenCrush= has different multiplier vs. different victim archetypes, but if that is added to the template it can be confusing, such as WhenCrushed=, since the victim can only be the crushed unit itself there is no need to differ based on the victim's archetype. This can be worked-around by making WhenCrush.Infantries=, WhenCrush.Units=, and WhenCrush.Overlays= three different events.
2. My WhenCrushed= can be supressed by specific WhenCrush.SupressVicitm= settings of the crusher, and that's pretty difficult for a template to handle, unless we make another concept called event supressor?

---

Here are my thoughts.

1. Maybe I will abandon the support of When*.(Damage|Warhead)= and leave only the weapon to make it easier.
2. Maybe we don't need to list the events as game objects, but we can have some hard-coded events like WhenCrush, WhenCrushed, WhenInfiltrate, and WhenKill, and we support custom game events and an InvokeEvent= command on weapons to allow custom events to be triggerd by something custom.
3. The multiplier vs. different objects of the event can be included in the base template, since may events may have a subject and an object, however only having an archetype filter might not be adequate for the pracise, we might need vs. techno multipliers and vs. armor type multipliers. The multiplers can be specified on the weapon, so we don't have to list them on the techno itself.
4. Other stuff such as WhenCrush.Soylent and WhenCrush.SupressVictim, just make them hard-coded for now.

---

Sample code 1:

[RhinoTank]
WhenCrush.Weapon=SelfHeal

[SelfHeal]
WhenCrush.MultiplierWH=SelfHealFilter

[SelfHealFilter]
Verses=50%,50%,50%,100%,100%,100%,0%,0%,0%,0%,0%
Versus.some_custom_armor_type=0%

In this case, when Rhino Tank crushes something, it fires the weapon SelfHeal on itself, which is invoked by a hard-coded event WhenCrush. If SelfHeal is invoked by WhenCrush, it tries to get a multiplier through WhenCrush.MultiplierWH. If it gets 0%, it doesn't fire at all. Otherwise, the damage is multiplied by the percentage it gets.

---

Sample code 2:

[Weapon_NanofiberSync]
InvokeEvents=WhenNanofiberSync

[Knightsframe]
WhenNanofiberSync=TransformIntoKingsframe

[TransformIntoKingsframe]
WhenNanofiberSync.MultiplierWH=<some warhead>

In this case, when the Weapon_NanofiberSync is fired on a Knightsframe, it tries to invoke the event of WhenNanofiberSync on it, which causes the Knightsframe to fire the weapon TransformIntoKingsframe on itself, which converts it into a Kingsframe.
Though you might not need the MultiplierWH in this case, it views the techno who fired the weapon that invoked the event as an object and tries to get a multiplier against it using that warhead, and if it gets 0%, it doesn't transform itself into a Kingsframe.

[Metadorius]

1. My WhenCrush= has different multiplier vs. different victim archetypes, but if that is added to the template it can be confusing, such as WhenCrushed=, since the victim can only be the crushed unit itself there is no need to differ based on the victim's archetype. This can be worked-around by making WhenCrush.Infantries=, WhenCrush.Units=, and WhenCrush.Overlays= three different events.
2. My WhenCrushed= can be supressed by specific WhenCrush.SupressVicitm= settings of the crusher, and that's pretty difficult for a template to handle, unless we make another concept called event supressor?

I think there has to be two concepts, what @Coronia called condition and sequence. Condition is X and is what you're describing more or less, (con)sequence is Y and is what I described as EventHandlerType.

Right now I am proposing to introduce only consequences, with conditions being simplified to the simplest thing - "event happened". @Coronia did an attempt on condition system in #1346, but I am not sure how future-proof that implementation is.

[Aephiex]

In the last sample codes, maybe we still need a list of [EventTypes], so we know the full list to iterate with. Just state in the document which event types are invoked through a hard-coded way.

[Aephiex]

My browser somehow can't reply to comments so I have to leave a new comment here.

Maybe we can make a shortcut by borrowing the multiplier vs. armor type system of warheads, we use that warhead to judge the event relative object to get a multiplier, so we get a [condition] and a [multiplier] at a same time without much cost of coding.

[TaranDahl]

Variable conditions - what if there's someone else other than cause and victim? What if there's no cause or no victim?

我认为可以使用“对象1、对象2、对象3”这样的标签，然后在具体的条件下进行赋予具体的含义。比如在“死亡”这个事件里我们设定“对象1”为死者，“对象2”为杀手，“对象3”没有含义就设定为空。
I think labels like "Object 1, Object 2, Object 3" can be used, and then specific meanings can be assigned under specific conditions. For example, in the event of "death", we set "Object 1" as the victim, "Object 2" as the killer, and since "Object 3" has no meaning, it is set to be nullptr.

So far I've only considered Technos as the "actors", what should we do with another things, like Bullets or maybe Objects?

也许需要包括ObjectClass和CellClass。不过大多数情况下TechnoClass和CellClass是足够的。
Perhaps ObjectClass and CellClass need to be included. However, in most cases, TechnoClass and CellClass are sufficient.

就给出的INI来说，我认为第一种比较好。
For the given INI, I think the first variant is better.