GensCore

GensCore is a comprehensive, production-ready core plugin developed specifically for the Survival/Faction server GensBien. It bundles all essential server mechanics into a single, high-performance plugin, eliminating the complexity and overhead of managing dozens of fragmented plugins. Engineered natively for PaperMC and Folia (Minecraft 26.1+) running on Java 25 LTS!

Official Documentation Website: williambossard.github.io/GensCore
Full offline reference: Comprehensive Documentation (DOCUMENTATION.md).

Included Features (30 Modules)

GensCore is 100% modular with zero mandatory external dependencies:

• Dual-Engine Database Persistence: Runs out of the box on embedded SQLite (WAL mode) or connects to remote MySQL / MariaDB with HikariCP pooling, dynamic SQL dialect translation, and automatic safe fallback to SQLite if remote DB is unreachable.
• Economy, Dynamic Shop & Auction House: Centralized currency (/money, /pay, /baltop), dynamic mathematical supply/demand shop (/shop, 319 survival items), and player-to-player marketplace (/ah).
• Guilds & Claims (Teams): Complete clan system (/team) featuring shared treasury ($ or XP levels), territory chunk protection ($16 \times 16$), real-time 3D BlueMap markers with custom colors, 10 team upgrade trees, shared vaults (/team vault), and web roster administration.
• Jobs & Daily Quests: 6 professions (Miner, Lumberjack, Hunter, Farmer, Fisherman, Builder) with anti-farm block caching, paired with a daily rotating quest system (/quests).
• Solo Quest Perks & Masteries: Individual progression rewarding completed quests (/perks), unlocking abilities like instant /autosmelt, 5-block /magnet, and extra homes.
• Container Security & Grief Shield: Container locking (/lock, /lock guild), anti-hopper protection, and anti-piston push/retraction shields.
• Web Panel & Player Portal: Fully responsive React 18 / Vite web application served by embedded Javalin, featuring live server telemetry, console, player management, module toggles, and interactive web minigames (Wheel of Fortune, Casino Slots).
• Discord Integration: Two-way synchronization via JDA (Java Discord API) with account linking (!link), chat bridge, and staff action embeds.
• Cross-Play Bedrock Ready: Native Geyser & Floodgate integration with automatic Cumulus Forms menus, Bedrock prefixes, and high-res avatar rendering.
• Multi-Protocol Compatibility: Decoupled ViaVersion integration detecting client protocols (/check <player>), mapping materials for legacy versions, and providing PlaceholderAPI expansions.
• Death Graves (Tombs) & Instanced Lootr: Holographic player graves preserving inventory/XP and per-player instanced dungeon chests.
• System Telemetry & Administration: In-game health monitoring (/gens status, /gens db) and live hot-swappable module toggling (/module).
• Modern MiniMessage Formatting: Pure Kyori Adventure chat and tablist styling with zero legacy formatting codes.

Dependencies & Integrations

GensCore is designed to be fully autonomous. It can run standalone without requiring any mandatory external plugins, but seamlessly integrates with the standard server ecosystem:

Recommended Integrations (Soft Dependencies)

• Vault:
  • If Vault is installed: GensCore automatically registers its internal economy engine into Vault's Economy service provider (GensVaultEconomy). This enables any other 3rd-party plugins on your server (like chest shops, claim plugins, or auction addons) to seamlessly access and modify GensCore player balances.
  • If Vault is NOT installed: GensCore's economy continues to work 100% autonomously! All internal economy features (/money, /balance, /baltop, /pay, /eco, Dynamic Shop, and Auction House) persist to the local SQLite database without interruption.
• LuckPerms:
  • If LuckPerms is installed: GensCore integrates with the LuckPerms API to fetch player ranks, primary groups, weights, and prefixes for the custom Chat and Scoreboard/Nametags.
  • If LuckPerms is NOT installed: GensCore gracefully falls back to default Bukkit permission checks (e.g. genscore.admin) and standard display names.

Optional Integrations

• GeyserMC & Floodgate: Highly recommended if you allow Bedrock cross-play. GensCore automatically detects Floodgate to open native Bedrock Forms (Cumulus API), assign platform prefixes ([Bedrock]), resolve Bedrock UUIDs/skins, and optimize inventory interactions.
• ViaVersion & ViaBackwards: Multi-version interop bridge. Automatically detects client versions (e.g. 26.2, 1.21.x, 1.20.x), maps 26.3 menu materials, supplies %genscore_client_version% placeholders, and enables the /check <player> staff command.
• BlueMap: If installed, the web panel integrates a live map view for administrators.
• PlaceholderAPI: Integrated with the official GensCoreExpansion (%genscore_balance%, %genscore_client_version%, %genscore_guild%, etc.).

Compatibility: Paper & Folia Only

GensCore is STRICTLY compatible with PaperMC and Folia (Minecraft 26.1+, Java 25+). It will not start on a standard legacy Spigot server. The plugin relies on modern Paper APIs such as Kyori Adventure (MiniMessage) for text components, regional multi-threaded Folia schedulers (FoliaLib), and the Cloud Command Framework for Paper.

Configuration & Networks (Ports)

To avoid hardcoded secrets or addresses, GensCore relies on a modular configuration system located in plugins/GensCore/. The main config.yml handles core settings (database, language), while a modules/ folder contains specific files for each feature.

Web Panel

The Web administration panel runs locally on your Minecraft server, alongside the game, using Javalin. It has been built with Vite and React for a fully responsive mobile-friendly experience.

• The default port is 8080.
• It can be modified via the port: 8080 option in modules/web.yml.
• If your Minecraft server runs on a host (like Pterodactyl), you will need to open a second free port and specify it in the configuration for the Web Panel to be accessible.

Web Panel Security (Admin Password): By default, the password is set to "gens". Upon the first startup, GensCore will automatically hash this password in web.yml using BCrypt to secure it. If you forget your password, simply open modules/web.yml, replace the long hashed string with a new password in plain text, and restart the server. The plugin will automatically hash it again.

Discord Bot

The Discord module requires a bot Token. For security reasons, this Token must never be shared or hardcoded in the Java source code.

• Provide it via the bot_token: "YOUR_TOKEN" option in modules/discord.yml.
• The bot ensures clean server shutdowns without throwing zip file closed errors by disconnecting its WebSockets properly before the Minecraft server halts.

Database Engine

GensCore uses a dual-engine database layer managed by HikariCP:

• SQLite (Default): Zero setup required. All data is saved locally in plugins/GensCore/genscore.db.
• MySQL / MariaDB (Optional): Can be activated in config.yml (database.type: "mysql"). Ideal for external databases or containerized setups.
• Automatic Fallback: If the external database server is unreachable or offline, GensCore automatically falls back to local SQLite without interrupting server startup.

database:
  type: "sqlite" # "sqlite" or "mysql"
  sqlite:
    file: "genscore.db"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "genscore"
    username: "genscore_user"
    password: "change_me"

Internal Code Architecture

For developers wishing to modify or understand the plugin, here are the pillars of its internal architecture:

1. The ModuleManager: This is the core system. Instead of being a monolithic plugin, GensCore is divided into dozens of "Modules" (such as EconomyModule, TeamsModule, DiscordModule). They all inherit from the Module interface and can be dynamically enabled or disabled.
2. Database Engine (DatabaseManager.java): By default, GensCore uses a local SQLite database (genscore.db) with HikariCP connection pooling. An optional external MySQL/MariaDB database can be enabled with automatic schema migration, SQL dialect translation (adaptQuery), and resilient automatic fallback to SQLite upon connection failure.
3. REST Web API (WebManager.java & WebPlayerAPI.java): Javalin is used in the background to spin up an HTTP micro-server on port 8080. The React code in the /web-panel folder is built and placed into /src/main/resources/public/. Every time an admin visits the web page, Javalin serves these HTML/JS files and communicates with React via a JSON API.
4. Metrics & Health Service (MetricsService.java): Collects real-time JVM telemetry, Folia tick rate, database connection pool statistics, and active module status exposed via /api/metrics and in-game commands.
5. Command Engine & Cloud Patch (CommandManager.java): Powered by the Incendo Cloud Command Framework with asynchronous coordination and Brigadier suggestions. Includes an architecture patch (ItemStackParser.java) to ensure flawless item argument parsing on Paper 26.3 until Cloud 2.1+ is released.

Build & Installation

If you wish to compile GensCore, the ideal environment is Java 25, managed by Maven and Node.js/npm (for the web panel).

Manual Build (Local)

git clone https://github.com/WilliamBossard/GensCore.git
cd GensCore
# First, build the web panel
cd web-panel
npm install
npm run build
cd ..
# Then, package the Java plugin
mvn clean package -DskipTests

The final file will be located in target/GensCore-1.0.3.jar.

Build via GitHub Actions

GensCore has a configured Workflow (in .github/workflows/release.yml).

1. Go to your GitHub Repository, in the "Actions" tab.
2. Select "Build and Release GensCore" on the left.
3. Click on "Run workflow".
4. GitHub will compile the project (both the React panel and the Java plugin) on its servers (for free) in a few seconds, then create a Draft Release.
5. All you have to do is download the .jar file from the GitHub Release without needing to install Java, Maven, or Node.js on your computer!

Plugin developed with passion for GensBien.

Language Support

GensCore fully supports multiple languages. The active language is set in config.yml:

lang: fr_FR  # or en_US

Available language files are located in plugins/GensCore/lang/. Each file contains all player-facing messages that can be freely customized. Supported languages out of the box:

Automatic Update Checker

On startup and when a player with the genscore.admin permission (or operator status) joins the server, GensCore automatically checks for a new release on GitHub.

• If a new version is available, a notification is sent in chat (visible to admins/ops only) and logged to the server console.
• The check is non-blocking and runs asynchronously to avoid any impact on startup time.
• The installed version is compared against the latest GitHub Release tag (e.g. 1.0.0 vs 1.0.1).

Commands & Permissions

Authentication

Economy, Dynamic Shop & Auction House

Guilds & Clans (/team)

Jobs, Daily Quests & Solo Perks

Teleportation & Navigation

Container Security & Locks

Survival Utilities

Staff & Moderation

Discord & Web Casino Bridge

Administration & Diagnostics

Note: Players with operator status (/op) automatically inherit the genscore.admin permission.

For the complete list of all 30 modules, advanced subcommands, bypass permissions, and ready-to-use LuckPerms templates, see DOCUMENTATION.md and the Online Docs.

Lootr Integration

GensCore completely integrates a custom Lootr-like system (per-player loot chests) directly into the core, meaning you do not need to install any external mods or plugins. Chest data and per-player loot inventories are persisted in the configured database (SQLite or MySQL, in lootr_chests & lootr_player_chests tables). If a legacy chests.yml file is detected on startup, it will be migrated automatically and transparently.

You can configure its behaviour in the modules/lootr.yml file:

lootr:
  prevent-hopper: true
  prevent-break: false
  particles-enabled: true
  break-confirm-time: 3

Server Wipe

[!WARNING] This action is irreversible. A server wipe permanently deletes all player data from the database (homes, economy, stats, auth, quests, etc.). It does not delete world files.

The Web Admin Panel includes a "Wipe Server Data" button at the bottom of the Configuration page. To prevent accidents:

1. The button is prominently marked in red.
2. Clicking it requires entering the admin password to confirm.
3. The console will log a confirmation message when the wipe completes.

To perform a wipe from the console, the Web Panel must be running and accessible.