The Legacy Voyage

Developer API

Integration notes for economy, placeholders, storage-backed data, shops, playtime, stats, and UI-aware systems.

Back to HyEssentialsX Wiki
Table of Contents
Jump to a section
Wiki Home
📌 Overview
What it is, features, and goals
 › 🧰 Installation
Install steps + recommended setup
 › ⌨️ Commands
Command list + examples
 › 🔐 Permissions
Permission nodes and rank setup
 › ⚙️ Configurations
Config options and details
 › 🎓 Tutorials
Common setups and how-to guides
 › 👤 Author & Support
Contact, bugs, feedback, links
 ›
Storage-aware VaultUnlocked PlaceholderAPI

Integrate through plugin services, not storage files.

HyEssentialsX can store data in SQLite, JSON, MySQL/MariaDB, or MongoDB. External integrations should use exposed managers, APIs, commands, or supported integration providers instead of reading or writing storage files directly.

Economy Integration

  • Use the HyEssentialsX economy API or VaultUnlocked economy provider when available.
  • Preserve configured decimal places and money formatting.
  • Do not write balances directly to JSON or SQL tables.
  • Use admin economy commands only for operator/staff workflows, not automated integrations.

Placeholder Integration

  • Scoreboard and hologram systems support plugin placeholders where enabled.
  • HyEssentialsX chat formatting resolves nicknames, real names, LuckPerms or HyperPerms prefix/suffix/primary-group values, dynamic LuckPerms meta keys, and local group prefix/suffix fallbacks.
  • PlaceholderAPI can expose HyEssentialsX nickname, plain nickname, display name, real-name, LuckPerms, and HyperPerms placeholders to other configured text surfaces.
  • Keep high-frequency placeholders lightweight, especially in holograms and scoreboards.

Storage Rules

  • The selected backend in storage.type owns persistent plugin data.
  • Data shared across backends should be accessed through StorageManager/model-backed APIs.
  • Manual local files are only appropriate for config or explicitly local plugin assets.

UI-Aware Systems

  • Several workflows are intentionally UI-first: auction house listing, shop editing, stats, leaderboards, economy admin, playtime, scoreboard, and holograms.
  • Commands often open pages rather than dumping large data into chat.
  • Keep event names and UI data keys stable when extending custom UI pages.

Shops and Auction House

  • Admin shops, player shops, and auction house data should be managed through the plugin systems.
  • Player shop stock can be linked to containers; integrations should not assume infinite stock.
  • Auction listing limits may come from config and permission nodes.

Stats and Progression

  • Stats, playtime, and rankups are persistent and can affect rewards.
  • Leaderboard and baltop exclusions are permission-based.
  • Use manager/API access when reading progression data for another plugin.

Integration Checklist

Before shipping another plugin against HyEssentialsX.

Respect Permissions

Check the same permission nodes the command/UI path checks. Do not bypass staff-only flows accidentally.

Respect Config

Feature toggles can disable entire systems. Integrations should fail cleanly when a feature is off.

Respect Storage

Use plugin services so the same integration works with SQLite, JSON, MySQL/MariaDB, and MongoDB.