hytopia 0.1.55 → 0.1.56

package/docs/server.defaultcharactercontroller.md

@@ -54,7 +54,7 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[(constructor)(entity, options)](./server.defaultcharactercontroller._constructor_.md)
+[(constructor)(options)](./server.defaultcharactercontroller._constructor_.md)
 
 
 </td><td>
@@ -290,7 +290,7 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[createColliders()](./server.defaultcharactercontroller.createcolliders.md)
+[attach(entity)](./server.defaultcharactercontroller.attach.md)
 
 
 </td><td>
@@ -298,13 +298,27 @@ Description
 
 </td><td>
 
-Creates the colliders for the character controller, overriding the default implementation.
+Called when the controller is attached to an entity.
 
 
 </td></tr>
 <tr><td>
 
-[tickWithPlayerInput(input, cameraOrientation, deltaTimeMs)](./server.defaultcharactercontroller.tickwithplayerinput.md)
+[spawn(entity)](./server.defaultcharactercontroller.spawn.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Called when the controlled entity is spawned. In DefaultCharacterController, this function is used to create the colliders for the entity for wall and ground detection.
+
+
+</td></tr>
+<tr><td>
+
+[tickWithPlayerInput(entity, input, cameraOrientation, deltaTimeMs)](./server.defaultcharactercontroller.tickwithplayerinput.md)
 
 
 </td><td>

package/docs/server.defaultcharactercontroller.spawn.md

@@ -0,0 +1,53 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [DefaultCharacterController](./server.defaultcharactercontroller.md) &gt; [spawn](./server.defaultcharactercontroller.spawn.md)
+
+## DefaultCharacterController.spawn() method
+
+Called when the controlled entity is spawned. In DefaultCharacterController, this function is used to create the colliders for the entity for wall and ground detection.
+
+**Signature:**
+
+```typescript
+spawn(entity: Entity): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+entity
+
+
+</td><td>
+
+[Entity](./server.entity.md)
+
+
+</td><td>
+
+The entity that is spawned.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+void
+

package/docs/server.defaultcharactercontroller.tickwithplayerinput.md

@@ -9,7 +9,7 @@ Ticks the player movement for the character controller, overriding the default i
 **Signature:**
 
 ```typescript
-tickWithPlayerInput(input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number): void;
+tickWithPlayerInput(entity: PlayerEntity, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number): void;
 ```
 
 ## Parameters
@@ -32,6 +32,22 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+entity
+
+
+</td><td>
+
+[PlayerEntity](./server.playerentity.md)
+
+
+</td><td>
+
+The entity to tick.
+
+
+</td></tr>
+<tr><td>
+
 input
 
 

package/docs/server.entity.md

@@ -164,25 +164,6 @@ The URI or path to the texture to be used, if this is set, the entity is a block
 The character controller for the entity.
 
 
-</td></tr>
-<tr><td>
-
-[createCustomCharacterController?](./server.entity.createcustomcharactercontroller.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; [BaseCharacterController](./server.basecharactercontroller.md)
-
-
-</td><td>
-
-_(Optional)_ A function that creates a custom character controller for the entity when it spawns.
-
-
 </td></tr>
 <tr><td>
 

package/docs/server.entity.setcharactercontroller.md

@@ -9,7 +9,7 @@ Sets the character controller for the entity.
 **Signature:**
 
 ```typescript
-setCharacterController(characterController: BaseCharacterController): void;
+setCharacterController(characterController: BaseCharacterController | undefined): void;
 ```
 
 ## Parameters
@@ -37,7 +37,7 @@ characterController
 
 </td><td>
 
-[BaseCharacterController](./server.basecharactercontroller.md)
+[BaseCharacterController](./server.basecharactercontroller.md) \| undefined
 
 
 </td><td>

package/docs/server.entityoptions.charactercontroller.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [EntityOptions](./server.entityoptions.md) &gt; [characterController](./server.entityoptions.charactercontroller.md)
+
+## EntityOptions.characterController property
+
+The character controller to use for the entity.
+
+**Signature:**
+
+```typescript
+characterController?: BaseCharacterController;
+```

package/docs/server.entityoptions.md

@@ -75,7 +75,7 @@ _(Optional)_ The texture uri of a entity if the entity is a block entity, if set
 </td></tr>
 <tr><td>
 
-[createCustomCharacterController?](./server.entityoptions.createcustomcharactercontroller.md)
+[characterController?](./server.entityoptions.charactercontroller.md)
 
 
 </td><td>
@@ -83,12 +83,12 @@ _(Optional)_ The texture uri of a entity if the entity is a block entity, if set
 
 </td><td>
 
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; [BaseCharacterController](./server.basecharactercontroller.md)
+[BaseCharacterController](./server.basecharactercontroller.md)
 
 
 </td><td>
 
-_(Optional)_ A function that creates a custom character controller for the entity when it spawns.
+_(Optional)_ The character controller to use for the entity.
 
 
 </td></tr>

package/examples/block-entity/index.ts

@@ -142,7 +142,7 @@ startServer(world => {
     blockHalfExtents: { x: 0.5, y: 0.5, z: 0.5 },
     // attach a simple character controller so we can pathfind,
     // the character controller will be created and associated when we spawn the entity
-    createCustomCharacterController: entity => new SimpleCharacterController(entity), 
+    characterController: new SimpleCharacterController(), 
   });
 
   blockPet.spawn(world, { x: 0, y: 10, z: -6 });

package/examples/character-controller/MyCharacterController.ts

@@ -1,41 +1,102 @@
 import {
   Audio,
   BaseCharacterController,
-  CollisionGroup,
-  Collider,
-  Entity,
   ColliderShape,
   CoefficientCombineRule,
+  CollisionGroup,
+  Entity,
+  PlayerEntity,
   BlockType,
 } from 'hytopia';
 
 import type {
   PlayerInput,
   PlayerCameraOrientation,
-  Vector3,
 } from 'hytopia';
 
+/** Options for creating a MyCharacterController instance. @public */
+export interface MyCharacterControllerOptions {
+  /** 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;
+
+  /** The normalized horizontal velocity applied to the entity when it walks. */
+  walkVelocity?: number;
+
+  /** 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;
+}
+
+/**
+ * A custom character controller implementation.
+ * 
+ * @remarks
+ * This class extends {@link BaseCharacterController}
+ * and implements the default movement logic for a
+ * character entity. 
+ * 
+ * @public
+ */
 export default class MyCharacterController extends BaseCharacterController {
+  /** The upward velocity applied to the entity when it jumps. */
   public jumpVelocity: number = 10;
+
+  /** The normalized horizontal velocity applied to the entity when it runs. */
   public runVelocity: number = 8;
+
+  /** The normalized horizontal velocity applied to the entity when it walks. */
   public walkVelocity: number = 4;
 
-  private _stepAudio: Audio;
-  private _groundContactCount: number = 0;
-  private _platform: Entity | undefined;
+  /**
+   * A function allowing custom logic to determine if the entity can walk.
+   * @param myCharacterController - The character controller instance.
+   * @returns Whether the entity of the character controller can walk.
+   */
+  public canWalk: (myCharacterController: MyCharacterController) => boolean = () => true;
 
-  public constructor(entity: Entity) {
-    super(entity);
+  /**
+   * A function allowing custom logic to determine if the entity can run.
+   * @param myCharacterController - The character controller instance.
+   * @returns Whether the entity of the character controller can run.
+   */
+  public canRun: (myCharacterController: MyCharacterController) => boolean = () => true;
 
-    // Setup any audio or dependencies in the constructor.
-    this._stepAudio = new Audio({
-      uri: 'audio/sfx/step.wav',
-      loop: true,
-      volume: 0.1,
-      attachedToEntity: this.entity,
-    });
+  /**
+   * A function allowing custom logic to determine if the entity can jump.
+   * @param myCharacterController - The character controller instance.
+   * @returns Whether the entity of the character controller can jump.
+   */
+  public canJump: (myCharacterController: MyCharacterController) => boolean = () => true;
+
+  /** @internal */
+  private _stepAudio: Audio | undefined;
+
+  /** @internal */
+  private _groundContactCount: number = 0;
+
+  /** @internal */
+  private _platform: Entity | undefined;
 
-    this.entity.lockAllRotations(); // prevent physics from applying rotation to the entity.
+  /**
+   * @param options - Options for the controller.
+   */
+  public constructor(options: MyCharacterControllerOptions = {}) {
+    super();
+
+    this.jumpVelocity = options.jumpVelocity ?? this.jumpVelocity;
+    this.runVelocity = options.runVelocity ?? this.runVelocity;
+    this.walkVelocity = options.walkVelocity ?? this.walkVelocity;
+    this.canWalk = options.canWalk ?? this.canWalk;
+    this.canRun = options.canRun ?? this.canRun;
+    this.canJump = options.canJump ?? this.canJump;
   }
 
   /** Whether the entity is grounded. */
@@ -48,41 +109,51 @@ export default class MyCharacterController extends BaseCharacterController {
   public get platform(): Entity | undefined { return this._platform; }
 
   /**
-   * Create the colliders for the character controller.
+   * Called when the controller is attached to an entity.
+   * @param entity - The entity to attach the controller to.
    */
-  public createColliders(): Collider[] {
-    if (!this.entity.isSpawned) {
-      throw new Error('CharacterController.createSensorColliders(): Entity is not spawned!');
-    }
+  public attach(entity: Entity) {
+    this._stepAudio = new Audio({
+      uri: 'audio/sfx/step.wav',
+      loop: true,
+      volume: 0.1,
+      attachedToEntity: entity,
+    });
+
+    entity.lockAllRotations(); // prevent physics from applying rotation to the entity, we can still explicitly set it.
+  };
 
-    const colliders: Collider[] = [];
+  /**
+   * Called when the controlled entity is spawned.
+   * In MyCharacterController, this function is used to create
+   * the colliders for the entity for wall and ground detection.
+   * @param entity - The entity that is spawned.
+   */
+  public spawn(entity: Entity) {
+    if (!entity.isSpawned) {
+      throw new Error('CharacterController.createColliders(): Entity is not spawned!');
+    }
 
-    /**
-     * Our ground sensor detects when we're on the ground.
-     * It assumes a cylinder shape and is positioned manually
-     * relative to the default entity rigid body as defined
-     * by the DEFAULT_ENTITY_RIGID_BODY_OPTIONS constant of
-     * the hytopia package.
-     */
-    colliders.push(new Collider({
+    // Ground sensor
+    entity.createAndAddChildColliderToSimulation({
       shape: ColliderShape.CYLINDER,
-      radius: 0.30,
+      radius: 0.23,
       halfHeight: 0.125,
       collisionGroups: {
         belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
         collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY ],
       },
       isSensor: true,
-      relativeTranslation: { x: 0, y: -0.75, z: 0 },
+      relativePosition: { x: 0, y: -0.75, z: 0 },
       tag: 'groundSensor',
       onCollision: (_other: BlockType | Entity, started: boolean) => {
         // Ground contact
         this._groundContactCount += started ? 1 : -1;
   
-        if (!this._groundContactCount) { // Trigger animations
-          this.entity.startModelOneshotAnimations([ 'jump_loop' ]);
+        if (!this._groundContactCount) {
+          entity.startModelOneshotAnimations([ 'jump_loop' ]);
         } else {
-          this.entity.stopModelAnimations([ 'jump_loop' ]);
+          entity.stopModelAnimations([ 'jump_loop' ]);
         }
 
         // Platform contact
@@ -94,15 +165,11 @@ export default class MyCharacterController extends BaseCharacterController {
           this._platform = undefined;
         }
       },
-    }));
-
-    /**
-     * A wall collider slightly larger than our player hitbox with
-     * a collision group that only collides with blocks. This prevent
-     * sticking and friction to blocks as a player moves, creating
-     * a smooth slide effect on walls that we jump into, etc.
-     */
-    colliders.push(new Collider({
+    });
+
+
+    // Wall collider
+    entity.createAndAddChildColliderToSimulation({
       shape: ColliderShape.CAPSULE,
       halfHeight: 0.30,
       radius: 0.37,
@@ -113,101 +180,109 @@ export default class MyCharacterController extends BaseCharacterController {
       friction: 0,
       frictionCombineRule: CoefficientCombineRule.Min,
       tag: 'wallCollider',
-    }));
-
-    return colliders;
-  }
+    });
+  };
 
   /**
-   * Handles movement of the entity based on player's input
-   * each tick. tickPlayerMovement is called internally if the entity
-   * is of the PlayerEntity class.
+   * Ticks the player movement for the character controller,
+   * overriding the default implementation.
+   * 
+   * @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.
    */
-  public tickWithPlayerInput(input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number) {
-    if (!this.entity.isSpawned || !this.entity.world) return; // type guard.
+  public tickWithPlayerInput(entity: PlayerEntity, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, deltaTimeMs: number) {
+    if (!entity.isSpawned || !entity.world) return;
 
-    super.tickWithPlayerInput(input, cameraOrientation, deltaTimeMs);
+    super.tickWithPlayerInput(entity, input, cameraOrientation, deltaTimeMs);
 
-    const { w, a, s, d, sp, sh, ml, mr } = input; // See PlayerInput type for all possible inputs.
-    const { yaw } = cameraOrientation; // Camera/perspectie orientation of player.
-    const currentVelocity = this.entity.getLinearVelocity();
+    const { w, a, s, d, sp, sh, ml } = input;
+    const { yaw } = cameraOrientation;
+    const currentVelocity = entity.linearVelocity;
     const targetVelocities = { x: 0, y: 0, z: 0 };
     const isRunning = sh;
 
-    // Handle movement animations if relevant.
-    if (w || a || s || d) {
+    // Temporary, animations
+    if (this.isGrounded && (w || a || s || d)) {
       if (isRunning) {
-        // We stop irrelevant animations to prevent blending issues.
-        this.entity.stopModelAnimations(Array.from(this.entity.modelLoopedAnimations).filter(v => v !== 'run'));
-        // If run is already playing, internally startModelLoopedAnimations will do nothing.
-        this.entity.startModelLoopedAnimations([ 'run' ]);
-        // Manually set a playback rate of our step audio to audibly sync to our walk speed.
-        this._stepAudio.setPlaybackRate(0.83);
+        entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => v !== 'run'));
+        entity.startModelLoopedAnimations([ 'run' ]);
+        this._stepAudio?.setPlaybackRate(0.83);
       } else {
-        this.entity.stopModelAnimations(Array.from(this.entity.modelLoopedAnimations).filter(v => v !== 'walk'));
-        this.entity.startModelLoopedAnimations([ 'walk' ]);
-        this._stepAudio.setPlaybackRate(0.5);
+        entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => v !== 'walk'));
+        entity.startModelLoopedAnimations([ 'walk' ]);
+        this._stepAudio?.setPlaybackRate(0.5);
       }
 
-      this._stepAudio.play(this.entity.world, !this._stepAudio.isPlaying);
+      this._stepAudio?.play(entity.world, !this._stepAudio?.isPlaying);
     } else {
-      this._stepAudio.pause();
-      this.entity.stopModelAnimations(Array.from(this.entity.modelLoopedAnimations).filter(v => v !== 'idle'));
-      this.entity.startModelLoopedAnimations([ 'idle' ]);
+      this._stepAudio?.pause();
+      entity.stopModelAnimations(Array.from(entity.modelLoopedAnimations).filter(v => v !== 'idle'));
+      entity.startModelLoopedAnimations([ 'idle' ]);
     }
 
-    // Play a simple interact animation on left mouse click then clear the input.
     if (ml) {
-      this.entity.startModelOneshotAnimations([ 'simple_interact' ]);
-      input.ml = false;
-    }
+      entity.startModelOneshotAnimations([ 'simple_interact' ]);
+
+      // break a block
+      const ray = entity.world.simulation.raycast(
+        entity.position,
+        entity.player.camera.facingDirection,
+        10,
+        { filterExcludeRigidBody: entity.rawRigidBody },
+      );
+
+      if (ray?.hitBlock) {
+        // Remove the block
+        entity.world.chunkLattice.setBlock(ray.hitBlock.globalCoordinate, 0);
+      }
 
-    // Rocket the player up on mouse right click.
-    if (mr) {
-      targetVelocities.y = 20;
-      input.mr = false;
+      input.ml = false;
     }
 
     // Calculate target horizontal velocities (run/walk)
-    const velocity = isRunning ? this.runVelocity : this.walkVelocity;
+    if ((isRunning && this.canRun(this)) || (!isRunning && this.canWalk(this))) {
+      const velocity = isRunning ? this.runVelocity : this.walkVelocity;
 
-    if (w) {
-      targetVelocities.x -= velocity * Math.sin(yaw);
-      targetVelocities.z -= velocity * Math.cos(yaw);
-    }
-
-    if (s) {
-      targetVelocities.x += velocity * Math.sin(yaw);
-      targetVelocities.z += velocity * Math.cos(yaw);
-    }
-    
-    if (a) {
-      targetVelocities.x -= velocity * Math.cos(yaw);
-      targetVelocities.z += velocity * Math.sin(yaw);
-    }
-    
-    if (d) {
-      targetVelocities.x += velocity * Math.cos(yaw);
-      targetVelocities.z -= velocity * Math.sin(yaw);
-    }
+      if (w) {
+        targetVelocities.x -= velocity * Math.sin(yaw);
+        targetVelocities.z -= velocity * Math.cos(yaw);
+      }
+  
+      if (s) {
+        targetVelocities.x += velocity * Math.sin(yaw);
+        targetVelocities.z += velocity * Math.cos(yaw);
+      }
+      
+      if (a) {
+        targetVelocities.x -= velocity * Math.cos(yaw);
+        targetVelocities.z += velocity * Math.sin(yaw);
+      }
+      
+      if (d) {
+        targetVelocities.x += velocity * Math.cos(yaw);
+        targetVelocities.z -= velocity * Math.sin(yaw);
+      }
 
-    // Normalize for diagonals
-    const length = Math.sqrt(targetVelocities.x * targetVelocities.x + targetVelocities.z * targetVelocities.z);
-    if (length > velocity) {
-      const factor = velocity / length;
-      targetVelocities.x *= factor;
-      targetVelocities.z *= factor;
+      // Normalize for diagonals
+      const length = Math.sqrt(targetVelocities.x * targetVelocities.x + targetVelocities.z * targetVelocities.z);
+      if (length > velocity) {
+        const factor = velocity / length;
+        targetVelocities.x *= factor;
+        targetVelocities.z *= factor;
+      }
     }
 
     // Calculate target vertical velocity (jump)
-    if (sp) {
-      if (this.isGrounded && currentVelocity.y <= 3) {
+    if (sp && this.canJump(this)) {
+      if (this.isGrounded && currentVelocity.y > -0.001 && currentVelocity.y <= 3) {
         targetVelocities.y = this.jumpVelocity;
       }
     }
 
     // Apply impulse relative to target velocities, taking platform velocity into account
-    const platformVelocity = this._platform ? this._platform.getLinearVelocity() : { x: 0, y: 0, z: 0 };
+    const platformVelocity = this._platform ? this._platform.linearVelocity : { x: 0, y: 0, z: 0 };
     const deltaVelocities = {
       x: targetVelocities.x - currentVelocity.x + platformVelocity.x,
       y: targetVelocities.y + platformVelocity.y,
@@ -219,11 +294,11 @@ export default class MyCharacterController extends BaseCharacterController {
       Math.abs(currentVelocity.y) > this.jumpVelocity ||
       Math.abs(currentVelocity.z) > this.runVelocity;
 
-    if (!hasExternalVelocity) { // allow external velocities like impulses to resolve, otherwise our deltas will cancel them out.
+    if (!hasExternalVelocity) { // allow external velocities to resolve, otherwise our deltas will cancel them out.
       if (Object.values(deltaVelocities).some(v => v !== 0)) {
-        const mass = this.entity.getMass();
+        const mass = entity.mass;        
 
-        this.entity.applyImpulse({ // multiply by mass for the impulse to result in applying the correct target velocity
+        entity.applyImpulse({ // multiply by mass for the impulse to result in applying the correct target velocity
           x: deltaVelocities.x * mass,
           y: deltaVelocities.y * mass,
           z: deltaVelocities.z * mass,
@@ -231,11 +306,11 @@ export default class MyCharacterController extends BaseCharacterController {
       }
     }
 
-    // Apply rotation relative to camera orientation.
+    // Apply rotation
     if (yaw !== undefined) {
       const halfYaw = yaw / 2;
       
-      this.entity.setRotation({
+      entity.setRotation({
         x: 0,
         y: Math.fround(Math.sin(halfYaw)),
         z: 0,
@@ -243,8 +318,4 @@ export default class MyCharacterController extends BaseCharacterController {
       });
     }
   }
-
-  public tickPathfindingMovement(_destination: Vector3, _deltaTimeMs: number) {
-    console.log('Non-player pathfinding not implemented!');
-  }
 }