net.minecraftforge.fml.common.network.simpleimpl

Class SimpleNetworkWrapper

java.lang.Object

net.minecraftforge.fml.common.network.simpleimpl.SimpleNetworkWrapper

public class SimpleNetworkWrapper
extends java.lang.Object

This class is a simplified netty wrapper for those not wishing to deal with the full power of netty. It provides a simple message driven system, based on a discriminator byte over the custom packet channel. It assumes that you have a series of unique message types with each having a unique handler. Generally, context should be derived at message handling time. Usage is simple:

• construct, and store, an instance of this class. It will automatically register and configure your underlying netty channel.
• Then, call registerMessage(Class, Class, int, Side) for each message type you want to exchange providing an IMessageHandler implementation class as well as an IMessage implementation class. The side parameter to that method indicates which side (server or client) the message processing will occur on. The discriminator byte should be unique for this channelName - it is used to discriminate between different types of message that might occur on this channel (a simple form of message channel multiplexing, if you will).
• To get a packet suitable for presenting to the rest of minecraft, you can call getPacketFrom(IMessage). The return result is suitable for returning from things like TileEntity#getDescriptionPacket() for example.
• Finally, use the sendXXX to send unsolicited messages to various classes of recipients.

Example

  // Request message
  public Message1 implements IMessage {
  // message structure
   public fromBytes(ByteBuf buf) {
    // build message from byte array
   }
   public toBytes(ByteBuf buf) {
    // put message content into byte array
   }
  }
  // Reply message
  public Message2 implements IMessage {
   // stuff as before
  }
  // Message1Handler expects input of type Message1 and returns type Message2
  public Message1Handler implements IMessageHandler {
   public Message2 onMessage(Message1 message, MessageContext ctx) {
    // do something and generate reply message
    return aMessage2Object;
   }
  }
  // Message2Handler expects input of type Message2 and returns no message (IMessage)
  public Message2Handler implements IMessageHandler {
   public IMessage onMessage(Message2 message, MessageContext ctx) {
    // handle the message 2 response message at the other end
    // no reply for this message - return null
    return null;
   }
  }

  // Code in a FMLPreInitializationEvent or FMLInitializationEvent handler
  SimpleNetworkWrapper wrapper = NetworkRegistry.newSimpleChannel("MYCHANNEL");
  // Message1 is handled by the Message1Handler class, it has discriminator id 1 and it's on the client
  wrapper.registerMessage(Message1Handler.class, Message1.class, 1, Side.CLIENT);
  // Message2 is handled by the Message2Handler class, it has discriminator id 2 and it's on the server
  wrapper.registerMessage(Message2Handler.class, Message2.class, 2, Side.SERVER);
  

Note: As of Minecraft 1.8 packets are by default handled on the network thread. That means that your IMessageHandler can not interact with most game objects directly. Minecraft provides a convenient way to make your code execute on the main thread instead using IThreadListener.addScheduledTask(Runnable). The way to obtain an IThreadListener is using either the Minecraft instance (client side) or a WorldServer instance (server side).

Constructor Summary

Constructors

Constructor and Description
SimpleNetworkWrapper(java.lang.String channelName)

Method Summary

Modifier and Type	Method and Description
Packet<?>	getPacketFrom(IMessage message) Construct a minecraft packet from the supplied message.
<REQ extends IMessage,REPLY extends IMessage> void	registerMessage(java.lang.Class<? extends IMessageHandler<REQ,REPLY>> messageHandler, java.lang.Class<REQ> requestMessageType, int discriminator, Side side) Register a message and it's associated handler.
<REQ extends IMessage,REPLY extends IMessage> void	registerMessage(IMessageHandler<? super REQ,? extends REPLY> messageHandler, java.lang.Class<REQ> requestMessageType, int discriminator, Side side) Register a message and it's associated handler.
void	sendTo(IMessage message, EntityPlayerMP player) Send this message to the specified player.
void	sendToAll(IMessage message) Send this message to everyone.
void	sendToAllAround(IMessage message, NetworkRegistry.TargetPoint point) Send this message to everyone within a certain range of a point.
void	sendToDimension(IMessage message, int dimensionId) Send this message to everyone within the supplied dimension.
void	sendToServer(IMessage message) Send this message to the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleNetworkWrapper

public SimpleNetworkWrapper(java.lang.String channelName)

Method Detail

registerMessage

public <REQ extends IMessage,REPLY extends IMessage> void registerMessage(java.lang.Class<? extends IMessageHandler<REQ,REPLY>> messageHandler,
                                                                          java.lang.Class<REQ> requestMessageType,
                                                                          int discriminator,
                                                                          Side side)

Register a message and it's associated handler. The message will have the supplied discriminator byte. The message handler will be registered on the supplied side (this is the side where you want the message to be processed and acted upon).

Parameters:

messageHandler - the message handler type

requestMessageType - the message type

discriminator - a discriminator byte

side - the side for the handler

registerMessage

public <REQ extends IMessage,REPLY extends IMessage> void registerMessage(IMessageHandler<? super REQ,? extends REPLY> messageHandler,
                                                                          java.lang.Class<REQ> requestMessageType,
                                                                          int discriminator,
                                                                          Side side)

Register a message and it's associated handler. The message will have the supplied discriminator byte. The message handler will be registered on the supplied side (this is the side where you want the message to be processed and acted upon).

Parameters:

messageHandler - the message handler instance

requestMessageType - the message type

discriminator - a discriminator byte

side - the side for the handler

getPacketFrom

public Packet<?> getPacketFrom(IMessage message)

Construct a minecraft packet from the supplied message. Can be used where minecraft packets are required, such as TileEntity#getDescriptionPacket().

Parameters:

message - The message to translate into packet form

Returns:

A minecraft Packet suitable for use in minecraft APIs

sendToAll

public void sendToAll(IMessage message)

Send this message to everyone. The IMessageHandler for this message type should be on the CLIENT side.

Parameters:

message - The message to send

sendTo

public void sendTo(IMessage message,
                   EntityPlayerMP player)

Send this message to the specified player. The IMessageHandler for this message type should be on the CLIENT side.

Parameters:

message - The message to send

player - The player to send it to

sendToAllAround

public void sendToAllAround(IMessage message,
                            NetworkRegistry.TargetPoint point)

Send this message to everyone within a certain range of a point. The IMessageHandler for this message type should be on the CLIENT side.

Parameters:

message - The message to send

point - The NetworkRegistry.TargetPoint around which to send

sendToDimension

public void sendToDimension(IMessage message,
                            int dimensionId)

Send this message to everyone within the supplied dimension. The IMessageHandler for this message type should be on the CLIENT side.

Parameters:

message - The message to send

dimensionId - The dimension id to target

sendToServer

public void sendToServer(IMessage message)

Send this message to the server. The IMessageHandler for this message type should be on the SERVER side.

Parameters:

message - The message to send