Offline Pass

English | 简体中文

Offline Pass is a minimal server-side Forge 1.20.1 mod that allows selected offline clients to join a server while online-mode=true remains enabled.

It is intended for private or trusted servers that want to keep premium authentication for real premium usernames while still allowing non-premium usernames to join.

Features

• Keeps the server in online-mode=true.
• Lets premium usernames continue through the normal online-mode login flow.
• Gives non-premium usernames an offline UUID and continues through Forge login negotiation.
• By default, offline players cannot use usernames that belong to premium Minecraft accounts.
• Supports a forced-offline username list for names that should always use offline identity.
• Sends simple login identity notices to players.
• Provides English and Simplified Chinese in-game messages.

Security Warning

Offline Pass does not authenticate offline players.

It does not provide account registration, password login, identity ownership proof, anti-impersonation protection, database integration, permission integration, or EasyAuth-style account protection.

Anyone who can connect with an allowed offline username can use that offline identity. By default, Offline Pass avoids letting offline players use premium usernames. If you add a premium username to the forced-offline list, you are explicitly allowing offline players to use that name. Use this mod only when you understand that risk, preferably on private or trusted servers.

How It Works

• If the username is premium, the player continues through normal online-mode authentication.
• If the username is not premium, the player is accepted with an offline UUID.
• If you want an offline player to use a premium username, add that username to config/offlinepass/forced-offline-names.txt or use the command below. That name will then always use offline identity.

Offline Pass returns accepted offline players to Forge's normal login negotiation, so mod channel handshakes still run.

Installation

1. Download the Offline Pass jar.
2. Put the jar into the server mods/ folder.
3. Keep online-mode=true in server.properties.
4. Start or restart the server.

This mod is server-side only. Clients do not need to install it.

Configuration

Files:

config/offlinepass/premium-cache.tsv
config/offlinepass/forced-offline-names.txt

premium-cache.tsv stores username status results. forced-offline-names.txt stores usernames that should always use offline identity.

Commands

Requires permission level 3:

/offlinepass forcedoffline add <name>
/offlinepass forcedoffline remove <name>
/offlinepass forcedoffline list
/offlinepass forcedoffline reload

add and remove update both memory and forced-offline-names.txt immediately. reload is only needed if you manually edit the file while the server is running.

Build From Source

./gradlew build

The jar is written to:

build/libs/offlinepass-0.1.0.jar

License

MIT License.

Credits

Implementation assistance by Codex.

Offline Pass 中文说明

English | 简体中文

Offline Pass 是一个极简 Forge 1.20.1 服务端 mod，用于在服务器保持 online-mode=true 的情况下，允许部分离线客户端进入服务器。

它适合私人服务器或可信服务器：正版用户名继续走正版验证，非正版用户名走离线身份。

功能

• 保持服务器 online-mode=true。
• 正版用户名继续走正常正版登录流程。
• 非正版用户名使用离线 UUID，并继续 Forge 登录协商。
• 默认情况下，离线玩家不能使用任何正版 Minecraft 账号已经占用的用户名。
• 支持强制离线用户名名单。
• 玩家进服后提示当前是正版身份还是离线身份。
• 游戏内提示支持英文和简体中文。

安全警告

Offline Pass 不会对离线玩家做鉴权。

它不提供账号注册、密码登录、身份所有权证明、顶号防护、数据库集成、权限集成，也不是 EasyAuth 账号系统的替代品。

任何能使用某个允许的离线用户名连接服务器的人，都可以使用该离线身份。默认情况下，Offline Pass 会避免离线玩家使用正版用户名。如果你把某个正版用户名加入强制离线名单，就等于明确允许离线玩家使用这个名字。请只在理解这些风险的情况下使用，最好用于私人或可信服务器。

工作方式

• 如果用户名是正版，玩家继续走正常 online-mode=true 正版验证。
• 如果用户名不是正版，玩家会使用离线 UUID 进入。
• 如果你确实想让离线玩家使用某个正版用户名，需要将该用户名加入 config/offlinepass/forced-offline-names.txt，或使用下面的命令添加。加入后该用户名总是走离线身份。

离线玩家被放行后仍会回到 Forge 正常登录协商流程，因此 mod channel 握手仍会执行。

安装方式

1. 下载 Offline Pass jar。
2. 将 jar 放入服务器 mods/ 文件夹。
3. 保持 server.properties 中的 online-mode=true。
4. 启动或重启服务器。

这是服务端 mod，客户端不需要安装。

配置

文件：

config/offlinepass/premium-cache.tsv
config/offlinepass/forced-offline-names.txt

premium-cache.tsv 保存用户名状态结果。forced-offline-names.txt 保存强制使用离线身份的用户名。

命令

需要权限等级 3：

/offlinepass forcedoffline add <name>
/offlinepass forcedoffline remove <name>
/offlinepass forcedoffline list
/offlinepass forcedoffline reload

add 和 remove 会立即更新内存和 forced-offline-names.txt。只有在服务器运行时手动编辑文件后，才需要使用 reload。

从源码构建

./gradlew build

jar 输出位置：

build/libs/offlinepass-0.1.0.jar

许可证

MIT License。

鸣谢

实现由 Codex 协助完成。