[Trigger] What's the difference between TriggerRegister-FilterUnitEvent and -UnitEvent?

[Luashine]

Hi there. See title. Jass/Lua, doesn't matter. The examples will be in Lua, but I would like to know what's the difference or an explanation for this behavior?

sameTrigger = CreateTrigger()
sheep = CreateUnit(Player(0), FourCC"nshe", -256, 0, 270.0)
TriggerRegisterUnitEvent(sameTrigger, sheep, EVENT_UNIT_DEATH) -- returns a new event
TriggerRegisterPlayerUnitEvent(sameTrigger, Player(0), EVENT_PLAYER_UNIT_DEATH, nil) -- returns a new event
TriggerRegisterFilterUnitEvent(sameTrigger, sheep, EVENT_UNIT_DEATH, nil) -- returns nil

Why does UnitEvent work with "EVENT_UNIT_DEATH", but FilterUnitEvent does not and returns null? Both register "EVENT_UNIT_LOADED" just fine.

For reference, the native declarations are:

native TriggerRegisterUnitEvent       takes trigger whichTrigger, unit whichUnit,           unitevent whichEvent                            returns event
native TriggerRegisterPlayerUnitEvent takes trigger whichTrigger, player whichPlayer, playerunitevent whichPlayerUnitEvent, boolexpr filter returns event
native TriggerRegisterFilterUnitEvent takes trigger whichTrigger, unit whichUnit,           unitevent whichEvent,           boolexpr filter returns event

 

[PurgeandFire]

so TriggerRegisterFilterUnitEvent is mostly meant for specific events that involve some "other" unit of interest (acquiring a target, being rescued, etc.). see this note from the common.j:

    //===================================================
    // For use with TriggerRegisterUnitEvent
    //===================================================
    constant unitevent EVENT_UNIT_DAMAGED                               = ConvertUnitEvent(52)
    constant unitevent EVENT_UNIT_DAMAGING                              = ConvertUnitEvent(314)
    constant unitevent EVENT_UNIT_DEATH                                 = ConvertUnitEvent(53)
    constant unitevent EVENT_UNIT_DECAY                                 = ConvertUnitEvent(54)
    constant unitevent EVENT_UNIT_DETECTED                              = ConvertUnitEvent(55)
    constant unitevent EVENT_UNIT_HIDDEN                                = ConvertUnitEvent(56)
    constant unitevent EVENT_UNIT_SELECTED                              = ConvertUnitEvent(57)
    constant unitevent EVENT_UNIT_DESELECTED                            = ConvertUnitEvent(58)
                                                                   
    constant unitevent EVENT_UNIT_STATE_LIMIT                           = ConvertUnitEvent(59)
                                                               
    // Events which may have a filter for the "other unit"         
    //                                                             
    constant unitevent EVENT_UNIT_ACQUIRED_TARGET                       = ConvertUnitEvent(60)
    constant unitevent EVENT_UNIT_TARGET_IN_RANGE                       = ConvertUnitEvent(61)
    constant unitevent EVENT_UNIT_ATTACKED                              = ConvertUnitEvent(62)
    constant unitevent EVENT_UNIT_RESCUED                               = ConvertUnitEvent(63)
                                                                   
    constant unitevent EVENT_UNIT_CONSTRUCT_CANCEL                      = ConvertUnitEvent(64)
    constant unitevent EVENT_UNIT_CONSTRUCT_FINISH                      = ConvertUnitEvent(65)
                                                                   
    constant unitevent EVENT_UNIT_UPGRADE_START                         = ConvertUnitEvent(66)
    constant unitevent EVENT_UNIT_UPGRADE_CANCEL                        = ConvertUnitEvent(67)
    constant unitevent EVENT_UNIT_UPGRADE_FINISH                        = ConvertUnitEvent(68)

from my testing, all the ones listed specifically under // For use with TriggerRegisterUnitEvent only work for TriggerRegisterUnitEvent, the rest should work with both but the provided filter may or may not be executed depending on the type of event.

here are all the details for reference though for all the "Does not work" items, TriggerRegisterFilterUnitEvent will return null.

Event Name	TriggerRegisterUnitEvent	TriggerRegisterFilterUnitEvent	Runs Filter?	Details
EVENT_UNIT_DAMAGED	Works	Does not work	N/A	Runs when a unit is damaged (after damage reduction has been calculated).
EVENT_UNIT_DAMAGING	Works	Does not work	N/A	Runs when a unit is about to take damage (before damage reduction has been calculated).
EVENT_UNIT_DEATH	Works	Does not work	N/A	Runs when a unit dies.
EVENT_UNIT_DECAY	Works	Does not work	N/A	Runs when a unit's corpse starts to decay.
EVENT_UNIT_DETECTED	Unknown	Does not work	N/A	Does not fire.
EVENT_UNIT_HIDDEN	Unknown	Does not work	N/A	Does not fire.
EVENT_UNIT_SELECTED	Works	Does not work	N/A	Runs when a unit is selected by a player.
EVENT_UNIT_DESELECTED	Works	Does not work	N/A	Runs when a unit is deselected by a player.
EVENT_UNIT_STATE_LIMIT	Does not work	Does not work	N/A	This event is just the underlying event ID TriggerRegisterUnitStateEvent. If used with TriggerRegisterUnitEvent, it technically returns a valid event object, but it never fires to my knowledge.
EVENT_UNIT_ACQUIRED_TARGET	Works	Works		Runs when a unit acquires a target (filter unit = acquired target).
EVENT_UNIT_TARGET_IN_RANGE	Works	Works		Runs when a target is now within attack range (filter unit = target to attack).
EVENT_UNIT_ATTACKED	Works	Works		Runs when a unit is attacked (filter unit = attacker).
EVENT_UNIT_RESCUED	Works	Works		Runs when a unit is rescued via rescue range (filter unit = rescuer).
EVENT_UNIT_CONSTRUCT_CANCEL	Works	Works		Runs when construction of a building is cancelled (filter unit = cancelled building).
EVENT_UNIT_CONSTRUCT_FINISH	Works	Works		Runs when construction of a building is completed (filter unit = finished building).
EVENT_UNIT_UPGRADE_START	Works	Works		Runs when a unit starts upgrading to another unit, such as a town hall => keep (filter unit = upgrading unit as the upgraded type, e.g. keep).
EVENT_UNIT_UPGRADE_CANCEL	Works	Works		Runs when a unit cancels an upgrade (filter unit = upgrading unit as the original type, e.g. town hall).
EVENT_UNIT_UPGRADE_FINISH	Works	Works		Runs when a unit finishes an upgrade (filter unit = upgrading unit as the upgraded type, e.g. keep).
EVENT_UNIT_TRAIN_START	Works	Works		Runs when a unit begins training another unit (e.g. when a barracks starts training a footman).
EVENT_UNIT_TRAIN_CANCEL	Works	Works		Runs when a unit cancels training another unit.
EVENT_UNIT_TRAIN_FINISH	Works	Works		Runs when a unit finishes training another unit (filter unit = the unit that was trained, e.g. the footman).
EVENT_UNIT_RESEARCH_START	Works	Works		Runs when a research begins, such as an armor upgrade (filter unit = researching structure).
EVENT_UNIT_RESEARCH_CANCEL	Works	Works		Runs when a research is cancelled (filter unit = researching structure).
EVENT_UNIT_RESEARCH_FINISH	Works	Works		Runs when a research completes (filter unit = researching structure).
EVENT_UNIT_ISSUED_ORDER	Works	Works		Runs when a unit is issued an immediate order with no target.
EVENT_UNIT_ISSUED_POINT_ORDER	Works	Works		Runs when a unit is issued an order targeting a point.
EVENT_UNIT_ISSUED_TARGET_ORDER	Works	Works		Runs when a unit is issued an order targeting a widget.
EVENT_UNIT_HERO_LEVEL	Works	Works		Runs when a hero gains a level (filter unit = the hero).
EVENT_UNIT_HERO_SKILL	Works	Works		Runs when a hero learns a skill (filter unit = the hero).
EVENT_UNIT_HERO_REVIVABLE	Works	Works		Runs when a hero becomes revivable (filter unit = dead hero).
EVENT_UNIT_HERO_REVIVE_START	Works	Works		Runs when a hero revival begins (filter unit = reviving hero).
EVENT_UNIT_HERO_REVIVE_CANCEL	Works	Works		Runs when a hero revival is cancelled (filter unit = hero that was being revived).
EVENT_UNIT_HERO_REVIVE_FINISH	Works	Works		Runs when a hero revival finishes (filter unit = revived hero).
EVENT_UNIT_SUMMON	Works	Works		Runs when a unit summons another unit (filter unit = summoned unit).
EVENT_UNIT_DROP_ITEM	Works	Works		Runs when a unit drops an item (filter unit = the unit dropping the item).
EVENT_UNIT_PICKUP_ITEM	Works	Works		Runs when a unit picks up an item (filter unit = the unit picking up the item).
EVENT_UNIT_USE_ITEM	Works	Works		Runs when a unit uses an item (filter unit = the unit using the item).
EVENT_UNIT_LOADED	Works	Works		Runs when a unit is loaded into a transport (filter unit = loaded unit).