ServerAuth Login Module —— Feature Overview

This is a pure server-side Fabric mod (1.20.2) that provides your server with a comprehensive security verification system, including forced login, automatic binding, session management, and anti-idling measures.

Core Design Principles

· Full admin control over accounts: Only OP (permission level 4) can create/delete accounts; regular

players cannot register themselves.

· Mandatory Login Verification: Unauthenticated players cannot move or interact (teleported to void space with black screen hover).

· Device-Bound Auto-Login: Players may opt to bind their account to their device's UUID for automatic

login upon future server access.

· Login Location Restoration: Upon successful login, players are teleported back to their initial spawn point.

· Dual Timeout Mechanism:

· Idle Timeout: Forced logout after a set number of minutes of inactivity post-login, requiring re-login.

· Auto-login validity period: After binding an account, auto-login becomes invalid if no login occurs within a set number of days. Manual password entry is required for subsequent logins.

· Add 3 languages, only administrators can use /change english , /change chinese and /change Spanish to switch between Chinese or English or Spanish, the default language for mods is Chinese

Player Experience (Player-facing features)

1. First Server Entry · Upon entering the game, players find themselves in the Void (black screen), suspended, and unable to move. · A prompt will appear in the chat bar instructing players to use the /login command to log in.
2. Login Command /login <username> <password> · Enter the username and password provided by the administrator to log in. · After successful login: · Players will be instantly teleported back to their entry location (spawn point or coordinates at entry). · The game mode will switch to Survival Mode, allowing normal gameplay.
3. Bind Device (Auto-Login) /login <username> <password> -b or /login <username> <password> --bind · Adding the -b parameter during login permanently binds the account to the player's UUID (unique identifier for verified accounts). · The player will automatically log in upon subsequent server entries without any action required.
4. Manual Logout /logout · Players can manually log out to return to the void state. Unbind Device /unbind · Use this command to unbind the current account from the device (e.g., when switching players). · After unbinding, manual login is required for the next entry. Administrator Functions (OP Exclusive)

All admin commands begin with /auth. Command Description Example

/auth create <username> <password> Create a regular player account

/auth create <username> <password> -admin Create an administrator account (with OP privileges)

/auth delete <username> Delete specified account

/auth unbind <username> Force unbind specified account (for players switching devices)

/auth list List all accounts and binding status

/auth kickall Kick all unlogged-in players (clear the server)

⚠️ Note: Before using /auth commands, administrators must grant themselves OP permissions via the console or other methods (op [playername]). Configurable Options (config/serverauth/config.json) The configuration file is automatically generated upon server startup. You can modify and save it at any time without restarting (the mod periodically re-reads settings).

json {

“requireLogin”: true, // Require login (recommended to keep true)

“kickOnFailedLogin”: true, // Kick player on login failure

“maxLoginAttempts”: 3, // Maximum login attempts (counting not yet implemented)

“enableSession”: true, // Enable session functionality

“sessionTimeout”: 30, // Reserved field, unused

“sessionTimeoutMinutes”: 30, // Idle timeout (minutes). Forced logout after inactivity exceeding this duration (0=no timeout)

“autoLoginExpiryDays”: 30 // Auto-login validity period (days). Accounts bound for longer than this period require manual password entry upon login (0=permanent validity)

· To prevent idle timeouts: “sessionTimeoutMinutes”: 0

· To enable permanent account binding: “autoLoginExpiryDays”: 0

**All account information (including password hashes, bound UUIDs, creation times) is stored in: [server root directory]/config/serverauth/accounts.json

· Password storage: Uses SHA-256 hashing, which cannot be reverse-engineered.

· Binding relationships: Based on Minecraft UUIDs (fixed for official accounts; generated from player names in offline mode). **

中文:

ServerAuth 登录模组 —— 功能详解

这是一个 纯服务端 Fabric 模组（1.20.2），为你的服务器提供了强制登录、自动绑定、会话管理、防挂机等完整的安全验证体系。

核心设计理念

· 管理员完全控制账号：只有 OP（权限等级4）可以创建/删除账号，普通玩家无法自行注册。

· 强制登录验证：未登录的玩家无法移动、无法交互（被传送到虚空，黑屏悬浮）。

· 绑定设备自动登录：玩家登录时可选择将账号与自己的 UUID 绑定，以后进入服务器自动登录。

· 登录位置恢复：登录成功后，玩家会被传送回刚进服时的位置。

· 双重超时机制：

· 在线挂机超时：登录后超过设定分钟无操作，强制登出，需重新登录。

· 自动登录有效期：绑定账号后，若超过设定天数未登录，自动登录失效，下次需手动输入密码。

·添加3种语言，只有管理员可用/change english 或者 /change chinese 或者 /change Spanish 来回切换中文,英文或者西班牙语，mod初始语言是中文

玩家体验（玩家视角的功能）

1.首次进入服务器

· 进入游戏后，玩家会发现自己处于 虚空（黑屏）、悬浮、无法移动 的状态。

· 聊天栏会显示提示信息，要求使用 /login 命令登录。

2.登录命令

/login <账号> <密码>

· 输入管理员发放的账号密码即可登录。

· 登录成功后： · 瞬间传送回进入服务器时的位置（出生点或进入时的坐标）。 · 游戏模式切换为生存模式，可以正常游玩。 3.绑定设备（自动登录）

/login <账号> <密码> -b或

/login <账号> <密码> --bind

· 登录时添加 -b 参数，会将当前账号与玩家的 UUID（正版账号唯一标识） 永久绑定。

· 以后该玩家每次进入服务器都会自动登录，无需任何操作。

4.手动登出

/logout

· 玩家可以主动登出，回到虚空状态。

解绑设备

/unbind

· 如果玩家想要解除当前账号与设备的绑定（例如换人玩），可以使用此命令。

· 解绑后，下次进入需要手动登录。

管理员功能（OP专用） 所有管理员命令都以 /auth 开头。

命令 说明 示例

/auth create <账号> <密码> 创建普通玩家账号

/auth create <账号> <密码> -admin 创建管理员账号（拥有OP权限）

/auth delete <账号> 删除指定账号

/auth unbind <账号> 强制解绑指定账号（玩家换设备时用）

/auth list 列出所有账号及绑定状态

/auth kickall 踢出所有未登录玩家（清场）

⚠️ 注意：使用 /auth 命令前，管理员必须在控制台或通过其他方式给自己 OP 权限（op 玩家名）。 可配置选项（config/serverauth/config.json） 服务器启动后自动生成配置文件，你可以随时修改并保存，无需重启（模组会定期重新读取）。

json {

"requireLogin": true, // 是否强制登录（建议保持true）

"kickOnFailedLogin": true, // 登录失败是否踢出玩家

"maxLoginAttempts": 3, // 最大登录尝试次数（暂未实现计数）

"enableSession": true, // 是否启用会话功能

"sessionTimeout": 30, // 保留字段，未使用

"sessionTimeoutMinutes": 30, // 在线挂机超时（分钟），超过此时间无操作强制登出（0=永不超时）

"autoLoginExpiryDays": 30 // 自动登录有效期（天），绑定账号后超过此天数未登录需手动输密码（0=永久有效）

· 想让玩家永不挂机超时："sessionTimeoutMinutes": 0

· 想让绑定账号永久有效："autoLoginExpiryDays": 0

所有账号信息（含密码哈希、绑定UUID、创建时间）都保存在：

[服务器根目录]/config/serverauth/accounts.json

· 密码存储：使用 SHA-256 哈希，无法逆向破解。

· 绑定关系：基于 Minecraft UUID（正版账号固定，离线模式由玩家名生成）