FrameworkZ 4.4.2
Provides a framework for Project Zomboid with various systems.
Loading...
Searching...
No Matches
Inventories.lua
Go to the documentation of this file.
1--! \page global_variables Global Variables
2--! \section Inventories Inventories
3--! FrameworkZ.Inventories\n
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.
9
10FrameworkZ = FrameworkZ or {}
11
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",
20 Vehicle = "Vehicle"
22FrameworkZ.Inventories = FrameworkZ.Foundation:NewModule(FrameworkZ.Inventories, "Inventories")
23
24--! \brief Inventory class for FrameworkZ.
25--! \class INVENTORY
26local INVENTORY = {}
27INVENTORY.__index = INVENTORY
28
29--! \brief Initialize an inventory.
30--! \return \string The inventory's ID.
31function INVENTORY:Initialize()
32 return FrameworkZ.Inventories:Initialize(self.id, self)
33end
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
41end
42
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)
51 end
52end
53
54function INVENTORY:GetItems()
55 return self.items
56end
57
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
63 return item
64 end
65 end
66
67 return false, "No item found with unique ID: " .. uniqueID
68end
69
70function INVENTORY:GetItemCountByID(uniqueID)
71 if not uniqueID or uniqueID == "" then return false, "No unique ID provided." end
72
73 local count = 0
74
75 for _key, item in pairs(self:GetItems()) do
76 if item.uniqueID == uniqueID then
77 count = count + 1
78 end
79 end
80
81 return count
82end
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"
88end
89
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)
96 if not id then
97 FrameworkZ.Inventories.List[#FrameworkZ.Inventories.List + 1] = {} -- Reserve space to avoid inconsistencies.
98 id = #FrameworkZ.Inventories.List
99 end
100
101 local object = {
102 id = id,
103 owner = username or "",
104 type = type or FrameworkZ.Inventories.Types.Character,
105 name = "Someone's Inventory",
106 description = "No description available.",
107 items = {}
108 }
110 setmetatable(object, INVENTORY)
112 return object
113end
114
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
121
122 return id
123end
124
125function FrameworkZ.Inventories:GetInventoryByID(id)
126 if not id then return false, "No inventory ID provided." end
127
128 local inventory = self.List[id] or nil
130 if not inventory then return false, "No inventory found with ID: " .. id end
132 return inventory
133end
134
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
138
139 local inventoryOrSuccess, inventoryMessage = self:GetInventoryByID(inventoryID)
140
141 if not inventoryOrSuccess then return inventoryOrSuccess, inventoryMessage end
142
143 local itemOrSuccess, itemMessage = inventoryOrSuccess:GetItemByID(uniqueID)
144
145 return itemOrSuccess, itemMessage
146end
147
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
151
152 local inventoryOrSuccess, inventoryMessage = self:GetInventoryByID(inventoryID)
153
154 if not inventoryOrSuccess then return inventoryOrSuccess, inventoryMessage end
155
156 local countOrSuccess, countMessage = inventoryOrSuccess:GetItemCountByID(uniqueID)
157
158 return countOrSuccess, countMessage
159end
160
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
168
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 })
173
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
182 item[key] = value
183 elseif item[key] == nil then
184 -- Copy over non-function and non-table fields if missing
185 item[key] = value
186 end
187 end
188 end
189
190 -- Rebuild an individual item
191 local function rebuildItem(item)
192 if type(item) ~= "table" then return end -- Ensure item is a table
193
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
197
198 -- Rebuild fields and inherit methods
199 rebuildAndInherit(item, itemDefinition)
200
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)
205
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 {}
220 }
221
222 -- Link the world item to the instance data
223 FrameworkZ.Items:LinkWorldItemToInstanceData(worldItem, instanceData)
224
225 -- Add the item instance to the inventory
226 inventory:AddItem(itemInstance)
227
228 -- Call OnInstance if it exists
229 if item.OnInstance then
230 item:OnInstance(isoPlayer, inventory, worldItem)
231 end
232 end
233 end
234
235 -- Iterate through and rebuild each item
236 for _, item in pairs(items) do
237 rebuildItem(item)
238 end
239
240 return true, "Inventory rebuilt.", inventory
241end
242
243FrameworkZ.Foundation:RegisterModule(FrameworkZ.Inventories)
void inventory()
void self isoPlayer
void id()
void shouldConsume()
void description()
void local success
void local worldItem()
void uniqueID()
void customFields()
void items()
void local object()
void useTime()
void category()
void local itemDefinition()
void itemID()
void owner()
void local instanceData()
void local instanceID
void type()
void name()
void weight()
void local itemInstance()
void useAction()
void FrameworkZ()
void local message
void self username()
void local item()
The Inventories module for FrameworkZ. Defines and interacts with INVENTORY object.
FrameworkZ Inventories Types
FrameworkZ Inventories __index
FrameworkZ Inventories List
FrameworkZ global table.
Inventory class for FrameworkZ.
void AddItem(item)
Add an item to the inventory.
void GetItems()
void GetItemCountByID(uniqueID)
void AddItems(uniqueID, quantity)
Add multiple items to the inventory.
string GetName()
Get the inventory's name.
INVENTORY __index
void GetItemByID(uniqueID)
string Initialize()
Initialize an inventory.