OnPlayerConsumableUse: Difference between revisions

From Wiki G1R-MP G1 Remake Multiplayer
Jump to navigation Jump to search

QCherry (talk | contribs)

3 user groups
887 edits
Update Lua event reference
 
Correct legacy consumable callback documentation
 
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]]

Latest revision as of 14:06, 8 September 2026

onPlayerConsumableUse

LEGACY NAME — NOT EMITTED BY THE PRODUCTION SERVER
This page previously described a callback that is not connected to the production consumable pipeline. Do not register new code for onPlayerConsumableUse.

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.

Replacement from update 0.1.3

Use the callback that matches the information your server resource needs:

The last three callbacks are transaction infrastructure owned by the bundled gothic_rp resource. Other resources may observe them, but must not remove inventory, apply progression values, or attempt to acknowledge the transaction.

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.

Retrieved from "https://g1r-mp.com/wiki/index.php?title=OnPlayerConsumableUse&oldid=790"