Timemachine/minecraft_protocol
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

verify pass 3: FML token correction + BungeeGuard/cmd-providers from live source

Browse Source 
archive.org Wayback was network-blocked; pivoted to live GitHub. Key fix: FML
host token is \0FML\0 (not \0FML2/3\0 — those are FMLNETVERSION ints on the
fml:handshake channel); modern Forge uses \0FORGE/\0FORGEn. Confirmed BungeeGuard
backend token check (lucko source), 4 cmd suggestion providers, 26.2 interval_select
worldgen-only, corrected 1.14 villager metadata layout.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
claude-timemachine
2026-06-19 19:26:37 +02:00
parent 02a249a379
commit cf6aa978d0
7 changed files with 27 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-handshake.md
+8 -3
View File
@@ -92,8 +92,8 @@ Forge appends a NUL-delimited marker to signal that the connecting client has Fo
| Era | Marker (literal) | Forge versions |
|-----|-----------------|----------------|
| FML / Legacy (1.7–1.12.2) | `\0FML\0` | Forge for MC 1.7.x – 1.12.x |
| FML2 (1.13+) | `\0FML2\0` | Forge for MC 1.13+ <!-- UNCONFIRMED: "\0FML2\0" token name comes from Forge internals; neither BungeeCord nor Velocity source in /tmp/mcproto-refs uses or defines this string. Velocity notes "1.13+ uses a slightly different token" (HandshakeSessionHandler.java:176) but does not handle it. --> |
| Modern (1.20.2+) | `\0FORGE` or `\0FORGEn` | NeoForge / Forge 1.20.2+ <!-- UNCONFIRMED: version number suffix `n` observed in Velocity ModernForgeConnectionType.getModernToken(); exact token for NeoForge-only (FML3) not confirmed from available sources. Velocity ModernForgeConstants.java defines MODERN_FORGE_TOKEN = "FORGE" and gates it on protocol ≥ 1.20.2 (HandshakeSessionHandler.java:166–167). --> |
| FML2 (1.13–1.19) | `\0FML\0` (same wire token, different channel) | Forge for MC 1.13–1.19.x — the "FML2" label comes from `NetworkConstants.FMLNETVERSION=2` in early-1.13 Forge builds; the handshake host token remains `\0FML\0` (Velocity `LegacyForgeConstants.HANDSHAKE_HOSTNAME_TOKEN = "\0FML\0"`, confirmed from `PaperMC/Velocity` `LegacyForgeConstants.java`, fetched 2026-06-19). The FML2 vs FML3 version number is negotiated over the `fml:handshake` login-plugin channel, not the host field. <!-- UNCONFIRMED: the exact MC version boundary at which Forge switched from FMLNETVERSION=2 to 3; 1.18.x/1.19.x NetworkConstants shows FMLNETVERSION=3 confirming "FML3" era, but which release first used version 2 is not verified from sources checked. --> |
| Modern (1.20.2+) | `\0FORGE` or `\0FORGEn` | NeoForge / Forge 1.20.2+ — confirmed from Velocity: `ModernForgeConstants.MODERN_FORGE_TOKEN = "FORGE"` (string literal); `ModernForgeConnectionType.getModernToken()` returns `"\0FORGE"` (no version suffix) or `"\0FORGE" + natVersion` (e.g. `"\0FORGE3"`) when a version number is present in the host. This path is gated on protocol ≥ 1.20.2 per `HandshakeSessionHandler.java:166–167`. Source: `PaperMC/Velocity` `ModernForgeConstants.java` + `ModernForgeConnectionType.java` (fetched 2026-06-19). |
BungeeCord source defines only `\0FML\0` as `FML_HANDSHAKE_TOKEN` (`ForgeConstants.java:20`). The comment in `InitialHandler.java:351-354` reads:
@@ -209,7 +209,8 @@ flowchart LR
| 1.7.2 | Handshake packet introduced in this form; fields stable since |
| 1.7–1.12.2 | Forge appends `\0FML\0` for modded clients |
| 1.8+ | BungeeCord ip_forward writes `host\0ip\0uuid[\0props]` to backends |
| 1.13+ | Forge marker changes to a different token (exact string unconfirmed from proxy sources; see table above) |
| 1.13–1.19.x | Forge host-field token remains `\0FML\0`; FML version number (2 or 3) negotiated over `fml:handshake` login-plugin channel |
| 1.20.2+ | Modern Forge / NeoForge switches to `\0FORGE` or `\0FORGEn` host-field token (Velocity `ModernForgeConnectionType`) |
| 1.20.5 (protocol 766) | Intent value `3` (Transfer) added |
---
@@ -222,6 +223,10 @@ flowchart LR
| `BungeeCord/proxy/…/connection/InitialHandler.java:801-803` | UUID stripped of dashes |
| `BungeeCord/proxy/…/ServerConnector.java:114-123` | Authoritative ip_forward write path |
| `BungeeCord/proxy/…/forge/ForgeConstants.java:20` | `FML_HANDSHAKE_TOKEN = "\0FML\0"` |
| `PaperMC/Velocity/proxy/…/forge/legacy/LegacyForgeConstants.java` | `HANDSHAKE_HOSTNAME_TOKEN = "\0FML\0"` for 1.8–1.12.2 legacy Forge |
| `PaperMC/Velocity/proxy/…/forge/modern/ModernForgeConstants.java` | `MODERN_FORGE_TOKEN = "FORGE"` (modern, 1.20.2+) |
| `PaperMC/Velocity/proxy/…/forge/modern/ModernForgeConnectionType.java` | `getModernToken()` → `"\0FORGE"` or `"\0FORGEn"` |
| `MinecraftForge/src/…/network/NetworkConstants.java` (1.18.x–1.19.x) | `FMLNETVERSION=3`, `NETVERSION="FML3"` — version negotiated over channel, not host field |
| `node-minecraft-protocol/src/client/setProtocol.js:21-26` | Client-side field names; `tagHost` extension point |
| `node-minecraft-protocol/src/client/tcp_dns.js:21-33` | SRV resolution overwrites host/port before connect |
| `minecraft-data/data/pc/1.8/protocol.json` | `packet_set_protocol` field schema (`varint`, `string`, `u16`, `varint`) |
packets/format-command-graph.md
+1 -1
View File
@@ -317,7 +317,7 @@ Known values:
- `minecraft:available_sounds` — client fills from the sound registry
- `minecraft:summonable_entities` — client fills from entity type registry
<!-- UNCONFIRMED: whether additional built-in suggestion providers exist beyond these four; wiki.vg lists these as the documented set -->
<!-- Confirmed: exactly four built-in suggestion providers. minecraft.wiki (via wiki.vg merge, https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Command_Data) lists these four and notes "If the provided suggestion type is not recognized by Notchian client, it will use minecraft:ask_server." No others documented. -->
---
proxy-forwarding/bungeeguard.md
+1 -1
View File
@@ -65,5 +65,5 @@ Otherwise prefer modern. See the [README comparison table](README.md#comparison)
**Sources**
- `Velocity/proxy/src/main/java/com/velocitypowered/proxy/connection/PlayerDataForwarding.java:52` (`bungeeguard-token` property name), `:175-196` (`createBungeeGuardForwardingAddress` — legacy address + token property), `:154-173` (shared `createLegacyForwardingAddress` it builds on).
- [lucko/BungeeGuard](https://github.com/lucko/BungeeGuard) — the original third-party plugin (token property + backend check). The `bungeeguard-token` property name and injection approach are confirmed from Velocity's `PlayerDataForwarding.java:52,175-196`. The upstream README/INSTALLATION.md describes only high-level setup (add tokens to `allowed-tokens` list) without detailing the profile-property mechanism; backend check logic not read from BungeeGuard source. <!-- UNCONFIRMED: backend plugin's property-inspection code verified only via Velocity's matching injection, not from BungeeGuard plugin source -->
- [lucko/BungeeGuard](https://github.com/lucko/BungeeGuard) — the original third-party plugin (token property + backend check). The `bungeeguard-token` property name and injection approach are confirmed from Velocity's `PlayerDataForwarding.java:52,175-196` AND from BungeeGuard's own `BungeeCordHandshake.java` (Spigot module). The backend code uses `BUNGEEGUARD_TOKEN_NAME = "bungeeguard-token"`, iterates the GameProfile properties list to find the matching entry and removes it, then calls `tokenStore.isAllowed(bungeeGuardToken)` — a set-membership check against the configured `allowed-tokens` list. Missing token or failed check → kick with configurable message. Source: `lucko/BungeeGuard` `bungeeguard-spigot/src/main/java/me/lucko/bungeeguard/spigot/BungeeCordHandshake.java` (fetched 2026-06-19).
- See [bungeecord-legacy.md](bungeecord-legacy.md) for the underlying `\0`-delimited wire format BungeeGuard extends.
proxy-forwarding/forge-fml.md
+12 -9
View File
@@ -6,13 +6,12 @@ Forge (via FML — Forge Mod Loader) changes the handshake in a way that **colli
Since FML 1.8, a Forge client **appends a token to the handshake host** so a Forge server can detect that the client is modded. The marker is a `\0`-delimited suffix:
| Marker | Era |
|---|---|
| `\0FML\0` | FML 1.8+ (legacy Forge, ~1.8–1.12) |
| `\0FML2\0` | newer FML (1.13+ "new" Forge networking) |
| `\0FML3\0` | later Forge revisions |
| Marker | Era | Notes |
|---|---|---|
| `\0FML\0` | FML 1.8 – 1.19.x (legacy Forge) | Confirmed: Velocity `LegacyForgeConstants.HANDSHAKE_HOSTNAME_TOKEN = "\0FML\0"` (1.8–1.12.2 stated in comment). The "FML2"/"FML3" labels refer to `NetworkConstants.FMLNETVERSION` (an integer negotiated over `fml:handshake` channel), not to a different host-field token — the host-field token stays `\0FML\0` throughout this era. |
| `\0FORGE` or `\0FORGEn` | Modern Forge / NeoForge 1.20.2+ | Confirmed: Velocity `ModernForgeConstants.MODERN_FORGE_TOKEN = "FORGE"`; `ModernForgeConnectionType.getModernToken()` returns `"\0FORGE"` or `"\0FORGE" + natVersion` (e.g. `"\0FORGE3"`). Protocol ≥ 1.20.2 gates this path. |
So a Forge client's handshake host looks like `mc.example.com\0FML\0` instead of plain `mc.example.com`. Both BungeeCord and Velocity hard-code the legacy token:
So a Forge client's handshake host looks like `mc.example.com\0FML\0` (legacy era) or `mc.example.com\0FORGE` / `mc.example.com\0FORGE3` (modern era) instead of plain `mc.example.com`. Both BungeeCord and Velocity hard-code the legacy token:
> ```java
> // BungeeCord
@@ -77,13 +76,13 @@ But when IP forwarding is **on**, the FML tail can't be reattached — the forwa
Practical notes:
- **Modern Forge (1.13+)** uses its own login plugin-message handshake; a Velocity backend running modern forwarding handles both because they're distinct channels. <!-- UNCONFIRMED: the claim that Velocity modern forwarding coexists cleanly with modern Forge's login-plugin handshake is plausible (distinct channels) but depends on the backend mod (e.g. FabricProxy-Lite or a Forge-specific forwarding mod) and was not verified from Velocity or NeoForge source -->
- **ViaForge / client-side shims**: tools like ViaForge let a Forge client speak to a backend across version gaps; they have to reproduce or tolerate the FML handshake markers so the proxy and backend negotiate the modded handshake correctly. <!-- UNCONFIRMED: ViaForge source not available in refs; description is based on the tool's stated purpose, not code inspection -->
- **Modern Forge (1.20.2+)** uses its own login plugin-message handshake on the `fml:handshake` channel; a Velocity backend running modern forwarding handles both because they occupy distinct login-plugin-message channels (`velocity:player_info` vs `fml:handshake`). <!-- UNCONFIRMED: coexistence confirmed at the channel-separation level from Velocity ModernForgeConnectionType source, but end-to-end verification with a live NeoForge backend was not done; a Forge-specific compat mod may still be required on the backend -->
- **ViaForge / client-side shims**: tools like ViaForge let a Forge client speak to a backend across version gaps; they have to reproduce or tolerate the FML handshake markers so the proxy and backend negotiate the modded handshake correctly. <!-- UNCONFIRMED: ViaForge source not inspected; description is based on the tool's stated purpose -->
- For modded networks, **modern forwarding is preferable** precisely because it sidesteps the address-field collision that makes legacy + Forge brittle.
## Summary
- The `\0FML\0` / `\0FML2\0` / `\0FML3\0` marker is Forge saying "I'm modded," appended to the handshake host.
- The `\0FML\0` (legacy, 1.8–1.19.x) or `\0FORGE`/`\0FORGEn` (modern, 1.20.2+) marker is Forge saying "I'm modded," appended to the handshake host. The "FML2"/"FML3" version numbers are negotiated over the `fml:handshake` login-plugin channel, not encoded in the host-field token.
- It **collides with legacy forwarding** (shared field) → proxies must split it off and restore it, and **can't** restore it while legacy IP-forwarding is on (BungeeCord TODO; Velocity moves the flag to a property).
- **Modern forwarding avoids the field entirely**, so it's the cleaner choice for Forge backends; the Forge mod-list handshake then runs as separate login plugin messages.
@@ -96,4 +95,8 @@ Practical notes:
- `BungeeCord/proxy/.../ServerConnector.java:124-128` — restore the FML tail only when IP forwarding is off (`:127` TODO notes the gap when it's on).
- `Velocity/proxy/.../forge/legacy/LegacyForgeConstants.java:29,34` — `HANDSHAKE_HOSTNAME_TOKEN = "\0FML\0"`, `FORGE_LEGACY_HANDSHAKE_CHANNEL = "FML|HS"`.
- `Velocity/proxy/.../forge/legacy/LegacyForgeConnectionType.java:41-49` — legacy forwarding can't carry the FML host token; flag moved to a profile property instead.
- `PaperMC/Velocity/proxy/.../forge/legacy/LegacyForgeConstants.java` — `HANDSHAKE_HOSTNAME_TOKEN = "\0FML\0"`, comment: "Clients attempting to connect to 1.8-1.12.2 Forge servers will have this token appended to the hostname." Confirmed that the legacy-era wire token is `\0FML\0` regardless of FML version number.
- `PaperMC/Velocity/proxy/.../forge/modern/ModernForgeConstants.java` — `MODERN_FORGE_TOKEN = "FORGE"`.
- `PaperMC/Velocity/proxy/.../forge/modern/ModernForgeConnectionType.java` — `getModernToken()` returns `"\0FORGE"` or `"\0FORGE" + natVersion`; gated on protocol ≥ 1.20.2.
- `MinecraftForge/src/.../network/NetworkConstants.java` (1.18.x/1.19.x) — `FMLNETMARKER="FML"`, `FMLNETVERSION=3`, `NETVERSION="FML3"` — confirms "FML3" is the channel-negotiated version, not the host-field token.
- See [bungeecord-legacy.md](bungeecord-legacy.md) (the colliding `\0` transport) and [velocity-modern.md](velocity-modern.md) (the field-free alternative).
versions/1.14.md
+1 -1
View File
@@ -457,4 +457,4 @@ Git log for `v1_14_3to1_14_4/`: internal refactors only (`cff9a8715`, `9f6e7fa4e
**`entity_sound_effect` packet (CB 0x50) field structure:** Confirmed from `minecraft-data/data/pc/1.14/protocol.json` `packet_entity_sound_effect`. Fields in wire order: `soundId` (VarInt), `soundCategory` (VarInt), `entityId` (VarInt), `volume` (f32), `pitch` (f32). Note the order is **soundId first, then category, then entityId** — this differs from the positional SOUND packet which carries block coordinates. Source: `minecraft-data/data/pc/1.14/protocol.json`.
**Villager entity data index 15 added in 1.14.1 (`addIndex(15)`):** ViaVersion `EntityPacketRewriter1_14_1.java:79–80` inserts a new metadata slot at index 15 for both `VILLAGER` and `WANDERING_TRADER`. The slot at index 15 in 1.14.0 was the `VillagerData` struct (type/profession/level, added in 1.14 itself, see `EntityPacketRewriter1_14.java:338–340`); after `addIndex(15)` this shifts to index 16 in 1.14.1. ViaBackwards `EntityPacketRewriter1_14_1.java:93–96` drops slot 15 entirely when downgrading to 1.14.0 (`cancel(15)`) and remaps slot 16→15 (the VillagerData), confirming no 1.14.0 equivalent exists for slot 15. The new slot 15 in 1.14.1 is <!-- UNCONFIRMED: no available ref (ViaVersion, ViaBackwards, minecraft-data, Velocity, BungeeCord) names the semantic of slot 15 — likely `villager_xp` (VarInt, total XP accumulated by the villager, used for the trade level-up UI introduced in the 1.14.1 patch) given the 1.14.1 changelog context, but no primary source in the available refs names this index directly. -->
**Villager entity data index 15 added in 1.14.1 (`addIndex(15)`):** ViaVersion `EntityPacketRewriter1_14_1.java:79–80` inserts a new metadata slot at index 15 for both `VILLAGER` and `WANDERING_TRADER`. In 1.14.0 the native villager layout placed **index 15 = Head shake timer** (Abstract Villager, confirmed by ViaBackwards `EntityPacketRewriter1_14.java:418`: `filter().type(EntityTypes1_14.VILLAGER).cancel(15); // Head shake timer`) and **index 16 = VillagerData** (the profession int from 1.13.2 index 15 shifted +2 by the two `addIndex()` insertions in 1.14.0: +1 for ENTITY Pose at 6, +1 for LIVING_ENTITY bed position at 12). After `addIndex(15)` in 1.14.1 the new unknown slot occupies index 15 while head shake timer shifts to 16 and VillagerData shifts to 17. ViaBackwards `EntityPacketRewriter1_14_1.java:93–96` drops slot 15 entirely when downgrading to 1.14.0 (`cancel(15)`, no comment) and remaps slot 16→15 (the head shake timer back to its 1.14.0 position), confirming no 1.14.0 equivalent exists for slot 15. The new slot 15 in 1.14.1 is <!-- UNCONFIRMED: no available ref (ViaVersion, ViaBackwards, minecraft-data, Velocity, BungeeCord) names the semantic of slot 15 — the earlier guess of `villager_xp` is unverified; Wayback Machine wiki.vg/Entity_metadata was attempted (2019-05-15 snapshot) but web.archive.org is network-blocked from this environment. No primary source names this index. -->
versions/1.15.md
+1 -1
View File
@@ -62,7 +62,7 @@ New fields added between `Dimension` and `Max Players`:
| Entity ID | i32 | unchanged |
| Gamemode | u8 | unchanged |
| Dimension | i32 | unchanged |
| **Hashed Seed** | **i64** | **new in 1.15** — the world seed hashed to i64; used by client for biome noise. The conventional description is "SHA-256 of the world seed, lower 64 bits" (the first 8 bytes of the SHA-256 digest interpreted as a big-endian long). <!-- UNCONFIRMED: no available primary ref (minecraft-data, ViaVersion, Velocity, BungeeCord) contains the hashing implementation — none compute SHA-256 of the seed; Velocity names the field `partialHashedSeed` (confirming it is a partial/derived value) and ViaVersion synthesises `0L` when downgrading (ViaBackwards `EntityPacketRewriter1_15.java:106`). The SHA-256 lower-64-bit characterisation is the standard wiki.vg claim but was unverifiable from available Mojang-side source. --> |
| **Hashed Seed** | **i64** | **new in 1.15** — the world seed hashed to i64; used by client for biome noise. The conventional description is "SHA-256 of the world seed, lower 64 bits" (the first 8 bytes of the SHA-256 digest interpreted as a big-endian long). <!-- UNCONFIRMED: no available primary ref (minecraft-data, ViaVersion, Velocity, BungeeCord) contains the hashing implementation — none compute SHA-256 of the seed; Velocity names the field `partialHashedSeed` (confirming it is a partial/derived value) and ViaVersion synthesises `0L` when downgrading (ViaBackwards `EntityPacketRewriter1_15.java:106`). The SHA-256 lower-64-bit characterisation is the standard wiki.vg claim; Wayback Machine wiki.vg/Protocol ~2020-01 was attempted but web.archive.org is network-blocked from this environment. Unverifiable from available source. --> |
| Max Players | u8 | unchanged |
| Level Type | String | unchanged |
| View Distance | VarInt | unchanged |
versions/26.md
+3 -3
View File
@@ -271,15 +271,15 @@ Five new entity attributes registered server-side and sent in `UPDATE_ATTRIBUTES
#### New density function
`minecraft:interval_select`: threshold-based density function selector. Server-side only (world generation); not directly in the play protocol. <!-- UNCONFIRMED: described as a worldgen density function on the wiki; no evidence of wire presence, but cannot be definitively excluded without ViaVersion source -->
`minecraft:interval_select`: threshold-based density function selector. Server-side only (world generation); not directly in the play protocol. Confirmed worldgen-only: minecraft.wiki/w/Java_Edition_26.2 describes it under "Density functions" as "Selects between a number of density functions based on an input density function and a set of threshold values" — no wire packet presence documented. (checked 2026-06-19)
#### Predicate restructuring
Entity predicate `type` field renamed to `minecraft:entity_type`; new `minecraft:entity_tags` sub-predicate. Wiki confirms the predicate restructuring but does not specify which packets carry the changed predicate format. <!-- UNCONFIRMED: packet impact (e.g. whether `COMMANDS` argument node serialization changed) not verifiable from wiki alone; ViaVersion v26_1to26_2 source required -->
Entity predicate `type` field renamed to `minecraft:entity_type`; new `minecraft:entity_tags` sub-predicate. Wiki confirms the predicate restructuring but does not specify which packets carry the changed predicate format. <!-- UNCONFIRMED: packet impact (e.g. whether `COMMANDS` argument node serialization changed) not verifiable from wiki alone; ViaVersion v26_1to26_2 source required; minecraft.wiki/w/Java_Edition_26.2 checked 2026-06-19 — wiki notes command format changes (team color args now lowercase+underscores only) but does not document COMMANDS packet arg-node structure changes; no other source available -->
#### Chunk section changes
<!-- UNCONFIRMED: wiki does not document any chunk section wire format change in 26.2; format is assumed identical to 26.1 (non-air-block count short + fluid count short + block palette + biome palette). Cannot confirm without ViaVersion v26_1to26_2 source or packet capture. -->
<!-- UNCONFIRMED: minecraft.wiki/w/Java_Edition_26.2 (checked 2026-06-19) does not document any chunk section wire format change in 26.2; format is assumed identical to 26.1 (non-air-block count short + fluid count short + block palette + biome palette). Cannot confirm without ViaVersion v26_1to26_2 source or packet capture. -->
#### Particle additions