Unity 全局中枢配置 (FastTMASettings)

FastTMA Suite 的全局配置中枢，通过 Tools → FastTMA → Settings 或 Edit → Project Settings → FastTMA 访问。所有字段持久化为 ProjectSettings/FastTMASettings.asset 单一 ScriptableObject 资源。

---

访问路径

方式	路径
Unity 菜单	Tools → FastTMA → Settings
项目设置窗口	Edit → Project Settings → FastTMA

---

三大核心字段技术规格

Telegram Pay Url

• 作用域： Stars 虚拟币支付中继入口。玩家发起 Stars 购买时，运行时读取此 URL，并通过 Telegram.WebApp.openTelegramLink() 在 Telegram WebView 中打开。
• 校验规则：
  • 必须以 https:// 开头 — http:// 与裸域名均被拒绝。
  • 严禁末尾带尾斜杠 /。 尾斜杠会导致 Telegram SDK 对路径段进行双重 URL 编码，使支付网关收到 404 响应。
• 行为说明： 若当前游戏不涉及 Stars 虚拟币购买，该字段可留空。它对其他所有模块（用户画像、触觉反馈、云端存档等）无任何影响。

WARNING

在误触发支付流程时，此字段留空将静默吞掉支付意图——不会抛异常，但购买行为被丢弃。在接入 Stars 购买功能后务必核查此字段。

---

Enable Eruda Console

• 作用域： 移动真机浮动调试面板，提供 Console（控制台）、Network（网络）、Elements（元素） 三个 Tab，底层由构建时注入的 Eruda 库驱动。

• 行为说明： 勾选此复选框后，后处理构建步骤会将 Eruda 代码片段注入 index.html，真机调试运行时自动出现调试齿轮。

• 正式发版卫生规范：

  阶段	Eruda Console	处置方式
  真机联调	✅ 勾选	齿轮可见，完整控制台输出
  内测 / TestFlight	❌ 取消勾选	齿轮隐藏，无 Eruda 残留
  商店正式版	❌ 取消勾选	干净构建，零 Eruda 痕迹

  后处理构建步骤在资源生成阶段对 index.html 执行严格的正则清理。取消勾选即保证彻底移除，无需手动修改文件。

---

Auto Optimize Compression

• 作用域： WebGL IL2CPP 编译管线启动前立即执行的前置自愈阶段。

• 核心价值： 默认保持勾选。自动完成以下两项操作：

  1. WebGL 压缩 → Disabled（禁用）
     在 Unity Player Settings 层级禁用 gzip / Brotli 压缩，防止 Unity 输出 Build.framework.js.br 或 .gz 文件时，静态托管（如 Cloudflare Pages、Vercel、GitHub Pages）未对资源设置正确的 Content-Encoding: br 响应头，导致浏览器将压缩字节误认为明文文本，从而引发首次加载时的白屏/黑屏死锁。

  2. Data Caching → Enabled（启用）
     激活 Application.SetConsoleFlag("webgl_defer_compilation") 等效行为，指示浏览器先将 WebGL 框架完整缓存，待全部二进制就绪后再执行，从根本上消除加载抖动。

• 何时取消勾选： 仅在你使用自建服务器端 Brotli 管线时（例如 Nginx 配置了 brotli_types，或 CDN 提供透明 Accept-Encoding: br 直通），且确认托管层对所有资源均正确设置 Content-Encoding: br 时方可关闭。

---

资产自愈机制与连通性验证

Create / Rebuild Settings Asset

此按钮确保 ProjectSettings/FastTMASettings.asset ScriptableObject 始终存在。在以下场景点击：

• 资源文件被误删。
• 在新机器上全新克隆仓库。
• Inspector 显示 No FastTMASettings found in ProjectSettings/。

点击 Create 以所有字段默认值写入新资源。点击 Rebuild 用当前 Inspector 显示的值覆盖现有资源，作为手动重置手段。

---

Apply 按钮 — 2 秒硬超时预检探测

点击 Apply 后，设置管线在将值提交到 ScriptableObject 之前执行以下序列：

1. 超时门控： 立即启动 2 秒硬计时器。
2. HTTP 探测： 对当前 Telegram Pay Url（若非空）发起 HEAD 请求。
3. 结果矩阵：

探测结果	是否超时	Asset Status 状态指示	提交行为
2xx OK	否	🟢 Valid	立即提交
3xx / 4xx / 5xx	否	🟡 Reachable / Warn	提交并输出控制台警告
网络错误 / DNS 失败	否	🔴 Unreachable	拒绝提交；错误写入 Assets/FastTMA/Editor/SettingsReport.txt
响应超时	是	⚠️ Timeout	中止提交；弹出"网络不可达——请检查防火墙/代理"对话框

2 秒超时策略刻意设计得激进，以防止构建农场运行时，在移动热点连接下 Apply 按钮无限阻塞。

---

Asset Status 状态机

[No Asset] --Create--> [Default] --Apply--> [Pending Probe]
                                              |
                            ┌─────────────────┼─────────────────┐
                            ▼                 ▼                 ▼
                         [Valid]    [Reachable / Warn]   [Unreachable]
                            │                 │                 │
                            └────────[Asset Saved]←─────────────┘
                                              |
                                         [Ready]

状态	说明
No Asset	资源文件缺失；Inspector 显示"Not found"横幅。
Default	资源存在；所有字段为默认值；从未点击 Apply。
Pending Probe	已点击 Apply；2 秒探测进行中。
Valid	探测返回 2xx；设置已提交。
Reachable / Warn	探测返回非 2xx；已提交但带警告。
Unreachable	探测失败；拒绝提交；错误已记录。
Ready	磁盘上资源与上次提交状态一致。

---

实战建议

将 Auto Optimize Compression（已启用）与 Cloudflare Pages 的 Pages → Settings → Build configuration → Build → Data Caching 联合使用，可将 Telegram Mini App 受众在 4G 网络下的 WebGL 首次加载时间压至最低。