忠诚的伙伴

---

✨ 关于忠诚伙伴

忠诚伙伴 为 Minecraft 添加了一套完整的伙伴成长系统。友好生物可以成为拥有自己的 等级、经验值、技能点、物品栏、装备、稀有度、饰品、行为模式、HUD 以及 复活机制 的个人宠物。

你的伙伴可以跟随你、与你并肩作战、携带物品、穿戴特殊装备、装备魔法宝石和护身符、作为可转移的图腾储存起来，并在战斗中倒下后通过魔法祭坛回归。

忠诚伙伴还包含一个 兼容性 API 和一个 配置白名单系统，允许模组开发者和整合包作者为来自其他模组的友好生物添加支持。

---

⭐ 主要特性

• 🐾 捕捉友好生物 并将其转化为忠诚伙伴
• 📈 自定义升级系统，包含经验值、等级和技能点
• 💪 升级伙伴属性：
  • 力量 — 增加伤害
  • 防御 — 提高保护能力
  • 攻击速度 — 减少攻击冷却时间
  • 活力 — 增加最大生命值
• 🌟 稀有度系统，带有属性加成和彩色视觉效果
• ✨ 强化伙伴，体型更小且拥有额外物品栏潜力
• 🖥️ 自定义伙伴菜单，包含计算数值和 3D 预览
• 📊 可移动的伙伴 HUD，显示生命值、经验值、等级、名称和模型预览
• 🎒 宠物物品栏，包含普通槽位、食物槽、装备槽、宝石槽、护身符槽和额外槽位
• ⌨️ 可配置按键，直接打开当前伙伴的物品栏
• 🛡️ 伙伴装备，包含鞍具和护甲板
• 💎 伙伴宝石和护身符，带有独特的属性加成和战利品来源
• 🩹 宠物治疗物品，包含小型、中型和大型绷带
• ⚔️ 行为模式，包括安全的怪物目标和全面生物目标
• 🍖 喂食系统，基于每个伙伴的生物类型
• 📣 伙伴哨子，带有宠物选择菜单
• 🧿 伙伴图腾，用于储存、转移和复活宠物
• 🛕 伙伴祭坛，带有复活动画和宠物储存功能
• 💔 伙伴之心，由铁傀儡掉落，用于复活
• 🔌 公共只读 API，供其他模组检测伙伴、主人、等级、属性和伙伴伤害来源
• 🧩 模组生物兼容性 API，供其他模组作者使用
• 📜 配置白名单和黑名单，供整合包作者和用户使用
• 👥 可选的 PartyLink 兼容性
• ⚙️ 服务器和单人游戏配置，用于重要的游戏玩法设置

---

🐕 捕捉与训练伙伴

对友好生物使用 捕捉护符 可将其绑定为你的伙伴。你的宠物会跟随你、获得经验值、升级，并随时间推移变得更强。

每升一级可获得 1 点技能点，可在伙伴菜单中分配。将你的宠物培养成更强的战士、更坚韧的守卫、更迅捷的攻击者或更耐久的旅行伙伴。

---

🌟 稀有度与强化伙伴

伙伴可以拥有 稀有度，为其提供额外的基础属性加成和彩色视觉效果。强化状态独立于稀有度，因此一个伙伴可以同时是 强化 和 传说 级别的。

• 普通 — 无额外属性点
• 稀有 — 每项属性 +1
• 史诗 — 每项属性 +3
• 传说 — 每项属性 +5

强化伙伴体型更小，外观特殊，并且在更高等级时可以解锁额外的物品栏空间。

---

🎒 宠物物品栏

伙伴拥有自己的物品栏界面，带有自定义槽位和提示信息。当前伙伴的物品栏也可以通过可配置的按键直接打开。

• 9 个普通物品栏槽位
• 1 个食物槽
• 1 个装备槽
• 1 个宝石槽
• 1 个护身符槽
• 9 个额外槽位，适用于 20 级的强化伙伴

该物品栏包含玩家物品栏和快捷栏，方便移动物品。物品名称和描述会直接显示在自定义界面中。

---

🛡️ 伙伴装备

为你的伙伴装备特殊装备，以提升其战斗力和生存能力。

• 伙伴皮革鞍具
• 伙伴铁护甲板
• 伙伴金护甲板
• 伙伴钻石护甲板
• 伙伴下界合金护甲板

装备可以提供护甲、生命值和攻击速度等加成。已装备的装备还会为你的伙伴增加一些微小的视觉效果。

---

💎 宝石与护身符

忠诚伙伴为你的宠物添加了魔法 宝石 和 护身符。这些饰品提供额外的属性加成，可以通过合成、村庄战利品、地牢战利品、下界敌人、Boss 以及末影龙获得。

💠 宝石

• 霜缚宝石 — 可合成的入门宝石
• 翠绿宝石 — 可在村庄战利品中找到
• 猩红迷宫宝石 — 可在战利品箱中找到
• 魂焰宝石 — 凋灵骷髅的稀有掉落物
• 龙棱宝石 — 强大的末影龙掉落物

🧿 护身符

• 守护者之心护身符 — 可合成的入门护身符
• 村庄守护者护身符 — 可在村庄战利品中找到
• 寻路者护身符 — 可在战利品箱中找到
• 幽魂骨护身符 — 凋灵的掉落物
• 龙眼护身符 — 强大的末影龙掉落物

最强的饰品被设计为稀有的 Boss 奖励，为末影龙提供了有价值的、以伙伴为核心的战利品进度。

---

🩹 宠物治疗物品

伙伴可以使用专用绷带进行治疗。

• 小型伙伴绷带 — 恢复少量生命值
• 中型伙伴绷带 — 恢复中等量生命值
• 大型伙伴绷带 — 恢复大量生命值

这些物品使长途冒险、地牢探险和 Boss 战对你的伙伴来说更加安全。

---

⚔️ 行为模式

• 跟随 — 正常跟随玩家
• 等待 — 停留在原地
• 被动 — 不进行攻击
• 保护 — 保护玩家免受附近威胁
• 坏怪物 — 仅攻击明显敌对的怪物敌人
• 所有生物 — 攻击大多数生物，同时仍保护玩家、村民、商人和伙伴

这使你可以选择安全的仅怪物模式，或用于狩猎的更强攻击模式。

---

📣 伙伴哨子与宠物槽位

伙伴哨子 会打开一个宠物选择菜单。根据配置，玩家可以管理多个伙伴槽位。

为了稳定性和平衡性，一次只能激活一个伙伴。在召唤另一个已储存的伙伴之前，请先让当前宠物消失。

---

🛕 伙伴祭坛与复活

当伙伴倒下时，它会被储存在一个 伙伴图腾 中。图腾包含重要的宠物数据，例如名称、生物类型、等级、属性、物品栏、稀有度、强化状态以及支持的特定生物数据，如狐狸类型、狼类型、马的颜色、鞍、马铠和所有权。

要复活倒下的伙伴，需将 伙伴图腾 和 伙伴之心 放入 伙伴祭坛 中。祭坛会播放一段简短的复活动画，之后恢复宠物。

你也可以使用祭坛将你当前的伙伴储存为图腾，而无需杀死它。这使得在玩家之间交易或转移宠物成为可能。

---

🧩 模组生物兼容性

忠诚伙伴包含两种方式来支持来自其他模组的友好生物：

• 开发者 API — 适用于希望添加直接支持的模组作者
• 配置白名单 — 适用于希望手动启用特定模组生物的整合包作者或用户

此系统对于添加友好动物、野生动物、奇幻生物或可驯服生物的模组非常有用。例如，本描述使用 WildCreatures 作为示例。

📜 配置示例：WildCreatures

在您的 Loyal Companions 配置中添加如下条目：

companion_entity_whitelist=wildcreatures:crab companion_entity_blacklist=wildcreatures:shark,wildcreatures:jellyfish,wildcreatures:mussel companion_food_overrides=wildcreatures:crab=minecraft:wheat

在此示例中：

• wildcreatures:crab 可以被捕捉为伙伴
• wildcreatures:shark、wildcreatures:jellyfish 和 wildcreatures:mussel 被禁止
• 螃蟹接受 小麦 作为伙伴食物

🍖 食物覆盖格式

简单的单物品食物覆盖：

companion_food_overrides=wildcreatures:crab=minecraft:wheat

多个可接受的食品物品：

companion_food_overrides=wildcreatures:crab=minecraft:wheat|minecraft:apple|minecraft:carrot

带翻译键的自定义显示文本：

companion_food_overrides=wildcreatures:crab=food.wildcreatures.crab|minecraft:wheat|minecraft:apple

当仅配置一个食物物品时，伙伴菜单将自动显示物品名称，例如显示 小麦 而不是通用的“已配置食物”标签。

🧪 开发者 API 示例

其他模组可以直接注册他们自己的伙伴支持：

LoyalCompanionsApi.allowCompanionEntity("wildcreatures:crab");

LoyalCompanionsApi.setCompanionFood( "wildcreatures:crab", "food.wildcreatures.crab", "minecraft:wheat", "minecraft:apple" );

LoyalCompanionsApi.blockCompanionEntity("wildcreatures:shark"); LoyalCompanionsApi.blockCompanionEntity("wildcreatures:jellyfish");

黑名单条目始终优先于白名单或 API 注册。该实体仍需是有效的生物实体，因此不会偶然使技术性或非安全实体具有伙伴兼容性。

---

🔌 面向其他模组的公共只读 API

忠诚伙伴提供了一个公共 只读 API，以便其他模组能够安全地检测伙伴、检查所有权、读取伙伴属性，并识别伙伴伤害来源，而无需访问内部模组类。

这对于地牢模组、Boss 模组、战斗平衡模组、队伍系统、领地保护模组，以及诸如 Solo Mining 之类需要区别对待伙伴伤害与玩家伤害的模组非常有用。

API 类：

com.mki.loyalcompanions.api.LoyalCompanionsApi

🐾 伙伴检测

其他模组可以检查实体是否为 Loyal Companions 宠物：

if (LoyalCompanionsApi.isCompanion(attacker)) {
    // 此处可以处理伙伴造成的伤害
}

可用的方法：

public static boolean isCompanion(Entity entity)
public static boolean isOwnedCompanion(Entity entity, UUID ownerUuid)
public static Optional<UUID> getCompanionOwner(Entity entity)
public static boolean isOwnedByPlayer(Entity entity, ServerPlayer player)

📊 伙伴属性

其他模组可以安全地读取伙伴的成长数值：

public static int getCompanionLevel(Entity entity)
public static int getCompanionAttack(Entity entity)
public static int getCompanionStrength(Entity entity)
public static int getCompanionDefense(Entity entity)
public static int getCompanionVitality(Entity entity)

这些值是只读的，不会修改伙伴。

⚔️ 伤害来源辅助方法

对于战斗相关模组，API 还提供了辅助方法来检查伤害是否来自伙伴：

public static boolean isCompanionDamageSource(DamageSource source)
public static Optional<LivingEntity> getCompanionAttacker(DamageSource source)

示例：

LoyalCompanionsApi.getCompanionAttacker(source).ifPresent(companion -> {
    // 伤害是由 Loyal Companions 宠物造成的
});

🎒 已储存伙伴辅助方法

其他模组也可以检查物品堆叠是否包含已储存的伙伴：

public static boolean isStoredCompanion(ItemStack stack)

🔒 API 安全性

公共 API 故意设计为 只读。它仅用于兼容性和检测目的。

其他模组应使用：

com.mki.loyalcompanions.api.LoyalCompanionsApi

并且不应直接访问内部类，例如：

com.mki.loyalcompanions.companion.CompanionData

---

👥 可选的 PartyLink 支持

忠诚伙伴包括与 PartyLink 的可选兼容性。如果安装了 PartyLink，队伍伙伴将受到保护，免受友军伤害。

• 队伍成员的宠物不会互相攻击
• 尊重队伍的 PvP 设置
• 未安装 PartyLink 时，模组仍可正常工作

---

⚙️ 配置

忠诚伙伴支持对专用服务器和本地单人世界进行单独的配置处理。

• 启用或禁用伙伴复活
• 伙伴之心的掉落几率
• 强化伙伴几率
• 稀有度几率
• 最大伙伴等级
• 每个玩家可管理的最大伙伴槽位数
• 保护模式半径
• 攻击模式半径
• 伙伴糖果的最大额外技能点数
• 伙伴糖果和战利品行为
• 模组伙伴白名单
• 模组伙伴黑名单
• 模组伙伴食物覆盖

---

🧭 适合用于

• 生存世界
• 冒险整合包
• RPG 风格成长
• 多人游戏服务器
• 希望宠物具有真正游戏价值的玩家
• 包含自定义野生动物和友好生物的整合包

---