SetPlayerWeapon - Revision history

QCherry: Release 0.1.4 BUILD133 / Protocol 36 and document authenticated event origin

2026-09-21T20:41:05Z

Release 0.1.4 BUILD133 / Protocol 36 and document authenticated event origin

← Older revision		Revision as of 20:41, 21 September 2026
Line 1:		Line 1:
	= 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.'''		'''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.		Requests a native weapon equipment change for a player. Melee and ranged slots are independent; equipping one does not request clearing the other.

QCherry: Clarify 0.1.4 weapon clearing, manual equipment and confirmation APIs

2026-09-20T13:42:06Z

Clarify 0.1.4 weapon clearing, manual equipment and confirmation APIs

← Older revision		Revision as of 13:42, 20 September 2026
Line 1:		Line 1:
	~~<!-- This page is generated automatically from the function definition: setPlayerWeapon. -->~~
	= setPlayerWeapon =		= setPlayerWeapon =
	~~Equips or clears~~ a player~~'s authoritative weapon slot~~.		'''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 ==		== 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 ~~returned by <code>~~getPlayerWeaponNames~~</code>~~, or <code>"none"</code> to ~~clear the slot~~.		\| <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 ==
	~~Returns~~ <code>true</code> ~~when~~ the ~~equipment change~~ is ~~accepted and replicated; otherwise returns~~ <code>false</code>.		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 ==
	=== ~~Example 1~~ ===		=== Equip an owned bow ===
	~~Give an item and equip it in the weapon slot:~~		<syntaxhighlight lang="lua">
	<syntaxhighlight lang="lua" ~~line~~>		-- The player must own the item and satisfy its native requirements.
	~~local itemKey = "1h_sword_01"~~		setPlayerWeapon(playerId, "bow_small_01")
	~~if givePlayerItem(playerId, itemKey) then~~
	setPlayerWeapon(playerId, ~~itemKey~~)
	~~end~~
	</syntaxhighlight>		</syntaxhighlight>
	=== ~~Example 2~~ ===		=== Clear both equipped weapons ===
	~~Clear the weapon slot:~~		<syntaxhighlight lang="lua">
	<syntaxhighlight lang="lua" ~~line~~>		-- 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.
	* ~~The player must own at least one copy of~~ a ~~non~~-~~empty item before it can be equipped~~.		* Ownership and native equipment requirements apply. This function does not grant items/ammunition, increase stats, draw the weapon or change armor/identity.
	* The ~~selected appearance is reliably synchronized~~ and ~~included in~~ late-join state.		* 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]]

	~~<!-- weapon-mouse014:start -->~~
	~~== Native confirmation since 0.1.4 (in development) ==~~
	See [[Weapon control]]. setPlayerWeapon returns request acceptance, not completion. getPlayerWeapon remains the legacy single scripted choice, not the actual two-slot loadout. Use [[getPlayerWeaponState]] and [[onPlayerWeaponChangeResult]] for confirmed equipment. Matching client and server are required.
	~~<!-- weapon-mouse014:end -->~~

QCherry: Document upcoming 0.1.4 weapon confirmation and mouse camera APIs

2026-09-19T13:53:57Z

Document upcoming 0.1.4 weapon confirmation and mouse camera APIs

← Older revision		Revision as of 13:53, 19 September 2026
Line 45:		Line 45:
	[[Category:Inventory Functions]]		[[Category:Inventory Functions]]
	[[Category:Equipment Functions]]		[[Category:Equipment Functions]]

			<!-- weapon-mouse014:start -->
			== Native confirmation since 0.1.4 (in development) ==
			See [[Weapon control]]. setPlayerWeapon returns request acceptance, not completion. getPlayerWeapon remains the legacy single scripted choice, not the actual two-slot loadout. Use [[getPlayerWeaponState]] and [[onPlayerWeaponChangeResult]] for confirmed equipment. Matching client and server are required.
			<!-- weapon-mouse014:end -->

QCherry: Complete Lua function catalog

2026-08-15T09:55:39Z

Complete Lua function catalog

← Older revision		Revision as of 09:55, 15 August 2026
Line 40:		Line 40:
	* The selected appearance is reliably synchronized and included in late-join state.		* The selected appearance is reliably synchronized and included in late-join state.

			[[Category:Lua Functions]]
	[[Category:Server Functions]]		[[Category:Server Functions]]
	[[Category:Player Functions]]		[[Category:Player Functions]]
	[[Category:Inventory Functions]]		[[Category:Inventory Functions]]
	[[Category:Equipment Functions]]		[[Category:Equipment Functions]]

QCherry: Automatyczna aktualizacja dokumentacji funkcji

2026-08-05T20:14:04Z

Automatyczna aktualizacja dokumentacji funkcji

New page

= setPlayerWeapon =
Equips or clears a player's authoritative weapon slot.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerWeapon(int playerId, string itemKey)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>itemKey</code> || <code>string</code> || yes || A key returned by <code>getPlayerWeaponNames</code>, or <code>"none"</code> to clear the slot.
|}

== Returns ==
Returns <code>true</code> when the equipment change is accepted and replicated; otherwise returns <code>false</code>.

== Examples ==
=== Example 1 ===
Give an item and equip it in the weapon slot:
<syntaxhighlight lang="lua" line>
local itemKey = "1h_sword_01"
if givePlayerItem(playerId, itemKey) then
setPlayerWeapon(playerId, itemKey)
end
</syntaxhighlight>
=== Example 2 ===
Clear the weapon slot:
<syntaxhighlight lang="lua" line>
setPlayerWeapon(playerId, "none")
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The player must own at least one copy of a non-empty item before it can be equipped.
* The selected appearance is reliably synchronized and included in late-join state.

[[Category:Server Functions]]
[[Category:Player Functions]]
[[Category:Inventory Functions]]
[[Category:Equipment Functions]]