FreeMinecraftModels 配置

config.yml 中的 registerCraftingRecipes 默认为 true。如需仅允许购买，请设为 false 并重启：配方仍显示在菜单和商店中，但 Bukkit 合成配方会被移除。本页的合成步骤要求该设置为 true。

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

文件位置

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

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

最低服务器版本

plugin.yml 声明了 api-version: 1.21.4，因此 Minecraft 1.21.4 是受支持的最低服务器版本。对更老版本线的支持已被移除；代码中仍存在旧的渲染/输出分支，但在能够加载本插件的服务器上已经无法触及。

config.yml 设置项

setupDone

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

nightbreak.autoDownloadPluginUpdates

• 默认值：false
• 共享的 MagmaCore 设置（位于 config.yml 的 nightbreak: 区块下）
• 为 true 时，FreeMinecraftModels 会在启动时自动下载可用的插件 jar 更新以及内容更新文件
• 下载的插件和内容更新只有在服务器重启后才会生效
• 自动下载插件需要一个有效的 Nightbreak 账户令牌以及一个有效的支持者 Patreon 会员资格。两者缺一时，请把它保持为 false 并改用游戏内的更新按钮
• 这相当于每次启动时都运行 /fmm downloadpluginupdate / /fmm downloadall 的配置项写法；可从 /fmm setup 菜单中切换，也可手动修改

useDisplayEntitiesWhenPossible

• 默认值：true
• 当服务器与客户端路径支持时，告知 FreeMinecraftModels 优先使用 display 实体来渲染
• 当 display 实体不可用时，插件仍会回退到盔甲架显示（配置注释中提到的是早于 1.19.4 的服务器和基岩版客户端；实际上当前插件声明了 api-version: 1.21.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 在运行时切换，避免在生产环境意外保持开启状态。参见 命令

skipUnchangedBoneUpdates

• 默认值：true
• 为 true 时，模型骨骼只有在其位置、旋转或缩放自上一 tick 起确实发生变化时，才会向观察者发送每 tick 的移动/元数据数据包
• 完全静止的骨骼（静态道具、模型中闲置的部件）什么都不发送，这会大幅削减 NPC 中枢、城镇等密集区域的每客户端数据包负载
• 周期性的完整重新同步仍会运行，因此任何罕见的客户端漂移都能自愈
• 只有在为了调试而需要恢复旧的"每 tick 重发每根骨骼"行为时，才把它设为 false

useDeltaMetadataPackets

• 默认值：true
• 为 true 时，展示实体模型骨骼的每 tick 元数据数据包只发送发生变化的值（该骨骼的变换），而不是每 tick 都重新序列化整个 item-display 数据块（物品模型 + 自定义模型数据）
• 当玩家首次看到某个模型时以及在周期性重新同步时，仍会发送完整状态
• 为了调试或对比而需要恢复旧的"每 tick 完整快照"行为时，把它设为 false

maxModelsForProximityOverride

• 默认值：25
• 近距离可见性覆盖的伪负载均衡器
• 通常，处于玩家 10 格范围内的模型总是会被显示，跳过视线射线检测，这样你身旁的模型就不会突然弹出
• 在密集区域（例如多层的 NPC 中枢），这一覆盖会把玩家实际根本看不到的数十个模型 —— 位于其他楼层、墙壁背后 —— 变成每 tick 都发包的观察对象
• 当某个世界中已加载的模型数量达到或超过该值时，近距离覆盖会在那个世界中被禁用，于是即便在近处也会运行遮挡射线检测，剔除玩家没有视线的模型。稀疏的世界仍保留该覆盖，因此也保留不弹出的表现
• 该判断是按世界而非全局进行的，因此拥挤的中枢世界不会拖累安静的世界
• 把它调得非常高即可实际恢复始终覆盖的行为；设为 0 则始终要求视线可见
• /fmm packetdebug 是用来测量其效果的工具 —— 参见命令

preventPropPlacementInProtectedRegions

• 默认值：true
• 为 true 时，FreeMinecraftModels 会询问 MagmaCore 已注册的保护提供者：这位具体的玩家是否可以在道具将要占据的格子里建造；如果答案是否，则拒绝此次放置
• 拥有 freeminecraftmodels.bypassregionprotection 权限（默认：op）的玩家会完全跳过该检查，永远不会被阻止
• 内置的感知玩家的提供者目前覆盖 WorldGuard 和 GriefPrevention。任何其他插件都可以注册一个 MagmaCore 保护提供者并获得同样的对待。若没有注册任何提供者，此检查不产生效果
• 拒绝时的消息为 You don't have permission to place a model here!

该检查是感知玩家的，而不是感知区域的。 早期版本问的是"这个位置是否位于任何受保护区域内？"并阻止所有人。当前的检查问的是"这位玩家可以在这里建造吗？"，因此正当拥有该领地、或作为其受信任成员、或身处自己 WorldGuard 区域内的玩家，都能正常在那里放置道具。只有那些本来就无法在该格子放置原版方块的玩家才会被拒绝。

每次放置都会进行一次单格检查；体素化道具还会额外进行一次覆盖整个体积的检查：

道具类型	检查的格子
普通（自由形态）道具	与被点击方块面相邻的那一个格子 —— 也就是道具将要占据的格子
voxelize: true 道具	先检查同一个相邻格子，然后检查围绕网格对齐放置点的道具旋转后占地范围（宽 x 高 x 深）内的每一个格子。只要该体积中任意一个格子不可用，整次放置就会被拒绝

体积检查之所以存在，是因为体素化道具可能有好几格宽，只测试被点击的格子会让玩家跨在领地边界上把一个大型道具塞进别人的建筑里。它在空间检查之后运行，因此当占地范围在物理上被阻挡时，Not enough space to place this model! 仍然优先。

备注

绕过权限是在提供者查询之前检查的，因此授予 freeminecraftmodels.bypassregionprotection 是让管理人员在任意位置放置道具的受支持做法，无需在全服范围内关闭此配置项。

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、deleteall、自身/他人伪装以及绕过区域保护的权限
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、/fmm packetdebug、/fmm setup, /fmm initialize、/fmm recommendedplugins、/fmm downloadall、/fmm downloadallcontent、/fmm updatecontent、/fmm downloadpluginupdate、/fmm forcereinstallcontent）检查的是通配符 freeminecraftmodels.*
freeminecraftmodels.deleteall	op	通配符的子权限；可访问 /fmm deleteall
freeminecraftmodels.disguise.self	op	允许在发送者本人身上使用 /fmm disguise / /fmm undisguise
freeminecraftmodels.disguise.others	op	允许针对目标玩家进行伪装/解除伪装，以及 /fmm disguiselist
freeminecraftmodels.bypassregionprotection	op	即使启用了 preventPropPlacementInProtectedRegions，仍可在任何其他插件会阻止普通方块放置的地方放置道具并与之交互
freeminecraftmodels.menu	true	可访问 /fmm 可制作物品菜单
freeminecraftmodels.shop	true	可访问 /fmm shop
nightbreak.login	op	由 MagmaCore 注册，而不是由 plugin.yml 注册。共享的 /nightbreaklogin 与 /nightbreaklogout 命令需要它

模型 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	字符串列表	要从 plugins/FreeMinecraftModels/scripts/ 附加的 Lua 脚本文件名。为清晰起见可包含 .lua；不带 .lua 的配置条目也会被接受并解析为对应的 .lua 文件。
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 物品钩子。

道具会将 scripts: 下列出的每个脚本作为独立实例运行。自定义物品目前只使用列表中第一个有效脚本；第一个之后的其他条目在物品运行时绑定时会被忽略。

运行说明

• /fmm reload 会重新导入内容并重新生成输出资源包，因此影响渲染行为的配置变更最容易在重载后验证。每次重载时都会派发 FmmReloadedEvent，依赖插件可借此重新绑定其模型附着。
• 生成的资源包是字节稳定的，因此在模型集未变化的情况下重新生成会得到完全相同的 zip 和 SHA1。正是这一点让 ResourcePackManager 能够跳过多余的重新上传。参见 资源包输出。
• FreeMinecraftModels 只负责生成资源包，并不会自行托管。
• 对于 Java 客户端，ResourcePackManager 仍是推荐的分发途径；对于混合环境，也是文档明确推荐的最稳妥路径。
• 在 plugin.yml 中，WorldGuard、WorldEdit、GriefPrevention、Vault、floodgate 和 Geyser-Spigot 被声明为 softdepend —— 它们都不是启动插件所必需的，但当它们存在时会解锁特定功能：WorldGuard/WorldEdit/GriefPrevention 同时喂给保护区感知的 Lua 谓词和感知玩家的道具放置检查，Vault 启用家具商店，而 floodgate/Geyser-Spigot 启用基岩版渲染后端。

何时该改这些值

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

• 官方包的生命周期管理请使用 /fmm setup、/fmm downloadall 和 /fmm updatecontent
• 手动 .bbmodel 或其他本地内容导入请使用 imports 文件夹
• 需要调整渲染模式、可视距离、交互距离、基岩版行为、保护区强制执行或自动更新下载时使用 config.yml
• 在模型密集的世界里进行数据包/带宽调优时，使用 skipUnchangedBoneUpdates、useDeltaMetadataPackets 和 maxModelsForProximityOverride。这三项都默认为已优化的行为；false / 极高的取值是为调试和 A/B 对比而存在的，并不是推荐的生产配置
• 不必动代码就能调优家具商店时，使用 shop_config.yml（以及每条配方的 shopEnabled/shopPrice 字段）

已知注意事项

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