gophertunnel

repository·master·Indexed 19 days ago

https://github.com/sandertv/gophertunnel

A Go library providing tools and primitives for interacting with Minecraft (Bedrock Edition), designed for developers building clients, servers, and proxies. It includes the minecraft package for core functionality and supports protocol-specific operations such as RakNet.

Tokens
977
Snippets
1
Records
5
Agent score
19%

What's inside gophertunnel

  1. Overview of gophertunnel

    master

    gophertunnel is a collection of Go packages designed as a 'Swiss army knife' for Minecraft (Bedrock Edition) software. It provides the necessary primitives to build Minecraft-related tools, such as clients, servers, or proxies.

    Requirements: As of version v1.47.5, gophertunnel requires Go 1.24 or higher.

  2. Understand gophertunnel versioning and protocol support

    master

    gophertunnel is designed to support one Minecraft version at a time (typically the latest official release).

    • Protocol Support: While it targets a specific Minecraft version, the API allows for supporting multiple protocols simultaneously.
    • Versioning: A new minor version of the gophertunnel library is generally released when support for a new Minecraft version is added.
  3. How to use gophertunnel for Minecraft connections

    master
    To implement core Minecraft functionality like dialing a connection or starting a server, use the minecraft package. Detailed implementation examples are located within the minecraft package directory in the repository.
  4. Configure the proxy via config.toml

    master

    The proxy uses a config.toml file to define connection settings. If the file does not exist, the application will create a default one.

    Required structure:

    [Connection]
    LocalAddress = "0.0.0.0:19132"
    RemoteAddress = "remote.server.com:19132"
  5. Implement a Minecraft MITM Proxy

    master

    The main.go file demonstrates how to build a Man-in-the-Middle (MITM) proxy that forwards Minecraft players from a local address to a remote address.

    Key steps in the proxy lifecycle:

    1. Authentication: Use auth.RequestLiveToken() to obtain a token and auth.RefreshTokenSource(token) to create an oauth2.TokenSource.
    2. Status Provider: Initialize a minecraft.NewForeignStatusProvider using the remote address to handle status requests.
    3. Listening: Use minecraft.ListenConfig with a StatusProvider to start a listener on a specific protocol (e.g., "raknet") and local address.
    4. Connection Handling: For every accepted connection, use minecraft.Dialer to connect to the remote server, passing the TokenSource and the client's ClientData().
    5. Session Initialization: Synchronize the game state by calling conn.StartGame(serverConn.GameData()) on the client connection and serverConn.DoSpawn() on the server connection.
    6. Packet Forwarding: Run two concurrent loops to read packets from the client and write them to the server, and vice versa, ensuring minecraft.DisconnectError is handled to disconnect the client gracefully.
    // Simplified proxy logic flow
    // 1. Setup Listener
    p, _ := minecraft.NewForeignStatusProvider(remoteAddr)
    listener, _ := minecraft.ListenConfig{StatusProvider: p}.Listen("raknet", localAddr)
    
    // 2. Handle Connections
    for {
    	conn, _ := listener.Accept()
    	go func(c *minecraft.Conn) {
    		// 3. Dial Remote
    		serverConn, _ := minecraft.Dialer{
    			TokenSource: src,
    			ClientData:  c.ClientData(),
    		}.Dial("raknet", remoteAddr)
    
    		// 4. Initialize Game
    		_ = c.StartGame(serverConn.GameData())
    		_ = serverConn.DoSpawn()
    
    		// 5. Forward Packets (Client -> Server)
    		// ... loop conn.ReadPacket() -> serverConn.WritePacket(pk)
    
    		// 6. Forward Packets (Server -> Client)
    		// ... loop serverConn.ReadPacket() -> c.WritePacket(pk)
    	}(conn.(*minecraft.Conn))
    }