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 worksLink zum Abschnitt kopieren

• 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 ItemGroundLink zum Abschnitt kopieren

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

ItemsGroundLink zum Abschnitt kopieren

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

createLink zum Abschnitt kopieren

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.

getByIdLink zum Abschnitt kopieren

ItemsGround.getById(id)

Returns the item with this number.

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

destroyLink zum Abschnitt kopieren

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.

getAllLink zum Abschnitt kopieren

ItemsGround.getAll()

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

Returns: ItemGround[]

getNearLink zum Abschnitt kopieren

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

ItemGroundLink zum Abschnitt kopieren

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

getPositionLink zum Abschnitt kopieren

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:

setPositionLink zum Abschnitt kopieren

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.

getRotationLink zum Abschnitt kopieren

item:getRotation()

Returns the rotation of the item.

Returns:

setRotationLink zum Abschnitt kopieren

item:setRotation(pitch, yaw, roll)

Turns the item.

Returns: boolean - false when the item is gone.

setAmountLink zum Abschnitt kopieren

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.

isValidLink zum Abschnitt kopieren

item:isValid()

Tells whether the item still lies on the ground.

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

destroyLink zum Abschnitt kopieren

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.

TypesLink zum Abschnitt kopieren

ItemGroundSpecLink zum Abschnitt kopieren

The table given to ItemsGround.create.