@hytopia.com/examples 1.0.3 → 1.0.5

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

@@ -5,34 +5,111 @@ import {
   PathfindingEntityController,
   PathfindingOptions,
   Quaternion,
+  QuaternionLike,
   RigidBodyType,
+  SceneUI,
   Vector3Like,
+  World,
 } from 'hytopia';
 
+import { SkillId } from '../config';
+import GamePlayerEntity from '../GamePlayerEntity';
+import QuestRegistry, { QUEST_DIALOGUE_OPTION_START_ID } from '../quests/QuestRegistry';
+import type IInteractable from '../interfaces/IInteractable';
+import type IDamageable from '../interfaces/IDamageable';
+import type { ItemClass } from '../items/BaseItem';
+
+export enum BaseEntityPlayerEvent {
+  KILLED = 'BaseEntity.KILLED',
+}
+
+export type BaseEntityPlayerEventPayloads = {
+  [BaseEntityPlayerEvent.KILLED]: { entity: BaseEntity };
+}
+
+export type BaseEntityDialogue = {
+  text: string;
+  options?: BaseEntityDialogueOption[];
+}
+
+export type BaseEntityDialogueOption = {
+  _id?: number; // internal autogenerated option id
+  text: string;
+  dismiss?: boolean;
+  isSelectable?: (interactor: GamePlayerEntity) => boolean;
+  nextDialogue?: BaseEntityDialogue;
+  onSelect?: (interactor: GamePlayerEntity) => void;
+  pureExit?: boolean;
+}
+
+export type BaseEntityDialogueRoot = {
+  avatarImageUri: string;
+  title?: string;
+  dialogue: BaseEntityDialogue;
+}
+
+export type BaseEntityItemDrop = {
+  itemClass: ItemClass;
+  maxQuantity?: number;
+  minQuantity?: number;
+  weight: number;
+  quantity?: number;
+}
+
 export type BaseEntityOptions = {
+  combatExperienceReward?: number;
   controller?: PathfindingEntityController;
+  deathAnimations?: string[];
+  deathDespawnDelayMs?: number;
+  deathItemDrops?: BaseEntityItemDrop[];
+  deathItemMaxDrops?: number;
+  dialogue?: BaseEntityDialogueRoot;
+  faceSpeed?: number;
   facingAngle?: number;
   facingPosition?: Vector3Like;
   idleAnimations?: string[];
   idleAnimationSpeed?: number;
+  interactActionText?: string;
+  health?: number;
   moveAnimations?: string[];
   moveAnimationSpeed?: number;
+  moveOptions?: MoveOptions;
   moveSpeed?: number;
+  nameplateViewDistnace?: number;
+  pathfindingOptions?: PathfindingOptions;
   pushable?: boolean;
 } & EntityOptions;
 
 export type WanderOptions = {
   idleMinMs: number;
   idleMaxMs: number;
+  maxWanderRadius: number;
   moveOptions?: MoveOptions;
-  pathfindOptions?: PathfindingOptions;
 }
 
-export default class BaseEntity extends Entity {
-  private _moveSpeed: number;
-  private _wanderAccumulatorMs: number = 0;
+export default class BaseEntity extends Entity implements IInteractable, IDamageable {
+  private _combatExperienceReward: number;
+  private _deathAnimations: string[];
+  private _deathDespawnDelayMs: number;
+  private _deathItemDrops: BaseEntityItemDrop[];
+  private _deathItemDropsTotalWeight: number = 0;
+  private _deathItemMaxDrops: number;
+  private _dialogueRoot: BaseEntityDialogueRoot | undefined;
+  private _dying: boolean = false;
+  private _faceSpeed: number;
+  private _health: number;
+  private _interactActionText: string | undefined;
+  private _maxHealth: number;
+  private _moveOptions: MoveOptions | undefined;
+  private _moveSpeed: number; 
+  private _nameplateSceneUI: SceneUI;
+  private _nameplateViewDistance: number | undefined;
+  private _optionMap: Map<number, BaseEntityDialogueOption> = new Map();
+  private _pathfindingOptions: PathfindingOptions | undefined;
+  private _pushable: boolean;
+  private _wanderTimeout: NodeJS.Timeout | undefined;
   
-  public constructor(options: BaseEntityOptions) {
+  public constructor(options: BaseEntityOptions = {}) {
     super({
       ...options,
       controller: new PathfindingEntityController(),
@@ -45,7 +122,25 @@ export default class BaseEntity extends Entity {
       }
     });
 
+    this._combatExperienceReward = options.combatExperienceReward ?? 0;
+    this._deathAnimations = options.deathAnimations ?? [];
+    this._deathDespawnDelayMs = options.deathDespawnDelayMs ?? 0;
+    this._deathItemDrops = options.deathItemDrops ?? [];
+    this._deathItemDropsTotalWeight = this._deathItemDrops.reduce((sum, drop) => sum + drop.weight, 0);
+    this._deathItemMaxDrops = options.deathItemMaxDrops ?? 1;
+    this._dialogueRoot = options.dialogue;
+    this._health = options.health ?? 0; // 0 is infinite health, will not show health bar
+    this._interactActionText = options.interactActionText;
+    this._maxHealth = this._health;
+    this._moveOptions = options.moveOptions;
     this._moveSpeed = options.moveSpeed ?? 2;
+    this._faceSpeed = options.faceSpeed ?? this._moveSpeed * 2;
+    this._nameplateViewDistance = options.nameplateViewDistnace;
+    this._pathfindingOptions = options.pathfindingOptions;
+    this._pushable = options.pushable ?? false;
+    if (this._dialogueRoot) {
+      this._buildDialogueOptionMap();
+    }
 
     this.pathfindingController.idleLoopedAnimations = options.idleAnimations ?? [];
     this.pathfindingController.idleLoopedAnimationsSpeed = options.idleAnimationSpeed ?? undefined;
@@ -55,49 +150,261 @@ export default class BaseEntity extends Entity {
     if (options.facingPosition) {
       this.pathfindingController.face(options.facingPosition, this._moveSpeed);
     }
+
+    this.setupNameplateUI();
   }
 
+  public get dialogueRoot(): BaseEntityDialogueRoot | undefined { return this._dialogueRoot; }
+  public get faceSpeed(): number { return this._faceSpeed; }
   public get idleAnimations(): string[] { return this.pathfindingController.idleLoopedAnimations; }
   public get idleAnimationsSpeed(): number | undefined { return this.pathfindingController.idleLoopedAnimationsSpeed; }
+  public get interactActionText(): string | undefined { return this._interactActionText; }
+  public get isDying(): boolean { return this._dying; }
+  public get isInteractable(): boolean { return !!this._dialogueRoot || !!this._interactActionText; }
+  public get health(): number { return this._health; }
+  public get maxHealth(): number { return this._maxHealth; }
   public get moveAnimations(): string[] { return this.pathfindingController.moveLoopedAnimations; }
   public get moveAnimationsSpeed(): number | undefined { return this.pathfindingController.moveLoopedAnimationsSpeed; }
   public get moveSpeed(): number { return this._moveSpeed; }
   public get pathfindingController(): PathfindingEntityController { return this.controller as PathfindingEntityController; }
+  public get pushable(): boolean { return this._pushable; }
+
+  public die(killer?: Entity): void {
+    if (this._dying) return;
+
+    this._dying = true;
+
+    this.startModelOneshotAnimations(this._deathAnimations);
+    this.stopMoving();
+    this.dropItems();
+
+    if (this._combatExperienceReward > 0 && killer instanceof GamePlayerEntity) {
+      killer.adjustSkillExperience(SkillId.COMBAT, this._combatExperienceReward);
+      killer.gamePlayer.eventRouter.emit(BaseEntityPlayerEvent.KILLED, { entity: this });
+    }
+
+    setTimeout(() => this.despawn(), this._deathDespawnDelayMs);
+  }
+
+  public dropItems(): void {
+    if (!this.world || !this._deathItemDrops || this._deathItemDrops.length === 0) return;
+
+    const maxDrops = Math.floor(Math.random() * (this._deathItemMaxDrops ?? 1) + 1);
+
+    for (let i = 0; i < maxDrops; i++) {
+      const selectedDrop = this._pickRandomDeathItemDrop();
+      if (!selectedDrop) continue;
+
+      const min = selectedDrop.minQuantity ?? 1;
+      const max = selectedDrop.maxQuantity ?? 1;
+      const quantity = selectedDrop.quantity ?? Math.floor(Math.random() * (max - min + 1)) + min;
+      
+      const item = selectedDrop.itemClass.create({ quantity });
+      item.spawnEntityAsEjectedDrop(this.world, this.position);
+    }
+  }
 
   public faceTowards(target: Vector3Like, faceSpeed: number) {
     this.pathfindingController.face(target, faceSpeed);
   }
 
+  public interact(interactor: GamePlayerEntity): void {
+    if (this._dialogueRoot) {
+      interactor.setCurrentDialogueEntity(this);
+      this.showDialogue(interactor, this._dialogueRoot.dialogue);
+      this.faceTowards(interactor.position, 8);
+    }
+  }
+
   public jump(height: number) {
     this.pathfindingController.jump(height);
   }
 
+  public moveTo(target: Vector3Like, speed: number = this._moveSpeed, options?: MoveOptions) {
+    this.pathfindingController.move(target, speed, options ?? this._moveOptions);
+  }
+
   public pathfindTo(target: Vector3Like, speed: number = this._moveSpeed, options?: PathfindingOptions) {
-    this.pathfindingController.pathfind(target, speed, options);
+    this.pathfindingController.pathfind(target, speed, options ?? this._pathfindingOptions);
   }
 
-  public moveTo(target: Vector3Like, speed: number = this._moveSpeed, options?: MoveOptions) {
-    this.pathfindingController.move(target, speed, options);
+  public progressDialogue(interactor: GamePlayerEntity, optionId: number): void {
+    // Try local dialogue options first, then quest dialogue options with validation
+    const selectedOption = this._optionMap.get(optionId) || 
+                          QuestRegistry.getValidQuestDialogueOptionForNPC(this.constructor as typeof BaseEntity, optionId, interactor);
+
+    if (!selectedOption) return;
+    if (selectedOption.isSelectable && !selectedOption.isSelectable(interactor)) return;
+
+    if (selectedOption.onSelect) {
+      selectedOption.onSelect(interactor);
+    }
+
+    if (selectedOption.nextDialogue) {
+      this.showDialogue(interactor, selectedOption.nextDialogue);
+    }
+  }
+
+  public override spawn(world: World, position: Vector3Like, rotation?: QuaternionLike) {
+    super.spawn(world, position, rotation);
+    this._nameplateSceneUI.load(world);
+  }
+
+  public showDialogue(interactor: GamePlayerEntity, dialogue: BaseEntityDialogue): void {
+    if (!this._dialogueRoot) return;
+
+    const isRootDialogue = this._dialogueRoot.dialogue === dialogue;
+    
+    let questDialogueRootOptions: BaseEntityDialogueOption[] = [];
+
+    if (isRootDialogue) {
+      questDialogueRootOptions = QuestRegistry.getQuestRootDialogueOptionsForNPC(this.constructor as typeof BaseEntity, interactor);
+    }
+
+    const allDialogueOptions = [ ...questDialogueRootOptions, ...(dialogue.options || []) ];
+
+    interactor.player.ui.sendData({
+      type: 'dialogue',
+      avatarImageUri: this._dialogueRoot.avatarImageUri,
+      name: this.name,
+      title: this._dialogueRoot.title,
+      text: dialogue.text,
+      options: allDialogueOptions.map(option => {
+        if (option.isSelectable && !option.isSelectable(interactor)) {
+          return null;
+        }
+
+        return {
+          id: option._id,
+          text: option.text,
+          dismiss: option.dismiss,
+          pureExit: option.pureExit ?? false,
+          isQuestRoot: isRootDialogue && option._id && option._id >= QUEST_DIALOGUE_OPTION_START_ID,
+        };
+      }).filter(Boolean),
+    });
   }
 
   public stopMoving() {
-    // reset & cancels all movements.
-    this.pathfindingController.pathfind(this.position, 1);
-  }
-
-  public wander(targets: Vector3Like[], speed: number = this._moveSpeed, options?: WanderOptions) {
-    const randomIndex = Math.floor(Math.random() * targets.length);
-    const target = targets[randomIndex];
-    this.pathfindTo(target, speed, {
-      debug: true,
-      maxFall: 5,
-      maxJump: 0,
-      maxOpenSetIterations: 400,
-      waypointTimeoutMs: 500,
-      pathfindCompleteCallback: () => {
-        setTimeout(() => this.wander(targets, speed, options), 2000);
-      }
+    this.pathfindingController.stopFace();
+    this.pathfindingController.stopMove();
+  }
+
+  public stopWandering() {
+    if (this._wanderTimeout) {
+      clearTimeout(this._wanderTimeout);
+      this._wanderTimeout = undefined;
+    }
+  }
+
+  public takeDamage(damage: number, attacker?: Entity): void {
+    // Infinite health, doesn't take damage if max health is 0
+    if (this._maxHealth === 0) return; 
+
+    this._health = Math.max(0, this._health - damage);
+
+    this._nameplateSceneUI.setState({
+      damage,
+      health: this._health
     });
-    console.log('wandering to', target);
+
+    if (this._health <= 0) {
+      this.die(attacker);
+    }
+  }
+
+  public wander(speed: number = this._moveSpeed, options: WanderOptions): void {
+    // Basic validation and early exit for invalid states
+    if (this._dying || !this.world || speed <= 0 || options.maxWanderRadius <= 0) return;
+
+    // Allow subclasses to defer wandering for other behaviors
+    if (this.shouldDeferWander()) {
+      const { idleMinMs, idleMaxMs } = options;
+      const idleTimeMs = Math.floor(Math.random() * (idleMaxMs - idleMinMs + 1)) + idleMinMs;
+      this._wanderTimeout = setTimeout(() => this.wander(speed, options), idleTimeMs);
+      return;
+    }
+
+    this.stopWandering();
+
+    const { idleMinMs, idleMaxMs, maxWanderRadius, moveOptions } = options;
+    const idleTimeMs = Math.floor(Math.random() * (idleMaxMs - idleMinMs + 1)) + idleMinMs;
+
+    this._wanderTimeout = setTimeout(() => {
+      if (this._dying || !this.world) return;
+
+      const offsetX = (Math.random() - 0.5) * 2 * maxWanderRadius;
+      const offsetZ = (Math.random() - 0.5) * 2 * maxWanderRadius;
+      const target = {
+        x: this.position.x + offsetX,
+        y: this.position.y,
+        z: this.position.z + offsetZ,
+      };
+
+      this.faceTowards(target, this._faceSpeed);
+      this.moveTo(target, speed, moveOptions);
+
+      const travelTimeMs = Math.max(500, ((offsetX + offsetZ) / speed) * 1000);
+      this._wanderTimeout = setTimeout(() => this.wander(speed, options), travelTimeMs);
+    }, idleTimeMs);
+  }
+
+  protected setupNameplateUI(): void {
+    this._nameplateSceneUI = new SceneUI({
+      attachedToEntity: this,
+      offset: { x: 0, y: this.height / 2 + 0.25, z: 0 },
+      templateId: 'entity-nameplate',
+      viewDistance: this._nameplateViewDistance,
+      state: {
+        name: this.name,
+        className: this.constructor.name,
+        health: this.health,
+        interactable: this.isInteractable,
+        interactActionText: this.interactActionText,
+        maxHealth: this.maxHealth,
+      },
+    });
+  }
+
+  protected shouldDeferWander(): boolean {
+    return false; // override in subclasses to prevent wandering
+  }
+
+  private _buildDialogueOptionMap(): void {
+    if (!this._dialogueRoot) return;
+    
+    let currentId = 0;
+    
+    const assignOptionIds = (dialogue: BaseEntityDialogue): void => {
+      if (dialogue.options) {
+        for (const option of dialogue.options) {
+          option._id = currentId;
+          this._optionMap.set(currentId, option);
+          currentId++;
+          
+          if (option.nextDialogue) {
+            assignOptionIds(option.nextDialogue);
+          }
+        }
+      }
+    };
+    
+    assignOptionIds(this._dialogueRoot.dialogue);
+  }
+
+  private _pickRandomDeathItemDrop(): BaseEntityItemDrop | null {
+    if (this._deathItemDropsTotalWeight <= 0) return null;
+
+    const random = Math.random() * this._deathItemDropsTotalWeight;
+    let cumulativeWeight = 0;
+
+    for (const drop of this._deathItemDrops) {
+      cumulativeWeight += drop.weight;
+      if (random < cumulativeWeight) {
+        return drop;
+      }
+    }
+
+    return null;
   }
 }

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

@@ -0,0 +1,119 @@
+import BaseEntity, { BaseEntityOptions } from './BaseEntity';
+import { SkillId } from '../config';
+import type { ItemClass } from '../items/BaseItem';
+import type GamePlayerEntity from '../GamePlayerEntity';
+
+export enum BaseForageableEntityPlayerEvent {
+  FORAGED = 'BaseForageableEntity.FORAGED',
+}
+
+export type BaseForageableEntityPlayerEventPayloads = {
+  [BaseForageableEntityPlayerEvent.FORAGED]: { entity: BaseForageableEntity };
+}
+
+export type ForageableItemDrop = {
+  itemClass: ItemClass;
+  maxQuantity?: number;
+  minQuantity?: number;
+  weight: number;
+  quantity?: number;
+}
+
+export type BaseForageableEntityOptions = {
+  forageDurationMs: number;
+  itemDrops: ForageableItemDrop[];
+  maxDropsPerForage?: number;
+  experienceReward?: number;
+} & BaseEntityOptions;
+
+export default class BaseForageableEntity extends BaseEntity {
+  private _forageDurationMs: number;
+  private _itemDrops: ForageableItemDrop[];
+  private _totalDropWeight: number = 0;
+  private _maxDropsPerForage: number;
+  private _isBeingForaged: boolean = false;
+  private _experienceReward: number;
+
+  public constructor(options: BaseForageableEntityOptions) {
+    super({
+      interactActionText: 'Press "E" to forage',
+      nameplateViewDistnace: 10,
+      ...options,
+    });
+
+    this._forageDurationMs = options.forageDurationMs;
+    this._itemDrops = options.itemDrops;
+    this._totalDropWeight = this._itemDrops.reduce((sum, drop) => sum + drop.weight, 0);
+    this._maxDropsPerForage = options.maxDropsPerForage ?? 1;
+    this._experienceReward = options.experienceReward ?? 1;
+  }
+
+  public get forageDurationMs(): number { return this._forageDurationMs; }
+  public get itemDrops(): ForageableItemDrop[] { return this._itemDrops; }
+  public get maxDropsPerForage(): number { return this._maxDropsPerForage; }
+  public get isBeingForaged(): boolean { return this._isBeingForaged; }
+
+  public forageItems(): void {
+    if (!this.world || !this._itemDrops || this._itemDrops.length === 0) return;
+
+    const maxDrops = Math.floor(Math.random() * this._maxDropsPerForage) + 1;
+
+    for (let i = 0; i < maxDrops; i++) {
+      const selectedDrop = this._selectRandomDrop();
+      if (!selectedDrop) continue;
+
+      const quantity = this._calculateDropQuantity(selectedDrop);
+      const item = selectedDrop.itemClass.create({ quantity });
+      item.spawnEntityAsEjectedDrop(this.world, this.position);
+    }
+  }
+
+  public override interact(interactor: GamePlayerEntity): void {
+    if (this._isBeingForaged) return;
+
+    this._isBeingForaged = true;
+    interactor.setIsMovementDisabled(true);
+    interactor.startModelOneshotAnimations([ 'foraging-transition' ]);
+    interactor.playerController.idleLoopedAnimations = [ 'foraging-loop' ]; // player controller stops all looped animations atm for its state, so we set the idle looped animations instead.
+
+    setTimeout(() => {
+      if (!this.isSpawned) return;
+
+      if (interactor.isSpawned) {
+        interactor.setIsMovementDisabled(false);
+        interactor.stopModelAnimations([ 'foraging-transition' ]);
+        interactor.playerController.idleLoopedAnimations = [ 'idle-upper', 'idle-lower' ];
+      }
+
+      if (!interactor.gamePlayer.isDead) {
+        interactor.gamePlayer.adjustSkillExperience(SkillId.FORAGING, this._experienceReward);
+        interactor.gamePlayer.eventRouter.emit(BaseForageableEntityPlayerEvent.FORAGED, { entity: this });
+      }
+
+      this.forageItems();
+      this.despawn();
+    }, this._forageDurationMs);
+  }
+
+  private _calculateDropQuantity(drop: ForageableItemDrop): number {
+    const min = drop.minQuantity ?? 1;
+    const max = drop.maxQuantity ?? 1;
+    return drop.quantity ?? Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+
+  private _selectRandomDrop(): ForageableItemDrop | null {
+    if (this._totalDropWeight <= 0) return null;
+
+    const random = Math.random() * this._totalDropWeight;
+    let cumulativeWeight = 0;
+
+    for (const drop of this._itemDrops) {
+      cumulativeWeight += drop.weight;
+      if (random < cumulativeWeight) {
+        return drop;
+      }
+    }
+
+    return null;
+  }
+}

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

@@ -0,0 +1,26 @@
+import { Entity, EntityOptions } from 'hytopia';
+import BaseItem from '../items/BaseItem';
+import GamePlayerEntity from '../GamePlayerEntity';
+import IInteractable from '../interfaces/IInteractable';
+
+export type BaseItemEntityOptions = {
+  item: BaseItem;
+} & EntityOptions;
+
+/**
+ * Note: This is an entity wrapper for BaseItem that enables interaction through the entity system.
+ * This adapter allows items to be interacted with via raycast hits on their entities.
+ */
+export default class BaseItemEntity extends Entity implements IInteractable {
+  public readonly item: BaseItem;
+
+  public constructor(options: BaseItemEntityOptions) {
+    super(options);
+
+    this.item = options.item;
+  }
+
+  public interact(playerEntity: GamePlayerEntity): void {
+    this.item.interact(playerEntity);
+  }
+}