NetworkChannel¶

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.

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.

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.

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.

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.

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.

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.
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.