Essence by Lumina

Important

Status: Beta

A Java implementation of Nethernet, the WebRTC-based protocol used by Minecraft Bedrock Edition for multiplayer connectivity.

Overview

Nethernet-java provides a complete implementation of Minecraft Bedrock's networking stack, supporting both WebRTC-based connections (Realms/Online) and traditional RakNet connections. The library handles authentication, signaling, WebRTC transport, packet compression, and protocol encoding/decoding.

Features

• WebRTC Support: Full implementation of Bedrock's WebRTC protocol for Realms and online play
• RakNet Support: Direct server connections using traditional RakNet protocol
• LAN Discovery: Encrypted UDP broadcast discovery on port 7551
• Xbox Live Authentication: Microsoft account authentication with device code flow
• Realms API: Connect to and manage Minecraft Realms
• Cross-Platform: Native WebRTC binaries for Windows, Linux, and macOS (x64/ARM)

Installation

Build from source:

./gradlew build -x test

API Usage

Authentication

Authenticate with Microsoft/Xbox Live to access online features:

var auth = new BedrockAuth();

// Authenticate using device code flow
auth.authenticateWithDeviceCode(code -> {
    System.out.println("Visit: " + code.verificationUri());
    System.out.println("Enter code: " + code.userCode());
});

// Save session for later use
String sessionJson = new Gson().toJson(auth.saveToJson());
Files.writeString(Path.of("session.json"), sessionJson);

// Restore saved session
JsonObject session = new Gson().fromJson(
    Files.readString(Path.of("session.json")), 
    JsonObject.class
);
auth.loadFromJson(session);

Connecting to Realms

Connect to a Minecraft Realm using WebRTC:

var client = new BedrockClient(NativeWebRtcConnection::new);

// Set up packet handler
client.setOnPacket(packet -> {
    if (packet instanceof TextPacket text) {
        System.out.println("[Chat] " + text.getMessage());
    }
});

// Handle disconnections
client.setOnDisconnected(reason -> {
    System.out.println("Disconnected: " + reason);
});

// Get available realms and connect
var realms = new BedrockRealms(auth);
var realmsList = realms.getRealms();
client.connectToRealm(auth, realmsList.get(0)).join();

LAN Connections

Connect to local network games:

// Direct connection with known network ID
var client = new BedrockClient(networkId, NativeWebRtcConnection::new);
client.connectLAN().join();

// Discover available hosts
var discovery = new DiscoveryClient(myNetworkId);
discovery.setOnResponse(response -> {
    System.out.println("Found host: " + response.senderId);
});
discovery.startDiscovery();

Direct Server Connections (RakNet)

Connect directly to servers without WebRTC:

var client = new RakNetBedrockClient("play.example.com", 19132);
client.setBedrockAuth(auth);
client.setOnPacket(packet -> {
    System.out.println("Received: " + packet);
});
client.connect().join();

Sending Packets

// Send a chat message
var textPacket = new TextPacket();
textPacket.setType(TextPacket.Type.CHAT);
textPacket.setMessage("Hello, world!");
client.sendPacket(textPacket);

Creating a Server

Host your own Bedrock server:

var server = new BedrockServer(NativeWebRtcConnection::new);

server.setOnSession(session -> {
    session.setOnPacket(packet -> {
        if (packet instanceof LoginPacket login) {
            // Handle player login
        }
    });
});

server.listen(authToken);

Architecture

The library implements a layered networking stack:

Application Code
    ↓
BedrockClient (Packet handling via CloudburstMC codec)
    ↓
Framer (Compression: Snappy/Deflate)
    ↓
Connection (10KB segment framing)
    ↓
NativeWebRtcConnection (WebRTC: ICE/DTLS/SCTP)
    ↓
SignalingClient (WebSocket: wss://signal.franchise.minecraft-services.net)

Signal Types

• CONNECTREQUEST - Initiate connection
• CONNECTRESPONSE - Connection acknowledgment
• CANDIDATEADD - ICE candidate exchange
• CONNECTERROR - Connection failure

LAN Discovery

• Port: UDP 7551
• Encryption: AES-ECB(SHA256(0xDEADBEEF))

Project Structure

net/nethernet/
├── auth/
│   ├── BedrockAuth.java          # Xbox Live/MSA authentication
│   └── BedrockRealms.java        # Realms API client
├── protocol/
│   ├── AuthUtils.java            # JWT signing utilities
│   ├── BedrockClient.java        # High-level client interface
│   ├── RakNetBedrockClient.java  # Direct RakNet connections
│   └── PacketHandler.java        # Cloudburst protocol codec
├── rtc/
│   └── NativeWebRtcConnection.java # WebRTC transport layer
├── signaling/
│   ├── SignalingClient.java      # WebSocket signaling
│   └── Signal.java               # Signal message types
├── discovery/
│   └── DiscoveryClient.java      # LAN discovery broadcast
└── transforms/
    └── Framer.java               # Compression/framing

Platform Support

Platform	Native Library
Windows x64	windows-x86_64
Linux x64	linux-x86_64
macOS x64	macos-x86_64
macOS ARM64	macos-aarch64

Credits

• CloudburstMC/Protocol - Minecraft Bedrock protocol implementation

License

Important

Attribution and Source Continuity License 1.0

© 2026 Project Lumina

What This License Means

“This License” refers to this simplified summary of the Attribution and Source Continuity License (ASCL).

“The Software” refers to the covered work and any related files licensed under ASCL.

“You” refers to any individual or entity using, modifying, or distributing the Software.

---

You Are Free To

• Use the Software for any purpose.
• Study how the Software works.
• Modify the Software.
• Share the Software with others.
• Distribute your own modifications.

---

You Must

• Keep the Software and all derivatives open-source if you distribute them.
• Provide complete and publicly accessible source code with any distribution.
• Preserve clear and visible attribution to the original authors.
• License all derivative works under the same ASCL license.
• Include a copy of this License (or a link to it) with the Software.

---

You May NOT

• Make the Software or any derivative closed-source.
• Re-license or dual-license it under another license.
• Remove, hide, or minimize required attribution.
• Add restrictions that limit the rights granted by this License.
• Apply DRM, paywalls, usage limits, or access restrictions.

---

Important

• Rewrites, refactors, language ports, and AI-generated outputs are considered derivatives if substantially similar.
• Automated or AI-assisted creation does not bypass this License.

---

Disclaimer

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND. THE AUTHORS ARE NOT LIABLE FOR ANY DAMAGE, DATA LOSS, OR OTHER ISSUES ARISING FROM USE OF THE SOFTWARE.

---

Full License

See the full Attribution and Source Continuity License (ASCL) for complete terms and conditions.

• ASCL v1.0