hytopia 0.1.77 → 0.1.79

package/docs/server.entity.despawn.md

@@ -4,7 +4,7 @@
 
 ## Entity.despawn() method
 
-Despawns the entity from the world.
+Despawns the entity and all children from the world.
 
 **Signature:**
 

package/docs/server.entity.md

@@ -528,6 +528,48 @@ number \| undefined
 The opacity of the entity between 0 and 1. 0 is fully transparent, 1 is fully opaque.
 
 
+</td></tr>
+<tr><td>
+
+[parent](./server.entity.parent.md)
+
+
+</td><td>
+
+`readonly`
+
+
+</td><td>
+
+[Entity](./server.entity.md) \| undefined
+
+
+</td><td>
+
+The parent entity of the entity.
+
+
+</td></tr>
+<tr><td>
+
+[parentNodeName](./server.entity.parentnodename.md)
+
+
+</td><td>
+
+`readonly`
+
+
+</td><td>
+
+string \| undefined
+
+
+</td><td>
+
+The name of the parent's node (if parent is a model entity) this entity is attached to when spawned.
+
+
 </td></tr>
 <tr><td>
 
@@ -622,7 +664,7 @@ Description
 
 </td><td>
 
-Despawns the entity from the world.
+Despawns the entity and all children from the world.
 
 
 </td></tr>
@@ -698,7 +740,7 @@ Sets the tint color of the entity.
 </td></tr>
 <tr><td>
 
-[spawn(world, coordinate)](./server.entity.spawn.md)
+[spawn(world, position, rotation)](./server.entity.spawn.md)
 
 
 </td><td>

package/docs/server.entity.parent.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; [Entity](./server.entity.md) &gt; [parent](./server.entity.parent.md)
+
+## Entity.parent property
+
+The parent entity of the entity.
+
+**Signature:**
+
+```typescript
+get parent(): Entity | undefined;
+```

package/docs/server.entity.parentnodename.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; [Entity](./server.entity.md) &gt; [parentNodeName](./server.entity.parentnodename.md)
+
+## Entity.parentNodeName property
+
+The name of the parent's node (if parent is a model entity) this entity is attached to when spawned.
+
+**Signature:**
+
+```typescript
+get parentNodeName(): string | undefined;
+```

package/docs/server.entity.spawn.md

@@ -9,7 +9,7 @@ Spawns the entity in the world.
 **Signature:**
 
 ```typescript
-spawn(world: World, coordinate: Vector3Like): void;
+spawn(world: World, position: Vector3Like, rotation?: QuaternionLike): void;
 ```
 
 ## Parameters
@@ -48,7 +48,7 @@ The world to spawn the entity in.
 </td></tr>
 <tr><td>
 
-coordinate
+position
 
 
 </td><td>
@@ -58,7 +58,23 @@ coordinate
 
 </td><td>
 
-The coordinate to spawn the entity at.
+The position to spawn the entity at.
+
+
+</td></tr>
+<tr><td>
+
+rotation
+
+
+</td><td>
+
+[QuaternionLike](./server.quaternionlike.md)
+
+
+</td><td>
+
+_(Optional)_ The optional rotation to spawn the entity with.
 
 
 </td></tr>

package/docs/server.entitymanager.getentitychildren.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; [getEntityChildren](./server.entitymanager.getentitychildren.md)
+
+## EntityManager.getEntityChildren() method
+
+Gets all child entities of an entity.
+
+**Signature:**
+
+```typescript
+getEntityChildren(entity: Entity): Entity[];
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+entity
+
+
+</td><td>
+
+[Entity](./server.entity.md)
+
+
+</td><td>
+
+The entity to get the children for.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[Entity](./server.entity.md)<!-- -->\[\]
+
+All child entities of the entity.
+

package/docs/server.entitymanager.md

@@ -160,6 +160,20 @@ 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>
+
+[getEntityChildren(entity)](./server.entitymanager.getentitychildren.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Gets all child entities of an entity.
+
+
 </td></tr>
 <tr><td>
 

package/docs/server.entityoptions.md

@@ -224,6 +224,44 @@ number
 _(Optional)_ The opacity of the entity between 0 and 1. 0 is fully transparent, 1 is fully opaque.
 
 
+</td></tr>
+<tr><td>
+
+[parent?](./server.entityoptions.parent.md)
+
+
+</td><td>
+
+
+</td><td>
+
+[Entity](./server.entity.md)
+
+
+</td><td>
+
+_(Optional)_ The parent entity of the entity, entities with a parent will ignore creating their own colliders.
+
+
+</td></tr>
+<tr><td>
+
+[parentNodeName?](./server.entityoptions.parentnodename.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+_(Optional)_ The name of the parent's node (if parent is a model entity) to attach the entity to.
+
+
 </td></tr>
 <tr><td>
 

package/docs/server.entityoptions.parent.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; [EntityOptions](./server.entityoptions.md) &gt; [parent](./server.entityoptions.parent.md)
+
+## EntityOptions.parent property
+
+The parent entity of the entity, entities with a parent will ignore creating their own colliders.
+
+**Signature:**
+
+```typescript
+parent?: Entity;
+```

package/docs/server.entityoptions.parentnodename.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; [EntityOptions](./server.entityoptions.md) &gt; [parentNodeName](./server.entityoptions.parentnodename.md)
+
+## EntityOptions.parentNodeName property
+
+The name of the parent's node (if parent is a model entity) to attach the entity to.
+
+**Signature:**
+
+```typescript
+parentNodeName?: string;
+```

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.getnodenames.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; [ModelRegistry](./server.modelregistry.md) &gt; [getNodeNames](./server.modelregistry.getnodenames.md)
+
+## ModelRegistry.getNodeNames() method
+
+Retrieves the names of all nodes in a model.
+
+**Signature:**
+
+```typescript
+getNodeNames(modelUri: string): string[];
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+modelUri
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The URI of the model to retrieve the node names for.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+string\[\]
+
+The names of all nodes in the 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.modelregistry.md

@@ -0,0 +1,139 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [ModelRegistry](./server.modelregistry.md)
+
+## ModelRegistry class
+
+Manages model data for all known models of the game.
+
+**Signature:**
+
+```typescript
+export default class ModelRegistry 
+```
+
+## Remarks
+
+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 `ModelRegistry` class.
+
+## Example
+
+
+```typescript
+import { ModelRegistry } from 'hytopia';
+
+const modelRegistry = ModelRegistry.instance;
+const boundingBox = modelRegistry.getBoundingBox('models/player.gltf');
+```
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[instance](./server.modelregistry.instance.md)
+
+
+</td><td>
+
+`static`
+
+`readonly`
+
+
+</td><td>
+
+[ModelRegistry](./server.modelregistry.md)
+
+
+</td><td>
+
+The global ModelRegistry instance as a singleton.
+
+
+</td></tr>
+</tbody></table>
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[getBoundingBox(modelUri)](./server.modelregistry.getboundingbox.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Retrieves the bounding box of a model.
+
+
+</td></tr>
+<tr><td>
+
+[getNodeNames(modelUri)](./server.modelregistry.getnodenames.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Retrieves the names of all nodes in a model.
+
+
+</td></tr>
+<tr><td>
+
+[modelHasNode(modelUri, nodeName)](./server.modelregistry.modelhasnode.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Checks if a model has a node with the given name.
+
+
+</td></tr>
+</tbody></table>

package/docs/server.modelregistry.modelhasnode.md

@@ -0,0 +1,71 @@
+<!-- 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; [modelHasNode](./server.modelregistry.modelhasnode.md)
+
+## ModelRegistry.modelHasNode() method
+
+Checks if a model has a node with the given name.
+
+**Signature:**
+
+```typescript
+modelHasNode(modelUri: string, nodeName: string): boolean;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+modelUri
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The URI of the model to check.
+
+
+</td></tr>
+<tr><td>
+
+nodeName
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The name of the node to check for.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+boolean
+
+Whether the model has a node with the given name.
+

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 :)