Alec 的遥测数据！/模组统计

Alec's Telemetry & ModStats.io

Alec's Telemetry 是 Hytale 模组的一体化遥测解决方案：包含一个在游戏中运行的运行时、一个面向模组作者的网页门户、一个公开模组统计列表，以及一个帮助玩家按模组查找已验证服务器的服务器浏览器。

它最初用于崩溃报告，但现在已涵盖围绕模组的更广泛支持循环：归因崩溃、结构化错误、生命周期和性能事件、匿名使用统计、玩家手动问题报告、项目访问、摄取密钥以及基于门户的分类。

打开遥测门户 | 查看公开统计 | 浏览服务器 | 加入 Discord

组合解决方案

Alec's Telemetry 以组合形式工作效果最佳：

• 运行时发现启用了遥测的模组，应用同意和服务器所有者覆盖，本地排队报告，并上传清理后的数据包
• 网页门户负责管理项目、密钥、成员资格、问题、手动报告、统计、服务器配置文件、公开可见性和操作工作流

大多数模组应使用网页门户。如果你需要将数据发送到自己的后端，相同的运行时也可以改为定位自定义端点。

处理内容

• 崩溃和启动失败捕获：归因堆栈跟踪、指纹、面包屑、本地排队和托管问题分组。
• 结构化运行时事件：显式错误、生命周期计时、性能测量、功能使用事件和经过描述符验证的事件上下文。
• 公开使用统计：聚合的活动服务器、活动玩家、环境细分、版本、已加载模组，以及通过 ModStats.io 提供的公开嵌入卡片。
• 服务器浏览器：服务器所有者可以发布经过验证的公开服务器列表，控制公开玩家数量、公开模组列表和加入信息，并显示运行某个公开模组的服务器。
• 手动玩家报告：游戏内问题和建议表单，附带本地回执、可选的日志附件、服务器所有者审查控制和门户跟进。
• 运行时协调：独立和嵌入的副本参与版本选举，使一个活动运行时可以为所有启用的项目提供服务。
• 同意和覆盖：描述符默认值为首次运行的同意界面提供初始数据，而服务器所有者通过运行时设置和每个项目的覆盖保持最终控制权。

适用对象

Alec's Telemetry 旨在惠及 Hytale 模组生态中的每个人。

对于模组作者，Alec's Telemetry 将现实世界的支持信号转变为一个小型、可重复的集成：提供一个描述符，添加一个门户项目密钥，让运行时和门户处理管道工作。

对于服务器所有者，它使遥测保持可见和可控。崩溃捕获、使用事件、性能遥测、统计、面包屑和报告是单独的类别，并具有运行时级别的控制。服务器所有者还可以在安装 Alec's Telemetry 后列出公开服务器，而无需创建模组项目。

对于玩家和社区，它缩短了从“出问题了”到真正修复的路径，同时公开统计可以在不暴露原始服务器或玩家数据的情况下，显示模组是否被积极使用。

模组作者快速设置

大多数网页门户集成从以下位置的描述符开始：

Server/Telemetry/project.json

如果你的 manifest.json 已经具有正确的 Group、Name 和 Main，Alec's Telemetry 可以推断出项目 ID、显示名称、插件标识符和包前缀。

这个最小描述符将你的打包模组或资源包连接到门户项目。它本身不会启用任何遥测类别。

{
  "hosted": {
    "projectKey": "replace_with_your_public_project_key"
  }
}

门户的 projectKey 值是可发布的摄取密钥。它们应放在描述符内分发；管理能力保留在门户中，而非密钥中。

只添加你的项目实际支持的遥测类别。例如，仅统计项目添加：

{
  "hosted": {
    "projectKey": "replace_with_your_public_project_key"
  },
  "telemetry": {
    "stats": {
      "supported": true
    }
  }
}

如果你希望在同意界面中显示模组标志，请将纹理打包到 Common/UI/Custom/... 目录下，并将 ui.iconTexturePath 设置为该自定义 UI 纹理路径。根模组图标（例如 icon-256.png）不会自动使用。

服务器所有者快速设置

你无需创建模组项目即可将你的服务器列在 ModStats 服务器浏览器中。

1. 在 Hytale 服务器上安装 Alec's Telemetry。
2. 至少启动服务器一次。
3. 打开门户并创建一个服务器配置文件。
4. 运行门户显示的验证命令：

/telemetry server verify <claim-token>

门户使用该声明心跳将公开服务器配置文件绑定到该服务器。服务器所有者控制列表、玩家数量、模组列表和加入信息是否公开。

运行时选项

独立依赖

当你希望使用标准依赖模型时，请使用独立的 Alec's Telemetry 模组。运行时从已安装的模组中发现启用的项目描述符，并协调这些项目的上传。

如果你的模组需要独立运行时，请在 manifest.json 中以及在 CurseForge、Modtale 和 Modifold 等分发平台上将 Alechilles:Alec's Telemetry! 设置为必需的依赖。仅当你的模组在没有安装遥测时仍能正常工作时，才使用可选的依赖。

嵌入运行时

当你的模组需要直接捆绑遥测引导程序时，请使用嵌入模式。嵌入的副本仍会参与协调器选举，并且最新的兼容运行时可以为所有已安装的启用项目提供服务。

自定义端点

当你希望使用运行时但不想使用 Alec 的网页门户时，请使用自定义端点。

{
  "defaults": {
    "destinationMode": "custom"
  },
  "customEndpoint": {
    "url": "https://example.com/api/telemetry/crash",
    "eventUrl": "https://example.com/api/telemetry/event"
  }
}

服务器所有者还可以在运行时覆盖打包的目标设置，位置如下：

mods/Alechilles_Alec's Telemetry!/Settings/projects/<project-id>.json

网页门户

网页门户是 Alec's Telemetry 项目和已验证服务器列表的管理界面。

• 使用 Discord 或 GitHub 登录。
• 管理项目成员资格和可发布的项目密钥。
• 审查崩溃组、产生问题的事件以及单个事件实例。
• 检查手动玩家报告，并将其链接或提升到问题工作流中。
• 查看公开和仅限门户的统计仪表板。
• 配置公开统计可见性和 ModStats.io 别名。
• 创建已验证的服务器配置文件并管理公开服务器列表设置。
• 当你的团队需要时，配置 Discord 路由和 GitHub 问题同步。

门户 URL：

https://telemetry.alecsmods.com/portal

公开统计：

https://www.modstats.io/stats/alecs-telemetry

服务器浏览器：

https://www.modstats.io/servers

运行时 API

模组可以仅使用描述符，但更丰富的集成可以调用运行时 API 来获取显式事件和自定义玩家报告入口点。

TelemetryRuntimeApi api = TelemetryRuntimeLocator.tryGet();
if (api == null || !api.isEnabled()) {
    return;
}

TelemetryProjectHandle project = api.findProject("example-consumer-mod");
if (project == null || !project.isEnabled()) {
    return;
}

project.recordPerformanceWithContext(
        "reload_config_duration",
        durationMs,
        null,
        TelemetryEventContext.performance()
                .subsystem("config")
                .phase("reload")
                .operation("apply")
                .runtimeSide("server")
                .detail("configFileCount", configFileCount)
                .build()
);

运行时忽略因同意、描述符默认值、运行时覆盖、采样或描述符允许列表而禁用的事件。

有用的命令

/telemetry status
/telemetry projects
/telemetry project <project-id>
/telemetry consent
/telemetry report [project-id] [issue|suggestion]
/telemetry reports pending
/telemetry reports submitted
/telemetry server verify <claim-token>
/telemetry flush [project-id]
/telemetry test <project-id> [detail]

根命令权限是 telemetry.command.telemetry；子命令使用相同的稳定前缀 telemetry.command.telemetry.*。

隐私模型

• 服务器所有者通过同意和运行时覆盖控制遥测类别。
• 公开统计暴露聚合计数和细分，而非原始服务器 ID、会话 ID、IP 地址、玩家名称、玩家 UUID、聊天内容、坐标、秘密或完整的配置文件。
• 自定义事件上下文字段必须在描述符中声明，并在上传前进行类型检查。
• 手动报告可以要求在上传前进行本地操作员审查，可选的附件由运行时设置控制。

有关完整的运行时、网页门户和 ModStats.io 策略，请参阅 Alec's Telemetry 隐私政策。

文档和示例

• 项目描述符参考
• 嵌入模式指南
• 运行时 API 指南
• 命令参考
• 运行时覆盖
• 隐私政策
• 手动玩家报告
• 使用统计指南
• 公开维基
• 项目密钥操作
• 摄取合约
• 服务器浏览器指南
• 示例消费者模组
• 嵌入消费者模组

许可 / 支持

本项目源代码在 Alec's Telemetry 运行时许可下可用。

• 许可
• 许可常见问题解答
• 商业许可
• Discord 支持和问题报告