Reusable Templates (Mixins) & Cascading Precedence
When managing servers with dozens or hundreds of blueprints, retyping the same pricing, visual themes, lore cards, and durability rules for every single recipe introduces configuration bloat and maintenance errors.
CraftingBlueprints features an object-oriented Template Composition Engine (Mixins) that allows server administrators to define modular template blocks once and compose them across multiple blueprints.
1. Defining Reusable Templates (templates:)
Templates are non-instantiated blueprint modules declared under the root templates: section of any YAML file in plugins/CraftingBlueprints/blueprints/:
# yaml-language-server: $schema=./blueprint.schema.json
templates:
# Module 1: Visual styling for ancient magic scrolls
visual_ancient_scroll:
item:
material: PAPER
custom_model_data: 1001
glowing: true
map:
theme: parchment_aged
frame: runic
badge: crafting
# Module 2: Visual styling for legendary forge relics
visual_legendary_relic:
item:
material: FILLED_MAP
glowing: true
map:
theme: forge
frame: rosette
badge: smithing
item_outline:
enabled: true
width: 2
color: "rainbow"
# Module 3: Economy pricing tier (Epic)
economy_tier_epic:
price: 15000.0
sell_price: 3750.0
extra:
tier: "EPIC"
currency: "VAULT"
# Module 4: 3-Craft durability limit mixin
usage_three_crafts:
permanent: false
time: 0
uses: 3
# Module 5: Permanent unlimited usage mixin
usage_permanent:
permanent: true
time: 0
uses: 0
2. Composing Templates on Blueprints
To apply templates to a blueprint, list their IDs under templates: (or single string template:):
# yaml-language-server: $schema=./blueprint.schema.json
singles:
titan_greatsword:
blueprint: NETHERITE_SWORD
name: "<gradient:#FF0000:#FFAA00><bold>Titan Greatsword Blueprint</bold></gradient>"
# Multi-template mixin composition
templates:
- visual_legendary_relic
- economy_tier_epic
- usage_three_crafts
# Specific local override (Blueprint overrides Template 3):
uses: 5
3. Mixin Inheritance Precedence Rules
When a blueprint inherits multiple templates, CraftingBlueprints resolves configurations using strict cascading precedence:
Parent Defaults -> Folder Defaults -> File Defaults -> Template 1 -> Template 2 -> Blueprint Local Config
┌──────────────────────────────────────────────┐
│ 1. Inherited Folder Defaults │
│ (From root blueprints/ downward) │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ 2. Current Folder default: │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ 3. Current File file_default: │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ 4. Template 1 (First Mixin) │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ 5. Template 2 (Second Mixin) │
│ (Overrides Template 1) │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ 6. Blueprint Local Configuration │
│ (HIGHEST PRECEDENCE) │
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ Final Merged Blueprint │
└──────────────────────────────────────────────┘
Precedence Invariants:
- Blueprint Local Wins: Any property defined explicitly on the blueprint itself (e.g.
uses: 5,price: 25000.0, or localname:) always takes absolute precedence over all templates and defaults. -
Template Order (Right Overrides Left): If
Template 1definesprice: 10000.0andTemplate 2definesprice: 15000.0,Template 2wins because it is evaluated later in the list:Blueprint Local > Template 2 > Template 1. -
Dictionaries & Maps (
item:,map:,extra:): Deep-merged recursively. IfTemplate 1setsitem.material: FILLED_MAPandTemplate 2setsitem.glowing: true, the resulting item will have bothmaterial: FILLED_MAPandglowing: true. - Lists (
lore:,blueprints:,pool:): Replaced entirely by the latest non-empty list declared in the cascade. - Scalars (
name:,price:,permanent:,uses:,time:): Overwritten by the latest declared non-null scalar.
4. Hierarchical Lexical Scoping
Templates are not flat global variables; they follow downward directory scoping:
-
Global Templates (Root Scope): Any template declared in a YAML file at the root of
plugins/CraftingBlueprints/blueprints/(e.g.blueprints/00_templates.yml) is globally visible to all blueprints across all folders and subfolders. -
Folder-Scoped Templates: A template declared in
blueprints/weapons/templates.ymlis visible only to files insideblueprints/weapons/and its subdirectories (e.g.weapons/swords/,weapons/axes/). It cannot be accessed byarmor/or root files. -
Template Shadowing (Nearest-Ancestor): If a template named
tier_epicis declared at both the root level and insideweapons/, blueprints inweapons/will inherit the localweapons/tier_epicdefinition.
5. Folder & File Defaults (default: & file_default:)
To apply settings across an entire folder without repeatedly typing templates: on every item, use defaults:
# Inside blueprints/weapons/swords.yml
# File-Level Default: applies to all blueprints in this file
file_default:
price: 7500.0
item:
material: FILLED_MAP
glowing: true
map:
theme: technical
frame: bracket
singles:
iron_blade:
blueprint: IRON_SWORD
name: "<white>Iron Blade</white>"
# Automatically inherits price: 7500.0 and technical map theme!
diamond_blade:
blueprint: DIAMOND_SWORD
name: "<aqua>Diamond Blade</aqua>"
price: 15000.0 # Overrides the file default price
Cutting Off Inheritance (inherit: false)
If you have an isolated file (such as admin event items) and want to discard all inherited folder defaults: