hytopia 0.1.76 → 0.1.78

package/boilerplate/index.ts

@@ -103,7 +103,7 @@ startServer(world => {
    * instance.
    */
   world.onPlayerLeave = player => {
-    world.entityManager.getAllPlayerEntities(player).forEach(entity => entity.despawn());
+    world.entityManager.getPlayerEntitiesByPlayer(player).forEach(entity => entity.despawn());
   };
 
   /**
@@ -111,7 +111,7 @@ startServer(world => {
    * "/rocket" in the game, they'll get launched into the air!
    */
   world.chatManager.registerCommand('/rocket', player => {
-    world.entityManager.getAllPlayerEntities(player).forEach(entity => {
+    world.entityManager.getPlayerEntitiesByPlayer(player).forEach(entity => {
       entity.applyImpulse({ x: 0, y: 20, z: 0 });
     });
   });

package/docs/server.entitymanager.getallplayerentities.md

@@ -4,52 +4,16 @@
 
 ## EntityManager.getAllPlayerEntities() method
 
-Gets all spawned entities in the world assigned to a player.
+Gets all spawned player entities in the world.
 
 **Signature:**
 
 ```typescript
-getAllPlayerEntities(player: Player): PlayerEntity[];
+getAllPlayerEntities(): PlayerEntity[];
 ```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-player
-
-
-</td><td>
-
-[Player](./server.player.md)
-
-
-</td><td>
-
-The player to get the entities for.
-
-
-</td></tr>
-</tbody></table>
 **Returns:**
 
 [PlayerEntity](./server.playerentity.md)<!-- -->\[\]
 
-All spawned entities in the world assigned to the player.
+All spawned player entities in the world.
 

package/docs/server.entitymanager.getplayerentitiesbyplayer.md

@@ -0,0 +1,55 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [EntityManager](./server.entitymanager.md) &gt; [getPlayerEntitiesByPlayer](./server.entitymanager.getplayerentitiesbyplayer.md)
+
+## EntityManager.getPlayerEntitiesByPlayer() method
+
+Gets all spawned entities in the world assigned to the provided player.
+
+**Signature:**
+
+```typescript
+getPlayerEntitiesByPlayer(player: Player): PlayerEntity[];
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+player
+
+
+</td><td>
+
+[Player](./server.player.md)
+
+
+</td><td>
+
+The player to get the entities for.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[PlayerEntity](./server.playerentity.md)<!-- -->\[\]
+
+All spawned entities in the world assigned to the player.
+

package/docs/server.entitymanager.md

@@ -107,7 +107,7 @@ Gets all spawned entities in the world.
 </td></tr>
 <tr><td>
 
-[getAllPlayerEntities(player)](./server.entitymanager.getallplayerentities.md)
+[getAllPlayerEntities()](./server.entitymanager.getallplayerentities.md)
 
 
 </td><td>
@@ -115,7 +115,7 @@ Gets all spawned entities in the world.
 
 </td><td>
 
-Gets all spawned entities in the world assigned to a player.
+Gets all spawned player entities in the world.
 
 
 </td></tr>
@@ -160,5 +160,19 @@ Gets all spawned entities in the world with a tag that includes a specific subst
 Gets a spawned entity in the world by its id.
 
 
+</td></tr>
+<tr><td>
+
+[getPlayerEntitiesByPlayer(player)](./server.entitymanager.getplayerentitiesbyplayer.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Gets all spawned entities in the world assigned to the provided player.
+
+
 </td></tr>
 </tbody></table>

package/docs/server.gameserver.md

@@ -66,7 +66,7 @@ The singleton instance of the game server.
 </td></tr>
 <tr><td>
 
-[modelManager](./server.gameserver.modelmanager.md)
+[modelRegistry](./server.gameserver.modelregistry.md)
 
 
 </td><td>
@@ -76,7 +76,7 @@ The singleton instance of the game server.
 
 </td><td>
 
-[ModelManager](./server.modelmanager.md)
+[ModelRegistry](./server.modelregistry.md)
 
 
 </td><td>

package/docs/{server.gameserver.modelmanager.md → server.gameserver.modelregistry.md}

@@ -1,13 +1,13 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [server](./server.md) &gt; [GameServer](./server.gameserver.md) &gt; [modelManager](./server.gameserver.modelmanager.md)
+[Home](./index.md) &gt; [server](./server.md) &gt; [GameServer](./server.gameserver.md) &gt; [modelRegistry](./server.gameserver.modelregistry.md)
 
-## GameServer.modelManager property
+## GameServer.modelRegistry property
 
 The model manager for the game server.
 
 **Signature:**
 
 ```typescript
-get modelManager(): ModelManager;
+get modelRegistry(): ModelRegistry;
 ```

package/docs/server.md

@@ -195,7 +195,7 @@ Manages Light instances in a world.
 </td></tr>
 <tr><td>
 
-[ModelManager](./server.modelmanager.md)
+[ModelRegistry](./server.modelregistry.md)
 
 
 </td><td>

package/docs/{server.modelmanager.getboundingbox.md → server.modelregistry.getboundingbox.md}

@@ -1,8 +1,8 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [server](./server.md) &gt; [ModelManager](./server.modelmanager.md) &gt; [getBoundingBox](./server.modelmanager.getboundingbox.md)
+[Home](./index.md) &gt; [server](./server.md) &gt; [ModelRegistry](./server.modelregistry.md) &gt; [getBoundingBox](./server.modelregistry.getboundingbox.md)
 
-## ModelManager.getBoundingBox() method
+## ModelRegistry.getBoundingBox() method
 
 Retrieves the bounding box of a model.
 

package/docs/server.modelregistry.instance.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; [ModelRegistry](./server.modelregistry.md) &gt; [instance](./server.modelregistry.instance.md)
+
+## ModelRegistry.instance property
+
+The global ModelRegistry instance as a singleton.
+
+**Signature:**
+
+```typescript
+static readonly instance: ModelRegistry;
+```

package/docs/{server.modelmanager.md → server.modelregistry.md}

@@ -1,31 +1,31 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [server](./server.md) &gt; [ModelManager](./server.modelmanager.md)
+[Home](./index.md) &gt; [server](./server.md) &gt; [ModelRegistry](./server.modelregistry.md)
 
-## ModelManager class
+## ModelRegistry class
 
 Manages model data for all known models of the game.
 
 **Signature:**
 
 ```typescript
-export default class ModelManager 
+export default class ModelRegistry 
 ```
 
 ## Remarks
 
-The ModelManager is created internally as a global singletone accessible with the static property `ModelManager.instance`<!-- -->.
+The ModelRegistry is created internally as a global singletone accessible with the static property `ModelRegistry.instance`<!-- -->.
 
-The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ModelManager` class.
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ModelRegistry` class.
 
 ## Example
 
 
 ```typescript
-import { ModelManager } from 'hytopia';
+import { ModelRegistry } from 'hytopia';
 
-const modelManager = ModelManager.instance;
-const boundingBox = modelManager.getBoundingBox('models/player.gltf');
+const modelRegistry = ModelRegistry.instance;
+const boundingBox = modelRegistry.getBoundingBox('models/player.gltf');
 ```
 
 ## Properties
@@ -53,7 +53,7 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[instance](./server.modelmanager.instance.md)
+[instance](./server.modelregistry.instance.md)
 
 
 </td><td>
@@ -65,12 +65,12 @@ Description
 
 </td><td>
 
-[ModelManager](./server.modelmanager.md)
+[ModelRegistry](./server.modelregistry.md)
 
 
 </td><td>
 
-The global PlayerManager instance as a singleton.
+The global ModelRegistry instance as a singleton.
 
 
 </td></tr>
@@ -96,7 +96,7 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[getBoundingBox(modelUri)](./server.modelmanager.getboundingbox.md)
+[getBoundingBox(modelUri)](./server.modelregistry.getboundingbox.md)
 
 
 </td><td>

package/docs/server.playermanager.getconnectedplayersbyworld.md

@@ -0,0 +1,55 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [PlayerManager](./server.playermanager.md) &gt; [getConnectedPlayersByWorld](./server.playermanager.getconnectedplayersbyworld.md)
+
+## PlayerManager.getConnectedPlayersByWorld() method
+
+Get all connected players in a specific world.
+
+**Signature:**
+
+```typescript
+getConnectedPlayersByWorld(world: World): Player[];
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+world
+
+
+</td><td>
+
+[World](./server.world.md)
+
+
+</td><td>
+
+The world to get connected players for.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[Player](./server.player.md)<!-- -->\[\]
+
+An array of all connected players in the world.
+

package/docs/server.playermanager.md

@@ -121,5 +121,19 @@ Get a connected player by their username (case insensitive).
 Get all connected players.
 
 
+</td></tr>
+<tr><td>
+
+[getConnectedPlayersByWorld(world)](./server.playermanager.getconnectedplayersbyworld.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Get all connected players in a specific world.
+
+
 </td></tr>
 </tbody></table>

package/docs/server.sceneuimanager.getsceneuibyid.md

@@ -0,0 +1,55 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [SceneUIManager](./server.sceneuimanager.md) &gt; [getSceneUIById](./server.sceneuimanager.getsceneuibyid.md)
+
+## SceneUIManager.getSceneUIById() method
+
+Retrieves a SceneUI instance by its unique identifier (id).
+
+**Signature:**
+
+```typescript
+getSceneUIById(id: number): SceneUI | undefined;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+id
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+The unique identifier (id) of the SceneUI to retrieve.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[SceneUI](./server.sceneui.md) \| undefined
+
+The SceneUI instance if found, otherwise undefined.
+

package/docs/server.sceneuimanager.md

@@ -109,6 +109,20 @@ Retrieves all loaded SceneUI instances attached to a specific entity.
 Retrieves all loaded SceneUI instances for the world.
 
 
+</td></tr>
+<tr><td>
+
+[getSceneUIById(id)](./server.sceneuimanager.getsceneuibyid.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Retrieves a SceneUI instance by its unique identifier (id).
+
+
 </td></tr>
 <tr><td>
 

package/examples/ai-agents/README.md

@@ -0,0 +1,47 @@
+# Hytopia Multi Agent Demo
+
+This demo codebase provides an example for building multi Agent AI systems in Hytopia. The server has the following features:
+- Multiple AI agents with unique pathfinding, behaviour and capabilities
+- Chat bubbles for agent speech
+- Side bar UI for viewing Agent actions
+
+## How do Agents work in Hytopia?
+Game Agents are driven by a combination of game-specific action logic, world state representation, and Large Language Models.
+
+At a high level, to integrate agents into your game, you need to think about these three pieces.
+
+### World State Representation
+Your Agents need to know what is going on in the game. Where are they? What is around them? etc..
+In this demo, the following data is available in the Agent's personal state:
+- Their location
+- Entities around them
+- The status of any ongoing actions ("Behaviors")
+- Items in their inventory
+
+For more information on this, see the [`getCurrentState()`](src/BaseAgent.ts#L205) function in BaseAgent. Each behavior returns their Agent-specific state as a string, which we group together into an object and stringify it for the Agent's prompt.
+States are prepended to each prompt to the agent.
+
+### Actions
+Actions are things that people and agents do in your game. In this simple demo, the things people do are simple: they go places, they say things, and some of them do profession-specific tasks like Fishing and Mining.
+
+Going places means going to specific locations (by coordinates), or going to a person or thing (by name). This means Bob can go to Jim, without knowing where Jim is. Bob might also decide to go to the Pier, since Jim is a Fisherman and one would expect the town fisherman to be at the pier.
+
+Saying things is simple, but the weeds of what that means is also game specific. In this demo, when agents speak, other agents can hear them in close proximity, but for the sake of the demo we also show their messages globally in chat. Speaking also spawns a chat bubble UI template. See the [`agent-chat template`](assets/ui/index.html#L178) for more info on this.
+
+Actions also interact with LLMs. Since actions are called by the LLM, we need to show the LLM how to call them.
+Some agent frameworks use tool calling/function calling, which is very popular with OpenAI.
+You can do this if you want, but I prefer XML. XML takes less output tokens, is very natural for LLMs to write (billions of html pages parsed). Most importantly, valid XML can be easily regexed out of any text, intermingled with other thoughts from the LLM. Many benchmarks show creativity in language models decreasing as output format is increasingly restricted.
+
+In this demo, an action can be called by an LLM simply by outputting text like this:
+`<action type="speak">...</action>`
+
+Another benefit of this approach is that models with very little infrastructure around their APIs can all output valid XML, so you can easily use whatever model or provider you want.
+
+### Large Language Models
+LLM's act as a router and brain for the agent, converting state representations and inputs into a sequence of actions.
+LLM's need to be prompted. You will not get a spontaneous output without an input. In a game, this means you need to decide when Agent's make decisions. In this demo I show two common techniques:
+- Response Triggers: when a Player speaks to an Agent, they will respond immediately. This lets players have some immediate control over influencing agent behaviours, and makes it easy to test your prompts with quick feedback. This is best for smaller player counts.
+- Game Steps: as you can imagine, the above response triggers will not work at scale. Imagine 100 players in an area all talking to the same agent. You would not want it to respond outloud to everyone in the area. Instead, you can take a page out of the playbook of turn-based strategy games. Divide your game time into turns (a step could be every 5 seconds, 10 seconds, whatever you want), and each turn, you trigger each agent with the new state since their last turn. Players don't need to be limited by turns, but this makes your agents a bit simpler to manage. You can see an example of how this works in the idle detection of the agents in this repo. If an agent has not been triggered by a player in the last 30 seconds, they wake up and can decide what to do next.
+
+## What's next?
+We want to continue to make AI Agents accessible for developers of Hytopia games. This means more game-specific demos, more tooling, and a standardized Agent implementation that you can import as a plugin into your games. More on this soon :)