NircraftCORE

The main custom plugin behind my Nircraft Minecraft server, built to power RPG systems, server-side gameplay logic, and custom progression.

NircraftCORE is the main Paper plugin that powers the Nircraft network, and is the server's core gameplay layer. The codebase owns progression, menus, collections, land/team systems, travel, duels, supporter features, market trading, Discord/network glue, and most of the custom survival rules that define the server.

The current codebase is organized as a feature-oriented monolith: one deployable plugin, split internally into domain packages and bootstrap modules instead of flat service / listener / command buckets.

Overview

Artifact

• Maven coordinates: com.nickrodi:nircraftcore:2.1.0
• Main class: com.nickrodi.nircraft.NirPlugin
• API target: Paper 1.21.11-R0.1-SNAPSHOT
• Java target: 21

Hard / soft integrations

• Hard dependency: WorldEdit
• Optional integrations: LuckPerms, Multiverse-Core, Multiverse-Inventories, DiscordSRV, FancyHolograms, FancyNpcs, Votifier, FastAsyncWorldEdit

Primary goals

• Turn barebones Minecraft survival into a long-term progression game without replacing vanilla world interaction
• Provide first-party menus and UX for progression, stats, market, supporter perks, teleportation, and tutorials
• Keep network-specific logic in one place, including Discord bridge behavior, role formatting, and moderation helpers
• Persist player progression in plugin-owned storage rather than relying on third-party quest/progression plugins

Feature Set

Progression and XP economy

• Full account progression with a custom level curve, prestige hooks, and version-aware playtime tracking
• XP sources across mining, farming, breeding, taming, PvE, PvP, bosses, fishing, trades, advancements, build reviews, night events, structure rewards, collections, and more
• Daily cap systems for selected categories through ProgressionService
• Health and hunger scaling tied to progression through HealthService and HungerService
• In-game stat display routing so players can expose selected stats to other players

Menu, player UI, and collections

• /info with custom chest UI style menu for player overview, progression, collections, caps, and stats
• Collection tracking for enchants, biomes, fishing, discs, bestiary, and night events
• Collection reward scaling handled centrally by CollectionXpScale
• Text-heavy book/menu rendering through QuestBookService, StatsMenuService, CollectionsMenuService, PlayerMenuService, and XpCapsMenuService
• Leaderboards and top-player presentation through command and hologram services

World and travel systems

• Spawn, homes, warps, world-center routing, and teleport requests
• RTP routing that can target both the vanilla overworld and Dreamland
• World-aware gameplay gating through WorldAccess
• Safety checks for teleport cancellation, request acceptance warnings, and home limits

Territory and social grouping

• Team creation, invites, renames, privacy, team homes, and team chat
• Land claiming with claim validation, center protection, invitations, bans, and metadata
• Friendly-fire and shared team progression support
• Team ranking via /ttop

Player market and trade

• In-plugin market offers with GUI flow for listing items and specifying requested return items
• Support for both vanilla and plugin-defined custom items in market matching
• "My Offers" claim flow for sold listings and seller-side notifications when offers are purchased
• Separate synchronous player-to-player trade request flow via the trade package

Duel and competitive systems

• Duel requests, spectator flow, post-duel command restrictions, queue entry, dequeue, and duel kit selection
• Duel arenas and duel-specific startup/login guards
• Queue-based PvP flow implemented inside the plugin rather than delegated to an arena plugin

Custom survival gameplay layers

• Death chests with player-owned retrieval behavior
• Sleep vote system instead of forcing full-server sleep
• Bestiary and biome discovery tracking through movement and entity listeners
• Heavy Core, Sheer Forger, Star of Nir, trial chamber unlocks, Nether unlocks, and other custom survival unlock paths
• Dragon egg tracking, special activation flows, custom loot hooks, and structure reward pipelines
• Combat tagging, totem tracking, attack indicator, suspicious mining alerts, and other live gameplay instrumentation

Social, moderation, and network integration

• Chat formatting, nickname handling, role-aware tab ordering, and profile formatting
• Discord account sync, slash-link flow, chat relay, moderation relay, and system announcements via DiscordSRV
• Player suggestions, reports, warnings, audit log, punishment history, vanish-aware staff tooling, invsee, and staff watch/spectate helpers
• Owner / mod / supporter role presentation and permission-aware display services

Supporter systems

• Supporter / Elite / Ultra tier handling through SupporterRoleService
• Theme, tag, claim, ender chest, back, gift, and store entry flows
• Supporter reminder and promo messaging helpers
• Tier-aware UI/menu services for perk access

Onboarding and documentation UX

• Help menu, tutorial flow, and rules UI
• Join-time onboarding hooks
• NPC-driven dialogue systems for guided feature discovery

Architecture

The plugin is intentionally split by feature domain.

Storage model

• Player state is owned by PlayerData
• Persistence is YAML-backed through StorageService
• Per-player data is stored under the plugin data folder in players/
• The plugin persists progression, collection progress, supporter-related state, duel stats, playtime metrics, daily-cap tracking, and settings flags
• Migration hooks exist for legacy/renamed fields and world-config changes

World model

• Supports a split between vanilla overworld and Dreamland-style custom generation
• Uses server/world name configuration rather than hardcoding a single survival world
• Keeps gameplay gating centralized so listeners can opt into only the intended world set

Command Surface

The plugin registers a large command surface because it is effectively the server's primary gameplay framework.

Core player commands

• /questbook, /info, /stats, /player, /menu
• /leaderboard
• /xpcaps
• /market
• /settings
• /vote
• /kit

Travel

• /spawn, /spawnfast
• /rtp, /rtpfast
• /warp, /warpfast
• /sethome, /home, /homes, /delhome
• /tpa, /tpahere, /tpaccept, /tpdecline

Territory

• /team
• /tc
• /ttop
• /land

PvP / trade

• /duel
• /queue, /dequeue
• /spectate
• /trade

Supporter / social

• /supporter, /rank, /claim, /gift
• /nick, /theme, /tag, /realname
• /report, /reports, /suggest, /suggestions

Admin

• /nir
• /build
• /builder
• /warn, /unmute, /auditlog, /mmtext

Inside the internal repository, plugin.yml is the canonical command and permission definition file.

Build and Test

mvn test
mvn package

Runtime assumptions

• Java 21
• Paper 1.21.11
• A local nuvotifier.jar is expected at ../service/plugins/nuvotifier.jar during compilation because the Maven build references it as a system-scoped dependency

Current test coverage includes

• progression math and level curve behavior
• health and hunger systems
• market matching and service behavior
• territory helpers and world-specific land rules
• RTP command behavior
• bootstrap and world-access logic
• collection reward scaling

Repository Layout

nircraft/source
├── pom.xml
├── src/main/java/com/nickrodi/nircraft
│   ├── bootstrap
│   ├── core
│   ├── player
│   ├── travel
│   ├── territory
│   ├── duel
│   ├── gameplay
│   ├── market
│   ├── trade
│   ├── social
│   ├── supporter
│   ├── help
│   └── admin
└── src/main/resources/plugin.yml

Operational Notes

• This repository is the source tree for the live Nircraft plugin, not a generic library
• nircraft/service is the main server runtime tree (not included within this repository)
• smptest/service is the staging/test deployment target used for pre-production validation (not included within this repository)
• The plugin contains Nircraft-specific assumptions about ranks, world names, Discord integration, and gameplay progression; should not be reused on another server