MinecraftForge/FML — pull request #257 by smith61 (2013-07-10 07:45:07+00:00)
Title: Add NetworkConnections for use over Minecraft channels

This is the complete rewrite of https://github.com/MinecraftForge/FML/pull/235. This version keeps very little similarities with the previous version.

Two things that are the same are PacketRepository and ModPacket. The only difference in this is the removal of RecycledPacket (may be readded later).

Unlike the previous version this is not built on top of the current Network APIs of FML. This is meant to replace the current API and as of now does not fully work. All the classes and methods are there to make it work it just needs to be feed Packet250CustomPayloads and notified when player's log in and out.

The reason I did not hook this in myself is because it does not work well with the current API and it makes it relatively hard to have both co-exist at the same time and that some of the classes maybe useful to current Forge packet handling methods and I expect a rewrite might be done there anyways. If a commit is needed to make it fully work it can easily be done.

Now on to the new power in this version. This adds several interfaces and classes to be used in the Network API.

NetworkConnection
----------------------------
This interface is there to abstract away how packets are sent over a connection. For all the mod knows the connection could be using Minecraft channels or over sockets. Most mods should be using this interface when they are sending and processing packets instead of the Minecraft specific connection ChannelNetworkConnection.

A NetworkConnection supports three operations. These are sending packets, registering PacketHandlers, and registering PacketRepositories. The last two allow you to change how packets are handled and what packets are read in on the connection without creating a new NetworkConnection. This can be used to better handle States in a NetworkConnection

ChannelNetworkConnection
---------------------------------------
This is a subclass of NetworkConnection that is Minecraft specific. It supports a few more operations such as getting the channel name and one way packet sending. Since the nature of how channel registration is set up, ChannelNetworkConnections supports both one-way and two-way network communication.

PacketHandler
---------------------
This interface is used to handle ModPackets that are read from a NetworkConnection. You can implement this interface yourself or use the helper class DelegatingPacketHandler which uses a much more friendly annotation based packet handling.

NetworkManager
------------------------
This is the main point you will be interacting from Minecraft mods. Each NetworkManager is bound to a Player instance and handles are connections for the player. This is where you will get and open ChannelNetworkConnections.There is no need to preregister any channel or packet handlers. When a player logs in you can grab their NetworkManager and open any channels you like. This allows for a lot of flexibility in your network.

These are the main classes that make up the Network API. I skipped over PacketRepository and ModPacket as they did not change in function from the previous version.

There are a couple of utility classes provided to help making NetworkConnection classes or for handling raw Minecraft packets. The two more useful ones are:

PacketSplitter
--------------------
This is a utility class for splitting and merging packets sent in Packet250CustomPayloads. It maintains it's own state and is not bound to any connection, but it is bound to a channel name.

AbstractNetworkConnection
----------------------------------------
This is the base class for helping to create NetworkConnections. It handles registration of PacketHandlers and PacketRepositories.

That wraps up the major changes and functionality of the Network API. I know it got rather lengthy but I wanted to explain it as clear as possible. If there are any questions or suggestions please ask.