QCherry: Document stable consumable lifecycle callbacks for 0.1.3

2026-09-08T14:06:26Z

Document stable consumable lifecycle callbacks for 0.1.3

New page

= onPlayerConsumableFinalizeRequested =
<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 after the inventory removal is durable and the server has applied the authoritative instant effect, requesting persistence of the final settlement snapshot.

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

== Callback signature ==
<syntaxhighlight lang="lua">
onPlayerConsumableFinalizeRequested(playerId, itemKey, inventoryItemId, sequence, generation, commitKey, quantityRemaining, health, maxHealth, mana, maxMana, strength, dexterity, alcohol, swampweed, appliedHealth, appliedMana, periodicTicks, periodicHealthPerTick, periodicManaPerTick)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>playerId</code> || <code>int</code> || The player using the consumable.
|-
| <code>itemKey</code> || <code>string</code> || The stable native inventory key of the consumable.
|-
| <code>inventoryItemId</code> || <code>int</code> || The native numeric consumable ID.
|-
| <code>sequence</code> || <code>int</code> || The positive client request sequence.
|-
| <code>generation</code> || <code>int</code> || The positive settlement generation; a newer snapshot uses a higher value.
|-
| <code>commitKey</code> || <code>string</code> || The opaque durable-operation key supplied by the commit request.
|-
| <code>quantityRemaining</code> || <code>int</code> || The current authoritative inventory quantity.
|-
| <code>health</code> || <code>number</code> || Canonical health in the settlement snapshot.
|-
| <code>maxHealth</code> || <code>number</code> || Canonical maximum health in the settlement snapshot.
|-
| <code>mana</code> || <code>number</code> || Canonical mana in the settlement snapshot.
|-
| <code>maxMana</code> || <code>number</code> || Canonical maximum mana in the settlement snapshot.
|-
| <code>strength</code> || <code>number</code> || Canonical strength in the settlement snapshot.
|-
| <code>dexterity</code> || <code>number</code> || Canonical dexterity in the settlement snapshot.
|-
| <code>alcohol</code> || <code>number</code> || Canonical alcohol progression value.
|-
| <code>swampweed</code> || <code>number</code> || Canonical swampweed progression value.
|-
| <code>appliedHealth</code> || <code>number</code> || Instant health change applied by this operation.
|-
| <code>appliedMana</code> || <code>number</code> || Instant mana change applied by this operation.
|-
| <code>periodicTicks</code> || <code>int</code> || The number of periodic ticks authored for the item.
|-
| <code>periodicHealthPerTick</code> || <code>number</code> || Authored health change per periodic tick.
|-
| <code>periodicManaPerTick</code> || <code>number</code> || Authored mana change per periodic tick.
|}

== Examples ==
Handle the event:
<syntaxhighlight lang="lua" line>
addEventHandler("onPlayerConsumableFinalizeRequested", root, function(playerId, itemKey, inventoryItemId, sequence, generation, commitKey, quantityRemaining, health, maxHealth, mana, maxMana, strength, dexterity, alcohol, swampweed, appliedHealth, appliedMana, periodicTicks, periodicHealthPerTick, periodicManaPerTick)
outputDebugString("Consumable finalize requested: " .. commitKey .. " generation=" .. generation)
end)
</syntaxhighlight>

== Notes ==
* This advanced durability-lifecycle callback is part of the stable server-side Lua contract beginning with update 0.1.3.
* The bundled <code>gothic_rp</code> resource owns persistence and is the only resource authorized to acknowledge this request with <code>completePlayerConsumableFinalize</code>. Other resources must treat it as read-only.
* The same generation can be delivered again after a persistence failure. A concurrent authoritative progression change can produce a newer generation that supersedes an older snapshot.
* A Lua return value does not complete the operation. Do not reapply the item effect or overwrite progression from an older generation.

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

OnPlayerConsumableFinalizeRequested - Revision history

QCherry: Document stable consumable lifecycle callbacks for 0.1.3