SpawnItem

spawnItem

IMPROVED FROM UPDATE 0.1.3

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.

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

Syntax

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]])

Parameters

Name	Type	Required	Description
playerId	int	no	Required by the near-player and player-attributed exact-position overloads. Omit it only for a purely server-owned exact-position spawn.
itemKey	string	yes	A verified public world-item key or inventory key from the server catalog allowlist, for example apple or itfo_apple.
heightOffset	number	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.
x	number	no	Exact world X coordinate in metres. The exact-position overload requires x, y, and z together.
y	number	no	Exact world Y coordinate in metres. The exact-position overload requires x, y, and z together.
z	number	no	Exact world Z coordinate in metres. The exact-position overload requires x, y, and z together.
yaw	number	no	Optional finite world yaw in degrees for an exact-position spawn. Defaults to 0 and is normalized by the authoritative world-item system.
snapToGround	bool	no	Whether an exact-position spawn requests ground snapping. Defaults to false.

Returns

Returns true after the server accepts and creates the item; otherwise returns false.

Examples

Example 1

Spawn an allowlisted apple near the invoking player:

addCommandHandler("spawnitem", function(playerId)
    if not spawnItem(playerId, "itfo_apple") then
        outputChatBox("The item could not be spawned.", playerId)
    end
end)

Example 2

Spawn other verified food, weapon, and rune entries:

spawnItem(playerId, "ItFo_Loaf")
spawnItem(playerId, "ItMw_1H_Axe_01")
spawnItem(playerId, "ItAr_Rune_FireBolt")

Example 3

Spawn at exact positions, either attributed to a connected player or owned only by the server:

spawnItem(playerId, "itfo_loaf", 125.5, -42.0, 18.25, 90, true)
spawnItem("itfo_apple", 125.5, -42.0, 18.25)

Example 4

Observe only pickups that the server has accepted and already granted:

addEventHandler("onWorldItemPickup", root, function(objectId, playerId, itemKey, quantity, serverTimeMs)
    outputDebugString(getPlayerName(playerId) .. " picked up " .. quantity .. "x " .. itemKey)
end)

Notes

• Available only in server-side resource scripts.
• 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 x, y, and z inputs use metres. onWorldItemSpawn exposes the published packet coordinates in Unreal centimetres.
• The player-attributed exact overload reports that connected player as sourcePlayerId. The server-owned exact overload reports sourcePlayerId = 0 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 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 false.
• 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.