CompatLink – Epic Fight Weapons Compat

CompatLink

为任意模组武器添加 Epic Fight 动作集——无需编写代码，只需 JSON。

Epic Fight 开箱即用时只认识原版武器。CompatLink 只需在配置文件夹中放入一个小型 JSON 文件，就能将任意模组武器关联到 Epic Fight 动作集。巨剑挥舞如大剑，武士刀拔刀如打刀，长矛突刺如长矛——支持任意模组，几分钟即可完成。

适用于 Forge 1.20.1（Epic Fight 20.14.17+）和 NeoForge 1.21.1（Epic Fight 21.13+）
任意物品都能使用任意 Epic Fight 动作集——包括其他 Epic Fight 附属模组添加的武器类型，不限于内置类型
挥砍轨迹、战斗属性调整，以及（实验性）生物动作集——全部通过同一份 JSON 设置
100% 数据驱动：基础用法无需编写代码，也不需要了解数据包
安全可靠：损坏的映射文件会跳过并记录日志，不会导致崩溃
未安装 Epic Fight 时也能正常加载（映射会等待 Epic Fight 安装后再生效）
适用于玩家和整合包制作者：30 秒即可完成设置
安装 CompatLink（以及 Epic Fight）。
打开 config/compatlink/mappings/——CompatLink 首次运行时会自动创建此文件夹并放入示例文件。
创建 mymappings.json：
{
“format”: 1,
“backend”: “epicfight”,
“weapons”: [
{ “target”: “simplyswords:iron_claymore”, “preset”: “epicfight:greatsword” },
{ “target”: “cataclysm:the_incinerator”, “preset”: “epicfight:greatsword” },
{ “target”: “somemod:*_katana”, “preset”: “epicfight:uchigatana” }
]
}

启动游戏（或运行 /reload）。完成——日志会显示 CompatLink: N entity mappings, M weapon mappings applied。

通配符（somemod:*）和优先级（数值越高越优先；优先级相同时，精确 ID 优先于通配符）让你能用一行映射整个模组，也能随后单独覆盖特定物品。

可用的武器预设包括 epicfight:sword、epicfight:greatsword、epicfight:longsword、epicfight:uchigatana、epicfight:tachi、epicfight:spear、epicfight:dagger、epicfight:axe、epicfight:bow，以及 Epic Fight 数据包添加的任何武器类型。

使用其他 Epic Fight 附属模组的动作集

预设只是一个 Epic Fight 武器类型 ID，因此不局限于内置类型——你可以借用其他 Epic Fight 附属模组注册的动作集。任意物品都能使用任意动作集：

{
“format”: 1,
“backend”: “epicfight”,
“weapons”: [
{ “target”: “minecraft:golden_apple”, “preset”: “wom:ender_blaster” }
]
}

在这个例子中，一个普通金苹果就能使用来自另一个附属模组、属于 wom:ender_blaster 武器类型的完整攻击动画。整合包中注册的任何武器类型——无论是 Epic Fight 自带的，还是其他模组添加的——都可以作为有效预设。

调整武器属性，使用
params

每条武器映射还可以调整 Epic Fight 的战斗属性——含义与 Epic Fight 数据包中的 attributes.common 相同，无需数据包：

{
“target”: “simplyswords:iron_claymore”,
“preset”: “epicfight:greatsword”,
“params”: { “impact”: 8.0, “max_strikes”: 6, “damage_bonus”: 2.0 }
}

impact — 使目标踉跄／击退的力度（小数）
armor_negation — 无视护甲的百分比（小数）
damage_bonus — 战斗模式下的额外伤害（小数）
speed_bonus — 攻击速度加成（小数）
max_strikes — 每次挥击可命中的目标数上限（整数）

未知键或格式错误的数值会在日志中显示警告并被忽略——武器仍会获得对应动作集。

武器挥砍轨迹

已映射的武器会自动继承其武器类型对应的 Epic Fight 挥砍轨迹，无需额外设置。想自定义轨迹？可在映射中添加一个 trail 对象（使用 Epic Fight 的 item_skins 格式）：

{
“target”: “simplyswords:runic_katana”,
“preset”: “epicfight:uchigatana”,
“trail”: {
“color”: [120, 40, 255],
“begin_pos”: [0.0, 0.0, -0.2], “end_pos”: [0.0, -0.22, -1.25],
“lifetime”: 4, “interpolations”: 6,
“texture_path”: “epicfight:textures/particle/swing_trail.png”,
“particle_type”: “epicfight:swing_trail”
}
}

小物品上的拖尾太大？可以用 “trail”: “none” （或 false）关闭该武器的拖尾。若要完全禁用自动拖尾——只有明确设置了 trail 对象的武器才会显示拖尾——请在 config/compatlink/settings.json 中设置 “auto_trails”: false。

通过配置映射生成的拖尾从游戏启动时就会显示；通配符/数据包映射的拖尾则会在重新加载资源后生效（F3+T）。Epic Fight 本身或其他模组定义的拖尾始终优先于 CompatLink 生成的拖尾。

整合包/模组作者须知：将映射作为数据包发布

将映射文件放在任意数据包或模组 jar 中的 data//compatlink/mappings/*.json 路径下。它们会参与 /reload ，并按照相同的优先级规则与配置文件夹中的映射合并。现成的数据包： CompatLink: Simply Swords （已映射全部 122 把武器）——请查看项目页面侧栏。

实体映射（实验性）

你还可以通过 entities 数组为生物添加 Epic Fight 战斗 AI/动画。此功能仍处于 实验阶段，面向高级整合包作者：

{
“format”: 1,
“backend”: “epicfight”,
“entities”: [
{ “target”: “illagerinvasion:basher”, “preset”: “minecraft:vindicator” },
{ “target”: “illagerinvasion:necromancer”, “preset”: “minecraft:evoker” }
]
}

预设必须与目标共享相同的 模型族和纹理布局 （灾厄村民外形的生物需要使用灾厄村民预设，例如 minecraft:evoker/minecraft:vindicator；僵尸外形的生物则需要使用 epicfight:zombie 等）。设计上不支持自定义模型生物（GeckoLib Boss）。
内置安全保护：在连接任何内容之前，CompatLink 会比较目标与预设的纹理尺寸。如果不匹配，映射就会被拒绝，并记录清晰的日志消息（例如 texture size mismatch 64×128 vs 64×64 — mapping skipped），该生物将完全保持原版状态——不会出现模型损坏或崩溃。
验证十分严格：如果映射中的任何内容无法安全连接，CompatLink 都不会注册该映射，并会记录原因。
常见问题

服务器需要安装吗？客户端呢？
在专用服务器上，两端都需要安装——客户端和服务器都要安装 CompatLink（以及相同的映射文件）。单人游戏只需安装一份。

如果缺少 Epic Fight 会怎样？
不会出问题。CompatLink 会正常加载并解析你的文件，同时在日志中提示“backend ‘epicfight’ unavailable”。

映射文件里有拼写错误，游戏会崩溃吗？
不会。该文件会被跳过，并记录原因；其他内容仍会正常生效。

我应该下载哪个加载器/版本？
Forge 1.20.1（Java 17）请下载 compatlink-1.1.2.jar；NeoForge 1.21.1（Java 21）请下载 compatlink-neoforge-1.1.2.jar。两者功能相同，JSON 格式也相同。

能否支持其他战斗模组？
核心 API 是与加载器无关、采用 MIT 许可的后端 SPI。Epic Fight 是首个后端。

武器 params 有作用吗？
有—— impact、armor_negation、damage_bonus、speed_bonus 和 max_strikes 会完全按照 Epic Fight 数据包属性的方式应用。请参阅上文“调整武器属性”。