7DaysToDieSkill

# 七日杀 XML Mod 制作完整技能指南

目录

1. 原版文件定位
2. XML 制作硬性规范
3. Buff 系统开发规范
4. Modlet 标准结构
5. 本地化翻译文件
6. 原版 DLL 读取路径
7. 开发最佳实践

原版文件定位

1.1 当前游戏根目录

七日杀安装目录必须先从当前工作区、用户提供路径或 Steam 库中确认。以下统一用 $GameRoot 表示游戏根目录：

$GameRoot

常见确认方式：

# 如果当前工作目录已经在七日杀目录内，优先使用当前目录
$GameRoot = (Get-Location).Path

# 或由用户明确提供
$GameRoot = "<用户提供的七日杀安装目录>"

# 或从常见 Steam libraryfolders.vdf 中确认库目录后再拼接 steamapps\common\7 Days To Die
# 注意：不同玩家可能在任意盘符、任意 Steam 库，不得写死路径。

# 校验是否是有效游戏根目录
Test-Path (Join-Path $GameRoot "Data\Config")
Test-Path (Join-Path $GameRoot "7DaysToDie_Data\Managed")

所有原版 XML、注释说明、可用词条、Buff 属性、触发器和 DLL 都必须从当前玩家实际安装目录读取，不得凭记忆编造。不要假设游戏一定安装在 C 盘或某个固定盘符。

1.2 原版 XML 配置目录

原版配置目录由 $GameRoot 拼出：

$GameRoot\Data\Config

常用原版 XML 文件：

1.3 查询原版词条

制作 XML 前必须先搜索原版是否存在对应标签、属性、值、action、trigger、requirement 或枚举。

# 搜索某个 XML 词条是否在原版出现过
Select-String -Path (Join-Path $GameRoot "Data\Config\*.xml") -Pattern "triggered_effect|passive_effect|ModifyCVar|onSelfBuffStart"

# 查询某个被动属性是否存在
Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'name="RunSpeed"'

# 查询某个触发器是否存在
Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'trigger="onSelfBuffStart"'

XML 制作硬性规范

2.1 禁止自创 XML 词条

除非用户明确允许，否则不得自创任何 XML 词条。

这里的“XML 词条”包括但不限于：

错误示例

<!-- 错误：未确认原版存在 SuperRunSpeed、onSelfJumpTwice、DoMagicDamage -->
<passive_effect name="SuperRunSpeed" operation="base_add" value="2"/>
<triggered_effect trigger="onSelfJumpTwice" action="DoMagicDamage"/>

正确示例

<!-- 正确：RunSpeed、base_add、onSelfBuffStart、ModifyCVar 都应先在原版 XML 中确认存在 -->
<passive_effect name="RunSpeed" operation="base_add" value="0.2"/>
<triggered_effect trigger="onSelfBuffStart" action="ModifyCVar" cvar="$example" operation="set" value="1"/>

2.2 先查原版，再写补丁

每次制作 XML 都按以下流程执行：

用户需求
    ↓
定位相关原版 XML 文件
    ↓
搜索原版标签、属性、属性值和引用方式
    ↓
复制原版写法作为模板
    ↓
只修改必要数值或引用
    ↓
写入 Modlet Config XML
    ↓
检查 XPath 和 XML 格式

2.3 不直接改原版文件

默认只制作 Modlet，不直接修改 Data\Config 下的原版文件。

原版 XML 只用于读取和比对，Mod 文件应放入：

$GameRoot\Mods\你的Mod名\Config

Buff 系统开发规范

3.1 Buff 注释是权威来源

buffs.xml 内注释已经给全游戏属性和游戏触发器说明。

处理 Buff 相关需求时，必须优先读取：

$GameRoot\Data\Config\buffs.xml

重点查找内容：

3.2 被动属性写法

被动属性必须使用原版已经出现过的 passive_effect 名称和 operation。

<effect_group>
    <passive_effect name="RunSpeed" operation="base_add" value="0.1"/>
    <passive_effect name="EntityDamage" operation="perc_add" value="0.2" tags="melee"/>
</effect_group>

写作前检查：

Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'passive_effect name="RunSpeed"'
Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'operation="base_add"'

3.3 触发效果写法

触发器和 action 必须使用 buffs.xml 注释或正文中已经出现过的内容。

<effect_group>
    <triggered_effect trigger="onSelfBuffStart" action="ModifyCVar" cvar="$example" operation="set" value="1"/>
    <triggered_effect trigger="onSelfBuffRemove" action="RemoveCVar" cvar="$example"/>
</effect_group>

写作前检查：

Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'trigger="onSelfBuffStart"'
Select-String -LiteralPath (Join-Path $GameRoot "Data\Config\buffs.xml") -Pattern 'action="ModifyCVar"'

3.4 requirement 条件写法

requirement 的 name、operation、属性组合必须从原版复制或确认。

<triggered_effect trigger="onSelfBuffUpdate" action="ModifyCVar" cvar="$example" operation="add" value="1">
    <requirement name="CVarCompare" cvar="$example" operation="LT" value="10"/>
</triggered_effect>

Modlet 标准结构

4.1 目录结构

推荐 Modlet 结构：

Mods\ExampleMod
├── ModInfo.xml
└── Config
    ├── buffs.xml
    ├── items.xml
    ├── blocks.xml
    └── recipes.xml

4.2 ModInfo.xml 模板

<?xml version="1.0" encoding="UTF-8"?>
<xml>
    <Name value="ExampleMod"/>
    <DisplayName value="Example Mod"/>
    <Description value="Example 7 Days To Die XML modlet."/>
    <Author value="Codex"/>
    <Version value="1.0.0"/>
</xml>

4.3 Config XML 补丁模板

七日杀 Modlet 通常使用 XPath 补丁方式修改原版 XML。

<?xml version="1.0" encoding="UTF-8"?>
<configs>
    <append xpath="/buffs">
        <buff name="exampleBuff">
            <stack_type value="ignore"/>
            <duration value="10"/>
            <effect_group>
                <passive_effect name="RunSpeed" operation="base_add" value="0.1"/>
            </effect_group>
        </buff>
    </append>
</configs>

注意：即使使用模板，也必须先确认其中每个标签、属性、属性值在原版中存在。若用户没有允许新增业务 name，则不要新增 exampleBuff 这类新命名词条。

4.4 XPath 操作规范

XPath 补丁应尽量精确，避免影响无关节点。

<!-- 精确修改某个 buff 的 duration -->
<set xpath="/buffs/buff[@name='buffDrugSteroids']/duration/@value">600</set>

<!-- 精确追加到某个 buff 的 effect_group -->
<append xpath="/buffs/buff[@name='buffDrugSteroids']/effect_group">
    <passive_effect name="RunSpeed" operation="base_add" value="0.1"/>
</append>

本地化翻译文件

5.1 原版翻译文件路径

原版翻译文件是 Localization.txt，路径由 $GameRoot 拼出：

$GameRoot\Data\Config\Localization.txt

凡是 XML 中出现 name_key、description_key、tooltip_key、display_value_key、物品显示名、方块显示名、Buff 显示名等本地化键，都必须同步检查或补充翻译文件。

5.2 原版 CSV 表头格式

Localization.txt 是 CSV 格式，原版表头为：

Key,File,Type,UsedInMainMenu,NoTranslate,english,Context / Alternate Text,german,spanish,french,italian,japanese,koreana,polish,brazilian,russian,turkish,schinese,tchinese

新增翻译行必须保持同样列顺序，不得随意删列、换列或改表头。

5.3 常见翻译行格式

参考原版 Buff 翻译行：

buffExampleName,buffs,Buff,,x,Example Buff,,,,,,,,,,,,示例 Buff,範例 Buff
buffExampleDesc,buffs,Buff,,x,Example description.,,,,,,,,,,,,示例描述。,範例描述。
buffExampleTooltip,buffs,Buff,,x,Example tooltip.,,,,,,,,,,,,示例提示。,範例提示。

列含义：

5.4 XML 键名和翻译行对应

XML 中只写 key，不直接写显示文本。

<buff name="exampleBuff" name_key="buffExampleName" description_key="buffExampleDesc" tooltip_key="buffExampleTooltip">
    <display_value_key value="buffExampleShort"/>
</buff>

对应翻译文件需要补充：

buffExampleName,buffs,Buff,,x,Example Buff,,,,,,,,,,,,示例 Buff,範例 Buff
buffExampleDesc,buffs,Buff,,x,Example description.,,,,,,,,,,,,示例描述。,範例描述。
buffExampleTooltip,buffs,Buff,,x,Example tooltip.,,,,,,,,,,,,示例提示。,範例提示。
buffExampleShort,buffs,Buff,,x,Example,,,,,,,,,,,,示例,範例

5.5 Modlet 中的 Localization.txt

Modlet 需要翻译时，应在 Mod 目录中提供自己的 Config\Localization.txt，不要直接修改原版翻译文件。

推荐结构：

Mods\ExampleMod
├── ModInfo.xml
└── Config
    ├── buffs.xml
    └── Localization.txt

5.6 翻译制作规则

• 先读取原版 Localization.txt，复制相同领域的行格式。
• Key 必须和 XML 中的 name_key、description_key、tooltip_key、display_value_key 完全一致。
• File 和 Type 必须参考原版同类条目，不确定时先搜索相似 key。
• CSV 列数必须与表头一致，包含英文、简体中文和繁体中文列。
• 文本含逗号时必须使用英文双引号包裹。
• 换行文本参考原版使用 \n，不要直接写真实换行破坏 CSV 行。
• 未经允许不要改原版 Data\Config\Localization.txt。

原版 DLL 读取路径

6.1 客户端 DLL 路径

当前玩家实际安装目录的原版托管 DLL 位于：

$GameRoot\7DaysToDie_Data\Managed

常用 DLL：

6.2 专用服务器 DLL 路径

如果安装了 Dedicated Server，优先检查：

$GameRoot\7DaysToDieServer_Data\Managed

不存在该目录时，说明当前目录主要是客户端安装，不要假设服务器 DLL 存在。

6.3 PowerShell 读取 DLL 路径

$GameRoot = "<用户提供或已确认的七日杀安装目录>"
$ClientManaged = Join-Path $GameRoot "7DaysToDie_Data\Managed"
$ServerManaged = Join-Path $GameRoot "7DaysToDieServer_Data\Managed"

Get-ChildItem -LiteralPath $ClientManaged -Filter *.dll |
    Select-Object FullName

if (Test-Path -LiteralPath $ServerManaged) {
    Get-ChildItem -LiteralPath $ServerManaged -Filter *.dll |
        Select-Object FullName
}

6.4 反编译读取原则

读取 DLL 仅用于确认原版类型、枚举、字段和 XML 解析逻辑。

推荐工具：

原则：

• 只读原版 DLL，不直接覆盖或改写原版 DLL。
• 若要实验，先复制 DLL 到临时目录再分析。
• XML 能解决的需求优先用 XML，不升级为 DLL 修改。
• DLL 结论必须回到 XML 中验证，不能绕过“不得自创 XML 词条”的规则。

开发最佳实践

7.1 标准工作流

明确需求
    ↓
确认目标 XML 文件
    ↓
搜索原版相似实现
    ↓
确认标签、属性、枚举、Buff 属性、触发器
    ↓
编写最小 XPath 补丁
    ↓
检查 XML 格式和 XPath 命中范围
    ↓
启动游戏或服务器验证日志

7.2 搜索优先级

1. 先搜 Data\Config\buffs.xml，确认 Buff 属性、触发器、action、requirement。
2. 再搜目标领域 XML，例如物品搜 items.xml，方块搜 blocks.xml。
3. 最后搜全部 Data\Config\*.xml，确认跨文件引用方式。
4. 只有 XML 无法确认时，才读取 7DaysToDie_Data\Managed 下 DLL。

7.3 修改范围控制

7.4 交付前检查清单

• 是否读取了原版 XML，而不是凭空写法。
• 是否没有自创未授权标签、属性、trigger、action、requirement、passive_effect。
• 是否确认游戏属性和触发器来自 buffs.xml 注释或正文。
• 是否使用 Modlet，而不是直接改原版 Data\Config。
• 是否为新增或变更的本地化 key 补充 Config\Localization.txt。
• XPath 是否精确到目标节点，避免误伤同名或相似节点。
• XML 是否为 UTF-8，标签是否闭合，属性引号是否统一。
• DLL 是否只读，且路径来自当前安装目录。