hytopia 0.4.4 → 0.5.0-dev

package/server.d.ts

@@ -1094,9 +1094,11 @@ export declare class Collider extends EventRouter {
     /**
      * Creates a collider options object from a modelUri with best approximate shape and size.
      * @param modelUri - The URI of the model.
+     * @param scale - The scale of the model.
+     * @param preferredShape - The preferred shape to use for the collider.
      * @returns The collider options object.
      */
-    static optionsFromModelUri(modelUri: string, scale?: number): ColliderOptions;
+    static optionsFromModelUri(modelUri: string, scale?: number, preferredShape?: ColliderShape): ColliderOptions;
     /** The bounciness of the collider. */
     get bounciness(): number;
     /** The bounciness combine rule of the collider. */
@@ -1221,15 +1223,16 @@ export declare class Collider extends EventRouter {
     removeFromSimulation(): void;
 
 
+    private _buildWedgeConvexHullVertices;
+
+
 
 
-    private _requireUnsimulated;
-    private _requireNotRemoved;
 
 }
 
 /** The options for a collider. @public */
-export declare type ColliderOptions = BallColliderOptions | BlockColliderOptions | CapsuleColliderOptions | ConeColliderOptions | CylinderColliderOptions | RoundCylinderColliderOptions | TrimeshColliderOptions | NoneColliderOptions;
+export declare type ColliderOptions = BallColliderOptions | BlockColliderOptions | CapsuleColliderOptions | ConeColliderOptions | CylinderColliderOptions | RoundCylinderColliderOptions | TrimeshColliderOptions | WedgeColliderOptions | NoneColliderOptions;
 
 /** The shapes a collider can be. @public */
 export declare enum ColliderShape {
@@ -1240,7 +1243,8 @@ export declare enum ColliderShape {
     CONE = "cone",
     CYLINDER = "cylinder",
     ROUND_CYLINDER = "round-cylinder",
-    TRIMESH = "trimesh"
+    TRIMESH = "trimesh",
+    WEDGE = "wedge"
 }
 
 /**
@@ -1411,6 +1415,197 @@ export declare type DecodedCollisionGroups = {
 /** The default rigid body options for a model entity when EntityOptions.rigidBodyOptions is not provided. @public */
 export declare const DEFAULT_ENTITY_RIGID_BODY_OPTIONS: RigidBodyOptions;
 
+/**
+ * Represents the default player model entity.
+ *
+ * @remarks
+ * The default player entity extends the {@link PlayerEntity} class,
+ * uses the default player model, and assigns a DefaultPlayerEntityController.
+ * This entity is the most commonly used player controlled entity in games.
+ * It automatically handles things like managing player visual customizations
+ * and cosmetics, and more. If you want to change the default model used, you
+ * can override all of the defaults, including the modelUri, but you must
+ * ensure that the model used has the same animation names and anchor points
+ * as the default player model in order to prevent unexpected behavior.
+ *
+ * @example
+ * ```typescript
+ * const playerEntity = new DefaultPlayerEntity({ player });
+ *
+ * playerEntity.spawn(world, { x: 0, y: 10, z: 0 });
+ * ```
+ *
+ * @public
+ */
+export declare class DefaultPlayerEntity extends PlayerEntity {
+    constructor(options: DefaultPlayerEntityOptions);
+}
+
+/**
+ * The player entity controller implementation.
+ *
+ * @remarks
+ * This class extends {@link BaseEntityController}
+ * and implements the default movement, platforming, jump,
+ * swimming, and other basic logic for the
+ * default player entity. We recommend you extend this class
+ * if you'd like to implement additional logic on top of the
+ * DefaultPlayerEntityController implementation.
+ *
+ * @example
+ * ```typescript
+ * // Create a custom entity controller for myEntity, prior to spawning it.
+ * myEntity.setController(new DefaultPlayerEntityController({
+ *   jumpVelocity: 10,
+ *   runVelocity: 8,
+ *   walkVelocity: 4,
+ * }));
+ *
+ * // Spawn the entity in the world.
+ * myEntity.spawn(world, { x: 53, y: 10, z: 23 });
+ * ```
+ *
+ * @public
+ */
+export declare class DefaultPlayerEntityController extends BaseEntityController {
+    /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
+    autoCancelMouseLeftClick: boolean;
+    /**
+     * A function allowing custom logic to determine if the entity can walk.
+     * @param controller - The default player entity controller instance.
+     * @returns Whether the entity of the entity controller can walk.
+     */
+    canWalk: (controller: DefaultPlayerEntityController) => boolean;
+    /**
+     * A function allowing custom logic to determine if the entity can run.
+     * @param controller - The default player entity controller instance.
+     * @returns Whether the entity of the entity controller can run.
+     */
+    canRun: (controller: DefaultPlayerEntityController) => boolean;
+    /**
+     * A function allowing custom logic to determine if the entity can jump.
+     * @param controller - The default player entity controller instance.
+     * @returns Whether the entity of the entity controller can jump.
+     */
+    canJump: (controller: DefaultPlayerEntityController) => boolean;
+    /** The looped animation(s) that will play when the entity is idle. */
+    idleLoopedAnimations: string[];
+    /** The oneshot animation(s) that will play when the entity interacts (left click) */
+    interactOneshotAnimations: string[];
+    /** The oneshot animation(s) that will play when the entity is jumping. */
+    jumpOneshotAnimations: string[];
+    /** The upward velocity applied to the entity when it jumps. */
+    jumpVelocity: number;
+    /** The looped animation(s) that will play when the entity is running. */
+    runLoopedAnimations: string[];
+    /** The normalized horizontal velocity applied to the entity when it runs. */
+    runVelocity: number;
+    /** Whether the entity sticks to platforms. */
+    sticksToPlatforms: boolean;
+    /** The normalized horizontal velocity applied to the entity when it swims fast (equivalent to running). */
+    swimFastVelocity: number;
+    /** The gravity modifier applied to the entity when swimming. */
+    swimGravity: number;
+    /** The looped animation(s) that will play when the entity is swimming. */
+    swimLoopedAnimations: string[];
+    /** The maximum downward velocity that the entity can reach when affected by gravity while swimming. */
+    swimMaxGravityVelocity: number;
+    /** The normalized horizontal velocity applied to the entity when it swims slowly (equivalent to walking). */
+    swimSlowVelocity: number;
+    /** The upward velocity applied to the entity when swimming. */
+    swimUpwardVelocity: number;
+    /** The looped animation(s) that will play when the entity is walking. */
+    walkLoopedAnimations: string[];
+    /** The normalized horizontal velocity applied to the entity when it walks. */
+    walkVelocity: number;
+
+
+
+
+
+    /**
+     * @param options - Options for the controller.
+     */
+    constructor(options?: DefaultPlayerEntityControllerOptions);
+    /** Whether the entity is grounded. */
+    get isGrounded(): boolean;
+    /** Whether the entity is on a platform, a platform is any entity with a kinematic rigid body. */
+    get isOnPlatform(): boolean;
+    /** Whether the entity is swimming, this is determined by if the entity is in a liquid block. */
+    get isSwimming(): boolean;
+    /** The platform the entity is on, if any. */
+    get platform(): Entity | undefined;
+    /**
+     * Called when the controller is attached to an entity.
+     * @param entity - The entity to attach the controller to.
+     */
+    attach(entity: Entity): void;
+    /**
+     * Called when the controlled entity is spawned.
+     * In DefaultPlayerEntityController, this function is used to create
+     * the colliders for the entity for wall and ground detection.
+     * @param entity - The entity that is spawned.
+     */
+    spawn(entity: Entity): void;
+    /**
+     * Ticks the player movement for the entity controller,
+     * overriding the default implementation. If the entity to tick
+     * is a child entity, only the event will be emitted but the default
+     * movement logic will not be applied.
+     *
+     * @param entity - The entity to tick.
+     * @param input - The current input state of the player.
+     * @param cameraOrientation - The current camera orientation state of the player.
+     * @param deltaTimeMs - The delta time in milliseconds since the last tick.
+     */
+    tickWithPlayerInput(entity: PlayerEntity, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number): void;
+}
+
+/** Options for creating a DefaultPlayerEntityController instance. @public */
+export declare interface DefaultPlayerEntityControllerOptions {
+    /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
+    autoCancelMouseLeftClick?: boolean;
+    /** A function allowing custom logic to determine if the entity can jump. */
+    canJump?: () => boolean;
+    /** A function allowing custom logic to determine if the entity can walk. */
+    canWalk?: () => boolean;
+    /** A function allowing custom logic to determine if the entity can run. */
+    canRun?: () => boolean;
+    /** Overrides the animation(s) that will play when the entity is idle. */
+    idleLoopedAnimations?: string[];
+    /** Overrides the animation(s) that will play when the entity interacts (left click) */
+    interactOneshotAnimations?: string[];
+    /** Overrides the animation(s) that will play when the entity is jumping. */
+    jumpOneshotAnimations?: string[];
+    /** The upward velocity applied to the entity when it jumps. */
+    jumpVelocity?: number;
+    /** The normalized horizontal velocity applied to the entity when it runs. */
+    runVelocity?: number;
+    /** Overrides the animation(s) that will play when the entity is running. */
+    runLoopedAnimations?: string[];
+    /** Whether the entity sticks to platforms, defaults to true. */
+    sticksToPlatforms?: boolean;
+    /** The normalized horizontal velocity applied to the entity when it swims fast (equivalent to running). */
+    swimFastVelocity?: number;
+    /** The gravity modifier applied to the entity when swimming. */
+    swimGravity?: number;
+    /** The maximum downward velocity that the entity can reach when affected by gravity while swimming. */
+    swimMaxGravityVelocity?: number;
+    /** The looped animation(s) that will play when the entity is swimming. */
+    swimLoopedAnimations?: string[];
+    /** The normalized horizontal velocity applied to the entity when it swims slowly (equivalent to walking). */
+    swimSlowVelocity?: number;
+    /** The upward velocity applied to the entity when swimming. */
+    swimUpwardVelocity?: number;
+    /** Overrides the animation(s) that will play when the entity is walking. */
+    walkLoopedAnimations?: string[];
+    /** The normalized horizontal velocity applied to the entity when it walks. */
+    walkVelocity?: number;
+}
+
+/** Options for creating a DefaultPlayerEntity instance. @public */
+export declare type DefaultPlayerEntityOptions = {} & PlayerEntityOptions;
+
 /** The options for a dynamic rigid body, also the default type. @public */
 export declare interface DynamicRigidBodyOptions extends BaseRigidBodyOptions {
     type?: RigidBodyType.DYNAMIC;
@@ -1504,6 +1699,7 @@ export declare class Entity extends RigidBody implements protocol.Serializable {
 
 
 
+
 
     /**
      * @param options - The options for the entity.
@@ -1525,6 +1721,8 @@ export declare class Entity extends RigidBody implements protocol.Serializable {
     get modelHiddenNodes(): ReadonlySet<string>;
     /** The looped animations to start when the entity is spawned. */
     get modelLoopedAnimations(): ReadonlySet<string>;
+    /** The preferred shape of the entity's model when automatically generating its collider when no explicit colliders are provided. */
+    get modelPreferredShape(): ColliderShape | undefined;
     /** The scale of the entity's model. */
     get modelScale(): number | undefined;
     /** The URI or path to the .gltf model asset to be used for the entity. */
@@ -2944,7 +3142,7 @@ export declare class Matrix4 extends Float32Array {
 }
 
 /** A bounding box for a model. @public */
-declare type ModelBoundingBox = {
+export declare type ModelBoundingBox = {
     min: Vector3Like;
     max: Vector3Like;
 };
@@ -2957,6 +3155,8 @@ export declare interface ModelEntityOptions extends BaseEntityOptions {
     modelHiddenNodes?: string[];
     /** The looped animations to start when the entity is spawned. */
     modelLoopedAnimations?: string[];
+    /** The preferred shape of the entity's model when automatically generating its collider when no explicit colliders are provided. */
+    modelPreferredShape?: ColliderShape;
     /** The scale of the entity's model. */
     modelScale?: number;
     /** The URI or path to the .gltf model asset to be used for the entity. */
@@ -2993,6 +3193,7 @@ export declare class ModelRegistry {
 
 
 
+
     /**
      * Retrieves the bounding box of a model.
      *
@@ -3014,6 +3215,14 @@ export declare class ModelRegistry {
      * @returns The names of all nodes in the model.
      */
     getNodeNames(modelUri: string): string[];
+    /**
+     * Retrieves the trimesh of a model.
+     *
+     * @param modelUri - The URI of the model to retrieve the trimesh for.
+     * @param scale - Optional uniform scaling to apply to the trimesh. Defaults to 1, which is no scaling.
+     * @returns The trimesh of the model.
+     */
+    getTrimesh(modelUri: string, scale?: number): ModelTrimesh | undefined;
     /**
      * Checks if a model has a node with the given name.
      *
@@ -3030,8 +3239,15 @@ export declare class ModelRegistry {
 
 
 
+
 }
 
+/** A trimesh for a model. @public */
+export declare type ModelTrimesh = {
+    vertices: Float32Array;
+    indices: Uint32Array;
+};
+
 /**
  * A callback function called when the entity associated with the
  * SimpleEntityController updates its position as it is
@@ -3561,12 +3777,13 @@ export declare type PlayerCameraOrientation = {
  *
  * @remarks
  * Player entities extend the {@link Entity} class.
- * They can be created and assigned to a player when
- * a player joins a world. PlayerEntity automatically
- * handles mapping player inputs to the associated
- * entity controller of the entity, calling the
- * entity controller's onTickPlayerMovement method
- * when player input has changed.
+ * They can be created and assigned to a player at
+ * anytime during gameplay, but most commonly when
+ * a player joins a world. PlayerEntity expects
+ * a controller to be set prior to spawning.
+ * Without setting a controller, the player entity
+ * will not respond to player inputs and throw an
+ * error.
  *
  * @example
  * ```typescript
@@ -3598,140 +3815,6 @@ export declare class PlayerEntity extends Entity {
 
 }
 
-/**
- * The player entity controller implementation.
- *
- * @remarks
- * This class extends {@link BaseEntityController}
- * and implements the default movement logic for a
- * entity. This is used as the default for
- * players when they join your game. This class may be extended
- * if you'd like to implement additional logic on top of the
- * PlayerEntityController implementation.
- *
- * @example
- * ```typescript
- * // Create a custom entity controller for myEntity, prior to spawning it.
- * myEntity.setController(new PlayerEntityController(myEntity, {
- *   jumpVelocity: 10,
- *   runVelocity: 8,
- *   walkVelocity: 4,
- * }));
- *
- * // Spawn the entity in the world.
- * myEntity.spawn(world, { x: 53, y: 10, z: 23 });
- * ```
- *
- * @public
- */
-export declare class PlayerEntityController extends BaseEntityController {
-    /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
-    autoCancelMouseLeftClick: boolean;
-    /**
-     * A function allowing custom logic to determine if the entity can walk.
-     * @param playerEntityController - The entity controller instance.
-     * @returns Whether the entity of the entity controller can walk.
-     */
-    canWalk: (playerEntityController: PlayerEntityController) => boolean;
-    /**
-     * A function allowing custom logic to determine if the entity can run.
-     * @param playerEntityController - The entity controller instance.
-     * @returns Whether the entity of the entity controller can run.
-     */
-    canRun: (playerEntityController: PlayerEntityController) => boolean;
-    /**
-     * A function allowing custom logic to determine if the entity can jump.
-     * @param playerEntityController - The entity controller instance.
-     * @returns Whether the entity of the entity controller can jump.
-     */
-    canJump: (playerEntityController: PlayerEntityController) => boolean;
-    /** The looped animation(s) that will play when the entity is idle. */
-    idleLoopedAnimations: string[];
-    /** The oneshot animation(s) that will play when the entity interacts (left click) */
-    interactOneshotAnimations: string[];
-    /** The oneshot animation(s) that will play when the entity is jumping. */
-    jumpOneshotAnimations: string[];
-    /** The upward velocity applied to the entity when it jumps. */
-    jumpVelocity: number;
-    /** The looped animation(s) that will play when the entity is running. */
-    runLoopedAnimations: string[];
-    /** The normalized horizontal velocity applied to the entity when it runs. */
-    runVelocity: number;
-    /** Whether the entity sticks to platforms. */
-    sticksToPlatforms: boolean;
-    /** The looped animation(s) that will play when the entity is walking. */
-    walkLoopedAnimations: string[];
-    /** The normalized horizontal velocity applied to the entity when it walks. */
-    walkVelocity: number;
-
-
-
-    /**
-     * @param options - Options for the controller.
-     */
-    constructor(options?: PlayerEntityControllerOptions);
-    /** Whether the entity is grounded. */
-    get isGrounded(): boolean;
-    /** Whether the entity is on a platform, a platform is any entity with a kinematic rigid body. */
-    get isOnPlatform(): boolean;
-    /** The platform the entity is on, if any. */
-    get platform(): Entity | undefined;
-    /**
-     * Called when the controller is attached to an entity.
-     * @param entity - The entity to attach the controller to.
-     */
-    attach(entity: Entity): void;
-    /**
-     * Called when the controlled entity is spawned.
-     * In PlayerEntityController, this function is used to create
-     * the colliders for the entity for wall and ground detection.
-     * @param entity - The entity that is spawned.
-     */
-    spawn(entity: Entity): void;
-    /**
-     * Ticks the player movement for the entity controller,
-     * overriding the default implementation. If the entity to tick
-     * is a child entity, only the event will be emitted but the default
-     * movement logic will not be applied.
-     *
-     * @param entity - The entity to tick.
-     * @param input - The current input state of the player.
-     * @param cameraOrientation - The current camera orientation state of the player.
-     * @param deltaTimeMs - The delta time in milliseconds since the last tick.
-     */
-    tickWithPlayerInput(entity: PlayerEntity, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number): void;
-}
-
-/** Options for creating a PlayerEntityController instance. @public */
-export declare interface PlayerEntityControllerOptions {
-    /** Whether to automatically cancel left click input after first processed tick, defaults to true. */
-    autoCancelMouseLeftClick?: boolean;
-    /** A function allowing custom logic to determine if the entity can jump. */
-    canJump?: () => boolean;
-    /** A function allowing custom logic to determine if the entity can walk. */
-    canWalk?: () => boolean;
-    /** A function allowing custom logic to determine if the entity can run. */
-    canRun?: () => boolean;
-    /** Overrides the animation(s) that will play when the entity is idle. */
-    idleLoopedAnimations?: string[];
-    /** Overrides the animation(s) that will play when the entity interacts (left click) */
-    interactOneshotAnimations?: string[];
-    /** Overrides the animation(s) that will play when the entity is jumping. */
-    jumpOneshotAnimations?: string[];
-    /** The upward velocity applied to the entity when it jumps. */
-    jumpVelocity?: number;
-    /** The normalized horizontal velocity applied to the entity when it runs. */
-    runVelocity?: number;
-    /** Overrides the animation(s) that will play when the entity is running. */
-    runLoopedAnimations?: string[];
-    /** Whether the entity sticks to platforms, defaults to true. */
-    sticksToPlatforms?: boolean;
-    /** Overrides the animation(s) that will play when the entity is walking. */
-    walkLoopedAnimations?: string[];
-    /** The normalized horizontal velocity applied to the entity when it walks. */
-    walkVelocity?: number;
-}
-
 /** Options for creating a PlayerEntity instance. @public */
 export declare type PlayerEntityOptions = {
     /** The player the player entity is assigned to. */
@@ -5514,6 +5597,13 @@ export declare type WaypointMoveCompleteCallback = (waypoint: Vector3Like, waypo
  */
 export declare type WaypointMoveSkippedCallback = (waypoint: Vector3Like, waypointIndex: number) => void;
 
+/** The options for a wedge collider. @public */
+export declare interface WedgeColliderOptions extends BaseColliderOptions {
+    shape: ColliderShape.WEDGE;
+    /** The extents of the wedge collider, defining full width (x), height (y), and length (z). */
+    extents?: Vector3Like;
+}
+
 /**
  * Represents a world in the game server.
  *