hytopia 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hytopia",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "The HYTOPIA SDK makes it easy for developers to create massively multiplayer games using JavaScript or TypeScript.",
   "type": "module",
   "main": "./node-server.mjs",

package/server.api.json

@@ -48902,6 +48902,662 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Class",
+          "canonicalReference": "server!Telemetry:class",
+          "docComment": "/**\n * Manages performance telemetry and error tracking through your Sentry.io account.\n *\n * @remarks\n *\n * 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.\n *\n * @example\n * ```typescript\n * // Initialize Sentry for production telemetry\n * Telemetry.initializeSentry('MY_SENTRY_PROJECT_DSN');\n *\n * // Wrap performance-critical code in spans\n * Telemetry.startSpan({\n *   operation: TelemetrySpanOperation.CUSTOM_OPERATION,\n *   attributes: { // any arbitrary attributes you want to attach to the span\n *     playerCount: world.playerManager.connectedPlayers.length,\n *     entityCount: world.entityManager.entityCount,\n *   },\n * }, () => {\n *   // Your performance-critical code here\n *   performExpensiveOperation();\n * });\n *\n * // Get current process statistics\n * const stats = Telemetry.getProcessStats();\n * console.log(`Heap usage: ${stats.jsHeapUsagePercent * 100}%`);\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export default class Telemetry "
+            }
+          ],
+          "fileUrlPath": "src/metrics/Telemetry.ts",
+          "releaseTag": "Public",
+          "isAbstract": false,
+          "name": "Telemetry",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Method",
+              "canonicalReference": "server!Telemetry.getProcessStats:member(1)",
+              "docComment": "/**\n * Gets current process memory and performance statistics.\n *\n * @param asMeasurement - Whether to return data in Sentry measurement format with units.\n *\n * @returns Process statistics including heap usage, RSS memory, and capacity metrics.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static getProcessStats(asMeasurement?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Record",
+                  "canonicalReference": "!Record:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<string, any>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 5
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "asMeasurement",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": true
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getProcessStats"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "server!Telemetry.initializeSentry:member(1)",
+              "docComment": "/**\n * Initializes Sentry telemetry with the provided DSN.\n *\n * @remarks\n *\n * 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.\n *\n * @param sentryDsn - The Sentry Data Source Name (DSN) for your project.\n *\n * @param tickTimeMsThreshold - The tick duration that must be exceeded to send a performance span to Sentry for a given tick. Defaults to 50ms.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static initializeSentry(sentryDsn: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", tickTimeMsThreshold?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "sentryDsn",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "tickTimeMsThreshold",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": true
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "initializeSentry"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "server!Telemetry.sentry:member(1)",
+              "docComment": "/**\n * Gets the Sentry SDK instance for advanced telemetry operations.\n *\n * @remarks\n *\n * 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.\n *\n * @returns The Sentry SDK instance.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static sentry(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "typeof "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Sentry",
+                  "canonicalReference": "server!~Sentry"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "sentry"
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "server!Telemetry.startSpan:member(1)",
+              "docComment": "/**\n * Executes a callback function within a performance monitoring span.\n *\n * @remarks\n *\n * 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.\n *\n * @param options - Configuration for the telemetry span including operation type and attributes.\n *\n * @param callback - The function to execute within the performance span.\n *\n * @returns The return value of the callback function.\n *\n * @example\n * ```typescript\n * const result = Telemetry.startSpan({\n *   operation: TelemetrySpanOperation.ENTITIES_TICK,\n *   attributes: {\n *     entityCount: entities.length,\n *     worldId: world.id,\n *   },\n * }, () => {\n *   return processEntities(entities);\n * });\n * ```\n *\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static startSpan<T>(options: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TelemetrySpanOptions",
+                  "canonicalReference": "server!TelemetrySpanOptions:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", callback: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(span?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Sentry.Span",
+                  "canonicalReference": "@sentry/core!Span:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ") => T"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "T"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "typeParameters": [
+                {
+                  "typeParameterName": "T",
+                  "constraintTokenRange": {
+                    "startIndex": 0,
+                    "endIndex": 0
+                  },
+                  "defaultTypeTokenRange": {
+                    "startIndex": 0,
+                    "endIndex": 0
+                  }
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 7,
+                "endIndex": 8
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "options",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "callback",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "startSpan"
+            }
+          ],
+          "implementsTokenRanges": []
+        },
+        {
+          "kind": "Enum",
+          "canonicalReference": "server!TelemetrySpanOperation:enum",
+          "docComment": "/**\n * Performance telemetry span operation types.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare enum TelemetrySpanOperation "
+            }
+          ],
+          "fileUrlPath": "src/metrics/Telemetry.ts",
+          "releaseTag": "Public",
+          "name": "TelemetrySpanOperation",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.BUILD_PACKETS:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "BUILD_PACKETS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"build_packets\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "BUILD_PACKETS"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.ENTITIES_EMIT_UPDATES:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "ENTITIES_EMIT_UPDATES = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"entities_emit_updates\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "ENTITIES_EMIT_UPDATES"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.ENTITIES_TICK:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "ENTITIES_TICK = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"entities_tick\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "ENTITIES_TICK"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.NETWORK_SYNCHRONIZE:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "NETWORK_SYNCHRONIZE = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"network_synchronize\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "NETWORK_SYNCHRONIZE"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.NETWORK_SYNCHRONIZE_CLEANUP:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "NETWORK_SYNCHRONIZE_CLEANUP = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"network_synchronize_cleanup\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "NETWORK_SYNCHRONIZE_CLEANUP"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.PHYSICS_CLEANUP:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "PHYSICS_CLEANUP = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"physics_cleanup\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "PHYSICS_CLEANUP"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.PHYSICS_STEP:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "PHYSICS_STEP = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"physics_step\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "PHYSICS_STEP"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.RELEASE_TICK_ALLOCATION:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "RELEASE_TICK_ALLOCATION = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"release_tick_allocation\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "RELEASE_TICK_ALLOCATION"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SEND_ALL_PACKETS:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SEND_ALL_PACKETS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"send_all_packets\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SEND_ALL_PACKETS"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SEND_PACKETS:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SEND_PACKETS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"send_packets\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SEND_PACKETS"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SERIALIZE_FREE_BUFFERS:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SERIALIZE_FREE_BUFFERS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"serialize_free_buffers\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SERIALIZE_FREE_BUFFERS"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SERIALIZE_PACKETS:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SERIALIZE_PACKETS = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"serialize_packets\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SERIALIZE_PACKETS"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SERIALIZE_PACKETS_ENCODE:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SERIALIZE_PACKETS_ENCODE = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"serialize_packets_encode\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SERIALIZE_PACKETS_ENCODE"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.SIMULATION_STEP:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "SIMULATION_STEP = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"simulation_step\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "SIMULATION_STEP"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.TICKER_TICK:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "TICKER_TICK = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"ticker_tick\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "TICKER_TICK"
+            },
+            {
+              "kind": "EnumMember",
+              "canonicalReference": "server!TelemetrySpanOperation.WORLD_TICK:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "WORLD_TICK = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"world_tick\""
+                }
+              ],
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "name": "WORLD_TICK"
+            }
+          ]
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "server!TelemetrySpanOptions:type",
+          "docComment": "/**\n * Options for creating a telemetry span.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type TelemetrySpanOptions = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    operation: "
+            },
+            {
+              "kind": "Reference",
+              "text": "TelemetrySpanOperation",
+              "canonicalReference": "server!TelemetrySpanOperation:enum"
+            },
+            {
+              "kind": "Content",
+              "text": " | string;\n    attributes?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Record",
+              "canonicalReference": "!Record:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<string, string | number>;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/metrics/Telemetry.ts",
+          "releaseTag": "Public",
+          "name": "TelemetrySpanOptions",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
         {
           "kind": "Class",
           "canonicalReference": "server!TickAllocator:class",