[engine]: New [event] battle names (DONE, available here)

[WhiteWolf]

Hi,

The idea has been made available for UMC authors. Scroll to the bottom of the post.

I think it could prove useful to append the list of predefined event names with a new way to describe fights.
We currently have: attack,attack end,attacker hits,defender hits,attacker misses,defender misses.
These can describe all attack events an author needs, but they all share a common feature: the attacker and defender roles define the primary and secondary filters. This is a very good thing to have, but in some but not rare cases it overcomplicates things in my opinion.

For instance: Let's say I want to do something (labeled <...>) every time an ambusher unit hits someone. Regardless of being attacker, or being attacked. (One could say: regardless of which side's turn it is).
Currently the code to do this is:

Current way:

Code: Select all

[event]
    name=attacker hits
    first_time_only=no
    [filter]
        ability=ambusher
    [/filter]

    <...>
[/event]
[event]
    name=defender hits
    [filter_second]
        ability=ambusher
    [/filter_second]

    <...>
[/event]

This is obviously long, and not pretty way to do it. My problem is, we need TWO [event]s to carry out ONE action. Sure it can be done by including <...> into a custom event and with the attacker/defender hits events we could fire it. I'm not saying it can't be done/solved/worked around. But it is still more complex than it should be, and it could discourage beginner coders.

What I'm proposing is not essential, it could only come in handy a couple of times.
The name=combat attribute should act the same way the name=attack does, except that the attacker and defender roles should not be cast. Example:

Code: Select all

[event]
    name=combat
    first_time_only=no
    [filter]
        type=Skeleton
    [/filter]

    [message]
          speaker=unit
          message= _ "I've just engaged the enemy!"
    [/message]
[/event]

This code will make any skeleton say the message, regardless of being attacked or being the attacker.

The secondary filter is completely optional at any time.
If a secondary filter is provided, then the behaviour should be that the event only fires at the fight of two units described in the filters. In this sense, [filter] and [filter_second] should be absolutely commutable, since attacker and defender roles have no meaning on them.

Example with given secondary filter:

Code: Select all

[event]
    name=combat
    first_time_only=no
    [filter]
        type=Skeleton
    [/filter]
    [filter]
        race=human
    [/filter]

    # If I switch up the filters, and replace speaker=unit with speaker=second_unit, I get the SAME RESULT.
    [message]
          speaker=unit
          message= _ "I've just engaged a human being!"
    [/message]
[/event]

The combat event could be extended to describe any part of the fight, just like attack does:

1. combat: Triggers when the units described in the filters engage each other.

• combat end: Similar to combat, but triggers after the fight, not before. Triggers before die events.

• combatant hits: Triggers when the unit described in the primary filter delivers a hit onto its enemy. (If the enemy is specified with [filter_second], the event only fires if the primary unit engages AND hits the unit in the secondary filter). Note that this fires regardless of who's attacking who, only the hit is what matters.

• combatant misses: Triggers when the unit described in the primary filter misses.

To support my point in having these, we already have an event which behaves exactly like these, but only when a unit is killed. It's called 'die', or 'last breath'.

Code: Select all

[event]
    name=die
    first_time_only=no
    [filter_second]
        type=Spearman
    [/filter_second]
[/event]

This fires every times a Spearman kills someone, regardless of it being done in offense or defense.

So why not have events with this same behaviour, but not for a kill, simply just for a fight?


EDIT 1:
If you are an UMC author and would like to use the combating events, download this file:

events.cfg

(4.46 KiB) Downloaded 259 times

Include it into your work as a util. If you want to use combating events in a scenario, include {ENABLE_COMBAT_EVENTS} into the scenario toplevel tag. Then you're free to go. Enjoy

Example:

Code: Select all

[scenario]
    id=my_scenario
    stuff
    {ENABLE_COMBAT_EVENTS}

    [event]
         name=combat # <- this now works as expected.
    [/event]
[/scenario]

Note on behaviour:

Note that 'combat' and 'combat end' carry an unexpected feature. If only the primary [filter] is given, and first_time_only is set to =no, everything inside the event will be played twice per battle.

You can use this a feature if this is what you need, but if you want to trigger the event only once per battle, add {TRIGGER_ONLY_ONCE} somewhere into the event.
Example:

Code: Select all

[event]
     name=combat
     first_time_only=no
     {TRIGGER_ONLY_ONCE}
      [filter]
           race=undead
      [/filter]
   
      # This fires every time an undead unit engages in combat, but plays the inside of the event only once, as expected.
[/event]

[Tad_Carlucci]

Combine the event names in a comma-separated list, and use an [if] instead of filtering when [filter_condition] won't fit the bill. I think everything you're asking can be done in a single filter.

Also, even if you choose to use separate filters to begin the event, using a custom filter for the bulk of the processing should eliminate duplicated code.

[WhiteWolf]

I stated somewhere that I'm aware that every aspect I mentioned as examples can be carried out in several different ways.

I plainly proposed that it may come in handy for some to have a very explicit and short way to write the events in question.

[Tad_Carlucci]

That's fine but the question is: is there anything new?

Simply proposing a name which does what two names do if you combine them in a list is just adding complexity for no real gain. Is there anything which you cannot do currently?

[zookeeper]

I don't recall ever desiring the "combat" event, but the current attacker/defender hits/misses events are really awkward because of the way the primary and secondary units switch places. I'd definitely welcome two general-purpose hits/miss events which simply trigger when the primary unit hits/misses the secondary unit.

[gfgtdf]

I agree that the attacker/defender hits/misses events are really awkward.

If yo want sucha sutom even in 1.12 you can just add code like

Code: Select all

[event]
 name="attacker hits"
 [fire_event]
  name=hits
  [fist_unit]
   x,y =x1,y1
  [/fist_unit]
  [second_unit]
   x,y =x2,y2
  [/second_unit]
 [/fire_event]
[/event]
[event]
 name="defender hits"
 [fire_event]
 name=hits
  [fist_unit]
   x,y =x2,y2
  [/fist_unit]
  [second_unit]
   x,y =x1,y1
  [/second_unit]
 [/fire_event]
[/event]

[WhiteWolf]

In my experience, there can be well-placed arguments both for and against the current behaviour of the defender hits/misses. Sometimes it comes in handy and keeps things consistent. Sometimes, it is really awkward.

Maybe just debate the creation of "name=combatant hits"? I just thought maybe the others could prove useful as well in some cases.

You could really build up something general by setting primary and secondary units inside the fire_event, I had not thought of that. A macro could be made... something like ALLOW_COMBATANT_EVENTS, this could work for UMC authors. But it is still not anything core-defined

I'll try what I can do to define these and I'll upload, see if it does the trick.

EDIT:
This can be done
Here is the code:

New events codes:

Code: Select all

	## NEW COMBATING EVENTS ##

	# Many could argue that the current defender and attacker hits/misses events are awkward. Sometimes they really are.
	# What they are messed up with is that the defender and attacker roles define the primary and secondary filters.
	#
	# These new events DO NOT CARE about who is the attacker and who is the defender.
	# Defined names are:
	# [event] name=combat -> similar to attack
	# [event] name=combat end -> similar to attack end
	# [event] name=combatant hits -> Triggers when the unit in the primary [filter] hits the unit in the [filter_second].
	# [event] name=combatant misses -> Triggers when the unit in the primary [filter] misses its strike at the unit in the [filter_second].
	# Note: [filter_second] is always optional.

	# Note on the behaviour of 'combat' and 'combat end'. If only the primary [filter] is given, and first_time_only is set to =no, the event is prone to an unexpected feature.
	# Example:
	# [event]
	#     name=combat
	#     first_time_only=no
	#     [filter]
	#         race=undead
	#     [/filter]
	#
	#     <...> # This will be carried out twice, each time an undead engages in a fight.
	# [/event]
	# If two Undead units engage each other, this event will trigger TWICE!	This can be kept if this is your will. If you would like the event to fire only once per combat, 
	# then add {TRIGGER_ONLY_ONCE} somewhere into the event, like this:
	# [event]
	#     name=combat
	#     first_time_only=no
	#     [filter]
	#         race=undead
	#     [/filter]
	#     {TRIGGER_ONLY_ONCE}
	#
	#     <...> # This will be carried out only once, each time an undead engages in a fight.
	# [/event]

## Combating event definitions:


#define TRIGGER_ONLY_ONCE
{VARIABLE combating_event_fired yes}
#enddef

#define ENABLE_COMBAT_EVENTS
[event]
	name=attack
	id=combat_attack_event_trigger1
	first_time_only=no

	# Handle with UTMOST CARE. If both units meet the filter of combat (f.e. two Undead fighting, primary filter yielding race=undead), the combat event will fire TWICE.
	# if first_time_only is set to no. If you feel it risky, add {VARIABLE combating_event_fired yes} at the bottom of the event, and all will be OK. This is optional.
	[fire_event]
		name=combat
		[primary_unit]
			x,y=$x1,$y1
		[/primary_unit]
		[secondary_unit]
			x,y=$x2,$y2
		[/secondary_unit]
	[/fire_event]

	[if]
		[variable]
			name=combating_event_fired
			equals=yes
		[/variable]
		[else]
			[fire_event]
				name=combat
				[primary_unit]
					x,y=$x2,$y2
				[/primary_unit]
				[secondary_unit]
					x,y=$x1,$y1
				[/secondary_unit]
			[/fire_event]
		[/else]
	[/if]
	{CLEAR_VARIABLE combating_event_fired}
[/event]
[event]
	name=attack end
	id=combat_attack_end_event_trigger1
	first_time_only=no

	# Handle with UTMOST CARE. If both units meet the filter of combat (f.e. two Undead fighting, primary filter yielding race=undead), the combat event will fire TWICE
	# if first_time_only is set to no. If you feel it risky, add {VARIABLE combating_event_fired yes} at the bottom of the event, and all will be OK. This is optional.
	[fire_event]
		name=combat end
		[primary_unit]
			x,y=$x1,$y1
		[/primary_unit]
		[secondary_unit]
			x,y=$x2,$y2
		[/secondary_unit]
	[/fire_event]

	[if]
		[variable]
			name=combating_event_fired
			equals=yes
		[/variable]
		[else]
			[fire_event]
				name=combat end
				[primary_unit]
					x,y=$x2,$y2
				[/primary_unit]
				[secondary_unit]
					x,y=$x1,$y1
				[/secondary_unit]
			[/fire_event]
		[/else]
	[/if]
	{CLEAR_VARIABLE combating_event_fired}
[/event]

# Hitting
[event]
	name=attacker hits
	id=combat_hit_event_trigger1
	first_time_only=no

	[fire_event]
		name=combatant hits
		[primary_unit]
			x,y=$x1,$y1
		[/primary_unit]
		[secondary_unit]
			x,y=$x2,$y2
		[/secondary_unit]
	[/fire_event]
[/event]
[event]
	name=defender hits
	id=combat_hit_event_trigger2
	first_time_only=no

	[fire_event]
		name=combatant hits
		[primary_unit]
			x,y=$x2,$y2
		[/primary_unit]
		[secondary_unit]
			x,y=$x1,$y1
		[/secondary_unit]
	[/fire_event]
[/event]

# Missing
[event]
	name=attacker misses
	id=combat_miss_event_trigger1
	first_time_only=no

	[fire_event]
		name=combatant misses
		[primary_unit]
			x,y=$x1,$y1
		[/primary_unit]
		[secondary_unit]
			x,y=$x2,$y2
		[/secondary_unit]
	[/fire_event]
[/event]
[event]
	name=defender misses
	id=combat_miss_event_trigger2
	first_time_only=no

	[fire_event]
		name=combatant misses
		[primary_unit]
			x,y=$x2,$y2
		[/primary_unit]
		[secondary_unit]
			x,y=$x1,$y1
		[/secondary_unit]
	[/fire_event]
[/event]

#enddef

Copy the whole thing into an event-utils.cfg, enable with {ENABLE_COMBAT_EVENTS}, and there you have it all. I'll also edit this into the top post.

Still, it could be nice to have this as a core function.