diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 2f92d424..4f7ed512 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -668,7 +668,7 @@ World:ForEachChestInChunk(Player:GetChunkX(), Player:GetChunkZ(), ContentsHeight = { Notes = "Height (Y) of the {{cItemGrid}} representing the contents" }, }, - Inherits = "cBlockEntity"; + Inherits = "cBlockEntityWithItems"; }, cEnchantments = @@ -1040,8 +1040,12 @@ Internally, the class uses three {{cItemGrid|cItemGrid}} objects to store the co
  • Armor
  • Inventory
  • Hotbar
  • -These ItemGrids are available in the API and can be manipulated by the plugins, too. -]], +These ItemGrids are available in the API and can be manipulated by the plugins, too.

    +

    + When using the raw slot access functions, such as GetSlot() and SetSlot(), the slots are numbered + consecutively, each ItemGrid has its offset and count. To future-proff your plugins, use the named + constants instead of hard-coded numbers. + ]], Functions = { AddItem = { Params = "{{cItem|cItem}}, [AllowNewStacks]", Return = "number", Notes = "Adds an item to the storage; if AllowNewStacks is true (default), will also create new stacks in empty slots. Returns the number of items added" }, @@ -1129,6 +1133,15 @@ These ItemGrids are available in the API and can be manipulated by the plugins, }, AdditionalInfo = { + { + Header = "Usage notes", + Contents = [[ + Note that the object contained in a cItem class is quite complex and quite often new Minecraft + versions add more stuff. Therefore it is recommended to copy cItem objects using the + copy-constructor ("local copy = cItem(original);"), this is the only way that guarantees that + the object will be copied at full, even with future versions of MCServer. + ]], + }, { Header = "Example code", Contents = [[ @@ -1164,14 +1177,14 @@ local Item5 = cItem(E_ITEM_DIAMOND_CHESTPLATE, 1, 0, "thorns=1;unbreaking=3"); cItemGrid = { Desc = [[This class represents a 2D array of items. It is used as the underlying storage and API for all cases that use a grid of items: -

  • Chest contents
  • +
  • {{cChestEntity|Chest}} contents
  • (TODO) Chest minecart contents
  • -
  • {{cDispenserEntity|Dispenser|| contents
  • +
  • {{cDispenserEntity|Dispenser}} contents
  • {{cDropperEntity|Dropper}} contents
  • {{cFurnaceEntity|Furnace}} contents (?)
  • {{cHopperEntity|Hopper}} contents
  • (TODO) Hopper minecart contents
  • -
  • Player Inventory areas
  • +
  • {{cPlayer|Player}} Inventory areas
  • (TODO) Trapped chest contents
  • The items contained in this object are accessed either by a pair of XY coords, or a slot number (x + Width * y). There are functions available for converting between the two formats. @@ -1232,6 +1245,40 @@ local Item5 = cItem(E_ITEM_DIAMOND_CHESTPLATE, 1, 0, "thorns=1;unbreaking=3"); Constants = { }, + AdditionalInfo = + { + { + Header = "Code example: Add items to player inventory", + Contents = [[ + The following code tries to add 32 sticks to a player's main inventory: +

    +local Items = cItem(E_ITEM_STICK, 32);
    +local PlayerMainInventory = Player:GetInventorySlots();  -- PlayerMainInventory is of type cItemGrid
    +local NumAdded = PlayerMainInventory:AddItem(Items);
    +if (NumAdded == Items.m_ItemCount) then
    +  -- All the sticks did fit
    +  LOG("Added 32 sticks");
    +else
    +  -- Some (or all) of the sticks didn't fit
    +  LOG("Tried to add 32 sticks, but only " .. NumAdded .. " could fit");
    +end
    +
    + ]], + }, + { + Header = "Code example: Damage an item", + Contents = [[ + The following code damages the helmet in the player's armor and destroys it if it reaches max damage: +
    +local PlayerArmor = Player:GetArmorSlots();  -- PlayerArmor is of type cItemGrid
    +if (PlayerArmor:DamageItem(0)) then  -- Helmet is at SlotNum 0
    +  -- The helmet has reached max damage, destroy it:
    +  PlayerArmor:EmptySlot(0);
    +end
    +
    + ]], + }, + }, -- AdditionalInfo }, cItems =