hytopia 0.1.54 → 0.1.56

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!');
-  }
 }

package/examples/character-controller/index.ts

@@ -11,6 +11,10 @@ startServer(world => {
   // Uncomment this to visualize physics vertices, will cause noticable lag.
   // world.simulation.enableDebugRendering(true);
   
+  // Visualize raycasts, like block breaking for our
+  // character controller.
+  world.simulation.enableDebugRaycasting(true);
+
   world.loadMap(worldMap);
 
   world.onPlayerJoin = player => {
@@ -20,18 +24,9 @@ startServer(world => {
       modelUri: 'models/player.gltf',
       modelLoopedAnimations: [ 'idle' ],
       modelScale: 0.5,
+      characterController: new MyCharacterController(), // attach our character controller
     });
 
-    // Assign a custom character controller factory to the player entity.
-    // This must be assigned before spawning the entity.
-    // createCustomCharacterController if set will be handled internally when
-    // .spawn() is called.
-    playerEntity.createCustomCharacterController = () => {
-      console.log('Creating custom player entity character controller...');
-
-      return new MyCharacterController(playerEntity);
-    };
-
     playerEntity.spawn(world, { x: 0, y: 10, z: 0 });
     console.log('Spawned player entity!');
 

package/examples/custom-ui/index.ts

@@ -45,7 +45,7 @@ startServer(world => {
         const randomY = Math.random() * 13 + 2;  // Random between 2 and 15
         const randomZ = Math.random() * 40 - 20; // Random between -20 and 20
 
-        playerEntity.setTranslation({ x: randomX, y: randomY, z: randomZ });
+        playerEntity.setPosition({ x: randomX, y: randomY, z: randomZ });
       }
     };
   };
@@ -75,7 +75,7 @@ function updatePlayerList() {
     // For each player, return their username and current position
     return {
       username: player.username,
-      position: entity.getTranslation(), // Gets x,y,z coordinate
+      position: entity.position, // Gets x,y,z coordinate
     };
   });
 

package/examples/payload-game/index.ts

@@ -151,7 +151,7 @@ startServer(world => { // Perform our game setup logic in the startServer init c
     // physics engine we use where entities despawned to not trigger a collision
     // event for leaving a sensor. This is a workaround till a better solution is found.
     world.entityManager.getAllPlayerEntities(player).forEach(entity => {
-      entity.setTranslation({ x: 0, y: 100, z: 0 });
+      entity.setPosition({ x: 0, y: 100, z: 0 });
       setTimeout(() => entity.despawn(), 50); // Despawn after a short delay so we step the physics after translating it so leaving the sensor registers.
     });
 
@@ -254,8 +254,8 @@ function spawnBullet(world: World, coordinate: Vector3Like, direction: Vector3Li
     // Apply knockback, the knockback effect is less if the spider is larger, and more if it is smaller
     // because of how the physics simulation applies forces relative to automatically calculated mass from the spider's
     // size
-    const bulletDirection = bullet.getDirectionFromRotation();
-    const mass = otherEntity.getMass();
+    const bulletDirection = bullet.directionFromRotation;
+    const mass = otherEntity.mass;
     const knockback = 14 * mass;
 
     otherEntity.applyImpulse({
@@ -266,7 +266,7 @@ function spawnBullet(world: World, coordinate: Vector3Like, direction: Vector3Li
 
     if (enemyHealth[otherEntity.id!] <= 0) {
       // YEET the spider before despawning it so it registers leaving the sensor
-      otherEntity.setTranslation({ x: 0, y: 100, z: 0 });
+      otherEntity.setPosition({ x: 0, y: 100, z: 0 });
       setTimeout(() => { otherEntity.despawn(); }, 50); // Despawn after a short delay so we step the physics after translating it so leaving the sensor registers.
     }
 
@@ -293,7 +293,7 @@ function spawnPayloadEntity(world: World) {
   }
 
   payloadEntity = new Entity({
-    createCustomCharacterController: (entity: Entity) => new SimpleCharacterController(entity),
+    characterController: new SimpleCharacterController(),
     name: 'Payload',
     modelUri: 'models/payload.gltf',
     modelScale: 0.7,
@@ -350,7 +350,7 @@ function spawnSpider(world: World, coordinate: Vector3Like) {
   const targetPlayers = new Set<PlayerEntity>();
 
   const spider = new Entity({
-    createCustomCharacterController: (entity: Entity) => new SimpleCharacterController(entity),
+    characterController: new SimpleCharacterController(),
     name: 'Spider',
     modelUri: 'models/spider.gltf',
     modelLoopedAnimations: [ 'walk' ],
@@ -399,7 +399,7 @@ function spawnSpider(world: World, coordinate: Vector3Like) {
 
   spider.onEntityCollision = (spider: Entity, entity: Entity, started: boolean) => { // If the spider hits a player, deal damage and apply knockback
     if (started && entity instanceof PlayerEntity && entity.isSpawned) {
-      const spiderDirection = spider.getDirectionFromRotation();
+      const spiderDirection = spider.directionFromRotation;
       const knockback = 4 * randomScaleMultiplier;
 
       entity.applyImpulse({
@@ -466,19 +466,19 @@ function onTickPathfindEnemy(entity: Entity, targetPlayers: Set<PlayerEntity>, s
     const targetPlayer = targetPlayers.values().next().value as PlayerEntity | undefined;
 
     enemyPathfindingTargets[entityId] = targetPlayer?.isSpawned
-      ? targetPlayer.getTranslation()
-      : payloadEntity.getTranslation();
+      ? targetPlayer.position
+      : payloadEntity.position;
 
     enemyPathfindAccumulators[entityId] -= PATHFIND_ACCUMULATOR_THRESHOLD;
 
     // Make the spider jump if its close to the target player
-    const currentPosition = entity.getTranslation();
+    const currentPosition = entity.position;
     const dx = enemyPathfindingTargets[entityId].x - currentPosition.x;
     const dz = enemyPathfindingTargets[entityId].z - currentPosition.z;
     const distance = Math.sqrt(dx * dx + dz * dz);
     
     if (distance < 10) {
-      const mass = entity.getMass();
+      const mass = entity.mass;
       entity.applyImpulse({ x: 0, y: (10 * Math.random() + 5) * mass, z: 0 });
     }
 
@@ -495,13 +495,12 @@ function onTickPathfindEnemy(entity: Entity, targetPlayers: Set<PlayerEntity>, s
   enemyPathfindAccumulators[entityId]++;
 }
 
-function onTickWithPlayerInput(this: DefaultCharacterController, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, _deltaTimeMs: number) {
-  if (!this.entity.world) return;
+function onTickWithPlayerInput(this: DefaultCharacterController, entity: PlayerEntity, input: PlayerInput, cameraOrientation: PlayerCameraOrientation, _deltaTimeMs: number) {
+  if (!entity.world) return;
 
   if (input.ml) {
-    const world = this.entity.world;
-    const entity = this.entity;
-    const direction = Vector3.fromVector3Like(entity.getDirectionFromRotation());
+    const world = entity.world;
+    const direction = Vector3.fromVector3Like(entity.directionFromRotation);
 
     direction.y = Math.sin(cameraOrientation.pitch);
 
@@ -513,10 +512,10 @@ function onTickWithPlayerInput(this: DefaultCharacterController, input: PlayerIn
     // Normalize the direction vector to unit length
     direction.normalize();
 
-    this.entity.startModelOneshotAnimations([ 'shoot' ]);
+    entity.startModelOneshotAnimations([ 'shoot' ]);
 
     // Adjust bullet origin roughly for camera offset so crosshair is accurate
-    const bulletOrigin = entity.getTranslation();
+    const bulletOrigin = entity.position;
     bulletOrigin.y += 0.65;
 
     const bullet = spawnBullet(world, bulletOrigin, direction);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hytopia",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "The HYTOPIA SDK makes it easy for developers to create massively multiplayer games using JavaScript or TypeScript.",
   "main": "server.js",
   "bin": {