@hytopia.com/examples 1.0.3 → 1.0.4

package/frontiers-rpg-game/src/items/BaseItem.ts

@@ -0,0 +1,300 @@
+import {
+  Collider,
+  ColliderShape,
+  CollisionGroup,
+  ErrorHandler,
+  Entity,
+  EntityEvent,
+  QuaternionLike,
+  RgbColor,
+  SceneUI,
+  Vector3Like,
+  World,
+  RigidBodyType,
+} from 'hytopia';
+
+import BaseItemEntity from '../entities/BaseItemEntity';
+import CustomCollisionGroup from '../physics/CustomCollisionGroup';
+import GamePlayerEntity from '../GamePlayerEntity';
+import IInteractable from '../interfaces/IInteractable';
+
+const DEFAULT_MODEL_CHILD_RELATIVE_POSITION = { x: -0.025, y: 0, z: -0.15 };
+const DEFAULT_MODEL_URI = 'models/items/snowball.gltf';
+const DEFAULT_MODEL_SCALE = 0.35;
+
+export const RARITY_RGB_COLORS: Record<ItemRarity, RgbColor> = {
+  common: { r: 225, g: 225, b: 225 },      // Light gray - subtle but visible
+  unusual: { r: 115, g: 215, b: 115 },     // Soft green - not too bright
+  rare: { r: 140, g: 190, b: 255 },        // Sky blue - easier on eyes
+  epic: { r: 200, g: 120, b: 255 },        // Purple - classic epic color - 255, 100, 180
+  legendary: { r: 255, g: 180, b: 50 },    // Golden orange - warm and premium - 255, 180, 50
+  utopian: { r: 255, g: 70, b: 70 },     // Pink-red - unique and special
+};
+
+export enum BaseItemPlayerEvent {
+  PICKED_UP = 'BaseItem.PICKED_UP',
+}
+
+export type BaseItemPlayerEventPayloads = {
+  [BaseItemPlayerEvent.PICKED_UP]: { item: BaseItem };
+}
+
+export type ItemClass = typeof BaseItem;
+
+export type ItemRarity = 'common' | 'unusual' | 'rare' | 'epic' | 'legendary' | 'utopian';
+
+export type ItemOverrides = {
+  quantity?: number;
+};
+
+export default abstract class BaseItem implements IInteractable {
+  // Required static properties that subclasses MUST implement
+  static readonly id: string;
+  static readonly name: string;
+  static readonly iconImageUri: string;
+  
+  // Optional static properties with defaults
+  static readonly buyPrice?: number = undefined;
+  static readonly description: string = '';
+  static readonly dropModelUri?: string = undefined;
+  static readonly dropModelScale: number = DEFAULT_MODEL_SCALE;
+  static readonly dropModelTintColor?: RgbColor = undefined;
+  static readonly heldModelUri?: string = undefined;
+  static readonly heldModelScale: number = DEFAULT_MODEL_SCALE;
+  static readonly heldModelTintColor?: RgbColor = undefined;
+  static readonly defaultRelativePositionAsChild: Vector3Like = DEFAULT_MODEL_CHILD_RELATIVE_POSITION;
+  static readonly defaultRelativeRotationAsChild?: QuaternionLike = undefined;
+  static readonly rarity: ItemRarity = 'common';
+  static readonly sellPrice: number = 1;
+  static readonly statsHeader: string = '';
+  static readonly statTexts: string[] = [];
+  static readonly stackable: boolean = false;
+
+  // Simple factory method
+  static create(overrides?: ItemOverrides): BaseItem {
+    const ItemClass = this as any;
+    return new ItemClass(overrides);
+  }
+
+
+
+  // Instance properties (mostly delegate to static)
+  public get id(): string { return (this.constructor as typeof BaseItem).id; }
+  public get name(): string { return (this.constructor as typeof BaseItem).name; }
+  public get iconImageUri(): string { return (this.constructor as typeof BaseItem).iconImageUri; }
+  public get buyPrice(): number | undefined { return (this.constructor as typeof BaseItem).buyPrice; }
+  public get description(): string { return (this.constructor as typeof BaseItem).description; }
+  public get dropModelUri(): string | undefined { return (this.constructor as typeof BaseItem).dropModelUri; }
+  public get dropModelScale(): number { return (this.constructor as typeof BaseItem).dropModelScale; }
+  public get dropModelTintColor(): RgbColor | undefined { return (this.constructor as typeof BaseItem).dropModelTintColor; }
+  public get heldModelUri(): string | undefined { return (this.constructor as typeof BaseItem).heldModelUri; }
+  public get heldModelScale(): number { return (this.constructor as typeof BaseItem).heldModelScale; }
+  public get heldModelTintColor(): RgbColor | undefined { return (this.constructor as typeof BaseItem).heldModelTintColor; }
+  public get defaultRelativePositionAsChild(): Vector3Like { return (this.constructor as typeof BaseItem).defaultRelativePositionAsChild; }
+  public get defaultRelativeRotationAsChild(): QuaternionLike | undefined { return (this.constructor as typeof BaseItem).defaultRelativeRotationAsChild; }
+  public get rarity(): ItemRarity { return (this.constructor as typeof BaseItem).rarity; }
+  public get sellPrice(): number { return (this.constructor as typeof BaseItem).sellPrice; }
+  public get statsHeader(): string { return (this.constructor as typeof BaseItem).statsHeader; }
+  public get statTexts(): string[] { return (this.constructor as typeof BaseItem).statTexts; }
+  public get stackable(): boolean { return (this.constructor as typeof BaseItem).stackable; }
+
+  // Instance-specific properties that can be overridden
+  private _entity: BaseItemEntity | undefined;
+  private _nameplateSceneUI: SceneUI | undefined;
+  private _quantity: number = 1;
+
+  public constructor(overrides?: ItemOverrides) {
+    const staticClass = this.constructor as typeof BaseItem;
+    
+    if (staticClass.stackable && overrides?.quantity) {
+      this._quantity = overrides.quantity;
+    }
+  }
+
+  public get entity(): Entity | undefined { return this._entity; }
+  public get quantity(): number { return this._quantity; }
+
+  public adjustQuantity(quantity: number): void {
+    if (!this.stackable) {
+      return ErrorHandler.warning(`BaseItem.adjustQuantity(): Item ${this.name} is not stackable.`);
+    }
+    
+    this._quantity += quantity;
+    this._updateNameplateSceneUI();
+  }
+
+  public clone(overrides?: ItemOverrides): BaseItem {
+    const ItemClass = this.constructor as any;
+    return new ItemClass({
+      quantity: this._quantity,
+      ...overrides,
+    });
+  }
+
+  public despawnEntity(): void {
+    if (!this._entity) return;
+    this._entity.despawn();
+  }
+
+  public interact(playerEntity: GamePlayerEntity): void {
+    const wouldAddToSelectedIndex = playerEntity.gamePlayer.hotbar.wouldAddAtSelectedIndex(this);
+    
+    if (wouldAddToSelectedIndex) {
+      this.despawnEntity();
+    }
+
+    if (playerEntity.gamePlayer.hotbar.addItem(this) || playerEntity.gamePlayer.backpack.addItem(this)) {
+      if (!wouldAddToSelectedIndex) {
+        this.despawnEntity();
+      }
+
+      playerEntity.gamePlayer.eventRouter.emit(BaseItemPlayerEvent.PICKED_UP, { item: this });
+    }
+  }
+
+  public setQuantity(quantity: number): void {
+    if (!this.stackable && quantity > 1) {
+      return ErrorHandler.warning(`BaseItem.setQuantity(): Item ${this.name} is not stackable.`);
+    }
+
+    this._quantity = quantity;
+    this._updateNameplateSceneUI();
+  }
+
+  public spawnEntityAsDrop(world: World, position: Vector3Like, rotation?: QuaternionLike): void {
+    if (!this._requireNotSpawned()) return;
+
+    const modelUri = this.dropModelUri ?? DEFAULT_MODEL_URI;
+
+    this._entity = new BaseItemEntity({
+      item: this,
+      name: this.name,
+      modelUri,
+      modelScale: this.dropModelScale,
+      tintColor: this.dropModelTintColor ?? RARITY_RGB_COLORS[this.rarity],
+      rigidBodyOptions: {
+        type: RigidBodyType.DYNAMIC,
+        colliders: [
+          Collider.optionsFromModelUri(modelUri, this.dropModelScale * 4, ColliderShape.BLOCK)
+        ],
+      },
+    });
+
+    this._entity.on(EntityEvent.DESPAWN, () => this._despawnCleanup())
+    this._entity.spawn(world, position, rotation);
+    this._loadNameplateSceneUI();
+    this._afterSpawn();
+  }
+
+  public spawnEntityAsHeld(parent: Entity, parentNodeName?: string, relativePosition?: Vector3Like, relativeRotation?: QuaternionLike): void {
+    if (!this._requireNotSpawned()) return;
+
+    this._entity = new BaseItemEntity({
+      item: this,
+      name: this.name,
+      modelUri: this.heldModelUri ?? DEFAULT_MODEL_URI,
+      modelScale: this.heldModelScale,
+      tintColor: this.heldModelTintColor ?? RARITY_RGB_COLORS[this.rarity],
+      parent: parent,
+      parentNodeName: parentNodeName,
+    });
+
+    this._entity.on(EntityEvent.DESPAWN, () => this._despawnCleanup())
+    this._entity.spawn(
+      parent.world!,
+      relativePosition ?? this.defaultRelativePositionAsChild,
+      relativeRotation ?? this.defaultRelativeRotationAsChild,
+    );
+    this._afterSpawn();
+  }
+
+  public spawnEntityAsEjectedDrop(world: World, position: Vector3Like, facingDirection?: Vector3Like): void {
+    this.spawnEntityAsDrop(world, position);
+    
+    if (this.entity) {
+      const mass = this.entity.mass;
+      const angle = facingDirection 
+        ? Math.atan2(facingDirection.z, facingDirection.x) + (Math.random() * Math.PI/2 - Math.PI/4)
+        : Math.random() * Math.PI * 2;
+      
+      this.entity.applyImpulse({
+        x: mass * Math.cos(angle) * 5,
+        y: mass * 3.5,
+        z: mass * Math.sin(angle) * 5,
+      });
+    }
+  }
+  
+  public splitStack(newStackQuantity: number): BaseItem | undefined {
+    if (!this.stackable) {
+      ErrorHandler.warning(`BaseItem.splitStack(): Item ${this.name} is not stackable.`);
+      return undefined;
+    }
+
+    if (newStackQuantity <= 0 || newStackQuantity >= this._quantity) {
+      ErrorHandler.warning(`BaseItem.splitStack(): Invalid quantity.`);
+      return undefined;
+    }
+
+    this.adjustQuantity(-newStackQuantity);
+    return this.clone({ quantity: newStackQuantity });
+  }
+
+  public useMouseLeft(): void {
+    // Override in subclasses for usable items
+  }
+
+  public useMouseRight(): void {
+    // Override in subclasses for usable items
+  }
+
+  private _afterSpawn(): void {
+    if (!this._entity) return;
+
+    this._entity.setCollisionGroupsForSolidColliders({
+      belongsTo: [ CustomCollisionGroup.ITEM ],
+      collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENVIRONMENT_ENTITY ],
+    });
+  }
+
+  private _despawnCleanup(): void {
+    this._nameplateSceneUI?.unload();
+    this._nameplateSceneUI = undefined;
+    this._entity = undefined; 
+  }
+
+  private _loadNameplateSceneUI(): void {
+    if (this._nameplateSceneUI || !this._entity || !this._entity.world) return;
+
+    this._nameplateSceneUI = new SceneUI({
+      attachedToEntity: this._entity,
+      offset: { x: 0, y: 0.45, z: 0 },
+      templateId: 'item-nameplate',
+      viewDistance: 8,
+      state: {
+        name: this.name,
+        iconImageUri: this.iconImageUri,
+        rarityColor: RARITY_RGB_COLORS[this.rarity],
+        quantity: this.quantity,
+      },
+    });
+
+    this._nameplateSceneUI.load(this._entity.world);
+  }
+
+  private _requireNotSpawned(): boolean {
+    if (this._entity) {
+      ErrorHandler.warning('BaseItem: Item is already spawned.');
+      return false;
+    }
+    return true;
+  }
+
+  private _updateNameplateSceneUI(): void {
+    if (!this._nameplateSceneUI) return;
+
+    this._nameplateSceneUI.setState({
+      quantity: this.quantity,
+    })
+  }
+}

package/frontiers-rpg-game/src/items/BaseWeaponItem.ts

@@ -0,0 +1,184 @@
+import { Entity } from 'hytopia';
+import BaseEntity from '../entities/BaseEntity';
+import BaseItem, { ItemOverrides } from './BaseItem';
+import GamePlayerEntity from '../GamePlayerEntity';
+import { isDamageable } from '../interfaces/IDamageable';
+import type { QuaternionLike, RawShape, Vector3Like } from 'hytopia';
+
+export type BaseWeaponItemAttack = {
+  id?: string;
+  animations: string[];
+  cooldownMs: number;
+  damage: number;
+  damageDelayMs: number;
+  damageVariance?: number; // 0.2 = +/- 20% of damage
+  knockbackForce?: number;
+  reach: number;
+}
+
+export type WeaponOverrides = {
+  attack?: BaseWeaponItemAttack;
+  specialAttack?: BaseWeaponItemAttack;
+} & ItemOverrides;
+  
+export default abstract class BaseWeaponItem extends BaseItem {
+  // Required static properties that weapon subclasses MUST implement
+  static readonly attack: BaseWeaponItemAttack;
+  
+  // Optional static properties with defaults
+  static readonly specialAttack?: BaseWeaponItemAttack = undefined;
+
+  // Simple factory method
+  static create(overrides?: WeaponOverrides): BaseWeaponItem {
+    const ItemClass = this as any;
+    return new ItemClass(overrides);
+  }
+
+  static isWeaponItem(item: BaseItem | typeof BaseItem): item is BaseWeaponItem {
+    if (typeof item === 'function') {
+      return BaseWeaponItem.prototype.isPrototypeOf(item.prototype);
+    }
+
+    return item instanceof BaseWeaponItem;
+  }
+
+  // Instance properties (delegate to static or use overrides)
+  public get attack(): BaseWeaponItemAttack { 
+    return this._attack ?? (this.constructor as typeof BaseWeaponItem).attack; 
+  }
+  public get specialAttack(): BaseWeaponItemAttack { 
+    return this._specialAttack ?? (this.constructor as typeof BaseWeaponItem).specialAttack ?? this.attack; 
+  }
+
+  // Instance-specific properties that can be overridden
+  private readonly _attack?: BaseWeaponItemAttack;
+  private readonly _specialAttack?: BaseWeaponItemAttack;
+  private _attackCooledDownAtMs: number = 0;
+
+  public constructor(overrides?: WeaponOverrides) {
+    super(overrides);
+
+    this._attack = overrides?.attack;
+    this._specialAttack = overrides?.specialAttack;
+  }
+
+  public get canAttack(): boolean { return performance.now() >= this._attackCooledDownAtMs; }
+
+  public override clone(overrides?: WeaponOverrides): BaseWeaponItem {
+    const WeaponClass = this.constructor as any;
+    return new WeaponClass({
+      quantity: this.quantity,
+      attack: this._attack,
+      specialAttack: this._specialAttack,
+      ...overrides,
+    });
+  }
+
+  public override useMouseLeft(): void {
+    this.performAttack();
+  }
+
+  public override useMouseRight(): void {
+    this.performSpecialAttack();
+  }
+
+  public performAttack(): void {
+    if (!this.entity?.parent || !this.canAttack) {
+      return;
+    }
+
+    this.entity.parent.startModelOneshotAnimations(this.attack.animations);
+    this.updateAttackCooldown(this.attack.cooldownMs);
+    setTimeout(() => this.processAttackDamageTargets(this.attack), this.attack.damageDelayMs);
+  }
+
+  public performSpecialAttack(): void {
+    if (!this.entity?.parent || !this.canAttack) {
+      return;
+    }
+
+    this.entity.parent.startModelOneshotAnimations(this.specialAttack.animations);
+    this.updateAttackCooldown(this.specialAttack.cooldownMs);
+    setTimeout(() => this.processAttackDamageTargets(this.specialAttack), this.specialAttack.damageDelayMs);
+  }
+
+  protected calculateDamageWithVariance(baseDamage: number, variance?: number): number {
+    if (!variance) return baseDamage;
+    
+    // variance of 0.2 means damage can be 80% to 120% of base damage
+    const min = baseDamage * (1 - variance);
+    const max = baseDamage * (1 + variance);
+    
+    return Math.floor(min + Math.random() * (max - min));
+  }
+
+  protected processAttackDamageTargets(attack: BaseWeaponItemAttack): void {
+    if (!this.entity?.parent) return;
+
+    const attackPosition = (this.entity.parent as GamePlayerEntity).adjustedRaycastPosition ?? this.entity.parent.position;
+    const attackDirection = (this.entity.parent as GamePlayerEntity).adjustedFacingDirection ?? this.entity.parent.directionFromRotation;
+
+    const target = this.getTargetByRaycast(
+      attackPosition,
+      attackDirection,
+      attack.reach,
+    );
+
+    if (target && !(target instanceof GamePlayerEntity)) { // change this for PVP support later.
+      const damage = this.calculateDamageWithVariance(attack.damage, attack.damageVariance);
+      this.dealDamage(target, damage, attackDirection, attack.knockbackForce);
+    }
+  }
+
+  protected dealDamage(target: Entity, damage: number, knockbackDirection: Vector3Like, knockbackForce?: number): void {
+    if (!isDamageable(target)) {
+      return;
+    }
+
+    target.takeDamage(damage, this.entity?.parent);
+
+    if (knockbackForce && target instanceof BaseEntity && target.pushable) {
+      target.applyImpulse({
+        x: knockbackDirection.x * knockbackForce * target.mass,
+        y: 0,
+        z: knockbackDirection.z * knockbackForce * target.mass,
+      });
+    }
+  }
+
+  protected getTargetsByRawShapeIntersection(rawShape: RawShape, position: Vector3Like, rotation: QuaternionLike, reach: number): Entity[] {
+    if (!this.entity?.parent || !this.entity.parent.world) {
+      return [];
+    }
+    
+    const intersectionsResults = this.entity.parent.world.simulation.intersectionsWithRawShape(
+      rawShape,
+      position,
+      rotation,
+      {
+        filterExcludeRigidBody: this.entity.parent.rawRigidBody, // ignore self (parent/player)
+        filterFlags: 8, // Rapier flag to exclude sensor colliders
+      },
+    );
+
+    return intersectionsResults.map(result => result.intersectedEntity).filter(Boolean) as Entity[];
+  }
+
+  protected getTargetByRaycast(fromPosition: Vector3Like, toDirection: Vector3Like, reach: number): Entity | undefined {
+    if (!this.entity?.parent || !this.entity.parent.world) {
+      return;
+    }
+
+    const raycastResult = this.entity.parent.world.simulation.raycast(fromPosition, toDirection, reach, {
+        filterExcludeRigidBody: this.entity.parent.rawRigidBody, // ignore self (parent/player)
+        filterFlags: 8, // Rapier flag to exclude sensor colliders
+      },
+    );
+
+    return raycastResult?.hitEntity;
+  }
+
+  protected updateAttackCooldown(attackCooldownMs: number): void {
+    this._attackCooledDownAtMs = performance.now() + attackCooldownMs;
+  }
+}

package/frontiers-rpg-game/src/items/BaseWearableItem.ts

@@ -0,0 +1,72 @@
+import BaseItem, { ItemOverrides } from './BaseItem';
+
+export const WEARABLE_SLOTS = ['helmet', 'armor', 'gloves', 'leggings', 'boots', 'accessory'] as const;
+export type WearableSlot = typeof WEARABLE_SLOTS[number];
+  
+export type WearableOverrides = {
+  damageBonus?: number;              // +5 flat outgoing damage
+  damageBonusPercent?: number;       // +15% outgoing damage  
+  damageReduction?: number;          // -3 flat incoming damage
+  damageReductionPercent?: number;   // -20% incoming damage
+} & ItemOverrides;
+
+export default abstract class BaseWearableItem extends BaseItem {
+  // Required static properties that wearable subclasses MUST implement
+  static readonly slot: WearableSlot;
+  
+  // Optional static properties with defaults
+  static readonly damageBonus: number = 0;
+  static readonly damageBonusPercent: number = 0;
+  static readonly damageReduction: number = 0;
+  static readonly damageReductionPercent: number = 0;
+
+  static readonly statsHeader: string = 'When equipped:';
+
+  static isWearableItem(item: BaseItem | typeof BaseItem): item is BaseWearableItem {
+    if (typeof item === 'function') {
+      return BaseWearableItem.prototype.isPrototypeOf(item.prototype);
+    }
+  
+    return item instanceof BaseWearableItem;
+  }
+
+  // Simple factory method
+  static create(overrides?: WearableOverrides): BaseWearableItem {
+    const ItemClass = this as any;
+    return new ItemClass(overrides);
+  }
+
+  // Instance properties (delegate to static or use overrides)
+  public get damageBonus(): number { return this._damageBonus ?? (this.constructor as typeof BaseWearableItem).damageBonus;  }
+  public get damageBonusPercent(): number { return this._damageBonusPercent ?? (this.constructor as typeof BaseWearableItem).damageBonusPercent; }
+  public get damageReduction(): number { return this._damageReduction ?? (this.constructor as typeof BaseWearableItem).damageReduction; }
+  public get damageReductionPercent(): number { return this._damageReductionPercent ?? (this.constructor as typeof BaseWearableItem).damageReductionPercent; }
+  public get slot(): WearableSlot { return (this.constructor as typeof BaseWearableItem).slot;}
+
+  // Instance-specific properties that can be overridden
+  private readonly _damageBonus?: number;
+  private readonly _damageBonusPercent?: number;
+  private readonly _damageReduction?: number;
+  private readonly _damageReductionPercent?: number;
+
+  public constructor(overrides?: WearableOverrides) {
+    super(overrides);
+    
+    this._damageBonus = overrides?.damageBonus;
+    this._damageBonusPercent = overrides?.damageBonusPercent;
+    this._damageReduction = overrides?.damageReduction;
+    this._damageReductionPercent = overrides?.damageReductionPercent;
+  }
+
+  public override clone(overrides?: WearableOverrides): BaseWearableItem {
+    const WearableClass = this.constructor as any;
+    return new WearableClass({
+      quantity: this.quantity,
+      damageBonus: this._damageBonus,
+      damageBonusPercent: this._damageBonusPercent,
+      damageReduction: this._damageReduction,
+      damageReductionPercent: this._damageReductionPercent,
+      ...overrides,
+    });
+  }
+}

package/frontiers-rpg-game/src/items/ItemRegistry.ts

@@ -0,0 +1,49 @@
+import { readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import BaseItem, { ItemClass } from './BaseItem';
+
+export default class ItemRegistry {
+  private static itemRegistry = new Map<string, ItemClass>();
+
+  public static getItemClass(itemId: string): ItemClass | undefined {
+    return this.itemRegistry.get(itemId);
+  }
+
+  public static initializeItems(): void {
+    console.log('Loading items...');
+    
+    const itemFiles = this._findItemFiles(__dirname);
+    let loadedCount = 0;
+    
+    for (const filePath of itemFiles) {
+      try {
+        const ItemClass = require(filePath).default;
+        
+        if (ItemClass?.prototype instanceof BaseItem && ItemClass.id) {
+          this.itemRegistry.set(ItemClass.id, ItemClass);
+          loadedCount++;
+        }
+      } catch (error) {
+        console.warn(`Failed to load item: ${filePath}`);
+      }
+    }
+
+    console.log(`Loaded ${loadedCount} items`);
+  }
+
+  private static _findItemFiles(dir: string): string[] {
+    const files: string[] = [];
+    
+    for (const item of readdirSync(dir)) {
+      const path = join(dir, item);
+      
+      if (statSync(path).isDirectory()) {
+        files.push(...this._findItemFiles(path));
+      } else if (!item.startsWith('Base')) {
+        files.push(path);
+      }
+    }
+
+    return files;
+  }
+}

package/frontiers-rpg-game/src/items/ItemUIDataHelper.ts

@@ -0,0 +1,64 @@
+import BaseItem from './BaseItem';
+import BaseWearableItem from './BaseWearableItem';
+import BaseWeaponItem from './BaseWeaponItem';
+
+export type ItemUIData = {
+  name: string;
+  description: string;
+  iconImageUri: string;
+  buyPrice?: number;
+  sellPrice?: number;
+  quantity?: number;
+  damageBonus?: number;
+  damageBonusPercent?: number;
+  damageReduction?: number;
+  damageReductionPercent?: number;
+  damage?: number;
+  damageVariance?: number;
+  position?: number;
+  statsHeader?: string;
+  statTexts?: string[];
+  type?: string; // UI update type
+}
+
+export type ItemUIDataOverrides = {
+  position?: number;
+  buyPrice?: number;
+  sellPrice?: number;
+  quantity?: number;
+  type?: string;
+}
+
+export class ItemUIDataHelper {
+  static getUIData(itemInstanceOrClass: BaseItem | typeof BaseItem, overrides?: ItemUIDataOverrides): ItemUIData {
+    const uiData: ItemUIData = {
+      name: itemInstanceOrClass.name,
+      description: itemInstanceOrClass.description,
+      iconImageUri: itemInstanceOrClass.iconImageUri,
+      ...overrides,
+    };
+
+    if (BaseWearableItem.isWearableItem(itemInstanceOrClass)) {
+      if (itemInstanceOrClass.damageBonus !== 0) uiData.damageBonus = itemInstanceOrClass.damageBonus;
+      if (itemInstanceOrClass.damageBonusPercent !== 0) uiData.damageBonusPercent = itemInstanceOrClass.damageBonusPercent;
+      if (itemInstanceOrClass.damageReduction !== 0) uiData.damageReduction = itemInstanceOrClass.damageReduction;
+      if (itemInstanceOrClass.damageReductionPercent !== 0) uiData.damageReductionPercent = itemInstanceOrClass.damageReductionPercent;
+    }
+
+    // Add weapon-specific properties if item is a weapon
+    if (BaseWeaponItem.isWeaponItem(itemInstanceOrClass)) {
+      if (itemInstanceOrClass.attack.damage !== 0) uiData.damage = itemInstanceOrClass.attack.damage;
+      if (itemInstanceOrClass.attack.damageVariance !== 0) uiData.damageVariance = itemInstanceOrClass.attack.damageVariance;
+    }
+
+    if (itemInstanceOrClass.statsHeader) {
+      uiData.statsHeader = itemInstanceOrClass.statsHeader;
+    }
+
+    if (itemInstanceOrClass.statTexts.length > 0) {
+      uiData.statTexts = itemInstanceOrClass.statTexts;
+    }
+
+    return uiData;
+  }
+} 

package/frontiers-rpg-game/src/items/consumables/CommonMushroomItem.ts

@@ -0,0 +1,20 @@
+import BaseConsumableItem from '../BaseConsumableItem';
+import type GamePlayerEntity from '../../GamePlayerEntity';
+
+export default class CommonMushroomItem extends BaseConsumableItem {
+  static readonly id = 'common_mushroom';
+  static readonly name = 'Common Mushroom';
+  static readonly iconImageUri = 'icons/items/common-mushroom.png';
+  static readonly consumeCooldownMs = 400;
+  static readonly description = `A normal looking mushroom. It's probably safe to eat.`;
+  static readonly buyPrice = 35;
+  static readonly sellPrice = 3;
+  static readonly stackable = true;
+  static readonly consumeRequiresDamaged = true;
+
+  static readonly statTexts = [ 'Heals 5hp' ];
+
+  protected override applyEffects(playerEntity: GamePlayerEntity): void {
+    playerEntity.gamePlayer.adjustHealth(5);
+  }
+}