SocketSVC DocsVersions and loaders
Minecraft version catalog, loader adaptation, source assembly, adding and withdrawing versions
這一頁還沒有翻譯，以下顯示英文原文。
Supported Minecraft Java Edition versions: 1.21.11, 26.1, 26.1.1, 26.1.2, 26.2, 26.3, the same for the client mod and the server mod. The approach is "shared code + version adaptation + a separate JAR per version", not a single JAR guessing the version at runtime: every Minecraft version × loader has its own JAR. When installing, pick the exact same version and loader as the game, and install only one SocketSVC client JAR.
Support matrix
| Minecraft | Java | Fabric/Quilt | NeoForge | Forge |
|---|---|---|---|---|
| 1.21.11 | 21 | ✓ | ✓ | ✓ |
| 26.1 | 25 | ✓ | ✓ (beta loader) | ✓ |
| 26.1.1 | 25 | ✓ | ✓ (beta loader) | ✓ |
| 26.1.2 | 25 | ✓ | ✓ | ✓ |
| 26.2 | 25 | ✓ | ✓ | ✓ |
| 26.3 | 25 | ✓ | ✓ | ✓ |
This table summarises gradle/socketsvc.properties, which is authoritative. It is an explicitly verified matrix and never implicitly claims compatibility with future versions.
- Checked 2026-10-18: NeoForge 26.3 has a stable release (26.3.0.92) and Forge has released 26.3 (66.0.13, none marked recommended yet). NeoForge 26.1 and 26.1.1 still only have
-betaversions on maven.neoforged.net, and NeoForge has moved on to 26.1.2, so those two stay beta. - Quilt uses the Fabric JAR: Quilt Loader runs Fabric API mods, and QSL has no 26.x release, so no separate Quilt JAR is built.
- Supported versions, each loader's version and the feature versions of all three sides (client/server/proxy) all come from the version catalog.
- The Paper plugin is compiled against Paper API
1.21.11-R0.1-SNAPSHOT.
Client and server compatibility are verified separately
Client support for 26.x does not mean the server has been verified on the same Paper version; server compatibility must be tested separately. At runtime the server must also meet the Java requirement of the Paper version it runs.
Version catalog
All of these settings live in gradle/socketsvc.properties:
| Setting | Purpose |
|---|---|
client.version/server.version/proxy.version | Feature version of each side, bumped and released independently |
minecraft.supported/minecraft.default | Officially supported list and the version used when none is given |
fabric.loader/fabric.loom/neoforge.moddev/forge.gradle/paper.api | Shared toolchain versions |
Per-version java/platform/renames | That version's Java, the Java implementation family it uses, and its ordered API transformation rules |
Per-version fabric.api/fabric.permissions/modmenu/flashback | Fabric-side dependencies; omitting flashback skips that integration |
Per-version neoforge/forge | That version's loader version; omit it to not build or publish that loader. A NeoForge version containing -beta is published as beta automatically |
platform currently accepts legacy and modern; adding another implementation family also requires updating the settings validation and the related tests.
Build environment and output
Building requires JDK 25; 1.21.11 additionally needs JDK 21 as its compile/test toolchain. The Gradle daemon runs on 25; each project's bytecode and Mixin compatibility level come from the version catalog; Paper and proxy compile to Java 21. For build commands see development setup.
- Without
minecraftVersion,minecraft.defaultis used, currently 1.21.11. - An unknown version fails during the settings phase; it never silently falls back to another version.
- If a version has no
<MC>.neoforge/<MC>.forge, that loader's project is not included. buildAll,buildAllClientsandbuildAllServersread the version catalog directly and run a separate Gradle build per version in sequence, always building every supported version regardless of-PminecraftVersion.
| Artifact | Location |
|---|---|
| Client | client/<loader>/build/<MC>/libs/socketsvc-client-<loader>-<client.version>+mc<MC>.jar |
| Server mod | server/<loader>/build/<MC>/libs/socketsvc-server-<loader>-<server.version>+mc<MC>.jar |
JARs not to use
NeoForge/Forge also produce a -slim.jar (libraries not bundled); do not publish or install it. The old client/build/<MC>/libs path is no longer updated; do not use leftover JARs from it.
For IDE work, set -PminecraftVersion=26.2 in the Gradle arguments, reload Gradle and run generateMainCompatibilitySources (see IDE and dev runs). Build different versions one after another in the same checkout; parallel builds across versions should use separate checkouts so the Loom/ModDevGradle/ForgeGradle working directories do not interfere.
Names and source assembly
Shared source code uses Mojang's official names.
- Fabric: per the Fabric 26.1 migration notes, Yarn is no longer provided from 26.1 on, and Java 25 with the non-remapping Loom plugin is required. Fabric for 1.21.11 uses the remapping Loom plugin and its release artifact is still remapped; 26.x produces official-name JARs directly.
- NeoForge/Forge: use official names at runtime on every supported version (for Forge 1.21.11 the installer renames the game; confirmed against Forge 1.21.11 mods actually published on Modrinth), so there is no reobf step. Forge's Mixin configs are declared in the JAR manifest (
MixinConfigs), NeoForge's inneoforge.mods.toml. - Metadata:
fabric.mod.json, mods.toml and the Mixin Java level are expanded from the version catalog; you cannot claim support by simply widening the Minecraft range in the metadata.
Source assembly is handled by socketsvc.sources in gradle/minecraft.gradle: it merges common/minecraft, <side>/common and the loader project's src/<kind>/java in that order, layering src/<platform>/<kind>/java on top of each directory; for identical relative paths the later one overrides the earlier, and the transformation rules are applied last.
Generation uses the same rules for main and test, so the tests really target each version's game API. Audio, WebSocket, handshake contents, settings data and UI behaviour are shared; nothing uses reflection to guess the game version or loader, and no full copy of the code exists per version or per loader.
NeoForge/Forge packaging
NeoForge/Forge load every JAR as a Java module and do not allow two modules to export the same package (e.g. mp3spi and vorbisspi both use javazoom.spi). Pure Java libraries are therefore relocated with shadow to com.socketsvc.shaded, and JNI libraries that cannot be relocated (opus4j/rnnoise4j) are embedded with Jar-in-Jar; Fabric still uses nested JARs.
Maintenance entry points
| Location | Contents |
|---|---|
gradle/socketsvc.properties | Feature versions of the three sides, supported list, default version, toolchains, and per-version Java/platform/transformation rules/Fabric API/permissions API/Mod Menu/Flashback/NeoForge/Forge versions |
gradle/minecraft.gradle | Shared by all loader projects: catalog reading, artifact naming, source assembly and transformation, metadata expansion, bytecode verification |
gradle/client-*.gradle, gradle/server-*.gradle | Dependencies, packaging and artifact verification per side and loader; client-libraries.gradle/server-libraries.gradle are the runtime library lists shared by all loaders |
gradle/forge.gradle, gradle/modular-jar.gradle | ForgeGradle setup, and NeoForge/Forge relocation and Jar-in-Jar packaging |
settings.gradle.kts | Validates the version catalog and includes loader projects per version; the 1.21.11 Fabric projects use legacy.gradle.kts (remapping Loom) instead |
client/common/src, server/common/src | Loader-independent code based on Mojang's official names; edit here, not build/generated |
<side>/<loader>/src | Loader entry points and platform implementations (ClientPlatform/ServerModPlatform) |
gradle/compat/*.json | Upstream pure renames/access-path changes, applied in the order listed in the version catalog; files can restrict which file names a rule applies to |
src/modern/<kind>/java | The few classes that need a different implementation; they replace the side's shared class with the same relative path |
Network compatibility between loaders
The handshake payloads (socketsvc:handshake, socketsvc:handshake_request) are raw bytes on every loader, identical to Paper's plugin messaging, so any client loader can connect to Paper or to any loader's server mod.
| Loader | Registration |
|---|---|
| Fabric | CustomPacketPayload |
| NeoForge | CustomPacketPayload (optional()) |
| Forge | EventNetworkChannel registering an optional raw channel |
When changing the payload format, verify all three loaders and Paper together.
Adding a release version
Verify dependencies. Check Mojang's release versions and each loader's Maven metadata to confirm the actual compatible versions of Java, Fabric API, fabric-permissions-api, Mod Menu, NeoForge and Forge.
Complete the version catalog. Add a full version row and a minecraft.supported entry. Versions with the same API can reuse platform and renames; omit a loader's key if it does not support the version yet. Do not substitute floating dependencies or a widened Minecraft range for verification.
Compile to find differences. Run python scripts/build_matrix.py <version> to get the real compile errors. Pure renames go into a new gradle/compat/*.json; rules are ordered text replacements, not a Java parser, so restrict them with files when necessary and check the generated output. Only use a Java overlay with the same relative path when behaviour differs, to avoid copying the whole client.
Check Mixins. When the nametag rendering path changes, check the bytecode, update the hook and its tests; do not lower Mixin required or defaultRequire to hide failures.
Run the full matrix. scripts/build_matrix.py reads the version catalog directly, so adding a version does not require editing any build script.
Publish after in-game acceptance. After real in-game acceptance (see validation levels below), publish the corresponding JARs (see publishing). Only bump client.version/server.version for the side that changed; the Minecraft version and loader are added automatically to artifact names, metadata and Modrinth version numbers.
Withdrawing a version or loader
- Remove the version from
minecraft.supported, or delete only that version's<MC>.neoforge/<MC>.forgekey; if it is the default version, updateminecraft.defaultas well. - Before removing rules that seem unused, confirm no other version references them.
- Do not overwrite a published JAR with the same name.
For release notes before withdrawal and version lifecycle rules, see version retirement and release records.
Validation levels
build enforces client/server JUnit, Mixin, native audio regression and artifact verification; for what each task actually checks, see validation and releases. Behaviour tests for the relay, authentication, hot reload and speaker API live in :server:paper:test; the server mod uses the same common/core implementation.
JUnit and Mixin reports are under <side>/<loader>/build/<version>/reports/tests/. CI runs the same gates on Linux with one job per Minecraft version and keeps the artifacts and test reports.
Automated checks are not in-game acceptance
These automated checks are not equivalent to real multiplayer voice acceptance. NeoForge/Forge clients currently only have compile and packaging verification, with no automated in-game load test.
Before a release, still confirm on every game version and loader:
- Joining/leaving servers and reconnecting
- Two-player voice / mute / deafen
- Settings / device selection / keybinds (including opening settings from the main menu)
- F1 hiding the HUD
- Nametags with scoreboards / sneaking / occlusion
- The server mod's
/ssvc-server status|reloadand permission nodes - Real devices and audio on Windows/Linux/macOS