@hytopia.com/examples 1.0.3 → 1.0.4

package/frontiers-rpg-game/src/entities/BaseMerchantEntity.ts

@@ -0,0 +1,149 @@
+import BaseEntity, { BaseEntityOptions } from './BaseEntity';
+import { ItemUIDataHelper } from '../items/ItemUIDataHelper';
+import { SkillId } from '../config';
+import type { ItemClass } from '../items/BaseItem';
+import type { BaseEntityDialogueOption } from './BaseEntity';
+import type GamePlayerEntity from '../GamePlayerEntity';
+import type ItemInventory from '../systems/ItemInventory';
+
+export type BaseMerchantEntityOptions = {
+  additionalDialogueOptions?: BaseEntityDialogueOption[];
+  buyableItemClasses: ItemClass[];
+  dialogueAvatarImageUri: string;
+  dialogueTitle: string;
+} & BaseEntityOptions;
+
+export default class BaseMerchantEntity extends BaseEntity {
+  public readonly buyableItemClasses: ItemClass[];
+
+  public constructor(options: BaseMerchantEntityOptions) {
+    super({
+      ...options,
+      dialogue: {
+        avatarImageUri: options.dialogueAvatarImageUri,
+        title: options.dialogueTitle,
+        dialogue: {
+          text: 'Welcome! How can I help you today?',
+          options: [
+            {
+              text: `Buy items.`,
+              onSelect: (interactor: GamePlayerEntity) => this.openBuyMenu(interactor),
+              dismiss: true,
+            },
+            {
+              text: `Sell items.`,
+              onSelect: (interactor: GamePlayerEntity) => this.openSellMenu(interactor),
+              dismiss: true,
+            },
+            ...(options.additionalDialogueOptions ?? []),
+            {
+              text: `I don't need anything.`,
+              dismiss: true,
+              pureExit: true,
+            },
+          ],
+        }
+      }
+    });
+
+    this.buyableItemClasses = options.buyableItemClasses;
+  }
+
+  public buyItem(interactor: GamePlayerEntity, buyableItemIndex: number, quantity: number): void {
+    const itemClass = this.buyableItemClasses[buyableItemIndex];
+
+    if (!itemClass?.buyPrice || quantity <= 0) {
+      return; // TODO: Show error message - invalid item or quantity
+    }
+
+    const totalGoldCost = itemClass.buyPrice * quantity;
+    const totalEmptySlots = interactor.gamePlayer.hotbar.totalEmptySlots + interactor.gamePlayer.backpack.totalEmptySlots;
+    const slotsNeeded = itemClass.stackable ? 1 : quantity;
+
+    if (totalEmptySlots < slotsNeeded) {
+      return interactor.showNotification('Not enough inventory space.', 'error');
+    }
+
+    if (!interactor.adjustGold(-totalGoldCost)) {
+      return interactor.showNotification('Not enough gold.', 'error');
+    }
+
+    // Create and add items based on stackability
+    if (itemClass.stackable) {
+      const boughtItem = itemClass.create({ quantity });
+      interactor.gamePlayer.hotbar.addItem(boughtItem) || interactor.gamePlayer.backpack.addItem(boughtItem);
+    } else {
+      for (let i = 0; i < quantity; i++) {
+        const boughtItem = itemClass.create();
+        interactor.gamePlayer.hotbar.addItem(boughtItem) || interactor.gamePlayer.backpack.addItem(boughtItem);
+      }
+    }
+
+    this._awardBarteringSkillExperience(interactor, totalGoldCost, true);
+    interactor.showNotification(`Bought ${quantity} ${itemClass.name} for ${totalGoldCost.toLocaleString()} gold.`, 'success');
+  }
+
+  public openBuyMenu(interactor: GamePlayerEntity): void {
+    interactor.setCurrentMerchantEntity(this);
+    interactor.player.ui.sendData({
+      type: 'toggleMerchant',
+      mode: 'buy',
+      merchantName: this.name,
+      merchantTitle: this.dialogueRoot?.title,
+      merchantAvatarUri: this.dialogueRoot?.avatarImageUri,
+      buyableItems: this.buyableItemClasses.map((itemClass, index) => {
+        return ItemUIDataHelper.getUIData(itemClass, {
+          position: index,
+          buyPrice: itemClass.buyPrice,
+        });
+      }),
+    })
+  }
+
+  public openSellMenu(interactor: GamePlayerEntity): void {
+    interactor.setCurrentMerchantEntity(this);
+    interactor.player.ui.sendData({
+      type: 'toggleMerchant',
+      mode: 'sell',
+      merchantName: this.name,
+      merchantTitle: this.dialogueRoot?.title,
+      merchantAvatarUri: this.dialogueRoot?.avatarImageUri,
+    });
+  }
+
+  public sellItem(interactor: GamePlayerEntity, itemInventory: ItemInventory, itemIndex: number, quantity: number): void {
+    const item = itemInventory.getItemAt(itemIndex);
+   
+    if (!item || quantity <= 0 || quantity > item.quantity) {
+      return interactor.showNotification('Invalid item or quantity.', 'error');
+    }
+
+    if (item.sellPrice === 0) {
+      return interactor.showNotification('Item is not sellable.', 'error');
+    }
+
+    const totalGoldEarned = item.sellPrice * quantity;
+    const isSellingAll = quantity === item.quantity;
+
+    if (isSellingAll) {
+      // Remove item first to free slot, then add gold (guaranteed to work)
+      itemInventory.removeItem(itemIndex);
+      interactor.adjustGold(totalGoldEarned);
+    } else {
+      // For partial sales, try gold first (must stack with existing), then adjust quantity
+      if (!interactor.adjustGold(totalGoldEarned)) {
+        return interactor.showNotification('Your inventory seems full. You cannot receive any gold.', 'error');
+      }
+
+      itemInventory.adjustItemQuantity(itemIndex, -quantity);
+    }
+
+    this._awardBarteringSkillExperience(interactor, totalGoldEarned, false);
+    interactor.showNotification(`Sold ${quantity} ${item.name} for ${totalGoldEarned.toLocaleString()} gold.`, 'success');
+  }
+
+  private _awardBarteringSkillExperience(interactor: GamePlayerEntity, transactionGoldAmount: number, isBuying: boolean): void {
+    const baseExperience = Math.max(5, Math.sqrt(transactionGoldAmount) * 2);
+    interactor.adjustSkillExperience(SkillId.BARTERING, Math.floor(isBuying ? baseExperience : baseExperience * 0.7));
+  }
+}

package/frontiers-rpg-game/src/entities/BaseProjectileEntity.ts

@@ -0,0 +1,73 @@
+import {
+  BlockType,
+  Collider,
+  Entity,
+  EntityOptions,
+  RigidBodyType,
+  Vector3Like,
+} from 'hytopia';
+import { isDamageable } from '../interfaces/IDamageable';
+
+export type BaseProjectileEntityOptions = {
+  damage: number;
+  despawnAfterMs: number;
+  direction: Vector3Like;
+  gravityScale?: number;
+  source: Entity;
+  speed: number;
+} & EntityOptions;
+
+export default class BaseProjectileEntity extends Entity {
+  public readonly damage: number;
+  public readonly direction: Vector3Like;
+  public readonly source: Entity;
+  public readonly speed: number;
+  private _despawnTimeout: NodeJS.Timeout | undefined;
+
+  constructor(options: BaseProjectileEntityOptions) {
+    const { damage, direction, source, speed, ...rest } = options;
+    
+    super({
+      ...rest,
+      rigidBodyOptions: {
+        type: RigidBodyType.DYNAMIC,
+        gravityScale: options.gravityScale ?? 1,
+        linearVelocity: {
+          x: direction.x * speed,
+          y: direction.y * speed,
+          z: direction.z * speed,
+        },
+        colliders: [
+          {
+            ...Collider.optionsFromModelUri('models/projectiles/arrow.gltf'),
+            isSensor: true,
+            onCollision: (other, started) => this.onCollision(other, started),
+          }
+        ],
+      }
+    });
+
+    this.damage = damage;
+    this.direction = direction;
+    this.source = source;
+    this.speed = speed;
+
+    this._despawnTimeout = setTimeout(this.safeDespawn, options.despawnAfterMs);
+  }
+
+  protected safeDespawn = (): void => {
+    if (!this.isSpawned) return;
+    this.despawn();
+  }
+
+  protected onCollision = (other: BlockType | Entity, started: boolean) => {
+    if (!started || other === this.source) return;
+    
+    if (isDamageable(other)) {
+      other.takeDamage(this.damage);
+    }
+
+    clearTimeout(this._despawnTimeout);
+    this.safeDespawn();
+  }
+}

package/frontiers-rpg-game/src/entities/PortalEntity.ts

@@ -0,0 +1,66 @@
+import {
+  BlockColliderOptions,
+  Collider,
+  ColliderShape,
+  Entity,
+  ErrorHandler,
+  ModelEntityOptions,
+  QuaternionLike,
+  RigidBodyType,
+  Vector3Like
+} from 'hytopia';
+
+import GameManager from '../GameManager';
+import GamePlayerEntity from '../GamePlayerEntity';
+
+export type PortalEntityOptions = {
+  destinationRegionId: string;
+  destinationRegionFacingAngle?: number;
+  destinationRegionPosition: Vector3Like;
+} & ModelEntityOptions;
+
+export default class PortalEntity extends Entity {
+  public readonly destinationRegionId: string;
+  public readonly destinationRegionFacingAngle: number;
+  public readonly destinationRegionPosition: Vector3Like;
+
+  public constructor(options: PortalEntityOptions) {
+    const colliderOptions = Collider.optionsFromModelUri('models/environment/portal.gltf', options.modelScale ?? 1, ColliderShape.BLOCK) as BlockColliderOptions;
+    colliderOptions.halfExtents!.x = Math.max(colliderOptions.halfExtents!.x, 0.5);
+
+    super({
+      modelScale: 2,
+      modelUri: 'models/environment/portal.gltf',
+      modelLoopedAnimations: [ 'idle' ],
+      rigidBodyOptions: {
+        type: RigidBodyType.FIXED,
+        colliders: [
+          {
+            ...colliderOptions,
+            relativePosition: { x: 0, y: 0, z: 0.5 }, // inset the sensor a bit
+            isSensor: true,
+            onCollision: (other, started) => {
+              if (!started || !(other instanceof GamePlayerEntity)) return;
+              
+              const destinationRegion = GameManager.instance.getRegion(this.destinationRegionId);
+              
+              if (!destinationRegion) {
+                ErrorHandler.warning(`PortalEntity: Destination region ${this.destinationRegionId} not found`);
+                return;
+              }
+              other.gamePlayer.setCurrentRegion(destinationRegion);
+              other.gamePlayer.setCurrentRegionSpawnFacingAngle(this.destinationRegionFacingAngle);
+              other.gamePlayer.setCurrentRegionSpawnPoint(this.destinationRegionPosition);              
+              other.player.joinWorld(destinationRegion.world);
+            },
+          },
+        ],
+      },
+      ...options,
+    });
+
+    this.destinationRegionId = options.destinationRegionId;
+    this.destinationRegionFacingAngle = options.destinationRegionFacingAngle ?? 0;
+    this.destinationRegionPosition = options.destinationRegionPosition;
+  }
+}

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

@@ -0,0 +1,161 @@
+import { ColliderShape, Entity, RigidBodyType } from 'hytopia';
+import BaseCombatEntity, { BaseCombatEntityOptions } from "../BaseCombatEntity";
+import BaseProjectileEntity from '../BaseProjectileEntity';
+import { isDamageable } from '../../interfaces/IDamageable';
+
+// Drops
+import BlightedRootItem from '../../items/materials/BlightedRootItem';
+import CommonMushroomItem from '../../items/consumables/CommonMushroomItem';
+import CommonSeedsItem from '../../items/seeds/CommonSeedsItem';
+import UnusualSeedsItem from '../../items/seeds/UnusualSeedsItem';
+import GoldItem from '../../items/general/GoldItem';
+
+export type LesserBlightBloomEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class LesserBlightBloomEntity extends BaseCombatEntity {
+  constructor(options?: LesserBlightBloomEntityOptions) {
+    super({
+      aggroRadius: 8,
+      aggroSensorForwardOffset: 0,
+      attacks: [
+        { // Eat
+          animations: [ 'eat' ],
+          complexAttack: () => this._eatTarget(),
+          complexAttackDelayMs: 750,
+          cooldownMs: 4000,
+          range: 4,
+          weight: 4,
+        },
+        { // AoEGas
+          animations: [ 'gas_explode' ],
+          complexAttack: () => this._emitGasAoE(25, 4),
+          complexAttackDelayMs: 2500,
+          cooldownMs: 4000,
+          range: 10,
+          weight: 2,
+        },
+        { // Spray 3 wide gas projectiles
+          animations: [ 'spore_splash' ],
+          complexAttack: () => this._sprayGas(18),
+          complexAttackDelayMs: 700,
+          cooldownMs: 4000,
+          range: 10,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 60,
+      deathAnimations: [ 'death' ],
+      deathDespawnDelayMs: 5000,
+      deathItemDrops: [
+        { itemClass: BlightedRootItem, minQuantity: 1, maxQuantity: 3, weight: 30 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 15 },
+        { itemClass: GoldItem, minQuantity: 12, maxQuantity: 23, weight: 9 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 6 },
+        { itemClass: UnusualSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      deathItemMaxDrops: 3,
+      faceSpeed: 0.75,
+      health: 250,
+      idleAnimations: [ 'waiting' ],
+      modelUri: 'models/enemies/blight-bloom.gltf',
+      modelScale: 0.5,
+      moveAnimations: [ 'waiting' ],
+      moveSpeed: 0, // stationary, doesn't move.
+      name: 'Lesser Blight Bloom',
+      pathfindingOptions: {
+        maxJump: 2,
+        maxFall: 2,
+      },
+      pushable: false,
+      tintColor: { r: 128, g: 255, b: 128 },
+      ...options,
+    });
+  }
+
+  private _eatTarget() {
+    if (!this.world) return;
+
+    const currentDirection = this.directionFromRotation;
+    const raycastDirection = {
+      x: currentDirection.x,
+      y: currentDirection.y - 0.5, // aim down
+      z: currentDirection.z,
+    }
+
+    const raycastResult = this.world.simulation.raycast(this.position, raycastDirection, 4, {
+      filterExcludeRigidBody: this.rawRigidBody,
+      filterFlags: 8, // Rapier flag to exclude sensor colliders
+    });
+
+    if (isDamageable(raycastResult?.hitEntity)) {
+      raycastResult.hitEntity.takeDamage(this.calculateDamageWithVariance(80, 0.3));
+    }
+  }
+  
+  private _emitGasAoE(baseDamage: number, aoeRadius: number) {
+    if (!this.world) return;
+
+    const gas = new Entity({
+      modelUri: 'models/vfx/gas-explode.gltf',
+      modelLoopedAnimations: [ 'actived' ],
+      rigidBodyOptions: {
+        type: RigidBodyType.FIXED,
+        colliders: [
+          {
+            shape: ColliderShape.BALL,
+            radius: aoeRadius,
+            isSensor: true,
+            onCollision: (other, started) => {
+              if (started && other !== this && isDamageable(other)) {
+                other.takeDamage(this.calculateDamageWithVariance(baseDamage, 0.3));
+              }
+            }
+          }
+        ]
+      },
+      tintColor: { r: 0, g: 255, b: 0 },
+    });
+
+    gas.spawn(this.world, this.position);
+
+    setTimeout(() => {
+      gas.despawn();
+    }, 1800);
+  }
+
+  private _sprayGas(baseDamage: number) {
+    const spray = () => {
+      if (!this.world) return;
+
+      const direction = this.directionFromRotation;
+      const gasSpray = new BaseProjectileEntity({
+        damage: this.calculateDamageWithVariance(baseDamage, 0.3),
+        despawnAfterMs: 2000,
+        direction,
+        gravityScale: 0.15,
+        modelUri: 'models/projectiles/wide-spinning-fireball.gltf',
+        modelLoopedAnimations: [ 'idle' ],
+        modelScale: 0.75,
+        speed: 4, 
+        source: this,
+        tintColor: { r: 0, g: 255, b: 128 },
+      });
+
+      const sourcePosition = this.position;
+      const offsetSpawnPosition = {
+        x: sourcePosition.x + direction.x * 2,
+        y: sourcePosition.y + direction.y * 2,
+        z: sourcePosition.z + direction.z * 2,
+      }
+
+      gasSpray.spawn(this.world, offsetSpawnPosition, this.rotation);
+    }
+
+    // 3 sprays
+    spray();
+    setTimeout(spray, 600);
+    setTimeout(spray, 1200);
+  }
+}

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

@@ -0,0 +1,79 @@
+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 RatkinBruteEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class RatkinBruteEntity extends BaseCombatEntity {
+  constructor(options?: RatkinBruteEntityOptions) {
+    super({
+      aggroRadius: 7.5,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Heavy body slam attack
+          animations: [ 'atk1' ],
+          cooldownMs: 4000,
+          range: 2,
+          simpleAttackDamage: 20,
+          simpleAttackDamageVariance: 0.6, // ±60% damage (12-28)
+          simpleAttackDamageDelayMs: 1000, // Deal damage 1000ms into animation
+          simpleAttackReach: 3,
+          weight: 1,
+        },
+        { // Light hammer swing attack
+          animations: [ 'atk2' ],
+          cooldownMs: 1500,
+          range: 2,
+          simpleAttackDamage: 16,
+          simpleAttackDamageVariance: 0.15, // ±15% damage (7-11)
+          simpleAttackDamageDelayMs: 500, // Deal damage 500ms into animation
+          simpleAttackReach: 3,
+          weight: 2,
+        },
+        { // Light hammer swing 2 attack
+          animations: [ 'atk3' ],
+          cooldownMs: 1500,
+          range: 2,
+          simpleAttackDamage: 13,
+          simpleAttackDamageVariance: 0.15, // ±15% damage (5-9)
+          simpleAttackDamageDelayMs: 350, // Deal damage 350ms into animation
+          simpleAttackReach: 3,
+          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: 6, maxQuantity: 15, weight: 2 },
+        { itemClass: CommonMushroomItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+        { itemClass: CommonSeedsItem, minQuantity: 1, maxQuantity: 3, weight: 1 },
+      ],
+      health: 140,
+      idleAnimations: [ 'idle' ],
+      modelUri: 'models/enemies/ratkin-brute.gltf',
+      modelScale: 0.6,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 2.5,
+      name: 'Ratkin Brute',
+      pathfindingOptions: {
+        maxJump: 2,
+        maxFall: 2,
+      },
+      ...options,
+    });
+  }
+}

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

@@ -0,0 +1,88 @@
+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 RatkinRangerEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class RatkinRangerEntity extends BaseCombatEntity {
+  constructor(options?: RatkinRangerEntityOptions) {
+    super({
+      aggroRadius: 11,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Fast bow attack
+          animations: [ 'atk1' ],
+          complexAttack: (params) => {
+            this._shootArrow(params.target.position, this.calculateDamageWithVariance(11, 0.5));
+          },
+          complexAttackDelayMs: 700,
+          cooldownMs: 2000,
+          range: 10,
+          weight: 2,
+        },
+        { // Slow heavy bow attack
+          animations: [ 'atk2' ],
+          complexAttack: (params) => {
+            this._shootArrow(params.target.position, this.calculateDamageWithVariance(16, 0.5));
+          },
+          complexAttackDelayMs: 1600,
+          cooldownMs: 3000,
+          range: 10,
+          weight: 3,
+        },
+      ],
+      combatExperienceReward: 20,
+      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-ranger.gltf',
+      modelScale: 0.8,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 3,
+      name: 'Ratkin Ranger',
+      pathfindingOptions: {
+        maxJump: 2,
+        maxFall: 2,
+      },
+      ...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/RatkinSpellcasterEntity.ts

@@ -0,0 +1,77 @@
+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 RatkinSpellcasterEntityOptions = {
+
+} & BaseCombatEntityOptions;
+
+export default class RatkinSpellcasterEntity extends BaseCombatEntity {
+  constructor(options?: RatkinSpellcasterEntityOptions) {
+    super({
+      aggroRadius: 12,
+      aggroSensorForwardOffset: 3,
+      attacks: [
+        { // Fireball attack
+          animations: [ 'atk1' ],
+          complexAttack: (params) => {
+            this._shootFireball(params.target.position, this.calculateDamageWithVariance(22, 0.5));
+          },
+          complexAttackDelayMs: 1000,
+          cooldownMs: 5000,
+          range: 10,
+          weight: 2,
+        },
+      ],
+      combatExperienceReward: 20,
+      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-spellcaster.gltf',
+      modelScale: 0.8,
+      moveAnimations: [ 'walk' ],
+      moveSpeed: 3,
+      name: 'Ratkin Spellcaster',
+      pathfindingOptions: {
+        maxJump: 2,
+        maxFall: 2,
+      },
+      ...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);
+  }
+}