| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Network API overview</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p>This document explains how to write network games with ClanLib's network |
| 8 |
model:</p> |
| 9 |
|
| 10 |
<ul> |
| 11 |
<li>Sockets, low-level sockets wrapped into nice c++ classes.</li> |
| 12 |
<li>NetSession, a networking engine.</li> |
| 13 |
<li>NetObjects, dynamic object replication for the networking engine.</li> |
| 14 |
<li>NetVariables, a object variables serialization system.</li> |
| 15 |
<li>Browse, system that allows games to register themselves to a browse master.</li> |
| 16 |
</ul> |
| 17 |
|
| 18 |
<h3>ClanLib Sockets, low-level sockets</h3> |
| 19 |
|
| 20 |
<p>The lowest level is <codelink>CL_Socket</codelink>. This is platform independent |
| 21 |
version of the system level socket functions, encapsulated in a class for your |
| 22 |
convience. A simple example:</p> |
| 23 |
|
| 24 |
<code> |
| 25 |
/* Gets clanlib.org's index.html page: */ |
| 26 |
try |
| 27 |
{ |
| 28 |
std::string request_msg = "GET index.html HTTP/1.0\n\n"; |
| 29 |
CL_Socket sock(CL_Socket::tcp); |
| 30 |
sock.connect(CL_IPAddress("clanlib.org", "80")); |
| 31 |
sock.send(request_msg); |
| 32 |
while (true) |
| 33 |
{ |
| 34 |
char buffer[16*1024+1]; |
| 35 |
int received = sock.recv(buffer, 16*1024); |
| 36 |
if (received == 0) break; // end of stream. server closed connection. |
| 37 |
buffer[received] = 0; |
| 38 |
std::cout << buffer; |
| 39 |
} |
| 40 |
std::cout << std::endl; |
| 41 |
} |
| 42 |
catch (CL_Error err) |
| 43 |
{ |
| 44 |
std::cout << "Why wont things never work as planned? " << err.message.c_str() << std::endl; |
| 45 |
} |
| 46 |
</code> |
| 47 |
|
| 48 |
<p>The <codelink>CL_BufferedSocket</codelink> class is not completely implemented |
| 49 |
and should not be used. I'm not even anymore sure it was a good idea and it might |
| 50 |
be pending for removal.</p> |
| 51 |
|
| 52 |
<h4>EventTriggers:</h4> |
| 53 |
|
| 54 |
<p>Additionally to this, <codelink>CL_Socket</codelink> can use the |
| 55 |
<codelink>CL_EventTrigger</codelink> and <codelink>CL_EventListener</codelink> |
| 56 |
to wait for socket data. A small example:</p> |
| 57 |
|
| 58 |
<code> |
| 59 |
void wait_for_socket_data(CL_Socket &sock, int timeout) |
| 60 |
{ |
| 61 |
CL_EventTrigger *read_trigger = sock.get_read_trigger(); |
| 62 |
read_trigger->wait(timeout); |
| 63 |
} |
| 64 |
|
| 65 |
void wait_for_sockets(std::list<CL_Socket> &sockets, int timeout) |
| 66 |
{ |
| 67 |
CL_EventListener listener; |
| 68 |
std::list<CL_Socket>::iterator it; |
| 69 |
for (it = sockets.begin(); it != sockets.end(); it++) |
| 70 |
{ |
| 71 |
CL_Socket &sock = *it; |
| 72 |
listener.add_trigger(sock.get_read_trigger(); |
| 73 |
} |
| 74 |
listener.wait(timeout); |
| 75 |
} |
| 76 |
</code> |
| 77 |
|
| 78 |
<h4>OutputSources:</h4> |
| 79 |
<p><codelink>CL_OutputSource_Socket</codelink> is a <codelink>CL_OutputSource</codelink> |
| 80 |
compatible wrapper for <codelink>CL_Socket</codelink>. It can be mixed with |
| 81 |
<codelink>CL_Socket</codelink> since the <codelink>CL_Socket</codelink> class reference |
| 82 |
counts the handle to the system level socket. A small example of its usage:</p> |
| 83 |
|
| 84 |
<code> |
| 85 |
void send_init_handshake(CL_Socket &sock) |
| 86 |
{ |
| 87 |
CL_OutputSource_Socket output(sock); |
| 88 |
|
| 89 |
// output.set_big_endian_mode(); // ha! as if that actually worked... |
| 90 |
output.write_string("Yo dude! You've entered the 1337 socket owned by Cl4nL1b"); |
| 91 |
|
| 92 |
output.write_int(42); |
| 93 |
} |
| 94 |
</code> |
| 95 |
|
| 96 |
<p>You will find a similar <codelink>CL_InputSource_Socket</codelink> for |
| 97 |
reading from sockets.</p> |
| 98 |
|
| 99 |
<p>That was the lowest level socket support. It doesnt do much except save you |
| 100 |
from the trouble of setting up some annoying C structs and filling them with |
| 101 |
data.</p> |
| 102 |
|
| 103 |
<h3>The ClanLib networking engine</h3> |
| 104 |
|
| 105 |
<p>ClanLib features a networking engine called NetSession. It is built on top |
| 106 |
of the lower level socket interface in ClanLib, so its all up to the game |
| 107 |
developer which level API is prefered. The NetSession engine provides the |
| 108 |
following core features:</p> |
| 109 |
|
| 110 |
<ul> |
| 111 |
|
| 112 |
<li>Single socket firewall & NAT friendly channeling system. It will not use a |
| 113 |
dozen of ports, forcing firewall admins to open a wide range of ports, and |
| 114 |
it should work flawlessly through NAT internet connected systems.</li> |
| 115 |
|
| 116 |
<li>Simple but powerful channel system to seperate different types of network |
| 117 |
communication in the game.</li> |
| 118 |
|
| 119 |
<li>Connection oriented stream communication support (like TCP sockets), and |
| 120 |
connectionless communication (like UDP sockets) support.</li> |
| 121 |
|
| 122 |
<li>Recognition of players that have left the server and now rejoining it - |
| 123 |
allowing a game to restore scores for people lagging out of server or for |
| 124 |
other reason left the server to return again.</li> |
| 125 |
|
| 126 |
<li>Flexible server/client relationship in a netsession, allowing a game to |
| 127 |
easilly implement server travelling (often used by mass-multiplayer online |
| 128 |
game servers). Server travelling means to have a client seamlessly connect |
| 129 |
to a new server as it reaches the border boundary of the map that a game |
| 130 |
server controls.</li> |
| 131 |
|
| 132 |
<li>Threadding model that both give you the option to run everything in one |
| 133 |
single thread, or to spread things over multiple worker threads. |
| 134 |
TODO: Explain more whats threaded in clanNetwork</li> |
| 135 |
|
| 136 |
<li>And most important of all, its simple and easy to understand. Most stuff |
| 137 |
is done completely automatically. :)</li> |
| 138 |
|
| 139 |
</ul> |
| 140 |
|
| 141 |
<h4>CL_NetSession:</h4> |
| 142 |
|
| 143 |
<p>So what is a CL_NetSession exactly?</p> |
| 144 |
|
| 145 |
<ol> |
| 146 |
|
| 147 |
<li>Its a container for computers connected to or from the computer.</li> |
| 148 |
|
| 149 |
<li>A set of signals being invoked when accepting new computers into the |
| 150 |
system, leaving the system, and rejoining the system.</li> |
| 151 |
|
| 152 |
<li>Signals that are being invoked when a new stream connection is made, or a |
| 153 |
netpacket is received.</li> |
| 154 |
|
| 155 |
</ol> |
| 156 |
|
| 157 |
<p>When a netsession is initially constructed, it will not listen for incoming |
| 158 |
computers on any ports, nor will it connect to any remote system. It can |
| 159 |
become a server, a client or any kind of combination you prefer.</p> |
| 160 |
|
| 161 |
<p>There are two ways a new computer can enter a netsession. Either |
| 162 |
CL_NetSession::start_listen() is called, making it accept connecting |
| 163 |
computers on the specified port, or CL_NetSession::connect() is called, |
| 164 |
making the netsession connect to an other computer.</p> |
| 165 |
|
| 166 |
<p>There is nothing that prevents you from mixing those two calls. Eg. to have |
| 167 |
a Peer To Peer network model, or to make servers connect to other servers. |
| 168 |
Its also no problem to make a client connect to two different servers at the |
| 169 |
same time, or to disconnect from them again.</p> |
| 170 |
|
| 171 |
<pre> |
| 172 |
// Connect to a server |
| 173 |
CL_NetSession netsession("MyGame"); |
| 174 |
CL_NetComputer server = netsession.connect(CL_IPAddress("myserver.coolgames.com", "4322")); |
| 175 |
|
| 176 |
... |
| 177 |
|
| 178 |
// Start a server which listens to incoming connections: |
| 179 |
CL_NetSession netsession("MyGame"); |
| 180 |
slots.connect(netsession.sig_computer_connected(), this, &Server::on_connect); |
| 181 |
slots.connect(netsession.sig_computer_disconnected(), this, &Server::on_disconnect); |
| 182 |
netsession.start_listen("4322"); |
| 183 |
|
| 184 |
... |
| 185 |
|
| 186 |
void Server::on_connect(CL_NetComputer &computer) |
| 187 |
{ |
| 188 |
std::cout << "A computer connected from " << computer.get_address().get_address() << std::endl;; |
| 189 |
} |
| 190 |
|
| 191 |
void Server::on_disconnect(CL_NetComputer &computer) |
| 192 |
{ |
| 193 |
std::cout << "Computer " << computer.get_address().get_address() << "disconnected" << std::endl; |
| 194 |
} |
| 195 |
</pre> |
| 196 |
|
| 197 |
<h4>CL_NetComputer:</h4> |
| 198 |
|
| 199 |
<p>When a computer enters the system, it is represented by a CL_NetComputer |
| 200 |
handle. The signal CL_NetSession::sig_computer_connected() is emitted when a |
| 201 |
new computer enters the system.</p> |
| 202 |
|
| 203 |
<p>If the incoming computer is already known to the system, |
| 204 |
CL_NetSession::sig_computer_reconnected() is emitted instead. A reconnecting |
| 205 |
computer can only be recognized if not all original CL_NetComputer handles |
| 206 |
to it has been destroyed. This allows the application to control for how |
| 207 |
long time an earlier computer can be recognized by the system. For instance, |
| 208 |
if a game wants to remember old computers for ten minutes, it could store |
| 209 |
the CL_NetComputer handle when being emitted by |
| 210 |
CL_NetSession::sig_computer_disconnected(). After the 10 minutes timeout, it |
| 211 |
just need to destroy the instance it kept, and the netsession will forget |
| 212 |
about the previous connected computer.</p> |
| 213 |
|
| 214 |
<h4>CL_NetPacket:</h4> |
| 215 |
|
| 216 |
<p>To send a message to an other computer, the most simple approach is to |
| 217 |
construct a netpacket, fill it with data, and send it to one or more |
| 218 |
computers (via CL_NetComputer::send() or CL_NetGroup::send()).</p> |
| 219 |
|
| 220 |
<pre> |
| 221 |
CL_NetPacket msg; |
| 222 |
msg.output.write_string(player->name); |
| 223 |
msg.output.write_int32(player->x); |
| 224 |
msg.output.write_int32(player->y); |
| 225 |
msg.output.write_bool8(player->running); |
| 226 |
destination_computer.send("Players", msg); |
| 227 |
</pre> |
| 228 |
|
| 229 |
<p>This is the connectionless sending approach. The message can be sent |
| 230 |
reliably (via TCP) or unreliable (via UDP). Netpackets are perfect for short |
| 231 |
messages where the latency (ping) should be kept at a minimum.</p> |
| 232 |
|
| 233 |
<p>When sending a netpacket, you have to point out what channel you want to |
| 234 |
send it to. This allows you to seperate the different types of communication |
| 235 |
in your application. If a game features a lobby, the messages sent between |
| 236 |
players in the lobby could use a channel name of "lobby". Player name stuff |
| 237 |
might be sent to "playerinfo" and so forth.</p> |
| 238 |
|
| 239 |
<p>The netpacket channel is used when a netpacket is received. For each channel |
| 240 |
in the application, there exist a signal in CL_NetSession that gets emitted. |
| 241 |
To hook up a receive function to the eg. the "lobby" channel, use |
| 242 |
CL_NetSession::sig_netpacket_receive() with "lobby" as the parameter. That |
| 243 |
will return the signal for that channel.</p> |
| 244 |
|
| 245 |
<pre> |
| 246 |
slot = netsession.sig_netpacket_receive("Login").connect(this, &Login::on_netpacket)); |
| 247 |
|
| 248 |
... |
| 249 |
|
| 250 |
void Login::on_netpacket(CL_NetPacket &packet, CL_NetComputer &computer) |
| 251 |
{ |
| 252 |
std::string user = packet.input.read_string(); |
| 253 |
std::string password = packet.input.read_string(); |
| 254 |
... |
| 255 |
</pre> |
| 256 |
|
| 257 |
<h4>CL_NetStream:</h4> |
| 258 |
|
| 259 |
<p>It is also possible to make connection oriented connections to a computer. |
| 260 |
This is often practical if there needs to a higher level of communication |
| 261 |
between the two computers.</p> |
| 262 |
|
| 263 |
<p>Imagine a game server that just did a map switch. The game supports |
| 264 |
automatic downloads of map files that are not available on the client. This |
| 265 |
is easiest implemented with a netstream. The server first has to tell the |
| 266 |
client about a file, then the client has to check if the file already exist |
| 267 |
locally, if not, it should report back and ask for the download. Then the |
| 268 |
server has to start sending the entire file, which may be several megs in |
| 269 |
size.</p> |
| 270 |
|
| 271 |
<p>There's a lot of 'ping-pong' communication here, where each end need to know |
| 272 |
what they talked about earlier. Connectionless communication (netpackets) |
| 273 |
become very unpleasant and annoying to use in this kind of communication, |
| 274 |
but with streams its very simple:</p> |
| 275 |
|
| 276 |
<pre> |
| 277 |
// Client version: |
| 278 |
CL_NetStream stream("download channel", server_netcomputer); |
| 279 |
int num_files = stream.input.read_int32(); |
| 280 |
for (int i=0; i<num_files; i++) |
| 281 |
{ |
| 282 |
std::string filename = stream.input.read_string(); |
| 283 |
if (file_exist(filename)) |
| 284 |
{ |
| 285 |
stream.output.write_bool8(false); // dont send file. |
| 286 |
} |
| 287 |
else |
| 288 |
{ |
| 289 |
stream.output.write_bool8(true); // send file. |
| 290 |
download_and_store_file(stream); |
| 291 |
} |
| 292 |
} |
| 293 |
</pre> |
| 294 |
|
| 295 |
<p>Simple, eh? What's the catch? The catch is that those calls are blocking. |
| 296 |
The code will stop up and wait for the server to answer, and if the |
| 297 |
connection is slow, we have to wait for the sends to complete as well.</p> |
| 298 |
|
| 299 |
<p>The solution to that problem is threadding. Construct a worker thread to do |
| 300 |
the communcation, and let the main game thread continue its run. Of course |
| 301 |
this means you'll have to do threadsafe code, but trust me, in most cases |
| 302 |
its far easier and nice than to start trying to store states between |
| 303 |
received netpackets.</p> |
| 304 |
|
| 305 |
<p>When a stream connection is made, CL_NetSession::sig_netstream_connect() is |
| 306 |
emitted on the receiving computer. ClanNetwork will not create a new thread |
| 307 |
for you when emitting this function, so if you want to thread your stream |
| 308 |
communcation, you'll have to create a thread in your slot function yourself.</p> |
| 309 |
|
| 310 |
|
| 311 |
<h3>NetObjects</h3> |
| 312 |
|
| 313 |
<p>On top of the netsession network engine, ClanLib provides a system to |
| 314 |
replicate objects to client machines. This system is called netobjects, and |
| 315 |
consist of three classes: CL_NetObject_Controller, CL_NetObject_Server and |
| 316 |
CL_NetObject_Client.</p> |
| 317 |
|
| 318 |
<p>The idea of the netobjects is that a CL_NetObject_Server object can send |
| 319 |
messages to a CL_NetObject_Client object, which is present on one or more |
| 320 |
client machines. These client objects can also send messages back to the |
| 321 |
server object.</p> |
| 322 |
|
| 323 |
<p>Netobjects operate over a netsession netpacket channel, which means that |
| 324 |
both the server and clients need to instantiate a CL_NetObject_Controller |
| 325 |
object. This object is responsible for receiving messages and dispatch them |
| 326 |
to the proper netobjects.</p> |
| 327 |
|
| 328 |
<p>In order to construct a server side netobject, simply construct an instance |
| 329 |
of CL_NetObject_Server. Notice that the object will NOT immidiately be |
| 330 |
replicated to clients. This will first happen when you send a message to the |
| 331 |
clients.</p> |
| 332 |
|
| 333 |
<p>When a server object sends a message, the receiving client machine's |
| 334 |
controller will look to see if there exist any CL_NetObject_Client for the |
| 335 |
object. If there do not, the controller will create a new |
| 336 |
CL_NetObject_Client object and signal CL_NetController:sig_create_object().</p> |
| 337 |
|
| 338 |
<p>The application is supposed to hook itself into this signal and read the |
| 339 |
message received. If the application keeps the CL_NetObject_Client handle |
| 340 |
around, future messages sent to this object will cause |
| 341 |
CL_NetObject_Client::sig_received_message() to be emitted. If the |
| 342 |
application do not keep the handle, or if it later on destroys it, any |
| 343 |
future messages sent to the object will cause sig_create_object() to be |
| 344 |
invoked again.</p> |
| 345 |
|
| 346 |
<p>Let's look at this again. When a server sends an initial message to the |
| 347 |
client, the client get the opportunity to create a client version of the |
| 348 |
object. If the game is a 3D shooter, where objects are only replicated to |
| 349 |
the client when within visible range, it is possible for the client to |
| 350 |
destroy the object when not visible any more. Next time the object comes |
| 351 |
within visible range, sig_create_object will be invoked again, and client |
| 352 |
recreates the object.</p> |
| 353 |
|
| 354 |
<p>Another example. Our netobject can have different kinds of messages. One of |
| 355 |
the messages is a "full update", including all information needed to |
| 356 |
construct the object. Then it has some "position update" messages that only |
| 357 |
include the new position of the object. Lets assume the first message, the |
| 358 |
full update, gets lost in package loss. Now the object sends a position |
| 359 |
update to the client. Since the client never got the original full update, |
| 360 |
sig_create_object is emitted, and the function do not have the information |
| 361 |
needed to create the object. The application can use the netobject handle in |
| 362 |
sig_create_object to send a message back to the server object, and in this |
| 363 |
message it asks for a full update. No object was created, so we do not keep |
| 364 |
the netobject handle. When the server receives the message, it sends back a |
| 365 |
full update, and sig_create_object is again invoked on the client. This time |
| 366 |
we do have the information needed to replicate, and we construct our object.</p> |
| 367 |
|
| 368 |
<pre> |
| 369 |
class ServerObject |
| 370 |
{ |
| 371 |
int x, y, shield; |
| 372 |
CL_NetObject_Server netobj; |
| 373 |
CL_Slot slot; |
| 374 |
|
| 375 |
ServerObject(CL_NetObject_Controller *controller) |
| 376 |
: netobj(controller) |
| 377 |
{ |
| 378 |
slot = netobj.sig_received_message(0).connect( |
| 379 |
this, &ServerObject::on_received_pos_update); |
| 380 |
} |
| 381 |
|
| 382 |
void on_received_pos_update( |
| 383 |
CL_NetComputer &computer, CL_NetPacket &packet) |
| 384 |
{ |
| 385 |
x = packet.input.read_int32(); |
| 386 |
y = packet.input.read_int32(); |
| 387 |
} |
| 388 |
|
| 389 |
void send_update(CL_NetComputer &comp) |
| 390 |
{ |
| 391 |
CL_NetPacket packet; |
| 392 |
packet.output.write_int32(x); |
| 393 |
packet.output.write_int32(y); |
| 394 |
packet.output.write_int32(shield); |
| 395 |
netobj.send(comp, 0, packet); |
| 396 |
} |
| 397 |
}; |
| 398 |
|
| 399 |
class ClientObject |
| 400 |
{ |
| 401 |
int x, y; |
| 402 |
CL_NetObject_Client netobj; |
| 403 |
CL_Slot slot; |
| 404 |
|
| 405 |
ClientObject(CL_NetObject_Client &netobj, CL_NetPacket &packet) |
| 406 |
: netobj(netobj) |
| 407 |
{ |
| 408 |
slot = netobj.sig_received_message(0).connect( |
| 409 |
this, &ClientObject::on_received_update); |
| 410 |
|
| 411 |
on_received_update(packet); |
| 412 |
} |
| 413 |
|
| 414 |
void on_received_update(CL_NetPacket &packet) |
| 415 |
{ |
| 416 |
x = packet.input.read_int32(); |
| 417 |
y = packet.input.read_int32(); |
| 418 |
shield = packet.input.read_int32(); |
| 419 |
} |
| 420 |
|
| 421 |
void send_pos_update() |
| 422 |
{ |
| 423 |
CL_NetPacket packet; |
| 424 |
packet.output.write_int32(x); |
| 425 |
packet.output.write_int32(y); |
| 426 |
netobj.send(0, packet); |
| 427 |
} |
| 428 |
}; |
| 429 |
|
| 430 |
class ClientWorld |
| 431 |
{ |
| 432 |
public: |
| 433 |
CL_NetObject_Controller controller; |
| 434 |
CL_Slot slot; |
| 435 |
std::list<ClientObject *> objects; |
| 436 |
|
| 437 |
ClientWorld(CL_NetSession &netsession) |
| 438 |
: controller("netobj_channel", netsession) |
| 439 |
{ |
| 440 |
slot = controller.sig_create_object().connect( |
| 441 |
this, &ClientWorld::on_create_object); |
| 442 |
} |
| 443 |
|
| 444 |
void on_create_object( |
| 445 |
CL_NetObject_Client &netobj, int msgtype, CL_NetPacket &packet) |
| 446 |
{ |
| 447 |
if (msgtype != 0) |
| 448 |
{ |
| 449 |
// not a update message. we can only create object |
| 450 |
// based on an update message. |
| 451 |
return; |
| 452 |
} |
| 453 |
|
| 454 |
objects.push_back(new ClientObject(netobj, packet)); |
| 455 |
} |
| 456 |
}; |
| 457 |
</pre> |
| 458 |
|
| 459 |
</body> |
| 460 |
</xml> |