模组安装与格式

.tnmod 容器的导入方式、目录结构与安全限额。 · UPDATED 2026-11-08

ON THIS PAGE

1. 安装方式 2. 目录结构 3. tnmod.json 关键字段 4. 安全限额 5. 启用 / 禁用 / 卸载 6. 模组类型

1. 安装方式

推荐：管理器内导入 .tnmod。

把 .tnmod 文件传到手机（下载目录即可）；
管理器 →「导入模组」→ 选择文件；
管理器先校验容器，再解包到模组根目录的一个子目录；
勾选启用后，启动游戏生效。

也可以手动放入目录（适合开发者调试）：

/sdcard/Android/data/com.terranova.loader/files/tnl_mods/<目录名>/

<目录名> 只是目录名、不参与校验；管理器导入时默认使用 tnmod.json 的 id。

2. 目录结构

一个已解包的模组目录：

<目录名>/
  tnmod.json         必需，<= 512 KiB
  scripts/           必需（JS 模组：main.js 入口）
  assets/            可选
  localization/      可选
  icon.png           可选
  banner.png         可选

.tnmod 只是传输容器：管理器解包后，运行时只扫描解包目录，不直接挂载 ZIP。

3. tnmod.json 关键字段

字段	说明
`format`	固定 `tnmod`
`formatVersion`	目前只支持 `1`
`apiVersion`	目前只支持 `1`
`id`	全局唯一，形如 `author.mod`；存档/禁用列表/安装目录都依赖它
`name` / `version`	显示名与版本
`entry`	入口：JS 模组写 `scripts/main.js`；C# 模组写 `.cs` 入口源文件
`targetGame`	目标游戏版本约束，可写 `*` 或 `{"minVersionCode":301720,"maxVersionCode":301729}`
`dependencies`	依赖的模组 id，缺失/循环会被禁用
`permissions`	声明式权限（`content.register`、`assets.read`、`localization.read`、`log` 等）
`capabilities`	引擎能力；未知能力会让模组被禁用（fail-closed）

宿主常量：游戏包名 com.and.games505.Terraria、版本 1.4.5.8.6、versionCode 301729。目标版本不匹配时，模组会被安全禁用而不是猜测加载。

4. 安全限额

.tnmod 文件 ≤ 128 MiB；
解包后总大小 ≤ 64 MiB；
单条目解压 ≤ 16 MiB；ZIP 条目数 ≤ 4096；
路径穿越、符号链接、超大条目等坏包会被拒绝导入。

5. 启用 / 禁用 / 卸载

管理器内可单独启停模组；禁用列表记录在模组根目录的 .tnmod_disabled；
删除模组 = 删除对应 tnl_mods/<目录名>；
更新模组：重新导入新版本（同 id）后覆盖安装，模组数据不自动迁移。

6. 模组类型

类型	说明
`mod`	内容模组（JS 或 C#），可注册物品/弹幕/图块等
`texture`	材质包（替换纹理资源，不执行脚本）
`font`	字体包

导入时根据 tnmod.json 与目录内容判定类型；类型与内容不符会被拒绝。