Home

SmoothLogin

SmoothLogin is a server-side Fabric mod that moves expensive player-login file work away from the Minecraft server thread. It prepares player NBT, statistics, and advancements on dedicated workers, then hands the prepared data back to the normal login flow.

Clients do not need to install the mod.

Features

• Asynchronously reads and prepares player NBT during login.
• Reads and parses statistics and advancements off the server thread.
• Serializes asynchronous usercache.json writes to avoid lost concurrent updates.
• Uses a configurable login worker pool with 1–32 threads.
• Replaces the login protocol's tick-only timeout with a combined threshold: a login is timed out only after both 30 seconds of real time and 300 server ticks have elapsed.
• Includes optional UUID migration tools for servers changing authentication modes.

Asynchronous login preparation and timeout mitigation are always enabled. Automatic UUID migration is independent of those features and is disabled by default.

Requirements

• Minecraft 26.1 or newer
• Fabric Loader 0.17.3 or newer
• Fabric API
• Java 25
• A dedicated server

The same JAR built against Minecraft 26.1.2 has also been tested successfully on Minecraft 26.2 with Fabric Loader 0.19.5 and Fabric API 0.160.0+26.2.

Installation

1. Install Fabric Loader and Fabric API on the server.
2. Place the SmoothLogin JAR in the server's mods directory.
3. Start the server once to generate config/smoothlogin.json.

No client-side installation is required. The asynchronous login pipeline works immediately with the default configuration.

Configuration

SmoothLogin creates config/smoothlogin.json.

Option	Default	Description
autoMigrate	false	Enables automatic UUID migration during login.
notifyPlayerOnMigrate	true	Notifies a player after a successful migration.
backupKeep	10	Number of migration backups to retain.
migratePlayerdata	true	Migrates player NBT data.
migrateStats	true	Migrates statistics.
migrateAdvancements	true	Migrates advancements.
migrateOpsWhitelistBans	true	Synchronizes operator, whitelist, and ban entries.
skinStationNamesUnique	true	Allows name-based migration when player names are a trustworthy identity anchor.
strictMode	false	Rejects weaker name-based evidence and requires manual review.
usercacheMaxEntries	10000	Maximum retained user-cache entries.
loginThreadPoolSize	4	Number of login preparation workers; accepted range is 1–32.

Use /smoothlogin reload after editing the configuration. Reloading and the associated file I/O run asynchronously, and runtime settings such as the worker-pool size are updated when the reload completes.

Commands

All commands require administrator permission.

Command	Purpose
/smoothlogin info <name>	Shows matching user-cache identities and the latest migration record.
/smoothlogin migrate <name>	Detects an old identity and starts migration when safe.
/smoothlogin bind <name> <old-uuid>	Migrates a known old UUID to the player's currently resolved UUID.
/smoothlogin undo <name>	Restores the latest undoable migration using its exact backup.
/smoothlogin conflicts list	Lists unresolved migration conflicts.
`/smoothlogin conflicts resolve <keep	old
/smoothlogin automigrate	Shows whether automatic migration is enabled.
`/smoothlogin automigrate <on	off>`
/smoothlogin reload	Reloads the configuration and applies runtime settings.

UUID migration safety

Automatic migration is an optional feature and remains off until explicitly enabled. Before changing a production server's authentication mode or migrating player identities, create a complete external backup.

SmoothLogin refuses unsafe migrations when the source or target player is online or already logging in, when target data already exists, or when configured identity checks do not provide sufficient confidence. It creates per-migration backups, records migration history, and supports undoing the latest eligible migration.

Building

Clone the repository and run:

./gradlew build

On Windows:

.\gradlew.bat build

The remapped JAR is generated in build/libs.

License

SmoothLogin is licensed under the GNU General Public License v3.0.