HytaleDocs
Server

Migrating off the netty transport

How to move servers and plugins from the deprecated netty transport to the quiche transport before 0.9.0.

The server has two network transports:

  • Quiche is the default transport.
  • Netty is the legacy transport. It is deprecated and will be removed in 0.9.0.

Players do not need to do anything. Server hosts and plugin authors must make the changes on this page before they update to 0.9.0.

Server hosts

Check your launch arguments

The server selects its transport with the --transport (or -t) argument. If you do not set this argument, the server uses quiche.

If your launch scripts contain --transport QUIC, the server uses netty. At startup it logs this warning:

The QUIC transport is deprecated and will be removed in 0.9.0. Use --transport QUICHE instead. See https://docs.hytale.com/server/netty-transport-migration

To migrate, do one of these steps:

  • Remove the --transport QUIC argument.
  • Replace it with --transport QUICHE.

Quiche supports these platforms:

  • Linux x64
  • macOS arm64
  • Windows x64

If you set --transport QUICHE on a platform that quiche does not support, the server stops at startup. It logs this error:

Quiche has no native library for <platform>. Use --transport QUIC. See https://docs.hytale.com/server/netty-transport-migration

If you see this error, or if the server cannot bind with quiche, do these steps:

  1. Set --transport QUIC again so that the server can start.
  2. Submit a bug report on the bug reports page. Include your operating system and CPU architecture.

Platforms without quiche

Quiche uses a native library. If no quiche native library exists for your platform, the server uses netty automatically. It logs this error:

Quiche has no native library for <platform>, so the server uses the QUIC transport

If you see this error, the server cannot start on this platform in 0.9.0. Submit a bug report on the bug reports page so that we can add support for your platform. Include the platform name from the error message.

Plugin authors

The deprecated types and members have @Deprecated(forRemoval = true). Your plugin still compiles and runs on the current version. Your compiler shows a removal warning for each use. Fix each warning before 0.9.0.

Stream priorities

Netty's QuicStreamPriority is replaced by com.hypixel.hytale.protocol.io.StreamPriority. It is a record with two components:

  • urgency: the priority from 0 to 127. A lower value has a higher priority.
  • incremental: whether the stream data can interleave with other streams at the same urgency.

Replace each deprecated member with its replacement:

DeprecatedReplacement
io.netty.handler.codec.quic.QuicStreamPrioritycom.hypixel.hytale.protocol.io.StreamPriority
StreamManager.registerHandler(StreamType, StreamHandlerFactory, QuicStreamPriority)StreamManager.registerHandler(StreamType, StreamHandlerFactory, StreamPriority)
StreamManager.getStreamPriority(StreamType)StreamManager.getPriority(StreamType)
StreamManager.GAME_STREAM_PRIORITYStreamManager.GAME_PRIORITY
StreamManager.DEFAULT_AUXILIARY_PRIORITYStreamManager.AUXILIARY_PRIORITY
PacketHandler.DEFAULT_STREAM_PRIORITIESPacketHandler.DEFAULT_CHANNEL_PRIORITIES
priority.isIncremental()priority.incremental()

Before:

import io.netty.handler.codec.quic.QuicStreamPriority;

StreamManager.getInstance().registerHandler(
    StreamType.Voice,
    MyStreamHandler::new,
    new QuicStreamPriority(127, true)
);

After:

import com.hypixel.hytale.protocol.io.StreamPriority;

StreamManager.getInstance().registerHandler(
    StreamType.Voice,
    MyStreamHandler::new,
    new StreamPriority(127, true)
);

To change the priority of a stream at runtime, call ChannelConnection.updateStreamPriority(StreamPriority).

Netty pipeline classes

These classes work only on the netty transport. They will be removed in 0.9.0 with no replacement:

  • All classes in com.hypixel.hytale.server.core.io.netty, for example NettyUtil, HytaleChannelInitializer, and RateLimitHandler.
  • All classes in com.hypixel.hytale.protocol.io.netty: PacketDecoder, PacketEncoder, and ProtocolUtil.
  • com.hypixel.hytale.server.core.io.transport.QUICTransport.
  • com.hypixel.hytale.server.core.io.stream.PendingStreamHandler and StreamConnectionHandlerAdapter.
  • TransportType.QUIC.

If your plugin uses one of these classes, use the transport-independent API instead:

  • To get a connection, call PacketHandler.getChannel(). It returns a ChannelConnection on both transports.
  • To read the connection details, call ChannelConnection methods such as getSniHostname() and getClientCertificate().
  • To close a connection, call ChannelConnection.closeApplicationConnection(...).

Do not cast a ChannelConnection to a netty type. On the quiche transport, the cast fails.

Netty types that stay

Some classes outside the transport still use netty's ByteBuf, for example PacketIO and VarInt. Both transports use these classes, so they are not deprecated.

On this page