✨ VaultEconomy

Economy, server management, and custom gameplay — together.

VaultEconomy 3.0.0-rc1 combines a persistent economy with auctions, clans, teleportation, moderation, custom items, recipes, brewing, interactive fishing, achievements, and visual effects.

Build a Survival economy, create RPG progression, reward players for their activities, or connect multiple servers through a shared database.

Free features • Server-side gameplay • No required client mod • No external database required

🧩 Compatibility

Declared Minecraft compatibility: 1.13–26.3.

Velocity and BungeeCord are proxies. Custom items, inventories, crafting, fishing, and other world mechanics run on the connected gameplay servers.

The compatibility range is maintainer-declared. Included automated API reports cover Spigot 1.13, Spigot 1.21.11, and Paper 26.2; they do not certify every intermediate release or a live 26.3 deployment.

Use the Java version required by your server software. Features such as newer attributes, Darkness, CustomModelData, virtual anvils, and furnace acceleration depend on available server APIs.

🌟 Main Features

The Bukkit plugin registers 108 root commands. Its extension catalog contains 391 command paths, with 819 static permission definitions and additional content-specific permissions.

These are command paths and permissions, not a claim of 391 unrelated gameplay systems.

🎮 Where Can You Use It?

• Survival: balances, homes, player trading, clans, fishing, and achievements.
• RPG: custom potions, special items, crafting chains, progression, and rewards.
• Community servers: communication, kits, marriage, moderation, and shared clan activities.
• Events: particles, player effects, charged spears, collectible rewards, and command-driven items.
• Networks: shared balances, server switching, and proxy messaging.

VaultEconomy supplies configurable systems. It does not automatically generate cities, quests, NPCs, land claims, or a resource pack.

📥 Installation

1. Stop the server and back up existing plugin and player data.
2. Remove the previous VaultEconomy JAR.
3. Install VaultEconomy-3.0.0-rc1.jar.
4. Preserve the existing plugins/VaultEconomy directory.
5. Start the server.
6. Check /ve status and /vex status.
7. Configure permissions and test with a non-operator account.

SQLite is the default backend and is created automatically.

Optional integrations

Built-in economy commands work without Vault.

If another plugin registers the same command, use the namespace:

/vaulteconomy:balance
/vaulteconomy:pay Alex 25

English setup

Edit config.yml:

language: en

currency:
  symbol: "$"
  singular: coin
  plural: coins

Then run:

/ve reload
/language reload
/language set en

Bundled custom-content names may contain both languages. Edit those names separately in items.yml, fishing.yml, and achievements.yml.

💰 Economy and Custom Currencies

Main currency

/balance [player]
/pay <player> <amount>
/baltop [currency]

/eco give <player> <amount>
/eco take <player> <amount>
/eco set <player> <amount>

Aliases include /bal, /money, and /bits.

Additional currencies

Create tokens for events, progression, or rewards:

/point create tokens T
/point list
/point give tokens Alex 50
/point balance tokens Alex
/point pay tokens Alex 5
/baltop tokens

Administrative operations support give, take, and set.

Transaction handling

• Amounts use integer hundredths.
• Commands accept up to two decimal places.
• Invalid amounts, overflow, and self-payments are rejected.
• Transfers commit before success is reported.
• Failed storage operations are not reported as successful payments.

Vault exposes the main currency. Additional currencies use the plugin’s own commands and placeholders.

Vault bank accounts are not implemented. Clan treasuries use internal accounts.

🛍️ Auction House

Sell the item stack in your main hand:

/ah sell 250

Other commands:

/ah
/ah mine
/ah cancel <listing-id>
/ah claim
/claim
/ahelp

Included behavior

• Listing browser with seller and price.
• Purchase confirmation.
• Configurable sale tax.
• Offline seller payments.
• Listing expiration.
• Returns and purchases delivered through a queue.
• Administrative recovery tools for interrupted operations.

/claim collects the next queued delivery when inventory space is available.

auction:
  tax-percent: 3.0
  lifetime-seconds: 172800

limits:
  auction: 5

172800 seconds equals 48 hours.

Recovery commands:

/ah recover list
/ah recover <operation-id> restore
/ah recover <operation-id> discard

Ambiguous item deliveries require an administrator to check records and inventories before choosing a recovery action.

🛡️ Clans and Social Features

Clans have four roles: member, officer, deputy, and owner.

Features include:

• Invitations and open joining.
• Treasury deposits and withdrawals.
• Clan home.
• Shared storage from 27 to 54 slots.
• Storage upgrades.
• Banners and clan chat.
• Promotions, demotions, and ownership transfer.
• PvP toggle.
• Alliances and war relationships.

/clan
/clan help
/clan create <name>
/clan invite <player>
/clan accept
/clan join <clan>
/clan deposit <amount>
/clan withdraw <amount>
/clan home
/clan storage
/clan upgrade

clans:
  create-price: "1000.00"
  storage-upgrade-price: "2000.00"
  max-members: 20

Permissions and clan roles are checked separately. A command permission does not automatically grant treasury authority.

Diplomacy does not include territory claiming.

Marriage and communication

/marry propose <player>
/marry accept
/marry info
/marry chat <message>
/marry divorce confirm

/msg <player> <message>
/reply <message>
/ignore <player>
/mail read
/mail send <player> <message>

🏠 Teleportation and Daily Utilities

Teleport requests expire after 60 seconds.

teleport:
  delay: 3

limits:
  homes: 2
  near: 100
  auction: 5

rtp:
  radius: 2000

cooldowns:
  spawn: 10
  home: 10
  warp: 10
  back: 10
  tpa: 5
  rtp: 120
  clanhome: 15

Teleport delays and cooldowns are measured in seconds.

Kits save main inventory contents, excluding armor and off-hand. Access requires the root kit permission and vaulteconomy.kit.<name>.

📦 Custom Items Without Java

Create reusable definitions in items.yml.

IDs use lowercase letters, numbers, underscores, and hyphens, with a maximum length of 48 characters.

Example: wand and potion

Merge these definitions into the existing items: section:

items:
  wind_wand:
    enabled: true
    public: true
    material: BLAZE_ROD
    name: "&bWind Wand"
    cooldown-seconds: 15

    lore:
      - "&7Right-click for Speed II."
      - "&8Cooldown: 15 seconds"

    actions:
      right_click:
        - "effect SPEED:8:2"
        - "sound ENTITY_EXPERIENCE_ORB_PICKUP"
        - "animation spiral"
        - "message &bThe wind carries you forward!"

  frost_potion:
    enabled: true
    public: true
    material: POTION
    name: "&bFrost Potion"
    color: "66CCFF"

    effects:
      - "SLOWNESS:30:2"
      - "RESISTANCE:30:1"

Apply and obtain:

/customitem reload
/customitem give wind_wand 1
/customitem give frost_potion 1 Alex

Item settings

CustomModelData does not generate a texture. A compatible resource pack is needed for custom models or appearances.

Effect syntax

TYPE:seconds:level

STRENGTH:45:3 means Strength III for 45 seconds.

Potion definitions support durations of 1–86,400 seconds and levels 1–255, subject to available server effects.

Create with commands

/customitem create frost_potion POTION
/customitem name frost_potion &bFrost Potion
/customitem effect add frost_potion RESISTANCE:30:1
/customitem color frost_potion 66CCFF
/customitem give frost_potion 1

New definitions default to public: false. Change it in YAML or grant the specific content permission.

Additional management:

/customitem list
/customitem inspect <id>
/customitem clone <id> <new-id>
/customitem delete <id> confirm
/customitem menu

🪄 Item Actions

Triggers

• right_click — right-click in the air or on a block.
• left_click — left-click in the air or on a block.
• target — right-click another player.

Actions

message <text>
effect TYPE:seconds:level
command <player-command>
console <console-command>
jail <cell>:<seconds>
sound <SOUND>
animation <style>

Command actions support {player} and {target}. Write commands without a leading slash.

Player commands use the player’s permissions. Console commands are administrator-defined actions.

Action use does not automatically consume the item.

Jail wand example

items:
  prison_wand:
    enabled: true
    public: false
    material: BLAZE_ROD
    name: "&5Prison Wand"
    cooldown-seconds: 5

    actions:
      target:
        - "jail default:60"
        - "sound BLOCK_ANVIL_LAND"

/jail set default
/customitem give prison_wand 1

Using it requires both:

vaulteconomy.item.use.prison_wand
vaulteconomy.item.target.prison_wand

Identity and updates

Custom items use HMAC-signed lore markers. Renaming an ordinary item does not turn it into a valid custom item.

Preserve the signing key stored in the backend.

Changing a definition affects future creation and action lookup. Existing item names, lore, and potion metadata are not automatically rebuilt in every inventory.

🔨 Crafting and Recipe Control

Recipes belong in recipes.yml.

Supported types:

shaped
shapeless
furnace

Shaped recipe

recipes:
  frost_craft:
    enabled: true
    public: true
    type: shaped
    result: frost_potion
    amount: 1

    shape:
      - " I "
      - "IPI"
      - " I "

    ingredients:
      I: ICE
      P: POTION

Spaces represent empty slots.

Use custom:<id> for exact signed custom ingredients:

ingredients:
  P: "custom:frost_potion"

Results use the item ID without custom:.

Signed custom items are not accepted as ordinary crafting ingredients simply because their material matches.

Recipe editor

/recipe create frost_craft shaped frost_potion
/recipe shape frost_craft _I_/IPI/_I_
/recipe ingredient frost_craft I ICE
/recipe ingredient frost_craft P POTION
/recipe enabled frost_craft true

In commands, / separates rows and _ means an empty slot.

New recipes start disabled and private. Finish the definition, enable it, and configure its permissions.

Blocking recipes

/recipe block minecraft:diamond_sword
/recipe unblock minecraft:diamond_sword
/recipe blockresult DIAMOND_SWORD
/recipe unblockresult DIAMOND_SWORD
/recipe reload

Blocking uses the Bukkit recipe registry. Recipes registered later by another plugin may require another reload.

Smelting definitions require ordinary material inputs; exact custom ingredients are supported for crafting and brewing.

⚗️ Brewing and Custom Furnaces

Brewing — brewing.yml

recipes:
  frost_brew:
    enabled: true
    public: true
    base: POTION
    ingredient: ICE
    result: frost_potion
    ticks: 200
    fuel: true

1. Put matching base potions into the stand.
2. Add blaze powder when required.
3. Add the ingredient, or hold it if the vanilla interface will not accept it.
4. Sneak-right-click the stand or look at it and run /brew start.
5. Leave the inventory unchanged until completion.

200 ticks is approximately ten seconds at normal tick rate. One blaze powder supplies 20 cycles.

/brew create <id> <base> <ingredient> <result-id>
/brew ticks <id> <ticks>
/brew fuel <id> <true|false>
/brew enabled <id> <true|false>

Custom furnaces

Add this section to a custom FURNACE item:

furnace:
  speed: 2
  fuel-multiplier: 2
  output-multiplier: 1

• speed: 2 requests half the normal cooking time.
• fuel-multiplier: 2 makes fuel last twice as long.
• output-multiplier changes output quantity within stack limits.

Acceleration requires the relevant server API. Normal supported block drops can preserve custom furnace identity; explosions do not guarantee item recovery.

🎣 Interactive Fishing

Fishing adds a timing minigame after a qualifying vanilla catch.

The interface uses a moving indicator, green target zone, and hit/miss counters. Right-click or press the swap-hand key, normally F, inside the target zone.

Defaults:

game:
  hits: 5
  misses: 3
  period-ticks: 40
  window: 0.28

Five hits land the fish. Three misses or missed windows lose it. Moving more than eight blocks away ends the attempt.

Included species

• River Carp.
• Silver Salmon.
• Moon Ray.
• Abyss Puffer.
• Golden Leviathan.

Custom species — fishing.yml

species:
  crystal_carp:
    enabled: true
    name: "&bCrystal Carp"
    material: COD
    rarity: rare
    chance: 5
    price: 20

    weight:
      min: 0.5
      max: 4.0

    length:
      min: 20
      max: 80

    worlds: []
    biomes: []
    rain-only: false

Weight is measured in kilograms; length in centimeters.

chance is a relative selection weight, not an independent percentage. Empty world and biome lists mean unrestricted selection.

Player commands

/fish menu
/fish price
/fish sell
/fish sellall
/fish list
/fish stats
/fish cancel
/fish animation ripple

Buyer

The buyer is a menu and command system, not an automatically spawned NPC.

/fish buyer set
/fish buyer require-location true

Location enforcement requires players to sell within six blocks of the saved point.

Price depends on base price, size, rarity, selection weight, and buyer multipliers.

Each generated fish has a signed serial number. A serial already sold cannot receive another payout.

Administrators can edit species with /fishspecies, buyer settings with /fish buyer, and difficulty with /fish difficulty.

✨ Effects and Charged Spears

Particle patterns

ring, spiral, helix, double_helix, wave,
orbit, fountain, vortex, star, pulse,
figure_eight, rain, comet, crown, ripple

/fx preview spiral
/fx sound ENTITY_EXPERIENCE_ORB_PICKUP
/fx title Welcome|Enjoy_your_stay
/fx styles

Spears

/spear give
/spear style storm
/spear styles

Hold the custom spear, sneak to charge, then throw within three seconds after releasing sneak.

Styles:

ember
storm
void
tidal
solar

Settings in effects.yml:

particles: true
sounds: true
points-per-frame: 12

spear:
  charge-ticks: 60
  screen-darkening: true
  max-speed-bonus: 1
  max-damage-bonus: 8

Screen darkening uses available potion effects, not a custom client shader.

🏆 Achievements

Create progression in achievements.yml:

achievements:
  stone_collector:
    enabled: true
    public: true
    name: "&6Stone Collector"
    icon: STONE
    trigger: block_break
    match: STONE
    goal: 500
    auto-claim: false

    rewards:
      money: 100
      items:
        - "reward_token:2"
      commands: []

Triggers

block_break
block_place
kill
death
craft
join
vanilla_advancement
fish_catch
fish_sell
item_use
brew
spear_throw

Use match: "*" when no specific match is required.

/achievements
/achievements progress <id>
/achievements rewards <id>
/achievements claim <id>
/achievements claimall

Item rewards enter /claim. Reward commands support {player} and {uuid}.

Money, claimed status, and queued item rewards are recorded together. External console commands cannot share a transaction with another plugin; interrupted rewards may need inspection.

Administrative tools:

/achievementedit create <id> <trigger> <goal>
/achievementedit grant <id> <player>
/achievementedit reset <id> <player> confirm
/achievementedit pending <player>

Creative block breaking/placing does not count. Previously completed vanilla advancements are not automatically imported.

🛠️ Item Editing and Player Controls

Held-item editor

/itemedit name &6Explorer's Sword
/itemedit lore-add &7An expedition reward.
/itemedit enchant sharpness 5
/itemedit unenchant sharpness
/itemedit enchants-clear
/itemedit potion-add SPEED 30 2
/itemedit potion-remove SPEED
/itemedit attribute-add attack_damage 3 ADD_NUMBER
/itemedit repair
/itemedit info

Also supports material, amount, durability, item flags, CustomModelData, books, leather color, potion color, and player heads.

/itemedit edits the held item. /customitem edits reusable definitions.

Potion removal affects custom potion effects. It is not a universal editor for every vanilla base-potion property or another plugin’s custom metadata.

Player controls

/playerctl glowing true Alex
/playerctl freeze Alex
/playerctl unfreeze Alex
/playerctl effect speed 30 2 Alex
/playerctl cure speed Alex
/playerctl attribute scale 1.5 Alex
/playerctl attribute-reset scale Alex

Additional controls include health, food, air, flight, movement, gravity, names, titles, velocity, effects, and disguises.

Attributes such as scale and interaction range require a server version that provides them.

Moderation and jail

/kick <player> [reason]
/ban <player> [reason]
/tempban <player> <seconds> [reason]
/mute <player> [reason]
/tempmute <player> <seconds> [reason]

/jail set default
/jail send Alex default 60
/jail info Alex
/jail release Alex

Jail preserves the sentence and return location. Sentence time continues while offline.

Inventory tools

/craft
/anvil
/enderchest [player]
/invsee <player>
/sejf
/repair [all]

Other-player inventory inspection is read-only. The personal safe has 54 slots.

🔑 Permissions

Core commands use:

vaulteconomy.<command>

Extension commands need both root and command-path permissions.

Example for freezing another player:

vaulteconomy.playerctl
vaulteconomy.playerctl.freeze
vaulteconomy.playerctl.freeze.others

Content permissions

public: true changes applicable content defaults. It does not grant editing, giving, or target-action rights.

Activity permissions

vaulteconomy.fish.play
vaulteconomy.spear.use
vaulteconomy.effects.view
vaulteconomy.achievements.earn

Useful additional permissions

vaulteconomy.balance.others
vaulteconomy.eco.give
vaulteconomy.eco.take
vaulteconomy.eco.set
vaulteconomy.repair.all
vaulteconomy.gamemode.creative
vaulteconomy.vanish.see
vaulteconomy.combat.bypass
vaulteconomy.cooldown.bypass
vaulteconomy.teleport.instant
vaulteconomy.kit.cooldown.bypass

Rank limits

vaulteconomy.limit.homes.10
vaulteconomy.limit.auction.15
vaulteconomy.limit.rtp.5000
vaulteconomy.limit.near.200

Positive numeric permissions increase the configuration baseline, within built-in maximums.

LuckPerms examples

/lp group vip permission set vaulteconomy.fly true
/lp group vip permission set vaulteconomy.limit.homes.10 true
/lp group default permission set vaulteconomy.item.use.wind_wand true
/lp group default permission set vaulteconomy.recipe.craft.frost_craft true

Most editing and administrative commands default to operators. Everyday economy, social, fishing, and achievement commands are generally available to players, with additional checks where applicable.

Use:

/vex help [page]
/vex permissions [filter]

The archive contains the full permissions.json and docs/COMMAND_CATALOG.md. Help and extension command-path suggestions are permission-filtered.

💾 Storage

Choose one of 11 backends:

These are selectable alternatives, not simultaneous replicas.

MySQL example

storage:
  type: MYSQL
  url: "jdbc:mysql://127.0.0.1:3306/minecraft"
  username: minecraft
  password: "CHANGE_ME"

PostgreSQL example

storage:
  type: POSTGRESQL
  url: "jdbc:postgresql://127.0.0.1:5432/minecraft"
  username: minecraft
  password: "CHANGE_ME"

JDBC drivers are included. Remote databases must exist and allow the plugin to create and use its table.

There is no dedicated SUPABASE, ORACLE, or CUSTOM_JDBC mode. A compatible hosted PostgreSQL service uses POSTGRESQL with its connection settings.

The backend stores plugin records, including balances, social data, auctions, locations, progress, and signing keys. Minecraft still manages world and player-inventory files.

Performance model

Storage saves complete state snapshots. SQL uses a shared locked record, so remote latency and frequent writes can affect performance.

Do not share file backends between server processes. Large-network throughput is not established by the included tests.

Backups and audit

/ve backup
/ve audit 25

Exports are stored in the plugin’s backups directory. The economy journal retains the latest 2,000 entries.

Backend changes require stopped-server export/import migration. Preserve storage.binding and the item-signing key. Instructions are included in docs/STORAGE_RU.md.

🌐 Velocity and BungeeCord

Proxy settings are stored in proxy.properties.

hub=lobby
language=en
economy.enabled=false
storage.type=MYSQL
storage.url=jdbc:mysql://127.0.0.1:3306/minecraft
storage.username=minecraft
storage.password=CHANGE_ME

Network commands

Permissions use:

vaulteconomy.proxy.<command>
vaulteconomy.proxy.server.<server-name>

Additional rights apply to other-player balances and administrative money operations.

Grant permissions on the proxy. Bukkit operator status does not automatically transfer.

Shared economy

Use a common remote SQL backend, matching player UUIDs, and different backend identities:

server-id: survival

server-id: skyblock

Proxy economy is disabled by default. Set economy.enabled=true after configuring storage.

Backend chat mutes and ignores do not automatically govern /gmsg.

🌍 Languages and Placeholders

Included Bukkit translations:

lang/en.yml
lang/ru.yml

To add another language:

1. Copy en.yml to a new language code, such as de.yml.
2. Translate values while preserving keys and {0}-style placeholders.
3. Reload and select it:

/language reload
/language set de

Missing translations fall back to English. Some older event messages use the server language.

Content names and lore belong to their definition files and are not translated separately for each viewer.

Proxy translations use UTF-8 .properties files.

PlaceholderAPI

%vaulteconomy_balance%
%vaulteconomy_balance_formatted%
%vaulteconomy_points_tokens%
%vaulteconomy_clan%
%vaulteconomy_prefix%
%vaulteconomy_kills%
%vaulteconomy_deaths%
%vaulteconomy_storage%

The expansion registers automatically when PlaceholderAPI is installed.

⚙️ Configuration and Reloads

Reload commands

/ve reload
/vex reload
/language reload
/customitem reload
/recipe reload
/fish reload
/achievementedit reload

• /ve reload updates core configuration.
• /vex reload reloads extension definitions, languages, recipes, and content permission defaults.
• Content-specific reload commands use shared extension reload paths.
• Storage and server-id are not switched live.

Use enabled switches where available and permissions to control access. GUI text is translatable, but this release does not include a universal YAML layout editor for every menu.

🧪 Release Notes and Verification

This is a release candidate.

Included reports contain 156 core checks, 18 extension-core checks, and 42 MockBukkit checks covering persistence, transactions, signatures, recipe matching, fish-sale tracking, and achievement rewards.

These reports do not replace real-server testing of every platform, remote database, physical gameplay mechanic, or multi-region Folia setup.

All features in this source release are available without paid activation, license checks, or trial expiration.