FreeMinecraftModels 配置

本页介绍当前 config.yml 与 shop_config.yml 中对设置、渲染、玩家交互以及可选家具商店有实质影响的设置项。

文件位置

plugins/FreeMinecraftModels/config.yml
plugins/FreeMinecraftModels/shop_config.yml

shop_config.yml 会在首次运行时生成；商店本身在你主动启用之前保持禁用。

`config.yml` 设置项

`setupDone`

默认值：false
控制首次设置指引是否视为已完成
在此值为 false 期间，拥有较广 FreeMinecraftModels 权限的玩家会收到提醒去运行 /fmm initialize
设置流程会自动切换该值，正常引导过程中无需手动编辑

`useDisplayEntitiesWhenPossible`

默认值：true
当服务器与客户端路径支持时，优先使用 display 实体来渲染
当 display 实体不可用时（低于 1.19.4 或基岩版客户端），插件仍会回退到盔甲架显示
基岩版客户端属于特例，因此不要假定它会为所有玩家强制使用同一渲染路径

`maxModelViewDistance`

默认值：60
限制模型化实体被发送给观察者的最大距离
较低的值能减少密集模型区域内的数据包和客户端渲染压力
单个实体可在运行时通过 ModeledEntity.setViewDistanceOverride(int) 覆盖此值 —— 参见 API 指南

`maxInteractionAndAttackDistance`

默认值：3
适用于静态和动态模型化实体
用于运行时的交互和命中检测

`maxInteractionAndAttackDistanceForProps`

默认值：6
适用于道具实体
此值与静态/动态实体的交互距离相互独立

`sendCustomModelsToBedrockClientsV2`

默认值：true
控制 FreeMinecraftModels 是否尝试向基岩版客户端发送自定义模型
此键替代了较旧的 sendCustomModelsToBedrockClients（其默认值为 false）。改名为 V2 后默认值被翻转，因此基岩版玩家默认就能看到模型；如果你以前显式设置了旧键，可以直接删除，由新的 V2 键接管
如果禁用，基岩版玩家会回退到底层的原版实体（若存在），且伪装对他们不会渲染
如果启用，请确保你的基岩版/Geyser/Floodgate 资源包链路已准备好向这些客户端分发资源
基岩版显示管线的运行时诊断日志不是配置项 —— 它通过 /fmm debug bedrock on|off 在运行时切换，避免在生产环境意外保持开启状态。参见命令

`shop_config.yml`

可选的、基于 Vault 的家具商店有自己的配置文件，可以与主插件的行为独立启用或调整。当 Vault 或经济提供方缺失时，商店会拒绝注册。

顶级键

键	默认值	描述
`enabled`	`false`	`/fmm shop` 的总开关。只有此项为 `true` 且同时存在 Vault 与经济提供方时，命令才会注册
`defaultPrice`	`100.0`	下次加载时写入到那些未设置 `shopPrice` 的配方文件中的价格
`menuTitle`	`&8FMM - Furniture Shop`	显示在商店物品栏顶部的标题（支持 `&` 颜色代码）
`priceLoreFormat`	`&7Price: &e{price}`	附加到每个商店物品的 Lore 行，用于显示价格。占位符：`{price}`
`clickToBuyLoreFormat`	`&aClick to purchase`	附加到每个商店物品的 Lore 行，提示进行购买

消息键（`messages.*`）

所有消息字符串都支持 & 颜色代码。

键	默认值	占位符
`messages.purchaseSuccess`	`&aPurchased &f{item} &afor &e{price}&a. Balance: &e{balance}&a.`	`{item}`、`{price}`、`{balance}`
`messages.insufficientFunds`	`&cYou need &e{price} &cto buy &f{item}&c. Balance: &e{balance}&c.`	`{item}`、`{price}`、`{balance}`
`messages.shopDisabled`	`&cThe furniture shop is currently unavailable.`	无
`messages.itemNotForSale`	`&cThat item is not currently for sale.`	`{item}`
`messages.inventoryFull`	`&eYour inventory was full; &f{item} &ehas been dropped at your feet.`	`{item}`

每条配方的商店字段

plugins/FreeMinecraftModels/recipes/<model_id>.yml 中的每个配方文件都会获得两个额外字段：

字段	默认值	描述
`shopEnabled`	`true`	该配方是否在 `/fmm shop` 中可见。`shopEnabled: false` 的配方仍然可以合成，但不会出现在购买列表中
`shopPrice`	`shop_config.yml` 中的 `defaultPrice`	该具体物品的 Vault 货币售价

配方编辑器（/fmm craftify）在保存时会写入这两个字段，所以调整价格只需做一次文本编辑即可。

权限

在 plugin.yml 中注册

权限	默认	描述
`freeminecraftmodels.*`	`op`	通配符，授予 admin + 自身/他人伪装权限
`freeminecraftmodels.admin`	`op`	可访问 `/fmm admin`（管理员内容浏览器）与 `/fmm giveitem`。其他管理/调试命令（`/fmm location`、`/fmm spawn`、`/fmm mount`、`/fmm itemify`、`/fmm craftify`、`/fmm reload`、`/fmm stats`、`/fmm hitbox visualize`、`/fmm debug bedrock`、`/fmm setup`、`/fmm initialize`、`/fmm downloadall`、`/fmm updatecontent`）检查的是通配符 `freeminecraftmodels.*`
`freeminecraftmodels.disguise.self`	`op`	允许在发送者本人身上使用 `/fmm disguise` / `/fmm undisguise`
`freeminecraftmodels.disguise.others`	`op`	允许针对目标玩家进行伪装/解除伪装，以及 `/fmm disguiselist`
`freeminecraftmodels.menu`	`true`	可访问 `/fmm` 可制作物品菜单
`freeminecraftmodels.shop`	`true`	可访问 `/fmm shop`

由命令强制执行（未在 plugin.yml 中注册）

权限	默认	描述
`freeminecraftmodels.deleteall`	`op`	可访问 `/fmm deleteall`（由命令处理器在运行时检查）

模型 YML 配置

每个 .bbmodel 文件都可以拥有一个同名同目录的 .yml 配套文件，用于控制特定于该模型的设置。统一的 YML 格式支持以下字段：

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
  - "&7Deals frost damage"
enchantments:
  - SHARPNESS,3
  - UNBREAKING,2

字段	类型	描述
`isEnabled`	布尔值	模型是否被加载（默认：`true`）
`scripts`	字符串列表	要附加的 Lua 脚本文件名（来自 `plugins/FreeMinecraftModels/scripts/`）
`voxelize`	布尔值	为 `true` 时，道具放置时会按 90 度旋转对齐并对齐到方块网格。占地面积根据模型的碰撞箱尺寸计算（向上取整为整方块）。放置时会检查占地面积内所有方块均为非实心
`solidify`	布尔值	为 `true` 时（需要 `voxelize: true`），会在道具占地面积内的每个方块放置仅存在于数据包中的屏障方块，从而提供客户端侧的碰撞。这些屏障是不可见的，仅存在于数据包中，并不会真实写入世界。当道具被拾取或销毁时，屏障会自动移除
`material`	字符串	Bukkit 材质名称（如 `DIAMOND_SWORD`、`PAPER`）。设置后，该模型将成为玩家可手持和装备的自定义物品
`name`	字符串	自定义物品的显示名称（支持 `&` 颜色代码）
`lore`	字符串列表	自定义物品的 Lore 行（支持 `&` 颜色代码）
`enchantments`	字符串列表	`ENCHANTMENT_NAME,LEVEL` 格式的附魔（如 `SHARPNESS,3`）

当设置 material 时，该模型会被注册为自定义物品。玩家可通过 /fmm giveitem 获得它，若配置了配方还可合成，并可使用全部 22 个 Lua 物品钩子。

运行说明

/fmm reload 会重新导入内容并重新生成输出资源包，因此影响渲染行为的配置变更最容易在重载后验证。每次重载时都会派发 FmmReloadedEvent，依赖插件可借此重新绑定其模型附着。
FreeMinecraftModels 只负责生成资源包，并不会自行托管。
对于 Java 客户端，ResourcePackManager 仍是推荐的分发途径；对于混合环境，也是文档明确推荐的最稳妥路径。
在 plugin.yml 中，WorldGuard、WorldEdit、GriefPrevention 和 Vault 被声明为 softdepend —— 它们都不是启动插件所必需的，但当它们存在时会解锁特定功能（保护区感知的 Lua 谓词和家具商店）。

何时该改这些值

本配置用于运行时行为调优，而不是内容包管理。

官方包的生命周期管理请使用 /fmm initialize、/fmm setup、/fmm downloadall 和 /fmm updatecontent
手动 .bbmodel 或其他本地内容导入请使用 imports 文件夹
需要调整渲染模式、可视距离、交互距离或基岩版行为时使用 config.yml
不必动代码就能调优家具商店时，使用 shop_config.yml（以及每条配方的 shopEnabled/shopPrice 字段）

已知注意事项

基岩版行为同时取决于 sendCustomModelsToBedrockClientsV2 与你更大范围的 Floodgate/Geyser/资源包链路，因此除非你已经在你具体的栈上验证过，否则请保持保守的承诺。
当 Vault 或经济提供方缺失时，商店会静默禁用自身。如果 /fmm shop 意外消失，请使用 /fmm version 并检查启动时的控制台。

文件位置​

config.yml 设置项​

setupDone​

useDisplayEntitiesWhenPossible​

maxModelViewDistance​

maxInteractionAndAttackDistance​

maxInteractionAndAttackDistanceForProps​

sendCustomModelsToBedrockClientsV2​

shop_config.yml​

顶级键​

消息键（messages.*）​

每条配方的商店字段​

权限​

在 plugin.yml 中注册​

由命令强制执行（未在 plugin.yml 中注册）​

模型 YML 配置​

运行说明​

何时该改这些值​

已知注意事项​