hytopia 0.1.18 → 0.1.20

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Create a bug report. Use this for unexpected behaviors that we can reproduce so we can fix them in the SDK. If we find your issue is not an SDK bug, we'll provide clarity on a fix for your code.
+title: <Concise title for this bug> [BUG]
+labels: bug
+assignees: iamarkdev
+
+---
+
+**What were you trying to do, what did you expect to happen?**
+Let us know what you were trying to do, and what you expected your code to do that it did not.
+
+**What actually happened?**
+What did your code actually do? Explain the bug/issue clearly.
+
+**To Reproduce**
+For SDK specific bugs, please provide the HYTOPIA SDK version you're using and a complete snippet of your code so we can reproduce this issue locally.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

package/README.md

@@ -1,14 +1,15 @@
 # HYTOPIA SDK
 
 ## Quick Links
-[Quickstart](#quickstart) • [API Reference](./docs/server.md) • [Report Bugs or Request Features](https://github.com/hytopiagg/sdk/issues)
+[Quickstart](#quickstart) • [API Reference](./docs/server.md) • [Examples](./examples) • [Join Our Developer Discord](https://discord.gg/hytopia-developers) • [Report Bugs or Request Features](https://github.com/hytopiagg/sdk/issues)
 
 ## What is HYTOPIA?
 
-![HYTOPIA Banner](./readme/assets/banner.png)
+![HYTOPIA Demo](./readme/assets/demo.gif)
+
 HYTOPIA is a modern games platform inspired by Minecraft, Roblox, and Rec Room.
 
-HYTOPIA allows you to create your own highly-sharable, immersive, massively multiplayer games in a voxel-like style. All playable in a web browser on any device!
+HYTOPIA allows you to create your own highly-sharable, immersive, massively multiplayer games in a voxel-like style by writing TypeScript or JavaScript. All playable in a web browser on any device!
 
 ## What is this SDK?
 
@@ -19,11 +20,11 @@ The HYTOPIA SDK makes it easy for developers to create multiplayer games on the
 Available as a simple NPM package, this SDK provides everything you need to get started:
 
 - Compiled HYTOPIA Server: The ready-to-use server software.
-- Game Client & Debugger: For rapidly testing and developing your games.
+- Game Client & Debugger: Accessible at https://play.hytopia.com
 - TypeScript Definitions: For strong typing and code completion.
-- Documentation: Detailed guides and references.
-- Default Assets: Textures, models and audio you can use in your games.
-- Game Examples: Sample projects & scripts showing how to build different types of games.
+- Documentation: Detailed guides and API reference.
+- Default Assets: Textures, models, audio and more you can use in your games.
+- Examples: Sample projects & scripts showing how to build different types of games.
 
 With these resources, you can quickly build and share immersive, voxel-style multiplayer games on HYTOPIA.
 
@@ -36,9 +37,13 @@ With these resources, you can quickly build and share immersive, voxel-style mul
 mkdir my-project-directory && cd my-project-directory
 ```
 
-3. Initialize a hytopia project. Sets up package.json and all dependencies, copies assets and an index.ts game script into your project.
+3. Initialize a hytopia project from boilerplate or an existing example. Sets up package.json and all dependencies, copies assets and an index.ts game script into your project.
 ```bash
+# Option 1: Initialize a boilerplate project
 bunx hytopia init
+
+# Option 2: Initialize a project from any of the examples in the examples directory like so:
+bunx hytopia init --template payload-game
 ```
 
 3. Start the server, use --watch for hot reloads as you make changes.
@@ -48,6 +53,8 @@ bun --watch index.ts
 
 4. Visit https://play.hytopia.com - when prompted, enter `localhost:8080` - this is the hostname of the local server you started in the previous step.
 
+**Note: If you'd prefer to use JavaScript instead of TypeScript, simply change the file extension of index.ts to index.js - Your editor will highlight the TypeScript syntax errors, simple delete the type annotations and everything should work the same without any TypeScript usage.**
+
 Once you're up and running, here's some other resources to go further:
 - [Game Examples](./examples)
 - [API Reference](./docs/server.md)

package/bin/scripts.js

@@ -43,7 +43,8 @@ const path = require('path');
       console.log('🔧 Initializing project');
       execSync('bun init --yes');
       execSync('bun add hytopia');
-
+      
+      const srcDir = path.join(__dirname, '..', 'boilerplate');
       fs.cpSync(srcDir, destDir, { recursive: true });  
     }
 

package/examples/README.md

@@ -0,0 +1,22 @@
+# HYTOPIA SDK Examples
+
+HYTOPIA SDK examples are a collection of HYTOPIA SDK projects that demonstrate full games or specific features using the SDK.
+
+In each folder, you'll find an index.ts file - this is the main entry point and where you'll find the code for each example.
+
+Here's an overview of the examples available:
+- [`payload-game`](./payload-game): A simple game where players must stay near a payload for it to move towards its destination while enemies spawn and swarm the players.
+- [`character-controller`](./character-controller): A simple example of how to implement your own character controller class.
+- [`entity-spawn`](./entity-spawn): A simple example of how to spawn an entity and set some of its properties.
+
+## Use Examples As Templates For Your Projects
+
+If you want to init a new HYTOPIA project based on an example in this directory, you can use the `hytopia init` command with the `--template` flag. 
+
+For example, to create a new project based on the `payload-game` example, you can run:
+
+```bash
+bunx hytopia init --template payload-game
+```
+
+The value passed to the `--template` flag should be the name of the folder in the examples directory.

package/examples/payload-game/index.ts

@@ -1,3 +1,21 @@
+/**
+ * payload-game is a simple game that encompasses a number of core HYTOPIA SDK systems.
+ * This example utilizes entities, spawning, rigid body, colliders and sensors, 
+ * collision groups, audio, character controller hooks, and more.
+ * 
+ * This example is a quick and dirty implementation of an overwatch style push the payload
+ * in a multiplayer PvE style. Players start the game around the payload and must stay near it
+ * for it to move towards the next waypoint. Enemies spawn near the next arget waypoint of 
+ * the payload and swarm towards the players. Players can left click to shoot spiders with
+ * bullets.
+ * 
+ * This example is not meant to be a polished game, but rather a demonstration of how to use
+ * the SDK to build your own games. 
+ * 
+ * In a polished implementation, we'd be using multiple files and not just index.ts to
+ * break out and properly organize game behavior and mechanics.
+ */
+
 import {
   Audio,
   BlockType,
@@ -5,7 +23,6 @@ import {
   CollisionGroup,
   DefaultCharacterController,
   Entity,
-  EventRouter,
   GameServer,
   PlayerEntity,
   RigidBodyType,
@@ -20,7 +37,7 @@ import type {
   Vector3,
 } from 'hytopia';
 
-import worldJson from './assets/map.json';
+import map from './assets/map.json';
 
 // Constants
 const BULLET_SPEED = 50;
@@ -57,35 +74,32 @@ const PAYLOAD_WAYPOINT_ENEMY_SPAWNS = [
   ],
 ];
 
-// Globals, yuck
-const enemyHealth: Record<number, number> = {};
-const enemyPathfindAccumulators: Record<number, number> = {};
-const enemyPathfindingTargets: Record<number, Vector3> = {};
-const playerEntityHealth: Record<number, number> = {};
-let started = false;
-let payloadEntity: Entity | null = null;
-let payloadPlayerEntityCount = 0;
-let playerCount = 0;
-let targetWaypointCoordinateIndex = 0;
-
-// Configure Global Event Router
-EventRouter.serverInstance.logIgnoreEvents = [ 'CONNECTION.PACKET_SENT' ];
-EventRouter.serverInstance.logIgnoreEventPrefixes = [ 'CONNECTION.PACKET_SENT:' ];
-EventRouter.serverInstance.logAllEvents = false;
+// Simple game state tracking via globals.
+const enemyHealth: Record<number, number> = {}; // Entity id -> health
+const enemyPathfindAccumulators: Record<number, number> = {}; // Entity id -> accumulator, so we don't pathfind each tick
+const enemyPathfindingTargets: Record<number, Vector3> = {}; // Entity id -> target coordinate
+const playerEntityHealth: Record<number, number> = {}; // Player entity id -> health
+let started = false; // Game started flag
+let payloadEntity: Entity | null = null; // Payload entity
+let payloadPlayerEntityCount = 0; // Number of player entities within the payload sensor, minus number of enemies
+let playerCount = 0; // Number of players in the game
+let targetWaypointCoordinateIndex = 0; // Current waypoint coordinate index for the payload
 
 // Run
-void startServer(world => {
+startServer(world => { // Perform our game setup logic in the startServer init callback here.
   const chatManager = world.chatManager;
 
-  // Enable local ssl
+  // Enable local ssl, so we can connect to https://localhost:8080 from play.hytopia.com for testing
+  // If using NGROK or a reverse proxy that handles SSL, you need to comment this out to be able to
+  // connect to the server from the client using the reverse proxy URL.
   GameServer.instance.webServer.enableLocalSSL();
 
   // Load Map
-  world.loadMap(worldJson);
+  world.loadMap(map);
 
   // Setup Player Join & Spawn Controlled Entity
   world.onPlayerJoin = player => {
-    const playerEntity = new PlayerEntity({
+    const playerEntity = new PlayerEntity({ // Create an entity our newly joined player controls
       player,
       name: 'Player',
       modelUri: 'models/player-with-gun.gltf',
@@ -93,21 +107,30 @@ void startServer(world => {
       modelScale: 0.5,
     });
 
+    // Spawn the player entity at a random coordinate
     const randomSpawnCoordinate = PLAYER_SPAWN_COORDINATES[Math.floor(Math.random() * PLAYER_SPAWN_COORDINATES.length)];
     playerEntity.spawn(world, randomSpawnCoordinate);
 
+    // We need to do some custom logic for player inputs, so let's assign custom onTick handler to the default player controller.
     playerEntity.characterController!.onTickPlayerMovement = onTickPlayerMovement;
 
+    // Set custom collision groups for the player entity, this is so we can reference the PLAYER collision group
+    // specifically in enemy collision sensors.
     playerEntity.setCollisionGroupsForSolidColliders({
       belongsTo: [ CollisionGroup.ENTITY, CollisionGroup.PLAYER ],
       collidesWith: [ CollisionGroup.ALL ],
     });
 
+    // Initialize player health
     playerEntityHealth[playerEntity.id!] = 20;
+
+    // Increment player count
     playerCount++;
 
+    // Send a message to all players informing them that a new player has joined
     chatManager.sendBroadcastMessage(`Player ${player.username} has joined the game!`, 'FFFFFF');
 
+    // If the game hasn't started yet, send a message to all players to start the game
     if (!started) {
       chatManager.sendBroadcastMessage('Enter command /start to start the game!', 'FFFFFF');
     }
@@ -115,9 +138,13 @@ void startServer(world => {
 
   // Setup Player Leave & Despawn Controlled Entity
   world.onPlayerLeave = player => {
+    // Despawn all player entities for the player that left
+    // We apply a translation prior to despawn because of a bug in the RAPIER
+    // 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 });
-      setTimeout(() => entity.despawn(), 50);
+      setTimeout(() => entity.despawn(), 50); // Despawn after a short delay so we step the physics after translating it so leaving the sensor registers.
     });
 
     playerCount--;
@@ -128,7 +155,6 @@ void startServer(world => {
   // Spawn Payload
   spawnPayloadEntity(world);
 
-
   // Start spawning enemies
   startEnemySpawnLoop(world);
 
@@ -143,7 +169,7 @@ void startServer(world => {
     started = false;
   });
 
-  // Start Ambient Music
+  // Start ambient music for all players
   (new Audio({
     uri: 'audio/music/game.mp3',
     loop: true,
@@ -155,7 +181,7 @@ void startServer(world => {
 function startEnemySpawnLoop(world: World) {
   let spawnInterval;
 
-  const spawn = () => {
+  const spawn = () => { // Simple spawn loop that spawns enemies relative to the payload's current waypoint
     const possibleSpawnCoordinate = PAYLOAD_WAYPOINT_ENEMY_SPAWNS[targetWaypointCoordinateIndex];
     
     if (!possibleSpawnCoordinate) {
@@ -177,18 +203,19 @@ function startEnemySpawnLoop(world: World) {
 }
 
 function spawnBullet(world: World, coordinate: Vector3, direction: Vector3) {
+  // Spawn a bullet when the player shoots.
   const bullet = new Entity({
     name: 'Bullet',
     modelUri: 'models/bullet.gltf',
     modelScale: 0.3,
     rigidBodyOptions: {
-      type: RigidBodyType.KINEMATIC_VELOCITY,
+      type: RigidBodyType.KINEMATIC_VELOCITY, // Kinematic means entity's rigid body will not be affected by physics. KINEMATIC_VELOCITY means the entity is moved by setting velocity.
       linearVelocity: {
         x: direction.x * BULLET_SPEED,
         y: direction.y * BULLET_SPEED,
         z: direction.z * BULLET_SPEED,
       },
-      rotation: getRotationFromDirection(direction),
+      rotation: getRotationFromDirection(direction), // Get the rotation from the direction vector so it's facing the right way we shot it
       colliders: [
         {
           shape: ColliderShape.BALL,
@@ -203,19 +230,22 @@ function spawnBullet(world: World, coordinate: Vector3, direction: Vector3) {
     },
   });
 
-  bullet.onBlockCollision = (block: BlockType, started: boolean) => {
+  bullet.onBlockCollision = (block: BlockType, started: boolean) => { // If the bullet hits a block, despawn it
     if (started) {
       bullet.despawn();
     }
   };
 
-  bullet.onEntityCollision = (entity: Entity, started: boolean) => {
-    if (!started || ![ 'Spider', 'Zombie' ].includes(entity.name)) {
+  bullet.onEntityCollision = (entity: Entity, started: boolean) => { // If the bullet hits an enemy, deal damage if it is a Spider
+    if (!started || entity.name !== 'Spider') {
       return;
     }
     
     enemyHealth[entity.id!]--;
 
+    // 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 = entity.getMass();
     const knockback = 14 * mass;
@@ -227,9 +257,9 @@ function spawnBullet(world: World, coordinate: Vector3, direction: Vector3) {
     });
 
     if (enemyHealth[entity.id!] <= 0) {
-      // have to YEET the spider to register it leaving the sensor
+      // YEET the spider before despawning it so it registers leaving the sensor
       entity.setTranslation({ x: 0, y: 100, z: 0 });
-      setTimeout(() => { entity.despawn(); }, 50);
+      setTimeout(() => { entity.despawn(); }, 50); // Despawn after a short delay so we step the physics after translating it so leaving the sensor registers.
     }
 
     bullet.despawn();
@@ -237,6 +267,7 @@ function spawnBullet(world: World, coordinate: Vector3, direction: Vector3) {
 
   bullet.spawn(world, coordinate);
 
+  // Play a bullet noise that follows the bullet spatially
   (new Audio({
     uri: 'audio/sfx/shoot.mp3',
     playbackRate: 2,
@@ -263,21 +294,23 @@ function spawnPayloadEntity(world: World) {
       colliders: [
         {
           shape: ColliderShape.BLOCK,
-          halfExtents: { x: 0.9, y: 1.6, z: 2.5 },
+          halfExtents: { x: 0.9, y: 1.6, z: 2.5 }, // Note: We manually set the collider size, the SDK currently does not support automatic sizing of colliders to a model.
           collisionGroups: {
             belongsTo: [ CollisionGroup.ALL ],
             collidesWith: [ CollisionGroup.ENTITY, CollisionGroup.ENTITY_SENSOR, CollisionGroup.PLAYER ],
           },
         },
         {
-          shape: ColliderShape.BLOCK,
+          shape: ColliderShape.BLOCK, // Create a proximity sensor for movement when players are near.
           halfExtents: { x: 3.75, y: 2, z: 6 },
           isSensor: true,
           collisionGroups: {
             belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
             collidesWith: [ CollisionGroup.PLAYER, CollisionGroup.ENTITY ],
           },
-          onCollision: (other: BlockType | Entity, started: boolean) => {
+          // We use a onCollision handler specific to this sensor, and 
+          // not the whole entity, so we can track the number of players in the payload sensor.
+          onCollision: (other: BlockType | Entity, started: boolean) => { 
             if (other instanceof PlayerEntity) {
               started ? payloadPlayerEntityCount++ : payloadPlayerEntityCount--;
             } else if (other instanceof Entity) {
@@ -289,22 +322,23 @@ function spawnPayloadEntity(world: World) {
     },
   });
 
-  payloadEntity.onTick = onTickPathfindPayload;
-  payloadEntity.spawn(world, PAYLOAD_SPAWN_COORDINATE);
+  payloadEntity.onTick = onTickPathfindPayload; // Use our own basic pathfinding function each tick of the game for the payload.
+  payloadEntity.spawn(world, PAYLOAD_SPAWN_COORDINATE); // Spawn the payload at the designated spawn coordinate
 
-  (new Audio({
+  (new Audio({ // Play a looped idle sound that follows the payload spatially
     uri: 'audio/sfx/payload-idle.mp3',
     loop: true,
     attachedToEntity: payloadEntity,
     volume: 0.25,
-    referenceDistance: 5,
+    referenceDistance: 5, // Reference distance affects how loud the audio is relative to a player's proximity to the entity
   })).play(world);
 } 
 
 function spawnSpider(world: World, coordinate: Vector3) {
   const baseScale = 0.5;
   const baseSpeed = 3;
-  const randomScaleMultiplier = Math.random() * 2 + 1; // Random value between 1 and 3
+  const randomScaleMultiplier = Math.random() * 2 + 1; // Random value between 1 and 3 // Random scale multiplier to make each spider a different size
+  const targetPlayers = new Set<PlayerEntity>();
 
   const spider = new Entity({
     name: 'Spider',
@@ -320,7 +354,7 @@ function spawnSpider(world: World, coordinate: Vector3) {
           borderRadius: 0.1 * randomScaleMultiplier,
           halfHeight: 0.225 * randomScaleMultiplier,
           radius: 0.5 * randomScaleMultiplier,
-          tag: 'body',
+          tag: 'body', // Note we use tags here, they don't really serve a purpose in this example other than showing that they can be used.
           collisionGroups: {
             belongsTo: [ CollisionGroup.ENTITY ],
             collidesWith: [ CollisionGroup.BLOCK, CollisionGroup.ENTITY_SENSOR, CollisionGroup.PLAYER ],
@@ -336,7 +370,7 @@ function spawnSpider(world: World, coordinate: Vector3) {
             belongsTo: [ CollisionGroup.ENTITY_SENSOR ],
             collidesWith: [ CollisionGroup.PLAYER ],
           },
-          onCollision: (other: BlockType | Entity, started: boolean) => {
+          onCollision: (other: BlockType | Entity, started: boolean) => { // If a player enters or exits the aggro sensor, add or remove them from the target players set
             if (other instanceof PlayerEntity) {
               started ? targetPlayers.add(other) : targetPlayers.delete(other);
             }
@@ -346,16 +380,14 @@ function spawnSpider(world: World, coordinate: Vector3) {
     },
   });
 
-  const targetPlayers = new Set<PlayerEntity>();
-
-  spider.onTick = (tickDeltaMs: number) => onTickPathfindEnemy(
+  spider.onTick = (tickDeltaMs: number) => onTickPathfindEnemy( // Use our own basic pathfinding function each tick of the game for the enemy
     spider,
     targetPlayers,
     baseSpeed * randomScaleMultiplier,
     tickDeltaMs,
   );
 
-  spider.onEntityCollision = (entity: Entity, started: boolean) => {
+  spider.onEntityCollision = (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 knockback = 4 * randomScaleMultiplier;
@@ -379,15 +411,16 @@ function spawnSpider(world: World, coordinate: Vector3) {
 
   spider.spawn(world, coordinate);
 
+  // Give the spider a health value relative to its size, bigger = more health
   enemyHealth[spider.id!] = 2 * Math.round(randomScaleMultiplier);
 }
 
-function onTickPathfindPayload(this: Entity, tickDeltaMs: number) {
-  const speed = started
+function onTickPathfindPayload(this: Entity, tickDeltaMs: number) { // Movement logic for the payload
+  const speed = started // Set the payload speed relative to the number of players in the payload sensor
     ? Math.max(Math.min(PAYLOAD_PER_PLAYER_SPEED * payloadPlayerEntityCount, PAYLOAD_MAX_SPEED), 0)
     : 0;
 
-  if (!speed) {
+  if (!speed) { // Play animations based on if its moving or not
     this.stopModelAnimations(Array.from(this.modelLoopedAnimations).filter(v => v !== 'idle'));
     this.startModelLoopedAnimations([ 'idle' ]);
   } else {
@@ -395,7 +428,7 @@ function onTickPathfindPayload(this: Entity, tickDeltaMs: number) {
     this.startModelLoopedAnimations([ 'walk' ]);
   }
 
-  // Calculate direction to target
+  // Calculate direction to target waypoint
   const targetWaypointCoordinate = PAYLOAD_WAYPOINT_COORDINATES[targetWaypointCoordinateIndex];
   const currentPosition = this.getTranslation();
   const deltaX = targetWaypointCoordinate.x - currentPosition.x;
@@ -406,7 +439,7 @@ function onTickPathfindPayload(this: Entity, tickDeltaMs: number) {
     z: Math.abs(deltaZ) > 0.1 ? Math.sign(deltaZ) : 0,
   };
 
-  // Apply rotation to face direction if necessary
+  // Apply rotation to face direction if necessary based on the current target waypoint
   const rotation = this.getRotation();
   const currentAngle = 2 * Math.atan2(rotation.y, rotation.w);
   const targetAngle = Math.atan2(direction.x, direction.z) + Math.PI; // Add PI to face forward
@@ -452,7 +485,7 @@ function onTickPathfindEnemy(entity: Entity, targetPlayers: Set<PlayerEntity>, s
   if (!entity.isSpawned || !payloadEntity) return;
   
   const entityId = entity.id!;
-  enemyPathfindAccumulators[entityId] ??= 0;
+  enemyPathfindAccumulators[entityId] ??= 0; // Initialize the accumulator for this enemy if it isn't initialized yet
 
   // Handle pathfinding
   if (!enemyPathfindingTargets[entityId] || enemyPathfindAccumulators[entityId] >= PATHFIND_ACCUMULATOR_THRESHOLD) {
@@ -542,7 +575,7 @@ function damagePlayer(playerEntity: PlayerEntity) {
   );
 
   if (playerEntityHealth[playerEntity.id!] <= 0) {
-    chatManager.sendPlayerMessage(
+    chatManager.sendPlayerMessage( // Alert the player they've been damaged, since we don't have UI support yet, we just use chat
       playerEntity.player,
       'You have died!',
       'FF0000',

package/package.json

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