hytopia 0.1.15 → 0.1.17

package/bin/scripts.js

@@ -6,6 +6,14 @@ const path = require('path');
 
 (async () => {
   const command = process.argv[2];
+  const flags = {};
+  for (let i = 3; i < process.argv.length; i += 2) {
+    if (i % 2 === 1) { // Odd indices are flags
+      const flag = process.argv[i].replace('--', '');
+      const value = process.argv[i + 1];
+      flags[flag] = value;
+    }
+  }
 
   /**
    * Init command
@@ -17,16 +25,27 @@ const path = require('path');
    * `bunx hytopia init my-project-name`
    */
   if (command === 'init') {
-    const srcDir = path.join(__dirname, '..', 'boilerplate');
     const destDir = process.cwd();
- 
-    // Initialize project
-    execSync('bun init --yes');
-    execSync('bun add hytopia');
-
-    // Copy boilerplate
-    console.log(`🖨️ Copying boilerplate to ${destDir}`);
-    fs.cpSync(srcDir, destDir, { recursive: true });
+
+    if (flags.template) {
+      console.log(`🔧 Initializing project with examples template ${flags.template}`);
+
+      const templateDir = path.join(__dirname, '..', 'examples', flags.template);
+
+      if (!fs.existsSync(templateDir)) {
+        console.error(`Examples template ${flags.template} does not exist in the examples directory, could not initialize project!`);
+        return;
+      }
+
+      fs.cpSync(templateDir, destDir, { recursive: true });
+      execSync('bun install');
+    } else {
+      console.log('🔧 Initializing project');
+      execSync('bun init --yes');
+      execSync('bun add hytopia');
+
+      fs.cpSync(srcDir, destDir, { recursive: true });  
+    }
 
     // Done, lfg!
     console.log('🚀 Hytopia project initialized successfully!');

package/docs/server.hytopia.md

@@ -741,7 +741,7 @@ The default rigid body options when EntityOptions.rigidBodyOptions is not provid
 
 </td><td>
 
-The port the server will listen on. You can override this in your .env by setting PORT.
+The port the server will run on. You can override this in your .env by setting PORT. When deployed in production to HYTOPIA servers, any .env value will be ignored and 8080 will be used.
 
 
 </td></tr>

package/docs/server.hytopia.port.md

@@ -4,10 +4,10 @@
 
 ## HYTOPIA.PORT variable
 
-The port the server will listen on. You can override this in your .env by setting PORT.
+The port the server will run on. You can override this in your .env by setting PORT. When deployed in production to HYTOPIA servers, any .env value will be ignored and 8080 will be used.
 
 **Signature:**
 
 ```typescript
-PORT: string | number
+PORT: string | 8080
 ```

package/docs/server.hytopia.supported_input_keys.md

@@ -9,5 +9,5 @@ The input keys included in the PlayerInputState.
 **Signature:**
 
 ```typescript
-SUPPORTED_INPUT_KEYS: string[]
+SUPPORTED_INPUT_KEYS: readonly ["w", "a", "s", "d", "sp", "sh", "tb", "ml", "mr", "q", "e", "r", "f", "z", "x", "c", "v", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0"]
 ```

package/docs/server.md

@@ -750,7 +750,7 @@ The default rigid body options when EntityOptions.rigidBodyOptions is not provid
 
 </td><td>
 
-The port the server will listen on. You can override this in your .env by setting PORT.
+The port the server will run on. You can override this in your .env by setting PORT. When deployed in production to HYTOPIA servers, any .env value will be ignored and 8080 will be used.
 
 
 </td></tr>

package/docs/server.port.md

@@ -4,10 +4,10 @@
 
 ## PORT variable
 
-The port the server will listen on. You can override this in your .env by setting PORT.
+The port the server will run on. You can override this in your .env by setting PORT. When deployed in production to HYTOPIA servers, any .env value will be ignored and 8080 will be used.
 
 **Signature:**
 
 ```typescript
-PORT: string | number
+PORT: string | 8080
 ```

package/docs/server.supported_input_keys.md

@@ -9,5 +9,5 @@ The input keys included in the PlayerInputState.
 **Signature:**
 
 ```typescript
-SUPPORTED_INPUT_KEYS: string[]
+SUPPORTED_INPUT_KEYS: readonly ["w", "a", "s", "d", "sp", "sh", "tb", "ml", "mr", "q", "e", "r", "f", "z", "x", "c", "v", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0"]
 ```

package/examples/character-controller/MyCharacterController.ts

@@ -0,0 +1,230 @@
+import {
+  Audio,
+  BaseCharacterController,
+  CollisionGroup,
+  Collider,
+  Entity,
+  ColliderShape,
+  BlockType,
+} from 'hytopia';
+
+import type {
+  PlayerInputState,
+  PlayerOrientationState,
+  Vector3,
+} from 'hytopia';
+
+export default class MyCharacterController extends BaseCharacterController {
+  public jumpVelocity: number = 10;
+  public runVelocity: number = 8;
+  public walkVelocity: number = 4;
+
+  private _stepAudio: Audio;
+  private _groundContactCount: number = 0;
+  private _platform: Entity | undefined;
+
+  public constructor(entity: Entity) {
+    super(entity);
+
+    // 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,
+    });
+
+    this.entity.lockAllRotations(); // prevent physics from applying rotation to the entity.
+  }
+
+  /** Whether the entity is grounded. */
+  public get isGrounded(): boolean { return this._groundContactCount > 0; }
+
+  /** Whether the entity is on a platform, a platform is any entity with a kinematic rigid body. */
+  public get isOnPlatform(): boolean { return !!this._platform; }
+
+  /** The platform the entity is on, if any. */
+  public get platform(): Entity | undefined { return this._platform; }
+
+  /**
+   * Create the sensor colliders for the character controller.
+   */
+  public createSensorColliders(): Collider[] {
+    if (!this.entity.isSpawned) {
+      throw new Error('CharacterController.createSensorColliders(): Entity is not spawned!');
+    }
+
+    const sensorColliders: Collider[] = [];
+
+    /**
+     * 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.
+     */
+    sensorColliders.push(new Collider({
+      shape: ColliderShape.CYLINDER,
+      radius: 0.30,
+      halfHeight: 0.125,
+      collisionGroups: {
+        belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
+        collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY ],
+      },
+      isSensor: true,
+      relativeTranslation: { 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' ]);
+        } else {
+          this.entity.stopModelAnimations([ 'jump_loop' ]);
+        }
+
+        // Platform contact
+        if (!(_other instanceof Entity) || !_other.isKinematic) return;
+        
+        if (started) {
+          this._platform = _other;
+        } else if (_other === this._platform && !started) {
+          this._platform = undefined;
+        }
+      },
+    }));
+
+    return sensorColliders;
+  }
+
+  /**
+   * Handles movement of the entity based on player's input
+   * each tick. tickPlayerMovement is called internally if the entity
+   * is of the PlayerEntity class.
+   */
+  public tickPlayerMovement(inputState: PlayerInputState, orientationState: PlayerOrientationState, deltaTimeMs: number) {
+    if (!this.entity.isSpawned || !this.entity.world) return; // type guard.
+
+    super.tickPlayerMovement(inputState, orientationState, deltaTimeMs);
+
+    const { w, a, s, d, sp, sh, ml, mr } = inputState; // See PlayerInputState type for all possible inputs.
+    const { yaw } = orientationState; // Camera/perspectie orientation of player.
+    const currentVelocity = this.entity.getLinearVelocity();
+    const targetVelocities = { x: 0, y: 0, z: 0 };
+    const isRunning = sh;
+
+    // Handle movement animations if relevant.
+    if (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);
+      } else {
+        this.entity.stopModelAnimations(Array.from(this.entity.modelLoopedAnimations).filter(v => v !== 'walk'));
+        this.entity.startModelLoopedAnimations([ 'walk' ]);
+        this._stepAudio.setPlaybackRate(0.5);
+      }
+
+      this._stepAudio.play(this.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' ]);
+    }
+
+    // Play a simple interact animation on left mouse click then clear the input.
+    if (ml) {
+      this.entity.startModelOneshotAnimations([ 'simple_interact' ]);
+      inputState['ml'] = false;
+    }
+
+    // Rocket the player up on mouse right click.
+    if (mr) {
+      targetVelocities.y = 20;
+      inputState['mr'] = false;
+    }
+
+    // Calculate target horizontal velocities (run/walk)
+    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);
+    }
+
+    // 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) {
+        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 deltaVelocities = {
+      x: targetVelocities.x - currentVelocity.x + platformVelocity.x,
+      y: targetVelocities.y + platformVelocity.y,
+      z: targetVelocities.z - currentVelocity.z + platformVelocity.z,
+    };
+
+    const hasExternalVelocity = 
+      Math.abs(currentVelocity.x) > this.runVelocity ||
+      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 (Object.values(deltaVelocities).some(v => v !== 0)) {
+        const mass = this.entity.getMass();
+
+        this.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,
+        });
+      }
+    }
+
+    // Apply rotation relative to camera orientation.
+    if (yaw !== undefined) {
+      const halfYaw = yaw / 2;
+      
+      this.entity.setRotation({
+        x: 0,
+        y: Math.fround(Math.sin(halfYaw)),
+        z: 0,
+        w: Math.fround(Math.cos(halfYaw)),
+      });
+    }
+  }
+
+  public tickPathfindingMovement(_destination: Vector3, _deltaTimeMs: number) {
+    console.log('Non-player pathfinding not implemented!');
+  }
+}

package/examples/character-controller/README.md

@@ -0,0 +1,15 @@
+# character-controller
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.1.26. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/examples/character-controller/assets/certs/README.md

@@ -0,0 +1,11 @@
+For local development self-signed certs are stored here.
+The server when GameServer.instance.webServer.enableLocalSSL();
+is used, will look for assets/certs/localhost.key and
+assets/certs/localhost.cert and use those for SSL.
+
+We use these self-signed certs to allow https://localhost
+& wss://localhost support. Without this, play.hytopia.com
+requires a bunch of funky browser flag workarounds in
+order to connect to your local server. This is only used
+for local development and will be ignored when your game
+is deployed to HYTOPIA servers.

package/examples/character-controller/assets/certs/localhost.crt

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDRjCCAi6gAwIBAgIFOTEzNTIwDQYJKoZIhvcNAQELBQAwWDEQMA4GA1UEAxMH
+SFlUT1BJQTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNV
+BAcTB1NlYXR0bGUxEDAOBgNVBAoTB0hZVE9QSUEwHhcNMjQxMTEzMjIyMjEwWhcN
+MzQxMTExMjIyMjEwWjAUMRIwEAYDVQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3
+DQEBAQUAA4IBDwAwggEKAoIBAQCo2i9L13+4KxvR9dxBeE3Xrj5WtoGFBwbUZkeV
+3B8n+ehJ2LWD13sGvCuHvSDovbSOxLxqbESQzWBRVrmfJMR1qe+o7kd/SMaLHosC
+2BWASn1oV9rGLktvd2Xs6xRf75cejzrr/OrNoTpICp3j1Z0Kd+73TuYyVFPfCbqH
+N6mwS+yCmG2/w3sXwbOGymNuYpaPoD8XVcIhO7GPZsCVqqSKP2xsGF+oP5+Isma+
+y3usNUnFnVW5ckk6SWWdxP9kuOW2xXoFFwj43STaE4OvXbTPCG7jowUpDH1aMvFA
+ceXUfuaE7H8QfZqoUNu8jCb8LiqTL+uL5kHbl2kQ7sQCN9gjAgMBAAGjWzBZMAwG
+A1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgWgMB0GA1UdJQQWMBQGCCsGAQUFBwMB
+BggrBgEFBQcDAjAaBgNVHREEEzARgglsb2NhbGhvc3SHBH8AAAEwDQYJKoZIhvcN
+AQELBQADggEBAHSINJsVuu11kmzx7/2yEiDSIQVzdzk/+hnx0iQt6rDy9ZNVdI8w
+JOUYaPjxDFfZ5gaPqrlb0n248lBMdGrp6xmhbgXL8eWkXRDcR6kuYBQrQmFitg7G
+KFFWnzCuQMLn5Mn6VA+sBf9n2LVaOQCci9jU0awRpaQTUNf894USjILo+PvbcUGU
+XlMtqc1abkN4NehDdaXsxMwyPgUCPkN5X80s8hxx5NgzwtwDtoTYj/PBRBXBddA+
+oN1rwkugWiTpIPU0wKb0ufLsq96I24UDQWd2jJGbD2W23Z0lwVz/Bq6uc4aOJn68
+JbejJgFyF3/m6oFDxgqMnuV5q5olVZHAWL8=
+-----END CERTIFICATE-----

package/examples/character-controller/assets/certs/localhost.key

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEowIBAAKCAQEAqNovS9d/uCsb0fXcQXhN164+VraBhQcG1GZHldwfJ/noSdi1
+g9d7Brwrh70g6L20jsS8amxEkM1gUVa5nyTEdanvqO5Hf0jGix6LAtgVgEp9aFfa
+xi5Lb3dl7OsUX++XHo866/zqzaE6SAqd49WdCnfu907mMlRT3wm6hzepsEvsgpht
+v8N7F8GzhspjbmKWj6A/F1XCITuxj2bAlaqkij9sbBhfqD+fiLJmvst7rDVJxZ1V
+uXJJOkllncT/ZLjltsV6BRcI+N0k2hODr120zwhu46MFKQx9WjLxQHHl1H7mhOx/
+EH2aqFDbvIwm/C4qky/ri+ZB25dpEO7EAjfYIwIDAQABAoIBAA6dvGRbRiICEUlu
+d99u84YM/jZxW+rQ/eVa6S1uvX+vYU0rJiNAftTJaxc35uZerYeCPjEUKCdEr+a6
+lBzTiPIKgMVlwuiguxcF0NCxNcNCL3Ld0AFBtqPyeO82NjBLxBAQI/CTlxuvriTY
+TmyPbCWg1h2wRbrrk8sFw5C638Rz2evbBfsUcTICr6QQa51YXgxawtew3Xy3aR3G
+PPuS7zlvjJYDApQs3+nakEj3DnM2nz5oJNS2YEsMKQRhmNrhen6Ose5G0jf6F6up
+8HVpN3XW01D7qVT1Og6Y5dE2EM/l3isKZWXif6CcFKoOy87z8HRMIoZJS62WtKtu
+liBmYxkCgYEA4VDPtFAGnChCTGLVwo7MKmH6/KU5Qj2fuufGNw8jcW3H0Ea52OFC
+qOGA9pRJVXCap7Wa7XCJXENLYWpSfB7H7GnhFLwHw7jAVB52DLDCdUnRv5fP3o8K
+xEseMJQaJm95eFVfTETcnjDixWtIzNbXULQbGjF3AY74aFjc1fhc/yUCgYEAv9jj
+Zrc+UzR0oi00Ip8O5C5Uvu2W35M+j2XoV/xPkX+Hcr12U40Gnc/rnzVp2lGTwNZS
+ImQcjLEd31qLOy90F9lcaKvOfgcx0JvGEp5SdzQQaS3RJqn0xWLh1O4NMsiVbLNi
+Zi5qFv7pW/DO174xSa7cMVE8qp8YHAOZdpcqm6cCgYB9FL2ZnetteTQE78E3NsrE
+pIwPATIeQdOQkOaK3k6Qw57vUrQNYE//LODJAl0Ln21buQd+1MCMhZctRzbvTK8z
+4TtgpVmyH7g1eouSU/Y/4nEcaYyuQr55ZjImSbGSsMPAN7SlxHytHPpnGj3Z6VKy
+rKl3CwrDxLjGRL6j0jLeOQKBgBiu3xMoIGy0Iw16o2qQ7GmPTHgEOZUqbLImem5X
+mCUwM00f80lsq51CUx540NW2CTyWVpr2JnYzk5RZIfDLejRXUvxknny4kEA2ypU6
+qYGMwU/HBVHkLAn5XvT2a9xM0mzZ558d+ahbw8qAgRxg7BZ+2PW/bf7F2WRBUk1f
+xauhAoGBALEspoxQozwohGQnP7EMF0/0JoKNpdNv0b0qCVvNiMo0+N297lI2mFQp
+6xYlW/1l9afLokklF/J2IsyBrTCZoY7SaEk/lMMrQSyra+y0z71ogZ8A4ny9fxsj
+0dDYJZGllL+3E/MQfd7k+KnOM/+A+cPoAnci76+L3vdkUb2P8SJk
+-----END RSA PRIVATE KEY-----