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.

Available from 0.1.9. Use matching updated server and clients.

Registered custom keys

This existing API also accepts the canonical item string from registerKeyDefinition in 0.1.9. Server registration, active definition and appropriate presentation readiness are required for mutations; use isPlayerKeyDefinitionReady. Do not pass the donor model alias as the custom item identity. Existing call shapes and limits remain; spawnItem creates one world item per call, whereas give/remove counts can manage copies. See Custom keys for safe server-side issuance, drop, pickup and persistence.