dev.polymodloader.api.network

Generated

This page is generated from the source's Javadoc by ./gradlew apiReference. Do not edit it; fix the source comment and generate it again.

Type	Kind	Description
ClientPayloadHandler	functional interface	Handles a payload the server sent to this client.
ConfigurationExchange	interface	A question the server asks each joining client before the player enters the world, during the game's configuration phase: to check versions, agree on settings, or send data the client needs first.
ConfigurationExchange.Answer	functional interface	The client's reply.
ConfigurationExchange.Check	functional interface	The server's decision.
ConfigurationExchange.Request	functional interface	The server's message for a joining player.
NetworkRegistrar	interface	Declares a mod's network channels.
PayloadChannel	interface	A two-way channel for one payload type.
PayloadCodec	interface	Converts a payload to and from bytes.
PayloadReader	interface	Reads payload values written by PayloadWriter.
PayloadWriter	interface	Writes payload values in big-endian order.
ServerPayloadHandler	functional interface	Handles a payload a client sent to the server.

ClientPayloadHandler

functional interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface ClientPayloadHandler<T>

Handles a payload the server sent to this client.

receive(T)

void receive(T payload)

Since 0.1.0-alpha.4 or earlier

Called on the client thread.

Parameter	Type	Description
payload	T	—

ConfigurationExchange

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface ConfigurationExchange<T>

A question the server asks each joining client before the player enters the world, during the game's configuration phase: to check versions, agree on settings, or send data the client needs first. The player joins only after the exchange finishes, and the server may refuse the connection.

• The server's serverRequest decides what to send to the player, or skips them.
• The client's clientAnswer replies.
• The server's serverCheck sees the reply, or nothing if the client did not answer within timeoutTicks (a client without the mod never answers), and lets the player in or refuses with a message.

Set the server parts in a common entrypoint and the client part in a client entrypoint. Without a serverCheck, a player whose client gives no answer is refused. Server parts run on the server thread, the client part on the client thread.

id()

ResourceId id()

Since 0.1.0-alpha.4 or earlier

The exchange's ID, <mod id>:<path>.

Returns ResourceId

serverRequest(ConfigurationExchange.Request<T>)

ConfigurationExchange<T> serverRequest(ConfigurationExchange.Request<T> request)

Since 0.1.0-alpha.4 or earlier

What the server sends to each joining player; without it the exchange is skipped.

Parameter	Type	Description
request	ConfigurationExchange.Request<T>	—

Returns ConfigurationExchange<T>

clientAnswer(ConfigurationExchange.Answer<T>)

ConfigurationExchange<T> clientAnswer(ConfigurationExchange.Answer<T> answer)

Since 0.1.0-alpha.4 or earlier

How the client answers; without it the client does not answer.

Parameter	Type	Description
answer	ConfigurationExchange.Answer<T>	—

Returns ConfigurationExchange<T>

serverCheck(ConfigurationExchange.Check<T>)

ConfigurationExchange<T> serverCheck(ConfigurationExchange.Check<T> check)

Since 0.1.0-alpha.4 or earlier

Whether the server lets the player in after the client's answer.

Parameter	Type	Description
check	ConfigurationExchange.Check<T>	—

Returns ConfigurationExchange<T>

timeoutTicks(int)

ConfigurationExchange<T> timeoutTicks(int ticks)

Since 0.1.0-alpha.4 or earlier

How long the server waits for the answer, in ticks; 100 (5 seconds) by default.

Parameter	Type	Description
ticks	int	—

Returns ConfigurationExchange<T>

Throws IllegalArgumentException — outside 1–1200

ConfigurationExchange.Answer

functional interface · Since 0.1.0-alpha.4 or earlier

public static interface Answer<T>

The client's reply.

answer(T)

T answer(T request)

Since 0.1.0-alpha.4 or earlier

The reply to the server's request.

Parameter	Type	Description
request	T	—

Returns T

ConfigurationExchange.Check

functional interface · Since 0.1.0-alpha.4 or earlier

public static interface Check<T>

The server's decision.

check(UUID, String, Optional<T>)

Optional<String> check(UUID playerId, String playerName, Optional<T> reply)

Since 0.1.0-alpha.4 or earlier

Empty to let the player in, or the message shown to them when the connection is refused.

Parameter	Type	Description
playerId	UUID	the player's UUID
playerName	String	the player's name
reply	Optional<T>	the client's answer, or empty when it did not answer in time or the answer could not be decoded

Returns Optional<String>

ConfigurationExchange.Request

functional interface · Since 0.1.0-alpha.4 or earlier

public static interface Request<T>

The server's message for a joining player.

request(UUID, String)

Optional<T> request(UUID playerId, String playerName)

Since 0.1.0-alpha.4 or earlier

The message for player playerName, or empty to skip the exchange for them.

Parameter	Type	Description
playerId	UUID	the player's UUID
playerName	String	the player's name

Returns Optional<T>

NetworkRegistrar

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface NetworkRegistrar

Declares a mod's network channels. A channel ID is <mod id>:<path> and carries one payload type in both directions.

When: inside common entrypoints, so both sides know the channel. Payloads on channels the receiver does not know are dropped by the game, like any unknown custom payload.

channel(String, PayloadCodec<T>)

<T> PayloadChannel<T> channel(String path, PayloadCodec<T> codec)

Since 0.1.0-alpha.4 or earlier

Declares a channel.

Parameter	Type	Description
path	String	—
codec	PayloadCodec<T>	—

Returns PayloadChannel<T>

Throws IllegalArgumentException — for an invalid or already used path (POLY-NETWORK-001)

Throws IllegalStateException — after registration closed (POLY-NETWORK-002)

configurationExchange(String, PayloadCodec<T>)

<T> ConfigurationExchange<T> configurationExchange(String path, PayloadCodec<T> codec)

Since 0.1.0-alpha.4 or earlier

Declares configuration exchange <mod id>:<path>: a question the server asks each joining client before the player enters the world. Declare it in the common entrypoint, on both sides, and set its parts with the returned handle.

Parameter	Type	Description
path	String	—
codec	PayloadCodec<T>	—

Returns ConfigurationExchange<T>

Throws IllegalArgumentException — for an invalid or used path (POLY-NETWORK-001)

PayloadChannel

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface PayloadChannel<T>

A two-way channel for one payload type. Encoded payloads are limited to 32 KiB towards the server and 1 MiB towards clients; larger payloads throw IllegalArgumentException (POLY-NETWORK-003).

id()

ResourceId id()

Since 0.1.0-alpha.4 or earlier

The channel ID.

Returns ResourceId

onServerReceive(ServerPayloadHandler<T>)

void onServerReceive(ServerPayloadHandler<T> handler)

Since 0.1.0-alpha.4 or earlier

Sets what the server does with payloads from clients. Runs on the server thread; sender is valid only during the call. Replaces an earlier handler.

Parameter	Type	Description
handler	ServerPayloadHandler<T>	—

onClientReceive(ClientPayloadHandler<T>)

void onClientReceive(ClientPayloadHandler<T> handler)

Since 0.1.0-alpha.4 or earlier

Sets what the client does with payloads from the server. Runs on the client thread.

Parameter	Type	Description
handler	ClientPayloadHandler<T>	—

sendToPlayer(PlayerView, T)

void sendToPlayer(PlayerView player, T payload)

Since 0.1.0-alpha.4 or earlier

Sends a payload to one player. Call on the server thread.

Parameter	Type	Description
player	PlayerView	—
payload	T	—

Throws IllegalStateException — when player is not a server-side player

sendToServer(T)

void sendToServer(T payload)

Since 0.1.0-alpha.4 or earlier

Sends a payload to the server. Call on the client thread while connected.

Parameter	Type	Description
payload	T	—

Throws IllegalStateException — on a dedicated server or when not connected

PayloadCodec

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface PayloadCodec<T>

Converts a payload to and from bytes. decode must read exactly what encode wrote. Runs on network threads: keep it free of game state.

encode(T, PayloadWriter)

void encode(T value, PayloadWriter out)

Since 0.1.0-alpha.4 or earlier

Writes value.

Parameter	Type	Description
value	T	—
out	PayloadWriter	—

decode(PayloadReader)

T decode(PayloadReader in)

Since 0.1.0-alpha.4 or earlier

Reads a value written by encode.

Parameter	Type	Description
in	PayloadReader	—

Returns T

string()

static PayloadCodec<String> string()

Since 0.1.0-alpha.4 or earlier

A codec for a single UTF-8 string.

Returns PayloadCodec<String>

PayloadReader

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface PayloadReader

Reads payload values written by PayloadWriter. Reading past the end throws IllegalStateException, which drops the payload (POLY-NETWORK-004).

readBoolean()

boolean readBoolean()

Since 0.1.0-alpha.4 or earlier

Reads a boolean.

Returns boolean

readInt()

int readInt()

Since 0.1.0-alpha.4 or earlier

Reads an int.

Returns int

readLong()

long readLong()

Since 0.1.0-alpha.4 or earlier

Reads a long.

Returns long

readDouble()

double readDouble()

Since 0.1.0-alpha.4 or earlier

Reads a double.

Returns double

readString()

String readString()

Since 0.1.0-alpha.4 or earlier

Reads a string.

Returns String

readBytes()

byte[] readBytes()

Since 0.1.0-alpha.4 or earlier

Reads a byte array.

Returns byte[]

remaining()

int remaining()

Since 0.1.0-alpha.4 or earlier

Bytes not read yet.

Returns int

PayloadWriter

interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface PayloadWriter

Writes payload values in big-endian order.

writeBoolean(boolean)

PayloadWriter writeBoolean(boolean value)

Since 0.1.0-alpha.4 or earlier

Writes a boolean as one byte.

Parameter	Type	Description
value	boolean	—

Returns PayloadWriter

writeInt(int)

PayloadWriter writeInt(int value)

Since 0.1.0-alpha.4 or earlier

Writes a 4-byte int.

Parameter	Type	Description
value	int	—

Returns PayloadWriter

writeLong(long)

PayloadWriter writeLong(long value)

Since 0.1.0-alpha.4 or earlier

Writes an 8-byte long.

Parameter	Type	Description
value	long	—

Returns PayloadWriter

writeDouble(double)

PayloadWriter writeDouble(double value)

Since 0.1.0-alpha.4 or earlier

Writes an 8-byte double.

Parameter	Type	Description
value	double	—

Returns PayloadWriter

writeString(String)

PayloadWriter writeString(String value)

Since 0.1.0-alpha.4 or earlier

Writes a length-prefixed UTF-8 string (at most 32767 characters).

Parameter	Type	Description
value	String	—

Returns PayloadWriter

writeBytes(byte[])

PayloadWriter writeBytes(byte[] value)

Since 0.1.0-alpha.4 or earlier

Writes a length-prefixed byte array.

Parameter	Type	Description
value	byte[]	—

Returns PayloadWriter

ServerPayloadHandler

functional interface · Stability PREVIEW · Since 0.1.0-alpha.4 or earlier

public interface ServerPayloadHandler<T>

Handles a payload a client sent to the server. Validate it: clients are not trusted.

receive(T, PlayerView)

void receive(T payload, PlayerView sender)

Since 0.1.0-alpha.4 or earlier

Called on the server thread.

Parameter	Type	Description
payload	T	—
sender	PlayerView	—