跳到主要内容

玩家伪装

FreeMinecraftModels 可以将任何在线玩家伪装为已加载的模型。伪装由命令、公共 DisguiseAPI 以及每位玩家对应的 PlayerDisguiseEntity 共同驱动，后者负责处理被伪装玩家的不可见性与模型渲染。

命令​

命令权限说明
/fmm disguise <modelID>freeminecraftmodels.disguise.self伪装发送者。仅限玩家
/fmm disguise <modelID> <player>freeminecraftmodels.disguise.others伪装指定玩家。可从控制台执行
/fmm undisguisefreeminecraftmodels.disguise.self解除发送者的伪装。仅限玩家
/fmm undisguise <player>freeminecraftmodels.disguise.others解除指定玩家的伪装。可从控制台执行
/fmm disguiselistfreeminecraftmodels.disguise.others列出所有处于伪装中的玩家及各自的伪装模型

通配符 freeminecraftmodels.* 在 OP 默认下同时授予三个权限（admin、disguise.self、disguise.others）。

行为​

  • 对已经伪装的玩家执行伪装时，会干净地替换之前的伪装 —— 无需先解除伪装。
  • 被伪装的玩家对其他玩家保持不可见，因此只看得到模型。被伪装的玩家自己仍能正常看到自己。
  • 不可见效果在喝牛奶、信标效果清除以及其他通常会清除效果的交互后仍会持续。
  • 玩家的碰撞箱保持不变。怪物的目标选定、碰撞与 PvP 都照常工作。
  • 伪装不会在服务器重启后保留。它们只在内存中追踪。
  • 执行 /fmm reload 时，所有活动伪装会作为插件关闭流程的一部分被销毁。重载后玩家需要重新被伪装。

基岩版客户端​

伪装依赖 FMM 渲染自定义模型。要让基岩版玩家看到伪装，你必须在 config.yml 中设置 sendCustomModelsToBedrockClients: true，并具备基岩版兼容的资源包链路（Floodgate + Geyser + 转换后的资源包）。若未正确配置，基岩版玩家既看不到模型也看不到底层的不可见玩家 —— 在被伪装玩家所站的位置，他们什么也看不到。

DisguiseAPI​

第三方插件可以通过 com.magmaguy.freeminecraftmodels.api.DisguiseAPI 以编程方式驱动伪装。

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// 伪装（若模型 ID 未加载则返回 false）
boolean ok = DisguiseAPI.disguise(player, "dragon");

// 解除伪装（若有伪装被移除则返回 true）
DisguiseAPI.undisguise(player);

// 查询
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // 未伪装时为 null

// 所有伪装玩家的不可修改快照
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

该 API 是公共的、对重构安全的入口。插件应调用 DisguiseAPI，而不是内部的 DisguiseManager。

常见用例​

  • 角色扮演与 RPG 服务器： 在电影化片段或任务脚本中将玩家伪装为 Boss 模型。
  • 活动主持： 将主持人伪装为巨大的自定义模型。
  • 坐骑与载具： 将 /fmm mount 与 /fmm disguise 结合，搭建创意的运输方案。
  • EliteMobs 集成： Boss 脚本可以将触发事件的玩家伪装，作为临时变身效果。

故障排查​

我执行 /fmm disguise dragon 后什么都没发生。 模型 ID 必须与某个已加载模型完全匹配。请通过 /fmm admin 或 /fmm stats 验证模型名称。如果发送者没有 freeminecraftmodels.disguise.others，FMM 故意返回通用的"无效实体 ID"消息（即便该模型确实存在）—— 这是为了避免向未授权玩家泄露已加载模型的 ID 列表。

我的伪装在 /fmm reload 后消失了。 这是预期行为。所有伪装都会在重载时被销毁。如需在重载后自动重新应用伪装，请监听 FmmReloadedEvent。

基岩版玩家看不到伪装。 请参阅上方的 基岩版客户端。

被伪装玩家对其他人仍然可见。 不可见性是以数据包级别的效果应用的。如果有另一个插件每刻都强制移除不可见性（一些反作弊插件会这么做），它就会和 FMM 的重新应用相冲突。请将 FMM 列入白名单或禁用冲突的检查。