> For the complete documentation index, see [llms.txt](https://tne.gitbook.io/vaultunlocked/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tne.gitbook.io/vaultunlocked/overview/introduction.md). # Introduction ## Introduction to VaultUnlocked **VaultUnlocked** is a modern, cross-platform service abstraction API designed to provide a **single, stable integration layer** for **Economy**, **Permissions**, and **Chat** systems. It is the spiritual successor to the original Vault API, rebuilt with modern platforms, extensibility, and long-term maintenance in mind. VaultUnlocked supports: * **Paper / Spigot / Bukkit** * **Hytale** with the **same core API concepts and philosophy**, allowing plugins to remain portable across ecosystems. *** ### Downloads & Source #### Paper / Spigot / Bukkit / Folia * **Download:**\ * **Source Code:**\ *** #### Hytale * **Download:**\ * **Source Code:**\ *** ### What Problem Does VaultUnlocked Solve? In multiplayer server environments, plugins often need access to: * Player balances * Permission checks * Group metadata * Chat prefixes, suffixes, and formatting data Without a shared abstraction layer, plugins must: * Hard-depend on specific implementations * Re-implement compatibility logic * Break when providers change VaultUnlocked solves this by acting as a **neutral contract** between plugins, allowing providers and consumers to evolve independently. *** ### Enhanced Functionality Over Vault VaultUnlocked builds upon the foundation laid by Vault, but significantly expands what is possible—especially for plugins that adopt the updated API. It is designed to handle **modern server requirements**, **complex economic systems**, and **advanced execution models** that the original Vault API was never built to support. *** ### Why VaultUnlocked? Choosing VaultUnlocked over Vault offers clear advantages for both **plugin developers** and **server administrators**. VaultUnlocked: * Extends Vault’s original concepts with modern capabilities * Supports advanced server frameworks like **Folia** * Introduces multicurrency and precision-based economy handling * Remains actively maintained and forward-looking For servers running complex economies or modern infrastructure, VaultUnlocked is a **more robust, future-proof solution**. *** ### Key Improvements and Additional Functionality #### Multicurrency Support VaultUnlocked introduces **native multicurrency support**, allowing servers to operate multiple currencies simultaneously. This enables: * Region-based currencies * Faction-specific economies * Premium vs standard currencies * Advanced gameplay-driven economic systems By handling multiple currencies cleanly, VaultUnlocked ensures transactions remain accurate and flexible across diverse server designs. *** #### BigDecimal-Based Economy Calculations VaultUnlocked uses **BigDecimal** for economy values, enabling: * High-precision calculations * Accurate fractional values * Reliable handling of very large numbers This is essential for servers with complex or long-running economies where floating-point inaccuracies are unacceptable. *(BigDecimal and UUID contributions by LlmDl)* *** #### UUID-Based Player Identification VaultUnlocked fully supports **UUID-based identification**, ensuring: * Player data remains consistent * Name changes do not break economies or permissions * Long-term data reliability across systems This aligns VaultUnlocked with modern server expectations and best practices. *** #### Folia Support VaultUnlocked is compatible with **Folia**, a server framework focused on scalability and concurrency. This allows: * Safe usage in regionized execution environments * Better performance under load * Compatibility with next-generation server architectures VaultUnlocked abstracts away platform differences while remaining safe and predictable. *** #### Better Plugin Compatibility VaultUnlocked improves compatibility with popular plugins such as **Towny**, reducing: * Conflicts between systems * Edge-case behavior in permissions and economy handling * Performance overhead caused by legacy assumptions This results in smoother plugin interactions and more stable server environments. *** #### Active Development VaultUnlocked is **actively developed**, ensuring: * Ongoing improvements * Bug fixes and optimizations * Continued compatibility with evolving platforms * Responsiveness to community feedback Unlike legacy Vault, VaultUnlocked is designed to evolve alongside modern server ecosystems. *** ### Core Functionality VaultUnlocked provides standardized access to: #### Economy * Balance retrieval * Deposits and withdrawals * Multicurrency support * Precise financial calculations * Account existence checks #### Permissions * Tri-state permission checks (TRUE / FALSE / UNDEFINED) * Context-aware lookups (global vs world) * Explicit subject modeling (players and groups) * Metadata access #### Chat * Prefix and suffix retrieval * Context-aware chat metadata * Unified formatting access * Provider-agnostic chat integration *** ### Providers and Consumers VaultUnlocked is built around two roles: #### Providers Providers are plugins that **supply functionality**, such as: * Economy plugins * Permission systems * Chat formatting plugins They implement VaultUnlocked interfaces and register themselves so other plugins can use them. #### Consumers Consumers are plugins that **use functionality**, such as: * Gamemodes * Minigames * Factions and land systems * Shops, NPCs, and UI plugins Consumers remain independent of specific implementations. *** ### Cross-Platform by Design VaultUnlocked is intentionally consistent across platforms: * Identical API concepts * Shared package structure * Consistent service boundaries This allows developers to: * Write integrations once * Support multiple platforms * Avoid platform-specific rewrites While internal registration differs between Paper and Hytale, the **developer-facing API remains familiar**. *** ### What VaultUnlocked Is Not VaultUnlocked is **not**: * An economy plugin * A permissions plugin * A chat formatting plugin It does not store data or enforce behavior. VaultUnlocked defines **how plugins communicate**, not what they do internally. *** ### Who Should Use VaultUnlocked? VaultUnlocked is ideal for: * Plugin developers targeting Paper, Spigot, Bukkit, or Hytale * Servers running multiple interacting plugins * Developers maintaining cross-platform ecosystems * Anyone seeking clean, future-proof integrations *** ### Moving Forward The rest of the documentation covers: * Providing Economy, Permissions, and Chat services * Consuming VaultUnlocked services * Platform-specific lifecycle notes * Best practices for performance and compatibility VaultUnlocked exists to make plugin ecosystems **simpler, more powerful, and future-proof** — across both current and next-generation platforms. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://tne.gitbook.io/vaultunlocked/overview/introduction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.