NexusContracts - Escrow Quest System v1.0.0

What is NexusContracts?

NexusContracts places a shared contract board on your server where two entirely different contract types coexist. Virtual factions — configurable guilds with no physical NPC entities — post ongoing system contracts for item delivery, mob hunting, and crafting. Players can also post their own requests, putting up a real Vault escrow that pays out automatically on delivery.

The reward is held the moment a player contract is posted. Nobody walks away empty-handed after a crash or a rage-quit: escrow is reconciled on every server startup, and cancelling a contract always refunds the poster. Abandoning an accepted contract triggers a configurable penalty — keeping the board honest.

Result: a living economy layer where players have a reason to go mining, hunt mobs, or fire up their crafting table every session — driven entirely by config, without writing a single line of code.


Dependency Stack

• Vault (optional — strongly recommended): enables all money-based escrow, payouts, and penalties. Without Vault, item- and command-reward contracts still work fully.
• PlaceholderAPI (optional): exposes nine %nexus_... placeholders (rank, per-faction rep, lifetime stats, active contract name, total earned) to scoreboards, chat formatters, and any other PAPI-aware plugin.

NexusContracts starts and runs without either dependency — Vault and PAPI are detected at runtime and enabled automatically when present.


Main Feature Set

• Dual contract board: System Contracts (faction-issued, always restocked) and Player Contracts (player-posted, escrowed) live on one paginated GUI with separate tabs.
• Vault escrow engine: reward money is withdrawn from the poster on creation and held safely — crash-safe reconciliation on startup ensures nothing is ever lost or double-paid.
• GUI delivery: contractors deposit items into a submission GUI and confirm — no passive block or pickup tracking. Fully Folia-safe by design.
• Faction reputation system: each faction tracks reputation separately. Higher factions are reputation-gated; players must earn their way up.
• Global rank tiers: total reputation (summed across all factions) maps to a config-driven rank ladder (Novice → Grandmaster). Promotion fires a PlayerRankUpEvent and can run any console command.
• Mission chains: each faction can define sequential multi-step chains with requires-chain dependencies. Chain contracts are only visible to the qualifying player.
• Counter-offer system: when a player contract is posted, competitors can submit a counter-offer; the poster accepts or rejects via a one-click GUI.
• Group contracts: multiple players can join a single contract and split the reward automatically on completion.
• Watchlist: players subscribe to specific materials; they receive a notification the moment a matching contract appears on the board.
• Price suggestions: the PriceSuggestionService analyses recent contract history and surfaces a recommended price range when creating a player contract.
• Reputation decay: configurable daily decay for inactive players, with a grace period — keeps the leaderboard competitive without punishing occasional players too hard.
• Pluggable persistence: SQLite (zero-config default), H2, MySQL, or MariaDB — switch with one config line. HikariCP handles connection pooling; all DB I/O is async.
• MiniMessage everywhere: every message, faction display name, and rank label uses full MiniMessage syntax — gradients, hex colours, hover events, all supported.
• Full localization: all player-facing text lives in messages_en.yml (or any language file you create). Hot-reloadable with /nexuscontracts reload.
• Discord webhooks: configurable embeds fire on high-value contract postings, completions, rank-ups, and server milestones — with a token-bucket rate limiter to protect your webhook quota.
• Public Java API: NexusContractsAPI exposes contract lookup, cancellation, stat snapshots, reputation reads, and rank resolution for other plugins to hook into.
• bStats metrics: anonymous usage statistics, opt-out anytime by disabling bStats globally.

Contract Types




Reward Grammar

All faction reward pools and step rewards use a simple string grammar:

• MONEY:RANGE:\<min\>:\<max\> — random amount between min and max, e.g. MONEY:RANGE:2000:6000.
• ITEM:\<material\>;\<custom-model-data\>;\<amount\> — gives a specific item; use 0 for no CMD.
• COMMAND:\<command\> — runs a console command; <player> is replaced with the contractor's name.

Commands & Permissions

• /contracts (aliases: /nc, /contract): open the contract board.
• /contracts create [material]: open the creation GUI; uses held item if material is omitted.
• /contracts deliver: open the submission GUI for your active contract.
• /contracts abandon: forfeit your active contract (penalty may apply).
• /contracts info: show progress and time remaining on your active contract.
• /contracts search: filter the board by keyword or material.
• /contracts history: view your completed and failed contract history.
• /nexuscontracts reload (alias: /ncadmin): hot-reload config, language files, and faction definitions.
• /nexuscontracts version: print plugin version, DB backend, and scheduler platform.
• /nexuscontracts list: list all currently active contracts.
• /nexuscontracts force-complete \<id\>: admin-force a contract to completion.
• /nexuscontracts force-expire \<id\>: admin-force a contract to expiry.

Permissions: nexuscontracts.use (everyone) for board access and accepting; nexuscontracts.create (everyone) for posting player contracts; nexuscontracts.admin (op) for all administrative commands. Posting tier caps are controlled by nexuscontracts.tier.default / .donor / .vip.


PlaceholderAPI Placeholders

• %nexus_rank%: the player's current rank key (e.g. expert), or none.
• %nexus_rank_display%: formatted rank name, deserialized to a legacy color string.
• %nexus_total_rep%: summed reputation across all factions.
• %nexus_rep_\<faction\>%: reputation with a single faction (e.g. %nexus_rep_miners_guild%).
• %nexus_active_contract%: name of the player's currently active contract, or None.
• %nexus_contracts_completed%: lifetime completed contracts.
• %nexus_contracts_failed%: lifetime failed/expired contracts.
• %nexus_contracts_posted%: lifetime posted player contracts.
• %nexus_total_earned%: lifetime money earned, formatted by your economy plugin.

Why Choose NexusContracts?

• Crash-safe escrow: money is reconciled on every startup — no silent duplication, no lost funds, even after an unexpected shutdown.
• Zero entity setup: factions are pure config — no spawning NPCs, no Citizens dependency, no region setup.
• Folia-native: declared folia-supported: true; all scheduling goes through a transparent abstraction that targets Folia region/async schedulers or falls back to the Bukkit scheduler automatically.
• One board, two economies: system quests and player trading coexist without separate plugins or conflicting commands.
• Scales with your server: swap SQLite for MySQL/MariaDB in one config line. HikariCP pools connections; all DB I/O is fully async.
• No reloads needed for most changes: /nexuscontracts reload hot-swaps config, messages, factions, and chains without a restart.

FAQ

Do I need Vault?
No — but without Vault, money-based rewards and escrow are disabled. Item and command rewards work fine without it.

Is Folia supported?
Yes. NexusContracts declares folia-supported: true and routes all scheduling through an abstraction layer that works identically on Paper, Purpur, and Folia.

Which databases are supported?
SQLite (bundled, zero-config), H2 (bundled), MySQL, and MariaDB. Set database.type in config.yml.

Can I translate the plugin?
Yes. All messages live in messages_en.yml. Copy it, rename it (e.g. messages_de.yml), translate, and point language in config.yml at it.

What happens to escrow money if the server crashes?
On the next startup, the ContractManager runs a reconciliation pass that compares in-memory state to the database and corrects any discrepancy before the board opens.

Can other plugins hook into NexusContracts?
Yes. The NexusContractsAPI interface exposes contract lookup, stat snapshots, reputation reads, rank resolution, and contract cancellation. It is available via NexusContracts.getApi().




minecraft contracts plugin, quest plugin, economy plugin, faction reputation, escrow plugin, folia plugin, vault economy, paper plugin, player contracts, delivery quest, contract board, nexuscontracts.