https://g1r-mp.com/wiki/index.php?action=history&feed=atom&title=Weapon_controlWeapon control - Revision history2026-09-19T15:45:42ZRevision history for this page on the wikiMediaWiki 1.46.0https://g1r-mp.com/wiki/index.php?title=Weapon_control&diff=901&oldid=prevQCherry: Document upcoming 0.1.4 weapon confirmation and mouse camera APIs2026-09-19T13:53:44Z<p>Document upcoming 0.1.4 weapon confirmation and mouse camera APIs</p>
<p><b>New page</b></p><div>= Weapon control =<br />
'''Confirmation APIs and corrected weapon request handling: since 0.1.4 (in development). Public 0.1.3 does not expose these additions. Use the matching client and server.'''<br />
<br />
== Requests versus completed equipment ==<br />
<code>setPlayerWeapon(playerId, itemKey)</code> still returns boolean queue acceptance, not native completion. Melee and ranged slots are independent. A request for the already equipped item is idempotent. <code>"none"</code> requests clearing both slots without deleting inventory. Ownership and native equipment requirements apply; the function does not grant ammunition, bypass stats, draw a weapon or change armor.<br />
<br />
[[getPlayerWeapon]] remains the legacy single scripted choice and is not a complete or confirmed two-slot loadout. Failed requests do not roll back that legacy choice. Use [[getPlayerWeaponState]] and [[onPlayerWeaponChangeResult]] when saving equipment or sequencing changes.<br />
<br />
== Confirmed state ==<br />
<code>getPlayerWeaponState(playerId)</code> returns false if unavailable, otherwise a table:<br />
* <code>supported</code>: the client has sent the new native report.<br />
* <code>known</code>: both native slots could be resolved. Unknown is not an empty slot.<br />
* <code>fresh</code>: a known observation no older than 3 seconds while the character is alive.<br />
* <code>melee</code>, <code>ranged</code>: catalog keys; <code>""</code> means an observed empty slot.<br />
* <code>pending</code>: array of <code>{requestId, itemKey}</code>. Clear requests use <code>"none"</code>.<br />
<br />
The owning resource receives <code>onPlayerWeaponChangeResult(playerId, itemKey, ok, reason, requestId)</code>. Completion checks actual native readback, ownership, request identity, current life revision and deadline. New requests supersede conflicting requests; opposite slots are independent. Result events are not ordinary remotely callable Lua events.<br />
<br />
<syntaxhighlight lang="lua"><br />
addEventHandler("onPlayerWeaponChangeResult", resourceRoot,<br />
function(playerId, itemKey, ok, reason, requestId)<br />
local state = getPlayerWeaponState(playerId)<br />
if ok and state and state.fresh then<br />
-- Persist state.melee and state.ranged in your own database schema.<br />
end<br />
end)<br />
setPlayerWeapon(playerId, "bow_small_01") -- must already be owned<br />
</syntaxhighlight><br />
<br />
== Failure and lifecycle ==<br />
Typical reasons include <code>confirmed</code>, <code>superseded</code>, <code>native-equip-not-allowed</code>, <code>readback-timeout</code>, <code>client-confirmation-timeout</code> and character/life changes. Native work is polled at 20 Hz while pending, with idle observations at 1 Hz. There is no blind replay after a native call. Client timeout is 6 seconds from native queueing; server timeout is 8 seconds from dispatch. Timeout does not prove an in-flight action had no effect: inspect current state before retrying.<br />
<br />
Stopping a resource discards its pending results, preventing old completions from entering a restarted script. An already issued native action may finish; stop is not rollback. Clearing settles one slot at a time without the unsafe bulk UnequipWeapons call. Its native toggle behavior must still pass retail gameplay tests; failure must report failure/timeout, not simulated success.<br />
<br />
== Development test ==<br />
gothic_rp includes <code>/weapontest status</code>, <code>prepare</code>, <code>start</code>, <code>set &lt;key&gt;</code>, <code>restore</code> and <code>stop</code>. Require a spawned/authenticated test character, enabled test tools and <code>admin.players</code> permission. Prepare grants missing test weapons but no stats or ammunition. Start tests a sword, bows, crossbow, repeated equips, clear and two-slot combination. Restore reinstates the original slots recorded by start; granted items remain in inventory.<br />
<br />
Test local rendering, a second client, late join, firing with correct ammo, native requirements, clear/restore, death and resource restart. Automated tests validate policies and Lua contracts, not the full retail gameplay path.<br />
[[Category:Lua API]]</div>QCherry