Path of Building 代码库指南从目录布局到模块职责的源码级解析【免费下载链接】PathOfBuildingOffline build planner for Path of Exile.项目地址: https://gitcode.com/GitHub_Trending/pa/PathOfBuilding导读本文以 Path of Building社区分支仓库自带的 docs/rundown.md 代码库概览文档为主线系统梳理项目的目录结构Assets / Classes / Data / Export / Modules / TreeData、核心模块职责Build、CalcSetup、Common、Main、ModParser、Data 等、更新机制UpdateCheck / UpdateApply / manifest.xml以及无头运行方式HeadlessWrapper.lua。无论你是打算为 PoB 提交新功能、修复计算 bug还是想在命令行下用无头模式跑自动化测试本文都能帮你快速定位该改哪个文件、代码从哪里进入、数据从哪里加载并附带可验证的源码相对路径方便深入阅读。一、仓库全景五个关键目录 顶层文件PoB 社区分支仓库由src/、spec/、runtime/、docs/等组成其中src/下的五个目录构成了运行时的骨架。rundown.md按以下顺序逐一定位目录职责src/Assets/树视图、Calcs 视图用到的图片资源范围引导图、珠宝光环环等src/Classes/UI 控件类与各标签页Tab的实现src/Data/游戏静态数据基底、技能、词缀、附魔、精华、万神殿等src/Export/从游戏资源GGPK导出数据的脚本系统src/Modules/核心业务逻辑构建管理、计算、数据加载、词缀解析、工具库src/TreeData/各赛季版本的天赋树数据与背景图2_6 ~ 3_29顶层文件还包括GameVersions.lua版本标识与天赋树升级映射、HeadlessWrapper.lua无头模式入口、Launch.lua程序入口、LaunchInstall.lua安装器、UpdateCheck.lua与UpdateApply.lua更新机制、manifest.xml文件 SHA-1 清单以及update_manifest.py清单生成脚本。注rundown.md中列出的tree-2_6.zip、tree-3_6.zip等 zip 包在当前仓库中对应展开为src/TreeData/下的各赛季目录runtime-win32.zip则在 runtime/ 下以展开形式存在。二、Assets图片资源的实际用途src/Assets/中存放了界面叠加、范围绘制与搜索高亮所需的图片。rundown.md明确标注了每张图的使用场景可结合 src/Assets/ 实际文件一一对应资源文件用途game_ui_small.png叠加在range_guide.png之上的 UI 遮罩range_guide.pngCalcs 视图中的技能范围AoE比例尺底图ring.png天赋树视图中鼠标悬停珠宝插槽时绘制的环形覆盖层ShadedInnerRing.png/ShadedOuterRing.png半径珠宝radius jewel的环形覆盖层ShadedInnerRingFlipped.png/ShadedOuterRingFlipped.pngThread of Hope 珠宝的环形覆盖层翻转版small_ring.png天赋树搜索结果中匹配节点的圆环高亮这些图片在运行时由SimpleGraphic渲染宿主以DrawImage方式绘制见 src/Launch.lua 中DrawPopup的绘制流程例如鼠标悬停珠宝插槽时树视图会根据珠宝类型选择对应的环形图片进行叠加。若你想为新的珠宝机制增加环形覆盖层改动的入口就在这些图片的选择逻辑处。三、ClassesUI 控件与标签页src/Classes/下几乎每一个文件对应一个可复用的 UI 控件或一个标签页Tabrundown.md列出了全部文件清单。按用途可归类为基础控件Control.lua、ControlHost.lua、ButtonControl.lua、LabelControl.lua、EditControl.lua、DropDownControl.lua、CheckBoxControl.lua、SliderControl.lua、ListControl.lua、ScrollBarControl.lua、TextListControl.lua、Tooltip.lua、TooltipHost.lua、PopupDialog.lua、UndoHandler.lua等标签页CalcsTab.lua计算、ConfigTab.lua配置、ItemsTab.lua装备、SkillsTab.lua技能、TreeTab.lua天赋树、NotesTab.lua笔记、ImportTab.lua导入、PartyTab.lua组队业务控件ItemSlotControl.lua、ItemListControl.lua、ItemDBControl.lua、GemSelectControl.lua、MinionListControl.lua、NotableDBControl.lua、PassiveMasteryControl.lua、TimelessJewelListControl.lua、TimelessJewelSocketControl.lua、PowerReportListControl.lua、SearchHost.lua等数据模型Item.lua、ModDB.lua、ModList.lua、ModStore.lua、PassiveSpec.lua、PassiveTree.lua、PassiveTreeView.lua、PathControl.lua。UI 控件与模式切换由mainControlHost 实例统一管理。在 src/Modules/Main.lua 中可以看到程序只维护两种顶层模式LIST构建列表对应Modules/BuildList与BUILD构建编辑对应Modules/Build其余全部是这两种模式之内的控件。控件通过锚点anchor与偏移定位例如底部工具栏的 Options / About 按钮都在 src/Modules/Main.lua 中创建。四、Data游戏数据的静态化组织src/Data/存放的是从 GGPK 导出、人工整理的游戏静态数据。rundown.md重点介绍了两个文件Global.lua集中了颜色编码colorCodes、词缀标志ModFlag与关键字keyword的映射还枚举了ActiveSkills.dat/GrantedEffects.dat中的技能类型skill type用于在代码中硬编码特定交互。rundown.md特别提醒这部分需要从 GGPK 逆向工程得出并非所有标志都已被完全理解。这一点在源码中可以得到印证——src/Data/Global.lua 中ModFlag以十六进制位掩码定义例如Attack0x00000001、Spell0x00000002、Projectile0x00000400、Axe0x00010000等colorCodes则定义了 POSITIVE / NEGATIVE / WARNING 等语义色并在 src/Modules/Main.lua 中被读取为程序级默认值。New.lua新公布但词缀数值区间尚未确认的传奇物品unique暂存于此待数值确认后再并入正式数据。rundown.md的说明与仓库现状一致当前src/Data/下没有New.lua文件说明该临时文件已随数据完善被并入 src/Data/Uniques 等正式数据文件。Data.lua是数据加载的中枢rundown.md也将其列入 Modules 一并进行说明它一次性加载了基底、技能、词缀描述、物品词缀、附魔、精华、万神殿、技能宝石、随从等全部静态数据并处理 2.6 / 3.0 版本的兼容分支见 src/Modules/Data.lua。从源码看data.itemMods会按词缀来源分组加载Explicit / Corrupted / Delve / Synthesis / Eldritch / Flask / Jewel 等data.enchantments按装备部位加载这为CalcSetup组装计算环境提供了完整数据源。五、Modules核心业务逻辑逐模块解析src/Modules/是仓库的计算与业务核心rundown.md对其中最重要的文件给出了逐条职责说明。下面按启动 → 数据加载 → 构建管理 → 计算管线 → 词缀解析的调用链展开。5.1 程序入口链Launch → Main → 两种模式src/Launch.lua 是程序入口首次运行读取first.run触发安装更新从 manifest.xml 读取版本号与分支判断 dev 模式初始化渲染器RenderInit(DPI_AWARE)后通过PLoadModule(Modules/Main)加载主模块并对Init/OnFrame/OnKeyDown等所有回调做PCall保护。它还提供了DownloadPage基于lcurl.safe的异步下载、CheckForUpdate每 12 小时后台检查一次等基础设施。src/Modules/Main.lua 初始化LIST与BUILD两种模式检测 Unicode 支持决定用户数据目录dev 模式用脚本目录否则用系统用户目录加载/重建 ModCache懒加载天赋树在后台协程中加载传奇与稀有物品数据库。它同时是状态持久化的入口SaveSettings把当前模式、账号、共享物品与 30 余项 Misc 设置写回Settings.xmlLoadSettings负责读回二者在 src/Modules/Main.lua 与 src/Modules/Main.lua 中一一对应。Launch.lua还内置了若干开发快捷键见 src/Launch.luadev 模式下F5重启、F6打印垃圾回收前后内存、PAUSE开关 profilerCtrlU手动检查更新、CtrlPrintScreen截图。5.2 Build.lua构建屏幕的总控src/Modules/Build.lua 对应rundown.md中对Build.lua的描述是构建屏幕的枢纽顶部back / save / save as、技能点、等级、职业、升华左侧各标签页按钮、盗贼bandits、万神殿pantheon、主技能、属性总览职责加载构建、初始化全部标签页组件、从构建文件读取对应 section、生成计算标签页输出、加载/保存构建、构建版本迁移弹窗、幽魂库spectre library、给侧边栏追加图腾/随从属性、属性需求提示与 tooltip 对比、额外的文件读写逻辑。从源码看buildMode:Init接受(dbFileName, buildName, buildXML, convertBuild, importLink)五个参数由main:SetMode(BUILD, ...)传入当传入buildXML时走LoadDB直接解析 XML否则走LoadDBFile从磁盘读取。构建文件是 XML 格式仓库spec/TestBuilds/下提供了可直接参考的.xml样例构建列表则通过扫描用户构建目录下的 XML 文件得到。5.3 CalcSetup.lua计算环境的装配车间rundown.md对CalcSetup.lua的描述非常详细我们将其职责归纳为如下流水线每一条都能在 src/Modules/CalcSetup.lua共约 1975 行中找到对应实现初始化玩家与敌方的 ModDBcalcs.initModDB(env, modDB)先为双方注入共享的基底属性——最大抗性、格挡上限、充能上限、各类 Debuff如 Intimidated / Unnerved / Debilitated对应的条件修饰等见 src/Modules/CalcSetup.lua注入双方共有的词缀与单方特有词缀包括角色基底、盗贼、万神殿加成构建天赋树节点列表及每个节点的词缀列表并纳入半径珠宝radius jewel增删改的词缀追踪属性需求attribute requirements确保装备/技能满足力敏智门槛查找装备授予的技能、检查珠宝插槽jewel sockets、半径珠宝与深渊珠宝abyss jewel加入药剂flasks对 Necromantic Aegis 与 Dancing Dervish 做特殊处理统计已腐化 / Shaper / Elder 等物品数量供相关词缀使用处理装备授予的额外技能移除不再匹配的插槽组获取武器数据、合并已分配天赋的词缀、设置主技能组并组装包含辅助宝石的主动技能列表未选择主技能时默认使用普通攻击default attack。其中initModDB使用modDB:NewMod(name, type, value, source, flags, conditions...)统一注入基底词缀条件通过{ type Condition, var ... }表描述这些条件变量如Buffed、Combat、Effective在文件末尾绑定到计算模式的开关上。5.4 Calcs 家族与 CalcToolsrundown.md列出的Calcs.lua、CalcActiveSkill.lua、CalcBreakdown.lua、CalcDefence.lua、CalcOffence.lua、CalcPerform.lua、CalcSections.lua共同构成计算管线Calcs.lua加载其余计算模块提供控制台调试打印器、节点/装备/宝石变更计算器并用一个函数同时生成侧边栏与 Calcs 标签页的属性统计CalcSetup.lua负责装配环境上文 5.3CalcSections.lua负责把输出组织成分区sectionsCalcOffence.lua/CalcDefence.lua分别计算攻防数值CalcPerform.lua驱动整体执行CalcTools.lua负责计算词缀数值并汇总 increased / more 修饰校验宝石与技能类型、判断辅助宝石能否作用于主动宝石、确定宝石类型与属性需求、为技能构建属性表。这类校验逻辑在spec/System/TestSkills_spec.lua、spec/System/TestOffence_spec.lua等测试中有大量覆盖。5.5 Common.lua被全仓库依赖的工具基座src/Modules/Common.lua 印证了rundown.md的描述它包含类库class 系统、字符编码转换、GGPK 文件使用的MurmurHash非加密哈希、用于解析 GGPK 的类型转换、JSON 转 Lua 转换器、表操作/打印工具、比较/取整/格式化/文件操作工具。同时它直接加载了一组运行时依赖库lcurl.safeHTTPS 请求、xml、base64、sha1、lua-utf8、lua-profiler可选这些库的二进制形式正是 runtime-win32.zip 中lcurl.dll、lua51.dll、zlib1.dll等 DLL 的 Lua 绑定见rundown.md对 runtime-win32.zip 的说明。类加载通过LoadModule(Classes/..className)完成实现了全局new()工厂。5.6 词缀解析与缓存ModParser / ModTools / ModCacherundown.md指出ModParser.lua解析物品、技能、万神殿上的全部词缀以生成ModCache和Export系统各自值得一篇独立文档——这正说明它们是高度自洽的子系统。这里补充关键事实src/Modules/ModTools.lua 提供创建词缀、格式化数值/标志/标签的函数并加载ModParser生成的ModCachesrc/Modules/Main.lua 中dev 模式下按住CTRL启动或设置环境变量REGENERATE_MOD_CACHE1时程序会跳过预生成缓存、重新解析并写回Data/ModCache.luaSaveModCache见 src/Modules/Main.lua由于 LuaJIT 对超大表有常量数限制SaveModCache会把缓存拆成每 5000 条语句一个匿名函数再合并这是缓存格式中分块函数设计的原因。5.7 其他重要模块ConfigOptions.lua定义增益buffs、条件conditions、地图词缀map mods等各类配置项的规格供 Config 标签页渲染选项对应的 UI 与校验逻辑在 src/Classes/ConfigTab.lua 中。ItemTools.lua计算物品词缀的数值区间、替换物品文本中的非 ASCII 字符、给词缀行着色。PantheonTools.lua万神殿词缀解析器供CalcSetup使用src/Modules/Main.lua 中也被显式加载。StatDescriber.lua统计描述把内部 stat 翻译为可读文本由 src/Modules/Data.lua 加载。BuildList.lua / BuildListHelpers.lua构建选择界面负责文件系统操作、在构建目录搜索 XML 文件并排序。BuildDisplayStats.lua构建列表中的展示统计列。六、版本与天赋树管理GameVersions.luasrc/GameVersions.lua 是rundown.md强调的版本管理模块核心事实如下legacyTargetVersion 2_6未知版本与 3.0 之前构建的默认目标版本liveTargetVersion 3_0新建构建的默认目标、旧构建的转换目标treeVersionList从2_6到3_29含 ruthless / alternate 变体的完整天赋树版本序列latestTreeVersion指向列表末尾defaultTreeVersion指向3_6多天赋树特性引入点treeVersions每个版本的展示名、数值与官方天赋树 URL。配合src/TreeData/目录2_6 ~ 3_29含alternate/ruthless变体即可理解main:LoadTree(treeVersion)见 src/Modules/Main.lua会按版本惰性实例化PassiveTree并把latestTreeVersion设为默认加载版本。七、更新机制manifest.xml 与 UpdateCheck / UpdateApplyrundown.md对更新链路描述得很清楚源码进一步给出了细节manifest.xml 记录文件名 : SHA-1 哈希配对用于判断哪些文件需要更新src/UpdateCheck.lua 在独立子进程中运行由launch:CheckForUpdate通过LaunchSubScript启动比较本地与远程清单、用 curl 下载缺失/变更文件与changelog.txt、重建manifest.xml、生成更新指令表。下载失败最多重试 5 次带全局重试上限支持connectionProtocolIPv4/IPv6、proxyURL、noSSL等连接参数与 src/Modules/Main.lua 的 Options 弹窗中的Connection Protocol / Proxy server选项一一对应src/UpdateApply.lua 消费并应用更新指令表Update/opFile.txt基础模式basic需要退回基础环境、由Update.exe单独处理运行时 DLL 的替换见 src/Launch.lua普通模式normal则可在正常环境下应用后Restart()update_manifest.py 用于为manifest.xml生成 SHA-1新文件必须手动加入清单才会被处理——这是rundown.md特别提示的维护要点。首次安装时src/Launch.lua 会读取first.run标记文件并立即执行一次完整更新此后非 dev 模式每 12 小时后台检查一次CtrlU可手动触发。八、无头模式HeadlessWrapper.lua 与自动化测试rundown.md指出HeadlessWrapper.lua为 PoB 的图形宿主及其环境提供桩实现stubs可在任意操作系统上用命令行运行 PoB建议使用 LuaJIT并提示仍需自行实现Deflate()/Inflate()才能导入/导出构建适用于自动化测试。源码验证了这些说法src/HeadlessWrapper.lua 通过dofile(_SimpleGraphic.def.lua)加载全部 SimpleGraphic API 桩并定义GetVirtualScreenSize()固定返回 1920×1080它用runCallback代替图形回调用dofile(Launch.lua)直接驱动启动流程并在require上做了 hack拦截lcurl.safe避免无头环境缺少该库__mainObject__.continuousIntegrationMode os.getenv(CI)从 CI 环境变量判断是否跳过 ModCache 加载对应REGENERATE_MOD_CACHE/ dev 缓存重建逻辑启动后先runCallback(OnInit)再runCallback(OnFrame)至少一帧完成初始化随后暴露build __mainObject__.main.modes[BUILD]以及三个辅助函数newBuild()新建空构建、loadBuildFromXML(xmlText, name)从 XML 文本加载、loadBuildFromJSON(characterJSON)从 PoE 官方角色 JSON 导入底层调用build.importTab:ImportItemsAndSkills与ImportPassiveTreeAndJewels。这些辅助函数正是spec/System/下全部测试如 spec/System/TestAilments_spec.lua 用before_each(newBuild)重置环境、spec/System/TestBuilds_spec.lua 用loadBuildFromXML(testBuild.xml, buildName)加载样例构建的公共入口。测试构建样例存放在 spec/TestBuilds/3.13spec/GenerateBuilds.lua负责生成它们。无头运行与测试的基本用法安装 LuaJIT或标准 Lua 解释器但 LuaJIT 更优在仓库根目录用lua src/HeadlessWrapper.lua启动无头模式会先走一遍Launch.lua的初始化流程若需导入/导出构建自行实现Deflate()/Inflate()在脚本中调用newBuild()/loadBuildFromXML(xmlText)/loadBuildFromJSON(json)后从build全局对象读取计算输出。提醒无头模式会跳过 ModCache 预加载CI 环境首次运行词缀解析类测试时可能较慢这是预期行为。九、辅助文件速查rundown.md还提到以下顶层文件的用途均可直接打开对照文件用途CHANGELOG.mdMarkdown 格式的补丁说明changelog.txt纯文本格式的补丁说明更新时随清单一并下载CONTRIBUTING.md贡献指南LICENSE.mdMIT 许可证README.md项目总览runtime-win32.zip运行时压缩包PoB 可执行文件、更新程序、libcurlHTTPS、lcurlLua 绑定、lua51LuaJIT 5.1、lzipDEFLATE、SimpleGraphic自研 2D 图形宿主以及 Base64 / JSON / SHA-1 / XML / 字体等 Lua 库.gitattributes / .gitignoreGit 属性与忽略规则十、给贡献者的定位速查表基于rundown.md与源码交叉验证以下是最常见的五类改动入口想改计算逻辑攻/防/状态从 src/Modules/CalcSetup.lua 的initModDB与装配流程入手再到CalcOffence/CalcDefence/CalcPerform想加新词缀/新传奇先看 src/Data/Global.lua 是否缺少对应 flag 或关键字再按data.itemMods分组在 src/Data/ 对应文件ModExplicit.lua、ModJewel.lua、Uniques/等中添加并验证 ModParser 能正确解析想改 UI / 标签页控件在 src/Classes/模式级 UI 布局在 src/Modules/Main.lua 与 src/Modules/Build.lua想改导入导出/构建文件格式入口在 src/Classes/ImportTab.lua 与Build.lua的LoadDB/Save相关函数格式样例参考 spec/TestBuilds/ 下的.xml想写自动化测试在 spec/System/ 新建TestXXX_spec.lua用newBuild()/loadBuildFromXML()驱动无头实例覆盖路径可参考现有TestAilments、TestBuilds、TestSkills等用例。结语docs/rundown.md是一份目录即文档的代码库导航本文在此基础上用源码逐一印证了每条职责说明从Global.lua的位掩码词缀标志到CalcSetup.lua的多步骤计算环境装配从manifest.xml的 SHA-1 更新链路到HeadlessWrapper.lua的无头测试基建。对于刚接触 PoB 社区分支的开发者建议按启动链 → 数据加载 → 构建管理 → 计算管线 → 词缀解析的顺序阅读 src/Modules/Main.lua、src/Modules/Build.lua、src/Modules/CalcSetup.lua 与 src/Data/Global.lua再结合spec/System/的测试用例反向验证理解。【免费下载链接】PathOfBuildingOffline build planner for Path of Exile.项目地址: https://gitcode.com/GitHub_Trending/pa/PathOfBuilding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Path of Building 代码库指南：从目录布局到模块职责的源码级解析
Path of Building 代码库指南从目录布局到模块职责的源码级解析【免费下载链接】PathOfBuildingOffline build planner for Path of Exile.项目地址: https://gitcode.com/GitHub_Trending/pa/PathOfBuilding导读本文以 Path of Building社区分支仓库自带的 docs/rundown.md 代码库概览文档为主线系统梳理项目的目录结构Assets / Classes / Data / Export / Modules / TreeData、核心模块职责Build、CalcSetup、Common、Main、ModParser、Data 等、更新机制UpdateCheck / UpdateApply / manifest.xml以及无头运行方式HeadlessWrapper.lua。无论你是打算为 PoB 提交新功能、修复计算 bug还是想在命令行下用无头模式跑自动化测试本文都能帮你快速定位该改哪个文件、代码从哪里进入、数据从哪里加载并附带可验证的源码相对路径方便深入阅读。一、仓库全景五个关键目录 顶层文件PoB 社区分支仓库由src/、spec/、runtime/、docs/等组成其中src/下的五个目录构成了运行时的骨架。rundown.md按以下顺序逐一定位目录职责src/Assets/树视图、Calcs 视图用到的图片资源范围引导图、珠宝光环环等src/Classes/UI 控件类与各标签页Tab的实现src/Data/游戏静态数据基底、技能、词缀、附魔、精华、万神殿等src/Export/从游戏资源GGPK导出数据的脚本系统src/Modules/核心业务逻辑构建管理、计算、数据加载、词缀解析、工具库src/TreeData/各赛季版本的天赋树数据与背景图2_6 ~ 3_29顶层文件还包括GameVersions.lua版本标识与天赋树升级映射、HeadlessWrapper.lua无头模式入口、Launch.lua程序入口、LaunchInstall.lua安装器、UpdateCheck.lua与UpdateApply.lua更新机制、manifest.xml文件 SHA-1 清单以及update_manifest.py清单生成脚本。注rundown.md中列出的tree-2_6.zip、tree-3_6.zip等 zip 包在当前仓库中对应展开为src/TreeData/下的各赛季目录runtime-win32.zip则在 runtime/ 下以展开形式存在。二、Assets图片资源的实际用途src/Assets/中存放了界面叠加、范围绘制与搜索高亮所需的图片。rundown.md明确标注了每张图的使用场景可结合 src/Assets/ 实际文件一一对应资源文件用途game_ui_small.png叠加在range_guide.png之上的 UI 遮罩range_guide.pngCalcs 视图中的技能范围AoE比例尺底图ring.png天赋树视图中鼠标悬停珠宝插槽时绘制的环形覆盖层ShadedInnerRing.png/ShadedOuterRing.png半径珠宝radius jewel的环形覆盖层ShadedInnerRingFlipped.png/ShadedOuterRingFlipped.pngThread of Hope 珠宝的环形覆盖层翻转版small_ring.png天赋树搜索结果中匹配节点的圆环高亮这些图片在运行时由SimpleGraphic渲染宿主以DrawImage方式绘制见 src/Launch.lua 中DrawPopup的绘制流程例如鼠标悬停珠宝插槽时树视图会根据珠宝类型选择对应的环形图片进行叠加。若你想为新的珠宝机制增加环形覆盖层改动的入口就在这些图片的选择逻辑处。三、ClassesUI 控件与标签页src/Classes/下几乎每一个文件对应一个可复用的 UI 控件或一个标签页Tabrundown.md列出了全部文件清单。按用途可归类为基础控件Control.lua、ControlHost.lua、ButtonControl.lua、LabelControl.lua、EditControl.lua、DropDownControl.lua、CheckBoxControl.lua、SliderControl.lua、ListControl.lua、ScrollBarControl.lua、TextListControl.lua、Tooltip.lua、TooltipHost.lua、PopupDialog.lua、UndoHandler.lua等标签页CalcsTab.lua计算、ConfigTab.lua配置、ItemsTab.lua装备、SkillsTab.lua技能、TreeTab.lua天赋树、NotesTab.lua笔记、ImportTab.lua导入、PartyTab.lua组队业务控件ItemSlotControl.lua、ItemListControl.lua、ItemDBControl.lua、GemSelectControl.lua、MinionListControl.lua、NotableDBControl.lua、PassiveMasteryControl.lua、TimelessJewelListControl.lua、TimelessJewelSocketControl.lua、PowerReportListControl.lua、SearchHost.lua等数据模型Item.lua、ModDB.lua、ModList.lua、ModStore.lua、PassiveSpec.lua、PassiveTree.lua、PassiveTreeView.lua、PathControl.lua。UI 控件与模式切换由mainControlHost 实例统一管理。在 src/Modules/Main.lua 中可以看到程序只维护两种顶层模式LIST构建列表对应Modules/BuildList与BUILD构建编辑对应Modules/Build其余全部是这两种模式之内的控件。控件通过锚点anchor与偏移定位例如底部工具栏的 Options / About 按钮都在 src/Modules/Main.lua 中创建。四、Data游戏数据的静态化组织src/Data/存放的是从 GGPK 导出、人工整理的游戏静态数据。rundown.md重点介绍了两个文件Global.lua集中了颜色编码colorCodes、词缀标志ModFlag与关键字keyword的映射还枚举了ActiveSkills.dat/GrantedEffects.dat中的技能类型skill type用于在代码中硬编码特定交互。rundown.md特别提醒这部分需要从 GGPK 逆向工程得出并非所有标志都已被完全理解。这一点在源码中可以得到印证——src/Data/Global.lua 中ModFlag以十六进制位掩码定义例如Attack0x00000001、Spell0x00000002、Projectile0x00000400、Axe0x00010000等colorCodes则定义了 POSITIVE / NEGATIVE / WARNING 等语义色并在 src/Modules/Main.lua 中被读取为程序级默认值。New.lua新公布但词缀数值区间尚未确认的传奇物品unique暂存于此待数值确认后再并入正式数据。rundown.md的说明与仓库现状一致当前src/Data/下没有New.lua文件说明该临时文件已随数据完善被并入 src/Data/Uniques 等正式数据文件。Data.lua是数据加载的中枢rundown.md也将其列入 Modules 一并进行说明它一次性加载了基底、技能、词缀描述、物品词缀、附魔、精华、万神殿、技能宝石、随从等全部静态数据并处理 2.6 / 3.0 版本的兼容分支见 src/Modules/Data.lua。从源码看data.itemMods会按词缀来源分组加载Explicit / Corrupted / Delve / Synthesis / Eldritch / Flask / Jewel 等data.enchantments按装备部位加载这为CalcSetup组装计算环境提供了完整数据源。五、Modules核心业务逻辑逐模块解析src/Modules/是仓库的计算与业务核心rundown.md对其中最重要的文件给出了逐条职责说明。下面按启动 → 数据加载 → 构建管理 → 计算管线 → 词缀解析的调用链展开。5.1 程序入口链Launch → Main → 两种模式src/Launch.lua 是程序入口首次运行读取first.run触发安装更新从 manifest.xml 读取版本号与分支判断 dev 模式初始化渲染器RenderInit(DPI_AWARE)后通过PLoadModule(Modules/Main)加载主模块并对Init/OnFrame/OnKeyDown等所有回调做PCall保护。它还提供了DownloadPage基于lcurl.safe的异步下载、CheckForUpdate每 12 小时后台检查一次等基础设施。src/Modules/Main.lua 初始化LIST与BUILD两种模式检测 Unicode 支持决定用户数据目录dev 模式用脚本目录否则用系统用户目录加载/重建 ModCache懒加载天赋树在后台协程中加载传奇与稀有物品数据库。它同时是状态持久化的入口SaveSettings把当前模式、账号、共享物品与 30 余项 Misc 设置写回Settings.xmlLoadSettings负责读回二者在 src/Modules/Main.lua 与 src/Modules/Main.lua 中一一对应。Launch.lua还内置了若干开发快捷键见 src/Launch.luadev 模式下F5重启、F6打印垃圾回收前后内存、PAUSE开关 profilerCtrlU手动检查更新、CtrlPrintScreen截图。5.2 Build.lua构建屏幕的总控src/Modules/Build.lua 对应rundown.md中对Build.lua的描述是构建屏幕的枢纽顶部back / save / save as、技能点、等级、职业、升华左侧各标签页按钮、盗贼bandits、万神殿pantheon、主技能、属性总览职责加载构建、初始化全部标签页组件、从构建文件读取对应 section、生成计算标签页输出、加载/保存构建、构建版本迁移弹窗、幽魂库spectre library、给侧边栏追加图腾/随从属性、属性需求提示与 tooltip 对比、额外的文件读写逻辑。从源码看buildMode:Init接受(dbFileName, buildName, buildXML, convertBuild, importLink)五个参数由main:SetMode(BUILD, ...)传入当传入buildXML时走LoadDB直接解析 XML否则走LoadDBFile从磁盘读取。构建文件是 XML 格式仓库spec/TestBuilds/下提供了可直接参考的.xml样例构建列表则通过扫描用户构建目录下的 XML 文件得到。5.3 CalcSetup.lua计算环境的装配车间rundown.md对CalcSetup.lua的描述非常详细我们将其职责归纳为如下流水线每一条都能在 src/Modules/CalcSetup.lua共约 1975 行中找到对应实现初始化玩家与敌方的 ModDBcalcs.initModDB(env, modDB)先为双方注入共享的基底属性——最大抗性、格挡上限、充能上限、各类 Debuff如 Intimidated / Unnerved / Debilitated对应的条件修饰等见 src/Modules/CalcSetup.lua注入双方共有的词缀与单方特有词缀包括角色基底、盗贼、万神殿加成构建天赋树节点列表及每个节点的词缀列表并纳入半径珠宝radius jewel增删改的词缀追踪属性需求attribute requirements确保装备/技能满足力敏智门槛查找装备授予的技能、检查珠宝插槽jewel sockets、半径珠宝与深渊珠宝abyss jewel加入药剂flasks对 Necromantic Aegis 与 Dancing Dervish 做特殊处理统计已腐化 / Shaper / Elder 等物品数量供相关词缀使用处理装备授予的额外技能移除不再匹配的插槽组获取武器数据、合并已分配天赋的词缀、设置主技能组并组装包含辅助宝石的主动技能列表未选择主技能时默认使用普通攻击default attack。其中initModDB使用modDB:NewMod(name, type, value, source, flags, conditions...)统一注入基底词缀条件通过{ type Condition, var ... }表描述这些条件变量如Buffed、Combat、Effective在文件末尾绑定到计算模式的开关上。5.4 Calcs 家族与 CalcToolsrundown.md列出的Calcs.lua、CalcActiveSkill.lua、CalcBreakdown.lua、CalcDefence.lua、CalcOffence.lua、CalcPerform.lua、CalcSections.lua共同构成计算管线Calcs.lua加载其余计算模块提供控制台调试打印器、节点/装备/宝石变更计算器并用一个函数同时生成侧边栏与 Calcs 标签页的属性统计CalcSetup.lua负责装配环境上文 5.3CalcSections.lua负责把输出组织成分区sectionsCalcOffence.lua/CalcDefence.lua分别计算攻防数值CalcPerform.lua驱动整体执行CalcTools.lua负责计算词缀数值并汇总 increased / more 修饰校验宝石与技能类型、判断辅助宝石能否作用于主动宝石、确定宝石类型与属性需求、为技能构建属性表。这类校验逻辑在spec/System/TestSkills_spec.lua、spec/System/TestOffence_spec.lua等测试中有大量覆盖。5.5 Common.lua被全仓库依赖的工具基座src/Modules/Common.lua 印证了rundown.md的描述它包含类库class 系统、字符编码转换、GGPK 文件使用的MurmurHash非加密哈希、用于解析 GGPK 的类型转换、JSON 转 Lua 转换器、表操作/打印工具、比较/取整/格式化/文件操作工具。同时它直接加载了一组运行时依赖库lcurl.safeHTTPS 请求、xml、base64、sha1、lua-utf8、lua-profiler可选这些库的二进制形式正是 runtime-win32.zip 中lcurl.dll、lua51.dll、zlib1.dll等 DLL 的 Lua 绑定见rundown.md对 runtime-win32.zip 的说明。类加载通过LoadModule(Classes/..className)完成实现了全局new()工厂。5.6 词缀解析与缓存ModParser / ModTools / ModCacherundown.md指出ModParser.lua解析物品、技能、万神殿上的全部词缀以生成ModCache和Export系统各自值得一篇独立文档——这正说明它们是高度自洽的子系统。这里补充关键事实src/Modules/ModTools.lua 提供创建词缀、格式化数值/标志/标签的函数并加载ModParser生成的ModCachesrc/Modules/Main.lua 中dev 模式下按住CTRL启动或设置环境变量REGENERATE_MOD_CACHE1时程序会跳过预生成缓存、重新解析并写回Data/ModCache.luaSaveModCache见 src/Modules/Main.lua由于 LuaJIT 对超大表有常量数限制SaveModCache会把缓存拆成每 5000 条语句一个匿名函数再合并这是缓存格式中分块函数设计的原因。5.7 其他重要模块ConfigOptions.lua定义增益buffs、条件conditions、地图词缀map mods等各类配置项的规格供 Config 标签页渲染选项对应的 UI 与校验逻辑在 src/Classes/ConfigTab.lua 中。ItemTools.lua计算物品词缀的数值区间、替换物品文本中的非 ASCII 字符、给词缀行着色。PantheonTools.lua万神殿词缀解析器供CalcSetup使用src/Modules/Main.lua 中也被显式加载。StatDescriber.lua统计描述把内部 stat 翻译为可读文本由 src/Modules/Data.lua 加载。BuildList.lua / BuildListHelpers.lua构建选择界面负责文件系统操作、在构建目录搜索 XML 文件并排序。BuildDisplayStats.lua构建列表中的展示统计列。六、版本与天赋树管理GameVersions.luasrc/GameVersions.lua 是rundown.md强调的版本管理模块核心事实如下legacyTargetVersion 2_6未知版本与 3.0 之前构建的默认目标版本liveTargetVersion 3_0新建构建的默认目标、旧构建的转换目标treeVersionList从2_6到3_29含 ruthless / alternate 变体的完整天赋树版本序列latestTreeVersion指向列表末尾defaultTreeVersion指向3_6多天赋树特性引入点treeVersions每个版本的展示名、数值与官方天赋树 URL。配合src/TreeData/目录2_6 ~ 3_29含alternate/ruthless变体即可理解main:LoadTree(treeVersion)见 src/Modules/Main.lua会按版本惰性实例化PassiveTree并把latestTreeVersion设为默认加载版本。七、更新机制manifest.xml 与 UpdateCheck / UpdateApplyrundown.md对更新链路描述得很清楚源码进一步给出了细节manifest.xml 记录文件名 : SHA-1 哈希配对用于判断哪些文件需要更新src/UpdateCheck.lua 在独立子进程中运行由launch:CheckForUpdate通过LaunchSubScript启动比较本地与远程清单、用 curl 下载缺失/变更文件与changelog.txt、重建manifest.xml、生成更新指令表。下载失败最多重试 5 次带全局重试上限支持connectionProtocolIPv4/IPv6、proxyURL、noSSL等连接参数与 src/Modules/Main.lua 的 Options 弹窗中的Connection Protocol / Proxy server选项一一对应src/UpdateApply.lua 消费并应用更新指令表Update/opFile.txt基础模式basic需要退回基础环境、由Update.exe单独处理运行时 DLL 的替换见 src/Launch.lua普通模式normal则可在正常环境下应用后Restart()update_manifest.py 用于为manifest.xml生成 SHA-1新文件必须手动加入清单才会被处理——这是rundown.md特别提示的维护要点。首次安装时src/Launch.lua 会读取first.run标记文件并立即执行一次完整更新此后非 dev 模式每 12 小时后台检查一次CtrlU可手动触发。八、无头模式HeadlessWrapper.lua 与自动化测试rundown.md指出HeadlessWrapper.lua为 PoB 的图形宿主及其环境提供桩实现stubs可在任意操作系统上用命令行运行 PoB建议使用 LuaJIT并提示仍需自行实现Deflate()/Inflate()才能导入/导出构建适用于自动化测试。源码验证了这些说法src/HeadlessWrapper.lua 通过dofile(_SimpleGraphic.def.lua)加载全部 SimpleGraphic API 桩并定义GetVirtualScreenSize()固定返回 1920×1080它用runCallback代替图形回调用dofile(Launch.lua)直接驱动启动流程并在require上做了 hack拦截lcurl.safe避免无头环境缺少该库__mainObject__.continuousIntegrationMode os.getenv(CI)从 CI 环境变量判断是否跳过 ModCache 加载对应REGENERATE_MOD_CACHE/ dev 缓存重建逻辑启动后先runCallback(OnInit)再runCallback(OnFrame)至少一帧完成初始化随后暴露build __mainObject__.main.modes[BUILD]以及三个辅助函数newBuild()新建空构建、loadBuildFromXML(xmlText, name)从 XML 文本加载、loadBuildFromJSON(characterJSON)从 PoE 官方角色 JSON 导入底层调用build.importTab:ImportItemsAndSkills与ImportPassiveTreeAndJewels。这些辅助函数正是spec/System/下全部测试如 spec/System/TestAilments_spec.lua 用before_each(newBuild)重置环境、spec/System/TestBuilds_spec.lua 用loadBuildFromXML(testBuild.xml, buildName)加载样例构建的公共入口。测试构建样例存放在 spec/TestBuilds/3.13spec/GenerateBuilds.lua负责生成它们。无头运行与测试的基本用法安装 LuaJIT或标准 Lua 解释器但 LuaJIT 更优在仓库根目录用lua src/HeadlessWrapper.lua启动无头模式会先走一遍Launch.lua的初始化流程若需导入/导出构建自行实现Deflate()/Inflate()在脚本中调用newBuild()/loadBuildFromXML(xmlText)/loadBuildFromJSON(json)后从build全局对象读取计算输出。提醒无头模式会跳过 ModCache 预加载CI 环境首次运行词缀解析类测试时可能较慢这是预期行为。九、辅助文件速查rundown.md还提到以下顶层文件的用途均可直接打开对照文件用途CHANGELOG.mdMarkdown 格式的补丁说明changelog.txt纯文本格式的补丁说明更新时随清单一并下载CONTRIBUTING.md贡献指南LICENSE.mdMIT 许可证README.md项目总览runtime-win32.zip运行时压缩包PoB 可执行文件、更新程序、libcurlHTTPS、lcurlLua 绑定、lua51LuaJIT 5.1、lzipDEFLATE、SimpleGraphic自研 2D 图形宿主以及 Base64 / JSON / SHA-1 / XML / 字体等 Lua 库.gitattributes / .gitignoreGit 属性与忽略规则十、给贡献者的定位速查表基于rundown.md与源码交叉验证以下是最常见的五类改动入口想改计算逻辑攻/防/状态从 src/Modules/CalcSetup.lua 的initModDB与装配流程入手再到CalcOffence/CalcDefence/CalcPerform想加新词缀/新传奇先看 src/Data/Global.lua 是否缺少对应 flag 或关键字再按data.itemMods分组在 src/Data/ 对应文件ModExplicit.lua、ModJewel.lua、Uniques/等中添加并验证 ModParser 能正确解析想改 UI / 标签页控件在 src/Classes/模式级 UI 布局在 src/Modules/Main.lua 与 src/Modules/Build.lua想改导入导出/构建文件格式入口在 src/Classes/ImportTab.lua 与Build.lua的LoadDB/Save相关函数格式样例参考 spec/TestBuilds/ 下的.xml想写自动化测试在 spec/System/ 新建TestXXX_spec.lua用newBuild()/loadBuildFromXML()驱动无头实例覆盖路径可参考现有TestAilments、TestBuilds、TestSkills等用例。结语docs/rundown.md是一份目录即文档的代码库导航本文在此基础上用源码逐一印证了每条职责说明从Global.lua的位掩码词缀标志到CalcSetup.lua的多步骤计算环境装配从manifest.xml的 SHA-1 更新链路到HeadlessWrapper.lua的无头测试基建。对于刚接触 PoB 社区分支的开发者建议按启动链 → 数据加载 → 构建管理 → 计算管线 → 词缀解析的顺序阅读 src/Modules/Main.lua、src/Modules/Build.lua、src/Modules/CalcSetup.lua 与 src/Data/Global.lua再结合spec/System/的测试用例反向验证理解。【免费下载链接】PathOfBuildingOffline build planner for Path of Exile.项目地址: https://gitcode.com/GitHub_Trending/pa/PathOfBuilding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考