SetPlayerWeapon: Difference between revisions
Jump to navigation
Jump to search
Document upcoming 0.1.4 weapon confirmation and mouse camera APIs |
Release 0.1.4 BUILD133 / Protocol 36 and document authenticated event origin |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
= setPlayerWeapon = | = setPlayerWeapon = | ||
'''Updated behavior since 0.1.4. This is an existing server function; the confirmation behavior below requires the matching 0.1.4 client and server. The current public release is 0.1.4 / Protocol 36.''' | |||
Requests a native weapon equipment change for a player. Melee and ranged slots are independent; equipping one does not request clearing the other. | |||
== Syntax == | == Syntax == | ||
| Line 14: | Line 15: | ||
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier. | | <code>playerId</code> || <code>int</code> || yes || The connected player identifier. | ||
|- | |- | ||
| <code>itemKey</code> || <code>string</code> || yes || A key | | <code>itemKey</code> || <code>string</code> || yes || A supported weapon key from [[getPlayerWeaponNames]] or [[getPlayerRangedWeaponNames]], or <code>"none"</code> to request clearing both weapon slots. | ||
|} | |} | ||
== Returns == | == Returns == | ||
In 0.1.4, <code>true</code> means the request was accepted for processing, not that the weapon is already equipped or its model displayed. <code>false</code> means the request was not accepted. Await [[onPlayerWeaponChangeResult]] and inspect [[getPlayerWeaponState]] for native confirmation. | |||
== Examples == | == Examples == | ||
=== | === Equip an owned bow === | ||
<syntaxhighlight lang="lua"> | |||
<syntaxhighlight lang="lua" | -- The player must own the item and satisfy its native requirements. | ||
setPlayerWeapon(playerId, "bow_small_01") | |||
</syntaxhighlight> | </syntaxhighlight> | ||
=== | === Clear both equipped weapons === | ||
<syntaxhighlight lang="lua"> | |||
<syntaxhighlight lang="lua" | -- Remove both equipped weapons without deleting owned inventory items. | ||
setPlayerWeapon(playerId, "none") | setPlayerWeapon(playerId, "none") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
These are independent examples; wait for the result before sequencing dependent equipment changes. A newer conflicting request supersedes the older pending request. | |||
== Notes == | == Notes == | ||
* Available only in server-side resource scripts. | * Available only in server-side resource scripts. | ||
* | * Ownership and native equipment requirements apply. This function does not grant items/ammunition, increase stats, draw the weapon or change armor/identity. | ||
* The | * A request for the already equipped item is idempotent. | ||
* Clearing requires a settled idle character with weapons sheathed and no active interaction. Confirmed clear includes native inventory and carry-visual cleanup. | |||
* The updated server commits confirmed empty equipment to replication and late-join state. This is not a continuing lock: subsequent manual equipment changes remain allowed. | |||
* Queue acceptance is not completion. Failure/timeout does not prove that no native change occurred; read current state before retrying. | |||
* [[getPlayerWeapon]] is a legacy single server-side key, not a confirmed two-slot loadout. | |||
See [[Weapon control]] for lifecycle, confirmation fields and failure handling. | |||
[[Category:Lua Functions]] | [[Category:Lua Functions]] | ||
[[Category:Server Functions]] | [[Category:Server Functions]] | ||
| Line 45: | Line 49: | ||
[[Category:Inventory Functions]] | [[Category:Inventory Functions]] | ||
[[Category:Equipment Functions]] | [[Category:Equipment Functions]] | ||
Latest revision as of 20:41, 21 September 2026
setPlayerWeapon
Updated behavior since 0.1.4. This is an existing server function; the confirmation behavior below requires the matching 0.1.4 client and server. The current public release is 0.1.4 / Protocol 36.
Requests a native weapon equipment change for a player. Melee and ranged slots are independent; equipping one does not request clearing the other.
Syntax
bool setPlayerWeapon(int playerId, string itemKey)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
playerId |
int |
yes | The connected player identifier. |
itemKey |
string |
yes | A supported weapon key from getPlayerWeaponNames or getPlayerRangedWeaponNames, or "none" to request clearing both weapon slots.
|
Returns
In 0.1.4, true means the request was accepted for processing, not that the weapon is already equipped or its model displayed. false means the request was not accepted. Await onPlayerWeaponChangeResult and inspect getPlayerWeaponState for native confirmation.
Examples
Equip an owned bow
-- The player must own the item and satisfy its native requirements.
setPlayerWeapon(playerId, "bow_small_01")
Clear both equipped weapons
-- Remove both equipped weapons without deleting owned inventory items.
setPlayerWeapon(playerId, "none")
These are independent examples; wait for the result before sequencing dependent equipment changes. A newer conflicting request supersedes the older pending request.
Notes
- Available only in server-side resource scripts.
- Ownership and native equipment requirements apply. This function does not grant items/ammunition, increase stats, draw the weapon or change armor/identity.
- A request for the already equipped item is idempotent.
- Clearing requires a settled idle character with weapons sheathed and no active interaction. Confirmed clear includes native inventory and carry-visual cleanup.
- The updated server commits confirmed empty equipment to replication and late-join state. This is not a continuing lock: subsequent manual equipment changes remain allowed.
- Queue acceptance is not completion. Failure/timeout does not prove that no native change occurred; read current state before retrying.
- getPlayerWeapon is a legacy single server-side key, not a confirmed two-slot loadout.
See Weapon control for lifecycle, confirmation fields and failure handling.