How to use SimpleNetworkWrapper, IMessage and IMessageHandler

[Ablaze]

Check out diesieben's tutorial here too: http://www.minecraftforge.net/forum/index.php/topic,20135.0.html

 

SimpleNetworkWrapper and what it is

SimpleNetworkWrapper is an FML wrapper around Messages and MessageHandlers, so that Netty can understand your messages and handlers. It is the new way to send packets to players. You could use Netty itself but as cpw said, it can cause lots of problems like memory leaks.

 

Steps to use the SimpleNetworkWrapper

1. Register a SimpleNetworkWrapper and a message

2. Create an IMessage

3. Create an IMessageHandler

4. Send the message

 

Register a SimpleNetworkWrapper

This step is fairly simple.

public static SimpleNetworkWrapper snw; 

in your preInit:
snw = NetworkRegistry.INSTANCE.newSimpleChannel(modid); 
snw.registerMessage(TutorialMessageHandler.class, TutorialMessage.class, 0, Side.CLIENT); 

You need to give the wrapper a String to identify the wrapper. It is a good practice to give it your mod-id so that it is unique for every mod.

 

The parameters for registerMessage() are - a message handler, a message, a discriminator byte (a unique identifier for your messages), the side the handler is on - client or server.

 

Create an IMessage

IMessage is a packet. Your class will be implementing IMessage, and will be implementing some methods.

public class TutorialMessage implements IMessage{
    public int extremelyImportantInteger; 

    public TutorialMessage() {}

    public TutorialMessage(int a) { 
        this.extremelyImportantInteger = a;
    }

    @Override
    public void toBytes(ByteBuf buf) { 
        buf.writeInt(extremelyImportantInteger);
    }

    @Override
    public void fromBytes(ByteBuf buf) { 
        this.extremelyImportantInteger = buf.readInt();
    }

}

We will pretend that extremelyImportantInteger is an extremely important integer to be sent from the client to the server.

 

Yes, you need two constructors. This one will be used by you to initialize your fields, while the other one will be used by Forge to create your packet.

 

Your data will be sent through a ByteBuffer and so you must write your data to it using the write*** methods in the toBytes() method.

 

To read from the buffer, use fromBytes(). You must read data IN THE SAME ORDER as you wrote it!

 

And that is it for your message!

 

Create an IMessageHandler

The IMessageHandler will act as your packet handler. So make sure your class implements this class.

public class TutorialMessageHandler implements IMessageHandler<TutorialMessage, IMessage> { 

    @Override
    public IMessage onMessage(TutorialMessage message, MessageContext ctx) { 
        System.out.println(message.extremelyImportantInteger);
        return null;
    }

}

IMessageHandler<> takes two type parameters - first is the packet you handle and the other one is the packet you return.

 

The handler calls the onMessage() method when it receives the packet.

 

That is it for your handler!

 

Send the message

We got it all working now. Launch Minecraft and it will work fine. But.. you never send a packet! So, wherever you want to send a packet, add this line:

MainFile.snw.sendTo(new TutorialMessage(3), (EntityPlayerMP) entityPlayer); 

 

The sendTo() method takes a packet to be sent and an EntityPlayerMP. The SimpleNetworkWrapper class also has some more cool methods like sendToDimension() but I'll leave that to you for exploring.

 

There you go! Give yourself a pat on the back because you successfully got it working!

 

BONUS: Reading and writing strings to and from ByteBufs

If you noticed, there is no ByteBuf.readString() or ByteBuf.writeString("") method. Not to worry! There is a class called ByteBufUtils which you can use to operate on much more complex stuff like ItemStacks and Strings!

So, to write a String -

ByteBufUtils.writeUTF8String(buf, ""); 

and to read

String myString = ByteBufUtils.readUTF8String(buf); 

 

In writeUTF8String(), buf is your ByteBuffer and the other parameter should be obvious.

 

readUTF8String should be quite obvious. buf is your buffer.

 

Thanks to diesieben for telling me about ByteBufUtils.

 

That is it folks! Hope you learnt something from this

 

Regards,

Ablaze.

 

[Alix_The_Alicorn]

I understand the part where you say the last param is what side the handler is on, but what side should the handler be on? Sender or Receiver?

[WorldsEnder]

You could also mention the class net.minecraft.network.PacketBuffer for advanced and optimized read/writing.

[Romejanic]

You can also use the ByteBufUtils class which has some amazing stuff, like ItemStacks and NBT Compounds!