StormContracts

StormContracts

Adds player-created contracts with tracked objectives, escrowed money and item rewards, claim review, refunds, and safe payouts.

StormContracts lets players post public work for other players to complete. Contracts can ask for kills, captures, mining, crafting, collecting, or item delivery, then pay escrowed rewards when a valid tracked player completes the objective.

It is built for survival, RPG, economy, and town servers where players should be able to create real jobs, bounties, deliveries, and reward-backed objectives without staff manually handling every payout.

Features

• Public contract board through /contracts.
• GUI contract board through /contractboard.
• Player-created contracts through /contract create.
• Contract detail pages with title, description, objectives, reward money, reward items, expiry, and status.
• Players must track a contract before progress counts.
• Many players can track the same contract.
• The first valid completion claim wins.
• Contract creators cannot fulfil their own contracts.
• Automatic progress tracking for supported objective types.
• Manual delivery objectives that remove delivered items safely when the player submits.
• Auto-pay contracts for straightforward completion.
• Manual-review contracts where the creator can approve or reject a claim.
• Manual-review claims auto-approve after the configured timeout.
• Escrowed StormEconomy money rewards.
• Escrowed item rewards.
• Claim box storage for reward items, refunded items, delivered items, and inventory overflow.
• Creator cancellation with escrow refund when no completion claim exists.
• Staff pause, remove, refund, approve, reject, and reset tools.
• Expired contracts refund safely.
• Paid contracts fail safely if StormEconomy is unavailable or unhealthy.
• Contract audit records for posts, tracking, progress, claims, payouts, refunds, reviews, resets, and admin actions.
• Bukkit events for post, track, progress, claim, review, payout, refund, expiry, cancellation, claim box, and audit activity.
• Bukkit service API for trusted integrations.
• System-post API so trusted plugins can publish contracts without pretending to be an online player.
• Capture objective support for bounty and court workflows.
• StormCourts integration for village-funded capture contracts and tracked custody progress.
• StormQuests objective credit for contract post, track, progress, claim, and payout actions.
• Optional NPCs fake-player resolution for automated scenarios and linked integrations.
• SQLite storage by default, with YAML, MySQL, and MariaDB support.
• Separate Paper and StormServer-compatible builds from the shared codebase.

Contract Objectives

StormContracts supports these objective types:

• kill_entity
• capture_player
• mine_block
• craft_item
• collect_item
• deliver_item

Objective targets use normal Minecraft-style material or entity keys. A target can also be * for wildcard-compatible objectives.

Examples of contract ideas:

• Kill 10 zombies.
• Mine 64 diamond ore.
• Craft 32 arrows.
• Collect 16 ender pearls.
• Deliver 128 oak logs.
• Capture a wanted player through a trusted integration.

Tracking And Progress

Players must run /contract track <id> before their actions count towards that contract.

Tracked progress can be checked with:

• /contract progress
• /contract progress <id>

StormContracts listens for normal gameplay events such as block mining, entity kills, crafting, item pickup, and item delivery. Delivery objectives are handled on submit so required items are removed safely and stored for the contract creator.

Claims And Review

When all objectives are complete, the fulfiller submits the contract:

• /contract submit <id>

Contracts can use two review modes:

• AUTO
• MANUAL

Auto contracts pay immediately after a valid submit. Manual contracts create a pending claim for the contract creator to review. If the creator does not respond before the configured review timeout, the claim is automatically approved.

Creators can review claims from:

• /contract claims

Staff can also approve or reject claims with admin commands.

Rewards And Escrow

StormContracts supports both money and item rewards.

Money rewards use StormEconomy and are withdrawn into escrow when the contract is posted. Item rewards are stored with the contract and paid to the fulfiller when the claim succeeds.

If a player cannot receive all reward items directly, or if items need to be returned after a refund or rejection, StormContracts stores them in the player's claim box.

Players can open their claim box with:

• /contract claimbox

The claim box helps prevent reward loss from full inventories, offline payouts, refunds, and rejected delivery claims.

Contract Board

The public contract board shows active contracts and lets players inspect available work.

Commands:

• /contracts [page]
• /contractboard
• /contract info <id>

Empty boards report No active contracts. instead of showing a blank page.

Commands

Main board commands:

• /contracts [page]
• /contractboard

Player contract commands:

• /contract info <id>
• /contract create
• /contract track <id>
• /contract untrack <id>
• /contract progress [id]
• /contract submit <id>
• /contract cancel <id>
• /contract claims
• /contract claimbox

Admin commands:

• /stormcontracts status
• /stormcontracts audit
• /stormcontracts storage
• /stormcontracts save
• /stormcontracts backup
• /stormcontracts reload
• /stormcontracts pause <id>
• /stormcontracts remove <id>
• /stormcontracts refund <id>
• /stormcontracts approve <claim>
• /stormcontracts reject <claim> [reason]
• /stormcontracts reset <player> [contract]

Permissions

Normal player access is granted by default through stormcontracts.defaults.

Player permissions:

• stormcontracts.board
• stormcontracts.contract
• stormcontracts.create

Admin permissions:

• stormcontracts.admin
• stormcontracts.admin.command
• stormcontracts.admin.audit
• stormcontracts.admin.storage
• stormcontracts.admin.save
• stormcontracts.admin.backup
• stormcontracts.admin.reload
• stormcontracts.admin.pause
• stormcontracts.admin.remove
• stormcontracts.admin.refund
• stormcontracts.admin.review
• stormcontracts.admin.reset

Configuration

StormContracts includes configurable limits for:

• Active contracts per creator.
• Tracked contracts per player.
• Objectives per contract.
• Default expiry.
• Maximum expiry.
• Manual-review timeout.
• Minimum and maximum money reward.
• Reward item stack count.
• Claim box item stack count.
• Title length.
• Description length.
• Auto-publish behaviour.
• Integration toggles.

Default storage uses SQLite at:

• plugins/StormContracts/stormcontracts.db

Storage

StormContracts supports:

• SQLite
• YAML
• MySQL
• MariaDB

SQLite is the default. Remote JDBC examples use hostname-verified TLS defaults and separate empty credential fields.

Stored data includes contracts, objectives, player progress, completion claims, claim box entries, escrow-related state, and audit records.

Optional Integrations

StormContracts can run with optional integrations while keeping the core contract system available.

• StormEconomy enables money escrow, refunds, and payouts.
• StormCourts can post village-funded capture contracts for wanted players and credit capture progress through court custody workflows.
• StormQuests receives STORMCONTRACTS_ACTION credit for contract posting, tracking, progress, claims, and payouts.
• NPCs can resolve linked fake players for automated scenarios and compatible integrations.
• ThunderPerms can provide permission checks when available.

StormEconomy is required for money-backed contracts. If StormEconomy is missing or unhealthy, StormContracts fails money escrow, refund, and payout paths safely instead of pretending the transaction succeeded.

Integration API

StormContracts exposes a Bukkit service API for other plugins.

The API can:

• Inspect active contracts.
• Inspect tracked player progress.
• Inspect claims.
• Inspect claim boxes.
• Track and untrack contracts.
• Credit objective progress.
• Submit, cancel, approve, reject, and refund contracts.
• Post trusted system contracts.
• Check storage health.

Trusted integrations can use this to create server-backed bounties, town jobs, court capture contracts, quest objectives, or custom event-driven work.

StormCourts Compatibility

StormContracts includes support for capture-style workflows used by StormCourts.

StormCourts can post village-funded capture contracts when a player's village bounty crosses a configured threshold. When a tracked hunter helps bring a wanted player into court custody, StormContracts can credit capture progress through the API.

This keeps bounty work visible on the contract board while preserving escrow, claim, refund, and payout rules.

Notes

StormContracts is designed to make player economies more active without relying on trust-based promises. Rewards are escrowed, progress only counts after tracking, delivery items are moved deliberately, refunds are explicit, and staff have tools to recover or review problematic contracts.

The result is a contract system that supports everyday jobs, community bounties, delivery requests, quest hooks, court capture work, and player-driven goals with safer payout handling.