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.

Command	Purpose
/smoothlogin info <name>	Show matching user-cache identities and the latest migration record.
/smoothlogin migrate <name>	Detect an old identity and start migration when safe.
/smoothlogin bind <name> <old-uuid>	Manually migrate a known old UUID to the player's currently resolved UUID.
/smoothlogin undo <name>	Restore the latest undoable migration using its exact backup.
/smoothlogin conflicts list	Display unresolved migration conflicts.
/smoothlogin conflicts resolve <name> <keep|old|new>	Record an administrator's decision without automatically deleting player files.
/smoothlogin automigrate	Display whether automatic migration is enabled.
/smoothlogin automigrate <on|off>	Enable or disable automatic migration and persist the setting.
/smoothlogin reload	Reload configuration and apply runtime settings.

Configuration

The configuration file is config/smoothlogin.json.

Option	Default	Description
autoMigrate	false	Opt in to automatic UUID migration during login. Asynchronous login preparation does not require this option.
notifyPlayerOnMigrate	true	Notify the player after a successful migration.
backupKeep	10	Number of migration backups to retain.
migratePlayerdata	true	Migrate inventory, location and other player NBT.
migrateStats	true	Migrate statistics.
migrateAdvancements	true	Migrate advancements.
migrateOpsWhitelistBans	true	Synchronize operator, whitelist and ban entries.
skinStationNamesUnique	true	Allow name-based automatic migration for the configured authentication environment. Disable it when names are not guaranteed to be unique.
strictMode	false	Reject weaker name-based evidence and require manual review.
usercacheMaxEntries	10000	Maximum retained user-cache entries.
loginThreadPoolSize	4	Worker threads used for login preparation; accepted range is 1–32.

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.