先说清楚:这不是玩法插件,也没有游戏内界面
很多人第一次看到它会以为漏装了什么东西——因为玩家在游戏里完全感知不到它存在,没有任何面板、没有快捷键、没有聊天框提示。它做的事全部发生在服务端和内存里。
它真正的身份是底层图片库。所有写着 [PluginReference] Plugin ImageLibrary 的插件都靠它取图:抽奖转盘的券、商城的商品图、签到面板的礼盒、交易市场的分类图标,追到底都是从这里拿 CRC。
所以判断它有没有在工作,不看游戏里,看两处:控制台敲一条命令,或者看日志里下游插件有没有报「素材已注册」。这篇里所有截图位置都用真实回话代替,你可以直接对照自己的日志。
三条加速路线,逐条说清楚
一、本地图标包:零网络,秒级
把 png 直接放进 oxide/data/ImageLibrary/icons,文件名就是图片名(wood.png 或 wood_0.png 都认)。启动时分帧批量注册,每帧处理固定张数,不卡主线程。
这条路最快也最稳:不经过任何网络,服务器断网、CDN 挂掉、镜像换域名都不影响。一次放好,以后每次重启都是秒级重建。
二、国内镜像并发:一次拿不到就换下一张
配置里填一个国内可达的镜像根地址,插件按物品短名拼出 <镜像根>/<shortname>.png 去拉。默认 8 路并发(官方是串行 1 路),一张挂了不影响其余七张。
三、快速失败:超时就跳过,绝不让队列卡住
单张图超时默认 10 秒,超时立刻放弃并重试一次(可调),仍然失败就写进缺失清单,下次启动不再白跑一趟。这是和官方版差别最大的地方——官方版一张图卡住,后面整队都得等。
| 对比项 | 官方版 | 国内加速版 |
|---|---|---|
| 图片源 | GitHub Raw + 国外 CDN | 本地包 / 你自己的国内镜像 |
| 下载方式 | 串行 1 路 | 8 路并发(可调) |
| 单张超时 | 默认较长,卡住就卡住 | 10 秒即跳过 |
| 失败重试 | 按默认策略 | 有限次 + 退避,超限入缺失清单 |
| 对外 API | ImageLibrary 标准 API | 同名同签名,完全一致 |
兼容性:为什么说「一行代码都不用改」
插件内部名还是 ImageLibrary,方法名、参数顺序、返回值全部照官方。依赖它的插件走的是 Plugin ImageLibrary 反射查找,名字对上了就直接调用,不需要改任何东西。
| 对外方法 | 用途 | 兼容 |
|---|---|---|
| AddImage | 给某个物品注册一张网络图片 | 一致 |
| AddImageData | 直接喂字节数组(内嵌素材) | 一致 |
| GetImage | 取图片 CRC 给 CUI 用 | 一致 |
| HasImage | 判断某张图是否已就绪 | 一致 |
| GetImageURL | 取原始 URL(可再分享) | 一致 |
| LoadImageList | 批量加载一整组图 | 一致 |
数据文件也同名:image_data.json、image_urls.json、missing.json。也就是说可以把原来的 .cs 直接换掉,已有的图片缓存全部沿用,不用重新下拉。
七条管理命令
全部在服务器控制台或 RCON 执行,玩家在 F1 里敲不出效果(有权限闸门)。
| 命令 | 作用 |
|---|---|
| ilstats | 看已缓存张数、待下载、下载中、授权状态、镜像地址、本地目录是否存在 |
| ilmirror <地址> | 设置国内镜像根地址,改完立刻生效 |
| ilicons | 按游戏内物品表批量拉取全部图标 |
| illocal | 把本地图标目录里的 png 当场注册一遍,不用重启 |
| ilreset | 清空缺失清单,让之前没拉到的图下次重新试 |
| imagelibrary.auth | 不带参数看授权状态;带授权码则写入并联网校验 |
| imagelibrary.deauth | 注销,清掉本地凭据与配置里的码 |
配置项
配置在 oxide/config/ImageLibrary.json,键名全中文。改完 reload 生效。
| 配置项 | 默认 | 说明 |
|---|---|---|
| 物品图标镜像根地址 | 空 | 填你自己的国内 CDN/COS 根地址,末尾带斜杠;留空则只用本地包 |
| 本地图标目录 | ImageLibrary/icons | 相对 oxide/data/ 的路径 |
| 并发下载路数 | 8 | 官方是串行 1 路;带宽差可以调到 3~4 |
| 单张下载超时秒数 | 10 | 超时立刻跳过,不卡整个队列 |
| 单张失败最大重试次数 | 1 | 超过就入缺失清单 |
| 启动时自动注册本地图标包 | 开 | 建议保持开启 |
| 启动时自动从镜像拉取 | 开 | 填了镜像就自动跑,不用每次敲 ilicons |
| 管理员直接可用 | 开 | admin 组与 RCON 免额外授权即可执行管理命令 |
| 本地注册每帧处理张数 | 20 | 大图标包怕卡顿就调小 |
| 输出详细日志 | 开 | 排障期开,稳定后可关 |
装好之后长什么样
下面是真实服务器 reload 后的回话,你可以拿自己的日志对照。
ImageLibrary was compiled successfully in 797ms [ImageLibrary] [授权] 已授权,本地凭据有效期至 2026-11-15 05:14 [ImageLibrary] 本地图标包注册完成 80 张(共 1482 张) [每日签到 LoginRewards] 面板素材已注册 8/8 [交易商城 TradeCenter] 内嵌素材已注册 2 张 [福利中心 GiftCenter] 内嵌素材已注册 24 张 Loaded plugin ImageLibrary v2.0.69 by biubr.com
敲 ilstats 得到四行:
[ImageLibrary] 已缓存图片 1482 张 | 待下载 0 张 | 下载中 0 张 | 工作协程 0 [ImageLibrary] 授权状态:已授权(国内镜像 + 自动预载生效) 码:PL-XXXX-****-XXXX [ImageLibrary] 图标镜像:https://你的镜像根地址/ [ImageLibrary] 本地图标目录:ImageLibrary/icons(存在)
如果某个普通玩家硬在 F1 里敲管理命令,会被明确挡下来(同时日志留一条审计):
13:16:24 > ilstats 13:16:24 没有权限:本命令仅限管理员(权限 imagelibrary.admin) 05:16 [Warning] [ImageLibrary] [权限] 拒绝 某玩家(SteamID 已隐去) 执行 ilstats(权限 imagelibrary.admin)
实测数据
| 项目 | 结果 |
|---|---|
| 编译耗时 | 约 0.8 秒,0 warning 0 error |
| 本地图标包规模 | 1376 张 png / 44 MB |
| 注册到缓存的张数 | 累计 1482 张 |
| 注册命令耗时 | 132 毫秒(分帧,不卡帧) |
| 并发下载 | 8 路 |
| 下游插件注册 | 签到 8/8、商城 2 张、福利 24 张,全部成功 |
安装与激活
- 把
ImageLibrary.cs放进oxide/plugins/,控制台oxide.reload ImageLibrary。原有的image_data.json会被自动沿用,不需要重新拉图。 - 填授权码:
imagelibrary.auth PL-XXXX-XXXX-XXXX。校验通过后会自动续期,本地凭据默认有 3 天离线宽限,断网期间照常工作。 - 配镜像:
ilmirror https://你的镜像根地址/。根目录下按<shortname>.png摆图即可。 - 批量拉取:
ilicons,然后用ilstats看进度。全部到齐后,把整套图标打包放进本地目录,以后重启就是纯离线。
几点需要提前知道的
- 它是替身,不是增强包。覆盖安装会取代官方版,不能两个共存。
- 未授权时不是「等同官方」,而是「镜像与预载都停用」。已缓存的图照常可用,缺的图要等授权后才补,文案里不会含糊过去。
- 管理命令默认 admin 组可用,RCON 永远可用。要让非 admin 的号也能用,执行
oxide.grant user <steamid> imagelibrary.admin。 - 镜像里的图统一是短名。拿不准某个物品的短名,可以先
ilreset再ilicons,从日志看它拼出来的 URL。









