06. Items & Currency tools: Depot

I. Introduction and Economic Scope

1.1 Purpose and Economic Functionality

The Items tool is the central system for defining, organizing, and managing all items and currencies used in your game economy.

This tool manages two distinct but related resource classes:

1. ItemCatalog (Singleton access: NexusForge.Items.): Responsible for defining every asset (items, equipment, consumables).
2. CurrencyCatalog (Singleton access: NexusForge.Currency.): Responsible for defining the economic units (e.g., gold, silver, copper). This tool allows the developer to set a relative unitary value for each currency, creating a conversion system flexible enough for a single-coin economy or a complex multi-currency system.

Each resource has its own custom icon for easy identification.

---

II. Item Catalog Management (ItemCatalog)

The ItemCatalog interface occupies the majority of the Depot window and is divided into three columns.

2.1 Column 1: Category and Item Trees

This column handles the organization and selection of items.

Category Tree:

• Controls: A text field for searching categories and a Pencil Icon button to enter Category Edit Mode.
• (unassigned) Category: A default, non-deletable category for items without a designed classification.
• Selection: Clicking a category populates the Items Tree below with its contents.
• Drag-and-Drop: You can drag an item from the Items Tree and drop it onto a category in this tree to re-assign it.

Items Tree:

• Controls: A text field for searching items and a Chest with Green '+' Icon button to create a new item.
• Enablement: The "Create Item" button is only enabled when a category (including (unassigned)) is selected.
• Selection: Clicking an item loads its data into Columns 2 and 3.

2.2 Category Edit Mode

Clicking the Pencil Icon switches the entire Depot window to this mode.

• Interface: A single, centered tree view for category management.
• Controls: A search bar and a '+' button to add new top-level categories.
• Category Items: Displays the nested categories and their subcategories.
• Custom Data: A tree view below manages custom data for the selected category.
  
• Exit: A "Done" button saves changes and returns to the main Depot view.

Tip

You can change the custom data new categories have by modyfing the constant CATEGORY_DEFAULT_DATA on the ItemCatalog^[2]

Note

• You can change the ID and name of a category by double-clicking it.
• Categories can be nested as necessary.
• Deleting a category with items in it will move all the items from that category to the (unassigned) category.
  

2.3 Column 2: Item Core Data

This column displays the primary data for the selected item.

• Name: Text field for the item's display name.
• Rarity: A dropdown menu. Options are defined by editing the Rarity enum of ItemSheet^[1]. The editor updates automatically when the script is saved.
• Value: An integer Spinbox for the item's intrinsic value.
• Description: A text box for the item's descriptive text.
• Custom Data: A tree view for defining any unique, item-specific properties.

Tip

You can change the custom data new items have by modyfing the constant ITEM_DEFAULT_DATA on the ItemCatalog^[2]

2.4 Column 3: Item Flags

This column manages the item's boolean properties.

• Flag Definition: Flags are defined by editing the ItemFlag enum of ItemSheet^[1]. The editor updates automatically when the script is saved.
• Display: Each flag appears with its name and an associated checkbox. Checking the box enables that flag for the item.

---

III. Usage in GDScript: ItemCatalog API

The ItemCatalog is accessed via the singleton NexusForge.Skills.

3.1 Item Lifecycle and Data

Function Signature	Purpose	Return Type	Notes
items()	Returns a list with all registered item IDs.	Array[StringName]
create_item(item_id)	Creates a new item.	-	Creation is skipped if item already exists.
erase_item(item_id)	Erases an item.	-
has_item(item_id)	Checks if an item exists.	Bool
get_item(item_id)	Returns an object with all the item data.	ItemSheet	Returns null if the item doesn't exist.
set_item_name(item_id, new_name)	Sets the item's display name.	-
set_item_rarity(item_id, new_rarity)	Sets the item's rarity.	-
set_item_value(item_id, new_value)	Sets the item's intrinsic integer value.	-
set_item_description(item_id, new_description)	Sets the item's description.	-
set_item_data(item_id, data_key, data)	Sets a custom data key.	-	If data is null, the key is erased.
clear_item_data(item_id)	Clears all custom data from the item.	-

3.2 Item Flags

Function Signature	Purpose	Return Type
set_item_flag(item_id, flag, enabled)	Sets the state of a single flag.	-
set_item_flags(item_id, flags, enabled)	Sets the state for an array of flags.	-
item_has_flag(item_id, flag)	Checks if the item has the specified flag enabled.	Bool
clear_item_flags(item_id)	Clears all flags from the item.	-

3.3 Category Management

Function Signature	Purpose	Return Type	Notes
categories()	Returns a list with all category IDs.	Array[StringName]
create_category(category_id)	Creates a new category.	-	Creation fails if the category_id already exists.
link_category(category, parent_category)	Sets category as a subcategory of parent_category.	-	Passing &"" as the parent_category turns category into a top-level category.
set_item_category(item_id, new_category)	Assigns an item to a category.	-
set_category_name(category_id, category_name)	Sets the category's display name.	-
set_category_data(category_id, data_key, data)	Sets custom data for a category.	-	Passing null as data will erase the data key.
erase_category(category_id)	Erases a category and removes it from any items that had it.	-
get_supercategories_of(from_category)	Returns the full parent hierarchy structure for a category.	Dictionary[StringName, Dictionary]	Example: get_supercategories_of(&"b") -> {&"a": {&"b": {}}
get_subcategories_of(from_category)	Returns the full subcategory hierarchy structure for a category.	Dictionary[StringName, Dictionary]	Example: get_subcategories_of(&"a") -> {&"a": {&"b": {&"c": {}}}

---

IV. Currency Management (CurrencyCatalog)

The CurrencyCatalog is accessed via NexusForge.Currency.

The CurrencyCatalog interface is a simple, vertical layout on the right side of the Depot.

• Creation: A text field for searching and a Two Coins with Green '+' Icon button to create a new currency (prompts for an ID).
• Currency Tree: Displays all currency IDs.
• Data Fields:
  • Name: The human-readable display name.
  • Unitary Value: An integer Spinbox for the currency's relative base value.
  • Custom Data: A tree view for currency-specific properties.

Tip

You can change the custom data new currencies have by modyfing the constant CURRENCY_DEFAULT_DATA on the CurrencyCatalog^[3]

Note

• Currencies are always sorted alphabetically by their ID, not by value.
• Double-clicking a currency ID allows you to edit it.
• Currencies' value can't be below 1.

Important

The system is designed so that there is always a currency with a value of 1. Missing it might lead to unintended behaviour by the helper methods.

Caution

Having multiple currencies with the same relative value will cause the currency converter methods to behave unexpectedly.
It is recommended that each currency has its own unique value.

---

V. Usage in GDScript: CurrencyCatalog API

5.1 Currency Lifecycle and Data

Function Signature	Purpose	Return Type	Notes
create_currency(currency_id)	Creates a new currency.	-	Creation fails if the currency already exists.
has_currency(currency_id)	Checks if a currency exists.	Bool
set_currency_value(currency_id, new_value)	Sets the unitary value.	-	Minimum value is 1.
get_currency_value(currency_id)	Returns the unitary value.	Integer	Returns 0 if the currency doesn't exist.
set_currency_name(currency_id, new_name)	Sets the currency's display name.	-
currencies(sort_ascendant = false)	Returns all currency IDs.	Array[StringName]	If sort_ascendant is true, the returned array will be sorted from lowest value to highest.
erase_currency(currency_id)	Erases a currency.	-
set_currency_data(currency_id, data_key, data)	Sets custom data for a currency.	-	Passing data as null will erase the data key.

5.2 Multi-Currency Conversion Utilities

In a multi-currency system, the NexusForge.Currency singleton holds helper methods to make managing exchanges and conversions easier.

Function Signature	Purpose	Return Type	Notes
currency_value(currencies)	Returns the total base integer value of a currency pool.	Integer	If currencies holds an inexistent currency, it'll be ignored.
substract_value(from, substract)	Subtracts one currency pool from another and returns the remainder.	Dictionary[StringName, int]	If substract is greater than from an empty dictionary will be returned. If substract's total value is less than 0, from will be returned. This method will substract from small denominations to large ones.
maximize_from_value(currency_value)	Converts a base integer value into the highest possible combination of currency denominations.	Dictionary[StringName, int]	If there is a remainder that couldn't be converted-due to a lack of a currency with a value of 1-the returned dictionary will contain a key _remainder with the remainder of the conversion.
maximize_from_currency(currency_type, amount)	Converts an amount of one currency into the highest possible combination of currency denominations.	Dictionary[StringName, int]
minimize_from_currency(currency_type, amount)	Converts a high denomination into the lowest denomination.	Dictionary[StringName, int]
convert_currency(from, to, amount)	Converts an amount of one currency type to another.	Dictionary[StringName, int]	Contains 2 keys The key given in from witht the remainder (Amount that couldn't be converted). The key given in to with the converted amount.

VI. Footnotes

1. The default path for ItemSheet is res://addons/nexus_forge/resources/item_sheet.gd
2. The default path for ItemCatalog is res://addons/nexus_forge/resources/recipe_catalog.gd.
3. The default path for CurrencyCatalog is res://addons/nexus_forge/resources/currency_catalog.gd.