Item System - UQcsse3200/2026-studio-2 GitHub Wiki

Item System

The Item System defines collectible and usable items that can be stored in the player's inventory. Each item is represented by an Item object, while static item data such as names, descriptions, textures, combat values, and effect values are centrally defined in ItemType.

This keeps inventory, item UI, item spawning, and item-use logic consistent by avoiding duplicated item attributes.

Key Components

ItemType

ItemType is the central catalogue of all supported item types:

  • STANDARD_ARROW
  • ROPE_ARROW
  • FIRE_ARROW
  • ICE_ARROW
  • HEALTH_POTION
  • SpeedPotion
  • PoisonPotion

It stores static information including:

  • Numeric ID
  • Display name and description
  • Inventory texture path
  • Projectile texture path for fired arrows
  • Damage, range, and cooldown
  • Healing amount
  • Ammo-consumption behaviour
  • Burn damage and duration
  • Slow multiplier and duration
  • Speed boost and duration
  • Poison damage and duration

ItemType also identifies whether an item is an arrow through isArrow() and converts inventory arrow types to combat arrow types through toArrowType().

Item

The abstract base class for all inventory items. It stores:

  • ItemType
  • Current stack quantity

Item ID, name, and description are retrieved from ItemType. Quantity is changed only through addQuantity() and removeQuantity().

ItemComponent

A component attached to item entities in the world. It stores the Item that the player receives when the entity is collected.

Arrow

Arrow is the inventory item class for stackable arrow ammunition. It retrieves arrow properties from ItemType, including:

  • Damage
  • Range
  • Cooldown
  • Ammo consumption
  • Fire burn damage and duration
  • Ice slow multiplier and duration

Standard, rope, fire, and ice arrows are distinguished by their ItemType.

Consumable

Consumable is the abstract base class for items consumed on use.

Current consumables are:

  • HealthPotion — restores player health.
  • SpeedPotion — temporarily increases player movement speed.
  • PoisonPotion — throws a poison flask that applies 3 damage per second for 3 seconds on impact.

UML Diagram

ItemSys

Item Usage

Items are used through ItemUseComponent, which responds to "attack", "useItem", "shoot", and "stopShoot" events based on the currently selected inventory item.

Selected Item Behaviour
STANDARD_ARROW Removes one standard arrow and triggers the primary bow attack.
FIRE_ARROW Removes one Fire Arrow, triggers the primary bow attack, and applies burn on a successful hit.
ICE_ARROW Removes one Ice Arrow, triggers the primary bow attack, and applies slow on a successful hit.
ROPE_ARROW Does not reduce quantity. Holding the shoot button starts a charge with "grappleDrawStart" and releasing it fires with "grappleDrawRelease"; the use/attack key fires immediately with "grappleFire". See Player Grappling.
HEALTH_POTION Removes one potion and restores player health.
SpeedPotion Removes one potion and triggers a temporary speed boost.
PoisonPotion Removes one potion and throws a poison projectile in the aim direction. It applies 3 poison damage per second for 3 seconds on impact, then expires on impact or at its maximum range.

Key Public Methods

Method Purpose
Item.getItemType() Returns the inventory item type.
Item.getItemId() Returns the numeric ID defined by ItemType.
Item.getQuantity() Returns the current stack quantity.
Item.addQuantity(amount) Adds to an existing item stack.
Item.removeQuantity(amount) Removes quantity when an item is consumed or fired.
ItemType.getDamage() Returns an item's base damage.
ItemType.getRange() Returns an item's configured range value.
ItemType.getCooldown() Returns an item's cooldown value.
ItemType.getProjectileTexturePath() Returns the fired projectile texture for an arrow type.
ItemType.isArrow() Checks whether an item is arrow ammunition.
ItemType.toArrowType() Converts an inventory arrow type to a combat ArrowType.
ItemUseComponent.useSelectedItem() Uses the currently selected inventory item.

Example Usage

Arrow arrow = new Arrow(ItemType.STANDARD_ARROW, 5);

if (arrow.removeQuantity(1)) {
  int damage = arrow.getDamage();
  float range = arrow.getRange();
}

HealthPotion potion = new HealthPotion(2);

if (potion.useConsumable()) {
  int healing = potion.getTreatment();
}

Testing

Item tests cover the main behaviours of the system, including:

  • Item data storage through ItemComponent
  • Standard arrow usage and quantity reduction
  • Separate handling of standard arrows and rope arrows
  • Rope arrow cooldown without ammo consumption
  • Health Potion restores health and cannot be used when the player is already at full health.
  • Speed Potion activation and prevention of overlapping speed boosts.
  • Poison Potion projectile creation, collision behaviour, poison-effect application, and expiry.
  • Item-use success and failure events

These tests ensure that items keep their expected attributes and that ItemUseComponent correctly handles arrows, rope arrows, and consumables.