GearForge
GUI-first MMO gear progression with upgrades, sockets, reforges, rarity, mastery, objectives, sets, stations, diagnostics, safety tools, and optional web config editing for Bukkit, Spigot, and Paper servers.
GUI-first MMO gear progression with upgrades, sockets, reforges, rarity, mastery, objectives, sets, stations, diagnostics, safety tools, and optional web config editing for Bukkit, Spigot, and Paper servers.
What Is GearForge?
GearForge turns normal or custom Minecraft items into long-term MMO-style progression gear. It is not just a simple upgrade command. It adds a full gear ecosystem with upgrade levels, rarity caps, failstacks, gems, sockets, reforges, set bonuses, soulbinding, item locks, item mastery, seasonal tracks, objectives, evolution, gear score, diagnostics, backups, exports, and player-facing codex menus.
The plugin is heavily GUI based. Players can use station menus to upgrade, socket, reforge, salvage, inspect progression, and browse the gear codex without needing to memorize command chains. Staff can use admin GUIs for giving materials, checking diagnostics, placing station blocks, viewing registered stations, refreshing labels, exporting debug data, and managing gear state.
Server Compatibility
GearForge is built against the modern Spigot API, which keeps the plugin compatible with the main Bukkit-style server platforms used by Minecraft server owners.
- Bukkit-compatible servers - the plugin uses standard Bukkit/Spigot-style plugin APIs for commands, menus, events, items, and configuration.
- Spigot supported - the build now targets org.spigotmc:spigot-api instead of Paper-only APIs.
- Paper supported - Paper remains supported because Paper runs Spigot/Bukkit plugins.
- Paper-only lock-in removed - the attribute handling and build dependencies have been adjusted so the plugin is not tied to Paper API.
- Modern server build - this is for modern Bukkit-compatible servers. Legacy 1.8 support still requires the separate compatibility layer described below.
Core Gear Systems
- Upgrade levels - improve items through configurable levels and rarity caps.
- Rarities - control item identity, colors, max levels, evolution paths, and scaling.
- Failstacks and pity - reward repeated failed upgrades with improved future chances.
- Protection scrolls - configurable safety item for risky upgrade attempts.
- Gems and sockets - create socketable gems with stat bonuses and custom display data.
- Reforges - apply named modifiers/prefixes to gear.
- Set bonuses - reward players for wearing configured gear sets.
- Soulbound gear - bind items to players and optionally restrict unsafe behavior.
- Item locks - prevent protected items from being modified or dropped.
- Mastery XP - let items gain progression as they are used.
- Seasonal tracks - attach progression paths and stages to gear.
- Objectives - give items their own mini-quests and completion progress.
- Evolution - advance items into stronger rarity or progression states.
- Gear score - calculate a configurable score from level, rarity, sockets, objectives, mastery, evolution, and other stats.
GUI-Based Station Workflow
GearForge is designed around stations and inventory menus. Players can open station GUIs by command, menu item, or right-clicking staff-placed GearForge station blocks.
- Station selector - central menu for all GearForge workstations.
- Upgrade station - place gear, preview chances, costs, risk, failstack behavior, and result.
- Socket station - place gear and a gem, preview socket rules, then apply the gem.
- Reforge station - reroll or apply configured reforge modifiers.
- Salvage station - break down gear into configured materials with confirmation clicks.
- Progression profile - view the held item's full progression state.
- Codex GUI - browse rarities, gems, reforges, sets, materials, filters, safety rules, and useful commands.
- Admin GUI - staff actions for materials, debug tools, reloads, registry checks, station management, and support exports.
Physical GearForge Stations
Admins can place real station blocks for players to interact with. This is useful for RPG hubs, dungeons, spawn areas, blacksmith builds, and progression rooms.
- Give station blocks through commands or the admin GUI.
- Place upgrade, socket, reforge, salvage, codex, and station selector blocks.
- Players right-click station blocks to open the matching menu.
- Floating labels identify each station in-world.
- Ambient particles and sounds make station areas feel alive.
- Registered stations are protected until staff unregister them.
- Admin station browser can list, inspect, teleport to, refresh, clean, and export station data.
Optional Web Config Editor
GearForge is configured through YAML and in-game GUIs, and it also works well with an optional standalone web config editor for larger setup passes. Use the web editor when you want to tune a full economy, rarity ladder, gem list, upgrade costs, reforge table, station settings, filters, and message text in a browser-style interface.
- Useful for large edits to config.yml and messages.yml.
- Pairs well with the in-game admin GUI for quick live testing.
- Keeps setup accessible for owners who prefer visual editing over raw text.
- No external database is required for normal GearForge operation.
Admin And Support Features
- /gearforge doctor - print runtime health and setup checks.
- /gearforge debugbundle - create a support zip with relevant plugin data.
- Config validation - startup/reload warnings for invalid materials and risky values.
- Audit logs - file-based records for important gear/admin actions.
- Item backups - backup and restore held items.
- Item export/import - snapshot items for staging, support, kits, and reproduction.
- Duplicate UUID scan - scan online players for cloned GearForge item UUIDs.
- Migration helper - normalize online-player gear data to the current item data version.
- Registry tools - inspect tracked gear UUIDs and leaderboard data.
- Localization - external messages file for rebranding and translation.
Compatibility With Custom Items
GearForge is built as a progression layer. It can add progression metadata to normal or plugin-created items while preserving the original item's identity as much as possible. This makes it suitable for servers using custom item pipelines, dungeon drops, boss rewards, kits, crates, and other plugin-generated gear.
- Works with normal Minecraft items.
- Designed to be friendly to custom item ecosystems.
- Item filters can block dangerous materials or restrict GearForge to approved item types.
- Utility items, gems, and progression materials can be protected from accidentally becoming gear.
- Developer events allow other plugins to react to or cancel upgrade behavior.
Player Commands
Code:
/gearforge station
/gearforge profile
/gearforge codex
/gearforge open
/gearforge socket
/gearforge reforge
/gearforge salvage
/gearforge compare
/gearforge milestonesAdmin Commands
Code:
/gearforge admin
/gearforge give upgrade_stone [player] [amount]
/gearforge give protection_scroll [player] [amount]
/gearforge give reforge_stone [player] [amount]
/gearforge give gem <gem_id> [player] [amount]
/gearforge give material <material_id> [player] [amount]
/gearforge stationblock <station|upgrade|socket|reforge|salvage|codex> [amount]
/gearforge stationadmin <list|set|remove|info> [type]
/gearforge setrarity <rarity> [level]
/gearforge setlevel <level>
/gearforge setreforge <reforge|random|none>
/gearforge reroll <reforge|sockets|uuid>
/gearforge clearsockets
/gearforge socketgem <gem_id>
/gearforge setset <set|none>
/gearforge bind [player]
/gearforge unbind
/gearforge lock
/gearforge unlock
/gearforge setobjective <objective|none>
/gearforge completeobjective
/gearforge inspect
/gearforge backupitem
/gearforge restoreitem <backup_id>
/gearforge exportitem
/gearforge importitem <export_id>
/gearforge listitemexports
/gearforge resetitem
/gearforge regenid
/gearforge mastery <addxp|setlevel> <amount>
/gearforge settrack <track|none> [stage]
/gearforge advancetrack
/gearforge evolve
/gearforge doctor
/gearforge debugbundle
/gearforge migrate [dryrun]
/gearforge scanduplicates
/gearforge registry
/gearforge exportleaderboard
/gearforge reload
/gearforge reloadmessagesPermissions
Code:
gearforge.use - open station/profile/upgrade GUIs
gearforge.socket - open socket station
gearforge.reforge - open reforge station
gearforge.salvage - open salvage station
gearforge.admin - use admin commands
gearforge.admin.station - manage placed GearForge stations
gearforge.export - export/import item snapshots
gearforge.diagnostics - run doctor/debug/migration/duplicate scans
gearforge.leaderboard - export online gear leaderboardFiles And Configuration
- config.yml - rarities, upgrade costs, success chances, gems, reforges, sets, filters, stations, acquisition, milestones, scoring, and safety settings.
- messages.yml - command, GUI, and support message text for localization and branding.
- gear-registry.yml - generated tracking for known GearForge item UUIDs.
- backups.yml - generated item backups.
- exports.yml - generated item export/import snapshots.
- leaderboard.csv - generated leaderboard export.
- duplicate-scan.csv - generated duplicate UUID scan export.
- audit.log - generated operational audit trail.
Dependencies
- Required: Bukkit-compatible server software. Spigot is recommended for compatibility, and Paper is also supported.
- Spigot: https://www.spigotmc.org/
- Paper: https://papermc.io/
- Required: Java runtime matching the build target used by your server.
- Optional: Vault API for economy integration - https://www.spigotmc.org/resources/vault.34315/
- Optional: PlaceholderAPI for placeholders - https://www.spigotmc.org/resources/placeholderapi.6245/
- Optional: External web config editor workflow included as a standalone local HTML file.
GearForge is for servers that want item progression to feel like a complete RPG system, with players living in polished station GUIs and staff managing the system through practical admin tools.
