Iw4x Toolkit

iw4x工具包

IW4X/MW2模块的Claude Code插件。IWD归档工具、GSC linting和格式化、DVAR知识库和用于模块移植的符号分析。

它做什么

IWD归档工具 --IWD档案中的手术现场编辑(iwd_patch, iwd_grep, iwd_write, iwd_rename, iwd_copy, iwd_extract)加上跨多个存档的差异、元数据和符号索引。

GSC语言工具 — gsc_lint 捕获未定义的变量、缺失的包含、无法访问的代码、无限循环、大括号不匹配和不区分大小写的名称冲突。 gsc_format 规范缩进、大括号样式和运算符间距。 gsc_find_orphans 在游戏启动之前识别无法解析的函数调用。

DVAR知识库 --1731 MW2 DVAR，包括类型、默认值、类别和FPS影响评级。 dvar_search 过滤服务器端以避免上下文泛滥。 dvar_integrity_check 根据数据库验证GSC中的DVAR名称文字。

安装

从内部克劳德代码：

/plugin marketplace add back1ply/iw4x-toolkit

然后安装插件：

/plugin install iw4x-toolkit

从源头构建

如果你克隆了仓库并想重建MCP服务器：

cd mcp-server
npm install
npm run build
npm test

需要Node.js 18+和TypeScript 5.7+。

• IWD工具: iwd_list, iwd_read, iwd_write, iwd_patch, iwd_grep, iwd_diff, iwd_rename, iwd_copy, iwd_extract, iwd_info, iwd_remove, iwd_index_symbols
• GSC工具: gsc_lint, gsc_format, gsc_find_orphans, gsc_lookup, gsc_template, gsc_outline, gsc_menu_hud
• DVAR工具: dvar_search, dvar_integrity_check
• 资源: iw4x://dvars, iw4x://gsc-builtins
• 技能: dvar-lookup FPS优化提示

文档

• 工作流.md：带有“黄金之路”和示例的使用指南。
• 策略.md：项目愿景，包括“混合”传统/现代工作流程。
• TODO.md路线图和当前任务。
• MCP_IMPROVEMENTS.md：从实际建模会话中提出的MCP工具增强功能。
• LINTER_ERRORS.md：GSC门楣错误代码参考。
• SOURCES.md：参考文献和研究。

API 文档

API文档是用TypeDoc生成的。生成：

cd mcp-server
npm run docs

查看生成的文档 docs/api/index.html.

贡献

看 贡献.md 用于开发设置、代码风格指南和拉取请求流程。

快速开始

检查IWD内容

iwd_list path="mods/promod.iwd" summary_only=true

搜索脚本

iwd_grep path="mods/promod.iwd" pattern="onPlayerConnect" entry_glob="*.gsc"

有关更多示例，请参见 工作流.md.

实现细节

• ZIP操作：用途 adm-zip 用于所有IWD读/写/删除。缓存限制为3个并发存档，以防止V8内存膨胀。
• 原子写入：写入内容通过管道传输到 .tmp 首先是文件，然后异步重命名为目标，以防止失败时损坏，同时保持事件循环畅通。
• 自动备份：关于会议中对任何IWD的第一次修改，a .bak 创建副本（仅当副本不存在时）。
• 二进制检测：已知的二进制扩展名（.iwi、.d3dbsp等）以base64而不是UTF-8返回。
• CRC差异: iwd_diff 比较ZIP中心目录中的CRC32值——无需解压缩，即使在大型存档上也非常快。
• DVAR分类：DVAR根据其前缀自动分类（例如。 r_ =渲染器， cg_ =客户端游戏， sv_ =服务器），其中包含渲染器DVAR的子类别（照明、开花、阴影等）。
• 损坏的存档检测：如果文件不是有效的zip/IWD存档，则所有zip操作都会用清晰的错误消息包装。安全处理丢失的文件、空文件、非压缩文件和丢失的标头。
• dry_run支持：破坏性/写入操作支持 dry_run=true 在提交之前进行安全预览。
• 上下文效率: iwd_grep 利用预测试正则表达式快速路径来避免大文件上的字符串分配GC尖峰，截断过长的压缩行，并将输出限制在 max_matches （默认值：50）； iwd_list 默认为仅压缩名称输出(names_only=true)可选 summary_only 和 limit 参数； iwd_read 支持 limit/offset 带友好的越界错误的安全分页； iwd_info 通过以下方式提供快速的类型和尺寸细分 summary_only; iwd_patch diff以实际更换线路为中心 hintLine.

依赖项

运行时间： @modelcontextprotocol/sdk, adm-zip, zod.Dev： vitest. 看 SOURCES.md 了解全部细节。

许可证

麻省理工学院