RunestoneMMO

📌 Compatibility

• Platform: Paper
• Minecraft: 1.21.11
• Java: 21
• Soft-Dependencies: Vault, Oraxen, Citizens
• Supported Hooks: LuckPerms, PlaceholderAPI

🚀 Quick Start

1. Drop RunestoneCore.jar into /plugins/
2. Start the server once to generate config and data folders
3. Edit files in plugins/RunestoneCore/
4. Restart the server ✅

Avoid /reload when possible. Prefer a full restart.

🧩 Included Systems

🏗️ Core Framework

• Deterministic bootstrap and shutdown flow
• Central subsystem lifecycle manager
• Central task registry and listener registry
• Modular architecture designed for future addons and internal expansion
• Public API layer for addons and integrations

💾 Data, Persistence & Backups

• Shared player data handling across core systems
• YAML and SQLite player-data backend support
• Runtime save/load flow for player and subsystem data
• Autosave support
• Backup support for YAML data and SQLite databases
• Structured runtime data folders for claims, graves, cooldowns, shops, auction data, treasury data, and more

📈 Performance & Stability

• Performance monitoring hooks
• Optional lag cleanup controls
• Spawn limiter system
• AFK detection/support systems
• Scoreboard timing/performance diagnostics
• Centralized task cleanup and subsystem shutdown behavior

💬 Chat & Communication

• Multi-channel chat system
• Global, local, party, and staff chat support
• Channel switching commands and aliases
• Broadcast/announcement command support
• Staff chat and moderation chat-control integration

📬 Mailbox System

• Full internal mailbox system built directly into RunestoneCore
• Inbox GUI and mailbox main menu
• Mail reading, deletion, and attachment claiming
• Claim-all support for attachments
• Player-to-player message mail
• Player-to-player currency mail
• Player-to-player item mail
• Admin/system mail support
• Admin message mail
• Admin currency mail
• Admin item mail
• Admin template mail
• Admin NPC test mail
• Typed-recipient compose support
• Unread login notifications
• Online recipient notifications
• Mail expiry support
• Inbox caps, cooldowns, subject/body limits, attachment rules, blocked-item handling, and currency restrictions
• Offline player mailbox delivery support for previously joined players

🔋 Resources

• Mana and Stamina
• Regen rules and delay-after-spend behavior
• Sprint/resource hooks
• Resource HUD support
• Teleport/resource integration

⚔️ Combat, Attributes & Progression

• Combat damage scaling
• Combat XP rewards
• Entity combat scaling hooks
• Attribute system
• Attribute persistence and cleanup controls
• Combat-level and progression-ready MMO foundation
• Shared XP API hooks for broader system integration

❤️ UI, HUD & Scoreboards

• Unified ActionBar/BossBar infrastructure
• Resource HUD system
• Mob health bars
• Multiple scoreboard layouts
• Scoreboard switching and auto-mode support
• Performance-aware scoreboard updating
• BossBarHub and channel-based UI handling

💰 Economy

• Multi-currency economy support
• Primary and secondary currency handling
• Balance, bank, treasury, exchange, taxes, and ledger/history systems
• Vault bridge support
• Transaction logging
• Dynamic pricing hooks
• Interest/task support
• Curated vendor sell support through /sell

🛒 Market Systems

• Auction House
• Player Shops
• Auction listing storage and expiration handling
• Player shop storage and GUI menus
• Market/dashboard command support
• Economy-integrated buy/sell foundations

🎁 Daily Rewards

• Daily reward system
• Reward claiming
• Status tracking
• Streak/cycle support
• Loot-table style MMO reward progression foundation

🧰 Items & Drops

• Config-driven item system
• Item definitions with rarity support
• Drop tables and drop manager system
• PDC-backed item metadata
• Oraxen bridge support
• Item use gating / requirement engine hooks
• Custom item command and drop command support

✨ Holograms

• Hologram subsystem
• Command support
• Leaderboard and information-display support
• Useful for spawn areas, shops, rankings, and server presentation

🌍 World Systems

• World rules manager
• Rule listeners and enforcement
• Sleep system / one-player-sleep support
• Dev/staff utility world support
• /devflat support
• Creative/staff-world access handling

🪦 Graves

• Grave system for death recovery
• Grave records stored in plugin data
• Grave markers with safe placement logic
• Owner/admin protection support
• Expiration and cleanup support
• Optional grave recovery command flow
• Claims-aware grave placement protection

🗺️ Claims & Territories

• Personal land claims
• Claim preview and selection tools
• Trusted-player access support
• Claim flags and protections
• Claim create/confirm/cancel/delete/info/list/trust/flag flows
• Claims API and claim events
• Territory config split into dedicated territory data
• Claims precedence/protection logic designed to work alongside wider territory systems

🏘️ Towns

• Town subsystem foundations
• Town membership/rank structures
• Town protection listeners
• Shared territory/towns config structure
• Built as part of the broader territory expansion path

🧑‍⚖️ Moderation

• Warn, mute, ban, temp punishment support
• Reports system
• Jail system
• Vanish and god mode
• Freeze / unfreeze
• Maintenance mode
• Staff alerts
• Audit trail / moderation event support
• Chat control hooks and enforcement tools

🧭 Teleportation

• Spawn system
• Back system
• Home system
• TPA / TPAHere / accept / deny / cancel / toggle
• Teleport cost/resource hooks
• Warmup/cancel-on-move foundations where applicable
• Staff utility teleport support

🧱 Menu Framework

• Shared menu / GUI framework
• Reusable menu components
• Layout/theme support
• Centralized menu behavior for expandable systems
• Used by mail, shops, auction, and other GUI-based systems

🤖 NPC / Citizens Integration

• RunestoneCore includes Citizens-facing /rnpc admin tooling
• Bind/unbind dialogue/quest/debug/open flows
• Root aliases for faster NPC admin handling
• Recent fixes tighten NPC behavior so normal Citizens NPCs are less likely to be affected unless intentionally bound
• /rnpc unbind clears stale Runestone-side Citizens metadata more safely

⌨️ Commands

RunestoneCore uses a Brigadier-based command backend and includes a wide range of command families.

Core command families include:

• /runestone
• /skills
• /channel
• /mail
• /claim
• /grave
• /town / /village
• /daily
• /balance, /bal, /baltop, /pay
• /eco, /bank, /exchange, /ledger
• /ah, /auction, /shop, /market
• /sell
• /mana, /stamina, /hudresources
• /spawn, /setspawn, /back
• /home, /sethome, /delhome
• /tpa, /tpahere, /tpaccept, /tpdeny, /tpacancel, /tptoggle
• /scoreboard
• /worldrule, /worldrulereload
• /broadcast
• /mod, /chatcontrol, /maintenance
• /freeze, /unfreeze, /jail, /invsee, /vanish, /god
• /playtime
• /holo
• /item, /drops
• /devflat
• /rnpc

Shortcut aliases include examples such as:

• /sm, /ss, /sc
• /gm
• /tpah, /tpacc, /tpac
• /bd, /bw
• /chg, /chl, /chp, /chs
• /dc, /ds
• /df
• /pt
• /rnb, /rnd, /rnq, /rndb, /rnm, /rno
• claim shortcuts such as /ccr, /ccf, /cc, /ci, /cl, /ct, /cf, /cd

Full usage, aliases, and permission trees should be documented on the separate Commands / Permissions pages.

🔌 Integrations

• Vault — economy provider bridge
• Oraxen — custom item bridge support
• Citizens — NPC admin/dialogue integration support
• LuckPerms — permission ecosystem support
• PlaceholderAPI — placeholder and UI formatting support

🧠 Configuration Philosophy

RunestoneCore is designed to be:

• config-first
• subsystem-based
• safe by default
• performance-conscious
• expandable for future modules

Runtime config/data structure includes files such as:

• config.yml
• economy.yml
• combat.yml
• attribute-config.yml
• cooldown-config.yml
• daily_rewards.yml
• items.yml
• messages.yml
• mob-health-config.yml
• moderation.yml
• playerdata.yml
• territories.yml
• worldrules.yml
• droptables.yml
• rarities.yml

📚 Documentation

Separate documentation pages are available for:

• Features / Commands
• Permissions
• Configuration
• Architecture
• API
• Claims
• Graves

🧯 Support & Reporting

Helpful info when reporting issues:

• server version (/version)
• RunestoneCore version
• relevant config section
• exact console stacktrace
• reproduction steps