GivePlayerItem: Difference between revisions
Document upcoming 0.1.9 custom native keys, shared doors, server Lua callbacks and persistence; not a release |
Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits |
||
| Line 41: | Line 41: | ||
<!-- customkeys019:start --> | <!-- customkeys019:start --> | ||
'''Available from 0.1.9 | '''Available from 0.1.9. Use matching updated server and clients.''' | ||
== Registered custom keys == | == Registered custom keys == | ||
This existing API also accepts the canonical item string from [[registerKeyDefinition]] in | This existing API also accepts the canonical item string from [[registerKeyDefinition]] in 0.1.9. Server registration, active definition and appropriate presentation readiness are required for mutations; use [[isPlayerKeyDefinitionReady]]. Do not pass the donor model alias as the custom item identity. Existing call shapes and limits remain; [[spawnItem]] creates one world item per call, whereas give/remove counts can manage copies. See [[Custom keys]] for safe server-side issuance, drop, pickup and persistence. | ||
<!-- customkeys019:end --> | <!-- customkeys019:end --> | ||
Latest revision as of 13:28, 20 October 2026
givePlayerItem
Adds a known item to a player's authoritative inventory.
Syntax
bool givePlayerItem(int playerId, string itemKey [, int quantity = 1])
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
playerId |
int |
yes | The connected player identifier. |
itemKey |
string |
yes | A rune, armor, or melee weapon key from the server catalog. |
quantity |
int |
no | Number of items to add, from 1 to 1000; defaults to 1. |
Returns
Returns true when the inventory change is validated, replicated, and applied by the server; otherwise returns false.
Examples
Give a player one sword and equip it:
if givePlayerItem(playerId, "1h_sword_01") then
setPlayerWeapon(playerId, "1h_sword_01")
end
Notes
- Available only in server-side resource scripts.
- Preferred descriptive inventory function.
- The resulting total may not be negative or exceed 100000 items.
Available from 0.1.9. Use matching updated server and clients.
Registered custom keys
This existing API also accepts the canonical item string from registerKeyDefinition in 0.1.9. Server registration, active definition and appropriate presentation readiness are required for mutations; use isPlayerKeyDefinitionReady. Do not pass the donor model alias as the custom item identity. Existing call shapes and limits remain; spawnItem creates one world item per call, whereas give/remove counts can manage copies. See Custom keys for safe server-side issuance, drop, pickup and persistence.