ForgeEngine

Overview

Platform: Spigot / Paper (Bukkit API)

ForgeEngine is a fully configurable crafting station plugin. Server owners can define stations and recipes entirely in YAML, with no code required, while developers can extend the plugin through a clean Java API.

It follows the popular "one YAML file per station" convention, while adding features such as:

• Weighted multi-outputs
• Rich condition and trigger system
• Non-consumed "tool" ingredients
• Persistent asynchronous crafting queue
• Multiple economy backends
• Public developer API
• MMOCore integration
• PlaceholderAPI integration
• MythicMobs / Oraxen / Nexo / ItemsAdder support

Core Concepts

Stations

Every file inside the stations/ folder becomes one CraftingStation.

Subfolders are allowed and are used purely for organisation.

The file name without .yml becomes the station's internal ID.

This follows the same general convention used by MMOItems item-type files.

Loading

StationManager recursively loads every .yml file under stations/ on startup.

If the folder is empty, an example example_forge.yml is copied automatically.

If a station fails to parse, it is logged and skipped without bringing down the rest of the server.

Keys

Decorative GUI items such as fill, no-recipe, locked-recipe and empty-queue-slot belong to the station itself, not the layout.

This allows the same slot layout to be reused with different visual themes.

Recipes

Recipes are declared under a station's recipes: section.

Each recipe must have a unique recipe ID.

recipes:
  iron_sword:
    output: 'vanilla{type=IRON_SWORD,amount=1}'
    ingredients:
      - 'vanilla{type=IRON_INGOT,amount=2}'
      - 'vanilla{type=STICK,amount=1}'
    conditions:
      - 'level{level=5}'
      - 'money{amount=50}'
    triggers:
      - 'sound{sound=ENTITY_PLAYER_LEVELUP}'
      - 'message{format="&aYou forged an iron sword!"}'
    crafting-time: 10
    cooldown: 5
    options:
      glow: true

Keys

Items

Both ingredients and outputs use the same ItemReference syntax:

provider{key=value,key2=value2}

Built-in providers include:

• vanilla
• MythicMobs
• Oraxen
• Nexo
• ItemsAdder

Additional providers can be registered through the Developer API.

Ingredients

ingredients:
  - 'vanilla{type=IRON_INGOT,amount=2}'
  - 'vanilla{type=DIAMOND_PICKAXE,amount=1}!nc'

!nc means "no consume".

The item must exist in the player's inventory but is not removed when crafting.

Outputs

Compact

output: 'vanilla{type=IRON_PICKAXE,amount=1}'

Expanded

output:
  type: VANILLA
  id: IRON_PICKAXE
  amount: 1
  name: '&fIron Pickaxe'
  lore:
    - '&7A sturdy tool.'

Weighted

output:
  - item: 'vanilla{type=IRON_INGOT,amount=2}'
    chance: 100
  - item:
      type: VANILLA
      id: DIAMOND
      amount: 1
    chance: 12.5

Each output rolls independently.

This allows recipes to produce guaranteed base items alongside bonus drops.

Conditions

Conditions determine whether a recipe can be crafted.

Important: every condition is checked first. Only when all conditions pass are ingredients or other resources consumed.

This prevents partial charges, such as taking money before discovering that another requirement failed.

Syntax:

type{key=value;key2=value2}

Common optional arguments:

• display="..." — custom tooltip line
• hide=true — hides the requirement from the tooltip

Non-hidden conditions are automatically displayed in the recipe tooltip.

Triggers

Triggers execute after a craft has completely succeeded.

Multiple triggers of the same type can be used.

Unknown trigger types are logged as warnings and ignored. The recipe itself still loads.

Queue

Recipes with crafting-time > 0 are handled by QueueService.

The queue is maintained per player and per station and persisted to the database.

Lifecycle

• Queue: ingredients are taken immediately and outputs are pre-rolled once.
• Progress: getProgress() and getSecondsRemaining() drive the GUI progress bar.
• Collection: completed items can be collected manually or automatically.
• Expiry: completed but uncollected items can expire after a configurable number of days.
• Cancellation: incomplete crafts can be cancelled and their consumed ingredients refunded.
• Persistence: queue entries survive server restarts.

Progress

The GUI displays a 10-segment progress bar while a craft is running.

Once complete, the queue icon changes to a ready state.

Auto-Collection

When:

auto-collect-on-complete: true

is enabled, completed items are automatically collected while the player is online.

Expiry

Default:

queue:
  ready-item-expiry:
    enabled: true
    after-days: 7

Persistence

Every queue entry is persisted.

A server restart therefore does not lose:

• Crafting progress
• Consumed ingredients
• Pending outputs

If a station or recipe referenced by a stored entry no longer exists, the entry is discarded and a warning is logged.

Economy

EconomyManager supports multiple pluggable economy backends.

• Vault — vault
• GemsEconomy — gemseconomy
• CoinsEngine — coinsengine

Recipes can select the backend using:

money{amount=50,provider=vault}

Multi-currency providers can additionally specify:

currency=<name>

Money is only withdrawn after every other condition has passed.

EconomyBridge

It supports:

• has
• withdraw
• deposit

It activates only when:

economy.enabled: true

and Vault is present.

MMOCore

ForgeEngine integrates with MMOCore through reflection.

Supported features:

• Level
• Level consumption
• Class
• Mana
• Stamina

Fallbacks

If MMOCore is not installed:

Level

%player_level% through PlaceholderAPI is checked first, followed by vanilla XP level.

Class

%mmocore_class% is used through PlaceholderAPI, then none.

Mana / Stamina

These have no vanilla equivalent and therefore always fail if MMOCore is unavailable.

A one-time warning is logged.

PlaceholderAPI

PlaceholderBridge connects to PlaceholderAPI when:

placeholderapi.enabled: true

and PlaceholderAPI is installed.

This is used by:

• placeholder{} conditions
• Level fallback
• Class fallback
• Other placeholder-based data

Database

Database persists three major categories of data using HikariCP connection pooling.

Craft Log

Recorded actions include:

Cooldowns

Active per-recipe cooldowns are also persisted.

SQLite

SQLite uses a single connection in the pool to avoid database locking issues.

MySQL

Configured through:

• host
• port
• database
• username
• password
• useSSL
• pool-size

Purge

Optional configuration:

database:
  purge:
    enabled: false
    after-days: 30

GUI

Recipes using:

hide-when-locked

or

hide-when-no-ingredients

can be hidden depending on their state.

Lore

Recipe icons automatically display:

• Required ingredients
• Green / red ingredient status
• Non-hidden conditions
• Crafting time
• Locked / unlocked state

glow: true adds an enchantment glint while unlocked.

Locked Icon

When blocked-icon is enabled and the recipe is locked, the station's locked-recipe item replaces the real icon.

The same behaviour is used in both the station list and recipe preview.

Preview

Right-clicking a recipe opens the preview.

The preview displays:

• Full output icon
• Every ingredient
• Owned / required status
• Confirm button
• Required conditions

Both the station GUI and preview automatically refresh while open.

Configuration

debug: false

queue-tick-rate: 10
default-max-queue-size: 9

background-queue-processing: true
auto-collect-on-complete: false

queue:
  ready-item-expiry:
    enabled: true
    after-days: 7

database:
  purge:
    enabled: false
    after-days: 30

economy:
  enabled: false

placeholderapi:
  enabled: false

providers:
  <providerId>: true

default-open-sound: BLOCK_CHEST_OPEN
default-craft-sound: ENTITY_PLAYER_LEVELUP

Developer API

ForgeEngine provides a public API for other plugins that want to integrate with crafting stations, register custom item providers, or open stations programmatically.

API Class:

com.mastercraft.forgeengine.api.ForgeEngineAPI

Availability

Before using the API, always check whether ForgeEngine is available:

if (!ForgeEngineAPI.isAvailable()) return;

Providers

The API allows other plugins to register their own item providers.

This makes custom items available inside station YAML files as ingredients, outputs, and other item-based features.

ForgeEngineAPI.registerItemProvider(
    "myitems",
    "My Items",
    myPlugin,
    (args, amount) -> buildMyItem(args, amount),
    (stack, args) -> matchesMyItem(stack, args)
);

Once registered, the provider can be used directly in station YAML:

output: 'myitems{id=example,amount=1}'

ingredients:
  - 'myitems{id=material,amount=2}'

Opening Stations

Other plugins can open a ForgeEngine station directly for a player.

The normal station permission check and StationOpenEvent are still applied.

boolean opened =
    ForgeEngineAPI.openStation(player, "iron_forge");

Integration

To integrate ForgeEngine into another plugin:

1. Add ForgeEngine as a compile-only / provided dependency.
2. Do not shade ForgeEngine into your plugin.
3. Add ForgeEngine to your depend or softdepend list.
4. Register custom item providers from your plugin's onEnable().

Advanced Providers

For advanced integrations, such as custom item matching or NBT-based identification, implement ItemProvider directly and register it through the API.

ForgeEngineAPI.registerItemProvider(ItemProvider)

Note: The Developer API is intended for plugin developers who want to extend ForgeEngine or integrate it with their own systems. Server owners do not need to use the API to configure stations and recipes.

Cheat Sheet

Example

recipes:
  example_recipe:
    output:
      - item: 'vanilla{type=NETHERITE_INGOT,amount=1}'
        chance: 100
      - item: 'vanilla{type=DIAMOND,amount=1}'
        chance: 15

    ingredients:
      - 'vanilla{type=IRON_INGOT,amount=4}'
      - 'vanilla{type=BLAZE_ROD,amount=2}'
      - 'vanilla{type=SMITHING_TABLE,amount=1}!nc'

    conditions:
      - 'level{level=25,consume=false}'
      - 'class{list=Blacksmith,Artisan}'
      - 'permission{list="forge.advanced"}'
      - 'placeholder{placeholder="%player_level%~>=~25"}'
      - 'food{amount=6}'
      - 'money{amount=250,provider=vault}'
      - 'mana{amount=30,format="0.#"}'
      - 'stamina{amount=20,format="0.#"}'

    triggers:
      - 'message{format="&aYou forged a Netherite Ingot!"}'
      - 'actionbar{format="&6Crafting complete"}'
      - 'broadcast{format="&e%player% just forged something legendary!"}'
      - 'title{title="&6Forged!",subtitle="&7A legendary item",fade-in=10,stay=40,fade-out=10}'
      - 'sound{sound=ENTITY_PLAYER_LEVELUP,volume=1,pitch=1}'
      - 'particle{particle=HAPPY_VILLAGER,amount=20}'
      - 'exp{amount=50}'
      - 'money{amount=10,provider=vault}'
      - 'vanilla{type=EMERALD,amount=1}'

    crafting-time: 30
    cooldown: 60

    options:
      glow: true
      blocked-icon: true
      close-on-craft: false

ForgeEngine

Fully configurable crafting stations for Spigot / Paper

YAML-driven • Async Queue • Multi-Economy • Conditions • Triggers • Developer API