# 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 | Concept | Class | Description | | --------------- | ------------------ | -------------------------------------------------------------------------------------------- | | **Station** | `CraftingStation` | A crafting menu with its own layout, recipes, permission, sounds and decorative items. | | **Recipe** | `Recipe` | One craftable entry inside a station: ingredients, outputs, conditions, triggers and timing. | | **Ingredient** | `RecipeIngredient` | An item required by a recipe, optionally non-consumed ("tool"). | | **Output** | `RecipeOutput` | An item produced by a recipe, with an optional drop chance. | | **Condition** | `RecipeCondition` | A requirement checked before a craft succeeds and optionally consumed. | | **Trigger** | `Trigger` | A side effect fired after a successful craft. | | **Queue Entry** | `QueueEntry` | A timed craft in progress, tracked per player/station and persisted to the database. | --- # 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 | Key | Type | Default | Description | | --------------------- | ---------- | -------------------------- | ------------------------------------------------------------------ | | `name` | string | file name | Display name. Supports `#page#` / `#max#` pagination placeholders. | | `layout` | string | `default` | ID of a registered `StationLayout`. | | `preview-layout` | string | `default` | ID of the `PreviewLayout` used for recipe previews. | | `permission.enabled` | boolean | `false` | Whether a permission is required to open the station. | | `permission.node` | string | `forgeengine.station.` | Permission node checked when opening the station. | | `sound` | string | config.yml | Bukkit `Sound` enum played when opening the station. | | `max-queue-size` | int | config.yml | Maximum concurrent queued crafts per player for this station. | | `fill` | item block | black glass pane | Decorative filler item for empty slots. | | `no-recipe` | item block | gray glass pane | Shown in an empty recipe slot. | | `locked-recipe` | item block | barrier | Shown instead of a locked recipe's real icon. | | `empty-queue-slot` | item block | light gray glass pane | Shown in empty queue slots. | | `command.enabled` | boolean | `false` | Registers a dedicated `/` command. | | `command.name` | string | — | Command name. | | `command.description` | string | — | Command description. | | `command.permission` | string | — | Command permission. | | `command.aliases` | list | — | Command aliases. | | `recipes` | section | — | Map of `recipeId -> recipe definition`. | 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. ```yaml 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 | Key | Type | Default | Description | | ---------------------------------- | ------------------- | ------------ | ---------------------------------------------------- | | `output` | string / map / list | — | One or more possible outputs. | | `ingredients` | string list | `[]` | Required items. Append `!nc` for non-consumed items. | | `conditions` | string list | `[]` | Non-item requirements. | | `triggers` | string list | `[]` | Effects fired after a successful craft. | | `crafting-time` | int | `0` | Crafting time in seconds. `0` = instant craft. | | `cooldown` | int | `0` | Per-recipe cooldown in seconds. | | `slot` | int | `-1` | Fixed GUI slot. `-1` = automatic placement. | | `icon` | string / map | first output | Overrides the recipe icon. | | `options.output-item` | boolean | `true` | Whether the output item is actually given. | | `options.silent-craft` | boolean | `false` | Suppresses default craft feedback. | | `options.hide-when-locked` | boolean | `false` | Completely hides the recipe while locked. | | `options.hide-when-no-ingredients` | boolean | `false` | Hides the recipe if ingredients are missing. | | `options.blocked-icon` | boolean | `true` | Uses the station's locked recipe icon while locked. | | `options.glow` | boolean | `false` | Adds an enchantment glint while unlocked. | | `options.close-on-craft` | boolean | `false` | Closes the GUI after a successful craft. | --- # Items Both ingredients and outputs use the same **ItemReference** syntax: ```text provider{key=value,key2=value2} ``` Built-in providers include: * `vanilla` * MythicMobs * Oraxen * Nexo * ItemsAdder Additional providers can be registered through the Developer API. ## Ingredients ```yaml 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 ```yaml output: 'vanilla{type=IRON_PICKAXE,amount=1}' ``` ### Expanded ```yaml output: type: VANILLA id: IRON_PICKAXE amount: 1 name: '&fIron Pickaxe' lore: - '&7A sturdy tool.' ``` ### Weighted ```yaml 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:** ```text type{key=value;key2=value2} ``` Common optional arguments: * `display="..."` — custom tooltip line * `hide=true` — hides the requirement from the tooltip | Condition | Syntax | Behaviour | | --------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Level** | `level{level=,consume=}` | Requires a minimum level. Uses MMOCore, then PlaceholderAPI, then vanilla XP level. | | **Class** | `class{list=,,...}` | Requires one of the listed RPG classes. | | **Permission** | `permission{list="perm1,perm2"}` | Requires every listed Bukkit permission. | | **Placeholder** | `placeholder{placeholder="~~"}` | Arbitrary PlaceholderAPI comparison. | | **Food** | `food{amount=}` | Requires and consumes food level. | | **Mana** | `mana{amount=,format="0.#"}` | Requires and consumes MMOCore mana. | | **Stamina** | `stamina{amount=,format="0.#"}` | Requires and consumes MMOCore stamina. | | **Money** | `money{amount=,provider=vault\|gemseconomy\|coinsengine,currency=}` | Requires and withdraws money through the selected economy backend. | 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. | Trigger | Syntax | Effect | | --------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- | | **Message** | `message{format="..."}` | Sends a chat message to the crafter. | | **Action Bar** | `actionbar{format="..."}` | Sends an action-bar message. | | **Broadcast** | `broadcast{format="..."}` | Broadcasts a message server-wide. | | **Title** | `title{title="...",subtitle="...",fade-in=10,stay=40,fade-out=10}` | Displays a title and subtitle. | | **Command** | `command{format="...",sender=CONSOLE\|PLAYER}` | Runs a command as console or player. | | **Sound** | `sound{sound=,volume=1,pitch=1}` | Plays a sound to the crafter. | | **Particle** | `particle{particle=,amount=20}` | Spawns particles at the player. | | **Exp** | `exp{amount=}` | Gives vanilla XP. | | **Money** | `money{amount=,provider=vault,currency=}` | Pays money through the selected economy backend. | | **MythicMobs Skill** | `mmskill{id=}` | Casts a MythicMobs skill. | | **MythicMobs Spawn** | `mmspawnmob{id=,amount=1,level=1}` | Spawns a MythicMobs mob. | | **MythicMobs Signal** | `mmsignal{signal=}` | Sends a MythicMobs signal. | | **Bonus Item** | `vanilla{type=...}` | Any registered item provider can be used as a bonus item trigger. | 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: ```yaml auto-collect-on-complete: true ``` is enabled, completed items are automatically collected while the player is online. ## Expiry Default: ```yaml 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: ```text money{amount=50,provider=vault} ``` Multi-currency providers can additionally specify: ```text currency= ``` Money is only withdrawn after every other condition has passed. ## EconomyBridge It supports: * `has` * `withdraw` * `deposit` It activates only when: ```yaml 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: ```yaml 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: | Action | Description | | ------------- | ------------------------------------------- | | `QUEUE_START` | A timed recipe was queued. | | `COLLECT` | A completed queued craft was collected. | | `CANCEL` | A queued craft was cancelled and refunded. | | `INSTANT` | An instant recipe was completed. | | `EXPIRED` | A completed item expired before collection. | ## 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: ```yaml database: purge: enabled: false after-days: 30 ``` --- # GUI Recipes using: ```text hide-when-locked ``` or ```text 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 ```yaml 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: : 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:** ```text com.mastercraft.forgeengine.api.ForgeEngineAPI ``` ## Availability Before using the API, always check whether ForgeEngine is available: ```java 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. ```java 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: ```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. ```java 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. ```java 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 ```yaml 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*

mastercraftreal178