SmoothLogin

SmoothLogin

Move login-time file work away from the server thread and keep player joins smooth.

SmoothLogin is a server-side Fabric performance mod that asynchronously prepares player data before a player enters the world. Player NBT, statistics and advancements are read and parsed on a configurable worker pool, reducing the amount of heavy file work performed on the server thread during login bursts.

It also includes an optional UUID migration toolkit for servers changing authentication modes. Automatic migration is disabled by default and can be enabled explicitly after reviewing the configuration and creating a backup.

Why SmoothLogin?

Player login touches several files. Reading player NBT and parsing statistics or advancements on the main thread can translate slow storage or many simultaneous joins into visible tick stalls. SmoothLogin prepares this data on dedicated workers and hands the prepared result back to the normal server login flow.

User-cache saves are also serialized through an asynchronous writer so concurrent logins cannot overwrite one another's updates.

Async login features

• Off-thread player-data preparation — reads player NBT without blocking the normal server tick loop.
• Pre-parsed statistics and advancements — file reads and JSON parsing happen before the main-thread consumer needs them.
• Configurable worker pool — choose between 1 and 32 login workers to suit the server's CPU and storage.
• Serialized user-cache writes — prevents concurrent login tasks from overwriting each other's usercache.json updates.
• Lifecycle-safe caching — prepared data is scoped to the owning login and cleared after use or disconnect.
• Server-side only — players do not need to install the mod.

Optional UUID migration

Authentication changes can assign a different UUID to the same player. SmoothLogin includes migration tools for moving UUID-linked data between offline mode, authenticated skin stations and Mojang authentication.

• Opt-in automatic migration — disabled by default; when enabled, it detects a previous UUID associated with the same player name and migrates only when policy and safety checks pass.
• Manual migration tools — inspect identity history, bind a known old UUID, start a migration, or undo the latest migration without enabling automatic migration.
• Broad data coverage — supports vanilla player data, statistics, advancements, operators, whitelist and bans, plus supported UUID-named paths and UUID references in world data.
• Transactional safety — checks source and target state, creates backups, records migration history, and attempts rollback if a migration fails.
• Conflict protection — never overwrites an existing target player automatically. Ambiguous cases are recorded for an administrator to review.
• Login guards — migration is refused while the source or target player is online or already logging in.

Supported environment

• Minecraft 26.1 or newer
• Fabric Loader 0.17.3 or newer
• Fabric API
• Dedicated server; no client installation required

Installation

1. Install Fabric Loader and Fabric API on the server.
2. Place SmoothLogin in the server's mods directory.
3. Start the server once to generate config/smoothlogin.json.
4. The asynchronous login pipeline works with the default configuration; no migration setup is required.
5. If UUID migration is needed, review its settings and make a complete world backup before enabling autoMigrate or running migration commands.

Commands

All commands require administrator permission.

Configuration

The configuration file is config/smoothlogin.json.

Important notes

• UUID migration is an optional feature and is not required for asynchronous login preparation.
• SmoothLogin cannot prove that two identities belong to the same person in every authentication setup. If enabling automatic migration, use strictMode, disable skinStationNamesUnique, or use manual binding when names are not a trustworthy identity anchor.
• Automatic migration requires usable identity history, normally from the server's user cache.
• Existing data at the target UUID is treated as a conflict and is not overwritten.
• Keep an independent full-server backup. SmoothLogin's transaction backups are designed for individual migrations, not as a replacement for normal backup policy.

Licensed under GPL-3.0-only.