ItemsGround

The server keeps the list of the items lying on the ground - the global table ItemsGround, each item an ItemGround. Every player sees the items near them as the game's own items: they look, burn (torches) and are picked up like the game's items, in the same place for everyone (client scripts read them with the client-side ItemsGround).

How it worksKopiuj link do sekcji

• A player throws or drops an item (drops it from the inventory, throws a torch away, or grabs a winch with a torch in hand) - the item goes on the list and onPlayerDropItem is called; cancelEvent() gives it back to the player. The other players near it see it fly and land.
• A player picks an item up - onPlayerTakeItem is called and the item leaves the list. The first player wins: a pick that comes too late (or that a handler cancelled with cancelEvent()) is undone in that player's game - the item leaves their inventory again (a cancelled one lies on the ground again).
• Scripts create items (ItemsGround.create), move them, change their amount and remove them; the players near them see it at once.
• Streaming - a player has the items within the <streaming radius> of config.xml, like characters; walking away and back brings them again.
• The list lives until the server stops; items do not disappear by themselves. At most <groundItems limit> (config.xml, default 5000) lie on the ground at once - a drop over the limit is refused and the item stays in the player's inventory.
• Items placed in the map by the game itself (plants, ore, loot lying in the world) are not on the list.

-- no throwing ore away, and the server console tells who took what
addEventHandler("onPlayerDropItem", function(pid, item)
  if item.instance == "ItMi_Orenugget" then
    sendMessage(pid, 0xFF8080, "Ore cannot be thrown away here.")
    cancelEvent()
  end
end)

addEventHandler("onPlayerTakeItem", function(pid, item)
  print(getPlayerName(pid) .. " took " .. item.instance .. " x" .. item.amount)
end)

Fields of ItemGroundKopiuj link do sekcji

In the examples below item is any ItemGround.

The object stays usable after the item was picked up or destroyed - then its fields are nil and isValid() returns false. Two objects of the same item are equal (==). Its fields can be read, not set (use the methods):

ItemsGroundKopiuj link do sekcji

The global table: put items on the ground, find them, remove them.

createKopiuj link do sekcji

ItemsGround.create(item)

Puts an item on the ground. It appears for every player near it at once, exactly at the given place (it does not fall - give a position on the ground, e.g. a player's position from getPlayerPosition lowered to their feet).

registerCommand("gold", function(pid, args)
  local x, y, z = getPlayerPosition(pid)
  ItemsGround.create({ instance = "ItMi_Orenugget", amount = tonumber(args) or 10, x = x, y = y, z = z - 90 })
end)

Returns: ItemGround | nil - The new item, or nil when <groundItems limit> is reached.

getByIdKopiuj link do sekcji

ItemsGround.getById(id)

Returns the item with this number.

Returns: ItemGround | nil - nil when no such item lies on the ground.

destroyKopiuj link do sekcji

ItemsGround.destroy(id)

Removes an item from the ground (for every player). Same as item:destroy().

Returns: boolean - false when no such item lies on the ground.

getAllKopiuj link do sekcji

ItemsGround.getAll()

Returns every item lying on the ground, in the order they were put there.

Returns: ItemGround[]

getNearKopiuj link do sekcji

ItemsGround.getNear(x, y, z, radius)

Returns the items within radius of a place, the nearest first.

registerCommand("cleanup", function(pid)
  local x, y, z = getPlayerPosition(pid)
  for _, item in ipairs(ItemsGround.getNear(x, y, z, 1000)) do item:destroy() end
end)

Returns: ItemGround[]

ItemGroundKopiuj link do sekcji

One item on the ground (item below): its place, amount and removal. Objects come from ItemsGround and from the events onPlayerDropItem / onPlayerTakeItem.

getPositionKopiuj link do sekcji

item:getPosition()

Returns the position of the item. A thrown item has its landing place once the thrower's game reported it (a moment after the throw); until then the place it was thrown from.

Returns:

setPositionKopiuj link do sekcji

item:setPosition(x, y, z)

Moves the item; every player near it sees it there at once (it does not fall - put it on the ground).

Returns: boolean - false when the item is gone.

getRotationKopiuj link do sekcji

item:getRotation()

Returns the rotation of the item.

Returns:

setRotationKopiuj link do sekcji

item:setRotation(pitch, yaw, roll)

Turns the item.

Returns: boolean - false when the item is gone.

setAmountKopiuj link do sekcji

item:setAmount(amount)

Changes how many pieces lie there (the player who picks it up gets this many).

Returns: boolean - false when the item is gone.

isValidKopiuj link do sekcji

item:isValid()

Tells whether the item still lies on the ground.

Returns: boolean - false after it was picked up or destroyed.

destroyKopiuj link do sekcji

item:destroy()

Removes the item from the ground (for every player). Same as ItemsGround.destroy(item.id).

Returns: boolean - false when it was already gone.

TypesKopiuj link do sekcji

ItemGroundSpecKopiuj link do sekcji

The table given to ItemsGround.create.