ForgeEngine
概览
平台: Spigot / Paper (Bukkit API)
ForgeEngine 是一个完全可配置的制作台插件。服务器管理员可以完全使用 YAML 定义制作台和配方,无需编写代码;而开发者则可以通过简洁的 Java API 扩展该插件。
它遵循流行的**“每个制作台一个 YAML 文件”**惯例,同时增加了以下功能:
- 带权重的多输出
- 丰富的条件和触发器系统
- 非消耗型“工具”材料
- 持久的异步制作队列
- 多种经济后端支持
- 公开的开发者 API
- MMOCore 集成
- PlaceholderAPI 集成
- MythicMobs / Oraxen / Nexo / ItemsAdder 支持
核心概念
| 概念 |
类 |
描述 |
| Station |
CraftingStation |
拥有独立布局、配方、权限、音效和装饰物品的制作菜单。 |
| Recipe |
Recipe |
制作台内的一个可制作条目:包含材料、产出、条件、触发器和计时。 |
| Ingredient |
RecipeIngredient |
配方所需的物品,可选为非消耗型(“工具”)。 |
| Output |
RecipeOutput |
配方产出的物品,带有可选的掉落几率。 |
| Condition |
RecipeCondition |
在制作成功前检查的需求,并可选择性消耗。 |
| Trigger |
Trigger |
制作成功后触发的副作用。 |
| Queue Entry |
QueueEntry |
正在进行的定时制作任务,按玩家/制作台追踪并持久化到数据库。 |
制作台 (Stations)
stations/ 文件夹内的每个文件都会成为一个 CraftingStation。
允许使用子文件夹,仅用于组织管理。
不带 .yml 后缀的文件名将成为制作台的内部 ID。
这遵循了与 MMOItems 物品类型文件相同的通用惯例。
加载
StationManager 会在启动时递归加载 stations/ 下的所有 .yml 文件。
如果文件夹为空,会自动复制示例文件 example_forge.yml。
如果某个制作台解析失败,会被记录日志并跳过,不会导致服务器其余部分崩溃。
键值 (Keys)
| Key |
Type |
Default |
Description |
name |
string |
文件名 |
显示名称。支持 #page# / #max# 分页占位符。 |
layout |
string |
default |
已注册的 StationLayout 的 ID。 |
preview-layout |
string |
default |
用于配方预览的 PreviewLayout 的 ID。 |
permission.enabled |
boolean |
false |
是否需要权限才能打开制作台。 |
permission.node |
string |
forgeengine.station.<id> |
打开制作台时检查的权限节点。 |
sound |
string |
config.yml |
打开制作台时播放的 Bukkit Sound 枚举音效。 |
max-queue-size |
int |
config.yml |
此制作台每个玩家的最大并发排队制作数量。 |
fill |
item block |
黑色玻璃板 |
用于空槽位的装饰性填充物品。 |
no-recipe |
item block |
灰色玻璃板 |
在空的配方槽位中显示。 |
locked-recipe |
item block |
屏障 |
替代被锁定配方的真实图标显示。 |
empty-queue-slot |
item block |
浅灰色玻璃板 |
在空的队列槽位中显示。 |
command.enabled |
boolean |
false |
注册专用的 /<name> 命令。 |
command.name |
string |
— |
命令名称。 |
command.description |
string |
— |
命令描述。 |
command.permission |
string |
— |
命令权限。 |
command.aliases |
list |
— |
命令别名。 |
recipes |
section |
— |
recipeId -> recipe definition 的映射。 |
像 fill、no-recipe、locked-recipe 和 empty-queue-slot 这样的装饰性 GUI 物品属于制作台本身,而不是布局。
这使得可以使用不同的视觉主题复用相同的槽位布局。
配方 (Recipes)
配方声明在制作台的 recipes: 部分下。
每个配方必须具有唯一的配方 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)
| Key |
Type |
Default |
Description |
output |
string / map / list |
— |
一个或多个可能的产出物。 |
ingredients |
string list |
[] |
所需物品。追加 !nc 表示非消耗性物品。 |
conditions |
string list |
[] |
非物品类要求。 |
triggers |
string list |
[] |
合成成功后触发的效果。 |
crafting-time |
int |
0 |
合成耗时,单位为秒。0 = 即时合成。 |
cooldown |
int |
0 |
每个配方的冷却时间,单位为秒。 |
slot |
int |
-1 |
固定的 GUI 槽位。-1 = 自动放置。 |
icon |
string / map |
first output |
覆盖配方图标。 |
options.output-item |
boolean |
true |
是否实际给予产出物。 |
options.silent-craft |
boolean |
false |
抑制默认的合成反馈。 |
options.hide-when-locked |
boolean |
false |
在锁定状态下完全隐藏配方。 |
options.hide-when-no-ingredients |
boolean |
false |
如果缺少材料则隐藏配方。 |
options.blocked-icon |
boolean |
true |
在锁定状态下使用工作台锁定的配方图标。 |
options.glow |
boolean |
false |
在解锁状态下添加附魔光效。 |
options.close-on-craft |
boolean |
false |
在合成成功后关闭 GUI 界面。 |
Items(物品)
材料和产出物均使用相同的 ItemReference 语法:
provider{key=value,key2=value2}
内置的提供者包括:
vanilla
- MythicMobs
- Oraxen
- Nexo
- ItemsAdder
可以通过 Developer API 注册其他额外的提供者。
Ingredients(材料)
ingredients:
- 'vanilla{type=IRON_INGOT,amount=2}'
- 'vanilla{type=DIAMOND_PICKAXE,amount=1}!nc'
!nc 表示 “不消耗”。
该物品必须存在于玩家背包中,但在合成时不会被移除。
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
每个产出项独立进行概率判定。
这允许配方在提供基础保底产出的同时,附带额外掉落。
Conditions(条件)
条件决定了一个配方是否可以被制作。
重要: 所有条件会优先进行检查。只有当 所有条件都满足 时,才会扣除材料或其他资源。
这可以防止部分扣费的情况,例如在发现其他要求未满足之前先扣除了金钱。
语法:
type{key=value;key2=value2}
常见的可选参数:
display="..." — 自定义工具提示行
hide=true — 从工具提示中隐藏该要求
| Condition |
Syntax |
Behaviour |
| Level(等级) |
level{level=<n>,consume=<bool>} |
要求最低等级。依次使用 MMOCore、PlaceholderAPI 或原版经验等级。 |
| Class(职业) |
class{list=<Class1>,<Class2>,...} |
要求拥有列出的 RPG 职业之一。 |
| Permission(权限) |
permission{list="perm1,perm2"} |
要求拥有列出的所有 Bukkit 权限。 |
| Placeholder(占位符) |
placeholder{placeholder="<Placeholder>~<Comparator>~<Value>"} |
任意的 PlaceholderAPI 比较。 |
| Food(食物值) |
food{amount=<n>} |
要求并消耗食物值。 |
| Mana(法力值) |
mana{amount=<n>,format="0.#"} |
要求并消耗 MMOCore 法力值。 |
| Stamina(体力值) |
stamina{amount=<n>,format="0.#"} |
要求并消耗 MMOCore 体力值。 |
| Money(金钱) |
money{amount=<n>,provider=vault|gemseconomy|coinsengine,currency=<name>} |
要求并通过选定的经济后端扣除金钱。 |
未隐藏的条件会自动显示在配方的工具提示中。
Triggers(触发器)
触发器在 合成完全成功后 执行。
可以使用多个相同类型的触发器。
| 触发器 |
语法 |
效果 |
| 消息 |
message{format="..."} |
向制作玩家发送一条聊天消息。 |
| 动作栏 |
actionbar{format="..."} |
发送一条动作栏消息。 |
| 广播 |
broadcast{format="..."} |
向全服广播一条消息。 |
| 标题 |
title{title="...",subtitle="...",fade-in=10,stay=40,fade-out=10} |
显示标题和副标题。 |
| 命令 |
command{format="...",sender=CONSOLE|PLAYER} |
以控制台或玩家身份运行命令。 |
| 音效 |
sound{sound=<Sound>,volume=1,pitch=1} |
向制作玩家播放一个音效。 |
| 粒子 |
particle{particle=<Particle>,amount=20} |
在玩家位置生成粒子效果。 |
| 经验值 |
exp{amount=<n>} |
给予原版经验值。 |
| 货币 |
money{amount=<n>,provider=vault,currency=<name>} |
通过选定的经济后端支付货币。 |
| MythicMobs 技能 |
mmskill{id=<skill>} |
施放一个 MythicMobs 技能。 |
| MythicMobs 生成 |
mmspawnmob{id=<mob>,amount=1,level=1} |
生成一个 MythicMobs 生物。 |
| MythicMobs 信号 |
mmsignal{signal=<id>} |
发送一个 MythicMobs 信号。 |
| 奖励物品 |
vanilla{type=...} |
任何已注册的物品提供程序均可用作奖励物品触发器。 |
未知的触发器类型将被记录为警告并被忽略。配方本身仍会加载。
队列
crafting-time > 0 的配方由 QueueService 处理。
队列按玩家和工作站分别维护,并持久化到数据库中。
生命周期
- 排队: 原料被立即扣除,输出结果预先随机生成一次。
- 进度:
getProgress() 和 getSecondsRemaining() 驱动 GUI 中的进度条。
- 收集: 完成的物品可以手动或自动收集。
- 过期: 已完成但未收集的物品可在配置的天数后过期。
- 取消: 未完成的制作可以被取消,其消耗的原料将被退还。
- 持久化: 队列条目在服务器重启后依然存在。
进度
GUI 在制作运行时显示一个分为 10 段的进度条。
完成后,队列图标变为就绪状态。
自动收集
当启用以下设置时:
auto-collect-on-complete: true
已完成的物品会在玩家在线时自动收集。
过期
默认设置:
queue:
ready-item-expiry:
enabled: true
after-days: 7
持久化
每个队列条目都会被持久化。
因此服务器重启不会丢失以下内容:
如果存储条目所引用的工作站或配方不再存在,该条目将被丢弃并记录警告日志。
经济
EconomyManager 支持多种可插拔的经济后端。
- Vault —
vault
- GemsEconomy —
gemseconomy
- CoinsEngine —
coinsengine
配方可以使用以下语法选择后端:
money{amount=50,provider=vault}
多货币提供者还可以指定:
currency=<name>
只有在所有其他条件都满足后,才会扣除货币。
EconomyBridge
它支持以下操作:
has(检查余额)
withdraw(取款)
deposit(存款)
仅在以下情况下激活:
economy.enabled: true
且存在 Vault 插件。
MMOCore
ForgeEngine 通过反射与 MMOCore 集成。
支持的功能:
回退机制
如果未安装 MMOCore:
等级
首先检查 PlaceholderAPI 中的 %player_level%,然后检查原版的经验等级。
职业
首先使用 PlaceholderAPI 中的 %mmocore_class%,否则使用 none。
法力值 / 体力值
这些没有对应的原版等效项,因此在 MMOCore 不可用时始终失败。
将记录一次性警告。
PlaceholderAPI
当启用以下设置且安装了 PlaceholderAPI 时,PlaceholderBridge 会连接至 PlaceholderAPI:
placeholderapi.enabled: true
这被以下功能使用:
placeholder{} 条件判断
- 等级回退机制
- 职业回退机制
- 其他基于占位符的数据
数据库
Database 使用 HikariCP 连接池持久化三大类数据。
制作日志
记录的操作用包含:
| 操作 |
描述 |
QUEUE_START |
定时配方已加入队列。 |
COLLECT |
已完成的队列制作已被收集。 |
CANCEL |
队列制作已被取消并退款。 |
INSTANT |
即时配方已完成。 |
EXPIRED |
成品在收集前已过期。 |
冷却时间
活动的配方级冷却时间也会被持久化。
SQLite
SQLite 在连接池中仅使用单个连接,以避免数据库锁定问题。
MySQL
通过以下配置进行设置:
host
port
database
username
password
useSSL
pool-size
清理 (Purge)
可选配置:
database:
purge:
enabled: false
after-days: 30
GUI
使用以下配置的配方:
hide-when-locked
或
hide-when-no-ingredients
可根据其状态进行隐藏。
描述 (Lore)
配方图标自动显示:
- 所需材料
- 绿色 / 红色材料状态
- 非隐藏的条件
- 制作时间
- 锁定 / 解锁状态
glow: true 会在解锁时添加附魔光泽效果。
锁定图标
当启用 blocked-icon 且配方被锁定时,工作站的 locked-recipe 物品将替换真实图标。
此行为同时适用于工作站列表和配方预览。
预览
右键点击配方即可打开预览窗口。
预览窗口显示:
- 完整输出物品图标
- 所有材料
- 拥有 / 所需状态
- 确认按钮
- 所需条件
在工作站 GUI 和预览窗口保持打开期间,两者都会自动刷新。
配置
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
开发者 API
ForgeEngine 提供了公开的 API,供其他希望与工作台集成、注册自定义物品提供者或以编程方式打开工作台的插件使用。
API 类:
com.mastercraft.forgeengine.api.ForgeEngineAPI
可用性
在使用 API 之前,请务必检查 ForgeEngine 是否可用:
if (!ForgeEngineAPI.isAvailable()) return;
提供者 (Providers)
该 API 允许其他插件注册自己的物品提供者。
这使得自定义物品可以作为材料、输出和其他基于物品的功能出现在工作站 YAML 文件中。
ForgeEngineAPI.registerItemProvider(
"myitems",
"My Items",
myPlugin,
(args, amount) -> buildMyItem(args, amount),
(stack, args) -> matchesMyItem(stack, args)
);
注册后,该提供者可以直接在站点 YAML 中使用:
output: 'myitems{id=example,amount=1}'
ingredients:
- 'myitems{id=material,amount=2}'
打开工作站
其他插件可以直接为玩家打开一个 ForgeEngine 工作站。
正常的权限检查和 StationOpenEvent 仍然会生效。
boolean opened =
ForgeEngineAPI.openStation(player, "iron_forge");
集成
要将 ForgeEngine 集成到其他插件中:
- 将 ForgeEngine 添加为 仅编译 / provided 依赖项。
- 不要将 ForgeEngine 阴影打包(shade)到您的插件中。
- 在您的
depend 或 softdepend 列表中添加 ForgeEngine。
- 从您插件的
onEnable() 中注册自定义物品提供者。
高级提供者
对于高级集成,例如自定义物品匹配或基于 NBT 的识别,请直接实现 ItemProvider 并通过 API 进行注册。
ForgeEngineAPI.registerItemProvider(ItemProvider)
注意: 开发者 API 旨在供想要扩展 ForgeEngine 或将其与自身系统集成的插件开发者使用。服务器管理员无需使用 API 来配置工作站和配方。
速查表
示例
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
适用于 Spigot / Paper 的全可配置合成工作站
YAML 驱动 • 异步队列 • 多经济系统 • 条件 • 触发器 • 开发者 API
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.<id> |
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 /<name> 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.
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:
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
| Condition |
Syntax |
Behaviour |
| Level |
level{level=<n>,consume=<bool>} |
Requires a minimum level. Uses MMOCore, then PlaceholderAPI, then vanilla XP level. |
| Class |
class{list=<Class1>,<Class2>,...} |
Requires one of the listed RPG classes. |
| Permission |
permission{list="perm1,perm2"} |
Requires every listed Bukkit permission. |
| Placeholder |
placeholder{placeholder="<Placeholder>~<Comparator>~<Value>"} |
Arbitrary PlaceholderAPI comparison. |
| Food |
food{amount=<n>} |
Requires and consumes food level. |
| Mana |
mana{amount=<n>,format="0.#"} |
Requires and consumes MMOCore mana. |
| Stamina |
stamina{amount=<n>,format="0.#"} |
Requires and consumes MMOCore stamina. |
| Money |
money{amount=<n>,provider=vault|gemseconomy|coinsengine,currency=<name>} |
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=<Sound>,volume=1,pitch=1} |
Plays a sound to the crafter. |
| Particle |
particle{particle=<Particle>,amount=20} |
Spawns particles at the player. |
| Exp |
exp{amount=<n>} |
Gives vanilla XP. |
| Money |
money{amount=<n>,provider=vault,currency=<name>} |
Pays money through the selected economy backend. |
| MythicMobs Skill |
mmskill{id=<skill>} |
Casts a MythicMobs skill. |
| MythicMobs Spawn |
mmspawnmob{id=<mob>,amount=1,level=1} |
Spawns a MythicMobs mob. |
| MythicMobs Signal |
mmsignal{signal=<id>} |
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:
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:
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:
| 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:
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:
- Add ForgeEngine as a compile-only / provided dependency.
- Do not shade ForgeEngine into your plugin.
- Add ForgeEngine to your
depend or softdepend list.
- 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
评论 0
登录后参与评分
还没有评论,来抢沙发吧