📖 Table of Contents

• ✨ Why HeliosCore?
• 📋 Requirements
• 📥 Installation
• 🎮 Commands
• 🔐 Permissions
• 🌐 Web Dashboard
• ⚙️ Configuration
• 🔌 Developer API
• 🚀 Quick-Start Examples
• ❓ FAQ
• 💬 Support

✨ Why HeliosCore?

HeliosCore is required by every Helios plugin (HeliosAdmin, HeliosEconomy, HeliosChat, HeliosTab, NinezJobs, NinezSkills, NinezMarket, NinezGUI, NinezLogs, …). Instead of every plugin re-implementing storage, permissions, messaging, and dashboards, HeliosCore provides them once — so your whole suite shares a single source of truth.

🚧 Licensing is a work in progress. The License Server, key issuance, and runtime validation pipeline are still being finalized. HeliosCore currently runs in permanent offline grace mode — install and use the suite normally; the licensing layer will activate transparently in a future release.

✅ Adventure / MiniMessage native • PlaceholderAPI bridge • Vault adapter • bStats metrics

📋 Requirements

🔌 HeliosCore loads before all Helios plugins automatically (loadbefore directive).

📥 Installation

1. Drop HeliosCore-x.y.z.jar  →  plugins/
2. Start the server (config & data folder auto-generate)
3. Run  /hcore setup          (creates one-time dashboard owner link — REQUIRED)
4. Open the link printed in console → set username + password in your browser
5. (Optional) Edit plugins/HeliosCore/config.yml for storage, dashboard, license
6. Run  /hcore reload
7. Install other Helios plugins — they register into HeliosCore automatically

⚠️ /hcore setup is required. Until you run it and complete owner setup, the dashboard refuses logins.

🎮 Commands

Aliases: /hcore • /helioscore • /ncore • /ninezcore

🔐 Permissions

HeliosCore uses a clean, hierarchical permission tree that drops straight into LuckPerms, GroupManager, PermissionsEx, or vanilla op.

🌳 Hierarchy

helioscore.admin                  (default: op)  ━ grants EVERYTHING
└── helioscore.command.all                        ━ all leaf nodes below
    ├── helioscore.command.about
    ├── helioscore.command.reload
    ├── helioscore.command.services
    ├── helioscore.command.database
    ├── helioscore.command.dashboard
    ├── helioscore.command.doctor
    ├── helioscore.command.update
    ├── helioscore.command.setup
    └── helioscore.command.register

All nodes default to false for non-ops. Grant helioscore.admin for full access, or assign individual leaf nodes to staff roles.

💡 Suggested LuckPerms Setup

# ────────────── Owner — full control ──────────────
/lp group owner permission set helioscore.admin true

# ────────────── Admin — everything except setup/register ──────────────
/lp group admin permission set helioscore.command.all true
/lp group admin permission set helioscore.command.setup false
/lp group admin permission set helioscore.command.register false

# ────────────── Senior Staff — read-only diagnostics ──────────────
/lp group senior permission set helioscore.command.about true
/lp group senior permission set helioscore.command.services true
/lp group senior permission set helioscore.command.dashboard true
/lp group senior permission set helioscore.command.doctor true

🌐 Web Dashboard

HeliosCore ships with a built-in HTTP + SSE server. Every Helios plugin can mount its own page, actions, and live data feeds via the DashboardContributor API.

📊 Out of the box you get…

• 📈 Live server status — TPS, MSPT, memory, uptime, online players
• 📡 Audit log stream — every staff action across every plugin, in real time
• 🧩 Plugin tiles — one tile per Helios plugin showing its service health
• 💾 Backup controls (via HeliosAdmin) — create, list, delete, restore world backups
• 🔒 Role gating — OWNER / ADMIN / STAFF actions checked server-side
• 🔑 Token authentication — rotate any time with /hcore dashboard

🚀 First-Run Flow

1. /hcore setup                  → console prints a one-time link
2. Open link in browser          → set username & password for OWNER
3. Log in                        → Settings → Users to invite staff
                                   (or use /hcore register)

⚙️ Configuration

Key sections in plugins/HeliosCore/config.yml:

# Storage backend — shared by every Helios plugin
storage:
  type: sqlite        # yaml | sqlite | mysql | mariadb
  mysql:
    host: localhost
    port: 3306
    database: helios
    username: helios
    password: changeme
    pool-size: 10

# Web dashboard
dashboard:
  enabled: true
  host: 0.0.0.0
  port: 8765
  public-url: "https://panel.example.com"
  tls:
    enabled: false
    cert: ""
    key: ""

# Licensing — work in progress
# The license server and key issuance flow are still being built.
# These settings are read but currently no-op; HeliosCore runs in offline grace mode.
license:
  key: "PASTE-YOUR-LICENSE-HERE"
  server-url: "https://license.helios.dev"
  grace-period-hours: 72

# Audit log
audit:
  retention-days: 30
  console-mirror: false

# Debug logging
debug:
  enabled: false
  verbose-services: false

🔄 Run /hcore reload to apply changes without restarting.

🔌 Developer API

HeliosCore exposes services through a tiny, stable lookup:

import dev.ninez.core.api.CoreServices;
import dev.ninez.core.api.permission.PermissionService;
import dev.ninez.core.api.storage.StorageService;
import dev.ninez.core.api.message.MessageService;
import dev.ninez.core.api.audit.AuditService;

@Override
public void onEnable() {
    PermissionService perms   = CoreServices.require(this, PermissionService.class);
    StorageService    storage = CoreServices.require(this, StorageService.class);
    MessageService    msg     = CoreServices.require(this, MessageService.class);
    AuditService      audit   = CoreServices.require(this, AuditService.class);

    perms.registerPermissions(MyPermissions.defaults());
    audit.log(this, "Enabled MyPlugin");
}

Add HeliosCore as a hard depend in your plugin.yml:

depend:
  - HeliosCore

🚀 Quick-Start Examples

# ━━━━━━━━━━━ First boot ━━━━━━━━━━━
/hcore setup                          # Generate owner setup link (REQUIRED)
/hcore dashboard                      # Print dashboard URL & status

# ━━━━━━━━━━━ Day-to-day ━━━━━━━━━━━
/hcore                                # Status overview
/hcore services                       # Which plugins registered which services
/hcore doctor                         # Diagnostic health checks
/hcore database                       # Test storage backend connectivity
/hcore reload                         # Hot reload config

# ━━━━━━━━━━━ Maintenance ━━━━━━━━━━━
/hcore update                         # Check for ecosystem updates
/hcore register                       # Invite a new dashboard staff user

❓ FAQ

💬 Support