ai-game-2/inventory-prd.md

Inventory & Backpack System — Product Requirements Document

1. Overview

This document specifies the behavior of a point-and-click adventure game inventory system, consisting of a backpack HUD element in the main game view and a full-screen inventory overlay for item combination. The system tracks which items the player currently holds, which items have been acquired at least once, and supports selecting, combining, acquiring, and removing items with animated transitions.

The specification is intentionally engine-agnostic and focuses on user-observable behavior, system architecture, and acceptance criteria suitable for implementation in any 2D game engine or framework.

2. Data Models

2.1. Player Inventory State

Field	Type	Description
Current inventory	Ordered list	Items the player is carrying. Preserves insertion order.
Obtained items	Set	Items the player has obtained at least once. Persists across removal — used to check "have you seen this item before".
Stripped items	Ordered list	Vault for items forcibly removed by game events. Items can be recovered later.

2.2. Item Definition

Each item is defined by a unique identifier and a descriptor:

Field	Type	Description
Name	String	Human-readable display name.
Identifier	Unique key	Canonical identifier for the item.
Cursor variant	Reference	Sprite or cursor variant to display when this item is selected.
Interaction handlers	Map or dynamic function	Defines what happens when this item is combined with another. May be a static lookup by the other item's identifier, or a dynamic function that evaluates at combination time. Empty or missing means no valid combination.
Combination category	Optional tag	Optional marker used by dynamic combination rules (e.g., "container" items that accept other items).

2.3. Inventory Queries

The system must support the following queries:

Query	Description
Has item?	Is a given item currently in the player's inventory?
Has obtained?	Has the player ever obtained a given item?
Has any of?	Does the player currently hold any item from a given set?
Has obtained any of?	Has the player ever obtained any item from a given set?
Has obtained all of?	Has the player ever obtained every item in a given set?

3. System Architecture

The inventory system comprises three components:

• Main Scene — The default game view. The player navigates the world and interacts with entities.
• Inventory Overlay — Full-screen overlay for viewing items and combining them. Blocks main scene input while visible.
• HUD Backpack FSM — Manages the backpack icon state, animations, and floating item display. Sits between the main scene and the overlay.

┌─────────────────────────────────────────────┐
│                 Main Scene                   │
│  ┌──────────┐    events      ┌────────────┐ │
│  │  HUD     │◄──────────────►│  Inventory │ │
│  │  Backpack│                │  Overlay   │ │
│  │  (FSM)   │                │            │ │
│  └──────────┘                └────────────┘ │
└─────────────────────────────────────────────┘

4. HUD Backpack FSM

The backpack element lives in the top-right of the main game screen. It is always rendered but its internal state drives animations and whether the inventory overlay is shown.

4.1. States

State	Meaning	Visual Behavior
Idle	Closed, at rest	Backpack icon at rest position. Idle animation.
Open	Inventory overlay is visible	Backpack animates to an "open" pose via rotation and repositioning. Overlay fades in.
Selected	An item is selected and displayed outside the backpack	Small item sprite rendered floating adjacent to the backpack.
Acquire	New item received, animating into the backpack	Backpack opens, item appears briefly, then drops into the backpack, backpack closes.
Remove	Item being removed from inventory	Backpack opens, item appears, then slides away and fades out. Backpack closes.

4.2. Transition Architecture

Transitions are multi-step. Each step is a discrete animation or action with a start trigger and a completion predicate. Steps execute sequentially — the next step begins only after the previous step reports completion. While a transition sequence is in progress, new transition requests are queued and executed in FIFO order after the current sequence finishes.

4.3. State Transitions

Idle → Open — Open Inventory

Trigger: Player clicks the backpack icon while the scene is interactable.

Steps:

1. Animate backpack rotation to open position (0.35s).
2. Animate backpack position to open location (0.35s).
3. Play backpack open sprite animation to completion.
4. Lock backpack to final open frame.
5. Show the inventory overlay screen.

Open → Idle — Close Inventory (no item selected)

Trigger: Inventory overlay closes via click-on-empty-space, drag-out, or cancel.

Steps:

1. Animate backpack rotation back to rest (0.35s).
2. Animate backpack position back to rest (0.35s).
3. Play backpack closing sprite animation to completion.
4. Return backpack to default sprite.
5. Clear any selected item.

Open → Selected — Select Item

Trigger: Player confirms an item selection from the inventory overlay.

Steps:

1. Fade in the item sprite; move it to its floating position next to the backpack (0.5s).

Selected → Idle — Deselect and Close

Trigger: Player deselects the item (e.g., right-click return, or explicit deselect).

Steps:

1. Fade out the item sprite; move it toward the backpack (0.5s).
2. Animate backpack rotation and position back to rest, play closing animation (0.35s).
3. Return backpack to default sprite, clear selected item.

Idle → Acquire → Idle — Pick Up New Item

Trigger: Player receives an item from the game world.

Visual: Backpack opens, item fades in at rest, backpack begins closing, item slides into the backpack and fades out, backpack returns to default.

Selected → Acquire → Selected — Replace Selected Item

Trigger: Player acquires a new item while another item is already selected.

Steps:

1. Fade out the currently selected item in place.
2. Fade in the new item in place.
3. Animate the new item sliding into the backpack and fading out.
4. Fade the new item back in at the floating position.

Remove Variants

Several remove transitions exist depending on the current state:

From → To	Condition	Behavior
Idle → Remove → Idle	No item selected	Backpack opens, item appears, slides up and fades, backpack closes.
Selected → Remove → Idle (same item)	Item being removed IS the selected item	Selected item slides up and fades out. Clear selection.
Selected → Remove → Idle (different item)	Item being removed is DIFFERENT from selected	Deselect current item, show item being removed, slide it up and fade, clear selection.

4.4. Item Appearance Animation Primitive

A reusable animation primitive handles showing or hiding the floating item sprite with optional vertical movement:

Fade direction	Movement direction	Effect
Show (fade in)	Out (away from backpack)	Item appears floating next to backpack
Show (fade in)	None	Item appears in place, no movement
Hide (fade out)	In (toward backpack)	Item slides into backpack and disappears
Hide (fade out)	Far-out (away and further)	Item slides upward and fades — used for removal
Hide (fade out)	None	Item fades out in place — used for swap

All fades are 0.5s with linear easing.

5. Inventory Overlay Screen

5.1. Activation

The overlay is shown when the HUD FSM enters the Open state. The overlay receives the current list of inventory items and lays them out in a grid.

5.2. Visual Layout

• Background: Semi-transparent dark overlay covering the full screen.
• Inventory Panel: Centered panel with a decorative frame texture.
• Item Grid: Items laid out left-to-right, top-to-bottom, with a fixed maximum number of items per row.
• Hover Text Label: Text area at the bottom of the panel for displaying item names and combination hints.

5.3. Open / Close Animations

Action	Animation
Open	Panel fades from 0% to 100% opacity over 0.2s. Items are laid out in the grid.
Close	Panel fades from 100% to 0% opacity over 0.2s. On completion, all selection and hover state is cleared.

5.4. Interaction Model

The inventory overlay only processes input when it is fully visible (opacity at 100%).

Hover

• Moving the mouse over an item highlights it and sets it as the hover target.
• Hover text behavior:
  • If an item is already selected and a different item is hovered: Display "Use {selected item} with {hovered item}"
  • If no item is selected and an item is hovered: Display the item's name.
  • Otherwise: Clear the label.

Press and Drag

• Pressing on an item selects it for the action.
• Dragging the selected item moves it to follow the cursor.
• Drag outside panel bounds: If the dragged item is moved outside the inventory panel area, the inventory closes immediately and the selection is discarded.

Left-Click Release

Condition	Result
No item was pressed	Close inventory, deselect.
Pressed and released on the same item, held > 0.5s	Deselect (long-press cancel). Inventory stays open.
Pressed and released on the same item, held ≤ 0.5s	Confirm selection. Close inventory. Item floats outside backpack in the main scene.
Pressed one item, released on a different item	Attempt to combine the two items. (See Item Combination below.)

Right-Click Release

Condition	Result
An item is selected or hovered	Inspect the item: play its description dialogue. Close inventory.

5.5. Item Combination Logic

When two different items are clicked together:

1. Forward lookup: Check whether the first item has a defined interaction with the second item.
2. Reverse lookup: If no interaction is defined, check whether the second item has a defined interaction with the first item. This ensures combinations work regardless of click order.
3. No match: If neither direction defines an interaction, show a generic refusal message.

Dynamic Combination Rules

Some items generate their interactions dynamically at evaluation time rather than using a static lookup. Common patterns include:

• Category-based rules: Items tagged with a combination category (e.g., "container") evaluate a rule set that checks the other item's properties.
• Prerequisite checks: A combination may require the player to have obtained a prerequisite item before the combination is allowed. If the prerequisite is missing, a different refusal message is shown.
• Order guards: Some item pairs define a "not ready" handler when combined out of sequence. The refusal message differs depending on whether the player possesses a reference item (e.g., a recipe or instructions).

Successful Combination

When a valid combination is found:

1. Execute the combination action (typically removes consumed items, adds a result item, plays dialogue).
2. Close the inventory.

Refusal Handling

When a combination is not valid, the player receives context-appropriate feedback:

• No interaction defined: Generic "I don't know how those go together" message.
• Missing prerequisite: Message indicating the player needs more information first.
• Wrong order ("not ready" guard): Message varies based on whether the player has reference materials.

5.6. Post-Selection Flow

When the inventory overlay closes with a confirmed item selection:

1. The HUD transitions to the Selected state — the item's sprite floats outside the backpack.
2. The game cursor switches to the item's dedicated cursor sprite.
3. The player can then:
   • Left-click in the game world: Use the item on the clicked entity. If nothing is clicked, show the item's self-description.
   • Click the backpack again: Re-open the inventory overlay.
   • Right-click in the game world: Return the item to the backpack. Cursor reverts to default.

6. Item Acquisition

When the player acquires an item from the game world:

1. Play a pickup sound effect.
2. Append the item to the current inventory list.
3. Add the item to the obtained-items set.
4. Trigger the acquisition animation on the HUD (backpack opens, item appears, drops in, closes).

If an item is already selected when a new item is acquired, the selected item display is replaced with the newly acquired item.

7. Item Removal

When an item is removed from inventory (consumed in combination, dropped, or stripped by a game event):

1. Remove the item from the current inventory list.
2. The item is not removed from the obtained-items set — acquisition history persists.
3. Unless the removal is quiet, trigger the removal animation on the HUD (backpack opens, item appears, slides up and fades, closes).

7.1. Bulk Item Removal

When a game event strips multiple items from the player:

1. Items removable by the event are removed from the current inventory.
2. Certain protected items may be exempt from removal.
3. Stripped items are moved to a vault for potential later recovery.
4. Obtained-items history is unaffected.

8. Cursor System

The game cursor changes based on the player's current inventory selection:

State	Cursor
No item selected	Default pointer
Item selected	Item-specific cursor sprite
System override (e.g., loading)	Hourglass or wait cursor

8.1. Cursor Behavior

• Each item's cursor sprite has a configurable hotspot offset so the click-detection point aligns with the meaningful part of the sprite.
• Cursor updates are throttled to avoid excessive redraws.
• When the mouse button is pressed, the cursor sprite shifts vertically to simulate a depressed state.
• Returning an item (right-click) reverts the cursor to default.

9. Guard Conditions

The inventory system respects the following scene-level guards:

Guard	Effect
Foreground action running	Inventory cannot be opened. Clicking the backpack instead attempts to skip the running action.
Screen fade in progress	Input is blocked. Inventory cannot be opened.
Game paused or inactive	Inventory is inaccessible.
HUD element hovered	A flag is set to prevent game-world clicks while the mouse is over any HUD element.

10. Using Selected Items in the Game World

When the player left-clicks in the game world with an item selected:

1. No clickable entity: Run the item's self-description dialogue.
2. Clickable entity found: Pass the item's identifier to the entity's interaction handler. The entity determines whether the item is useful in this context.
3. Entity has no interaction for that item: Show a generic "nothing to do with that" message.

11. Animation Specifications

11.1. Backpack Animations

Animation	Source	Behavior
Default (idle)	Idle sprite or animation loop	Static or looping idle state. Plays when backpack is at rest.
Open	Multi-frame animation	Plays frames forward from closed to open. Stops at final frame.
Opened (held)	Final frame of open animation	Locked frame while inventory is open.
Closing	Multi-frame animation	Plays frames from the open frame back toward closed. Stops at final frame.

11.2. Tween Timing Reference

Tween	Easing	Duration
Backpack rotation (open or close)	Linear	~0.35s
Backpack position (open or close)	Ease-in	~0.35s
Overlay fade-in	Ease-out	~0.2s
Overlay fade-out	Ease-out	~0.2s
Item appear/disappear	Linear	~0.5s

Durations are reference values — implementations should target similar pacing.

12. Acceptance Criteria

AC-1: Inventory Data

• Current inventory is an ordered collection that preserves insertion order.
• Obtained items is a set that records every item ever acquired.
• Removing an item from the current inventory does not remove it from obtained items.
• Initial state: empty inventory, empty obtained set.

AC-2: HUD Backpack FSM

• The FSM starts in the Idle state.
• State transitions execute as multi-step sequences, not instantaneous changes.
• Each step completes before the next step begins.
• New transition requests are queued while the FSM is busy; no transitions are dropped.
• Queued transitions execute in FIFO order.

AC-3: Open Inventory

• Clicking the backpack icon when the scene is interactable opens the inventory overlay.
• The backpack icon animates to an open pose (rotation and reposition).
• The inventory overlay fades in over ~0.2s.
• Items are laid out in a grid with a fixed maximum per row.

AC-4: Close Inventory

• Clicking empty space in the overlay closes the inventory.
• Dragging an item outside the panel bounds closes the inventory and discards the selection.
• The overlay fades out over ~0.2s.
• The backpack animates back to its rest pose.
• Selection and hover state are cleared on close.

AC-5: Item Selection

• Clicking an item in the inventory selects it.
• Long-press release (>0.5s) on the same item deselects it; inventory stays open.
• Short release (≤0.5s) on the same item confirms selection; inventory closes.
• The selected item's sprite appears floating outside the backpack.
• The game cursor switches to the item's cursor sprite.
• Right-clicking an item in the inventory inspects it and closes the overlay.

AC-6: Item Combination

• Clicking item A then item B checks A's interactions for B.
• If A has no interaction for B, B's interactions for A are checked (order-independent).
• If no interaction exists for the pair, a refusal message is shown.
• Category-based dynamic combination rules evaluate at interaction time.
• Prerequisite-checked combinations show a distinct refusal when the prerequisite is missing.
• Order-guarded combinations show context-appropriate refusals based on available reference items.
• Successful combinations remove consumed items and add the result item.
• Combination-triggered removals and acquisitions fire the appropriate HUD animations.
• Hover text displays "Use {A} with {B}" when hovering B while A is selected.

AC-7: Item Acquisition

• When an item is acquired, the backpack opens, the item appears, drops in, and the backpack closes.
• A pickup sound plays.
• The item is appended to the inventory and added to the obtained set.
• If another item is currently selected, it is replaced with the newly acquired item.

AC-8: Item Removal

• When an item is removed, the backpack opens, the item appears, slides up and fades, and the backpack closes.
• Quiet removals skip the HUD animation.
• Removed items are taken from the inventory but remain in the obtained set.

AC-9: Bulk Item Removal

• A game event can strip multiple items, with certain protected items exempt.
• Stripped items are stored in a vault for later recovery.
• The obtained-items set is unaffected by bulk removal.

AC-10: Game World Item Use

• Left-clicking an entity with an item selected uses the item on that entity.
• Left-clicking empty space with an item selected shows the item's self-description.
• Right-clicking in the game world returns the item to the backpack.
• The cursor reverts to default after returning an item.

AC-11: Guard Conditions

• Inventory cannot open while a foreground action is running.
• Inventory cannot open during a screen fade transition.
• Inventory cannot open when the game is paused or inactive.
• Hovering over HUD elements prevents game-world interaction.
• Clicking the backpack while a foreground action is running attempts to skip that action.

AC-12: Overlay Interactivity

• The overlay only accepts input when fully opaque.
• During fade-in or fade-out, the overlay renders but does not accept input.
• Items render at the panel's current opacity during transitions.

AC-13: Visual Feedback

• Hover text shows the item name when hovering an item with none selected.
• Hover text shows "Use {A} with {B}" when hovering a different item than the selected one.
• Hover text is cleared when not hovering any item.
• Dragged items follow the cursor in real time.
• The hovered item under the dragged item is tracked for combination hint text.

AC-14: Cursor Behavior

• The cursor reflects the currently selected inventory item.
• Cursor updates are throttled to avoid excessive redraws.
• Each cursor variant has a configurable hotspot offset for accurate click targeting.
• The depressed (mouse-down) cursor state shows a vertically shifted sprite.

13. Godot Node Architecture — Design Brainstorm

The following section explores how this system could be structured using Godot 4's node primitives. These are not prescriptive — they represent one viable approach with trade-offs flagged where relevant.

13.1. High-Level Scene Tree

MainScene (Node2D)                      # Game world layer
├── GameWorld (Node2D)                  # Entities, backgrounds, interactables
├── SubViewportContainer                # Scene fade layer
│   └── SubViewport                     # Contains a ColorRect for screen fades
├── HUD (Control)                       # Top-level UI container
│   ├── InventoryBackpack (Control)     # HUD backpack FSM node
│   │   ├── AnimationPlayer             # Backpack open/close sprite animations
│   │   ├── Sprite2D                    # Backpack sprite
│   │   └── FloatingItem (Control)      # Selected item sprite, positioned relative to backpack
│   │       └── Sprite2D                # Dynamic item sprite
│   ├── SaveButton (Button)
│   └── CloseButton (Button)
└── InventoryOverlay (Control)          # Full-screen overlay, initially hidden
    ├── ColorRect                       # Semi-transparent dark background
    ├── InventoryPanel (Control)        # Decorative frame + item grid
    │   ├── TextureRect                 # Panel frame texture
    │   ├── ItemGrid (HBoxContainer or custom Control)
    │   │   ├── InventorySlot (Control) # One per item, dynamically instantiated
    │   │   │   └── Sprite2D            # Item icon
    │   │   └── ...
    │   └── HoverLabel (Label)          # Bottom text label

Reasoning: The game world lives on the Node2D layer, while all UI sits under Control nodes in a separate canonical layer. This mirrors Godot's recommended separation of 2D game content from UI. The backpack HUD element is a Control node anchored to the screen's top-right corner using anchors/offsets. The inventory overlay is a full-screen Control with anchor_preset set to fill the viewport.

13.2. InventoryBackpack — FSM Implementation

The backpack FSM (Section 4) has several possible implementations in Godot, each with trade-offs:

Option A: Hand-Rolled FSM in GDScript (Recommended for this system)

A single _ready() → _process() or signal-driven FSM on the InventoryBackpack node itself.

# Pseudocode sketch
enum State { IDLE, OPEN, SELECTED, ACQUIRE, REMOVE }
var state := State.IDLE
var pending_transitions : Array[Tuple] = []
var current_transition_steps : Array[Tween] = []

Pros:

• Full control over the multi-step, queued transition sequencing described in §4.2
• Tween objects are fire-and-forget with a finished signal, making it straightforward to chain steps sequentially
• No engine-version dependencies or animation graph learning curve

Cons:

• No graphical state machine editor; transitions must be understood from code
• More boilerplate than a declarative approach

Key Godot API fit:

• create_tween() returns a Tween referenced by Godot 4.6 docs — tweens execute sequentially by default and support tween_property(), tween_callback(), tween_interval(), set_trans(), set_ease() — matching all the animation primitives used here
• The step_finished signal on Tween provides per-step completion notifications, suitable for the FSM's step-by-step sequencing
• bind_node(self) ensures tweens die when the backpack node is freed

Option B: AnimationTree with AnimationNodeStateMachine

Use an AnimationTree node with an AnimationNodeStateMachine as its tree_root, linked to the backpack's AnimationPlayer.

Pros:

• Visual state machine editor in the Godot editor (tree_root property exposes this)
• Godot provides AnimationNodeStateMachine as a first-class resource for AnimationTree
• Transitions between states can use blend times

Cons:

• AnimationTree is designed primarily for character/character-state animations, not UI state — it may be over-engineered here
• Multi-step transitions with conditional logic (e.g., "same item vs different item" removal branches) are awkward to encode purely in the animation graph
• The AnimationTree docs explicitly note that when using AnimationTree, several AnimationPlayer properties and methods "will not function as expected" — playback should be handled solely through the tree, which adds complexity
• The queued transition FIFO mechanism is not native to AnimationNodeStateMachine; would need to be hand-rolled anyway

Verdict: Option A is preferred for this particular FSM because the transition logic has conditional branching and queuing that maps more naturally to code than to an animation graph.

13.3. Tween Usage — Transition Steps

Each multi-step FSM transition (§4.3) can be built as a single Tween with sequentially chained tween_property() calls and tween_callback() for state changes:

# Pseudocode: Idle → Open transition
func transition_to_open():
    var t = create_tween().bind_node(self)
    t.tween_property(backpack_sprite, "rotation", deg_to_rad(-90), 0.35)
       .set_trans(Tween.TRANS_LINEAR)
    t.tween_property(backpack_sprite, "position:y", open_y, 0.35)
       .set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_IN)
    t.tween_property(backpack_sprite, "position:x", open_x, 0.35)
       .set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_IN)
    # Play the open sprite animation, then continue...
    t.tween_callback(self._on_open_animation_done)
    # ... subsequent steps added by the callback

Caveat from docs: Tween objects "are not designed to be reused" — each transition needs a fresh create_tween() call. Also: "tweens start immediately, so only create a Tween when you want to start animating." This means the multi-step approach needs to build the tween incrementally via callbacks, rather than pre-building the entire sequence.

An alternative for fully deterministic sequences is to use AnimationPlayer with tween_callback()-free tracks and await on the animation_finished signal, but this introduces the AnimationTree compatibility issues mentioned above.

13.4. Inventory Overlay — Control Hierarchy

The inventory overlay (§5) maps cleanly to Godot's Control-based UI system:

• The overlay is a full-screen Control with modulate.a (opacity) tweened for fade-in/fade-out
• The "input only when fully visible" guard (§5.4) is implemented by checking modulate.a >= 1.0 in _gui_input() before processing events
• mouse_filter can be set to MOUSE_FILTER_STOP on the overlay's background ColorRect to block input from reaching the game world beneath — confirmed by the Control docs: accept_event() stops propagation, and mouse_filter with MOUSE_FILTER_STOP prevents child nodes behind the control from receiving input

Item Grid Layout

Two approaches for laying out items:

1. GridContainer — Godot's built-in Container with configurable columns. Pros: automatic layout, respects custom_minimum_size, works with the anchor/offset system. Cons: items have to be pre-instantiated or managed dynamically; less control over exact per-cell positioning during drag.

2. Custom Control with manual positioning — A bare Control that computes cell positions in _process() or _notification(NOTIFICATION_DRAW). Pros: full control over drag behavior, hover hit-testing, and real-time position updates. Cons: more code, must handle layout manually.

Recommendation: GridContainer for static layout, with items switched to set_anchors_preset(PRESET_WIDE) or reparented during drag to allow free movement. Alternatively, a Control subclass that computes grid positions in _get_minimum_size() and _layout_children() (Godot 4.3+ pattern for Container-like behavior without the full Container overhead).

Drag and Drop

Godot has a built-in drag-and-drop system via _get_drag_data(), _can_drop_data(), and _drop_data() on Control nodes. However, the inventory's drag behavior (§5.4) has custom requirements:

• Items must follow the mouse cursor in real time (Godot's drag preview is a separate Control returned by _get_drag_data(), which could work, but the PRD requires the actual item sprite to move)
• Drag outside bounds must close the inventory immediately
• Hover state must be tracked under the dragged item for combination hints

Verdict: Godot's built-in drag-and-drop is a partial fit, but the real-time follow-cursor and drag-out-close behaviors are more naturally handled through raw _gui_input() with InputEventMouseButton and InputEventMouseMotion tracking. The drag preview mechanism would require a custom preview Control that follows global mouse coordinates, and the hover-under-drag item tracking would need manual bounding-box checks.

13.5. Cursor System — Custom Cursor

Godot supports custom cursors through Input.set_custom_mouse_cursor(texture) and per-control cursors via Control.mouse_default_cursor_shape. For item-specific cursors:

• Godot's Input.create_custom_cursor(texture, shape, hot_spot) creates a named cursor variant. Each item would register its cursor with a unique name.
• Switching cursors: Input.set_custom_mouse_cursor(cursor_name)
• Hotspot offsets map to the hot_spot parameter of create_custom_cursor() — documented as a Vector2i offset from the top-left of the texture
• The depressed (mouse-down) cursor state would need two cursor textures per item (normal and pressed), or the sprite could be shifted by temporarily adding a vertical offset to the custom cursor's shape

Throttling (§8.1): Godot doesn't have a built-in cursor-update throttle. This would be implemented as a simple timestamp check in _process() comparing against the last cursor switch time.

Alternative: For games with many unique cursor items, some Godot projects skip the OS-level cursor entirely, hide it with Input.set_mouse_mode(Input.MOUSE_MODE_HIDDEN), and draw a custom cursor as a Sprite2D in the game world that follows the mouse position. This gives full control over appearance, hotspot, and depressed-state offset without the overhead of creating many custom cursor resources.

13.6. Global State — Inventory Manager

The player inventory state (§2) needs a globally accessible, persistent data store. Two Godot patterns:

AutoLoad Singleton (Recommended)

A Node exported as an AutoLoad singleton (InventoryManager) holds the inventory list, obtained-items set, and stripped-items vault. Signals are emitted for state changes:

# Pseudocode
extends Node
signal item_acquired(item_id)
signal item_removed(item_id)
signal inventory_changed

var inventory : Array = []
var obtained_items : Array = []      # Used as a set
var stripped_items : Array = []

func has_item(item_id) -> bool: ...
func acquire_item(item_id): ...
func remove_item(item_id): ...

The HUD backpack, inventory overlay, and main scene all connect to this singleton's signals. This avoids tight coupling between the UI layers and the game world.

Autoload + Resource

For save-game persistence, the inventory data could be wrapped in a Resource (custom InventoryResource extending Resource) that the singleton references and saves/loads. This is a common Godot pattern for serializable game state.

13.7. Overlay Fade Layer

The full-screen fade overlay (§5.3) and guard condition fade layer (§9) can share a single CanvasLayer with a ColorRect:

FadeOverlay (CanvasLayer, layer=10)
└── ColorRect                       # color = (0,0,0,0) by default

Tweening ColorRect.modulate.a handles fade-in/out. The CanvasLayer ensures it renders above both the game world and HUD regardless of z-index. Guard conditions check ColorRect.modulate.a > 0.0 to block input.

13.8. Signal Flow Summary

The communication between components would rely on Godot's signal system:

InventoryManager (singleton)
  ├─ signal item_acquired          → InventoryBackpack._on_give_item()
  ├─ signal item_removed           → InventoryBackpack._on_remove_item()
  └─ signal inventory_changed      → InventoryOverlay._refresh_grid()

InventoryBackpack (FSM)
  ├─ signal transition_to_open     → InventoryOverlay._show()
  ├─ signal item_selected(item)    → MainScene._on_item_chose(item)
  └─ signal returning_to_idle      → InventoryOverlay._hide()

InventoryOverlay
  ├─ signal close_requested        → InventoryBackpack.transition_to(State.IDLE)
  ├─ signal combine(items)         → InventoryManager.attempt_combine(items)
  └─ signal inspect(item)          → MainScene.play_ego_script(item)

MainScene
  ├─ signal backpack_clicked       → InventoryBackpack.transition_to(State.OPEN) (guarded)
  ├─ signal world_entity_clicked   → InventoryManager.use_item_on_entity(item, entity)
  └─ script_finished              → Game resumes normal input

13.9. Godot-Specific Considerations and Risks

Concern	Detail
Tween ownership	Godot 4 Tween objects are not reusable. Each FSM transition must create a new Tween. If a transition is interrupted, the old tween should be kill()-ed before starting a new one.
Control vs Node2D mixing	The game world (Node2D) and UI (Control) live in different rendering spaces. Converting between them (e.g., for screen-position calculations) requires get_global_transform_with_canvas() or get_viewport().get_mouse_position().
Input event consumption	The overlay's background ColorRect must use accept_event() in _gui_input() to prevent clicks from reaching the game world behind it. Godot propagates unhandled events to _unhandled_input() on all nodes, so careful ordering is needed.
Anchor-based UI positioning	The backpack HUD icon should use Control anchors for screen-relative positioning (top-right anchor preset), so it stays correctly positioned across screen resolutions.
AnimationPlayer queue	Godot 4's AnimationPlayer.queue() allows queuing animations, but the queue clears on play(). This differs from the PRD's FIFO transition queue, which is why the hand-rolled FSM (Option A) is preferred.
Sprite flipping	The Sprite2D.flip_h property handles horizontal flipping (needed for backpack animations per §11.1).
Custom minimum size	Item cell sizing uses Control.custom_minimum_size to enforce grid cell dimensions, regardless of texture size.

13.10. Input Priority — Layer Suppression Patterns

When the inventory overlay is open, it must take exclusive input priority. The game world, HUD elements (other than the overlay itself), and any background interaction must be suppressed. This section brainstorms common patterns for managing input priority across layered 2D game UI, and how they map to this system.

Pattern 1: Control Hierarchy Input Consumption

How it works: The overlay sits at the top of a Control tree. Its background ColorRect has mouse_filter = MOUSE_FILTER_STOP. Events are consumed in _gui_input() via accept_event(), so they never propagate downward.

Godot mechanics: Per the Control docs, _gui_input() "filters out unrelated input events, such as by checking z-order, mouse_filter, focus, or if the event was inside of the control's bounding box." Calling accept_event() marks the event as handled. Unhandled events reach _unhandled_input() on all nodes.

Pros:

• Simple — a full-screen MOUSE_FILTER_STOP background automatically blocks all mouse input from reaching controls beneath
• No extra logic needed; the engine's event propagation handles it

Cons:

• Only blocks Control-tree input. The game world (Node2D layer) receives input through a separate path: _input() or _unhandled_input(). A Control node consuming an event does NOT prevent _unhandled_input() from firing on Node2D children, because _gui_input() → accept_event() → unhandled is a Control-only pipeline
• Node2D input handlers (_input_event() on Node2D via viewport forwarding) operate independently

Verdict: Necessary but insufficient on its own. This pattern handles Control-vs-Control blocking (overlay blocks HUD), but does NOT handle Control-vs-Node2D blocking (overlay blocks game world).

Pattern 2: Guard Flag (Input Owner)

How it works: A boolean flag (e.g., input_layer_active or overlay_grabs_focus) is set when the overlay opens. Both the overlay and the game world check this flag before processing input.

# Pseudocode
# In InventoryOverlay
func _ready():
    GameInput.input_owner = Self   # Claim input

func _on_close():
    GameInput.input_owner = null   # Release input

# In MainScene (game world)
func _input(event):
    if GameInput.input_owner != null:
        return   # Another layer owns input
    # ... process clicks on entities

Pros:

• Explicit, easy to reason about
• Works across any node types (Node2D, Control, mixed)
• Single source of truth for "who gets input right now"

Cons:

• Every input handler must check the flag — easy to forget, leading to input leaking through
• No engine-level enforcement — it's a convention, not a guarantee
• If multiple layers use the flag, race conditions can occur during transitions (e.g., overlay closing and game world reclaiming input on the same frame)

Variant — Central input router: Instead of a boolean flag, route all input through a single _unhandled_input() handler at the root that dispatches based on a priority stack. This centralizes the guard logic and eliminates the "every layer must check" problem.

Verdict: The guard flag approach is the simplest and most common pattern in small-to-medium Godot projects. Paired with Pattern 1, it covers both Control and Node2D layers.

Pattern 3: CanvasLayer + Viewport Input Forwarding

How it works: Use a CanvasLayer set to a high layer value for the overlay, and accept_event() on its controls. The CanvasLayer renders above the game world. Controls in higher CanvasLayer values receive _gui_input() before lower layers.

Godot mechanics: CanvasLayer controls are composited on top and receive GUI input in layer order. However, Node2D input events still flow through _input_event() independently.

Pros:

• Layer ordering is explicit and editor-visible
• Godot's GUI input pipeline already respects CanvasLayer ordering

Cons:

• Same fundamental limitation as Pattern 1: Node2D input is not suppressed by Control CanvasLayer hierarchy
• CanvasLayer input forwarding is per-layer, not a global gate

Verdict: Useful for organizing Control-layer input priority, but doesn't solve the Node2D crossover problem. Works alongside Pattern 2.

Pattern 4: Engine-Level Input Mode Switch

How it works: When the overlay opens, call Input.set_mouse_mode(Input.MOUSE_MODE_CONFINED) or Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED) to change how the engine handles mouse input.

Pros:

• Engine-enforced — no per-layer checks needed

Cons:

• MOUSE_MODE_CONFINED and MOUSE_MODE_CAPTURED are designed for FPS-style camera control, not for UI layer gating
• MOUSE_MODE_CONFINED keeps the cursor within the viewport bounds, which would interfere with the "drag item outside panel bounds to close" behavior (AC-4) — the cursor can't leave the window
• MOUSE_MODE_CAPTURED hides the cursor entirely
• Neither mode provides layer-selective suppression; it's all-or-nothing

Verdict: Not suitable for this use case. The "drag outside panel bounds" interaction explicitly requires the cursor to be able to leave the inventory area, which these modes prevent.

Pattern 5: _unhandled_input() Gate at Scene Root

How it works: The main scene has a top-level _unhandled_input() handler that checks the overlay's visibility state. If the overlay is active, the handler returns early before any game-world _input_event() handlers are reached.

# Pseudocode in MainScene
func _unhandled_input(event):
    if inventory_overlay.is_visible():
        return   # Overlay owns input; game world does nothing
    if is_instance_valid(clicked_entity):
        clicked_entity.interact(event)

Pros:

• Single gate point — only one place to maintain
• _unhandled_input() fires for events that were NOT consumed by _gui_input(), so it naturally catches the "Control consumed this but Node2D shouldn't" case
• Combines well with Pattern 1: overlay's accept_event() prevents the event from reaching _unhandled_input(), and the gate provides a safety net for edge cases

Cons:

• Requires the game world to use _unhandled_input() instead of _input() — this is actually the recommended Godot pattern for gameplay input anyway
• Some events may reach Node2D children via _input_event() (the viewport's direct forwarding to foreground controls), bypassing _unhandled_input()

Verdict: Strong approach for Godot. The game world should ideally use _unhandled_input() for all gameplay input (Godot's docs recommend this pattern), which naturally gives Control UI priority. Combined with the overlay's background MOUSE_FILTER_STOP, input from both sources is suppressed.

Recommended Combined Approach for This System

No single pattern covers all cases. The robust solution combines multiple layers of defense:

Layer	Mechanism	What it blocks
Overlay background ColorRect	mouse_filter = MOUSE_FILTER_STOP + accept_event() in _gui_input()	Other Control input (HUD buttons, backpack icon)
Game world input	Uses _unhandled_input() instead of _input()	Already filtered by the overlay's accept_event() — unhandled events only reach game world if no Control consumed them
Explicit guard flag	inventory_active boolean on the overlay, checked by game world	Safety net: game world double-checks that overlay is closed before processing any input, including _input_event() from viewport forwarding
CanvasLayer ordering	Overlay CanvasLayer at layer 10, HUD at layer 5, game world at layer 0	Ensures visual and input priority ordering

Transition edge case: During the overlay fade-in/fade-out (§AC-12), the overlay is rendering but shouldn't accept input. The guard flag handles this:

func _on_fade_in_complete():
    overlay.input_active = true    # Only after fade finishes

func _on_fade_out_start():
    overlay.input_active = false   # Immediately when fade begins

This prevents the common bug where the overlay is half-visible, the user clicks, and input goes to neither the overlay nor the game world (the "input black hole" problem).

Summary: What to Watch Out For

1. Node2D vs Control input gap: Control.accept_event() does NOT suppress Node2D._input_event(). This is the most common pitfall. Always pair Control-level blocking with a game-world-side check.
2. Fade transition gap: Input priority must switch exactly at the opacity threshold, not at visibility. The overlay should block input the moment fading begins and release it the moment fading completes (or vice versa, depending on the desired user experience).
3. Drag-out escape: The "drag item outside panel bounds" interaction intentionally sends input past the overlay. This is a controlled exception to the blocking rule — the overlay's _gui_input() must detect the drag-out condition and choose to not accept_event(), allowing the event to fall through to the HUD/game world level. This is the only case where the overlay lets input pass.