@hytopia.com/examples 1.0.3 → 1.0.5

package/frontiers-rpg-game/src/entities/enemies/RatkinWarriorEntity.ts

@@ -0,0 +1,69 @@
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+
+// Drops
+import CommonMushroomItem from "../../items/consumables/CommonMushroomItem";
+import CommonSeedsItem from "../../items/seeds/CommonSeedsItem";
+import GoldItem from "../../items/general/GoldItem";
+import RatkinBonesItem from "../../items/materials/RatkinBonesItem";
+import RatkinEyesItem from "../../items/materials/RatkinEyesItem.ts";
+import RatkinTailItem from "../../items/materials/RatkinTailItem";
+import RatkinToothItem from "../../items/materials/RatkinToothItem.ts";
+
+export type RatkinWarriorEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class RatkinWarriorEntity extends BaseCombatEntity {
+  constructor(options?: RatkinWarriorEntityOptions) {
+    super({
+      aggroRadius: 7.5,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Heavy attack
+          animations: [ 'atk1' ],
+          cooldownMs: 4000,
+          range: 2,
+          simpleAttackDamage: 16,
+          simpleAttackDamageVariance: 0.4, // ±40% damage (12-20)
+          simpleAttackDamageDelayMs: 1000, // Deal damage 1000ms into animation
+          simpleAttackReach: 3,
+          weight: 1,
+        },
+        { // Light attack
+          animations: [ 'atk2' ],
+          cooldownMs: 2000,
+          range: 2,
+          simpleAttackDamage: 9,
+          simpleAttackDamageVariance: 0.1, // ±10% damage (6-8) 
+          simpleAttackDamageDelayMs: 400, // Deal damage 400ms into animation
+          simpleAttackReach: 3,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 15,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 1000,
+      deathItemDrops: [
+        { itemClass: RatkinBonesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinEyesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinToothItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinTailItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: GoldItem, minQuantity: 6, maxQuantity: 15, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 100,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-warrior.gltf',
+      modelScale: 0.8,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 3,
+      name: 'Ratkin Warrior',
+      pathfindingOptions: {
+        maxJump: 2,
+        maxFall: 2,
+      },
+      ...options,
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/enemies/TaintedRatkinBruteEntity.ts

@@ -0,0 +1,80 @@
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+
+// Drops
+import CommonMushroomItem from "../../items/consumables/CommonMushroomItem";
+import CommonSeedsItem from "../../items/seeds/CommonSeedsItem";
+import GoldItem from "../../items/general/GoldItem";
+import RatkinBonesItem from "../../items/materials/RatkinBonesItem";
+import RatkinEyesItem from "../../items/materials/RatkinEyesItem.ts";
+import RatkinTailItem from "../../items/materials/RatkinTailItem";
+import RatkinToothItem from "../../items/materials/RatkinToothItem.ts";
+
+export type TaintedRatkinBruteEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class TaintedRatkinBruteEntity extends BaseCombatEntity {
+  constructor(options?: TaintedRatkinBruteEntityOptions) {
+    super({
+      aggroRadius: 7.5,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Heavy body slam attack
+          animations: [ 'atk1' ],
+          cooldownMs: 3500,
+          range: 2,
+          simpleAttackDamage: 30,
+          simpleAttackDamageVariance: 0.6, // ±60% damage
+          simpleAttackDamageDelayMs: 1000, // Deal damage 1000ms into animation
+          simpleAttackReach: 3,
+          weight: 1,
+        },
+        { // Light hammer swing attack
+          animations: [ 'atk2' ],
+          cooldownMs: 1000,
+          range: 2,
+          simpleAttackDamage: 18,
+          simpleAttackDamageVariance: 0.15, // ±15% damage
+          simpleAttackDamageDelayMs: 500, // Deal damage 500ms into animation
+          simpleAttackReach: 3,
+          weight: 2,
+        },
+        { // Light hammer swing 2 attack
+          animations: [ 'atk3' ],
+          cooldownMs: 1000,
+          range: 2,
+          simpleAttackDamage: 13,
+          simpleAttackDamageVariance: 0.15, // ±15% damage
+          simpleAttackDamageDelayMs: 350, // Deal damage 350ms into animation
+          simpleAttackReach: 3,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 45,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 1000,
+      deathItemDrops: [
+        { itemClass: RatkinBonesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinEyesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinToothItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinTailItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: GoldItem, minQuantity: 11, maxQuantity: 20, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 210,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-brute.gltf',
+      modelScale: 0.675,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 3.325,
+      name: 'Tainted Ratkin Brute',
+      pathfindingOptions: {
+        maxJump: 3,
+        maxFall: 3,
+      },
+      tintColor: { r: 128, g: 255, b: 128 },
+      ...options,
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/enemies/TaintedRatkinRangerEntity.ts

@@ -0,0 +1,90 @@
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+import BaseProjectileEntity from "../BaseProjectileEntity";
+import type { Vector3Like } from 'hytopia';
+
+// Drops
+import CommonMushroomItem from "../../items/consumables/CommonMushroomItem";
+import CommonSeedsItem from "../../items/seeds/CommonSeedsItem";
+import GoldItem from "../../items/general/GoldItem";
+import RatkinBonesItem from "../../items/materials/RatkinBonesItem";
+import RatkinEyesItem from "../../items/materials/RatkinEyesItem.ts";
+import RatkinTailItem from "../../items/materials/RatkinTailItem";
+import RatkinToothItem from "../../items/materials/RatkinToothItem.ts";
+
+
+export type TaintedRatkinRangerEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class TaintedRatkinRangerEntity extends BaseCombatEntity {
+  constructor(options?: TaintedRatkinRangerEntityOptions) {
+    super({
+      aggroRadius: 11,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Fast bow attack
+          animations: [ 'atk1' ],
+          complexAttack: (params) => {
+            this._shootArrow(params.target.position, this.calculateDamageWithVariance(15, 0.5));
+          },
+          complexAttackDelayMs: 700,
+          cooldownMs: 1500,
+          range: 10,
+          weight: 2,
+        },
+        { // Slow heavy bow attack
+          animations: [ 'atk2' ],
+          complexAttack: (params) => {
+            this._shootArrow(params.target.position, this.calculateDamageWithVariance(30, 0.5));
+          },
+          complexAttackDelayMs: 1600,
+          cooldownMs: 2500,
+          range: 10,
+          weight: 3,
+        },
+      ],
+      combatExperienceReward: 30,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 1000,
+      deathItemDrops: [
+        { itemClass: RatkinBonesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinEyesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinToothItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinTailItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: GoldItem, minQuantity: 9, maxQuantity: 17, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 150,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-ranger.gltf',
+      modelScale: 0.9,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 4,
+      name: 'Tainted Ratkin Ranger',
+      pathfindingOptions: {
+        maxJump: 3,
+        maxFall: 3,
+      },
+      tintColor: { r: 128, g: 255, b: 128 },
+      ...options,
+    });
+  }
+
+  private _shootArrow(targetPosition: Vector3Like, damage: number) {
+    if (!this.world) return;
+    
+    const arrow = new BaseProjectileEntity({
+      damage,
+      despawnAfterMs: 1000,
+      direction: this.calculateDirectionToTargetPosition(targetPosition),
+      gravityScale: 0.1,
+      modelUri: 'models/projectiles/arrow.glb',
+      modelScale: 0.75,
+      speed: 30,
+      source: this,
+    });
+    
+    arrow.spawn(this.world, this.position, this.rotation);
+  }
+}

package/frontiers-rpg-game/src/entities/enemies/TaintedRatkinSpellcasterEntity.ts

@@ -0,0 +1,78 @@
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+import BaseProjectileEntity from "../BaseProjectileEntity";
+import type { Vector3Like } from 'hytopia';
+
+// Drops
+import CommonMushroomItem from "../../items/consumables/CommonMushroomItem";
+import CommonSeedsItem from "../../items/seeds/CommonSeedsItem";
+import GoldItem from "../../items/general/GoldItem";
+import RatkinBonesItem from "../../items/materials/RatkinBonesItem";
+import RatkinEyesItem from "../../items/materials/RatkinEyesItem.ts";
+import RatkinTailItem from "../../items/materials/RatkinTailItem";
+import RatkinToothItem from "../../items/materials/RatkinToothItem.ts";
+
+export type TaintedRatkinSpellcasterEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class TaintedRatkinSpellcasterEntity extends BaseCombatEntity {
+  constructor(options?: TaintedRatkinSpellcasterEntityOptions) {
+    super({
+      aggroRadius: 12,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Fireball attack
+          animations: [ 'atk1' ],
+          complexAttack: (params) => {
+            this._shootFireball(params.target.position, this.calculateDamageWithVariance(45, 0.5));
+          },
+          complexAttackDelayMs: 1000,
+          cooldownMs: 4500,
+          range: 10,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 30,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 1000,
+      deathItemDrops: [
+        { itemClass: RatkinBonesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinEyesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinToothItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinTailItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: GoldItem, minQuantity: 9, maxQuantity: 17, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 150,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-spellcaster.gltf',
+      modelScale: 0.9,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 4,
+      name: 'Tainted Ratkin Spellcaster',
+      pathfindingOptions: {
+        maxJump: 3,
+        maxFall: 3,
+      },
+      tintColor: { r: 128, g: 255, b: 128 },
+      ...options,
+    });
+  }
+
+  private _shootFireball(targetPosition: Vector3Like, damage: number) {
+    if (!this.world) return;
+
+    const fireball = new BaseProjectileEntity({
+      damage,
+      despawnAfterMs: 2000,
+      direction: this.calculateDirectionToTargetPosition(targetPosition),
+      gravityScale: 0,
+      modelUri: 'models/projectiles/fireball.glb',
+      speed: 15,
+      source: this,
+    });
+    
+    fireball.spawn(this.world, this.position, this.rotation);
+  }
+}

package/frontiers-rpg-game/src/entities/enemies/TaintedRatkinWarriorEntity.ts

@@ -0,0 +1,70 @@
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+
+// Drops
+import CommonMushroomItem from "../../items/consumables/CommonMushroomItem";
+import CommonSeedsItem from "../../items/seeds/CommonSeedsItem";
+import GoldItem from "../../items/general/GoldItem";
+import RatkinBonesItem from "../../items/materials/RatkinBonesItem";
+import RatkinEyesItem from "../../items/materials/RatkinEyesItem.ts";
+import RatkinTailItem from "../../items/materials/RatkinTailItem";
+import RatkinToothItem from "../../items/materials/RatkinToothItem.ts";
+
+export type TaintedRatkinWarriorEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class TaintedRatkinWarriorEntity extends BaseCombatEntity {
+  constructor(options?: TaintedRatkinWarriorEntityOptions) {
+    super({
+      aggroRadius: 7.5,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Heavy attack
+          animations: [ 'atk1' ],
+          cooldownMs: 3500,
+          range: 2,
+          simpleAttackDamage: 35,
+          simpleAttackDamageVariance: 0.4, // ±40% damage (15-35)
+          simpleAttackDamageDelayMs: 1000, // Deal damage 1000ms into animation
+          simpleAttackReach: 3,
+          weight: 1,
+        },
+        { // Light attack
+          animations: [ 'atk2' ],
+          cooldownMs: 1500,
+          range: 2,
+          simpleAttackDamage: 15,
+          simpleAttackDamageVariance: 0.1, // ±10% damage (9-11) 
+          simpleAttackDamageDelayMs: 400, // Deal damage 400ms into animation
+          simpleAttackReach: 3,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 25,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 1000,
+      deathItemDrops: [
+        { itemClass: RatkinBonesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinEyesItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinToothItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: RatkinTailItem, minQuantity: 1, maxQuantity: 3, weight: 4 },
+        { itemClass: GoldItem, minQuantity: 9, maxQuantity: 17, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 150,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-warrior.gltf',
+      modelScale: 0.9,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 4,
+      name: 'Tainted Ratkin Warrior',
+      pathfindingOptions: {
+        maxJump: 3,
+        maxFall: 3,
+      },
+      tintColor: { r: 128, g: 255, b: 128 },
+      ...options,
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/environmental/SpiderWebEntity.ts

@@ -0,0 +1,23 @@
+import { Collider, Entity, EntityOptions, RigidBodyType } from 'hytopia';
+
+export type SpiderWebEntityOptions = {
+
+} & EntityOptions;
+
+export default class SpiderWebEntity extends Entity {
+  public constructor(options?: SpiderWebEntityOptions) {
+    super({
+      ...options,
+      modelUri: 'models/vfx/spider-web.gltf',
+      rigidBodyOptions: {
+        type: RigidBodyType.DYNAMIC,
+        colliders: [
+          {
+            ...Collider.optionsFromModelUri('models/vfx/spider-web.gltf'),
+            isSensor: true,
+          }
+        ]
+      }
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/forageables/DecayingPileEntity.ts

@@ -0,0 +1,38 @@
+import BaseForageableEntity, { BaseForageableEntityOptions } from '../BaseForageableEntity';
+
+// Forageable Items
+import CommonMushroomItem from '../../items/consumables/CommonMushroomItem';
+import CommonSeedsItem from '../../items/seeds/CommonSeedsItem';
+import GoldItem from '../../items/general/GoldItem';
+import MinorHealingPotionItem from '../../items/consumables/MinorHealingPotionItem';
+import MonsterHideItem from '../../items/materials/MonsterHideItem';
+import StonebellyFungusMushroomItem from '../../items/consumables/StonebellyFungusMushroomItem';
+import UnusualSeedsItem from '../../items/seeds/UnusualSeedsItem';
+
+export type DecayingPileEntityOptions = {
+
+} & BaseForageableEntityOptions;
+
+export default class DecayingPileEntity extends BaseForageableEntity {
+  public constructor(options?: DecayingPileEntityOptions) {
+    super({
+      forageDurationMs: 2000,
+      itemDrops: [
+        { itemClass: CommonMushroomItem, weight: 100, minQuantity: 1, maxQuantity: 3 },
+        { itemClass: CommonSeedsItem, weight: 35 },
+        { itemClass: GoldItem, weight: 15, minQuantity: 9, maxQuantity: 20 },
+        { itemClass: MinorHealingPotionItem, weight: 25 },
+        { itemClass: MonsterHideItem, weight: 12 },
+        { itemClass: StonebellyFungusMushroomItem, weight: 5, minQuantity: 1, maxQuantity: 3 },
+        { itemClass: UnusualSeedsItem, weight: 3 },
+      ],
+      maxDropsPerForage: 3,
+      experienceReward: 15,
+      modelUri: 'models/forageables/decaying-pile.gltf',
+      modelLoopedAnimations: [ 'idle' ],
+      modelScale: 1.2,
+      name: 'Decaying Pile',
+      ...options,
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/forageables/RottenLogEntity.ts

@@ -0,0 +1,37 @@
+import BaseForageableEntity, { BaseForageableEntityOptions } from '../BaseForageableEntity';
+
+// Forageable Items
+import CommonMushroomItem from '../../items/consumables/CommonMushroomItem';
+import CommonSeedsItem from '../../items/seeds/CommonSeedsItem';
+import EmbercapMushroomItem from '../../items/consumables/EmbercapMushroomItem';
+import GoldItem from '../../items/general/GoldItem';
+import MinorHealingPotionItem from '../../items/consumables/MinorHealingPotionItem';
+import MonsterHideItem from '../../items/materials/MonsterHideItem';
+import UnusualSeedsItem from '../../items/seeds/UnusualSeedsItem';
+
+export type RottenLogEntityOptions = {
+
+} & BaseForageableEntityOptions;
+
+export default class RottenLogEntity extends BaseForageableEntity {
+  public constructor(options?: RottenLogEntityOptions) {
+    super({
+      forageDurationMs: 2000,
+      itemDrops: [
+        { itemClass: CommonMushroomItem, weight: 100, minQuantity: 1, maxQuantity: 3 },
+        { itemClass: CommonSeedsItem, weight: 25 },
+        { itemClass: MinorHealingPotionItem, weight: 25 },
+        { itemClass: GoldItem, weight: 15, minQuantity: 6, maxQuantity: 17 },
+        { itemClass: MonsterHideItem, weight: 10 },
+        { itemClass: EmbercapMushroomItem, weight: 5, minQuantity: 1, maxQuantity: 3 },
+        { itemClass: UnusualSeedsItem, weight: 1 },
+      ],
+      maxDropsPerForage: 3,
+      experienceReward: 8,
+      modelUri: 'models/forageables/fallen-log.gltf',
+      modelScale: 0.5,
+      name: 'Rotten Log',
+      ...options,
+    });
+  }
+}

package/frontiers-rpg-game/src/entities/npcs/CapfolkElderEntity.ts

@@ -10,7 +10,6 @@ export default class CapfolkElderEntity extends BaseEntity {
       moveAnimationSpeed: 2,
       moveSpeed: 3,
       name: 'Capfolk Elder',
-      pushable: false,
       ...options,
     });
   }

package/frontiers-rpg-game/src/entities/npcs/CapfolkKnightEntity.ts

@@ -10,7 +10,6 @@ export default class CapfolkKnightEntity extends BaseEntity {
       moveAnimationSpeed: 2,
       moveSpeed: 3,
       name: 'Capfolk Knight',
-      pushable: false,
       ...options,
     });
   }

package/frontiers-rpg-game/src/entities/npcs/CapfolkVillagerEntity.ts

@@ -1,16 +1,15 @@
 import BaseEntity, { BaseEntityOptions } from '../BaseEntity';
 
-export default class CapfolkBoyEntity extends BaseEntity {
+export default class CapfolkVillagerEntity extends BaseEntity {
   public constructor(options?: BaseEntityOptions) {
     super({
       idleAnimations: [ 'idle' ],
       modelUri: 'models/npcs/mushroom-boy.gltf',
       modelScale: 0.5 + Math.random() * 0.15,
       moveAnimations: [ 'walk' ],
-      moveAnimationSpeed: 2,
-      moveSpeed: 3,
-      name: 'Capfolk Boy',
-      pushable: false,
+      moveAnimationSpeed: 3,
+      moveSpeed: 2.5,
+      name: 'Capfolk Villager',
       ...options,
     });
   }

package/frontiers-rpg-game/src/interfaces/IDamageable.ts

@@ -0,0 +1,13 @@
+import type { Entity } from 'hytopia';
+
+
+export default interface IDamageable {
+  takeDamage(damage: number, attacker?: Entity): void;
+}
+
+/**
+ * Type guard to check if an entity implements IDamageable
+ */
+export function isDamageable(target: any): target is IDamageable {
+  return target && typeof target.takeDamage === 'function';
+}

package/frontiers-rpg-game/src/interfaces/IInteractable.ts

@@ -0,0 +1,5 @@
+import type GamePlayerEntity from '../GamePlayerEntity';
+
+export default interface IInteractable {
+  interact(playerEntity: GamePlayerEntity): void;
+}

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

@@ -0,0 +1,98 @@
+import BaseItem, { ItemOverrides } from './BaseItem';
+import GamePlayerEntity from '../GamePlayerEntity';
+
+export type ConsumableOverrides = {
+  consumeAnimations?: string[];
+  consumeCooldownMs?: number;
+  consumeRequiresDamaged?: boolean;
+} & ItemOverrides;
+
+export default abstract class BaseConsumableItem extends BaseItem {
+  // Required static properties that consumable subclasses MUST implement
+  static readonly consumeCooldownMs: number;
+  
+  // Optional static properties with defaults
+  static readonly consumeAnimations: string[] = ['consume-upper'];
+  static readonly consumeRequiresDamaged: boolean = false;
+  
+  static readonly statsHeader: string = 'When consumed:';
+
+  // Simple factory method
+  static create(overrides?: ConsumableOverrides): BaseConsumableItem {
+    const ItemClass = this as any;
+    return new ItemClass(overrides);
+  }
+
+  // Instance properties (delegate to static or use overrides)
+  public get consumeAnimations(): string[] { 
+    return this._consumeAnimations ?? (this.constructor as typeof BaseConsumableItem).consumeAnimations; 
+  }
+  public get consumeCooldownMs(): number { 
+    return this._consumeCooldownMs ?? (this.constructor as typeof BaseConsumableItem).consumeCooldownMs; 
+  }
+  public get consumeRequiresDamaged(): boolean { 
+    return this._consumeRequiresDamaged ?? (this.constructor as typeof BaseConsumableItem).consumeRequiresDamaged; 
+  }
+
+  // Instance-specific properties that can be overridden
+  private readonly _consumeAnimations?: string[];
+  private readonly _consumeCooldownMs?: number;
+  private readonly _consumeRequiresDamaged?: boolean;
+  private _lastConsumeTimeMs: number = 0;
+
+  public constructor(overrides?: ConsumableOverrides) {
+    super(overrides);
+    
+    this._consumeAnimations = overrides?.consumeAnimations;
+    this._consumeCooldownMs = overrides?.consumeCooldownMs;
+    this._consumeRequiresDamaged = overrides?.consumeRequiresDamaged;
+  }
+
+  public override clone(overrides?: ConsumableOverrides): BaseConsumableItem {
+    const ConsumableClass = this.constructor as any;
+    return new ConsumableClass({
+      quantity: this.quantity,
+      consumeAnimations: this._consumeAnimations,
+      consumeCooldownMs: this._consumeCooldownMs,
+      consumeRequiresDamaged: this._consumeRequiresDamaged,
+      ...overrides,
+    });
+  }
+
+  public consume(): void {
+    if (!this.entity?.parent) return;
+
+    const now = performance.now();
+
+    if (now - this._lastConsumeTimeMs < this.consumeCooldownMs) {
+      return;
+    }
+    
+    const gamePlayerEntity = this.entity.parent as GamePlayerEntity;
+    const gamePlayer = gamePlayerEntity.gamePlayer;
+
+    if (this.consumeRequiresDamaged && !gamePlayerEntity.isDamaged) {
+      return;
+    }
+
+    const itemInventory = 
+      gamePlayer.hotbar.getItemPosition(this) !== null ? gamePlayer.hotbar : 
+      gamePlayer.backpack.getItemPosition(this) !== null ? gamePlayer.backpack : null;
+   
+    if (!itemInventory || !gamePlayer.adjustInventoryItemQuantityByReference(itemInventory, this, -1)) {
+      return;
+    }
+
+    this._lastConsumeTimeMs = now;
+    gamePlayerEntity.startModelOneshotAnimations(this.consumeAnimations);
+    this.applyEffects(gamePlayerEntity);
+  }
+
+  protected applyEffects(playerEntity: GamePlayerEntity): void {
+    // Override in subclasses to apply specific effects (healing, buffs, etc.)
+  }
+
+  public override useMouseLeft(): void {
+    this.consume();
+  }
+}