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).

Author:

cpw

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.EnumMap<Side,FMLEmbeddedChannel>	channels
private static java.lang.Class<?>	defaultChannelPipeline
private static java.lang.reflect.Method	generateName
private SimpleIndexedCodec	packetCodec

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
private <REQ extends IMessage,REPLY extends IMessage,NH extends INetHandler> void	addClientHandlerAfter(FMLEmbeddedChannel channel, java.lang.String type, IMessageHandler<? super REQ,? extends REPLY> messageHandler, java.lang.Class<REQ> requestType)
private <REQ extends IMessage,REPLY extends IMessage,NH extends INetHandler> void	addServerHandlerAfter(FMLEmbeddedChannel channel, java.lang.String type, IMessageHandler<? super REQ,? extends REPLY> messageHandler, java.lang.Class<REQ> requestType)
private java.lang.String	generateName(io.netty.channel.ChannelPipeline pipeline, io.netty.channel.ChannelHandler handler)
private <REPLY extends IMessage,REQ extends IMessage> SimpleChannelHandlerWrapper<REQ,REPLY>	getHandlerWrapper(IMessageHandler<? super REQ,? extends REPLY> messageHandler, Side side, java.lang.Class<REQ> requestType)
Packet<?>	getPacketFrom(IMessage message) Construct a minecraft packet from the supplied message.
(package private) static <REQ extends IMessage,REPLY extends IMessage> IMessageHandler<? super REQ,? extends REPLY>	instantiate(java.lang.Class<? extends IMessageHandler<? super REQ,? extends REPLY>> handler)
<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	sendToAllTracking(IMessage message, Entity entity) Sends this message to everyone tracking an entity.
void	sendToAllTracking(IMessage message, NetworkRegistry.TargetPoint point) Sends this message to everyone tracking 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

Field Detail

channels

private java.util.EnumMap<Side,FMLEmbeddedChannel> channels

packetCodec

private SimpleIndexedCodec packetCodec

defaultChannelPipeline

private static java.lang.Class<?> defaultChannelPipeline

generateName

private static java.lang.reflect.Method generateName

Constructor Detail

SimpleNetworkWrapper

public SimpleNetworkWrapper(java.lang.String channelName)

Method Detail

generateName

private java.lang.String generateName(io.netty.channel.ChannelPipeline pipeline,
                                      io.netty.channel.ChannelHandler handler)

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

instantiate

static <REQ extends IMessage,REPLY extends IMessage> IMessageHandler<? super REQ,? extends REPLY> instantiate(java.lang.Class<? extends IMessageHandler<? super REQ,? extends REPLY>> 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

addServerHandlerAfter

private <REQ extends IMessage,REPLY extends IMessage,NH extends INetHandler> void addServerHandlerAfter(FMLEmbeddedChannel channel,
                                                                                                        java.lang.String type,
                                                                                                        IMessageHandler<? super REQ,? extends REPLY> messageHandler,
                                                                                                        java.lang.Class<REQ> requestType)

addClientHandlerAfter

private <REQ extends IMessage,REPLY extends IMessage,NH extends INetHandler> void addClientHandlerAfter(FMLEmbeddedChannel channel,
                                                                                                        java.lang.String type,
                                                                                                        IMessageHandler<? super REQ,? extends REPLY> messageHandler,
                                                                                                        java.lang.Class<REQ> requestType)

getHandlerWrapper

private <REPLY extends IMessage,REQ extends IMessage> SimpleChannelHandlerWrapper<REQ,REPLY> getHandlerWrapper(IMessageHandler<? super REQ,? extends REPLY> messageHandler,
                                                                                                               Side side,
                                                                                                               java.lang.Class<REQ> requestType)

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

sendToAllTracking

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

Sends this message to everyone tracking a point. The IMessageHandler for this message type should be on the CLIENT side. The range field of the NetworkRegistry.TargetPoint is ignored.

Parameters:

message - The message to send

point - The tracked NetworkRegistry.TargetPoint around which to send

sendToAllTracking

public void sendToAllTracking(IMessage message,
                              Entity entity)

Sends this message to everyone tracking an entity. The IMessageHandler for this message type should be on the CLIENT side. This is not equivalent to #sendToAllTracking(IMessage, TargetPoint) because entities have different tracking distances based on their type.

Parameters:

message - The message to send

entity - The tracked entity 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