NetworkChannel¶

open class NetworkChannel(id: ResourceLocation)

Manages the registration and sending of strongly-typed, serialization-backed network packets.

A single NetworkChannel can handle any number of server-bound and client-bound packet types. All packets are serialized with CBOR via kotlinx.serialization.

Packet classes must be Kotlin data classes annotated with @Serializable when registered via the reflective serverbound/clientbound overloads; pass an explicit KSerializer instead (see the two-argument-serializer overloads, or serverboundLazy) for a type that can't carry that annotation.

Example¶

val CHANNEL = NetworkChannel(Archie["main"])

@Serializable
data class SyncDataPacket(val value: Int)

// During mod init:
CHANNEL.clientbound(SyncDataPacket::class) { packet, ctx ->
    // handle on client
}
CHANNEL.register()

// Sending:
CHANNEL.toPlayer(player, SyncDataPacket(42))

Parameters¶

id: The unique ResourceLocation identifier for this channel.

Inheritors¶

ArchieNetworkChannel

Constructors¶

NetworkChannel¶

constructor(id: ResourceLocation)

Parameters

id: The unique ResourceLocation identifier for this channel.

Functions¶

clientbound¶

fun <T : Any> clientbound(klass: KClass<T>, handler: PacketHandler<T>)

Registers a client-bound packet type and its handler, decoding with klass's own @Serializable-generated KSerializer.

The handler is invoked on the client when the server sends a packet of class klass.

Parameters

T: The packet data class type.
klass: The KClass of the packet. Must be a data class with @Serializable.
handler: The handler invoked on the receiving side.

Throws

IllegalArgumentException: if klass is not a data class, lacks a serializer, or is already registered.

inline fun <T : Any> clientbound(noinline handler: PacketHandler<T>)

Registers a client-bound packet type and its handler, inferring the packet class from the reified type parameter T instead of requiring T::class to be passed explicitly.

Equivalent to clientbound(T::class, handler).

Parameters

T: The packet data class type.
handler: The handler invoked on the receiving side.

Throws

IllegalArgumentException: if T is not a data class, lacks a serializer, or is already registered.

fun <T : Any> clientbound(
    klass: KClass<T>, 
    serializer: KSerializer<T>, 
    handler: PacketHandler<T>
)

Registers a client-bound packet type and its handler with an explicit serializer, for a type that can't carry @Serializable. See the server-bound overload of the same shape for why this exists.

Throws

IllegalArgumentException: if klass is already registered.

register¶

fun register()

Registers this channel with the Architectury networking layer.

Must be called once during mod initialization (before any packets are sent or received). Both serverbound and clientbound handlers should be registered before calling this.

serverbound¶

fun <T : Any> serverbound(klass: KClass<T>, handler: PacketHandler<T>)

Registers a server-bound packet type and its handler, decoding with klass's own @Serializable-generated KSerializer.

The handler is invoked on the server when a client sends a packet of class klass.

Parameters

T: The packet data class type.
klass: The KClass of the packet. Must be a data class with @Serializable.
handler: The handler invoked on the receiving side.

Throws

IllegalArgumentException: if klass is not a data class, lacks a serializer, or is already registered.

inline fun <T : Any> serverbound(noinline handler: PacketHandler<T>)

Registers a server-bound packet type and its handler, inferring the packet class from the reified type parameter T instead of requiring T::class to be passed explicitly.

Equivalent to serverbound(T::class, handler).

Parameters

T: The packet data class type.
handler: The handler invoked on the receiving side.

Throws

IllegalArgumentException: if T is not a data class, lacks a serializer, or is already registered.

fun <T : Any> serverbound(
    klass: KClass<T>, 
    serializer: KSerializer<T>, 
    handler: PacketHandler<T>
)

Registers a server-bound packet type and its handler with an explicit serializer, for a type that can't carry @Serializable (e.g. a Kotlin object singleton with a hand-built KSerializer). The payload is always decoded before handler runs; use serverboundLazy instead when decoding must be conditional on something the handler checks first.

Throws

IllegalArgumentException: if klass is already registered.

serverboundLazy¶

fun <T : Any> serverboundLazy(
    klass: KClass<T>, 
    serializer: KSerializer<T>, 
    handler: (decode: () -> T, IPacketContext) -> Unit
)

Registers a server-bound packet type whose handler controls exactly when (or whether) the payload gets decoded, unlike serverbound (the two-argument-serializer overload), which always decodes before invoking its handler. Useful when decoding unconditionally would have a side effect that must stay conditional on something only the handler can check (e.g. a permission check that must happen before an edit is applied).

Throws

IllegalArgumentException: if klass is already registered.

toAllPlayers¶

fun <T : Any> toAllPlayers(vararg packets: T)

Sends one or more packets from the server to all connected players.

Parameters

packets: The packets to send.

Throws

IllegalArgumentException: if no packets are provided.
IllegalStateException: if called from the client side.

toNearPlayers¶

fun <T : Any> toNearPlayers(
    level: ServerLevel, 
    exclude: ServerPlayer? = null, 
    x: Double, 
    y: Double, 
    z: Double, 
    radius: Double, 
    vararg packets: T
)

Sends one or more packets to all players within radius blocks of the given coordinates in level, optionally excluding exclude.

Parameters

level: The ServerLevel to broadcast within.
exclude: A ServerPlayer to exclude, or null to include all nearby players.
x: The X coordinate of the broadcast origin.
y: The Y coordinate of the broadcast origin.
z: The Z coordinate of the broadcast origin.
radius: The broadcast radius in blocks.
packets: The packets to send.

Throws

IllegalArgumentException: if no packets are provided.

toPlayer¶

fun <T : Any> toPlayer(player: ServerPlayer, vararg packets: T)

Sends one or more packets from the server to a specific player.

Parameters

player: The target ServerPlayer.
packets: The packets to send. All must have been registered via clientbound.

Throws

IllegalArgumentException: if no packets are provided.

toPlayers¶

fun <T : Any> toPlayers(players: List<ServerPlayer>, vararg packets: T)

Sends one or more packets from the server to a list of players.

Parameters

players: The list of target ServerPlayers. A no-op if empty - skipped before createPayloads even runs, so this is also safe to call with no client loaded at all (a server-only GameTest run, or a dedicated server with nobody online), not just an empty nearby-players list on an otherwise-normal server.
packets: The packets to send.

Throws

IllegalArgumentException: if no packets are provided.

toPlayersInDimension¶

fun <T : Any> toPlayersInDimension(level: ServerLevel, vararg packets: T)

Sends one or more packets to all players currently in the given level (dimension).

Parameters

level: The ServerLevel whose players should receive the packets.
packets: The packets to send.

Throws

IllegalArgumentException: if no packets are provided.

toPlayersTrackingChunk¶

fun <T : Any> toPlayersTrackingChunk(
    level: ServerLevel, 
    pos: ChunkPos, 
    vararg packets: T
)

Sends one or more packets to all players tracking chunk pos in level.

Parameters

level: The ServerLevel containing the chunk.
pos: The ChunkPos of the chunk being tracked.
packets: The packets to send.

toPlayersTrackingEntity¶

fun <T : Any> toPlayersTrackingEntity(
    entity: Entity, 
    self: Boolean = false, 
    vararg packets: T
)

Sends one or more packets to all players tracking entity (i.e., the entity is loaded on their client).

Parameters

entity: The entity being tracked.
self: Whether to also send the packet to the entity itself if it is a ServerPlayer.
packets: The packets to send.

Throws

IllegalArgumentException: if no packets are provided.
IllegalStateException: if called from the client side.

toServer¶

fun <T : Any> toServer(vararg packets: T)

Sends one or more packets from the client to the server.

Parameters

packets: The packets to send. All must have been registered via serverbound.

Throws

IllegalArgumentException: if no packets are provided.
IllegalStateException: if a packet type was not registered.