QCherry: Document stable consumable lifecycle callbacks for 0.1.3

2026-09-08T14:06:27Z

Document stable consumable lifecycle callbacks for 0.1.3

New page

= onPlayerConsumableDetachedSnapshot =
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">AVAILABLE FROM UPDATE 0.1.3</div>
<div style="color:#111111; margin-top:0.25rem;">This event is available in G1R:MP 0.1.3 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
</div>

Triggered during disconnect when a consumable operation is still awaiting its durable inventory result, providing both rollback and success snapshots for detached recovery.

== Availability ==
This event is available in '''server-side''' scripts.

== Callback signature ==
<syntaxhighlight lang="lua">
onPlayerConsumableDetachedSnapshot(playerId, itemKey, sequence, commitKey, baseHealth, baseMaxHealth, baseMana, baseMaxMana, baseStrength, baseDexterity, baseAlcohol, baseSwampweed, successHealth, successMaxHealth, successMana, successMaxMana, successStrength, successDexterity, successAlcohol, successSwampweed, appliedHealth, appliedMana)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>playerId</code> || <code>int</code> || The disconnecting player's last authoritative ID.
|-
| <code>itemKey</code> || <code>string</code> || The stable native inventory key of the consumable.
|-
| <code>sequence</code> || <code>int</code> || The positive client request sequence.
|-
| <code>commitKey</code> || <code>string</code> || The opaque durable-operation key.
|-
| <code>baseHealth</code> || <code>number</code> || Health to preserve if stage-one persistence failed.
|-
| <code>baseMaxHealth</code> || <code>number</code> || Maximum health to preserve if stage-one persistence failed.
|-
| <code>baseMana</code> || <code>number</code> || Mana to preserve if stage-one persistence failed.
|-
| <code>baseMaxMana</code> || <code>number</code> || Maximum mana to preserve if stage-one persistence failed.
|-
| <code>baseStrength</code> || <code>number</code> || Strength to preserve if stage-one persistence failed.
|-
| <code>baseDexterity</code> || <code>number</code> || Dexterity to preserve if stage-one persistence failed.
|-
| <code>baseAlcohol</code> || <code>number</code> || Alcohol value to preserve if stage-one persistence failed.
|-
| <code>baseSwampweed</code> || <code>number</code> || Swampweed value to preserve if stage-one persistence failed.
|-
| <code>successHealth</code> || <code>number</code> || Projected health if the reserved item is durably consumed.
|-
| <code>successMaxHealth</code> || <code>number</code> || Projected maximum health after durable success.
|-
| <code>successMana</code> || <code>number</code> || Projected mana after durable success.
|-
| <code>successMaxMana</code> || <code>number</code> || Projected maximum mana after durable success.
|-
| <code>successStrength</code> || <code>number</code> || Projected strength after durable success.
|-
| <code>successDexterity</code> || <code>number</code> || Projected dexterity after durable success.
|-
| <code>successAlcohol</code> || <code>number</code> || Projected alcohol value after durable success.
|-
| <code>successSwampweed</code> || <code>number</code> || Projected swampweed value after durable success.
|-
| <code>appliedHealth</code> || <code>number</code> || Projected instant health change for the success outcome.
|-
| <code>appliedMana</code> || <code>number</code> || Projected instant mana change for the success outcome.
|}

== Examples ==
Handle the event:
<syntaxhighlight lang="lua" line>
addEventHandler("onPlayerConsumableDetachedSnapshot", root, function(playerId, itemKey, sequence, commitKey, baseHealth, baseMaxHealth, baseMana, baseMaxMana, baseStrength, baseDexterity, baseAlcohol, baseSwampweed, successHealth, successMaxHealth, successMana, successMaxMana, successStrength, successDexterity, successAlcohol, successSwampweed, appliedHealth, appliedMana)
outputDebugString("Detached consumable recovery: " .. itemKey .. " #" .. sequence)
end)
</syntaxhighlight>

== Notes ==
* This advanced disconnect-recovery callback is part of the stable server-side Lua contract beginning with update 0.1.3.
* It is emitted only when the player disconnects while stage-one inventory persistence is unresolved. A disconnect during final settlement reuses <code>onPlayerConsumableFinalizeRequested</code> instead.
* The bundled <code>gothic_rp</code> resource selects and persists the correct snapshot after reconciling the durable receipt. Other resources must treat both snapshots as read-only.
* The player session is being removed; do not defer ordinary player getters or assume that the player remains connected after this callback.

[[Category:Lua Events]]
[[Category:Server Events]]
[[Category:Magic Events]]

OnPlayerConsumableDetachedSnapshot - Revision history

QCherry: Document stable consumable lifecycle callbacks for 0.1.3