InvSeparate

InvSeparate is an open-source routing solution for Minecraft networks that host multiple modpacks behind a single proxy entrypoint.

It is made of two parts:

• a Velocity plugin that decides which login server and destination backend a player should use
• a client mod that appends a pack identifier to the Minecraft handshake before backend selection happens

This allows one Velocity proxy to serve vanilla clients, multiple modpack clients, and different login flows at the same time.

Features

• Identifier-based initial routing
• Two-stage routing from login server to final backend
• Default fallback for clients without the mod or with unknown identifiers
• Developed against Velocity 3.4.x with a target compatibility range through Velocity 4.x
• Monorepo layout for shared protocol code, proxy plugin, and multiple loader implementations

How It Works

1. The client mod reads the configured identifier
2. The mod writes <hostname>\0<identifier> into the handshake host field
3. The Velocity plugin reads the identifier from the raw handshake hostname
4. The plugin selects the configured login server and post-login target
5. If no identifier is present, normal default routing is used

Important: Velocity's getVirtualHost() discards any data after the null byte. The proxy plugin must therefore read the raw virtual host value to recover the identifier.

Repository Layout

• common: shared protocol constants and helpers
• velocity: Velocity plugin implementation
• neoforged: NeoForge client mod
• fabric: Fabric client mod
• forge: Forge client mod
• bungeecord: BungeeCord proxy plugin

Example Configuration

Velocity config at plugins/invseparate/config.yml:

default-server: "login"
default-post-login-server: "lobby"
post-login-delay-seconds: 5

identifiers:
  endlessmc-hng:
    login-server: "hng_login"
    post-login-server: "hng"

Client config:

identifier = "endlessmc-hng"

Build Notes

Common and Velocity

The repository currently defaults to Gradle 9.x, so these modules can be built directly:

./gradlew.bat :common:build :velocity:build

Loader Modules

Loader-specific modules such as neoforged, fabric, and forge live in the same repository, but they are not all enabled by default in settings.gradle.kts.

Follow the inline comments in the build files to switch the required Gradle version and enable the loader module you want to build.

Branch Strategy

• 1.21.1 is the current primary branch
• Other Minecraft versions should be maintained in dedicated branches when needed
• The 1.21.8 branch is no longer in use

Use Cases

• Vanilla clients join the default login server
• Different modpack clients join different login servers
• Players are forwarded to their target backend after authentication
• Networks that need a stronger proxy-side routing layer than simple post-login forwarding plugins

License

The current source headers are organized around the MIT license.

InvSeparate

InvSeparate 是一个面向多整合包 Minecraft 网络的开源路由方案。

它由两部分组成：

• Velocity 插件：在代理层识别客户端标识，并决定玩家应进入哪个登录服、认证后再进入哪个目标服。
• 客户端 Mod：在 Minecraft 握手阶段把整合包标识附加到握手主机名中，让代理在真正进入后端前就能完成分流。

这让同一个 Velocity 入口可以同时服务原版客户端、多个整合包客户端，以及各自不同的登录与落地流程。

特性

• 支持基于客户端标识的初始路由
• 支持“登录服 -> 目标服”的二段转发
• 未安装 Mod 或标识未知时回退到默认服务器
• 当前以 Velocity 3.4.x 为基线开发，目标兼容 Velocity 4.x
• 仓库内按模块组织公共协议、代理插件和不同加载器实现

工作原理

1. 客户端 Mod 在连接服务器时读取本地配置中的 identifier
2. Mod 将 <hostname>\0<identifier> 写入握手地址
3. Velocity 插件从原始握手主机名中提取标识
4. 插件根据 config.yml 中的规则选择登录服与登录后目标服
5. 若无标识或标识未知，则按默认规则处理

注意：Velocity 的 getVirtualHost() 会丢弃 null byte 之后的数据，因此服务端必须读取原始主机名而不是处理后的虚拟主机值。

仓库结构

• common：公共协议常量与工具
• velocity：Velocity 插件实现
• neoforged：NeoForge 客户端 Mod
• fabric：Fabric 客户端 Mod
• forge：Forge 客户端 Mod
• bungeecord：BungeeCord 代理插件

配置示例

Velocity 配置文件位于 plugins/invseparate/config.yml：

default-server: "login"
default-post-login-server: "lobby"
post-login-delay-seconds: 5

identifiers:
  endlessmc-hng:
    login-server: "hng_login"
    post-login-server: "hng"

NeoForge/Fabric 客户端配置核心项：

identifier = "endlessmc-hng"

构建说明

公共模块与 Velocity

当前仓库默认使用 Gradle 9.x，可直接构建：

./gradlew.bat :common:build :velocity:build :fabric:build :bungeecord:build

Loader 模块

fabric 现已可直接随默认 Gradle 9.x wrapper 构建；neoforged 与 forge 因依赖不同构建链，仍建议单独使用 Gradle 8.x 构建。

按仓库内注释切换对应模块与 Gradle 版本后，可分别构建对应 Loader 产物。

分支策略

• 当前主线版本为 1.21.1
• 其他 Minecraft 版本建议使用独立分支维护
• 1.21.8 分支已停止使用

适用场景

• 原版客户端进入默认登录服
• 不同整合包客户端进入各自的登录服
• 登录认证完成后自动进入各自目标后端
• 需要替代或补强现有“只负责转发、不负责识别客户端”的代理路由方案

许可证

本项目当前源码头部按 MIT 许可约定组织。