上一页：物品类插件.md · 下一页：经济插件.md 相关：../02-服主指南/自定义方块.md · ../04-开发者/工具集.md · 概览.md
🧱 方块 / 模型 / 作物对接
除了「取物品」，QCL 还把三类世界交互能力接了进来：CraftEngine 的方块与家具、ModelEngine 的模型化实体、CustomCrops 的作物。它们一样遵循软依赖 + 反射桥：没装就静默不可用，绝不影响启动。
🧰 共同基座：本页所有桥的「多版本多签名兼容」都建立在
ReflectionBridge/ReflectionCache之上 —— 同一个插件不同大版本的方法签名都能被自动找对。开发者细节见 👉 ../04-开发者/工具集.md。
🛠️ 一、CraftEngine —— 物品 / 方块 / 家具
| 项目 | 内容 |
|---|---|
| 桥类 | CraftEngineBridge / CraftEngineManager |
| 涉及三类对象 | 自定义物品、自定义方块、自定义家具 |
CraftEngine 的物品引用（ce-命名空间_id）见 物品类插件.md。本页关注它的方块与家具能力。
🔧 CraftEngineManager 能力表
| 能力 | 签名 | 作用 |
|---|---|---|
| 构建物品 | buildItemStack(标识, 数量) | 取 CraftEngine 物品 |
| 放置方块 | placeBlock(位置, blockId, playSound) | 在指定位置放自定义方块，可选播放音效 |
| 移除方块 | removeBlock(方块) | 移除自定义方块 |
| 判断自定义方块 | isCustomBlock(方块) | 这个方块是不是 CraftEngine 自定义方块 |
| 读方块 id | getCustomBlockId(方块) | 取自定义方块的 id |
| 放置家具 | placeFurniture(位置, 家具id) → 实体 | 放家具，返回家具实体 |
| 移除家具 | removeFurniture(实体) | 移除家具 |
| 判断家具 | isFurniture(实体) | 这个实体是不是家具 |
| 读家具 id | getFurnitureId(实体) | 取家具 id |
🪑 方块 vs 家具：CraftEngine 把「能踩在上面的方块」和「摆设实体（家具）」分成两套对象，所以放置/识别 API 也分两套 —— 方块用
*Block，家具用*Furniture。
🧩 CustomBlock 抽象层 —— 不绑死 CraftEngine
QCL 在 CraftEngine 之上又抽象了一层「自定义方块」，让上层逻辑不直接依赖某个具体插件：
| 组件 | 角色 |
|---|---|
CustomBlockBridge | 聚合器：把所有「自定义方块提供者」汇总 |
CustomBlockProvider | 接口：id / isAvailable / isCustomBlock / getCustomBlockId / getCustomBlockAt |
CraftEngineBlockProvider | 内置提供者，id = craftengine |
CustomBlockConfig | 自定义方块的服主配置（见自定义方块页） |
这意味着：以后再接别的方块插件，只要再实现一个 CustomBlockProvider 即可，上层无感。
服主侧如何配置自定义方块（掉落、行为等），见 👉 ../02-服主指南/自定义方块.md。
🎯 典型用途
- GUI / 脚本里程序化放置一个 CraftEngine 方块或家具。
- 监听玩家破坏方块时，用
isCustomBlock+getCustomBlockId判定「这是不是我配置的自定义方块」，从而决定掉落。
🤖 二、ModelEngine —— 模型化实体 / 动画 / 骨骼持物
| 项目 | 内容 |
|---|---|
| 桥类 | ModelEngineBridge / Manager |
| 检测类 | com.ticxo.modelengine.api.ModelEngineAPI |
ModelEngine 让一个普通实体「穿上」一个 3D 模型，并播放动画。QCL 把这套能力包装成更顺手的 API。
🔧 桥能力表
| 能力 | 作用 |
|---|---|
createModeledEntity(实体) | 把一个实体变成模型化实体 |
removeModeledEntity(...) | 取消模型化 |
getModeledEntity(...) | 取一个实体的模型化包装 |
createActiveModel(模型id) | 创建一个激活模型实例 |
📦 包装器 API
QCL 提供两个包装器，把反射调用收敛成清爽方法：
ModeledEntityWrapper（模型化实体包装）
| 方法 | 作用 |
|---|---|
addModel(...) | 给实体加一个模型 |
removeModel(...) | 移除模型 |
setBaseEntityVisible(...) | 设置底层实体是否可见（常用来隐藏原版形体只显示模型） |
destroy() | 销毁 |
getModels() | 取当前所有模型 |
ActiveModelWrapper（激活模型包装）
| 方法 | 作用 |
|---|---|
playAnimation(名, 速度, force) | 播放指定动画 |
getBones() | 取骨骼列表 |
setHeldItem(骨骼, 物品) | 让某根骨骼「拿着」一个物品 |
⚡ Manager 快捷方法
| 方法 | 作用 |
|---|---|
spawnModel(实体, 模型id, 隐藏底实体) | 一步：生成模型并可选隐藏底层实体 |
playAnimation(...) | 播放动画 |
setHeldItem(...) | 骨骼持物 |
🔄 桥对这些方法做了多签名兼容，应对 ModelEngine 不同版本的 API 差异。
🎯 典型用途
- 生成一个带模型的 Boss / NPC，隐藏底层实体只显示模型。
- 触发攻击/受击/死亡时
playAnimation播放对应动画。 - 用
setHeldItem让模型某根骨骼（手部）拿上武器物品。
🌾 三、CustomCrops —— 作物识别 / 收获 / 种植 / 生长 / 骨粉
| 项目 | 内容 |
|---|---|
| 桥类 | CustomCropsBridge / Manager |
| 检测类 | net.momirealms.customcrops.api.CustomCropsAPI |
CustomCrops 提供一套自定义农作物系统，QCL 把它的核心动作都桥接了出来。
🔧 能力表
| 能力 | 作用 |
|---|---|
isCrop(方块 / 位置) | 这个方块/位置是不是作物 |
getCropId(...) | 取作物 id |
tryHarvest(方块, 玩家?) | 尝试收获（玩家参数可选） |
tryPlant(位置, 玩家, 物品, cropId) | 尝试种植 |
tryGrow(位置, 骨粉?, 倍率?) | 尝试催生长（可带骨粉、生长倍率） |
isBoneMeal(物品) | 这个物品是不是骨粉 |
getBoneMealItem() | 取骨粉物品 |
🌱
try*系列方法返回的是「是否成功」语义，调用方可据此决定后续逻辑（如扣体力、给经验）。
🎯 典型用途
- 自定义农场玩法：脚本里
tryPlant帮玩家种地、tryHarvest一键收割。 - 道具效果：某个道具触发
tryGrow给周围作物催熟。 - 判定
isCrop/getCropId，让 GUI 或任务系统识别玩家面前的作物。
🧰 共同兼容基座：ReflectionBridge
再强调一次：上面所有桥的「多版本多签名兼容」都依赖底层的：
ReflectionBridge——isClassAvailable(类名)探测目标类是否存在。ReflectionCache—— 缓存方法/字段查找（getMethod/findMethodByName/invoke/safeCall…）。
开发者若要在自己代码里复用这套反射工具，见 👉 ../04-开发者/工具集.md。
📚 继续阅读
- 🧱 ../02-服主指南/自定义方块.md —— CustomBlockConfig 服主配置。
- 🔧 ../04-开发者/工具集.md —— ReflectionBridge / ReflectionCache。
- 🎒 物品类插件.md —— CraftEngine / 其它插件的物品引用。
- 💰 经济插件.md —— 三经济后端对接。