1--! \page global_variables Global Variables
2--! \section Inventories Inventories
4--! See Inventories
for the
module on inventories.\n\n
5--! FrameworkZ.Inventories.List\n
6--! A list of all instanced inventories in the game.\n\n
7--! FrameworkZ.Inventories.Types\n
8--! The types of inventories that can be created.
10FrameworkZ = FrameworkZ or {}
12--! \brief The Inventories module for FrameworkZ. Defines and interacts with INVENTORY object.
13--! \class FrameworkZ.Inventories
14FrameworkZ.Inventories = {}
15FrameworkZ.Inventories.__index = FrameworkZ.Inventories
16FrameworkZ.Inventories.List = {}
17FrameworkZ.Inventories.Types = {
18 Character = "Character",
19 Container = "Container",
22FrameworkZ.Inventories = FrameworkZ.Foundation:NewModule(FrameworkZ.Inventories, "Inventories")
24--! \brief Inventory class for FrameworkZ.
27INVENTORY.__index = INVENTORY
29--! \brief Initialize an inventory.
30--! \return \string The inventory's ID.
31function INVENTORY:Initialize()
32 return FrameworkZ.Inventories:Initialize(self.id, self)
35--! \brief Add an item to the inventory.
36--! \details Note: This does not add a world item, it simply adds it to the inventory's object. Please use CHARACTER::GiveItem(uniqueID) to add an item to a character's inventory along with the world item.
37--! \param item \string The item's ID.
38--! \see CHARACTER::GiveItem(uniqueID)
39function INVENTORY:AddItem(item)
40 self.items[#self.items + 1] = item
43--! \brief Add multiple items to the inventory.
44--! \details Note: This does not add a world item, it simply adds it to the inventory's object. Please use CHARACTER::GiveItems(uniqueID) to add an items to a character's inventory along with the world item.
45--! \param uniqueID \string The item's ID.
46--! \param quantity \integer The quantity of the item to add.
47--! \see CHARACTER::GiveItems(uniqueID)
48function INVENTORY:AddItems(uniqueID, quantity)
49 for i = 1, quantity do
50 self:AddItem(uniqueID)
54function INVENTORY:GetItems()
58function INVENTORY:GetItemByID(uniqueID)
59 if not uniqueID or uniqueID == "" then return false, "No unique ID provided." end
61 for _key, item in pairs(self:GetItems()) do
62 if item.uniqueID == uniqueID then
67 return false, "No item found with unique ID: " .. uniqueID
70function INVENTORY:GetItemCountByID(uniqueID)
71 if not uniqueID or uniqueID == "" then return false, "No unique ID provided." end
75 for _key, item in pairs(self:GetItems()) do
76 if item.uniqueID == uniqueID then
84--! \brief Get the inventory's name.
85--! \return \string The inventory's name.
86function INVENTORY:GetName()
87 return self.name or "Someone's Inventory"
90--! \brief Create a new inventory object.
91--! \param username \string The owner's username. Can be nil for no owner.
92--! \param type \string The type of inventory. Can be nil, but creates a character inventory type by default. Refer to FrameworkZ.Inventories.Types table for available types.
93--! \param id \string The inventory's ID. Can be nil for an auto generated ID (recommended).
94--! \return \table The new inventory object.
95function FrameworkZ.Inventories:New(username, type, id)
97 FrameworkZ.Inventories.List[#FrameworkZ.Inventories.List + 1] = {} -- Reserve space to avoid inconsistencies.
98 id = #FrameworkZ.Inventories.List
103 owner = username or "",
104 type = type or FrameworkZ.Inventories.Types.Character,
105 name = "Someone's Inventory",
106 description = "No description available.",
110 setmetatable(object, INVENTORY)
115--! \brief Initialize an inventory.
116--! \param id \table The inventory's id.
117--! \param object \table The inventory's object.
118--! \return \integer The inventory's ID.
119function FrameworkZ.Inventories:Initialize(id, object)
120 FrameworkZ.Inventories.List[id] = object
125function FrameworkZ.Inventories:GetInventoryByID(id)
126 if not id then return false, "No inventory ID provided." end
128 local inventory = self.List[id] or nil
130 if not inventory then return false, "No inventory found with ID: " .. id end
135function FrameworkZ.Inventories:GetItemByID(inventoryID, uniqueID)
136 if not inventoryID then return false, "No inventory ID provided." end
137 if not uniqueID or uniqueID == "" then return false, "No unique ID provided." end
139 local inventoryOrSuccess, inventoryMessage = self:GetInventoryByID(inventoryID)
141 if not inventoryOrSuccess then return inventoryOrSuccess, inventoryMessage end
143 local itemOrSuccess, itemMessage = inventoryOrSuccess:GetItemByID(uniqueID)
145 return itemOrSuccess, itemMessage
148function FrameworkZ.Inventories:GetItemCountByID(inventoryID, uniqueID)
149 if not inventoryID then return false, "No inventory ID provided." end
150 if not uniqueID or uniqueID == "" then return false, "No unique ID provided." end
152 local inventoryOrSuccess, inventoryMessage = self:GetInventoryByID(inventoryID)
154 if not inventoryOrSuccess then return inventoryOrSuccess, inventoryMessage end
156 local countOrSuccess, countMessage = inventoryOrSuccess:GetItemCountByID(uniqueID)
158 return countOrSuccess, countMessage
161--! \brief Recursively traverses the inventory table for missing data while referencing the item definitions to rebuild the inventory.
162--! \param inventory \table The inventory to rebuild.
163--! \return \table The rebuilt inventory.
164function FrameworkZ.Inventories:Rebuild(isoPlayer, inventory, items)
165 if not isoPlayer then return false, "No ISO Player to add items to." end
166 if not inventory then return false, "No inventory to rebuild." end
167 if not items then return false, "No items to add to inventory." end
169 -- Recursive function to rebuild fields and inherit methods
170 local function rebuildAndInherit(item, definition)
171 -- Ensure item inherits methods and properties from the definition
172 setmetatable(item, { __index = definition })
174 -- Recursively rebuild all fields
175 for key, value in pairs(definition) do
176 if type(value) == "table" then
177 -- Ensure item[key] exists and is a table, then recurse
178 item[key] = item[key] or {}
179 rebuildAndInherit(item[key], value)
180 elseif type(value) == "function" then
181 -- Ensure functions are inherited and retain their object context
183 elseif item[key] == nil then
184 -- Copy over non-function and non-table fields if missing
190 -- Rebuild an individual item
191 local function rebuildItem(item)
192 if type(item) ~= "table" then return end -- Ensure item is a table
194 -- Fetch the item definition
195 local itemDefinition = FrameworkZ.Items:GetItemByID(item.uniqueID)
196 if not itemDefinition then return end -- Exit if no definition is found
198 -- Rebuild fields and inherit methods
199 rebuildAndInherit(item, itemDefinition)
201 -- Create and link the world item
202 local success, message, worldItem = FrameworkZ.Items:CreateWorldItem(isoPlayer, item.itemID)
203 if success and worldItem then
204 local instanceID, itemInstance = FrameworkZ.Items:AddInstance(item, isoPlayer, worldItem)
206 -- Define instance data
207 local instanceData = {
208 uniqueID = itemInstance.uniqueID,
209 itemID = worldItem:getFullType(),
210 instanceID = instanceID,
211 owner = isoPlayer:getUsername(),
212 name = itemInstance.name or "Unknown",
213 description = itemInstance.description or "No description available.",
214 category = itemInstance.category or "Uncategorized",
215 shouldConsume = itemInstance.shouldConsume or false,
216 weight = itemInstance.weight or 1,
217 useAction = itemInstance.useAction or nil,
218 useTime = itemInstance.useTime or nil,
219 customFields = itemInstance.customFields or {}
222 -- Link the world item to the instance data
223 FrameworkZ.Items:LinkWorldItemToInstanceData(worldItem, instanceData)
225 -- Add the item instance to the inventory
226 inventory:AddItem(itemInstance)
228 -- Call OnInstance if it exists
229 if item.OnInstance then
230 item:OnInstance(isoPlayer, inventory, worldItem)
235 -- Iterate through and rebuild each item
236 for _, item in pairs(items) do
240 return true, "Inventory rebuilt.", inventory
243FrameworkZ.Foundation:RegisterModule(FrameworkZ.Inventories)
void local itemDefinition()
void local instanceData()
void local itemInstance()
The Inventories module for FrameworkZ. Defines and interacts with INVENTORY object.
FrameworkZ Inventories Types
FrameworkZ Inventories __index
FrameworkZ Inventories List
Inventory class for FrameworkZ.
void AddItem(item)
Add an item to the inventory.
void GetItemCountByID(uniqueID)
void AddItems(uniqueID, quantity)
Add multiple items to the inventory.
string GetName()
Get the inventory's name.
void GetItemByID(uniqueID)
string Initialize()
Initialize an inventory.