hytopia 0.1.26 → 0.1.29

package/server.d.ts

@@ -290,6 +290,11 @@ export declare interface AudioOptions {
 export declare abstract class BaseCharacterController {
     /** The entity the controller is for. */
     readonly entity: Entity;
+    /**
+     * A callback function for when the controller ticks.
+     * @param deltaTimeMs - The delta time in milliseconds since the last tick.
+     */
+    onTick?: (deltaTimeMs: number) => void;
     /**
      * A callback function for when the controller ticks
      * player movement.
@@ -298,13 +303,6 @@ export declare abstract class BaseCharacterController {
      * @param deltaTimeMs - The delta time in milliseconds since the last tick.
      */
     onTickPlayerMovement?: (inputState: PlayerInputState, orientationState: PlayerOrientationState, deltaTimeMs: number) => void;
-    /**
-     * A callback function for when the controller ticks
-     * pathfinding movement.
-     * @param destination - The destination to move to.
-     * @param deltaTimeMs - The delta time in milliseconds since the last tick.
-     */
-    onTickPathfindingMovement?: (destination: Vector3, deltaTimeMs: number) => void;
     /**
      * @param entity - The entity the controller is for.
      * @param _options - Arbitrary options you may provide or omit for your controller implementation.
@@ -325,13 +323,11 @@ export declare abstract class BaseCharacterController {
      */
     tickPlayerMovement(inputState: PlayerInputState, orientationState: PlayerOrientationState, deltaTimeMs: number): void;
     /**
-     * Override this method to implement pathfinding
-     * movement logic for your character controller.
-     * NOTE: This method is not fully supported yet.
-     * @param destination - The destination target to move to.
+     * Override this method to handle entity movements
+     * based on your character controller.
      * @param deltaTimeMs - The delta time in milliseconds since the last tick.
      */
-    tickPathfindingMovement(destination: Vector3, deltaTimeMs: number): void;
+    tick(deltaTimeMs: number): void;
 }
 
 /**
@@ -1148,13 +1144,6 @@ export declare class DefaultCharacterController extends BaseCharacterController
      * @param deltaTimeMs - The delta time in milliseconds since the last tick.
      */
     tickPlayerMovement(inputState: PlayerInputState, orientationState: PlayerOrientationState, deltaTimeMs: number): void;
-    /**
-     * Ticks the pathfinding movement for the character controller,
-     * overriding the default implementation.
-     * @param destination - The destination to move to.
-     * @param deltaTimeMs - The delta time in milliseconds since the last tick.
-     */
-    tickPathfindingMovement(destination: Vector3, deltaTimeMs: number): void;
 }
 
 /** Options for creating a DefaultCharacterController instance. @public */
@@ -1507,6 +1496,34 @@ export declare class EventRouter {
     emit<TPayload>(event: Event_2<TPayload>): boolean;
 }
 
+/**
+ * A callback function called when the entity associated with the
+ * SimpleCharacterController updates its rotation as it is
+ * attempting to face a target coordinate.
+ * @param currentRotation - The current rotation of the entity.
+ * @param targetRotation - The target rotation of the entity.
+ * @public
+ */
+export declare type FaceCallback = (currentRotation: Rotation, targetRotation: Rotation) => void;
+
+/**
+ * A callback function called when the entity associated with the
+ * SimpleCharacterController finishes rotating and is now facing
+ * a target coordinate.
+ * @param endRotation - The rotation of the entity after it has finished rotating.
+ * @public
+ */
+export declare type FaceCompleteCallback = (endRotation: Rotation) => void;
+
+/**
+ * Options for the {@link SimpleCharacterController.face} method.
+ * @public
+ */
+export declare type FaceOptions = {
+    faceCallback?: FaceCallback;
+    faceCompleteCallback?: FaceCompleteCallback;
+};
+
 /**
  * Manages the game and associated worlds and systems.
  *
@@ -1616,17 +1633,54 @@ declare namespace HYTOPIA {
         RigidBodyType,
         RigidBodyAdditionalMassProperties,
         RigidBodyOptions,
+        SimpleCharacterController,
+        FaceCallback,
+        FaceCompleteCallback,
+        FaceOptions,
+        MoveCallback,
+        MoveCompleteCallback,
+        MoveOptions,
         Simulation,
         WebServer,
         PORT,
         World,
         WorldMap,
         WorldOptions,
-        WorldLoop
+        WorldLoop,
+        WorldLoopEventType,
+        WorldLoopEventPayload
     }
 }
 export default HYTOPIA;
 
+/**
+ * A callback function called when the entity associated with the
+ * SimpleCharacterController updates its translation as it is
+ * attempting to move to a target coordinate.
+ * @param currentTranslation - The current translation of the entity.
+ * @param targetTranslation - The target translation of the entity.
+ * @public
+ */
+export declare type MoveCallback = (currentTranslation: Vector3, targetTranslation: Vector3) => void;
+
+/**
+ * A callback function called when the entity associated with the
+ * SimpleCharacterController reaches the target coordinate. An entity
+ * must reach the x,y,z coordinate for the callback to be called.
+ * @param endTranslation - The translation of the entity after it has finished moving.
+ * @public
+ */
+export declare type MoveCompleteCallback = (endTranslation: Vector3) => void;
+
+/**
+ * Options for the {@link SimpleCharacterController.move} method.
+ * @public
+ */
+export declare type MoveOptions = {
+    moveCallback?: MoveCallback;
+    moveCompleteCallback?: MoveCompleteCallback;
+};
+
 /**
  * A player in the game.
  *
@@ -2292,6 +2346,76 @@ export declare interface Rotation {
     w: number;
 }
 
+/**
+ * A simple character controller with basic movement functions.
+ *
+ * @remarks
+ * This class implements simple movement methods that serve
+ * as a way to add realistic movement and rotational facing
+ * functionality to an entity. This is also a great base to
+ * extend for your own more complex character controller
+ * that implements things like pathfinding.
+ *
+ * @example
+ * ```typescript
+ * // Create a custom character controller for myEntity, prior to spawning it.
+ * myEntity.createCustomCharacterController = () => {
+ *   return new SimpleCharacterController(myEntity);
+ * };
+ *
+ * // Spawn the entity in the world.
+ * myEntity.spawn(world, { x: 53, y: 10, z: 23 });
+ *
+ * // Move the entity at a speed of 4 blocks
+ * // per second to the coordinate (10, 1, 10).
+ * // console.log when we reach the target.
+ * myEntity.characterController.move({ x: 10, y: 1, z: 10 }, 4, {
+ *   moveCompleteCallback: endPosition => {
+ *     console.log('Finished moving to', endPosition);
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class SimpleCharacterController extends BaseCharacterController {
+
+
+
+
+
+
+
+
+    /**
+     * Rotates the entity at a given speed to face a target coordinate.
+     *
+     * @remarks
+     * If this method is called while the entity is already attempting
+     * to face another target, the previous target will be ignored and
+     * the entity will start attempting to face the new target.
+     *
+     * @param target - The target coordinate to face.
+     * @param speed - The speed at which to rotate to the target coordinate.
+     * @param options - Additional options for the face operation, such as callbacks.
+     */
+    face(target: Vector3, speed: number, options?: FaceOptions): void;
+    /**
+     * Moves the entity at a given speed in a straight line to a target coordinate.
+     *
+     * @remarks
+     * If this method is called while the entity is already attempting
+     * to move to another target, the previous target will be ignored and
+     * the entity will start attempting to move to the new target.
+     *
+     * @param target - The target coordinate to move to.
+     * @param speed - The speed at which to move to the target coordinate.
+     * @param options - Additional options for the move operation, such as callbacks.
+     */
+    move(target: Vector3, speed: number, options?: MoveOptions): void;
+
+}
+
 /**
  * Represents the physics simulation for a world.
  *
@@ -2539,6 +2663,37 @@ export declare class WorldLoop {
 
 
 
+}
+
+/** Payloads for events emitted by a WorldLoop instance. @public */
+export declare namespace WorldLoopEventPayload {
+    export interface Start {
+        worldLoop: WorldLoop;
+    }
+    export interface Stop {
+        worldLoop: WorldLoop;
+    }
+    export interface TickStart {
+        worldLoop: WorldLoop;
+        tickDeltaMs: number;
+    }
+    export interface TickEnd {
+        worldLoop: WorldLoop;
+        tickDurationMs: number;
+    }
+    export interface TickError {
+        worldLoop: WorldLoop;
+        error: Error;
+    }
+}
+
+/** Event types a WorldLoop instance can emit. @public */
+export declare enum WorldLoopEventType {
+    START = "WORLD_LOOP.START",
+    STOP = "WORLD_LOOP.STOP",
+    TICK_START = "WORLD_LOOP.TICK_START",
+    TICK_END = "WORLD_LOOP.TICK_END",
+    TICK_ERROR = "WORLD_LOOP.TICK_ERROR"
 }
 
 /** A map representation for a world. @public */