hytopia 0.1.46 → 0.1.48

package/docs/server.player.md

@@ -124,6 +124,27 @@ Readonly&lt;[PlayerOrientationState](./server.playerorientationstate.md)<!-- -->
 The current [PlayerOrientationState](./server.playerorientationstate.md) of the player.
 
 
+</td></tr>
+<tr><td>
+
+[ui](./server.player.ui.md)
+
+
+</td><td>
+
+`readonly`
+
+
+</td><td>
+
+PlayerUI
+
+
+</td><td>
+
+The UI for the player.
+
+
 </td></tr>
 <tr><td>
 

package/docs/server.player.ui.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; [Player](./server.player.md) &gt; [ui](./server.player.ui.md)
+
+## Player.ui property
+
+The UI for the player.
+
+**Signature:**
+
+```typescript
+readonly ui: PlayerUI;
+```

package/docs/server.simulation.enabledebugraycasting.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; [Simulation](./server.simulation.md) &gt; [enableDebugRaycasting](./server.simulation.enabledebugraycasting.md)
+
+## Simulation.enableDebugRaycasting() method
+
+Enables or disables debug raycasting for the simulation. This will render lines for the raycast that disappear after a few seconds.
+
+**Signature:**
+
+```typescript
+enableDebugRaycasting(enabled: boolean): void;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+enabled
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+Whether to enable debug raycasting.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+void
+

package/docs/server.simulation.enabledebugrendering.md

@@ -4,7 +4,7 @@
 
 ## Simulation.enableDebugRendering() method
 
-Enables or disables debug rendering for the simulation. When enabled, all colliders, rigid body and raycast outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.
+Enables or disables debug rendering for the simulation. When enabled, all colliders and rigid body outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.
 
 **Signature:**
 

package/docs/server.simulation.isdebugraycastingenabled.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; [Simulation](./server.simulation.md) &gt; [isDebugRaycastingEnabled](./server.simulation.isdebugraycastingenabled.md)
+
+## Simulation.isDebugRaycastingEnabled property
+
+Whether the simulation has debug raycasting enabled
+
+**Signature:**
+
+```typescript
+get isDebugRaycastingEnabled(): boolean;
+```

package/docs/server.simulation.md

@@ -61,6 +61,27 @@ RAPIER.Vector3
 The gravity vector for the simulation.
 
 
+</td></tr>
+<tr><td>
+
+[isDebugRaycastingEnabled](./server.simulation.isdebugraycastingenabled.md)
+
+
+</td><td>
+
+`readonly`
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+Whether the simulation has debug raycasting enabled
+
+
 </td></tr>
 <tr><td>
 
@@ -158,6 +179,20 @@ Description
 Casts a ray through the simulation.
 
 
+</td></tr>
+<tr><td>
+
+[enableDebugRaycasting(enabled)](./server.simulation.enabledebugraycasting.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Enables or disables debug raycasting for the simulation. This will render lines for the raycast that disappear after a few seconds.
+
+
 </td></tr>
 <tr><td>
 
@@ -169,7 +204,7 @@ Casts a ray through the simulation.
 
 </td><td>
 
-Enables or disables debug rendering for the simulation. When enabled, all colliders, rigid body and raycast outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.
+Enables or disables debug rendering for the simulation. When enabled, all colliders and rigid body outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.
 
 
 </td></tr>

package/examples/custom-ui/assets/ui/index.html

@@ -0,0 +1,91 @@
+<html>
+  <body>
+    <!-- 
+      We MUST always import the Hytopia UI library! 
+      Importing this library also imports the hytopia global.
+
+      If we were using React, or Svelte, or another framework, we
+      can install the HYTPIA UI library as a package and import it
+      with `npm install hytopia-ui` and then import it as
+      `import hytopia from 'hytopia-ui';`
+    -->
+    <script src="https://unpkg.com/hytopia-ui@latest/dist/index.umd.js"></script>
+
+    <script>
+      document.addEventListener('DOMContentLoaded', () => {
+        // Handle received data from server
+        hytopia.ui.onData = data => {
+          if (data.type === 'playerList') {
+            const { list } = data;
+
+            // Update player count
+            document.getElementById('player-count').textContent = `Players Connected: ${list.length}`;
+
+            // Clear and rebuild player list
+            const playerListElement = document.getElementById('player-list');
+            playerListElement.innerHTML = '';
+
+            // Add each player to the list
+            list.forEach(player => {
+              const pos = player.position;
+              const playerRow = document.createElement('div');
+              playerRow.className = 'player-row';
+              playerRow.textContent = `${player.username}: x:${pos.x.toFixed(1)}, y:${pos.y.toFixed(1)}, z:${pos.z.toFixed(1)}`;
+              playerListElement.appendChild(playerRow);
+            });
+          }
+        }
+
+        // Send data to server on teleport btn press
+        document.getElementById('teleport-btn').addEventListener('click', () => {
+          // We can send any arbitrary object to the server. We as the developer define
+          // whatever schema we want to use for data between client and server.
+          // For now we'll just use a "type" property we made up so the server knows
+          // what to do with the data.
+          hytopia.ui.sendData({ type: 'teleport' });
+        });
+      });
+    </script>
+
+    <div id="player-panel">
+      <div id="player-count">Players Connected: 0</div>
+      <div id="player-list"></div>
+      <button id="teleport-btn">Click to Teleport!</button>
+    </div>
+
+    <style>
+      #player-panel {
+        position: absolute;
+        right: 20px;
+        top: 20px;
+        background-color: rgba(0, 0, 0, 0.7);
+        color: white;
+        padding: 15px;
+        border-radius: 8px;
+        min-width: 200px;
+        font-family: Arial, sans-serif;
+        letter-spacing: 0.5px;
+      }
+      .player-row {
+        margin: 8px 0;
+      }
+      #teleport-btn {
+        width: 100%;
+        padding: 8px;
+        margin-top: 15px;
+        background-color: #4CAF50;
+        color: white;
+        border: none;
+        border-radius: 4px;
+        cursor: pointer;
+        font-family: Arial, sans-serif;
+        font-weight: bold;
+        text-transform: uppercase;
+        letter-spacing: 1px;
+      }
+      #teleport-btn:hover {
+        background-color: #45a049;
+      }
+    </style>
+  </body>
+</html>

package/examples/custom-ui/index.ts

@@ -0,0 +1,91 @@
+import {
+  startServer,
+  Audio,
+  Player,
+  PlayerEntity,
+  PlayerUI,
+} from 'hytopia';
+
+import worldMap from './assets/map.json';
+
+// Simple map for player -> singular controlled entity
+const playerEntityMap = new Map<Player, PlayerEntity>();
+
+startServer(world => {
+  world.loadMap(worldMap);
+
+  world.onPlayerJoin = player => {
+    // Load the UI for the player.
+    // This is loaded directly into a sandboxed iframe
+    // overlaying the game. As long as it's an HTML file,
+    // it can be loaded. You can bundle React, Svelte, or
+    // any other framework into the UI you want to serve,
+    // or just use plain HTML like in this example.
+    player.ui.load('ui/index.html');
+
+    const playerEntity = new PlayerEntity({
+      player,
+      name: 'Player',
+      modelUri: 'models/player.gltf',
+      modelLoopedAnimations: [ 'idle' ],
+      modelScale: 0.5,
+    });
+
+    playerEntity.spawn(world, { x: 0, y: 10, z: 0 });
+
+    // Set the player entity on our map for when
+    // we do player list updates.
+    playerEntityMap.set(player, playerEntity);
+
+    // Handle data sent from player to server by client UI interactions we define. 
+    // See the ui/index.html file for the UI code that sends the data.
+    player.ui.onData = (playerUI: PlayerUI, data: Record<string, any>) => {
+      if (data.type === 'teleport') {
+        const randomX = Math.random() * 40 - 20; // Random between -20 and 20
+        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 });
+      }
+    };
+  };
+
+  world.onPlayerLeave = player => {
+    world.entityManager.getAllPlayerEntities(player).forEach(entity => entity.despawn());
+    // Remove the player entity from our map for our list.
+    playerEntityMap.delete(player);
+  };
+
+  // Update the player list every 1 second, no need to send too frequently.
+  // We want to balance not sending too much UI data too frequently, because
+  // it is currently sent over the same connection as game packets and will
+  // compete for critical game packet bandwidth on slower player connections.
+  setInterval(updatePlayerList, 1000);
+
+  new Audio({
+    uri: 'audio/music/overworld.mp3',
+    loop: true,
+    volume: 0.2,
+  }).play(world);
+});
+
+function updatePlayerList() {
+  // Create a list of all connected players and their positions
+  const playerListData = Array.from(playerEntityMap).map(([ player, entity ]) => {
+    // For each player, return their username and current position
+    return {
+      username: player.username,
+      position: entity.getTranslation(), // Gets x,y,z coordinate
+    };
+  });
+
+  // Send the updated player list to every connected player's UI
+  for (const [ player ] of playerEntityMap) {
+    player.ui.sendData({
+      type: 'playerList', // Message type for UI to handle
+      list: playerListData, // List of all players and positions
+    });
+  }
+}
+
+

package/package.json

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

package/server.api.json

@@ -13461,6 +13461,37 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "server!Player#ui:member",
+              "docComment": "/**\n * The UI for the player.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly ui: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "PlayerUI",
+                  "canonicalReference": "server!~PlayerUI:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "ui",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "server!Player#username:member",
@@ -22362,10 +22393,58 @@
               "isAbstract": false,
               "name": "castRay"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "server!Simulation#enableDebugRaycasting:member(1)",
+              "docComment": "/**\n * Enables or disables debug raycasting for the simulation. This will render lines for the raycast that disappear after a few seconds.\n *\n * @param enabled - Whether to enable debug raycasting.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "enableDebugRaycasting(enabled: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "enabled",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "enableDebugRaycasting"
+            },
             {
               "kind": "Method",
               "canonicalReference": "server!Simulation#enableDebugRendering:member(1)",
-              "docComment": "/**\n * Enables or disables debug rendering for the simulation. When enabled, all colliders, rigid body and raycast outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.\n *\n * @param enabled - Whether to enable debug rendering.\n */\n",
+              "docComment": "/**\n * Enables or disables debug rendering for the simulation. When enabled, all colliders and rigid body outlines will be rendered in the world. Do not enable this in production. In large worlds enabling this can cause noticable lag and RTT spikes.\n *\n * @param enabled - Whether to enable debug rendering.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -22512,6 +22591,36 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "server!Simulation#isDebugRaycastingEnabled:member",
+              "docComment": "/**\n * Whether the simulation has debug raycasting enabled\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get isDebugRaycastingEnabled(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "isDebugRaycastingEnabled",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "server!Simulation#isDebugRenderingEnabled:member",

package/server.d.ts

@@ -1813,6 +1813,8 @@ export declare class Player {
     /** The camera for the player. */
     readonly camera: PlayerCamera;
 
+    /** The UI for the player. */
+    readonly ui: PlayerUI;
 
 
 
@@ -1846,6 +1848,7 @@ export declare class Player {
 
 
 
+
 }
 
 /**
@@ -2183,6 +2186,45 @@ export declare type PlayerOrientationState = {
     yaw: number;
 };
 
+/**
+ * The UI for a player.
+ *
+ * @remarks
+ * UI allows control of all in-game overlays a player
+ * sees. UI is controlled by HTML, CSS and JavaScript
+ * files you provide in your `assets` folder.
+ *
+ * @public
+ */
+declare class PlayerUI {
+    /** The player that the UI belongs to. @readonly */
+    readonly player: Player;
+    /**
+     * A function that is called when the player's client UI
+     * sends data to the server.
+     *
+     * @remarks
+     * Data sent is an object of any shape defined by you
+     * and controlled with invocations of  `hytopia.ui.sendData()`
+     * from your loaded client UI files.
+     *
+     * @param playerUI - The PlayerUI instance that the data is from.
+     * @param data - The data sent from the client UI.
+     */
+    onData?: (playerUI: PlayerUI, data: object) => void;
+
+    /**
+     * Loads client UI for the player.
+     * @param htmlUri - The ui html uri to load.
+     */
+    load(htmlUri: string): void;
+    /**
+     * Sends data to the player's client UI.
+     * @param data - The data to send to the client UI.
+     */
+    sendData(data: object): void;
+}
+
 /**
  * The port the server will run on. You can override
  * this in your .env by setting PORT. When deployed in
@@ -2929,6 +2971,9 @@ export declare class Simulation {
 
 
 
+
+    /** Whether the simulation has debug raycasting enabled */
+    get isDebugRaycastingEnabled(): boolean;
     /** Whether the simulation has debug rendering enabled. */
     get isDebugRenderingEnabled(): boolean;
     /** The gravity vector for the simulation. */
@@ -2948,9 +2993,16 @@ export declare class Simulation {
     castRay(origin: RAPIER.Vector3, direction: RAPIER.Vector3, length: number, options?: RayCastOptions): Block | Entity | null;
 
 
+    /**
+     * Enables or disables debug raycasting for the simulation.
+     * This will render lines for the raycast that disappear
+     * after a few seconds.
+     * @param enabled - Whether to enable debug raycasting.
+     */
+    enableDebugRaycasting(enabled: boolean): void;
     /**
      * Enables or disables debug rendering for the simulation.
-     * When enabled, all colliders, rigid body and raycast outlines
+     * When enabled, all colliders and rigid body outlines
      * will be rendered in the world. Do not enable this in production.
      * In large worlds enabling this can cause noticable lag and RTT spikes.
      * @param enabled - Whether to enable debug rendering.