Skip to content

Items & Definitions

Items are defined using the ItemDefinition Resource. This resource is purely data-driven; it holds all the properties, visuals, and metadata for an item without containing any execution logic.

Creating an Item

  1. In the Godot FileSystem dock, right-click and select Create New > Resource.
  2. Search for and select ItemDefinition.
  3. Save the file as a .tres resource (e.g., apple.tres).

Properties Breakdown

Identity

  • id (String): A unique string identifier for code references.
  • display_name (String): human-readable name shown in UI and tooltips.
  • description (String): A multiline string for item lore or stats.
  • icon (Texture2D): 2D texture used in inventory slots and drag previews.

Stacking & Weight

  • max_stack_size (int): Maximum number of items that can occupy a single slot (e.g., 64 for wood, 1 for a sword).
  • weight (float): Used if you are implementing a weight-based carrying system.

Durability

  • has_durability (bool): Enables the durability system for this item.
  • max_durability (int): starting/maximum durability value.
  • default_durability (int): Currently unused by the codebase. Intended to be the starting durability, but the system always defaults to max_durability.
  • durability_loss_per_use (int): How much durability is lost when _consume_item_durability() is called.
  • break_on_zero (bool): If true, the item is automatically destroyed and removed from the inventory when durability hits 0.

Incomplete Feature: Durability System

Visuals (3D World)

  • model_scene (PackedScene): Instantiated when the item is dropped into the 3D world.
  • placement_scene (PackedScene): Used by PlacementLogic when building structures.
  • preview_offset (Vector3): Offset for 3D preview models.

Runtime Behavior

  • logic_script (Script): A script extending ItemLogic that defines what happens when the item is used.

Metadata & Tags

  • tags (Array[String]): Used for filtering (e.g., ["weapon", "melee", "iron"]).
  • equipment_type (int): Used by EquipmentTypeRule to lock items to specific gear slots.
  • custom_metadata (Dictionary): Arbitrary data storage (e.g., {"rarity": "legendary"}).

Helper Methods

func has_tag(tag: String) -> bool             # Checks if the item has a specific tag
func is_equipment_type(type: int) -> bool     # Checks if it matches an equipment type
func get_meta_value(key: String, default)     # Safely retrieves custom metadata
func set_meta_value(key: String, value)       # Sets custom metadata
func is_broken(current_durability: int) -> bool
func get_durability_percent(current_durability: int) -> float