There is now available a new GNE tutorial for making GNE programs, meant for the beginning user. You can find it in the docs package or on the GNE website. Originally this beginner's guide was the only help for GNE, so the tutorial overlaps this guide. However, the tutorial goes in depth and explains the code, whereas this guide is a general outline of the library.
Do not forget that there are lots of examples and tests in the examples directory. After reading this guide you'll probably want to examine the examples to see some sample code. exaddr, expacket, and exhello are good examples to look at first. The example expong is the first example game using GNE and shows the basics of how to create a framework for a GNE game.
There are several parts and services that the GNE library provides.
Throughout this guide, there will be classes marked with a star (*). These classes are ones that you probably could not make program without using them, and you'll probably want to learn them first.
Classes that are not listed are ones that are used mostly by GNE itself and you'll probably not need to use them directly in normal circumstances.
Threads are used throughout GNE. You will need a basic understanding of threads to use GNE. You won't need to create any threads yourself, but you receive events in different threads from your game engine, so you will need to understand when to use mutexes to guard your game engine's data.
For those of you who have used Allegro, the Allegro timers and their callbacks are done in threads, and so are GNE's timers and events.
Basically, what a mutex does is it only allows one thread into a section of code at a time. You should use a mutex around a section of code that accesses any data on the heap (ie static variables or allocated using new or malloc) that is shared by more than one thread.
For more information a link to a pthreads tutorial: http://www.llnl.gov/computing/tutorials/workshops/workshop/pthreads/MAIN.html
GNE uses pthreads internally. You can pick up on threading concepts and examples in this tutorial although obviously the functions don't apply as you should use the threading classes. You'll want to focus espically on the area of detaching, joining, and mutexes. After you read that check the documentation for the GNE classes to see the differences.
Standard C/C++ only allows for line buffered input and output. It does not allow for output the same time as input, nor does it allow the user to get input without the user pressing enter or reposition the cursor. These features are useful for game servers so that one can implement a console where the user can input/chat while other messages are being outputted. Additionally, the standard C/C++ I/O is not thread-safe.
GNE provides multithreaded console I/O which you can use to make text-based servers, consoles, or chat programs. See the exinput example for sample code using the GNE Console API, although every GNE example makes use of the GNE Console API.
The Connection API provides the classes to send data between computers. Connections in GNE handle bandwith controls, do version and error checking, parse packets, and more.
Learning this part of GNE can be a little confusing at first as to what classes to use and when you use them. The exhello example shows the minimum proper code to set up your connections.
Connection is the base class of every GNE connection. While you won't directly create an object of type Connection, you will use the methods of this class, and espically the PacketStream that it contains.
Connections generate events and send them to a ConnectionListener. You will need to create your own ConnectionListener and a large part of your networking logic will be in this class. The ConnectionListener is what actually makes the connection do anything useful.
When you are ready to make a connection, you will need on the server side your own ServerConnectionListener to listen for incoming connections, and of course a ConnectionListener to provide the actual server's functionality.
On the client side you will use a ClientConnection and a ConnectionListener to connect to this server.
The PacketStream represents an outgoing and an incoming queue of packets. To get sent packets, use GNE::PacketStream::getNextPacket to receive the next incoming packet. Use GNE::PacketStream::writePacket to send one.
PacketStreams can also be tied with a PacketFeeder. A PacketFeeder provides a way to feed a continuous stream of packets that is based on the bandwidth of the connection. For example if you wanted your client to send update packets as fast as it can, but you always want to send the latest information, what you would do is create a packet, send it, wait for it to be sent (based on the bandwidth of the connection), and then repeat again. In GNE a PacketFeeder provides this sort of functionality.
To send and receive packets, you will want to derive your own packet class from GNE::Packet and register it with GNE::PacketParser::registerPackets. Override all of the relevant functions in Packet and in the writePacket and readPacket functions will be the only place you are likely to use the GNE::RawPacket class. The RawPacket represents the serialized form of a packet. Use it similarly to cout or cin. Seeing the expacket example is probably the best way to learn how to make your own packets.
Once you make your own packet types and register them, GNE will be able to recognize and parse these packets and be able to send and receive them through the PacketStream as it would any other packet.
You only have to use SyncConnection when connecting, and even then, only to get a pointer to the Connection object. But the SyncConnection is a helpful class to write connecting code or to do connections where you are sending a packet and are waiting for a specific response packet. See the exsynchello example for a version of exhello using SyncConnections rather than the PacketStream, and further note that exhello and exsynchello are completely compatable with each other -- so they are doing the SAME thing over the network but are simply just two ways of doing it.
This API will contain classes to manage unique player IDs and data, manage a list of players, and handle things like text communication amongst the players.
The list service was meant to address one of the largest problems with independent multiplayer games -- finding others who have the game to play with. The service will act as services like Battle.NET or Half-Life's game lists do. Initially only a searchable database of current game servers will exist but afterwards chat/IM/login functionality might be added.
There is also a mailing list called gnelib-users on the sourceforge website: http://lists.sourceforge.net/mailman/listinfo/gnelib-users