Minecraft Forums

Handling Packets in 1.7.x and up - Making the SimpleNetworkWrapper Not So Simple

Note about terminology: I will be using the terms 'packet' and 'message' interchangeably in this tutorial.

Today, I will show you how to make a 'convenient-and-annoyance-free-but-possibly-too-complicated' version of the SimpleNetworkWrapper. If you prefer a simple solution, please see this tutorial by diesieben07 - he'll have you up and running with packets in no time. You should check out that tutorial anyway if you are going to follow along, as it provides an excellent explanation of everything you need to know about the SimpleNetworkWrapper.

IMPORTANT: The solutions presented in this tutorial are wholly unnecessary for a functioning packet handling system - they are purely stylistic. Take this tutorial with a grain of salt - it's one of those projects that was more a 'can I do this?' than 'should I do this?', and since I did it, I figured heck, maybe someone else will get a kick out of this.

Now, why would anyone want to do something different when it's so simple? Well, there were a couple points about the process that annoyed me (in comparison to the good old days when everything was better :P) and I wanted to fix:

1. There isn't an EntityPlayer passed directly to the onMessage method - when nearly every packet sent is going to want to reference either a player or world object, this seemed like a huge oversight and inconvenience to me, even though it CAN be retrieved (and stored) in one line, why should we have to do that when it can just be passed as a parameter like it always has been?

2. There is no indication of which side you are on when handling the message - you must either remember to which side you registered it, go check, or check the MessageContext#side field, all of which seem kind of lame, whereas before, at least the way I had it set up, the side you were on was embedded in the name of the handling method. Clear, concise, no chance of getting confused and using Minecraft.getMinecraft() for something when on the server. It was awesome.

3. Registering requires a byte discriminator - wait, what? Why couldn't it just automatically increment each time a message is registered, since they are all registered per mod (i.e. everyone gets to start at 0) ? What a useless parameter to provide, and boy, is that sure annoying.

Ok... so maybe those points aren't that convincing to you, and they really aren't that big of a deal. If you find that's the case, then stop now and use the earlier tutorial. If, on the other hand, the above points irk you to no end and you really wish you could do something about them, then here we go! Please remember, you can always change your mind later if you decide that the extra work isn't worth it

Step 1: Create a PacketDispatcher

 /**
 * 
 * This class will house the SimpleNetworkWrapper instance, which I will name 'dispatcher',
 * as well as give us a logical place from which to register our packets. These two things
 * could be done anywhere, however, even in your Main class, but I will be adding other
 * functionality (see below) that gives this class a bit more utility. 
 * 
 * While unnecessary, I'm going to turn this class into a 'wrapper' for SimpleNetworkWrapper
 * so that instead of writing "PacketDispatcher.dispatcher.{method}" I can simply write
 * "PacketDispatcher.{method}" All this does is make it quicker to type and slightly shorter;
 * if you do not care about that, then make the 'dispatcher' field public instead of private,
 * or, if you do not want to add a new class just for one field and one static method that
 * you could put anywhere, feel free to put them wherever.
 * 
 * For further convenience, I have also added two extra sendToAllAround methods: one which
 * takes an EntityPlayer and one which takes coordinates.
 *
 */
public class PacketDispatcher
{
 // a simple counter will allow us to get rid of 'magic' numbers used during packet registration
 private static byte packetId = 0;
 
 /**
 * The SimpleNetworkWrapper instance is used both to register and send packets.
 * Since I will be adding wrapper methods, this field is private, but you should
 * make it public if you plan on using it directly.
 */
 private static final SimpleNetworkWrapper dispatcher = NetworkRegistry.INSTANCE.newSimpleChannel(TutorialMain.MOD_ID);

 /**
 * Call this during pre-init or loading and register all of your packets (messages) here
 */
 public static final void registerPackets() {
 // Using an incrementing field instead of hard-coded numerals, I don't need to think
 // about what number comes next or if I missed on should I ever rearrange the order
 // of registration (for instance, if you wanted to alphabetize them... yeah...)
 // It's even easier if you create a convenient 'registerMessage' method:
 PacketDispatcher.registerMessage(OpenGuiMessage.OpenGuiMessageHandler.class, OpenGuiMessage.class, Side.SERVER);
 PacketDispatcher.registerMessage(SyncPlayerPropsMessage.SyncPlayerPropsMessageHandler.class, SyncPlayerPropsMessage.class, Side.CLIENT);
 
 // If you don't want to make a 'registerMessage' method, you can do it directly:
 //PacketDispatcher.dispatcher.registerMessage(OpenGuiMessage.OpenGuiMessageHandler.class, OpenGuiMessage.class, packetId++, Side.SERVER);
 //PacketDispatcher.dispatcher.registerMessage(SyncPlayerPropsMessage.SyncPlayerPropsMessageHandler.class, SyncPlayerPropsMessage.class, packetId++, Side.CLIENT);
 }

 /**
 * Registers a message and message handler
 */
 private static final void registerMessage(Class handlerClass, Class messageClass, Side side) {
 PacketDispatcher.dispatcher.registerMessage(handlerClass, messageClass, packetId++, side);
 }

 //========================================================//
 // The following methods are the 'wrapper' methods; again,
 // this just makes sending a message slightly more compact
 // and is purely a matter of stylistic preference
 //========================================================//
 
 /**
 * Send this message to the specified player.
 * See {@link SimpleNetworkWrapper#sendTo(IMessage, EntityPlayerMP)}
 */
 public static final void sendTo(IMessage message, EntityPlayerMP player) {
 PacketDispatcher.dispatcher.sendTo(message, player);
 }

 /**
 * Send this message to everyone within a certain range of a point.
 * See {@link SimpleNetworkWrapper#sendToDimension(IMessage, NetworkRegistry.TargetPoint)}
 */
 public static final void sendToAllAround(IMessage message, NetworkRegistry.TargetPoint point) {
 PacketDispatcher.dispatcher.sendToAllAround(message, point);
 }

 /**
 * Sends a message to everyone within a certain range of the coordinates in the same dimension.
 */
 public static final void sendToAllAround(IMessage message, int dimension, double x, double y, double z, 

double range) {
 PacketDispatcher.sendToAllAround(message, new NetworkRegistry.TargetPoint(dimension, x, y, z, 

range));
 }

 /**
 * Sends a message to everyone within a certain range of the player provided.
 */
 public static final void sendToAllAround(IMessage message, EntityPlayer player, double range) {
 PacketDispatcher.sendToAllAround(message, player.worldObj.provider.dimensionId, player.posX, 

player.posY, player.posZ, range);
 }

 /**
 * Send this message to everyone within the supplied dimension.
 * See {@link SimpleNetworkWrapper#sendToDimension(IMessage, int)}
 */
 public static final void sendToDimension(IMessage message, int dimensionId) {
 PacketDispatcher.dispatcher.sendToDimension(message, dimensionId);
 }

 /**
 * Send this message to the server.
 * See {@link SimpleNetworkWrapper#sendToServer(IMessage)}
 */
 public static final void sendToServer(IMessage message) {
 PacketDispatcher.dispatcher.sendToServer(message);
 }
}

Step 2: Create an AbstractMessage class

 // the base class:
public abstract class AbstractMessageHandler<T extends IMessage> implements IMessageHandler <T, IMessage>
// class for messages sent to and handled on the client:
public abstract class AbstractClientMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>
// class for messages sent to and handled on the server:
public abstract class AbstractServerMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

 /**
 * 
 * Syntax for extending this class is "public class YourMessageHandler extends AbstractMessageHandler"
 * 
 * I prefer to have an EntityPlayer readily available when handling packets, as well as to
 * know which side I'm on without having to check every time, so I handle those operations
 * here and pass off the rest of the work to abstract methods to be handled in each sub-class.
 * 
 * We do not want to have to implement client handling for server side messages (and vice-versa),
 * however, so we will abstractify even further, as well as create separate packages to organize
 * our client vs. server messages. If you only have a few packets, you may opt not to, but once
 * you have more than a handful, keeping them separate makes it easier to remember on which side
 * to register, which side you can send to, and so on.
 *
 */
public abstract class AbstractMessageHandler<T extends IMessage> implements IMessageHandler <T, IMessage>

 // In your server proxy (mine is named CommonProxy):
/**
 * Returns a side-appropriate EntityPlayer for use during message handling
 */
public EntityPlayer getPlayerEntity(MessageContext ctx) {
 return ctx.getServerHandler().playerEntity;
}

// In your client proxy:
@Override
public EntityPlayer getPlayerEntity(MessageContext ctx) {
 // Note that if you simply return 'Minecraft.getMinecraft().thePlayer',
 // your packets will not work because you will be getting a client
 // player even when you are on the server! Sounds absurd, but it's true.

 // Solution is to double-check side before returning the player:
 return (ctx.side.isClient() ? Minecraft.getMinecraft().thePlayer : super.getPlayerEntity(ctx));
}

 /**
 * 
 * This is just a convenience class that will prevent the server-side message handling
 * method from appearing in our client message handler classes.
 *
 */
public abstract class AbstractClientMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

 /**
 * 
 * This is just a convenience class that will prevent the client-side message handling
 * method from appearing in our server message handler classes.
 *
 */
public abstract class AbstractServerMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

 private static final void registerMessage(Class<? extends IMessageHandler<REQ, REPLY>> handlerClass, Class<REQ>  messageClass) {
 Side side = AbstractClientMessageHandler.class.isAssignableFrom(handlerClass) ? Side.CLIENT : Side.SERVER;
 PacketDispatcher.dispatcher.registerMessage(handlerClass, messageClass, packetId++, side);
}

Step 3: Real Examples

 // I send this packet whenever the player joins the world, specifically from ExtendedPlayer#loadProxyData:
PacketDispatcher.sendTo(new SyncPlayerPropsMessage(player), (EntityPlayerMP) player);

/**
 * 
 * A packet to send ALL data stored in your extended properties to the client.
 * This is handy if you only need to send your data once per game session or
 * all of your data needs to be synchronized together; it's also handy while
 * first starting, since you only need one packet for everything - however,
 * you should NOT use such a packet in your final product!!!
 * 
 * Each packet should handle one thing and one thing only, in order to minimize
 * network traffic as much as possible. There is no point sending 20+ fields'
 * worth of data when you just need the current mana amount; conversely, it's
 * foolish to send 20 packets for all the data when the player first loads, when
 * you could send it all in one single packet.
 * 
 * TL;DR - make separate packets for each piece of data, and one big packet for
 * those times when you need to send everything.
 *
 */
public class SyncPlayerPropsMessage implements IMessage
// remember - the IMessageHandler will be implemented as a static inner class
{
 // Previously, we've been writing each field in our properties one at a time,
 // but that is really annoying, and we've already done it in the save and load
 // NBT methods anyway, so here's a slick way to efficiently send all of your
 // extended data, and no matter how much you add or remove, you'll never have
 // to change the packet / synchronization of your data.

 // this will store our ExtendedPlayer data, allowing us to easily read and write
 private NBTTagCompound data;

 // The basic, no-argument constructor MUST be included to use the new automated handling
 public SyncPlayerPropsMessage() {}

 // We need to initialize our data, so provide a suitable constructor:
 public SyncPlayerPropsMessage(EntityPlayer player) {
 // create a new tag compound
 data = new NBTTagCompound();
 // and save our player's data into it
 ExtendedPlayer.get(player).saveNBTData(data);
 }

 @Override
 public void fromBytes(ByteBuf buffer) {
 // luckily, ByteBufUtils provides an easy way to read the NBT
 data = ByteBufUtils.readTag(buffer);
 }

 @Override
 public void toBytes(ByteBuf buffer) {
 // ByteBufUtils provides a convenient method for writing the compound
 ByteBufUtils.writeTag(buffer, data);
 }

/**
 * Remember: this class MUST be static or you will crash
 *
 * Don't forget to add as well - it is required
 */
public static class Handler extends AbstractClientMessageHandler<SyncPlayerPropsMessage> {
 // the fruits of our labor: we immediately know from the method name that we are handling
 // a message on the client side, and we have our EntityPlayer right there ready for use. Awesome.
 @Override
 public IMessage handleClientMessage(EntityPlayer player, SyncPlayerPropsMessage message, MessageContext ctx) {
 // now we can just load the NBTTagCompound data directly; one and done, folks
 ExtendedPlayer.get(player).loadNBTData(message.data);
 return null;
 }
 
 // Note here that we don't (and can't) implement the handleServerMessage method
 // since we extended AbstractClientMessage. This is exactly what we want.
 }
}

 // sent using the following code from KeyInputEvent:
PacketDispatcher.sendToServer(new OpenGuiMessage(TutorialMain.GUI_CUSTOM_INV));

/**
 * If you are going with the more simple route, the only difference is your inner handler class signature
 * will look like this:
 *
 * public static class Handler implements IMessageHandler<OpenGuiMessage, IMessage>
 *
 * and the only method will be:
 *
 * public IMessage onMessage(OpenGuiMessage, MessageContext)
 *
 * Note that you can't immediately tell what side you are supposed to be on just from looking at the method,
 * and you have to do some work to get the player if you want it. But we fixed all that xD
 */
public class OpenGuiMessage implements IMessage {
 // this will store the id of the gui to open
 private int id;

 // The basic, no-argument constructor MUST be included to use the new automated handling
 public OpenGuiMessage() {}

 // if there are any class fields, be sure to provide a constructor that allows
 // for them to be initialized, and use that constructor when sending the packet
 public OpenGuiMessage(int id) {
 this.id = id;
 }

 @Override
 public void fromBytes(ByteBuf buffer) {
 // basic Input/Output operations, very much like DataInputStream
 id = buffer.readInt();
 }

 @Override
 public void toBytes(ByteBuf buffer) {
 // basic Input/Output operations, very much like DataOutputStream
 buffer.writeInt(id);
 }
 
public static class Handler extends AbstractServerMessageHandler<OpenGuiMessage> {
 @Override
 public IMessage handleServerMessage(EntityPlayer player, OpenGuiMessage message, 
MessageContext ctx) {
 // because we sent the gui's id with the packet, we can handle all cases with one line:
 player.openGui(TutorialMain.instance, message.id, player.worldObj, (int) player.posX, (int) player.posY, (int) player.posZ);
 return null;
 }
 }
}

Bi-Directional Packets

 /**
 * For messages which can be sent to either Side
 */
public abstract class AbstractBiMessageHandler<T extends IMessage> extends AbstractMessageHandler<T> {

}

 /**
 * Registers a message and message handler on both sides
 * @param handlerClass Must extend {@link AbstractBiMessageHandler} 
 * @param messageClass must implement {@link IMessage}
 */
private static final void registerBiMessage(Class handlerClass, Class messageClass) {
 if (AbstractBiMessageHandler.class.isAssignableFrom(handlerClass)) {
 PacketDispatcher.dispatcher.registerMessage(handlerClass, messageClass, packetId, Side.CLIENT);
 PacketDispatcher.dispatcher.registerMessage(handlerClass, messageClass, packetId++, Side.SERVER);
 } else {
 throw new IllegalArgumentException("Cannot register " + handlerClass.getName() + " on both sides - must extend AbstractBiMessageHandler!");
 }
}

 registerBiMessage(PlaySoundPacket.Handler.class, PlaySoundPacket.class);

// Sound packet handler code:
public static class Handler extends AbstractBiMessageHandler<PlaySoundPacket> {
 @Override
 public IMessage handleClientMessage(EntityPlayer player, PlaySoundPacket message, MessageContext ctx) {
 // This will play a sound that only the client player will hear:
 player.playSound(message.sound, message.volume, message.pitch);
 return null;
 }
 
 @Override
 public IMessage handleServerMessage(EntityPlayer player, PlaySoundPacket message, MessageContext ctx) {
 // This will play a sound that everyone nearby will hear:
 player.worldObj.playSoundEffect(message.x, message.y, message.z, message.sound, message.volume, message.pitch);
 return null;
 }
}

Setting up the Server

Well, I hope you enjoyed that little exercise as much as I did, and hopefully this helped you customize the packet handling experience to your liking. Again, I feel the need to stress that the solutions presented in this tutorial are wholly unnecessary for a functioning packet handling system, so please do not think that it has to be done this way.

FOOTNOTE

Now that you've gone through all of that, you may be thinking, as I did, that it seems really stupid to have to write a static IMessageHandler class for every single IMessage. I mean, can't it be generalized somehow? ABSOLUTELY!

Now, there are some who prefer to keep the message handler completely separate from the message class, since they are technically two different things. That's fine. However, my opinion is that the message should be completely self-contained as much as possible so that when you add a new message, you write one single class that does everything it needs to do to accomplish what it's supposed to do, and that includes handling itself when it is received on the other side. It makes the code simple and easy to understand, and you'll never have to write another stupid IMessageHandler class again! Sweet.

A few notes about this method of self-contained messages:

1. You should still choose to extend either the Server or Client message class in most cases

2. You won't ever need to check Side again (unless implementing a bidirectional message, which is very rare)

3. You CAN use 'this' in your message class when processing itself, because the way the system is set up the message instance that is constructed on the receiving side calls the processing method after reading in its data. I personally find this more intuitive than writing 'msg.whatever' in an external handling class.

Finally, again, let me reiterate the fact that NONE OF THE ABOVE is necessary. At all. You can have a perfectly functioning network system without doing any of it. In fact, I recommend you try the 'normal' way first, as only then will you truly appreciate how awesome this tutorial is. Er, I mean, as only then will you be able to determine for yourself which way you prefer... Happy modding!

MY TUTORIALS
Need help with modding? Check out my tutorials on Github, or read them on the forums:

Custom Armors, the OOP Way (GitHub only)

1.7.2 Example Mod (GitHub only)

Modding With APIs

EventHandler and IExtendedEntityProperties

Custom Inventories in Items and Players

Multi-Input/Output Furnace

Custom Projectile: Getting it to Render

Overriding shift-click in custom Containers

Using Potions in Crafting Recipes

Enchanted Books and Crafting Recipes

Quote from Xuluf

Ah, excellent tutorial! I've always wondered how to use the SimpleNetworkWrapper

// first layer of abstraction:
public abstract class AbstractMessageHandler<T extends IMessage> implements IMessageHandler <T, IMessage>

// second layer (two classes: one for server, one for client)
public abstract class AbstractServerMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

public abstract class AbstractClientMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

// Abstract Handler class for server; note the <T extends IMessage> and <T>
public abstract class AbstractServerMessageHandler<T extends IMessage> extends AbstractMessageHandler<T>

// so your actual handler class will need to have a signature like this,
// with your message class to be handled in brackets: <YourMessageClass>
public static class OpenGuiMessageHandler extends AbstractServerMessageHandler<OpenGuiMessage>

Quote from Lucrecious

Hey! Any updates on getting this code up on Github?

@Override
public EntityPlayer getPlayerEntity(MessageContext ctx) {
  return (ctx.side.isClient() ? Minecraft.getMinecraft().thePlayer : super.getPlayerEntity(ctx));
}

Quote from Canadinese»

Hi, I'm having trouble handling any messages received on the server side when using SendToAllAround. What I'm trying to do is play a sound when a player presses a button on one of my GUIs and any nearby players will hear this sound. Here's how I've been trying to do it using your networking classes PacketDispatcher, AbstractMessageHandler, AbstractBiMessageHandler, PlaySoundPacket.

Inside of my Gui class, in the constructor:

//player is the player that is passed in when constructing the GUI

PacketDispatcher.sendToAllAround(new PlaySoundPacket(Constants.MODID + ":fx.ui.test", 1, 1, player), player, 50.0);

When playing Singleplayer, this works fine. I can hear the sounds, and BiMessages work. Although, the moment it becomes multiplayer it gives an error and plays no sound. Any BiMessages will do this, and sending messages to the server works. I am using Minecraft Forge for 1.7.2 (10.13.2.1230).

Quote from Canadinese»

Inside of my Gui class, in the constructor:

//player is the player that is passed in when constructing the GUI

PacketDispatcher.sendToAllAround(new PlaySoundPacket(Constants.MODID + ":fx.ui.test", 1, 1, player), player, 50.0);

How would I send a packet that included a variable that was changed client side, to the server?

example code:

I have pretty much everything you have from github in my environment and the game runs fine.

I'm not sure how to tell the server about changes in the world.

I will look at my code again in a few hours and try to figure out.

Very great tutorial:) It really helped me out! Thanks:D

Quote from dvatreknerd314»

This may be a dumb question, but where would the following bit of code from step 2 go?

 private static final void registerMessage(Class<!--? extends IMessageHandler<REQ, REPLY-->> handlerClass, Class  messageClass) {

 Side side = AbstractClientMessageHandler.class.isAssignableFrom(handlerClass) ? Side.CLIENT : Side.SERVER;

 PacketDispatcher.dispatcher.registerMessage(handlerClass, messageClass, packetId++, side);

}

Anywhere you want. I put my registration code in the PacketDispatcher class to keep everything in the same place.

Quote from atijaf»

How would I send a packet that included a variable that was changed client side, to the server?

example code:

int a = 2;

if (world.isRemote){

a = 5;

}

else{

//print variable.

}

You create a packet that can be sent to the server, and that packet should contain the integer field you want. When you instantiate the packet on the client, you provide it with the data you need (e.g. '5') and send it to the server; the server receives it and you can print out the value when the packet processes.

Look at the example packets, such as the OpenGuiPacket - what you want is exactly the same.

ou create a packet that can be sent to the server, and that packet should contain the integer field you want. When you instantiate the packet on the client, you provide it with the data you need (e.g. '5') and send it to the server; the server receives it and you can print out the value when the packet processes.

Look at the example packets, such as the OpenGuiPacket - what you want is exactly the same.

Thanks:) Would the same go for updating the world. (Places block via command and tell the server I placed a block?)