Skip to content

Item Logic

ItemLogic allows you to attach custom, scriptable behaviors to items. Instead of writing massive match statements in your player controller, you assign a Logic script to an ItemDefinition, and the logic is written separately so the same behavior can be used on multiple items.

No Automatic Execution

addon provides the ItemLogic classes but does not include a player controller or execution manager. You are responsible for writing the code in your player script that:

  • Detects input actions (use_primary, use_secondary)
  • Calls the corresponding methods on the item's logic script:
  • on_primary_use(slot_index)
  • on_secondary_use(slot_index)
  • update(delta)
  • on_release()

Base Class: ItemLogic (RefCounted)

All custom logic scripts must extend ItemLogic.

Methods called at specific times

# Called when the logic is initialized with the item and the player using it.
func setup(item: ItemDefinition, player: Node) -> void

# Return false to prevent the item from being used (e.g., out of stamina).
func can_use() -> bool

# Called when the player presses the "Primary Use" button (e.g., Left Click).
func on_primary_use(slot_index: int = -1) -> void

# Called when the player presses the "Secondary Use" button (e.g., Right Click).
func on_secondary_use(slot_index: int = -1) -> void

# Called when the player releases the "Use" button (great for charged attacks).
func on_release() -> void

# Called every frame while the item is being held/used.
func update(delta: float) -> void

Signals

  • use_started: Emitted when use begins.
  • use_ended: Emitted when use finishes.
  • use_finished(item: ItemDefinition, success: bool): Emitted with the final result.
  • tool_used(item, user, direction, range): Emitted for tools/weapons hitting something.

Success Parameter Always True

In the current implementation, use_finished always emits true for the success parameter. Code does not yet handle failure states (e.g., interrupted use, insufficient resources). Future versions may emit false in these cases.

Built-in Helper

# Automatically finds the player's InventoryComponent.

Built-in Logic Templates

1. ConsumableLogic

Handles food, potions, and healing items.

  • Properties: hunger_restore, health_restore, stamina_restore, use_duration (timer), consume_sound.

  • Behavior: Waits for use_duration, applies stat effects (requires you to uncomment and hook up your game's SurvivalStats node), removes the item from the inventory, and plays an audio cue.

2. RangedLogic

Handles bows, crossbows, and magic staves.

  • Properties: projectile_scene, charge_speed, max_charge, arrow_tag, draw_sound, release_sound.

  • Behavior: Charges up while on_primary_use is held. On on_release, it searches the inventory for an item with the arrow_tag, consumes it, and spawns the projectile_scene with velocity based on charge time.

3. PlacementLogic

Handles building systems, traps, and placeable objects.

  • Properties: grid_size, use_grid_snap, max_slope_angle, placement_layer_mask, ghost_opacity, rotation_step.

  • Behavior: Spawns a transparent "ghost" preview. Uses raycasting to validate surface angles. Supports grid snapping and rotation via input axes.

  • Signals: placement_started, placement_confirmed, placement_cancelled. ```