hytopia 0.8.6-devtrace-1 → 0.8.6-devtrace-allocs

package/server.d.ts

@@ -5,13 +5,20 @@ import http from 'http';
 import type { IncomingMessage } from 'http';
 import type { InputSchema } from '@hytopia.com/server-protocol';
 import type { LobbyMembershipDto } from '@hytopia.com/creative-lib/dist/impl/getSession';
-import mediasoup from 'mediasoup';
 import protocol from '@hytopia.com/server-protocol';
 import RAPIER from '@dimforge/rapier3d-simd-compat';
 import { SdpMatrix3 } from '@dimforge/rapier3d-simd-compat';
+import * as Sentry from '@sentry/node';
 import type { Socket } from 'net';
+import type { types } from 'mediasoup';
 import { WebSocket as WebSocket_2 } from 'ws';
 
+/** A 3-element number array. @public */
+export declare type Array3Number = [number, number, number];
+
+/** A 4-element number array. @public */
+export declare type Array4Number = [number, number, number, number];
+
 /**
  * Represents a audio playback in a world.
  *
@@ -272,28 +279,40 @@ export declare class AudioManager {
     /**
      * Retrieves all loaded audio instances for the world.
      *
+     * @param tickAllocated - If true, uses the tick allocator and frees
+     * the allocated array at the end of the current tick. false by default.
+     *
      * @returns An array of audio instances.
      */
-    getAllAudios(): Audio[];
+    getAllAudios(tickAllocated?: boolean): Audio[];
     /**
      * Retrieves all loaded audio instances attached to a specific entity.
      *
      * @param entity - The entity to get attached audio instances for.
+     * @param tickAllocated - If true, uses the tick allocator and frees
+     * the allocated array at the end of the current tick. false by default.
+
      * @returns An array of audio instances.
      */
-    getAllEntityAttachedAudios(entity: Entity): Audio[];
+    getAllEntityAttachedAudios(entity: Entity, tickAllocated?: boolean): Audio[];
     /**
      * Retrieves all looped audio instances for the world.
      *
+     * @param tickAllocated - If true, uses the tick allocator and frees
+     * the allocated array at the end of the current tick. false by default.
+     *
      * @returns An array of audio instances.
      */
-    getAllLoopedAudios(): Audio[];
+    getAllLoopedAudios(tickAllocated?: boolean): Audio[];
     /**
      * Retrieves all oneshot (non-looped) audio instances for the world.
      *
+     * @param tickAllocated - If true, uses the tick allocator and frees
+     * the allocated array at the end of the current tick. false by default.
+     *
      * @returns An array of audio instances.
      */
-    getAllOneshotAudios(): Audio[];
+    getAllOneshotAudios(tickAllocated?: boolean): Audio[];
 
     /**
      * Unregisters and stops an audio instance from the audio manager.
@@ -603,14 +622,17 @@ export declare class BlockType extends EventRouter implements protocol.Serializa
 
 
 
+
     /**
      * Creates a new block type instance.
      * @param world - The world the block type is for.
      * @param options - The options for the block type.
      */
-    constructor(options?: BlockTypeOptions);
+    constructor(blockTypeRegistry: BlockTypeRegistry, options?: BlockTypeOptions);
     /** The unique identifier for the block type. */
     get id(): number;
+    /** The block type registry that the block type belongs to. */
+    get blockTypeRegistry(): BlockTypeRegistry;
     /** The collider options for the block type. */
     get colliderOptions(): VoxelsColliderOptions;
     /** The half extents size of the block type. */
@@ -702,9 +724,15 @@ export declare class BlockTypeRegistry extends EventRouter implements protocol.S
     get world(): World;
     /**
      * Get all registered block types.
+     *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of BlockType instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns An array of all registered block types.
      */
-    getAllBlockTypes(): BlockType[];
+    getAllBlockTypes(tickAllocated?: boolean): BlockType[];
     /**
      * Get a registered block type by its id.
      * @param id - The id of the block type to get.
@@ -862,12 +890,15 @@ export declare class ChatManager extends EventRouter {
 export declare class Chunk implements protocol.Serializable {
 
 
+
     /**
      * Creates a new chunk instance.
      */
-    constructor(originCoordinate: Vector3Like);
+    constructor(chunkLattice: ChunkLattice, originCoordinate: Vector3Like);
     /** The blocks in the chunk as a flat Uint8Array[4096], each index as 0 or a block type id. */
     get blocks(): Readonly<Uint8Array>;
+    /** The chunk lattice that the chunk belongs to. */
+    get chunkLattice(): ChunkLattice;
     /** The origin coordinate of the chunk. */
     get originCoordinate(): Vector3Like;
     /**
@@ -928,6 +959,8 @@ export declare class ChunkLattice extends EventRouter {
     constructor(world: World);
     /** The number of chunks in the lattice. */
     get chunkCount(): number;
+    /** The world that the chunk lattice belongs to. */
+    get world(): World;
     /**
      * Removes and clears all chunks and their blocks from the lattice.
      */
@@ -966,9 +999,15 @@ export declare class ChunkLattice extends EventRouter {
     getOrCreateChunk(globalCoordinate: Vector3Like): Chunk;
     /**
      * Get all chunks in the lattice.
+     *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of Chunk instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns An array of all chunks in the lattice.
      */
-    getAllChunks(): Chunk[];
+    getAllChunks(tickAllocated?: boolean): Chunk[];
     /**
      * Check if a block exists at a specific global coordinate.
      * @param globalCoordinate - The global coordinate of the block to check.
@@ -995,12 +1034,18 @@ export declare class ChunkLattice extends EventRouter {
 
 /** Event types a ChunkLattice instance can emit. See {@link ChunkLatticeEventPayloads} for the payloads. @public */
 export declare enum ChunkLatticeEvent {
+    ADD_CHUNK = "CHUNK_LATTICE.ADD_CHUNK",
     REMOVE_CHUNK = "CHUNK_LATTICE.REMOVE_CHUNK",
     SET_BLOCK = "CHUNK_LATTICE.SET_BLOCK"
 }
 
 /** Event payloads for ChunkLattice emitted events. @public */
 export declare interface ChunkLatticeEventPayloads {
+    /** Emitted when a chunk is added to the lattice. */
+    [ChunkLatticeEvent.ADD_CHUNK]: {
+        chunkLattice: ChunkLattice;
+        chunk: Chunk;
+    };
     /** Emitted when a chunk is removed from the lattice. */
     [ChunkLatticeEvent.REMOVE_CHUNK]: {
         chunkLattice: ChunkLattice;
@@ -2108,9 +2153,15 @@ export declare class EntityManager {
 
     /**
      * Gets all spawned entities in the world.
+     *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of Entity instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns All spawned entities in the world.
      */
-    getAllEntities(): Entity[];
+    getAllEntities(tickAllocated?: boolean): Entity[];
     /**
      * Gets all spawned player entities in the world.
      * @returns All spawned player entities in the world.
@@ -2760,9 +2811,14 @@ export declare class LightManager {
     /**
      * Retrieves all spawned Light instances for the world.
      *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of Light instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns An array of Light instances.
      */
-    getAllLights(): Light[];
+    getAllLights(tickAllocated?: boolean): Light[];
     /**
      * Retrieves all spawned Light instances attached to a specific entity.
      *
@@ -3861,6 +3917,12 @@ export declare class ParticleEmitter extends EventRouter implements protocol.Ser
      * @param velocityVariance - The velocity variance of an emitted particle.
      */
     setVelocityVariance(velocityVariance: Vector3Like): void;
+    /**
+     * Creates a burst of particles, regardless of pause state.
+     *
+     * @param count - The number of particles to burst.
+     */
+    burst(count: number): void;
     /**
      * Despawns the ParticleEmitter from the world.
      */
@@ -3884,6 +3946,7 @@ export declare class ParticleEmitter extends EventRouter implements protocol.Ser
 
 /** Event types a ParticleEmitter instance can emit. See {@link ParticleEmitterEventPayloads} @public */
 export declare enum ParticleEmitterEvent {
+    BURST = "PARTICLE_EMITTER.BURST",
     DESPAWN = "PARTICLE_EMITTER.DESPAWN",
     SET_ALPHA_TEST = "PARTICLE_EMITTER.SET_ALPHA_TEST",
     SET_ATTACHED_TO_ENTITY = "PARTICLE_EMITTER.SET_ATTACHED_TO_ENTITY",
@@ -3919,6 +3982,11 @@ export declare enum ParticleEmitterEvent {
 
 /** Event payloads for ParticleEmitter emitted events. @public */
 export declare interface ParticleEmitterEventPayloads {
+    /** Emitted when a ParticleEmitter bursts the specified number of particles. */
+    [ParticleEmitterEvent.BURST]: {
+        particleEmitter: ParticleEmitter;
+        count: number;
+    };
     /** Emitted when a ParticleEmitter is despawned. */
     [ParticleEmitterEvent.DESPAWN]: {
         particleEmitter: ParticleEmitter;
@@ -4096,9 +4164,14 @@ export declare class ParticleEmitterManager {
     /**
      * Retrieves all spawned ParticleEmitter instances for the world.
      *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of ParticleEmitter instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns An array of ParticleEmitter instances.
      */
-    getAllParticleEmitters(): ParticleEmitter[];
+    getAllParticleEmitters(tickAllocated?: boolean): ParticleEmitter[];
     /**
      * Retrieves all spawned ParticleEmitter instances attached to a specific entity.
      *
@@ -5192,7 +5265,7 @@ export declare type RaycastOptions = {
     solidMode?: boolean;
 } & FilterOptions;
 
-/** A RGB color. @public */
+/** A RGB color. r, g and b expect a value between 0 and 255. @public */
 export declare interface RgbColor {
     r: number;
     g: number;
@@ -5729,9 +5802,14 @@ export declare class SceneUIManager {
     /**
      * Retrieves all loaded SceneUI instances for the world.
      *
+     * @param tickAllocated - Whether to use the tick allocator to allocate the
+     * returned array of SceneUI instances. The allocated array will be collected
+     * and released at the end of the current tick if true. Only use this if
+     * you know what you're doing.
+     *
      * @returns An array of SceneUI instances.
      */
-    getAllSceneUIs(): SceneUI[];
+    getAllSceneUIs(tickAllocated?: boolean): SceneUI[];
     /**
      * Retrieves all loaded SceneUI instances attached to a specific entity.
      *
@@ -6071,6 +6149,221 @@ export declare function startServer(init: ((() => void) | ((world: World) => voi
 /** The input keys that are included in the PlayerInput. @public */
 export declare const SUPPORTED_INPUT_KEYS: readonly ["w", "a", "s", "d", "sp", "sh", "tb", "ml", "mr", "q", "e", "r", "f", "z", "x", "c", "v", "u", "i", "o", "j", "k", "l", "n", "m", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0"];
 
+/**
+ * Manages performance telemetry and error tracking through your Sentry.io account.
+ *
+ * @remarks
+ * The Telemetry class provides low-overhead performance monitoring
+ * and error tracking through Sentry (https://sentry.io) integration
+ * and your provided Sentry DSN. It automatically tracks critical game loop
+ * operations like physics simulation, entity updates, network synchronization,
+ * and more. The system only sends telemetry data when errors or slow-tick
+ * performance issues are detected, minimizing bandwidth and storage costs.
+ *
+ * @example
+ * ```typescript
+ * // Initialize Sentry for production telemetry
+ * Telemetry.initializeSentry('MY_SENTRY_PROJECT_DSN');
+ *
+ * // Wrap performance-critical code in spans
+ * Telemetry.startSpan({
+ *   operation: TelemetrySpanOperation.CUSTOM_OPERATION,
+ *   attributes: { // any arbitrary attributes you want to attach to the span
+ *     playerCount: world.playerManager.connectedPlayers.length,
+ *     entityCount: world.entityManager.entityCount,
+ *   },
+ * }, () => {
+ *   // Your performance-critical code here
+ *   performExpensiveOperation();
+ * });
+ *
+ * // Get current process statistics
+ * const stats = Telemetry.getProcessStats();
+ * console.log(`Heap usage: ${stats.jsHeapUsagePercent * 100}%`);
+ * ```
+ *
+ * @public
+ */
+export declare class Telemetry {
+    /**
+     * Gets current process memory and performance statistics.
+     *
+     * @param asMeasurement - Whether to return data in Sentry measurement format with units.
+     * @returns Process statistics including heap usage, RSS memory, and capacity metrics.
+     */
+    static getProcessStats(asMeasurement?: boolean): Record<string, any>;
+    /**
+     * Initializes Sentry telemetry with the provided DSN.
+     *
+     * @remarks
+     * This method configures Sentry for error tracking and performance monitoring.
+     * It sets up filtering to only send performance spans that exceed the
+     * provided threshold duration, reducing noise and costs. The initialization
+     * includes game-specific tags and process statistics attachment.
+     *
+     * @param sentryDsn - The Sentry Data Source Name (DSN) for your project.
+     * @param tickTimeMsThreshold - The tick duration that must be exceeded to
+     * send a performance span to Sentry for a given tick. Defaults to 50ms.
+     */
+    static initializeSentry(sentryDsn: string, tickTimeMsThreshold?: number): void;
+    /**
+     * Executes a callback function within a performance monitoring span.
+     *
+     * @remarks
+     * This method provides zero-overhead performance monitoring in development
+     * environments. In production with Sentry enabled and `SENTRY_ENABLE_TRACING=true`,
+     * it creates performance spans for monitoring. The span data is only transmitted
+     * to Sentry when performance issues are detected.
+     *
+     * @param options - Configuration for the telemetry span including operation type and attributes.
+     * @param callback - The function to execute within the performance span.
+     * @returns The return value of the callback function.
+     *
+     * @example
+     * ```typescript
+     * const result = Telemetry.startSpan({
+     *   operation: TelemetrySpanOperation.ENTITIES_TICK,
+     *   attributes: {
+     *     entityCount: entities.length,
+     *     worldId: world.id,
+     *   },
+     * }, () => {
+     *   return processEntities(entities);
+     * });
+     * ```
+     */
+    static startSpan<T>(options: TelemetrySpanOptions, callback: (span?: Sentry.Span) => T): T;
+    /**
+     * Gets the Sentry SDK instance for advanced telemetry operations.
+     *
+     * @remarks
+     * This method provides direct access to the Sentry SDK for operations
+     * not covered by the Telemetry wrapper, such as custom error reporting,
+     * user context setting, or advanced span manipulation.
+     *
+     * @returns The Sentry SDK instance.
+     */
+    static sentry(): typeof Sentry;
+}
+
+/** Performance telemetry span operation types. @public */
+export declare enum TelemetrySpanOperation {
+    BUILD_PACKETS = "build_packets",
+    ENTITIES_EMIT_UPDATES = "entities_emit_updates",
+    ENTITIES_TICK = "entities_tick",
+    NETWORK_SYNCHRONIZE = "network_synchronize",
+    NETWORK_SYNCHRONIZE_CLEANUP = "network_synchronize_cleanup",
+    PHYSICS_CLEANUP = "physics_cleanup",
+    PHYSICS_STEP = "physics_step",
+    RELEASE_TICK_ALLOCATION = "release_tick_allocation",
+    SEND_ALL_PACKETS = "send_all_packets",
+    SEND_PACKETS = "send_packets",
+    SERIALIZE_FREE_BUFFERS = "serialize_free_buffers",
+    SERIALIZE_PACKETS = "serialize_packets",
+    SERIALIZE_PACKETS_ENCODE = "serialize_packets_encode",
+    SIMULATION_STEP = "simulation_step",
+    TICKER_TICK = "ticker_tick",
+    WORLD_TICK = "world_tick"
+}
+
+/** Options for creating a telemetry span. @public */
+export declare type TelemetrySpanOptions = {
+    /** The operation being measured. */
+    operation: TelemetrySpanOperation | string;
+    /** Additional attributes to attach to the span for context. */
+    attributes?: Record<string, string | number>;
+};
+
+/**
+ * High-performance tick-scoped allocator for temporary objects, arrays, and buffers.
+ * All allocations are automatically bulk-released when reset() is called.
+ *
+ * @remarks
+ * TickAllocator maintains separate pools for different data types and tracks all
+ * allocations made during a tick cycle. Objects are reused across ticks to eliminate
+ * garbage collection overhead in hot paths like network synchronization.
+ *
+ * @example
+ * ```typescript
+ * // Allocate during tick
+ * const position = tickAllocator.getArray3Number();
+ * const rotation = tickAllocator.getArray4Number();
+ * const data = tickAllocator.getObject<EntitySchema>();
+ *
+ * // At end of tick - bulk release everything
+ * tickAllocator.reset();
+ * ```
+ *
+ * @public
+ */
+export declare class TickAllocator {
+
+
+
+
+
+
+
+
+
+
+    /**
+     * Filters an array using a callback function.
+     * @typeParam T - The type of the array.
+     * @param array - The array to filter.
+     * @param callback - The callback function to filter the array.
+     * @returns A new array with the filtered values.
+     */
+    filter<T>(array: T[], callback: (value: T, index: number, array: T[]) => boolean): T[];
+    /**
+     * Gets a generic array from the pool.
+     * Array is reset to empty state and ready for use.
+     * @typeParam T - The array type.
+     * @returns A reusable array.
+     */
+    getArray<T extends unknown[] = unknown[]>(copyFromA?: Iterable<unknown>, copyFromB?: Iterable<unknown>): T;
+    /**
+     * Gets a 3-element number array from the pool.
+     * Array is reset to [0, 0, 0] and ready for use.
+     * @returns A reusable 3-element array.
+     */
+    getArray3Number(copyFrom?: Array3Number | Set<number>): Array3Number;
+    /**
+     * Gets a 4-element number array from the pool.
+     * Array is reset to [0, 0, 0, 0] and ready for use.
+     * @returns A reusable 4-element array.
+     */
+    getArray4Number(copyFrom?: Array4Number | Set<number>): Array4Number;
+    /**
+     * Gets a plain object from the pool.
+     * Object is reset to empty state and ready for use.
+     * @typeParam T - The type interface for the object.
+     * @returns A reusable plain object.
+     */
+    getObject<T extends Record<string, unknown> = Record<string, unknown>>(copyFromA?: T, copyFromB?: T): T;
+    /**
+     * Gets a set from the pool.
+     * Set is reset to empty state and ready for use.
+     * @typeParam T - The type of the set.
+     * @returns A reusable set.
+     */
+    getSet<T>(copyFromA?: Set<T> | T[], copyFromB?: Set<T> | T[]): Set<T>;
+    /**
+     * Maps an array to a new array using a callback function.
+     * @typeParam T - The type of the array.
+     * @typeParam U - The type of the resulting array.
+     * @param array - The array to map.
+     * @param callback - The callback function to map the array.
+     * @returns A new array with the mapped values.
+     */
+    map<T, U>(array: T[], callback: (value: T, index: number, array: T[]) => U): U[];
+    /**
+     * Releases all allocated objects back to their respective pools.
+     * This is intended to be called at the end of a tick.
+     */
+    reset(): void;
+}
+
 /** The options for a trimesh collider. @public */
 export declare interface TrimeshColliderOptions extends BaseColliderOptions {
     shape: ColliderShape.TRIMESH;
@@ -6685,6 +6978,7 @@ export declare class World extends EventRouter implements protocol.Serializable
 
 
 
+
 
 
     /**
@@ -6697,40 +6991,32 @@ export declare class World extends EventRouter implements protocol.Serializable
     get ambientLightColor(): RgbColor;
     /** The intensity of the ambient light. */
     get ambientLightIntensity(): number;
+    /** The block type registry for the world. */
+    get blockTypeRegistry(): BlockTypeRegistry;
+    /** The chat manager for the world. */
+    get chatManager(): ChatManager;
+    /** The chunk lattice for the world. */
+    get chunkLattice(): ChunkLattice;
     /** The color of the directional light. */
     get directionalLightColor(): RgbColor;
     /** The intensity of the directional light. */
     get directionalLightIntensity(): number;
     /** The position the directional light originates from. */
     get directionalLightPosition(): Vector3Like;
+    /** The entity manager for the world. */
+    get entityManager(): EntityManager;
     /** The color of the fog, if not explicitly set, defaults to ambient light color. */
     get fogColor(): RgbColor | undefined;
     /** The maximum distance from the camera at which fog stops being applied. */
     get fogFar(): number;
     /** The minimum distance from the camera to start applying fog. */
     get fogNear(): number;
-    /** The name of the world. */
-    get name(): string;
-    /** The intensity of the world's skybox brightness. */
-    get skyboxIntensity(): number;
-    /** The URI of the skybox cubemap for the world. */
-    get skyboxUri(): string;
-    /** The audio manager for the world. */
-    get audioManager(): AudioManager;
-    /** An arbitrary identifier tag of the world. Useful for your own logic. */
-    get tag(): string | undefined;
-    /** The block type registry for the world. */
-    get blockTypeRegistry(): BlockTypeRegistry;
-    /** The chat manager for the world. */
-    get chatManager(): ChatManager;
-    /** The chunk lattice for the world. */
-    get chunkLattice(): ChunkLattice;
-    /** The entity manager for the world. */
-    get entityManager(): EntityManager;
     /** The light manager for the world. */
     get lightManager(): LightManager;
     /** The world loop for the world. */
     get loop(): WorldLoop;
+    /** The name of the world. */
+    get name(): string;
 
     /** The particle emitter manager for the world. */
     get particleEmitterManager(): ParticleEmitterManager;
@@ -6738,6 +7024,16 @@ export declare class World extends EventRouter implements protocol.Serializable
     get sceneUIManager(): SceneUIManager;
     /** The simulation for the world. */
     get simulation(): Simulation;
+    /** The intensity of the world's skybox brightness. */
+    get skyboxIntensity(): number;
+    /** The URI of the skybox cubemap for the world. */
+    get skyboxUri(): string;
+    /** The audio manager for the world. */
+    get audioManager(): AudioManager;
+    /** An arbitrary identifier tag of the world. Useful for your own logic. */
+    get tag(): string | undefined;
+    /** The tick allocator for the world. */
+    get tickAllocator(): TickAllocator;
     /**
      * Loads a map into the world, clearing any prior map.
      * @param map - The map to load.