Previous: 物品类插件.md　·　Next: 经济插件.md Related: ../02-服主指南/自定义方块.md · ../04-开发者/工具集.md · 概览.md

🧱 Block / Model / Crop Integration

Beyond "fetching items", QCL also wires in three kinds of world-interaction capabilities: CraftEngine's blocks and furniture, ModelEngine's modeled entities, and CustomCrops' crops. They all follow the soft-dependency + reflection bridge approach: if the plugin isn't installed they silently become unavailable, never affecting startup.

🧰 Shared foundation: The "multi-version, multi-signature compatibility" of every bridge on this page is built on top of ReflectionBridge / ReflectionCache — method signatures across different major versions of the same plugin are matched automatically. For developer details see 👉 ../04-开发者/工具集.md.

🛠️ 1. CraftEngine — Items / Blocks / Furniture

Item	Content
Bridge classes	`CraftEngineBridge` / `CraftEngineManager`
Three object categories involved	Custom items, custom blocks, custom furniture

CraftEngine's item references (ce-namespace_id) are covered in 物品类插件.md. This page focuses on its block and furniture capabilities.

🔧 CraftEngineManager capability table

Capability	Signature	Effect
Build item	`buildItemStack(identifier, amount)`	Fetch a CraftEngine item
Place block	`placeBlock(location, blockId, playSound)`	Place a custom block at the given location, optionally playing a sound
Remove block	`removeBlock(block)`	Remove a custom block
Check custom block	`isCustomBlock(block)`	Whether this block is a CraftEngine custom block
Read block id	`getCustomBlockId(block)`	Get the id of a custom block
Place furniture	`placeFurniture(location, furnitureId)` → entity	Place furniture, returns the furniture entity
Remove furniture	`removeFurniture(entity)`	Remove furniture
Check furniture	`isFurniture(entity)`	Whether this entity is furniture
Read furniture id	`getFurnitureId(entity)`	Get the furniture id

🪑 Block vs furniture: CraftEngine splits "blocks you can stand on" and "decorative entities (furniture)" into two separate object types, so the placement/identification APIs are also split into two sets — blocks use *Block, furniture uses *Furniture.

🧩 CustomBlock abstraction layer — not bound to CraftEngine

On top of CraftEngine, QCL adds another "custom block" abstraction layer so that upper-level logic doesn't directly depend on any specific plugin:

Component	Role
`CustomBlockBridge`	Aggregator: gathers all "custom block providers"
`CustomBlockProvider`	Interface: `id` / `isAvailable` / `isCustomBlock` / `getCustomBlockId` / `getCustomBlockAt`
`CraftEngineBlockProvider`	Built-in provider, `id = craftengine`
`CustomBlockConfig`	Server-owner configuration for custom blocks (see the Custom Blocks page)

This means: to integrate another block plugin later, you only need to implement one more CustomBlockProvider — the upper layer is unaffected.

For how server owners configure custom blocks (drops, behaviors, etc.), see 👉 ../02-服主指南/自定义方块.md.

🎯 Typical uses

Programmatically place a CraftEngine block or furniture from a GUI / script.
When listening for a player breaking a block, use isCustomBlock + getCustomBlockId to determine "is this one of my configured custom blocks", and decide drops accordingly.

🤖 2. ModelEngine — Modeled Entities / Animations / Bone-Held Items

Item	Content
Bridge classes	`ModelEngineBridge` / `Manager`
Detection class	`com.ticxo.modelengine.api.ModelEngineAPI`

ModelEngine lets an ordinary entity "wear" a 3D model and play animations. QCL wraps this capability into a more convenient API.

🔧 Bridge capability table

Capability	Effect
`createModeledEntity(entity)`	Turn an entity into a modeled entity
`removeModeledEntity(...)`	Cancel modeling
`getModeledEntity(...)`	Get an entity's modeled wrapper
`createActiveModel(modelId)`	Create an active model instance

📦 Wrapper API

QCL provides two wrappers that condense the reflection calls into clean methods:

ModeledEntityWrapper (modeled-entity wrapper)

Method	Effect
`addModel(...)`	Add a model to the entity
`removeModel(...)`	Remove a model
`setBaseEntityVisible(...)`	Set whether the underlying entity is visible (commonly used to hide the vanilla body and show only the model)
`destroy()`	Destroy
`getModels()`	Get all current models

ActiveModelWrapper (active-model wrapper)

Method	Effect
`playAnimation(name, speed, force)`	Play the specified animation
`getBones()`	Get the bone list
`setHeldItem(bone, item)`	Make a bone "hold" an item

⚡ Manager shortcut methods

Method	Effect
`spawnModel(entity, modelId, hideBaseEntity)`	One step: spawn the model and optionally hide the underlying entity
`playAnimation(...)`	Play an animation
`setHeldItem(...)`	Bone-held item

🔄 The bridge provides multi-signature compatibility for these methods to cope with API differences across ModelEngine versions.

🎯 Typical uses

Spawn a modeled Boss / NPC, hiding the underlying entity to show only the model.
Call playAnimation on attack/hit/death to play the matching animation.
Use setHeldItem to make a model's bone (hand) hold a weapon item.

🌾 3. CustomCrops — Crop Detection / Harvesting / Planting / Growth / Bone Meal

Item	Content
Bridge classes	`CustomCropsBridge` / `Manager`
Detection class	`net.momirealms.customcrops.api.CustomCropsAPI`

CustomCrops provides a custom farming-crop system, and QCL bridges out all of its core actions.

🔧 Capability table

Capability	Effect
`isCrop(block / location)`	Whether this block/location is a crop
`getCropId(...)`	Get the crop id
`tryHarvest(block, player?)`	Attempt to harvest (player parameter optional)
`tryPlant(location, player, item, cropId)`	Attempt to plant
`tryGrow(location, boneMeal?, multiplier?)`	Attempt to force growth (optionally with bone meal and growth multiplier)
`isBoneMeal(item)`	Whether this item is bone meal
`getBoneMealItem()`	Get the bone meal item

🌱 The try* family of methods returns "whether it succeeded" semantics; the caller can decide follow-up logic accordingly (e.g. deduct stamina, grant experience).

🎯 Typical uses

Custom farm gameplay: use tryPlant in a script to plant for the player, tryHarvest for one-click harvesting.
Item effects: an item triggers tryGrow to ripen surrounding crops.
Use isCrop / getCropId to let a GUI or quest system identify the crop in front of the player.

🧰 Shared compatibility foundation: ReflectionBridge

To emphasize once more: the "multi-version, multi-signature compatibility" of every bridge above relies on the underlying:

ReflectionBridge — isClassAvailable(className) probes whether the target class exists.
ReflectionCache — caches method/field lookups (getMethod / findMethodByName / invoke / safeCall …).

If a developer wants to reuse this reflection toolkit in their own code, see 👉 ../04-开发者/工具集.md.

📚 Continue reading

🧱 ../02-服主指南/自定义方块.md — CustomBlockConfig server-owner configuration.
🔧 ../04-开发者/工具集.md — ReflectionBridge / ReflectionCache.
🎒 物品类插件.md — CraftEngine / other plugins' item references.
💰 经济插件.md — Integration with three economy backends.

🧱 Block / Model / Crop Integration ​

🛠️ 1. CraftEngine — Items / Blocks / Furniture ​

🔧 CraftEngineManager capability table ​

🧩 CustomBlock abstraction layer — not bound to CraftEngine ​

🎯 Typical uses ​

🤖 2. ModelEngine — Modeled Entities / Animations / Bone-Held Items ​

🔧 Bridge capability table ​

📦 Wrapper API ​

⚡ Manager shortcut methods ​

🎯 Typical uses ​

🌾 3. CustomCrops — Crop Detection / Harvesting / Planting / Growth / Bone Meal ​

🔧 Capability table ​

🎯 Typical uses ​

🧰 Shared compatibility foundation: ReflectionBridge ​

📚 Continue reading ​

🧱 Block / Model / Crop Integration

🛠️ 1. CraftEngine — Items / Blocks / Furniture

🔧 CraftEngineManager capability table

🧩 CustomBlock abstraction layer — not bound to CraftEngine

🎯 Typical uses

🤖 2. ModelEngine — Modeled Entities / Animations / Bone-Held Items

🔧 Bridge capability table

📦 Wrapper API

⚡ Manager shortcut methods

🎯 Typical uses

🌾 3. CustomCrops — Crop Detection / Harvesting / Planting / Growth / Bone Meal

🔧 Capability table

🎯 Typical uses

🧰 Shared compatibility foundation: ReflectionBridge

📚 Continue reading