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
+ 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: -
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 =