hytopia 0.14.49 → 0.14.50

package/docs/server.audio.md

@@ -597,7 +597,7 @@ Sets the playback rate of the audio.
 
 </td><td>
 
-Sets the position of the audio. Will detach from entity if attached.
+Sets the position of the audio.
 
 
 </td></tr>

package/docs/server.audio.setattachedtoentity.md

@@ -51,3 +51,7 @@ The entity to attach the Audio to.
 
 void
 
+## Remarks
+
+\*\*Clears position:\*\* Setting an attached entity clears any previously set `position`<!-- -->. Audio can be entity-attached or position-based, not both.
+

package/docs/server.audio.setposition.md

@@ -4,7 +4,7 @@
 
 ## Audio.setPosition() method
 
-Sets the position of the audio. Will detach from entity if attached.
+Sets the position of the audio.
 
 **Signature:**
 
@@ -51,3 +51,7 @@ The position in the world.
 
 void
 
+## Remarks
+
+\*\*Detaches from entity:\*\* Setting a position clears any `attachedToEntity`<!-- -->. Audio can be position-based or entity-attached, not both.
+

package/docs/server.audiomanager.unregisteraudio.md

@@ -51,3 +51,7 @@ The audio instance to pause and unregister.
 
 void
 
+## Remarks
+
+\*\*Pauses audio:\*\* Calls `audio.pause()` before removing from the manager.
+

package/docs/server.audiomanager.unregisterentityattachedaudios.md

@@ -51,3 +51,7 @@ The entity to pause and unregister audio instances for.
 
 void
 
+## Remarks
+
+\*\*Pauses all:\*\* Calls `unregisterAudio()` for each attached audio, which pauses them.
+

package/docs/server.baseentitycontroller.attach.md

@@ -51,3 +51,9 @@ The entity to attach the controller to.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `Entity` constructor when a controller is provided in options.
+
+\*\*Super call:\*\* Call `super.attach(entity)` to emit the `ATTACH` event.
+

package/docs/server.baseentitycontroller.despawn.md

@@ -42,7 +42,7 @@ entity
 
 </td><td>
 
-The entity to despawn.
+The entity being despawned.
 
 
 </td></tr>
@@ -51,3 +51,9 @@ The entity to despawn.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `Entity.despawn()` after `detach()` is called.
+
+\*\*Super call:\*\* Call `super.despawn(entity)` to emit the `DESPAWN` event.
+

package/docs/server.baseentitycontroller.detach.md

@@ -42,7 +42,7 @@ entity
 
 </td><td>
 
-The entity to detach.
+The entity being detached.
 
 
 </td></tr>
@@ -51,3 +51,9 @@ The entity to detach.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `Entity.despawn()` before `despawn()` is called.
+
+\*\*Super call:\*\* Call `super.detach(entity)` to emit the `DETACH` event.
+

package/docs/server.baseentitycontroller.md

@@ -119,7 +119,7 @@ Override this method to handle entity movements based on your entity controller.
 
 </td><td>
 
-Override this method to handle entity movements based on player input for your entity controller. This is called every tick by a PlayerEntity with a entity controller.
+Override this method to handle entity movements based on player input for your entity controller.
 
 
 </td></tr>

package/docs/server.baseentitycontroller.spawn.md

@@ -42,7 +42,7 @@ entity
 
 </td><td>
 
-The entity to spawn.
+The entity being spawned.
 
 
 </td></tr>
@@ -51,3 +51,9 @@ The entity to spawn.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `Entity.spawn()` after the entity is added to the physics simulation.
+
+\*\*Super call:\*\* Call `super.spawn(entity)` to emit the `SPAWN` event.
+

package/docs/server.baseentitycontroller.tick.md

@@ -42,6 +42,8 @@ entity
 
 </td><td>
 
+The entity being ticked.
+
 
 </td></tr>
 <tr><td>
@@ -65,3 +67,9 @@ The delta time in milliseconds since the last tick.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `Entity.tick()` every tick for non-environmental entities. For `PlayerEntity`<!-- -->, this is called after `tickWithPlayerInput()`<!-- -->.
+
+\*\*Super call:\*\* Call `super.tick(entity, deltaTimeMs)` to emit the `TICK` event.
+

package/docs/server.baseentitycontroller.tickwithplayerinput.md

@@ -4,7 +4,7 @@
 
 ## BaseEntityController.tickWithPlayerInput() method
 
-Override this method to handle entity movements based on player input for your entity controller. This is called every tick by a PlayerEntity with a entity controller.
+Override this method to handle entity movements based on player input for your entity controller.
 
 **Signature:**
 
@@ -42,7 +42,7 @@ entity
 
 </td><td>
 
-The entity to tick.
+The player entity being ticked.
 
 
 </td></tr>
@@ -99,3 +99,9 @@ The delta time in milliseconds since the last tick.
 
 void
 
+## Remarks
+
+\*\*Called by:\*\* `PlayerEntity.tick()` every tick when `isTickWithPlayerInputEnabled` is true. Called before `tick()`<!-- -->.
+
+\*\*Super call:\*\* Call `super.tickWithPlayerInput(...)` to emit the `TICK_WITH_PLAYER_INPUT` event.
+

package/docs/server.blocktyperegistry.registergenericblocktype.md

@@ -53,3 +53,7 @@ The options for the block type.
 
 The registered block type.
 
+## Remarks
+
+\*\*Creates anonymous class:\*\* Internally creates an anonymous class extending `BlockType` with the provided options, then calls `registerBlockType()`<!-- -->.
+

package/docs/server.chunklattice.clear.md

@@ -15,3 +15,9 @@ clear(): void;
 
 void
 
+## Remarks
+
+\*\*Removes colliders:\*\* All block type colliders are removed from the physics simulation.
+
+\*\*Emits events:\*\* Emits `REMOVE_CHUNK` for each chunk before clearing.
+

package/docs/server.chunklattice.getorcreatechunk.md

@@ -4,7 +4,7 @@
 
 ## ChunkLattice.getOrCreateChunk() method
 
-Get the chunk for a given global coordinate.
+Get the chunk for a given global coordinate, creating it if it doesn't exist.
 
 **Signature:**
 
@@ -51,5 +51,9 @@ The global coordinate of the chunk to get.
 
 [Chunk](./server.chunk.md)
 
-The chunk at the given global coordinate or undefined if not found.
+The chunk at the given global coordinate (created if needed).
+
+## Remarks
+
+\*\*Creates chunk:\*\* If the chunk doesn't exist, creates a new one and emits `ADD_CHUNK`<!-- -->.
 

package/docs/server.chunklattice.initializeblocks.md

@@ -44,7 +44,7 @@ blocks
 
 </td><td>
 
-The blocks to initialize.
+The blocks to initialize, keyed by block type id.
 
 
 </td></tr>
@@ -53,3 +53,9 @@ The blocks to initialize.
 
 void
 
+## Remarks
+
+\*\*Clears first:\*\* Calls `clear()` before initializing, removing all existing blocks and colliders.
+
+\*\*Collider optimization:\*\* Creates one collider per block type with all placements combined. Voxel colliders have their states combined for efficient neighbor collision detection.
+

package/docs/server.chunklattice.md

@@ -209,7 +209,7 @@ Get the chunk that contains the given global coordinate.
 
 </td><td>
 
-Get the chunk for a given global coordinate.
+Get the chunk for a given global coordinate, creating it if it doesn't exist.
 
 
 </td></tr>

package/docs/server.chunklattice.setblock.md

@@ -74,7 +74,7 @@ blockRotation
 
 </td><td>
 
-_(Optional)_
+_(Optional)_ The rotation of the block.
 
 
 </td></tr>
@@ -83,3 +83,9 @@ _(Optional)_
 
 void
 
+## Remarks
+
+\*\*Collider updates:\*\* Manages physics colliders automatically. For voxel block types, updates the existing collider. For trimesh block types, recreates the entire collider.
+
+\*\*Removes previous:\*\* If replacing an existing block, removes it from its collider first. If the previous block type has no remaining blocks, its collider is removed from simulation.
+

package/docs/server.collider.addtosimulation.md

@@ -67,3 +67,9 @@ _(Optional)_ The parent rigid body of the collider.
 
 void
 
+## Remarks
+
+\*\*Parent linking:\*\* Links the collider to the parent rigid body if provided.
+
+\*\*Collision callback:\*\* Applies any configured `onCollision` callback.
+

package/docs/server.collider.removefromsimulation.md

@@ -15,3 +15,7 @@ removeFromSimulation(): void;
 
 void
 
+## Remarks
+
+\*\*Parent unlinking:\*\* Unlinks from parent rigid body if attached.
+

package/docs/server.collider.setoncollision.md

@@ -51,3 +51,7 @@ The on collision callback for the collider.
 
 void
 
+## Remarks
+
+\*\*Auto-enables events:\*\* Automatically enables/disables collision events based on whether callback is set.
+

package/docs/server.collider.setscale.md

@@ -49,3 +49,7 @@ scale
 
 void
 
+## Remarks
+
+\*\*Ratio-based:\*\* Uses ratio-based scaling relative to current scale, not absolute dimensions. Also scales `relativePosition` proportionally.
+

package/docs/server.defaultplayerentity._constructor_.md

@@ -4,7 +4,7 @@
 
 ## DefaultPlayerEntity.(constructor)
 
-Constructs a new instance of the `DefaultPlayerEntity` class
+Creates a new DefaultPlayerEntity instance.
 
 **Signature:**
 
@@ -42,6 +42,15 @@ options
 
 </td><td>
 
+The options for the default player entity.
+
 
 </td></tr>
 </tbody></table>
+
+## Remarks
+
+\*\*Auto-assigned defaults:\*\* A `DefaultPlayerEntityController` is automatically created and assigned. Default `modelLoopedAnimations` are `['idle_lower', 'idle_upper']`<!-- -->. All defaults can be overridden via options.
+
+\*\*Cosmetics on spawn:\*\* When spawned, player cosmetics (hair, skin, equipped items) are fetched asynchronously and applied. Child entities are created for hair and equipped cosmetic items.
+

package/docs/server.defaultplayerentity.md

@@ -54,7 +54,7 @@ Description
 
 </td><td>
 
-Constructs a new instance of the `DefaultPlayerEntity` class
+Creates a new DefaultPlayerEntity instance.
 
 
 </td></tr>

package/docs/server.defaultplayerentitycontroller.attach.md

@@ -51,3 +51,13 @@ The entity to attach the controller to.
 
 void
 
+## Remarks
+
+\*\*Wraps `applyImpulse`<!-- -->:\*\* The entity's `applyImpulse` method is wrapped to track external velocities separately from internal movement. External impulses decay over time when grounded.
+
+\*\*Locks rotations:\*\* Calls `entity.lockAllRotations()` to prevent physics from rotating the entity. Rotation is set explicitly by the controller based on camera orientation.
+
+\*\*Enables CCD:\*\* Enables continuous collision detection on the entity.
+
+\*\*Swimming detection:\*\* Registers a `BLOCK_COLLISION` listener to detect liquid blocks and manage swimming state, gravity scale, and animations.
+

package/docs/server.defaultplayerentitycontroller.md

@@ -17,6 +17,10 @@ export default class DefaultPlayerEntityController extends BaseEntityController
 
 This class extends [BaseEntityController](./server.baseentitycontroller.md) and implements the default movement, platforming, jump, swimming, and other basic logic for the default player entity. We recommend you extend this class if you'd like to implement additional logic on top of the DefaultPlayerEntityController implementation.
 
+<h2>Coordinate System &amp; Model Orientation</h2>
+
+HYTOPIA uses \*\*-Z as forward\*\*. Models must be authored with their front facing -Z. A yaw of 0 means facing -Z. The controller rotates the entity based on camera yaw and movement direction, always orienting the entity's -Z axis in the intended facing direction.
+
 ## Example
 
 

package/docs/server.defaultplayerentitycontroller.spawn.md

@@ -51,3 +51,9 @@ The entity that is spawned.
 
 void
 
+## Remarks
+
+\*\*Creates colliders:\*\* Adds two child colliders to the entity: - `groundSensor`<!-- -->: Cylinder sensor below entity for ground/platform detection and landing animations - `wallCollider`<!-- -->: Capsule collider for wall collision with zero friction
+
+\*\*Collider sizes scale:\*\* Collider dimensions scale proportionally with `entity.height`<!-- -->.
+

package/docs/server.defaultplayerentitycontroller.tickwithplayerinput.md

@@ -99,3 +99,13 @@ The delta time in milliseconds since the last tick.
 
 void
 
+## Remarks
+
+\*\*Rotation (-Z forward):\*\* Sets entity rotation based on camera yaw. A yaw of 0 faces -Z. Movement direction offsets (WASD/joystick) are added to camera yaw to determine facing. Models must be authored with their front facing -Z.
+
+\*\*Child entities:\*\* If `entity.parent` is set, only emits the event and returns early. Movement logic is skipped for child entities.
+
+\*\*Input cancellation:\*\* If `autoCancelMouseLeftClick` is true (default), `input.ml` is set to `false` after processing to prevent repeated triggers.
+
+\*\*Animations:\*\* Automatically manages idle, walk, run, jump, swim, and interact animations based on movement state and input.
+

package/docs/server.entity._constructor_.md

@@ -4,7 +4,7 @@
 
 ## Entity.(constructor)
 
-Constructs a new instance of the `Entity` class
+Creates a new Entity instance.
 
 **Signature:**
 
@@ -47,3 +47,8 @@ The options for the entity.
 
 </td></tr>
 </tbody></table>
+
+## Remarks
+
+\*\*Controller attachment:\*\* If `controller` is provided, `controller.attach(this)` is called during construction (before spawn).
+

package/docs/server.entity.despawn.md

@@ -15,3 +15,13 @@ despawn(): void;
 
 void
 
+## Remarks
+
+\*\*Cascading:\*\* Recursively despawns all child entities first (depth-first).
+
+\*\*Controller:\*\* Calls `controller.detach()` then `controller.despawn()` if attached.
+
+\*\*Cleanup:\*\* Automatically unregisters attached audios, despawns attached particle emitters, and unloads attached scene UIs from their respective managers.
+
+\*\*Simulation:\*\* Removes from physics simulation.
+

package/docs/server.entity.md

@@ -19,6 +19,12 @@ export default class Entity extends RigidBody implements protocol.Serializable
 
 Entities are highly configurable and controllable. All entities are created from a .gltf model asset and allow full control of their rigid body and attached collider dynamics.
 
+<h2>Coordinate System</h2>
+
+HYTOPIA uses a right-handed coordinate system where: - \*\*+X\*\* is right - \*\*+Y\*\* is up - \*\*-Z\*\* is forward (identity orientation)
+
+Models should be authored with their front/forward facing the \*\*-Z axis\*\*. When an entity has identity rotation (0,0,0,1 quaternion or yaw=0), it faces -Z.
+
 <h2>Events</h2>
 
 This class is an EventRouter, and instances of it emit events with payloads listed under [EntityEventPayloads](./server.entityeventpayloads.md)
@@ -77,7 +83,7 @@ Description
 
 </td><td>
 
-Constructs a new instance of the `Entity` class
+Creates a new Entity instance.
 
 
 </td></tr>
@@ -997,7 +1003,7 @@ Starts a oneshot animation for the entity, blending with other animations curren
 
 </td><td>
 
-Stops all looped and oneshot animations for the entity, optionally excluded the provided animations from stopping.
+Stops all looped and oneshot animations for the entity, optionally excluding the provided animations from stopping.
 
 
 </td></tr>

package/docs/server.entity.setmodelhiddennodes.md

@@ -51,3 +51,7 @@ The nodes to hide on the entity's model.
 
 void
 
+## Remarks
+
+\*\*Replaces, not merges:\*\* This replaces all hidden nodes, not adds to them. To add nodes, include existing hidden nodes in the array.
+

package/docs/server.entity.setmodelscale.md

@@ -51,3 +51,9 @@ The scale of the entity's model. Can be a vector or a number for uniform scaling
 
 void
 
+## Remarks
+
+\*\*Collider scaling is relative:\*\* Colliders are scaled by the ratio of new/old scale, not set to absolute values. Example: scaling from 1 to 2 doubles collider size; scaling from 2 to 4 also doubles it.
+
+\*\*Reference equality check:\*\* Uses `===` to compare with current scale, so passing the same object reference will early return even if values changed. Always pass a new object.
+

package/docs/server.entity.setmodelshownnodes.md

@@ -51,3 +51,7 @@ The nodes to show on the entity's model.
 
 void
 
+## Remarks
+
+\*\*Replaces, not merges:\*\* This replaces all shown nodes, not adds to them. To add nodes, include existing shown nodes in the array.
+

package/docs/server.entity.spawn.md

@@ -83,3 +83,17 @@ _(Optional)_ The optional rotation to spawn the entity with.
 
 void
 
+## Remarks
+
+\*\*Rotation default:\*\* If no rotation is provided, entity spawns with identity rotation facing -Z. For Y-axis rotation (yaw): `{ x: 0, y: sin(yaw/2), z: 0, w: cos(yaw/2) }`<!-- -->. Yaw 0 = facing -Z.
+
+\*\*Auto-collider creation:\*\* If no colliders are provided, a default collider is auto-generated from the model bounds (or block half extents). Set `modelPreferredShape` to `ColliderShape.NONE` to disable.
+
+\*\*Collision groups:\*\* Colliders with default collision groups are auto-assigned based on `isEnvironmental` and `isSensor` flags. Environmental entities don't collide with blocks or other environmental entities.
+
+\*\*Event enabling:\*\* Collision/contact force events are auto-enabled on colliders if listeners are registered for `BLOCK_COLLISION`<!-- -->, `ENTITY_COLLISION`<!-- -->, `BLOCK_CONTACT_FORCE`<!-- -->, or `ENTITY_CONTACT_FORCE` prior to spawning.
+
+\*\*Controller:\*\* If a controller is attached, `controller.spawn()` is called after the entity is added to the physics simulation.
+
+\*\*Parent handling:\*\* If `parent` was set in options, `setParent()` is called after spawn with the provided position/rotation.
+

package/docs/server.entity.startmodelloopedanimations.md

@@ -53,5 +53,5 @@ void
 
 ## Remarks
 
-This method will be ignored and do nothing if the entity is a block entity.
+\*\*Deduplication:\*\* If an animation is already in the looped set, it won't be re-added or restarted. The event only emits if at least one new animation is added.
 

package/docs/server.entity.startmodeloneshotanimations.md

@@ -53,5 +53,7 @@ void
 
 ## Remarks
 
-This method will be ignored and do nothing if the entity is a block entity.
+\*\*No deduplication:\*\* Unlike `startModelLoopedAnimations`<!-- -->, this always emits the event even if the animation is already playing. This allows restarting oneshot animations.
+
+\*\*Tracking:\*\* Oneshot animations are tracked internally to prevent packet spam from `stopModelAnimations()` but are not serialized for new player joins (they're transient).
 

package/docs/server.entity.stopallmodelanimations.md

@@ -4,7 +4,7 @@
 
 ## Entity.stopAllModelAnimations() method
 
-Stops all looped and oneshot animations for the entity, optionally excluded the provided animations from stopping.
+Stops all looped and oneshot animations for the entity, optionally excluding the provided animations from stopping.
 
 **Signature:**
 
@@ -51,3 +51,7 @@ _(Optional)_ The animations to exclude from being stopped.
 
 void
 
+## Remarks
+
+\*\*Delegates to `stopModelAnimations`<!-- -->:\*\* Collects animations from both looped and oneshot sets (minus exclusions), then calls `stopModelAnimations()` once.
+

package/docs/server.entity.stopmodelanimations.md

@@ -53,5 +53,5 @@ void
 
 ## Remarks
 
-This method will be ignored and do nothing if the entity is a block entity.
+\*\*Removes from both sets:\*\* Stops animations from both looped and oneshot tracking sets.
 

package/docs/server.entitymanager.getentitychildren.md

@@ -51,5 +51,9 @@ The entity to get the children for.
 
 [Entity](./server.entity.md)<!-- -->\[\]
 
-All child entities of the entity.
+All direct child entities of the entity.
+
+## Remarks
+
+\*\*Direct children only:\*\* Returns only immediate children, not recursive descendants.
 

package/docs/server.entitymanager.getplayerentitiesbyplayer.md

@@ -4,7 +4,7 @@
 
 ## EntityManager.getPlayerEntitiesByPlayer() method
 
-Gets all spawned entities in the world assigned to the provided player.
+Gets all spawned player entities in the world assigned to the provided player.
 
 **Signature:**
 
@@ -51,5 +51,5 @@ The player to get the entities for.
 
 [PlayerEntity](./server.playerentity.md)<!-- -->\[\]
 
-All spawned entities in the world assigned to the player.
+All spawned player entities in the world assigned to the player.
 

package/docs/server.entitymanager.md

@@ -206,7 +206,7 @@ Gets all child entities of an entity.
 
 </td><td>
 
-Gets all spawned entities in the world assigned to the provided player.
+Gets all spawned player entities in the world assigned to the provided player.
 
 
 </td></tr>

package/docs/server.particleemitter.setattachedtoentity.md

@@ -51,3 +51,7 @@ The entity to attach the ParticleEmitter to.
 
 void
 
+## Remarks
+
+Clears any set position (mutual exclusivity).
+

package/docs/server.particleemitter.spawn.md

@@ -51,3 +51,7 @@ The world to spawn the ParticleEmitter in.
 
 void
 
+## Remarks
+
+\*\*Requires spawned entity:\*\* If attached to an entity, the entity must be spawned first.
+

package/docs/server.pathfindingentitycontroller.md

@@ -17,6 +17,10 @@ export default class PathfindingEntityController extends SimpleEntityController
 
 This class implements pathfinding using the A\* algorithm. Pathfinding when frequently called can cause performance issues, use it sparingly. The .pathfind() method should only need to be called once in nearly all cases when attempting to move an entity to a target coordinate.
 
+<h2>Coordinate System &amp; Model Orientation</h2>
+
+HYTOPIA uses \*\*-Z as forward\*\*. Models must be authored with their front facing -Z. The pathfinding controller automatically calls `face()` to orient the entity's -Z axis toward each waypoint as it moves.
+
 ## Constructors
 
 <table><thead><tr><th>

package/docs/server.pathfindingentitycontroller.pathfind.md

@@ -58,7 +58,7 @@ number
 
 </td><td>
 
-The speed of the entity.
+The speed of the entity (blocks per second).
 
 
 </td></tr>
@@ -83,5 +83,17 @@ _(Optional)_ The pathfinding options.
 
 boolean
 
-Whether the path was found.
+Whether a path was found.
+
+## Remarks
+
+\*\*Synchronous return:\*\* Path calculation happens synchronously. Returns `true` if a path was found, `false` if no path exists or calculation was aborted.
+
+\*\*Auto-starts movement:\*\* If a path is found, movement begins immediately using the inherited `move()`<!-- -->, `face()`<!-- -->, and `jump()` methods from `SimpleEntityController`<!-- -->.
+
+\*\*Auto-facing (-Z forward):\*\* Automatically calls `face()` for each waypoint, orienting the entity's -Z axis toward the next waypoint. Models must be authored with their front facing -Z.
+
+\*\*A\* algorithm:\*\* Uses A\* pathfinding with configurable `maxJump`<!-- -->, `maxFall`<!-- -->, and `verticalPenalty`<!-- -->. Path calculation is capped by `maxOpenSetIterations` (default 200) to prevent blocking.
+
+\*\*Waypoint progression:\*\* Entity moves through calculated waypoints sequentially. Each waypoint has a timeout (`waypointTimeoutMs`<!-- -->) after which it's skipped if not reached.