MCLocalAuth

MCLocalAuth v1.4.1 — Velocity

Type: First Velocity Release - Metrics, Update Checker, MySQL Storage Date: July 3, 2026 Status: ALPHA File: MCLocalAuth-Velocity-v1.4.1.jar ---

New Features

Velocity Support

MCLocalAuth is now available on Velocity! Full standalone module. - All features included (Discord bot, slash commands, IP authentication) - Independent SnakeYAML configuration - Compiled with Java 17 for Velocity 3.3.0+ compatibility

bStats Metrics

[bStats](https://bstats.org/) integration to track how many servers use the plugin. - Anonymous and opt-out data collection - View statistics: [bstats.org](https://bstats.org/)

Update Checker

The plugin automatically checks at startup if a newer version is available on Modrinth. - Async check (no startup impact) - Smart version comparison (only notifies if the Modrinth version is higher) - Console message with download link

MySQL Storage (optional)

Option to store player data (IPs, names, logins) in a MySQL database instead of data.yml. Configuration:

storage:
  type: "yaml"       # yaml or mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "mclocalauth"
    username: "root"
    password: ""

Auto-created tables: - mclocalauth_players — UUID, name, last IP, last login - mclocalauth_ips — UUID + authorized IPs (unique key) Benefits: - Ideal for multi-server Velocity networks - Shared data across all servers connected to the same database - Automatic fallback to YAML if database is not configured

Geyser/Bedrock Support

- Automatic Bedrock player detection (name prefix + Floodgate UUID) - Adapted kick message without color codes for Bedrock clients - Configurable via geyser.enabled and geyser.prefix

Configurable Discord Link

- discord.invite_link field in config.yml - %discord_link% placeholder in kick messages ---

Compatibility

| Platform | Versions | |----------|----------| | Velocity | 3.3.0+ | Java: 17+ ---

Installation

1. Download MCLocalAuth-Velocity-v1.4.1.jar 2. Place in plugins/ 3. Configure the Discord bot in plugins/mclocalauth/config.yml 4. Restart the proxy ---

Known Issues

No known bugs at this time. --- Build: Maven 3.9.5 + Java 17 Status: ALPHA

MCLocalAuth v1.4.0

Type: Major Update - BungeeCord Discord Bot + Discord Admin Commands Date: May 13, 2026 Status: STABLE ---

Major New Features

Discord Bot on BungeeCord

The Discord bot is now fully functional on BungeeCord. - Complete Discord module added for the proxy - Clean startup and shutdown with the BungeeCord plugin - Automatic bot status verification after connection - Displays bot name, ping, Discord server name, and member count Example startup logs:

§1[§6MCLocalAuth§1]§r §a§l[OK] §aDiscord bot connected: MyBot#1234
§1[§6MCLocalAuth§1]§r §7Ping: §f42ms
§1[§6MCLocalAuth§1]§r §7Discord server: §fMy Server
§1[§6MCLocalAuth§1]§r §7Members: §f150

New Discord /mcadmin Command

You can now manage player authorized IPs directly from Discord. | Subcommand | Description | |----------|-------------| | /mcadmin showips <player> | Show authorized IPs | | /mcadmin addip <player> <ip> | Add an IP | | /mcadmin removeip <player> <ip> | Remove an IP | | /mcadmin resetip <player> | Reset all IPs | | /mcadmin setip <player> <ip> | Set the primary IP | Security: - Restricted to the Discord ID set in admin.discord_id - Unauthorized users receive an access denied message

Discord Commands Available in DMs

Slash commands are now registered globally. This means you can use them: - On your Discord server - In direct messages with the bot

Colored Console Output on Paper and BungeeCord

All important messages now use a colored prefix on both platforms:

§1[§6MCLocalAuth§1]§r

- Brackets in dark blue - MCLocalAuth in orange - Works on Paper/Spigot and BungeeCord consoles

/auth Command on BungeeCord

The BungeeCord proxy now has its own /auth admin command. Available subcommands: - /auth showips <player> - /auth addip <player> <ip> - /auth removeip <player> <ip> - /auth resetip <player> - /auth setip <player> <ip> This allows managing authorized IPs from the proxy, across your entire network. ---

Important Fixes

IP Commands Fixed

`/auth setip <player> <ip>` - Before: Added the IP instead of replacing the primary one - After: Properly sets the primary IP and removes others `/auth resetip <player>` - Before: Deleted ALL player data - After: Only clears the authorized IP list

Guild ID Validation

The Discord bot now checks if guild_id is a valid numeric Discord snowflake. - No more crash if guild_id contains an invalid value - The plugin shows a clear error message instead of failing silently

Improved Player Lookup

Discord admin commands can now find a player: - by name - by full UUID Player names are also saved with authentication entries for better lookups. ---

Compatibility

Supported Versions

| Platform | Versions | |----------|----------| | Paper | 1.8.9 → 26.1.1 | | Spigot | 1.8.9 → 1.21.x | | Purpur | 1.8.9 → 1.21.x | | BungeeCord | Build 2068 | Java: 8+ The plugin is compiled with Java 8 for maximum compatibility. ---

Migration from v1.3.x

1. Stop the server / proxy 2. Replace old JARs with the v1.4.0 versions 3. Configure discord.bot_token if needed 4. Add your admin Discord ID:

admin:
  discord_id: "YOUR_DISCORD_ID"

5. Restart Configuration compatible Player data preserved Existing Discord commands still work ---

Technical Details

New Files

- BungeeDiscordBot.java - BungeeDiscordCommandListener.java

Modified Files

- MCLocalAuthBungee.java - DiscordBot.java - DiscordCommandListener.java - Storage.java - BungeeStorage.java - BungeePendingManager.java - BungeeLoginListener.java - AuthAdminCommand.java

Technical Improvements

- Added verifyBotStatus() to check actual bot state - Added isOnline() to test if the bot is connected - Added player lookup by name/UUID - Global Discord command registration - Improved console messages and error handling ---

Discord Commands

| Command | Description | Access | |---------|-------------|--------| | /mclogin <code> | Authenticate with code | Everyone | | /mctest | Test bot/plugin connection | Everyone | | /status | Check your status | Everyone | | /unlink <discord_id> | Unlink an account | Admin | | /mcadmin showips <player> | View authorized IPs | Admin | | /mcadmin addip <player> <ip> | Add an IP | Admin | | /mcadmin removeip <player> <ip> | Remove an IP | Admin | | /mcadmin resetip <player> | Reset IPs | Admin | | /mcadmin setip <player> <ip> | Set primary IP | Admin | ---

Minecraft Admin Commands

| Command | Spigot/Paper | BungeeCord | |---------|--------------|------------| | /auth showips <player> | | | | /auth addip <player> <ip> | | | | /auth removeip <player> <ip> | | | | /auth resetip <player> | fixed | | | /auth setip <player> <ip> | fixed | | ---

Installation

Spigot / Paper 1. Download MCLocalAuth-Spigot-v1.4.0.jar 2. Place in plugins/ 3. Configure the Discord bot 4. Restart the server BungeeCord 1. Download MCLocalAuth-Bungee-v1.4.0.jar 2. Place in plugins/ 3. Configure the Discord bot 4. Restart the proxy ---

Known Issues

No known bugs at this time. If you encounter a problem, check: - Plugin version - Discord token - guild_id - admin.discord_id value --- Build: Maven 3.9.9 + Java 8 Status: STABLE Compatibility: Minecraft 1.8.9 → 26.1.1 (Paper & BungeeCord 2068)

MCLocalAuth v1.3.1 - Changelog

Type: Compatibility Update Date: January 2, 2026 Status: STABLE ---

New Features

Extended Compatibility: 1.8.9 → 1.21.11

The plugin now officially supports all Minecraft versions from 1.8.9 to 1.21.11! Main improvements: - Added VersionUtil utility class to automatically detect server version - Intelligent Minecraft version detection at startup - Enhanced log messages with detected version At plugin startup, you'll now see:

[MCLocalAuth] ================================
[MCLocalAuth] MCLocalAuth v1.3.1 - Starting...
[MCLocalAuth] Detected Minecraft version: v1_20_R3
[MCLocalAuth] Compatibility: 1.8.9 - 1.21.11
[MCLocalAuth] ================================

---

Bug Fixes

PlayerMoveEvent Fix (Multi-version compatibility)

Problem solved: NPE (NullPointerException) on some versions when blocking movement Before:

if (e.getFrom().getX() != e.getTo().getX() || ...)
    e.setTo(e.getFrom());

Crashes if getTo() returns null on certain versions After:

Location to = e.getTo();
Location from = e.getFrom();

if (to != null && (from.getX() != to.getX() || ...))
    e.setTo(from);

Null check added to ensure compatibility Impact: Unauthenticated players won't be able to move, without crash risk on any version ---

Compatibility

Tested and Supported Versions

| Minecraft Version | Status | |-------------------|--------| | 1.8.9 - 1.12.2 | Compatible | | 1.13 - 1.16.5 | Compatible | | 1.17 - 1.19.4 | Compatible | | 1.20 - 1.21.11 | Compatible | Supported Servers: Spigot, Paper, Purpur, Pufferfish Latest tested version: 1.21.11 Note: The plugin automatically detects your Minecraft version at startup ---

Technical Changes

Modified Files

Java: - MCLocalAuthPlugin.java - Enhanced startup logs with version detection - RestrictListener.java - NPE fix on PlayerMoveEvent with null check - VersionUtil.java - NEW - Version detection utility class Configuration: - plugin.yml - Version 1.3.1 + Updated description - pom.xml - Version 1.3.1 + Updated description Documentation: - README.md - Updated badges and compatibility range - CHANGELOG.md - Complete documentation of changes ---

Migration from v1.3.0

Simple and risk-free! 1. Stop the server 2. Replace the JAR with MCLocalAuth-Spigot-v1.3.1.jar 3. Restart the server No configuration changes required! Existing configuration remains 100% compatible Player data is preserved No action required on Discord side ---

Why Update?

If you're using an old version (1.8.9 - 1.12.2)

Recommended - Important compatibility fix to avoid crashes

If you're using a recent version (1.20+)

Recommended - Better version detection and clearer logs

If you're on v1.3.0

Optional but recommended - Improves stability on all versions ---

Core Features (Unchanged)

All v1.3.0 features are preserved: - Integrated Discord bot - Authentication via /mclogin <code> - IP protection per account - Discord commands: /mclogin, /mctest, /status, /unlink (admin) - Admin commands: authorized IP management - Restrictions for unauthenticated players - IPv4 & IPv6 support ---

VersionUtil Class Details

The new utility class provides:

VersionUtil.getVersion()      // Ex: "v1_20_R3"
VersionUtil.getMajorVersion() // Ex: 1
VersionUtil.getMinorVersion() // Ex: 20
VersionUtil.isVersion(1, 13)  // true if >= 1.13
VersionUtil.is1_8()           // true if 1.8.x
VersionUtil.is1_13Plus()      // true if >= 1.13
VersionUtil.is1_20Plus()      // true if >= 1.20
VersionUtil.is1_21Plus()      // true if >= 1.21

Purpose: Allows future code adaptations based on server version ---

Known Issues

No known bugs at this time. If you encounter a problem: 1. Verify you're using v1.3.1 2. Check server logs (Minecraft version detected is displayed at startup) 3. Open an issue on GitHub with: - Plugin version - Minecraft version detected in logs - Problem description ---

Discord Commands (Unchanged)

| Command | Description | Access | |---------|-------------|--------| | /mclogin <code> | Authenticate with code | Everyone | | /mctest | Test bot/plugin connection | Everyone | | /status | Check your status | Everyone | | /unlink <discord_id> | Unlink account | Admin only | ---

Installation

1. Download MCLocalAuth-Spigot-v1.3.1.jar 2. Place in plugins/ folder 3. Restart server 4. Check logs: detected Minecraft version should be displayed 5. Test functionality with /mctest on Discord --- File: MCLocalAuth-Spigot-v1.3.1.jar Size: 11.20 MB Build: Maven 3.9.9 + Java 8 Status: STABLE Compatibility: Minecraft 1.8.9 → 1.21.11

MCLocalAuth v1.3.0 - Changelog

Type: Major Update Date: October 22, 2025 Status: STABLE ---

New Features

1. Discord Command Renamed

- BEFORE: /auth <code> - NOW: /mclogin <code> - All messages and references updated throughout the plugin

2. /unlink Command (Admin Only)

- Usage: /unlink <discord_id> - Reserved for admin configured in config.yml (admin.discord_id) - All attempts are logged for security auditing - Note: Basic feature implemented, persistent linking system coming soon ---

Bug Fixes

1. UTF-8 Encoding Fixed (In-Game)

Problem solved: In-game messages displayed garbled characters Fixed messages: - "reset" instead of "réinitialisé" - "added" instead of "ajouté" - "removed" instead of "supprimé" - "set" instead of "défini" - "authorized" instead of "autorisées" Result: Clean, readable messages on all systems

2. IPv6 Support

- IPv4 AND IPv6 both accepted for authorized IPs - Validation using InetAddress.getByName() - Affected commands: /auth addip, /auth setip

3. Current IP Displayed in Kick Messages

- Kick message now displays player's actual current IP - Variable %current_ip% is correctly replaced - Helps players identify their connection issues ---

Technical Changes

Modified files: - AuthAdminCommand.java: ASCII encoding + IPv6 validation - LoginListener.java: Current IP display + encoding fixes - DiscordBot.java: Renamed /auth → /mclogin - DiscordCommandListener.java: /mclogin + /unlink admin handler - config.yml: Messages without accents + /mclogin references - plugin.yml: Version 1.3.0 - pom.xml: Version 1.3.0 ---

Migration from v1.2.x

Steps: 1. Stop the server 2. Replace JAR with MCLocalAuth-Spigot-v1.3.0.jar 3. Configure admin in config.yml:

   admin:
     discord_id: "YOUR_DISCORD_ID"
     minecraft_uuid: ""
   

4. Restart the server 5. Inform players: command is now /mclogin <code> Note: Old configuration remains compatible ---

Changes for Players

On Discord:

- BEFORE: /auth 123456 - NOW: /mclogin 123456

In Minecraft:

- Connection message: "On Discord, type: /mclogin 870600" - (instead of "/auth PvP_UNGEUR 870600") ---

Security

Admin logging: - All admin actions are logged - Example: [ADMIN] PvP_UNGEUR#1234 attempted to unlink Discord ID: 987654321 - Useful for auditing sensitive actions ---

Compatibility

- Minecraft: 1.8 → 1.21+ - Java: 8+ - IPv4 & IPv6: Fully supported - Config: Compatible with v1.2.x (auto-adds admin section) ---

Known Issues

No known bugs at this time. If you encounter a problem: 1. Verify you're using v1.3.0 2. Check server logs 3. Open an issue on GitHub ---

Discord Commands (Updated)

| Command | Description | Access | |---------|-------------|--------| | /mclogin <code> | Authenticate with code | Everyone | | /mctest | Test bot/plugin connection | Everyone | | /status | Check your status | Everyone | | /unlink <discord_id> | Unlink account | Admin only | ---

Installation

1. Download MCLocalAuth-Spigot-v1.3.0.jar 2. Place in plugins/ folder 3. Restart server 4. Configure admin.discord_id in config.yml 5. Test with /mctest and /mclogin --- File: MCLocalAuth-Spigot-v1.3.0.jar Size: 10.68 MB Build: Maven 3.9.5 + Java 8 Status: STABLE

MCLocalAuth v1.2.3 - Changelog

Type: Critical Fixes Date: October 21, 2025 - 22:06 Status: STABLE ---

Bug Fixes

1. UTF-8 Encoding Fixed

Problem: Discord messages with garbled characters Example: â„¹ï¸ Délier le compte Solution: All messages without accents/special emojis - Discord titles: Simple ASCII text - Server logs: [OK], [ERROR], [WARN] - No more problematic emojis ( ) Result: Clean and readable messages everywhere ---

2. Administrator Configuration Added

New in `config.yml`:

admin:
  discord_id: "YOUR_DISCORD_ID"
  minecraft_uuid: ""

Allows storing admin identifiers for future features (reserved commands, etc.) ---

3. /status Command Updated

- Old text: /auth <username> <code> - New text: /auth <code> Consistent with v1.2.2 ---

Technical Details

Modified files: - config.yml - Added admin section (discord_id, minecraft_uuid) - DiscordBot.java - Logs without UTF-8 emojis - Messages: "Starting", "connected", etc. - DiscordCommandListener.java - All Discord messages in simple ASCII - Titles without emojis ( → text) - "been" instead of "été", etc. Reason: Java 8 + Windows Console = UTF-8 Issues Solution: ASCII only for maximum stability ---

Compatibility

- Minecraft: 1.8 → 1.21+ - Java: 8+ - Server: Spigot, Paper, Purpur - Config: Compatible v1.2.0-1.2.2 (auto-adds admin section) Migration from v1.2.2: - No action required - Admin section added automatically on first start ---

Usage

Admin Configuration (Optional)

1. Open plugins/MCLocalAuth/config.yml 2. Find the "admin" section 3. Fill in: - discord_id: Your Discord ID (right-click > Copy ID) - minecraft_uuid: (optional) Your Minecraft UUID To get your UUID: → https://mcuuid.net/?q=YOUR_USERNAME ---

Fixed Bugs

- Unreadable Discord messages (encoding) - Broken emojis in logs - Obsolete "/auth <username> <code>" text ---

Previous Versions

v1.2.2 (10/21/2025 19:53)

- Fixed code search (findByCode) - Code works even after kick

v1.2.1 (10/21/2025 19:53)

- Force delete old Discord commands - /auth without username parameter

v1.2.0 (10/21/2025 19:33)

- Added /mctest - Simplified /auth (code only) - Fixed "player not found"

v1.1.0 (10/21/2025 19:12)

- Fixed plugin.yml package - Initial functional build ---

Installation

1. Stop the server 2. Replace old JAR with MCLocalAuth-Spigot-v1.2.3.jar 3. (Optional) Configure admin.discord_id in config.yml 4. Restart the server 5. Test with /mctest on Discord ---

Next Version (v1.3.0)

Planned features: - Reserved admin commands (via discord_id) - Persistent Discord linking system - Functional /unlink - Authentication statistics - Multi-language support (FR/EN) --- File: MCLocalAuth-Spigot-v1.2.3.jar Size: 10.68 MB Build: Maven 3.9.5 + Java 8 (1.8.0_432) Status: STABLE

First version, several bugs may be present, they will be corrected in future updates.