TerraNova Loader运行时能力与边界
TN 的原则：能真实接管的才声称支持；不能接管的显式 fail-closed，不静默降级。 本文给出当前版本的能力面与已知边界，便于你在选用/移植模组时判断。
1. 已接管的运行时能力
| 能力 | 说明 |
|---|---|
| 内容注册 | 物品、Buff、弹幕、图块、墙壁、Dust、NPC、TileEntity 等注册链 |
| 世界生成 | 真实 GenPass 管线：ModifyWorldGenTasks、RunPass 权重回写、Hardmode 转换、Tile 清理保留箱子 |
| 生物群系 / 场景 | ModBiome、SceneEffect、BossBar 的注册与切换 |
| TileEntity | 受管实体的注册、放置、查找、持久化 sidecar |
| 音乐 / 音效 | 加载器音乐槽位与播放循环、音效表桥接 |
| 配置 | ModConfig 头less 注册与序列化（配置 UI 逐步完善） |
| 本地化 | .hjson 加载与回退 |
| 资产 | 内容纹理 budget + 占位降级 + lean 解码 + 查询缓存 |
| 内容系统扩展 | 护甲/饰品/坐骑/宠物/召唤物/弹药等更多内容基类的注册与自动加载 |
| 图格对象 | 多格结构 / 图格实体的对象检查与受控放置辅助 |
| 掉落规则与条件 | NPC/物品掉落规则与条件在托管侧求值，条件不满足时按原版回退 |
| 屏幕效果 | ScreenApi：受控的屏幕震动/着色等效果请求（不越权改渲染管线） |
| 音频桥 | 音效/音乐事件到托管侧的桥接与播放控制 |
| 委托桥 | 模组回调可安全桥接为游戏事件委托；入口缺失时记录并跳过（fail-closed） |
2. 资产预算（移动端关键）
大型模组的纹理按 RGBA 展开后可能超过手机可用内存。TN 采用：
- 硬预算：内容资产不超过配置上限；
- 分档降级：超出预算时按优先级保留，其余使用占位纹理并记录日志；
- lean 解码：解码时避免中间副本；
- 查询缓存：同一纹理的
assetOf结果缓存，降低重复开销。
降级不会导致崩溃，但会影响观感；日志中会出现 content budget: degraded=… 行。
3. fail-closed 边界
以下行为在移动端无法与桌面版完全等价，当前显式禁用并记录原因，而不是模拟：
- 部分需要原生渲染/音频批处理的管线（如自定义云绘制、部分 UI 图层插入、部分音频提交）；
- 某些依赖桌面版资源加载器的路径（缺失纹理时走占位与警告）；
- 移动端 struct 化的游戏对象在特定空值语义下的边界（大型模组若触发，会在编译/加载期给出明确错误）。
每个 fail-closed 点都会在 boot.log 留下可检索的记录（关键字 fail-closed / deferred / unsupported）。
4. 诊断
| 手段 | 用法 |
|---|---|
boot.log | 两个进程共用；proc= 区分 :main / :game |
| 管理器日志页 | 检索 TN mod loaded / TN mod rejected / budget 等关键字 |
| 错误卡片 | 启动失败时管理器直接显示失败阶段与原因 |
5. 性能建议
- 内容贴图尽量使用与游戏一致的尺寸与格式；
- 大世界 + 大量内容模组时，关注启动日志中的资产预算行；
- 测试构建的性能数据仅代表当次设备，正式评估以 release 通道为准。