SpawnItem - Revision history

QCherry: Document spawnItem exact-position and server-owned overloads for G1R:MP 0.1.3

2026-09-08T20:28:14Z

Document spawnItem exact-position and server-owned overloads for G1R:MP 0.1.3

← Older revision		Revision as of 20:28, 8 September 2026
Line 1:		Line 1:
	= spawnItem =		= spawnItem =
	<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">		<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
	<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">~~AVAILABLE~~ FROM UPDATE 0.1.2</div>		<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">IMPROVED FROM UPDATE 0.1.3</div>
	<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.2 and later. The contract below ~~includes~~ the ~~compatibility guarantees introduced in that update~~.</div>		<div style="color:#111111; margin-top:0.25rem;">This function is available in earlier releases and has corrected or expanded behavior in G1R:MP 0.1.3 and later. The contract below describes the updated behavior.</div>
	</div>		</div>

	Spawns an allowlisted synchronized pickup near a player.		Spawns an allowlisted, server-authoritative synchronized pickup near a player or at an exact world position.

	== Syntax ==		== Syntax ==
	<syntaxhighlight lang="lua">		<syntaxhighlight lang="lua">
	bool spawnItem(int playerId, string itemKey [, number heightOffset])		bool spawnItem(int playerId, string itemKey [, number heightOffset])
			bool spawnItem(int playerId, string itemKey, number x, number y, number z [, number yaw [, bool snapToGround]])
			bool spawnItem(string itemKey, number x, number y, number z [, number yaw [, bool snapToGround]])
	</syntaxhighlight>		</syntaxhighlight>

Line 16:		Line 18:
	! Name !! Type !! Required !! Description		! Name !! Type !! Required !! Description
	\|-		\|-
	\| <code>playerId</code> \|\| <code>int</code> \|\| ~~yes~~ \|\| ~~The connected~~ player ~~identifier~~.		\| <code>playerId</code> \|\| <code>int</code> \|\| no \|\| Required by the near-player and player-attributed exact-position overloads. Omit it only for a purely server-owned exact-position spawn.
	\|-		\|-
	\| <code>itemKey</code> \|\| <code>string</code> \|\| yes \|\| A verified public world-item key or inventory key from the server catalog allowlist, for example <code>apple</code> or <code>itfo_apple</code>.		\| <code>itemKey</code> \|\| <code>string</code> \|\| yes \|\| A verified public world-item key or inventory key from the server catalog allowlist, for example <code>apple</code> or <code>itfo_apple</code>.
	\|-		\|-
	\| <code>heightOffset</code> \|\| <code>number</code> \|\| no \|\| Optional finite vertical offset in metres from -100 through 100. Values outside this range are rejected. Omit it to request ground snapping; an explicit 0 keeps the player's snapshot height without ground snapping.		\| <code>heightOffset</code> \|\| <code>number</code> \|\| no \|\| Optional finite vertical offset in metres from -100 through 100. Values outside this range are rejected. Omit it to request ground snapping; an explicit 0 keeps the player's snapshot height without ground snapping.
			\|-
			\| <code>x</code> \|\| <code>number</code> \|\| no \|\| Exact world X coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
			\|-
			\| <code>y</code> \|\| <code>number</code> \|\| no \|\| Exact world Y coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
			\|-
			\| <code>z</code> \|\| <code>number</code> \|\| no \|\| Exact world Z coordinate in metres. The exact-position overload requires <code>x</code>, <code>y</code>, and <code>z</code> together.
			\|-
			\| <code>yaw</code> \|\| <code>number</code> \|\| no \|\| Optional finite world yaw in degrees for an exact-position spawn. Defaults to 0 and is normalized by the authoritative world-item system.
			\|-
			\| <code>snapToGround</code> \|\| <code>bool</code> \|\| no \|\| Whether an exact-position spawn requests ground snapping. Defaults to <code>false</code>.
	\|}		\|}

Line 42:		Line 54:
	spawnItem(playerId, "ItMw_1H_Axe_01")		spawnItem(playerId, "ItMw_1H_Axe_01")
	spawnItem(playerId, "ItAr_Rune_FireBolt")		spawnItem(playerId, "ItAr_Rune_FireBolt")
			</syntaxhighlight>
			=== Example 3 ===
			Spawn at exact positions, either attributed to a connected player or owned only by the server:
			<syntaxhighlight lang="lua" line>
			spawnItem(playerId, "itfo_loaf", 125.5, -42.0, 18.25, 90, true)
			spawnItem("itfo_apple", 125.5, -42.0, 18.25)
			</syntaxhighlight>
			=== Example 4 ===
			Observe only pickups that the server has accepted and already granted:
			<syntaxhighlight lang="lua" line>
			addEventHandler("onWorldItemPickup", root, function(objectId, playerId, itemKey, quantity, serverTimeMs)
			outputDebugString(getPlayerName(playerId) .. " picked up " .. quantity .. "x " .. itemKey)
			end)
	</syntaxhighlight>		</syntaxhighlight>

	== Notes ==		== Notes ==
	* Available only in server-side resource scripts.		* Available only in server-side resource scripts.
	* ~~Each accepted call~~ spawns exactly one item 0.7 metres in front of the player's latest replicated position and facing direction.		* This function was introduced in update 0.1.2. Update 0.1.3 adds the two exact-position overloads without changing the original near-player signature.
			* The legacy overload spawns exactly one item 0.7 metres in front of the connected player's latest replicated position and facing direction.
			* Exact-position <code>x</code>, <code>y</code>, and <code>z</code> inputs use metres. [[onWorldItemSpawn]] exposes the published packet coordinates in Unreal centimetres.
			* The player-attributed exact overload reports that connected player as <code>sourcePlayerId</code>. The server-owned exact overload reports <code>sourcePlayerId = 0</code> and does not require a player snapshot.
	* The update 0.1.2 catalog contains 681 structurally verified world-item entries. Item codes are case-insensitive; the server canonicalizes every accepted value before replication.		* The update 0.1.2 catalog contains 681 structurally verified world-item entries. Item codes are case-insensitive; the server canonicalizes every accepted value before replication.
	* The [https://www.nexusmods.com/gothic1remake/articles/8 Gothic Remake item-code reference] is useful when looking up candidate codes. A code is spawnable only when it also exists in the current server catalog; unsupported codes return <code>false</code>.		* The [https://www.nexusmods.com/gothic1remake/articles/8 Gothic Remake item-code reference] is useful when looking up candidate codes. A code is spawnable only when it also exists in the current server catalog; unsupported codes return <code>false</code>.
	* The server owns the item identity, revision, visibility, pickup validation, inventory award, and late-join state.		* The server owns the item identity, revision, visibility, pickup validation, inventory award, and late-join state.
			* [[onWorldItemPickup]] runs only after an authoritative pickup is accepted, the inventory grant is applied, and the reliable picked-up tombstone removes the item from active late-join state. It is an observation event; do not grant the same item again in its handler.
	* Only entries mapped by the verified world-item catalog may be spawned; arbitrary asset names and paths are rejected.		* Only entries mapped by the verified world-item catalog may be spawned; arbitrary asset names and paths are rejected.

QCherry: Document Lua APIs available or improved from G1R:MP 0.1.2

2026-09-03T18:40:01Z

Document Lua APIs available or improved from G1R:MP 0.1.2

← Older revision		Revision as of 18:40, 3 September 2026
Line 1:		Line 1:
	= spawnItem =		= spawnItem =
	<div style="background:#~~0b0b0b~~; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#~~f1f1f1~~; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">		<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
	<div style="color:#~~ff5a5a~~; font-weight:bold; letter-spacing:0.04em;">~~COMING IN~~ UPDATE 0.1.2</div>		<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">AVAILABLE FROM UPDATE 0.1.2</div>
	<div style="color:#~~f1f1f1~~; margin-top:0.25rem;">This function is ~~documented~~ in ~~advance~~ and ~~is not yet available~~ in ~~the current public release~~.</div>		<div style="color:#111111; margin-top:0.25rem;">This function is available in G1R:MP 0.1.2 and later. The contract below includes the compatibility guarantees introduced in that update.</div>
	</div>		</div>

QCherry: Document Lua functions planned for G1R:MP update 0.1.2

2026-09-02T17:32:57Z

Document Lua functions planned for G1R:MP update 0.1.2

New page

= spawnItem =
<div style="background:#0b0b0b; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#f1f1f1; padding:0.85rem 1rem; margin:0.75rem 0 1rem;">
<div style="color:#ff5a5a; font-weight:bold; letter-spacing:0.04em;">COMING IN UPDATE 0.1.2</div>
<div style="color:#f1f1f1; margin-top:0.25rem;">This function is documented in advance and is not yet available in the current public release.</div>
</div>

Spawns an allowlisted synchronized pickup near a player.

== Syntax ==
<syntaxhighlight lang="lua">
bool spawnItem(int playerId, string itemKey [, number heightOffset])
</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 verified public world-item key or inventory key from the server catalog allowlist, for example <code>apple</code> or <code>itfo_apple</code>.
|-
| <code>heightOffset</code> || <code>number</code> || no || Optional finite vertical offset in metres from -100 through 100. Values outside this range are rejected. Omit it to request ground snapping; an explicit 0 keeps the player's snapshot height without ground snapping.
|}

== Returns ==
Returns <code>true</code> after the server accepts and creates the item; otherwise returns <code>false</code>.

== Examples ==
=== Example 1 ===
Spawn an allowlisted apple near the invoking player:
<syntaxhighlight lang="lua" line>
addCommandHandler("spawnitem", function(playerId)
if not spawnItem(playerId, "itfo_apple") then
outputChatBox("The item could not be spawned.", playerId)
end
end)
</syntaxhighlight>
=== Example 2 ===
Spawn other verified food, weapon, and rune entries:
<syntaxhighlight lang="lua" line>
spawnItem(playerId, "ItFo_Loaf")
spawnItem(playerId, "ItMw_1H_Axe_01")
spawnItem(playerId, "ItAr_Rune_FireBolt")
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Each accepted call spawns exactly one item 0.7 metres in front of the player's latest replicated position and facing direction.
* The update 0.1.2 catalog contains 681 structurally verified world-item entries. Item codes are case-insensitive; the server canonicalizes every accepted value before replication.
* The [https://www.nexusmods.com/gothic1remake/articles/8 Gothic Remake item-code reference] is useful when looking up candidate codes. A code is spawnable only when it also exists in the current server catalog; unsupported codes return <code>false</code>.
* The server owns the item identity, revision, visibility, pickup validation, inventory award, and late-join state.
* Only entries mapped by the verified world-item catalog may be spawned; arbitrary asset names and paths are rejected.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:World Functions]]
[[Category:Inventory Functions]]