KoleVault

A lightweight and developer-friendly economic plugin for Hytale servers. Designed to simplify resource management, KoleVault handles databases, resources, and transactions so you can focus on building great gameplay experiences.

✨ Features

• Resource Management: Store and manage any virtual resource (gold, diamonds, experience, etc.) through a flexible YAML configuration.
• Complete Transaction System: Commands for payments, requests, and a full audit history.
• Event-Driven API: Extensible architecture allowing other plugins to listen to economic events (transfers, balance changes).
• Database Ready: Built-in support for HyDB (SQLite) with automatic table management.
• Clean Commands: Intuitive commands with tab completion and helpful feedback.

🚀 Quick Start

Installation (Server Admins)

1. Install Dependencies: Place the following .jar files in your server's mods/ folder and restart the server:
   • HyDB (for database management)
   • TinyMessage (for formatted chat messages)
2. Install KoleVault: Place KoleVault-Core.jar in the mods/ folder.
3. Configure: On first run, edit the generated config file at plugins/KoleVault/resources.yml.
4. Restart: Restart your server for changes to take effect.

📖 Commands & Usage

Player Commands

Get Balance

• /balance
• Aliases: /bal, /money
• Description: View your or another player's resource balances.
• Options:
• -p=<player> - Specify a player.
• Examples:
  • /balance - Shows your own balance.
  • /balance --p=Alex - Shows the balance of the player "Alex".

Pay Another Player

• /pay <player> <amount>
• Aliases: /payPlayer
• Description: Transfer resources to another player. Uses the main currency by default.
• Options:
  • -r=<resource_id> - Specify a different resource (e.g., -r=diamonds).
  • -c="text" - Add a note to the transaction.
• Examples:
  • /pay Alex 100 - Send 100 of the main currency to Alex.
  • /pay Alex 50 -r=experience -comment="For helping with the quest" - Send 50 experience points.

Request Resources

• /req <player> <amount>
• Aliases: /request, /requestResource
• Description: Send a resource request to another player.
• Options: Same as /pay (-r, -comment).
• Example: /req Alex 200 -r=gold -comment="Loan for a new tool"

Manage Your Requests

• /reqCan <player>
• Aliases: /reqDecline, /requestDecline
• Description: Cancel a resource request you have sent.
• Example: /reqCan Alex --r=gold --c="Nevermind. I need it more."

Decline Incoming Requests

• /reqDec <player>
• Aliases: /reqDecline, /requestDecline
• Description: Decline or decline a pending resource request sent to you.
• Example: /reqDec Alex --r=diamonds --c="Sorry, I'm short on diamonds."

Accept Incoming Requests

• Accept: /reqAcc [request_id] (Aliases: reqAccept, requestAccept)
• Decline: /reqDec [request_id] (Aliases: reqDecline, requestDecline)
• Description: Accept or decline a pending resource request sent to you.
• Example: /reqAcc Alex --r=gold

(Full list available on GitHub page)

Command Options

Most commands support optional flags:

• -r=<resource_id>: Specify which resource to use (defaults to main_currency from config). bash /pay Alex 100 -r=diamonds /req Alex 50 -r=experience
• -comment="text": Add a note to the transaction. bash /pay Alex 100 -comment="For the legendary sword!"

⚙️ Configuration

Define your resources in plugins/KoleVault/resources.yml:

main_currency: "gold"

resources:
  gold:
    display_name: "<c:gold>Gold coins</c>"
    # "short_sign" is used for string formatting
    # Examples:
    # - "Your balance: 5$"
    # - "You have 1🗝️. You need 2🗝️ to open the lock."
    # - "You need more 🌟Experience to use this item. Gain 50🌟 more."

    #Too bad Hytale does NOT support emojis
    short_sign: "$"
    default_amount: 100.0
    transferable: true  # can be transferred to other players

  # other resources
  diamonds:
    display_name: "<c:aqua>Diamonds</c>"
    short_sign: "D"
    description: "Hello, it's an optional description!" # OPTIONAL!
    default_amount: 0.0
    max_amount: 1000.0 #OPTIONAL! Remove to disable the maximum
    min_amount: 0.0 #OPTIONAL! Remove to disable the minimum
    transferable: true

  keys:
    display_name: "<c:yellow>Keys</c>"
    short_sign: "K"
    default_amount: 0.0
    max_amount: 100.0
    min_amount: 0.0
    transferable: false

🛠️ API for Developers

KoleVault provides an event-based API for easy integration. You'll find the examples on the GitHub page of the project.

🚧 Current Status

Under Active Development - Core features are stable, but expect improvements and additions.

🤝 Contributing & Feedback

Found a bug? Have a feature request? Please:

~Open an issue on the GitHub repository~ There is no accessible repository YET. It will be available in the next few days.

Feel free to leave comments with your suggestions.

Share how you're using the plugin!

This plugin was crafted to simplify economic interactions — so you can focus on building great experiences, not boilerplate code.