[outdated] Improvements to player resurrection

[sirinsidiator]

Before I state my wish I try to describe the current state of the API.

Player resurrection has 2 stages. The active stage where a player has to press a key and shoots his weird beam at another player and the passive stage where the resurrection is pending and the receiving player has to react.

The API currently only has parts of this covered:
When I start resurrecting someone, EVENT_START_SOUL_GEM_RESURRECTION is fired. It does give me a duration, but not who I am resurrecting.
The information about the player can be collected by hooking into TryShowingResurrectLabel on the PLAYER_TO_PLAYER object.

Then we have EVENT_END_SOUL_GEM_RESURRECTION which is fired whenever the beam stops. This can be for a number of reasons, but the event does not provide us with any information about it. There is also no way I know of to get this reason via other means.

Once the resurrection got through the target player can either accept, decline or wait until the timeout occurs. The failure cases are covered by EVENT_RESURRECT_FAILURE which gives a good amount of details (targetChar, reason, targetDisplayName).
There are several reasons for it to fail:

• RESURRECT_FAILURE_REASON_DECLINED -- player pressed decline or timeout occurred
• RESURRECT_FAILURE_REASON_ALREADY_CONSIDERING -- when another player is faster than us
• RESURRECT_FAILURE_REASON_NO_INSTANCE_REVIVE_COUNTERS -- in trials and arena when there is no resurrection left
• RESURRECT_FAILURE_REASON_NO_SOUL_GEM -- when our gem disappears during resurrection (?)
• RESURRECT_FAILURE_REASON_SOUL_GEM_IN_USE -- when we have a pending resurrection on another player

When the player accepts the resurrection we don't get any direct indication that it happened. Only thing we could potentially try is infer that it happened by looking at the soul gem count in EVENT_INVENTORY_SINGLE_SLOT_UPDATE. But that is error prone as the count could change for any reason.

On the receiving end we have no events when the player is getting resurrected, but we could potentially track it via IsUnitBeingResurrected("player") in an update handler. We also don't get any info when it gets interrupted. As soon as the resurrection succeeds we get EVENT_RESURRECT_REQUEST and can access the information about it via GetPendingResurrectInfo. Finally we get EVENT_RESURRECT_REQUEST_REMOVED when we press accept, decline or the timeout happens, but again have no information which of the 3 cases caused the event to fire. It's possible to hook into AcceptResurrect and DeclineResurrect to differentiate them though.

My wish for the wishlist is that we get events and functions that provide us with all the details for each stage on both ends. I would also like to see a new unit group for resurrections (e.g. resurrect1 ... n) that gives us access to players that are resurrecting us or that we are resurrecting. The unit would live from when the resurrection starts to when it is over.

Events:

• EVENT_PLAYER_RESURRECTION_STARTED(*string* _unitTag_, *integer* _timeLeftMs_) -- fires when a player starts resurrecting us or we start to resurrect another player
• EVENT_PLAYER_RESURRECTION_CANCELLED(*string* _unitTag_, *PlayerResurrectionCancelledReason* _reason_) -- fires when the resurrection was cancelled before it was over
• EVENT_PLAYER_RESURRECTION_PENDING(*string* _unitTag_, *integer* _timeLeftToAcceptMs_) -- fires when the resurrection was successful and the receiving player has to react
• EVENT_PLAYER_RESURRECTION_ACCEPTED(*string* _unitTag_) -- fires when the resurrection was accepted by the receiving player
• EVENT_PLAYER_RESURRECTION_FAILED(*string* _unitTag_, *PlayerResurrectionFailedReason* _reason_) -- fires when the resurrection failed after it entered the pending stage

Functions:
More than one player can try to resurrect us, so we need to be able to access them all:

• *integer* _numAttempts_ = GetNumResurrectionAttempts()
• *string* _unitTag_, *integer* _timeLeftMs_ = GetResurrectionAttemptInfo(*luaindex* _index_)

We can give one resurrect at a time and we can also receive one at the same time, so we will need two different functions.

• *string* _unitTag_, *integer* _timeLeftToAcceptMs_ = GetIncomingPendingResurrectInfo()
• *string* _unitTag_, *integer* _timeLeftToAcceptMs_ = GetOutgoingPendingResurrectInfo()

PlayerResurrectionCancelledReason

• PLAYER_RESURRECTION_CANCELLED_REASON_PLAYER
• PLAYER_RESURRECTION_CANCELLED_REASON_INTERRUPTED
• PLAYER_RESURRECTION_CANCELLED_REASON_RESPAWNED
• PLAYER_RESURRECTION_CANCELLED_REASON_DISCONNECTED
• PLAYER_RESURRECTION_CANCELLED_REASON_ALREADY_CONSIDERING
• PLAYER_RESURRECTION_CANCELLED_REASON_NO_SOUL_GEM
• PLAYER_RESURRECTION_CANCELLED_REASON_NO_INSTANCE_REVIVE_COUNTERS
• PLAYER_RESURRECTION_CANCELLED_REASON_SOUL_GEM_IN_USE

PlayerResurrectionFailedReason

• PLAYER_RESURRECTION_FAILED_REASON_DECLINED
• PLAYER_RESURRECTION_FAILED_REASON_TIMEOUT
• PLAYER_RESURRECTION_FAILED_REASON_RESPAWNED
• PLAYER_RESURRECTION_FAILED_REASON_DISCONNECTED

This idealized version is probably not feasible any time soon, but at least an event that provides the missing information about accepted resurrections by other players would be good to have as it is something I would like to use in one of my addons.