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-migrationTo migrate, do one of these steps:
- Remove the
--transport QUICargument. - 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-migrationIf you see this error, or if the server cannot bind with quiche, do these steps:
- Set
--transport QUICagain so that the server can start. - 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 transportIf 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:
| Deprecated | Replacement |
|---|---|
io.netty.handler.codec.quic.QuicStreamPriority | com.hypixel.hytale.protocol.io.StreamPriority |
StreamManager.registerHandler(StreamType, StreamHandlerFactory, QuicStreamPriority) | StreamManager.registerHandler(StreamType, StreamHandlerFactory, StreamPriority) |
StreamManager.getStreamPriority(StreamType) | StreamManager.getPriority(StreamType) |
StreamManager.GAME_STREAM_PRIORITY | StreamManager.GAME_PRIORITY |
StreamManager.DEFAULT_AUXILIARY_PRIORITY | StreamManager.AUXILIARY_PRIORITY |
PacketHandler.DEFAULT_STREAM_PRIORITIES | PacketHandler.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 exampleNettyUtil,HytaleChannelInitializer, andRateLimitHandler. - All classes in
com.hypixel.hytale.protocol.io.netty:PacketDecoder,PacketEncoder, andProtocolUtil. com.hypixel.hytale.server.core.io.transport.QUICTransport.com.hypixel.hytale.server.core.io.stream.PendingStreamHandlerandStreamConnectionHandlerAdapter.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 aChannelConnectionon both transports. - To read the connection details, call
ChannelConnectionmethods such asgetSniHostname()andgetClientCertificate(). - 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.
