hytopia 0.1.27 → 0.1.30

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;
 }
 
 /**
@@ -382,16 +378,18 @@ export declare class Block {
 export declare class BlockType implements protocol.Serializable {
     /**
      * A callback function that is invoked when an entity collides with blocks of this type.
-     * @param entity - The entity that collided with the block.
+     * @param blockType - The block type the collision is for.
+     * @param entity - The entity that collided with the block type.
      * @param started - Whether the collision started.
      */
-    onEntityCollision?: (this: BlockType, entity: Entity, started: boolean) => void;
+    onEntityCollision?: (blockType: BlockType, entity: Entity, started: boolean) => void;
     /**
      * A callback function that is invoked when an entity contacts a block of this type.
-     * @param entity - The entity that contacted the block.
+     * @param blockType - The block type the contact is for.
+     * @param entity - The entity that contacted the block type.
      * @param contactForceData - The contact force data.
      */
-    onEntityContactForce?: (this: BlockType, entity: Entity, contactForceData: ContactForceData) => void;
+    onEntityContactForce?: (blockType: BlockType, entity: Entity, contactForceData: ContactForceData) => void;
 
 
 
@@ -1104,22 +1102,22 @@ export declare class DefaultCharacterController extends BaseCharacterController
     walkVelocity: number;
     /**
      * A function allowing custom logic to determine if the entity can walk.
-     * @param this - The character controller instance.
-     * @returns Whether the entity can walk.
+     * @param defaultCharacterController - The character controller instance.
+     * @returns Whether the entity of the character controller can walk.
      */
-    canWalk: (this: DefaultCharacterController) => boolean;
+    canWalk: (defaultCharacterController: DefaultCharacterController) => boolean;
     /**
      * A function allowing custom logic to determine if the entity can run.
-     * @param this - The character controller instance.
-     * @returns Whether the entity can run.
+     * @param defaultCharacterController - The character controller instance.
+     * @returns Whether the entity of the character controller can run.
      */
-    canRun: (this: DefaultCharacterController) => boolean;
+    canRun: (defaultCharacterController: DefaultCharacterController) => boolean;
     /**
      * A function allowing custom logic to determine if the entity can jump.
-     * @param this - The character controller instance.
-     * @returns Whether the entity can jump.
+     * @param defaultCharacterController - The character controller instance.
+     * @returns Whether the entity of the character controller can jump.
      */
-    canJump: (this: DefaultCharacterController) => boolean;
+    canJump: (defaultCharacterController: DefaultCharacterController) => boolean;
 
 
 
@@ -1148,13 +1146,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 */
@@ -1210,55 +1201,55 @@ export declare interface DefaultCharacterControllerOptions {
  */
 export declare class Entity extends RigidBody implements protocol.Serializable {
     /**
-     * A function that creates a custom character controller for the entity.
-     * @param this - The Entity instance.
+     * A function that creates a custom character controller for the entity when it spawns.
+     * @param entity - The Entity instance the character controller is created for.
      * @returns A character controller that extends {@link BaseCharacterController}.
      */
-    createCustomCharacterController?: (this: Entity) => BaseCharacterController;
+    createCustomCharacterController?: (entity: Entity) => BaseCharacterController;
     /**
      * A function that is called when the entity collides with a block.
-     * @param this - The Entity instance.
+     * @param entity - The Entity instance the collision is for.
      * @param block - The block that the entity collided with.
      * @param started - Whether the collision started or ended.
      */
-    onBlockCollision?: (this: Entity, block: BlockType, started: boolean) => void;
+    onBlockCollision?: (entity: Entity, block: BlockType, started: boolean) => void;
     /**
      * A function that is called when the entity collides with a block.
-     * @param this - The Entity instance.
+     * @param entity - The Entity instance the collision is for.
      * @param block - The block that the entity collided with.
      * @param contactForceData - The contact force data.
      */
-    onBlockContactForce?: (this: Entity, block: BlockType, contactForceData: ContactForceData) => void;
+    onBlockContactForce?: (entity: Entity, block: BlockType, contactForceData: ContactForceData) => void;
     /**
      * A function that is called when the entity collides with another entity.
-     * @param this - The Entity instance.
-     * @param entity - The entity that the entity collided with.
+     * @param entity - The Entity instance the collision is for.
+     * @param otherEntity - The other entity that the entity collided with.
      * @param started - Whether the collision started or ended.
      */
-    onEntityCollision?: (this: Entity, entity: Entity, started: boolean) => void;
+    onEntityCollision?: (entity: Entity, otherEntity: Entity, started: boolean) => void;
     /**
      * A function that is called when the entity contacts another entity.
-     * @param this - The Entity instance.
-     * @param entity - The entity that the entity collided with.
+     * @param entity - The Entity instance the collision is for.
+     * @param otherEntity - The other entity that the entity collided with.
      * @param contactForceData - The contact force data.
      */
-    onEntityContactForce?: (this: Entity, entity: Entity, contactForceData: ContactForceData) => void;
+    onEntityContactForce?: (entity: Entity, otherEntity: Entity, contactForceData: ContactForceData) => void;
     /**
      * A function that is called when the entity is spawned.
-     * @param this - The Entity instance.
+     * @param entity - The Entity instance that spawned.
      */
-    onSpawn?: (this: Entity) => void;
+    onSpawn?: (entity: Entity) => void;
     /**
      * A function that is called when the entity is despawned.
-     * @param this - The Entity instance.
+     * @param entity - The Entity instance that despawned.
      */
-    onDespawn?: (this: Entity) => void;
+    onDespawn?: (entity: Entity) => void;
     /**
      * A function that is called every tick.
-     * @param this - The Entity instance.
+     * @param entity - The Entity instance that ticked.
      * @param tickDeltaMs - The delta time in milliseconds since the last tick.
      */
-    onTick?: (this: Entity, tickDeltaMs: number) => void;
+    onTick?: (entity: Entity, tickDeltaMs: number) => void;
 
 
 
@@ -1421,6 +1412,12 @@ export declare class EntityManager {
 
 /** Options for creating an Entity instance. @public */
 export declare interface EntityOptions {
+    /**
+     * A function that creates a custom character controller for the entity when it spawns.
+     * @param entity - The Entity instance.
+     * @returns A character controller that extends {@link BaseCharacterController}.
+     */
+    createCustomCharacterController?: (entity: Entity) => BaseCharacterController;
     /** The URI or path to the .gltf model asset to be used for the entity. */
     modelUri?: string;
     /** The looped animations to start when the entity is spawned. */
@@ -1507,6 +1504,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,6 +1641,13 @@ declare namespace HYTOPIA {
         RigidBodyType,
         RigidBodyAdditionalMassProperties,
         RigidBodyOptions,
+        SimpleCharacterController,
+        FaceCallback,
+        FaceCompleteCallback,
+        FaceOptions,
+        MoveCallback,
+        MoveCompleteCallback,
+        MoveOptions,
         Simulation,
         WebServer,
         PORT,
@@ -1629,6 +1661,42 @@ declare namespace HYTOPIA {
 }
 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 = {
+    /** Callback called each tick movement of the character controller's entity. */
+    moveCallback?: MoveCallback;
+    /** Callback called when the character controller's entity has finished moving. */
+    moveCompleteCallback?: MoveCompleteCallback;
+    /** Axes to ignore when moving the character controller's entity. Also ignored for determining completion. */
+    moveIgnoreAxes?: {
+        x?: boolean;
+        y?: boolean;
+        z?: boolean;
+    };
+};
+
 /**
  * A player in the game.
  *
@@ -2294,6 +2362,78 @@ 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. Compatible with
+ * entities that have kinematic or dynamic rigid body types.
+ *
+ * @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.
  *