NovaSyncPlugin — Frequently Asked Questions
What is NovaSyncPlugin?
An all-in-one server management plugin for Paper. Web dashboard with granular RBAC (Owner / Admin / Moderator / Viewer + custom roles), 7-detection anti-cheat, chat moderation (120+ regex / English + Afrikaans), role system with damage protection, zones & warps & homes, groups / clans / families, web-based voice chat (Java + Bedrock), full economy (mob rewards, shops, kits, leaderboards, voice bonuses), GFS backup scheduling, player analytics, live console, file manager, scheduler, NovaLink directory listing, voice-controlled admin commands, world-seed change tool, customisable Welcome Book for new players, plugin auto-update with Stable / Fast channel, multi-channel notifications (WhatsApp / Discord / SMTP) per-admin, TOTP 2FA, and multiplayer Nova AI companion sync. One JAR, no required dependencies.
How do I change the dashboard password?
Settings tab → 🔐 Security pill → Change Dashboard Login. Type your current password + the new one (6+ chars). Hitting save invalidates every active session so everyone has to log in fresh. If you're locked out, drop an empty RESET-LOGIN.txt into plugins/NovaSyncPlugin/ and run /nova reload — credentials reset to admin / changeme. If you've configured SMTP (below), the "Forgot password?" link on the login page emails recovery steps to dashboard.recovery-email.
How do I enable password-recovery email (SMTP)?
Edit plugins/NovaSyncPlugin/config.yml → dashboard.smtp block. Recommended free-tier providers (port 587 STARTTLS): Brevo (smtp-relay.brevo.com, 300/day free), Mailjet (in-v3.mailjet.com, 200/day), Mailgun (smtp.mailgun.org, 100/day), Gmail (smtp.gmail.com — use an App Password, not your real one). Fill host / port / username / password / from, set enabled: true, then /nova reload. Verify with curl -u admin:YOURPASS -X POST -H 'Content-Type: application/json' -d '{"to":"you@example.com"}' http://your-server:8585/api/email/test — success = working.
How do I link a second server (cross-node sync)?
On the first node: Overview tab → copy the network key from the onboarding card + copy its public dashboard URL (both shown in "Copy Invite for Peer"). On the second node: open its dashboard → Overview → onboarding card → paste the peer URL + paste the same network key → click 🔍 Test Connection → if green, click 💾 Save + Link. Port 8585 (dashboard API) must be reachable between the two nodes — open the firewall / forward the port on both sides. Players, blocks, chat, voice, bans, and /pay then sync both ways.
Stable vs Fast update channel — which should I be on?
NovaSync ships through two channels from the central CDN: Stable (default — polished releases) and Fast (every new build — newest features, may have rough edges). Update banners show channel-specific colour: green strip = Stable available, amber strip with 🧪 badge = Fast-channel available. Switch via 👑 Owner → ⚙ Settings → NovaSync Update → Update channel. Stable → Fast requires the maintainer's PIN (4 digits, ask if you want testing-track features). Fast → Stable is one click, no PIN. After the channel switch, the next stable release auto-applies. Recommendation: production servers stay on Stable; test boxes and adventurous operators flip to Fast to help shake out bugs before they reach Stable.
I'm running a single server. How do I hide the "link a peer" card?
Click "I'm running single-server — hide this" at the bottom of the onboarding card. That writes network.single-server-mode: true into config.yml, disables the peer-sync subsystem, and keeps the card hidden across every browser (not just yours). To re-enable peer sync later, flip the flag back to false and restart.
Voice chat isn't working — what do I check?
Most common fixes in order: (1) Simple Voice Chat plugin installed? Optional but recommended for ambient proximity audio for Java players — grab from modrinth.com. (2) Port 8586 open? The browser /voice page (Java + Bedrock) needs port 8586 forwarded (self-signed cert auto-generated; HTTPS required for mic permission). (3) Mic permission granted? Browser requires HTTPS + explicit mic permission. (4) Bedrock players? They join via the same /voice URL — paste the PIN into the web client. The dashboard's top-level 🎤 Voice tab (Live sub-tab) shows live sessions + admin actions: talk to one player, broadcast to all, listen feed, auto-stop on empty, voice bonuses (XP boost / currency drip / particle aura / shop discount), and per-player kick. Voice quota usage and config keys live in 🎤 Voice → Settings.
How do I pardon / unban an unfairly-banned player?
Two ways: (1) Reports & Bans tab → find the ban row → click Pardon, or (2) open the player's profile → click Unban. Both do the same thing: lift the Bukkit ban AND mark the ban-history row as pardoned. Pardons are local-only (each server its own). If they hit /appeal/<uuid> from the kick screen, the appeal lands in the Reports tab for your review.
How does the Economy work?
Full earn-and-spend loop is live. New players start with a configurable balance, then earn from: mob-kill rewards (per-mob coin drops, configurable in 💰 Economy → Mob Rewards), shops (place a chest + sign with [shop], line 2 = item, line 3 = price — buy/sell signs with right-click), kits (claimable item bundles with cooldowns), daily login streaks, voting rewards, and voice bonuses (toggle "Currency drip" in 🎤 Voice → Settings → Bonuses to give coins to voice-active players over time). Players spend via shops, kits, and /pay <player> <amount>. Admin tools: 💰 Economy → Overview (total in circulation, top earners), Activity (ledger), Shops (GUI shop editor + chest-shop list), Kits (price/cooldown editor), Mob Rewards (per-mob coin table + bonus events), Config (start balance, taxes, transfer fees), Leaderboards. Disable entirely by flipping economy.enabled: false in config.yml.
How do I schedule auto-restarts?
Scheduler tab → New Task. Set a cron expression (e.g. 0 4 * * * = every day at 4am) + command (say [SERVER] restart in 60s followed by a stop with a short gap). If you run via ./start.sh (the default for bare Paper), a clean stop gets auto-respawned by the supervisor. WhatsApp / Discord notifications fire on restart if configured in Notifications.
My server's TPS is dropping — where do I start?
Overview tab → TPS History chart. Dropdown cadence 1–60s for finer detail. Drops below 18 are visible; below 15 is felt by players. Common causes, in order: (1) render distance too high — check server.properties view-distance, try 8–10 for busy servers. (2) too many entities — /nova despawnmobs 200 clears hostile mobs in radius. (3) slow plugin event handler — check the Dev tab's performance panel for which plugin's events cost the most. (4) full JVM heap — bump -Xmx in jvm.env, restart. Stream Rates card on Overview also shows if cross-server replication is saturating.
Roles vs Zones — when do I use which?
Roles apply to a player everywhere on the server — PVP off, flight, creative, build protection, etc. Best for "this player type always plays this way" (new-player Noob role, trusted Builder role, Admin).
Zones apply to an area regardless of who's in it — safezone at spawn (no damage, no PVP), PvP zone in an arena (PVP forced on), creative zone in a build server section. Best for "behaviour depends on location".
When they conflict, the zone wins for location-scoped behaviour (PVP, damage, gamemode), and the role wins for everything else (build protection, chat colors, commands).
How do I form a group / clan / family?
Players form groups in chat — no slash-command knowledge required, a sign at spawn explains it. The aliases /group, /clan, /family, /party all do the same thing.
Create: /group create <name>
Invite a player: /group invite <player>
Accept an invite: /group accept <name>
Leave: /group leave
Disband: /group disband (leader only)
List your groups: /group list
Group info: /group info <name>
Build / break / interact bonus: group members can build, break, and interact (chests / doors / buttons / beds) inside each other's build-protected homes. Toggle off via groups.share-build: false in config.yml — that makes groups social-only (chat tag + member roster, no shared building). Roles within a group: leader / officer / member. Officers can invite + kick on the leader's behalf; the leader can transfer leadership before leaving.
How do I see who's in a group? (admin)
Two ways. In-game: /group info <name> shows the leader + officers + members + creation date. Dashboard (admin): 👥 Players → 🤝 Groups sub-tab. Lists every group with leader / member-count / motto / colour / formation date. Click a row to expand: full member list with promote / demote / kick / transfer-leader buttons, plus per-group audit trail (joins / leaves / promotions for the last 30 days). Admin actions: rename, change colour, force-disband (logs to audit). Permission keys (gateable per role): groups.view (default-on for everyone), groups.admin-create, groups.admin-edit, groups.admin-kick, groups.admin-promote, groups.admin-disband-any.
How do I promote a user to admin? (and what's in the 👑 Owner tab?)
The 👑 Owner tab is gold-bordered and only visible if your role is OWNER. It hosts every privileged management tool:
👥 Users — table of every dashboard admin (username / role / status / last-login / linked-MC-account). Click "+ Add user", pick a role (Admin / Moderator / Viewer / any custom role), set a starter password. Click any row to edit role, reset password (sends a one-time link valid 24h), toggle active, link/unlink an MC UUID. Cannot delete the OWNER row; cannot demote yourself if you're the only OWNER.
🎭 Roles — built-in templates (OWNER / Admin / Moderator / Viewer) + custom roles. Click a role → permission matrix scoped to that role. Inheritance: new custom role can inherit from any built-in.
🔐 Permissions — full grid of every permission key × every role. Owner-only keys (🔒) lock to the OWNER row.
📜 Audit Log — every privileged action with filter + export-CSV.
👤 Your Account — change password, set up TOTP 2FA + recovery codes, transfer ownership, configure your own notification channels (My Notifications).
Quick promote workflow: 👑 Owner → 👥 Users → click the user → role picker → "Admin" → save. They get full access except owner-only actions (managing other users, transferring ownership, exporting audit). All API endpoints enforce permissions server-side.
How do I configure my own notification channels (per-admin)?
Each admin can route notifications to their own WhatsApp / Discord webhook / email — independent of the global server config. Global config is the fallback for every event; per-admin routes are additive on top.
Setup (yourself): 👑 Owner → 👤 Your Account → My Notifications card. Add a channel (WhatsApp number / Discord webhook URL / email address), pick which event categories you want (player joins, kicks, ban-issued, plugin error, anti-cheat critical, etc.), toggle enabled. Real-time test button on each channel.
Setup (for another admin): 👑 Owner → 👥 Users → click user → "Notifications: ⚙" link → toggle "Allow custom notifications". When the toggle is off, that admin's prefs are bypassed and only global config fires.
Permissions: notifications.self.manage (default-grant to OWNER + Admin), notifications.others.manage (owner-only).
Why per-admin: different admins want different events. Mods don't need plugin-error pages; the head admin doesn't need every player join. Now everyone tunes their own.
How do I send an announcement to all players?
Dashboard → ⚡ Quick Admin tab → 📢 Announcement card. Type up to 200 chars, click Announce Now. Players on every linked node see a red 🔊 ANNOUNCEMENT banner + the same message in chat + a bell sound. Useful for downtime warnings, event start, "report bugs in #feedback". Cross-node delivery uses the peer relay — SA players hear an EU admin's announcement within ~1s.
Note: this is plain-text broadcast. For actual voice broadcast (your microphone → every player's speakers), use 🎤 Voice → 🎤 Live → "Broadcast to all" or "Talk to player(s)".
How do I change the world seed?
🌍 World tab → 🌱 Seed sub-tab (owner-only, gated by world.change-seed permission). Type the new seed, type your server's name to confirm (typo-protection), and click apply.
⚠ Destructive — read this first. Changing the seed renames the active world folder so the next boot generates fresh chunks against the new seed. The old world is preserved on disk under a timestamped name (recoverable by editing level-name back if you need to roll forward) but the live game starts fresh. Players' inventories and homes survive on rejoin if they were stored server-side; everything in-world (built bases, farms, chests of items) lives only in the old folder.
The flow: auto-backup runs first (visible in 💾 Backups → "Pre-seed-change snapshot"), then the server schedules a graceful restart with a 60s countdown overlay (kicks players with the configured message), boots into the new seed, audit log records the change with the OWNER who triggered it. Recovery: SSH in, edit server.properties level-name=<old-name>, restart.
Dashboard Tabs Explained
The dashboard has 12 main tabs (13 if you're an Owner) along the top. Each main tab opens a sub-bar of pills underneath. Use Ctrl+K (or 🔍 Search top-right) to jump anywhere instantly — it indexes tabs, players, groups, kits, zones, roles, chapters, settings, and quick actions.
🏠 Dashboard · 📊 Overview (TPS / RAM / players / events) · 📈 Analytics (uniques, playtime, retention, heatmaps, deep metrics) · ⚡ Quick Admin (📢 Announcement, Graceful Restart, Heal/Feed/Teleport, etc.) · 📜 Server Events
👥 Players · 🟢 Online · 🎭 Roles · 🤝 Groups (clans / families) · 🚨 Reports & Bans · 📋 Audit Log
🎤 Voice · 🎤 Live (talk-to-player, broadcast-to-all, listen feed) · 🏛 War Room (admin-to-admin voice + text, optional player pull-in) · ⚙ Settings (echo-guard, voice quotas, voice-bonus rewards, mobile tokens)
🌍 World · ⚙ Server (server.properties + RAM/restart) · 🏷 Identity (server name / icon / MOTD) · 🗺 Zones · 🌀 Warps · 🏠 Homes · 📖 Welcome Book (chapter editor for new-player guide) · 🌱 Seed (owner-only world-seed change tool)
💰 Economy · 📊 Overview · 📜 Activity · 🛒 Shops · 🎁 Kits · 🐲 Mob Rewards · ⚙ Config · 🏆 Leaderboards
🌐 NovaLink · Public server directory listing (link.nova-ai.online) — opt-in, free
🛡 Anti-Cheat · 📋 Live Flags · 📊 Offenders · ⚙ Config · 📈 Stats · 🔧 Tools · 🛡 Moderation · 🕵 CoreProtect (block forensics + rollback)
🔔 Notifications · WhatsApp / Discord / Email channel config + Events matrix + Audit log
⚙ Settings · 🔗 Sync (cross-server) · 🧩 Features · 💻 Console · ⏰ Scheduler · 💾 Backups · 🔐 Security (login, 2FA, recovery email) · 🔌 Integrations · 🤖 Nova · 🔧 Advanced · 📈 Analytics
🐛 Bug Report · Submit issue + diagnostics straight to the maintainer
❓ FAQ · This page
👑 Owner (gold border, owner-only) · 👥 Users · 🎭 Roles (custom + built-in) · 🔐 Permissions (full grid) · 📁 Files (file manager) · 📜 Audit Log · 🚀 Updates (Stable / Fast channel + promote) · 👤 Your Account (password, 2FA, transfer ownership, my notifications)
Role System
Baby (weight 5) — Full protection from everything. PVP off, mob-safe, env-safe, explosion-safe, magic-safe, build-protected. Can still attack mobs. For brand-new players who need total safety.
Noob (weight 10, DEFAULT) — PVP protection + build protection. Takes normal mob/fire/fall damage. Default role assigned to all new players.
Builder (weight 30) — Creative mode + flight. Invincible (creative). PVP off, build-protected. Can't drop items, can't use dangerous commands, can't spawn restricted items.
Player (weight 50) — Normal survival. PVP on, no protections. The real Minecraft experience.
Admin (weight 100) — Full access. Creative + fly. Can break protected blocks. All commands.
Weight = priority. Higher weight = more important. If a player has multiple roles, highest weight wins. Weight 100+ bypasses build protection.
Custom roles — Create any role with any combination of protections from the Roles tab.
Protection Toggles Explained
PVP Enabled — ON: can hit and be hit by players. OFF: no player damage in either direction.
Build Protected — Other players cannot break blocks placed by this role (uses CoreProtect to check who placed the block). Admins bypass this.
Mob Protected — Immune to mob attacks (zombie, skeleton, creeper melee, etc). Can still attack and kill mobs.
Environment Protected — Immune to: fall, fire, lava, drowning, suffocation, void, cactus, magma, campfire, freezing, starvation, lightning, falling blocks, world border.
Explosion Protected — Immune to TNT, creeper, ghast, bed, respawn anchor explosions.
Magic Protected — Immune to damage potions, poison, wither effect, dragon breath, thorns.
Creative Mode — GameMode.CREATIVE (invincible, unlimited blocks, instant break). Restricted: can't drop items, can't use /give /op /gamemode, can't spawn eggs/command blocks.
Can Fly — Flight enabled. Works in survival mode without creative.
Chat Moderation
120+ regex patterns across 7 categories. English + Afrikaans.
PREDATORY — Grooming, asking for personal info, age probing, "send me a pic", social media fishing, isolation tactics, meeting up requests. Instant mute.
SEXUAL — Explicit content, body parts, sexual acts, profanity, nudes requests. Instant mute.
RACIST — Racial slurs (English + Afrikaans), hate speech, supremacist language. Instant mute.
SCAM — Phishing links, "free nitro/robux", credential stealing, fake giveaways, payment scams. Instant mute.
BOT — 5+ messages in 10 seconds = bot-like rate. Instant mute.
SPAM — 2+ identical messages in a row. Instant mute.
TOXIC — Death threats, KYS, doxxing, IP threats, severe harassment. Warning first, mute on 3rd offense.
Anti-evasion: leet speak normalization, spaced letters, Cyrillic lookalikes, dots/asterisks between letters, "ph" substitution.
Flagged players show in red on the Overview tab. Click to see their messages. "Mark Reviewed & Unmute" clears flags.
Backup System (GFS)
Grandfather-Father-Son rotation. Backups are automatically tagged:
Daily — most backups. Oldest deleted first when limit reached.
Weekly — every Sunday's backup is promoted to weekly tier.
Monthly — 1st of the month is promoted to monthly tier.
Snapshot — manual backups. Never auto-deleted.
Three purge limits run simultaneously: keep N per tier, delete older than X days, max total storage size. Pre-backup runs save-all. Activity-gated option skips backup if server is empty. Configurable compression level (1-9) and directory exclusions.
Player Actions
Every action has an undo:
Kick — player can rejoin
Ban / Unban
Mute / Unmute
Freeze / Unfreeze — adds slowness + mining fatigue + blindness
Whitelist / Unwhitelist
OP / Deop
Rollback Blocks / Restore Blocks — CoreProtect 30-day rollback/restore
Reset Player / Unreset Player — full wipe (inventory, XP, role, blocks) with snapshot. Unreset restores everything from the snapshot.
Bedrock Support
Requires Geyser-Spigot + Floodgate plugins. Bedrock players connect on port 19132 (or your configured Bedrock port — playit/cloudflared/SRV record setups can use a non-default port; configure Bedrock connect-address separately under Identity tab). Their names start with "." (Floodgate prefix). NovaSyncPlugin handles this automatically:
Anti-Cheat: Bedrock players are exempt by default (Geyser movement reports are unreliable on the Java protocol).
Voice: Bedrock connects via the same browser /voice URL as Java — paste the PIN into the web client. Echo cancellation is browser-side via echoCancellation:true; admin echo guard is configurable per-server.
Skins: Real Bedrock skins are fetched via Geyser Global API (api.geysermc.org/v2/skin/<xuid>) and injected into admin-GUI player heads. Falls back to distinguishing material (zombie / skeleton / creeper / piglin / dragon / wither head, hashed by UUID) if API unavailable. Display name always renders aqua so admins can spot Bedrock at a glance.
Nametags: Floodgate-prefixed players auto-assigned to a team with nametagVisibility: ALWAYS so floating nametags render correctly to Java viewers (fixed in 2.16.222).
Voice perms: Default group must have voicechat.listen + voicechat.speak. NovaSync auto-runs a self-healing migration via LuckPerms on first boot — preserves admin's deliberate denials.
Config needed once: enforce-secure-profile: false (server.properties), perform-username-validation: false, allow-invalid-usernames: true (LuckPerms). The first-run wizard handles these for you.
How do I set my home?
Place a sign anywhere you want to mark as home. On any line, write [home] (or "set home" / "nova home") and optionally add a name on line 2 like "Mining Base". You can also use /sethome [name] without a sign. Then open the player menu (default key M or /menu), click the Home icon, and pick your home to teleport. Default cooldown is 30 seconds. Use /homes to list your homes and /delhome [name] to remove one. Admins can configure max-homes per player, cooldown, and zone restrictions in the dashboard Homes tab.
🛈 Privacy & data retention
NovaSyncPlugin records minimal player data: UUID, username history, hashed IP, session timestamps, ban/kick history, anti-cheat flag counts. Collected to enable the cross-server features (whitelist/ban relay, anti-cheat, appeals, multi-network player profiles). Retention: 10 years from last activity; older records are purged automatically. Raw IP addresses are never stored — only SHA-256 hashes.
Players can request data removal via novasyncplugin.com/appeal/ — appeals are reviewed by the plugin maintainer and processed manually. Server admins cannot delete other admins' player records.
Optional Integrations
CoreProtect — enables block history lookup, rollback/restore, and build protection (who placed the block). Highly recommended.
LuckPerms — NovaSyncPlugin auto-creates matching LP groups (nova_rolename) and syncs player membership. Optional.
Geyser + Floodgate — Bedrock player support. Optional.
Simple Voice Chat — Proximity voice chat. Independent, no NovaSyncPlugin integration needed.
Global Reputation System
Cross-server player reputation tracking. When a player is banned or muted for a severe offense (PREDATORY, SEXUAL, RACIST, SCAM, or anti-cheat ban), the offense is reported to the central Nova AI API and stored locally.
When a player joins ANY NovaSyncPlugin server, their reputation is checked. Admins see a notification with offense count + severity. Full evidence (chat logs, anti-cheat data) is visible only to the server admin in the player's profile.
Public view: Offense category + severity only (e.g., "CHAT_PREDATORY / CRITICAL")
Admin view: Full evidence, reason, reporting server, timestamp, pardon button
Pardoning: Admins can pardon individual offenses or all offenses for a player from their profile
Appeal: Kicked/banned players receive a disconnect message with your configured appeal URL + Discord link (set appeals.url and appeals.discord in config.yml, or leave blank for a neutral "Contact your server admin" message)
Severity levels: CRITICAL (predatory/grooming), HIGH (sexual/racist/scam/cheating), MEDIUM (toxic), LOW (spam)
Licensing & Trial
Free 6-month trial: Every new NovaSyncPlugin install gets 6 months of all features unlocked automatically. No key needed. Every dashboard tab, anti-cheat, chat moderation, role system, backups, reputation, analytics — everything works from day one.
After trial: Contact your plugin distributor for a license key. Tiers: 1 month, 6 months, 1 year, or forever.
Activate: Settings tab → paste key → click Activate. Shows tier, expiry, and time remaining.
Without license: NovaSyncPlugin still works — basic dashboard, Nova sync, and player tracking remain free forever. Premium features (advanced anti-cheat, chat moderation, GFS backups, reputation system, roles, analytics) require an active license.
Telemetry
NovaSyncPlugin sends anonymous usage stats to the Nova AI central server every 30 minutes. This helps us track how many servers are running NovaSyncPlugin, how many players are using it, and identify issues.
What is sent: Server ID (random UUID), plugin version, MC version, player count (Java/Bedrock split), TPS, Nova count, role count, license status, OS, Java version, CPU cores, RAM. NO player names, NO IPs, NO chat logs, NO personal data.
Disable: Add telemetry.enabled: false to plugins/NovaSyncPlugin/config.yml and restart.
Where data goes: Nova AI admin dashboard (private, only visible to the Nova AI team). Used for install stats, usage analytics, and improving the plugin.
Technical Info
Database: SQLite (auto-created at plugins/NovaSyncPlugin/novasync.db). WAL mode. All queries use PreparedStatements.
HTTP Server: Java built-in HttpServer on port 8585 (configurable). 16-thread pool. Session auth via HttpOnly cookies.
Security: Rate-limited login (5 attempts/min), CSRF protection on actions, SQL injection safe, XSS protected, command blacklist.
Thread Safety: ConcurrentHashMap caches, volatile snapshots updated on main thread, synchronized DB access.
Nova Sync: NMS fake player packets (Paper 1.21.11). ArmorStand fallback. Proximity-based spawn/despawn. Custom skin support.
Support & Contact
Support contact: Set appeals.url + appeals.discord in config.yml so kicked / banned players see your support channel.
Bug Reports: Reproduce + capture logs/latest.log + screenshots, then submit via the 🐛 Bug Report tab — sends straight to the Nova team with diagnostics attached.
Ban Appeals: Configure via appeals.url / appeals.discord in config.yml. Defaults to a neutral "contact your server admin" message.