Navigation: Documentation Home › Server Owner Guide › Custom Blocks Related: 物品源引用.md · 外部插件对接 / 方块模型作物.md · 脚本入门.md

🧱 Custom Blocks (CustomBlock)

QCL provides a custom block abstraction layer that unifies custom blocks/furniture from different sources (currently CraftEngine) under a single interface, with a built-in fallback mechanism—when the backend plugin isn't installed or placement fails, it automatically falls back to a normal block, so no holes are left in the world.

⚠️ This is an advanced / development capability, in most cases driven by sub-plugins or scripts. At the pure server-owner level, there are mainly two things you need to understand: item_sources (item sources) and the fallback mechanism.

---

🧠 Concepts

QCL's custom blocks consist of several layers:

CustomBlockBridge (aggregation layer)
   └── CustomBlockProvider (backend, can be multiple)
          └── CraftEngineBlockProvider  (id = craftengine, requires CraftEngine)

Layer	Role
CustomBlockBridge	The unified outward entry point, aggregating multiple Providers
CustomBlockProvider	The concrete implementation of a specific backend; there can be multiple
CraftEngineBlockProvider	Currently the only built-in backend, id = craftengine, depends on the CraftEngine plugin

In other words: custom block functionality = CraftEngine providing blocks/furniture + QCL's unified wrapping and fallback. When CraftEngine isn't installed, the custom part is unusable, but normal blocks can still be placed via the fallback mechanism.

---

🗂️ CustomBlockConfig Field Table

A custom block is parsed from a ConfigurationSection (a YAML config section), with the following fields:

Key	Type	Default	Description
material	Material name	CHEST	Fallback material: the normal block to fall back to when custom placement fails
custom-model-data	Integer	(unset)	Fallback CMD: takes effect when ≥ 0, attaching custom model data to the fallback item/block
displayname	String	—	Display name
item_sources	List	—	List of item source references, ordered by priority

my_block:
  displayname: "&bMana Ore"
  material: STONE              # Fallback material (falls back to stone when CraftEngine is unavailable)
  custom-model-data: 10001     # Fallback CMD, only takes effect when ≥0
  item_sources:                # Priority from top to bottom
    - craftengine-myaddon_mana_ore
    - STONE

---

🔗 Relationship Between item_sources and Unified Item Sources

item_sources uses exactly QCL's unified item source references (see 物品源引用.md for details). In the list, entries higher up have higher priority.

The syntax for a CraftEngine source is:

craftengine-namespace_id

Parsing rule: after the craftengine- prefix, the first underscore _ is converted to a colon :, thereby corresponding to CraftEngine's namespace:id.

Example: craftengine-myaddon_mana_ore → CraftEngine's myaddon:mana_ore (note that only the first underscore is converted; subsequent _ are preserved).

---

🎯 Placement Priority and Fallback Mechanism

The logic of place() (placement) tries each source in item_sources order, one by one:

For each source in item_sources (in order):
   ├─ If the source starts with craftengine-:
   │     1) First try "furniture placement"
   │     2) If furniture fails → then try "block placement"
   └─ If both fail → continue to the next source
If all sources fail:
   └─ Place a normal block using material (fallbackMaterial) (fallback)

Stage	Behavior
1️⃣ Iterate over item_sources	Try each one by priority
2️⃣ CraftEngine source	Try furniture first, then block if it fails
3️⃣ All fail	Fall back to placing a normal block with material + (optional) custom-model-data

This way, even if CraftEngine isn't installed or a custom block id is mistyped, the world will only turn into a normal block of the "fallback material", rather than throwing an error or leaving a gap—that's the point of the fallback mechanism.

---

🪑 Furniture vs Block

Custom content in CraftEngine comes in two forms, and QCL tries furniture first, then block when placing:

Form	Description	Try Order
Furniture	Decoration/model in entity form	Tried first
Block	A real block	Tried after furniture fails

For the same craftengine-xxx source, QCL automatically tries both, so you don't need to care whether it's furniture or a block.

---

🧰 Capability Overview

The custom block object (at the development/script level) provides these capabilities:

Capability	Method	Description
Get item	getItem(amount)	Retrieve the corresponding item by item_sources priority
Place	place(location)	Place at the specified location (with the fallback logic above)
Identify	isThis(block/entity)	Determine whether a block or entity is "this" custom block
Remove	remove(block/entity)	Remove the custom block

These four capabilities (get / place / identify / remove) are usually called by sub-plugins or scripts. Server owners generally use them indirectly through configs provided by sub-plugins.

---

📋 YAML Example Skeletons

Single CraftEngine source + fallback

mana_ore:
  displayname: "&bMana Ore"
  material: STONE                       # Falls back to stone when CraftEngine is unavailable
  custom-model-data: -1                 # <0 has no effect; set ≥0 if you want a fallback model
  item_sources:
    - craftengine-myaddon_mana_ore      # → myaddon:mana_ore

Multi-source fallback (prefer custom, fall back to normal)

magic_chest:
  displayname: "&dMagic Chest"
  material: CHEST                        # Final last-resort material
  custom-model-data: 20001
  item_sources:                         # Priority from top to bottom
    - craftengine-myaddon_magic_chest   # ① First choice: CraftEngine custom
    - craftengine-coreaddon_fancy_box   # ② Second choice: another custom
    - CHEST                             # ③ Fall back: a normal chest

The parsing logic tries from top to bottom: if ① fails, try ②; if ② fails, try ③; only if ③ also fails does it fall back to material (CHEST).

---

📌 Notes

• 🔌 Depends on CraftEngine: custom forms (furniture/block) require CraftEngine installed to place properly; otherwise everything goes through fallback.
• 🧪 This is an advanced capability: mostly driven by sub-plugins / scripts; server owners just need to focus on item_sources and fallback.
• 🔠 Only the first underscore is converted to a colon: craftengine-a_b_c → a:b_c, don't be misled by multiple underscores.
• 🔻 custom-model-data only takes effect when ≥ 0: a negative value means unset.

---

➡️ Continue Reading

• 物品源引用.md —— the unified item source reference format used by item_sources (including the craftengine- prefix rule)
• 外部插件对接 / 方块模型作物.md —— integration details for CraftEngine blocks/furniture/crops
• 脚本入门.md —— driving custom block get / place / identify / remove via scripts