75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# Java Edition Networking Overview
|
|
|
|
The Java Edition network stack handles standard Minecraft PC clients connecting over TCP. Wire-level structures and serialization logic reside in `pumpkin-protocol::java`, while connection management and gameplay packet handlers reside in `pumpkin::net::java`.
|
|
|
|
---
|
|
|
|
## The Five Protocol States
|
|
|
|
The Minecraft Java protocol operates as an explicit finite state machine. Every connection begins in the `Handshake` state and transitions according to client requests and server responses:
|
|
|
|
| State | Transition Trigger | Purpose & Next State |
|
|
| :--- | :--- | :--- |
|
|
| **Handshake** | Client initiates connection | Inspects protocol version and transitions to `Status`, `Login`, or `Transfer` |
|
|
| **Status** | `NextState = 1` | Streams MOTD, active player counts, favicon, and ping response |
|
|
| **Login** | `NextState = 2` | Authenticates account (Yggdrasil), negotiates encryption (AES-128), transitions to `Config` |
|
|
| **Transfer** | `NextState = 3` | Modern proxy / server-transfer negotiation |
|
|
| **Config** | Authentication success | Exchanges dynamic registries, data tags, feature flags, and resource packs |
|
|
| **Play** | Configuration acknowledged | Primary bidirectional gameplay loop (chunks, movement, combat, chat) |
|
|
|
|
1. **Handshake (`0x00`)**: Always the first packet sent by the client. It declares the client's protocol version, server address, port, and desired next state (`Status`, `Login`, or `Transfer`).
|
|
2. **Status**: Lightweight query state. The client requests a server list ping, and Pumpkin responds with the server version, player counts, favicon, and MOTD.
|
|
3. **Login**: Authenticates the player. If `online_mode` is enabled, Pumpkin performs an encryption handshake (AES-128/CFB8) and verifies the player's account with Mojang's Yggdrasil session servers.
|
|
4. **Config**: Introduced in modern Minecraft (1.20.2+). The server sends feature flags, known registries, resource packs, and custom server links before the player joins the physical world.
|
|
5. **Play**: The primary gameplay state. Used for all in-game actions including block breaking, entity movement, combat, chat, and chunk streaming.
|
|
|
|
---
|
|
|
|
## Connection Representation: `JavaClient` vs. `Player`
|
|
|
|
To keep memory usage minimal and prevent unnecessary allocations, Pumpkin cleanly separates pre-play connections from active players:
|
|
|
|
### `JavaClient`
|
|
- **Scope**: Exists across `Handshake`, `Status`, `Login`, and `Config` states.
|
|
- **Location**: `crates/pumpkin/src/net/java/mod.rs`.
|
|
- **Characteristics**:
|
|
- Contains connection metadata: client protocol version, remote address, encryption/compression state.
|
|
- Has no world coordinates, no physics, no inventory, and no living entity.
|
|
- Very low memory footprint.
|
|
|
|
### `Player`
|
|
- **Scope**: Exists solely during the `Play` state.
|
|
- **Location**: `crates/pumpkin/src/entity/player/`.
|
|
- **Characteristics**:
|
|
- Implements `EntityBase`, representing a living entity inside a `World` and `Level`.
|
|
- Holds inventory screens, health, hunger, velocities, and chunk view subscription queues.
|
|
- Contains an `Arc<JavaClient>` reference for network transmission.
|
|
|
|
---
|
|
|
|
## Multi-Version Support (`JavaMinecraftVersion`)
|
|
|
|
Pumpkin supports multiple Minecraft client versions. Protocol differences are handled cleanly via `pumpkin_util::version::JavaMinecraftVersion`:
|
|
|
|
- Packet IDs may differ across Minecraft versions. The `#[java_packet(ID)]` macro works with `pumpkin-data` to resolve the correct ID for the target version.
|
|
- When reading or writing packets, methods accept a `&JavaMinecraftVersion` reference to conditionally include or omit fields that changed in specific Minecraft updates.
|
|
|
|
```rust
|
|
if *version <= JavaMinecraftVersion::V_1_7_6 {
|
|
// Read legacy stance coordinate present in early Minecraft versions
|
|
let _stance = bytebuf.get_f64_be()?;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## The Packet Pipeline
|
|
|
|
Incoming Java packets pass through a structured pipeline:
|
|
|
|
1. **Length Framing**: `tokio_util::codec` decodes VarInt frame lengths.
|
|
2. **Decompression & Decryption**: If enabled, the raw buffer is decrypted via AES/CFB8 and decompressed via ZLib.
|
|
3. **Plugin Event Interception**: A `PacketReceivedEvent` is dispatched to the plugin manager. Plugins can inspect or cancel the packet before server processing.
|
|
4. **ID Dispatching**: The packet ID is matched against version-specific constants in `crates/pumpkin/src/net/java/mod.rs` (or the respective state module).
|
|
5. **Handling**: The packet struct is deserialized and processed by state-specific handler functions.
|