API Usage

API Usage

Everything below is called on the *portaldf.Portal returned by Enable/EnableWithLogger/New — see Installation. All of it works whether or not you're also using the built-in Commands.

import (
	"github.com/google/uuid"
	"github.com/MEMOxiiii/PortalDF"
	"github.com/MEMOxiiii/PortalDF/packet"
)

Transfer a player

portal.TransferPlayer(playerUUID, "SkyWars1", func(uid uuid.UUID, status byte, err string) {
	if status == packet.TransferResponseSuccess {
		log.Info("Player transferred successfully")
	}
})

status is one of:

Constant	Value	Meaning
TransferResponseSuccess	0	Player transferred successfully
TransferResponseServerNotFound	1	Target server not found on proxy
TransferResponseAlreadyOnServer	2	Player is already on that server
TransferResponsePlayerNotFound	3	Player could not be found
TransferResponseError	4	An error occurred — check the err string

List all servers

portal.RequestServerList(func(servers []packet.ServerEntry) {
	for _, s := range servers {
		log.Info("Server", "name", s.Name, "players", s.PlayerCount)
	}
})

Includes every registered server, even ones currently failing the proxy's health check.

Find a player anywhere on the network

portal.FindPlayer(uuid.Nil, "PlayerName", func(uid uuid.UUID, name string, online bool, server string) {
	if online {
		log.Info("Player found", "name", name, "server", server)
	}
})

Pass uuid.Nil and a name to search by name, or a real UUID (with an empty name) to search by UUID.

Player info (XUID, IP)

portal.RequestPlayerInfo(playerUUID, func(uid uuid.UUID, status byte, xuid string, address string) {
	log.Info("Player info", "xuid", xuid, "address", address)
})

Latency updates

portal.SetLatencyHandler(func(uid uuid.UUID, latency int64) {
	log.Info("Player latency update", "uuid", uid, "latency_ms", latency)
})

Called whenever the proxy reports a player's latency (controlled by the proxy's own player_latency.* config — see Portal's Configuration page).

Stale-session cleanup

portal.SetDisconnectPlayerHandler(func(playerName string) {
	log.Info("Disconnecting stale session", "player", playerName)
})

Called when the proxy is about to transfer a player in to this server and wants any existing local session for them cleaned up first (e.g. left over from a previous, interrupted connection). Already wired up automatically by portalcmd.Register/Enable — only set this yourself if you're not using either.

Draining

portal.SetDraining(true)

Marks this server as draining, so the proxy's load balancers stop routing new players to it — already-connected players are unaffected. The standard way to take a server out of rotation ahead of a planned restart.

Connection state

portal.Connected() // bool
portal.ServerName() // string — the name this instance registered as

Protocol

PortalDF implements Portal's binary TCP socket protocol directly: a 4-byte little-endian length prefix, a 2-byte little-endian packet ID header, and payloads serialized with gophertunnel's protocol.Reader/Writer. See Portal's own Socket Protocol page for the full wire format if you're debugging at that level.