QCherry: Correct legacy consumable callback documentation

2026-09-08T14:06:47Z

Correct legacy consumable callback documentation

← Older revision		Revision as of 14:06, 8 September 2026
Line 1:		Line 1:
	~~<!-- This page is generated from the verified Lua event definition: onPlayerConsumableUse. -->~~
	= onPlayerConsumableUse =		= onPlayerConsumableUse =
	~~Triggered after~~ the ~~server accepts or rejects a~~ consumable~~-use request~~.		<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;">LEGACY NAME — NOT EMITTED BY THE PRODUCTION SERVER</div>
			<div style="color:#111111; margin-top:0.25rem;">This page previously described a callback that is not connected to the production consumable pipeline. Do not register new code for <code>onPlayerConsumableUse</code>.</div>
			</div>

	~~== Availability ==~~		The old signature covered only a legacy mana-result payload and did not represent food, health restoration, periodic effects, or the current two-stage durable inventory transaction.
	~~This event is available in '''server~~-~~side''' scripts~~.

	== ~~Callback signature~~ ==		== Replacement from update 0.1.3 ==
	~~<syntaxhighlight lang="lua">~~		Use the callback that matches the information your server resource needs:
	~~onPlayerConsumableUse(playerId, itemId, sequence, accepted, rejectReason, quantityRemaining, mana, maxMana, appliedRestore)~~
	~~</syntaxhighlight>~~

	~~== Parameters ==~~		* [[onPlayerConsumableDurablySettled]] — the primary read-only success callback after inventory and the final authoritative snapshot are durable.
	~~{\| class="wikitable"~~		* [[onPlayerConsumableEffectTick]] — each successfully applied, non-zero health or mana tick from a periodic consumable.
	~~! Name !! Type !! Description~~		* [[onPlayerConsumableCommitRequested]] — advanced stage-one persistence lifecycle notification.
	\|-		* [[onPlayerConsumableFinalizeRequested]] — advanced final-snapshot persistence lifecycle notification.
	~~\| <code>playerId</code> \|\| <code>int</code> \|\| The player using~~ the ~~consumable.~~		* [[onPlayerConsumableDetachedSnapshot]] — advanced disconnect-recovery lifecycle notification.
	\|-
	~~\| <code>itemId</code> \|\| <code>int</code> \|\| The consumable item ID.~~
	\|-
	~~\| <code>sequence</code> \|\| <code>int</code> \|\| The client request sequence.~~
	\|-
	~~\| <code>accepted</code> \|\| <code>bool</code> \|\| Whether~~ the ~~server accepted the use~~.
	\|-
	~~\| <code>rejectReason</code> \|\| <code>int</code> \|\| The rejection reason code,~~ or ~~zero when accepted.~~
	\|-
	~~\| <code>quantityRemaining</code> \|\| <code>int</code> \|\| Authoritative quantity remaining~~.
	\|-
	~~\| <code>mana</code> \|\| <code>number</code> \|\| Authoritative mana after the request~~.
	\|-
	~~\| <code>maxMana</code> \|\| <code>number</code> \|\| The player's maximum mana~~.
	\|-
	~~\| <code>appliedRestore</code> \|\| <code>number</code> \|\| The amount of mana actually restored~~.
	\|}

	~~== Examples ==~~		The last three callbacks are transaction infrastructure owned by the bundled <code>gothic_rp</code> resource. Other resources may observe them, but must not remove inventory, apply progression values, or attempt to acknowledge the transaction.
	~~Handle~~ the ~~event:~~
	<~~syntaxhighlight lang="lua" line~~>
	~~addEventHandler("onPlayerConsumableUse"~~, ~~root~~, ~~function(playerId~~, ~~itemId, sequence, accepted, rejectReason, quantityRemaining, mana, maxMana, appliedRestore)~~
	~~if accepted then~~
	~~outputChatBox("Restored "~~ .~~. appliedRestore .. " mana.", playerId, 100, 160, 255)~~
	~~end~~
	~~end)~~
	~~</syntaxhighlight>~~

	~~== Notes ==~~		There is no one-to-one server-side rejection callback under the legacy name. Pre-validation rejection and the client-visible result remain part of the authoritative native protocol rather than this Lua event.
	* This event observes authoritative inventory and ~~mana changes; do not remove~~ the ~~item again~~.

	[[Category:Lua Events]]		[[Category:Lua Events]]
	[[Category:~~Server Events]]~~		[[Category:Deprecated API]]
	~~[[Category:Magic Events~~]]

QCherry: Update Lua event reference

2026-08-14T22:31:36Z

Update Lua event reference

New page

= onPlayerConsumableUse =
Triggered after the server accepts or rejects a consumable-use request.

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

== Callback signature ==
<syntaxhighlight lang="lua">
onPlayerConsumableUse(playerId, itemId, sequence, accepted, rejectReason, quantityRemaining, mana, maxMana, appliedRestore)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Description
|-
| <code>playerId</code> || <code>int</code> || The player using the consumable.
|-
| <code>itemId</code> || <code>int</code> || The consumable item ID.
|-
| <code>sequence</code> || <code>int</code> || The client request sequence.
|-
| <code>accepted</code> || <code>bool</code> || Whether the server accepted the use.
|-
| <code>rejectReason</code> || <code>int</code> || The rejection reason code, or zero when accepted.
|-
| <code>quantityRemaining</code> || <code>int</code> || Authoritative quantity remaining.
|-
| <code>mana</code> || <code>number</code> || Authoritative mana after the request.
|-
| <code>maxMana</code> || <code>number</code> || The player's maximum mana.
|-
| <code>appliedRestore</code> || <code>number</code> || The amount of mana actually restored.
|}

== Examples ==
Handle the event:
<syntaxhighlight lang="lua" line>
addEventHandler("onPlayerConsumableUse", root, function(playerId, itemId, sequence, accepted, rejectReason, quantityRemaining, mana, maxMana, appliedRestore)
if accepted then
outputChatBox("Restored " .. appliedRestore .. " mana.", playerId, 100, 160, 255)
end
end)
</syntaxhighlight>

== Notes ==
* This event observes authoritative inventory and mana changes; do not remove the item again.

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

OnPlayerConsumableUse - Revision history

QCherry: Correct legacy consumable callback documentation

QCherry: Update Lua event reference