PopochiuInventoryItem

Inherits: TextureRect

Description

Represents an item that can be collected, stored in the inventory, and used on objects.

Inventory items can handle click interactions and be combined with other items or used on PopochiuClickable objects.

---

Properties

Type	Name	Default
CURSOR	cursor	CURSOR.Type.USE
Variant	description	""
Variant	ever_collected	false
bool	in_inventory
Variant	last_click_button	-1 # NOTE Don't know if this will make sense, or if it this object should
Variant	max_quantity	1
Variant	quantity_owned	0
Variant	script_name	""

---

Methods

Return Type	Method
void	_on_added_to_inventory() virtual
void	_on_click() virtual
void	_on_discard() virtual
void	_on_item_used(item: PopochiuInventoryItem) virtual
void	_on_middle_click() virtual
void	_on_quantity_changed(_old_qty: int, _new_qty: int) virtual
void	_on_right_click() virtual
void	add(quantity = 1, character: PopochiuCharacter = null)
void	add_as_active(quantity = 1, character: PopochiuCharacter = null)
int	count_invoked(command: int)
void	deselect()
void	discard(quantity: int = 0)
bool	ever_invoked(command: int)
bool	first_invoked(command: int)
String	get_description()
void	handle_command(button_idx: int)
void	on_click()
void	on_item_used(item: PopochiuInventoryItem)
void	on_middle_click()
void	on_right_click()
Callable	queue_add(quantity = 1, character: PopochiuCharacter = null)
Callable	queue_add_as_active(quantity = 1, character: PopochiuCharacter = null)
Callable	queue_discard(quantity: int = 0)
Callable	queue_remove(quantity: int = 0, character: PopochiuCharacter = null)
Callable	queue_replace(new_item: PopochiuInventoryItem, character: PopochiuCharacter = null)
void	remove(quantity: int = 0, character: PopochiuCharacter = null)
void	replace(new_item: PopochiuInventoryItem, character: PopochiuCharacter = null)
void	set_active(_ignore_block = false)
void	set_ever_collected(value: bool)
void	set_in_inventory(value: bool)
void	set_max_quantity(value: int)

---

Signals

• selected(item)
• unselected()

---

Signal Descriptions

selected

signal selected(item)

Emitted when the item is selected.

---

unselected

signal unselected()

Emitted when the item is unselected (in most GUIs, this happens when right-clicking anywhere on the screen).

---

Property Descriptions

cursor

@export var cursor : CURSOR = CURSOR.Type.USE

The cursor to use when the mouse hovers the object.

---

description

@export var description = ""

• Getter: get_description

The text shown to players when the cursor hovers the item.

---

ever_collected

var ever_collected = false

• Setter: set_ever_collected

Whether this item has ever been in the inventory. Once true, it stays true.

---

in_inventory

var in_inventory : bool

Reading returns true if quantity_owned is greater than 0.

Setting true ensures quantity_owned is at least 1.

Setting false sets quantity_owned to 0.

Warning: Unlike add() and remove(), this setter does not emit inventory signals and does not update the inventory GUI. Use add() and remove() instead.

---

last_click_button

var last_click_button = -1 # NOTE Don't know if this will make sense, or if it this object should

Stores the last MouseButton pressed on this object.

---

max_quantity

@export var max_quantity = 1

• Setter: set_max_quantity

The maximum number of this item the player can own at one time.

Defaults to 1, which preserves the legacy single-item behaviour. Cannot be set below 1: a value of zero or less would make the item permanently un-addable and break the first-add vs. stacking logic inside add().

---

quantity_owned

var quantity_owned = 0

The number of this item the player currently owns. Use this property to check ownership and stack sizes.

---

script_name

@export var script_name = ""

The identifier of the item used in scripts.

---

Method Descriptions

_on_added_to_inventory

func _on_added_to_inventory() -> void

This is a virtual method. Override it in your subclass.

Called after the item is added to the inventory.

Override this to implement custom behavior (e.g. playing a sound).

---

_on_click

func _on_click() -> void

This is a virtual method. Override it in your subclass.

Called when the item is clicked in the inventory GUI.

Override this to define what happens when the item is clicked.

---

_on_discard

func _on_discard() -> void

This is a virtual method. Override it in your subclass.

Called when the item is discarded from the inventory.

Override this to implement custom behavior (e.g. playing a sound).

---

_on_item_used

func _on_item_used(item: PopochiuInventoryItem) -> void

This is a virtual method. Override it in your subclass.

Called when this item is clicked while another item is selected.

Override this to define what happens when this item is used on another item.

---

_on_middle_click

func _on_middle_click() -> void

This is a virtual method. Override it in your subclass.

Called when the item is middle-clicked in the inventory GUI.

Override this to define what happens when the item is middle-clicked.

---

_on_quantity_changed

func _on_quantity_changed(_old_qty: int, _new_qty: int) -> void

This is a virtual method. Override it in your subclass.

Called when quantity_owned changes due to stacking or partial removal — i.e., when the item slot stays in the inventory but the count changes.

Override this to react to quantity changes (e.g. play a different sound for 1 vs. many coins).

---

_on_right_click

func _on_right_click() -> void

This is a virtual method. Override it in your subclass.

Called when the item is right-clicked in the inventory GUI.

Override this to define what happens when the item is right-clicked.

---

add

func add(quantity = 1, character: PopochiuCharacter = null) -> void

Adds quantity of this item to character's inventory (default: player character). quantity defaults to 1. On first add, the GUI shows an entrance animation; subsequent stack additions only emit item_quantity_updated.

Example:

func on_click() -> void:
    await C.walk_to_clicked()
    await C.player.say("I'm gonna take this with me")
    await I.Key.add()
    # Add three coins at once:
    await I.Coin.add(3)
    # Add Key to Popsy's inventory:
    await I.Key.add(1, C.Popsy)

---

add_as_active

func add_as_active(quantity = 1, character: PopochiuCharacter = null) -> void

Adds quantity of this item to character's inventory (default: player character) and makes it the active item (cursor shows the item's texture).

---

count_invoked

func count_invoked(command: int) -> int

Returns the number of times the command has been invoked on this object.

---

deselect

func deselect() -> void

Deselects this item if it is the current active item.

---

discard

func discard(quantity: int = 0) -> void

Use remove() instead. Calls _on_discard() and emits item_discarded before delegating to remove().

---

ever_invoked

func ever_invoked(command: int) -> bool

Returns true if the command has ever been invoked on this object. This function is typically used in a command handler to provide different behaviors depending on whether the command has been used before or not.

---

first_invoked

func first_invoked(command: int) -> bool

Returns true if this is the first time the command is being invoked on this object. This function is typically used in a command handler to provide different behaviors depending on whether the command has been used before or not.

---

get_description

func get_description() -> String

---

handle_command

func handle_command(button_idx: int) -> void

Triggers the proper GUI command for the clicked mouse button identified with button_idx, which can be MouseButton.MOUSE_BUTTON_LEFT, MouseButton.MOUSE_BUTTON_RIGHT or MouseButton.MOUSE_BUTTON_MIDDLE.

---

on_click

func on_click() -> void

Called when the item is clicked in the inventory.

---

on_item_used

func on_item_used(item: PopochiuInventoryItem) -> void

Called when the item is clicked and there is another item currently selected.

---

on_middle_click

func on_middle_click() -> void

Called when the item is middle clicked in the inventory.

---

on_right_click

func on_right_click() -> void

Called when the item is right clicked in the inventory.

---

queue_add

func queue_add(quantity = 1, character: PopochiuCharacter = null) -> Callable

Adds quantity of this item to character's inventory (default: player character). quantity defaults to 1. On first add, the GUI shows an entrance animation; subsequent stack additions only emit item_quantity_updated.

This method is intended to be used inside a queue() of instructions.

Example:

func on_click() -> void:
    E.queue([
        C.queue_walk_to_clicked(),
        "Player: I'm gonna take this with me",
        I.Key.queue_add()
    ])

---

queue_add_as_active

func queue_add_as_active(quantity = 1, character: PopochiuCharacter = null) -> Callable

Adds quantity of this item to character's inventory (default: player character) and makes it the active item (cursor shows the item's texture).

This method is intended to be used inside a queue() of instructions.

---

queue_discard

func queue_discard(quantity: int = 0) -> Callable

Use queue_remove() instead.

This method is intended to be used inside a queue() of instructions.

---

queue_remove

func queue_remove(quantity: int = 0, character: PopochiuCharacter = null) -> Callable

Removes quantity of this item from character's inventory (default: player character). Instance is kept in memory. Call without params or pass quantity as 0 (the default) to remove the full stack.

This method is intended to be used inside a queue() of instructions.

Example:

func on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.ToyCar:
        E.queue([
            "Player: Here is your toy car",
            I.ToyCar.queue_remove()
        ])

---

queue_replace

func queue_replace(new_item: PopochiuInventoryItem, character: PopochiuCharacter = null) -> Callable

Replaces this inventory item with new_item in character's inventory (default: player character). Useful when combining items. Replacing removes the whole collected quantity of this item and adds exactly one quantity of new_item.

This method is intended to be used inside a queue() of instructions.

Example:

# This is the script of the InventoryItemHook.gd (I.Hook)
func on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.Rope:
        E.queue([
            I.Rope.queue_remove(),
            queue_replace(I.RopeWithHook)
        ])

---

remove

func remove(quantity: int = 0, character: PopochiuCharacter = null) -> void

Removes quantity of this item from character's inventory (default: player character). Instance is kept in memory. Call without params or pass quantity as 0 (the default) to remove the full stack.

Example:

func on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.ToyCar:
        await C.player.say("Here is your toy car")
        await I.ToyCar.remove()

---

replace

func replace(new_item: PopochiuInventoryItem, character: PopochiuCharacter = null) -> void

Replaces this inventory item with new_item in character's inventory (default: player character). Useful when combining items. Replacing removes the whole collected quantity of this item and adds exactly one quantity of new_item.

Example:

# This is the script of the InventoryItemHook.gd (I.Hook)
func on_item_used(item: PopochiuInventoryItem) -> void:
    if item == I.Rope:
        await I.Rope.remove()
        await replace(I.RopeWithHook)

---

set_active

func set_active(_ignore_block = false) -> void

Makes this item the current active item (the cursor will look like the item's texture).

---

set_ever_collected

func set_ever_collected(value: bool) -> void

---

set_in_inventory

func set_in_inventory(value: bool) -> void

---

set_max_quantity

func set_max_quantity(value: int) -> void