SetPlayerWeapon
setPlayerWeapon
Updated behavior since 0.1.4 (in development). This is an existing server function; the confirmation behavior below requires the matching 0.1.4 client and server. Public release remains 0.1.3.
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.