PBZModLoader 脚本加载器封面

PBZModLoader 脚本加载器

影之刃零
工具与前置

MOD介绍

交流QQ群:1130285067

1.0.2 — 日志保留次数 / Log retention
默认保留最近 10 次普通运行(含本次)。在 mods.ini 的 Loader 配置节设置 LogRetentionRuns,重启后生效。设为 0 时停止写入加载器日志并保留已有记录。带验证文件的目录单独保留。升级时退出游戏,替换当前使用的代理 DLL、运行脚本和随包编译器,保留 mods.ini 与 mods/。
The loader keeps the latest 10 ordinary runs, including the current run. Set LogRetentionRuns in the Loader section of mods.ini and restart. Set it to 0 to disable loader logs and keep existing records. Verification directories are preserved separately. To upgrade, exit the game, update your active proxy DLL, runtime scripts and bundled compiler, and keep mods.ini and mods/.

1.0.1 — Log rotation / 日志轮转
加载器日志按 8 MiB 分段;默认总预算为 2 GiB,优先清理最旧的加载器日志。在 mods.ini  的 Loader 配置节中设置 LogDirectoryLimitMiB(120–4096 MiB),重启生效。
升级:退出游戏,只替换已选入口 DLL,并更新运行脚本和随包编译器。保留 mods.ini 和 mods/;旧配置无需修改,开发模板无需更新。
Loader logs rotate in 8 MiB segments. The default budget is 2 GiB; the oldest loader logs are pruned first. Set LogDirectoryLimitMiB (120–4096 MiB) under Loader section in mods.ini and restart to apply.
To upgrade, exit the game, replace only your selected proxy DLL, and update the runtime scripts and bundled compiler. Keep mods.ini and mods/. Existing configs and the dev template need no changes.

1.0.0 — Stable release / 正式版
The 1.0.0 package promotes the 0.3.7-preview packaging to a stable release and retains the 0.3.6 DLL. Steam and WeGame default DLL paths are included. WeGame has been tested in-game: loader startup and MOD execution work. The optional development template is 0.2.0 with SDK 0.3.3.
1.0.0 将 0.3.7-preview 的打包内容转为正式发布,沿用 0.3.6 DLL;包含 Steam / WeGame 默认入口。WeGame 平台已实测可用,加载器自动加载与 MOD 运行已确认。开发模板为 0.2.0,SDK 为 0.3.3。升级前备份配置和 MOD,只安装一个代理 DLL。

PBZModLoader
An unofficial JavaScript and TypeScript mod loader for Phantom Blade Zero, using the game's PuerTS runtime. This is a modding framework; install compatible mods separately.

0.3.6-preview — November 4 game update fix / 11 月 4 日更新兼容修复
Fixes MOD loading and interrupted game/menu initialization after the November 4, 2026 Steam update. This release updates MainStart matching and adapts the new script-content checks for loader-owned files that match their local contents. Original game scripts retain their original validation.
Steam startup logs confirm original MainStart returned and mod-demo loaded successfully (loaded=1, failed=0). Automated native, signature, JavaScript and five-proxy tests passed. Full gameplay and map transitions are not covered by these automated checks. WeGame loader startup and MOD execution have since been verified in-game.
Upgrade: Exit the game and back up your configuration. Replace your selected proxy DLL and update the supplied runtime files, including bootstrap.js and manager.js. Preserve ProjectPBZ/PBZModLoader/mods.ini and mods/. If you previously disabled the loader for diagnosis, set Enabled=1 under [Loader]. Do not use the withdrawn 0.3.5-preview build.
修复本次 Steam 更新后 MOD 不加载及游戏菜单初始化异常。升级前退出游戏,更新当前使用的 DLL 和运行文件,保留 mods.ini 与 mods 文件夹;若排查时关闭了加载器,请将 [Loader] 下 Enabled 恢复为 1。0.3.5-preview 已撤回,请使用 1.0.2。

Recommended: develop your mods with an AI Agent
Have an idea but no programming experience? You can get started with an AI coding agent and the included TypeScript development template. Describe the feature you want in plain language, and let the agent help you read the SDK, write code, build the mod and work through errors. PBZModLoader provides the runtime; the optional template provides a practical starting point for turning an idea into a working mod.

1. Download the Optional TypeScript development template and open the extracted folder in your AI coding tool.
2. Ask the agent to read README.md, vendor/game-api/README.md, src/main.ts and the SDK declarations before making changes.
3. Describe one small, specific feature. Ask the agent to check whether the required game APIs exist and explain any unverified assumptions instead of inventing APIs.
4. Let the agent help install development dependencies, run npm run check and npm run build, and explain where to copy the resulting mod folder.
5. Test in the game, then share the observed behavior and relevant log lines with the agent to improve the mod step by step. Use Alt+F5 for supported hot reload and preserve stop() cleanup.

No prior coding experience is required to start learning this workflow. What you can build depends on the game's available APIs and the feature's complexity. AI-generated code still needs type checking and in-game testing; a successful build alone does not prove a mod works. AI tools are optional development helpers and are not bundled with or required to run this loader.

Starter prompt
I am new to programming and want to build a Phantom Blade Zero mod with PBZModLoader. Read this template's README, SDK documentation and example entry first. Help me implement this feature: [describe your idea]. Check the available APIs, identify anything that needs in-game verification, and start with the smallest working version. Preserve stop() cleanup, run the type check and build, and explain installation and testing step by step. Do not invent game APIs or assume Node.js APIs exist inside the game.
推荐使用 AI Agent 辅助开发:零编程经验也能开始
即使没有编程经验,也可以借助 AI 编程 Agent 和随附的 TypeScript 开发模板,尝试把自己的想法做成可运行的 MOD。用自然语言描述你希望实现的功能,让 AI 帮助阅读 SDK、编写代码、编译构建和分析错误;PBZModLoader 负责在游戏中加载运行你的 MOD。
下载 Optional 开发模板,用 AI 编程工具打开模板文件夹,先让它阅读 README、SDK 说明和 src/main.ts,再从一个简单、明确的功能开始。完成 npm run check 和 npm run build 后,将产物安装进游戏,结合实际效果和日志逐步修改。支持热重载的 MOD 可用 Alt+F5 调试,并应保留 stop() 清理逻辑。
不需要先成为程序员才能开始,但具体功能能否实现取决于游戏开放的 API 和需求复杂度。AI 可能生成错误代码或不存在的接口,因此仍需类型检查和游戏实测。AI 工具是可选的开发辅助,并非加载器内置功能,玩家运行 MOD 时无需使用 AI。

可直接复制给 AI 的提示词
我没有编程经验,想用 PBZModLoader 开发影之刃零 MOD。请先阅读这个模板的 README、SDK 文档和示例入口,帮助我实现:[填写你的功能想法]。先确认可用 API,列出需要游戏内验证的部分,从最小可用版本开始。保留 stop() 资源清理,执行类型检查和构建,并一步步解释安装和测试方法。不要编造游戏 API,也不要假设游戏中存在 Node.js API。
Features
• Automatically discovers mods//main.ts or main.js (TypeScript takes priority).
• Bundled native TypeScript compiler: players do not need Node.js, npm or an additional compiler.
• Enable or disable individual mods through mods.ini.
• Alt+F5 hot reload with cleanup callbacks and on-screen success, failure or skipped status.
• The main runtime archive does not include example mods; install compatible mods separately. An optional TypeScript development template includes game API SDK 0.3.3.

Compatibility and requirements
Windows x64 and a legitimate installation of Phantom Blade Zero. Stable release 1.0.2. Supports the original Steam signature layout and the November 4, 2026 update; future game updates may require an updated loader. Unmatched or ambiguous signatures cause the loader to skip mods.
WeGame has been tested on an actual installation; loader startup and MOD execution work. No other Nexus mod is required for the loader itself.

Installation — manual
1. Exit the game. Open the game root folder (the folder containing ProjectPBZ).
2. Extract the main ZIP directly into that folder, merging ProjectPBZ and platform. Do not add an extra PBZModLoader parent folder.
3. Confirm version.dll is beside the actual game executable, not a launcher. The archive includes platform/steam/version.dll and platform/wegame/version.dll. WeGame loader startup and MOD execution have been verified in-game.
4. Start the game from your normal platform client.
Back up your mods and configuration before updating. Do not overwrite another tool's version.dll. Update the DLL, bootstrap.js, manager.js and bundled compiler together, preserving your own mods.ini and mods.
Older installs using ProjectPBZ/Mods/PBZModLoader must move their configuration and mods to ProjectPBZ/PBZModLoader and update the DLL.

Alternative DLL entries
Default: version.dll. Dedicated alternatives are supplied in 备用入口/: hid.dll, winmm.dll, dsound.dll and dxgi.dll. Install ONLY ONE loader DLL beside the actual game EXE and keep its original filename. If version.dll belongs to another mod, merge ProjectPBZ only and choose an unused alternative; do not overwrite the other mod. When switching, remove only this loader's previous entry. Do not rename version.dll to create an alternative.

Installing and managing mods
Put each mod folder in ProjectPBZ/PBZModLoader/mods, for example mods/my-mod/main.js. Use letters, numbers, underscores or hyphens for the folder name. Do not install an extra dist folder.
New mods are discovered automatically. Under [Mods] in ProjectPBZ/PBZModLoader/mods.ini, set my-mod=0 to disable a mod; remove the entry or use my-mod=1 to enable it. To disable the loader, set Enabled=0 under [Loader] and restart.

Hot reload — Alt+F5
Save changes in the installed mod folder, switch to the game and press Alt+F5. Locally built mods must first be copied into the installed folder. Reloading applies to the entire mod group, including additions, removals and [Mods] switches. The hotkey only responds while the game is in the foreground; files are not watched automatically.
Mods must export stop() to clear timers, unsubscribe events and release resources. Async cleanup is supported and awaited. Missing or failed cleanup keeps the old instance and skips replacement. A stop() that never finishes blocks subsequent reloads. Map changes and game exit do not automatically invoke stop().
TypeScript compilation failure keeps the old instance during reload. Fix it and retry. If entry execution fails, restart the game after fixing it to avoid duplicate partial initialization. Startup compilation transpiles syntax only; it does not perform full type checking or use a mod's tsconfig.json.

For developers
Download the Optional file “PBZModLoader TS Dev Template - SDK 0.3.3” and extract it into a development workspace, not the game folder. Node.js and npm are required on the development PC.
Run npm ci, npm run check, then npm run build. Edit src/main.ts and copy dist/my-mod into ProjectPBZ/PBZModLoader/mods. Read the included README and SDK documentation for API limitations and hot-reload cleanup.
The SDK supplies UE/PuerTS type declarations, not runtime code. Generated declarations do not mean every API has been tested. The game supplies the ue and puerts modules; do not run mod entry files directly with Node.js.

Troubleshooting and uninstall
Loader log: ProjectPBZ/PBZModLoader/evidence//loader.log. TypeScript diagnostics also appear in compile.log inside the relevant generated mod cache.
generated-mods and generated-reloads under ProjectPBZ/Content/JavaScript/PBZModLoader are automatic caches. Do not edit them or delete them while the game runs. Restarting clears/rebuilds caches.
To uninstall: exit the game, back up your mods and settings, then remove only this loader's selected proxy DLL, ProjectPBZ/PBZModLoader and ProjectPBZ/Content/JavaScript/PBZModLoader. Do not delete the game's entire Content/JavaScript folder or another tool's DLL.
When reporting an issue, include your game build, platform, loader version, reproduction steps and relevant log lines, after removing any personal paths or information.

Credits
PBZModLoader by LLKKFF. Uses the game's PuerTS runtime and bundles the TypeScript compiler; third-party notices and licenses are included in the download. Unofficial community project, not affiliated with or endorsed by the game's developers.

中文安装提示
退出游戏后,将主文件 ZIP 解压到含 ProjectPBZ 的游戏根目录。确认 version.dll 位于实际游戏 EXE 旁;安装包同时包含 platform/steam 和 platform/wegame 的默认入口。更新前备份自己的配置和 MOD,不要覆盖其他工具的同名 DLL。
MOD 放入 ProjectPBZ/PBZModLoader/mods//,支持 main.ts 或 main.js。游戏前台按 Alt+F5 热重载;MOD 必须导出 stop() 清理资源。玩家无需安装 Node.js。开发模板为可选文件,需要在开发电脑安装 Node.js 和 npm。详细中文说明见压缩包中的安装说明和模板 README。
当前为 1.0.2 正式版,WeGame 自动加载及 MOD 运行已通过实机验证。