File indexing completed on 2025-02-02 03:58:48
0001 <html> 0002 <head> 0003 <title>Documentation for libkdegames</title> 0004 <meta content=""> 0005 <style></style> 0006 </head> 0007 <body> 0008 <H1>Documentation for the classes in libkdegames</H1> 0009 <!--------------------------------------------------------------------------------> 0010 <H3>Design Principles</H3> 0011 The library <em>kdegames</em> contains a collection of classes that can be used 0012 to develop games using the KDE environment very easily. There are a few 0013 principles that were used when developing the library:<P> 0014 0015 <UL> 0016 <LI><b>usable for a big variety of games</b><br> 0017 The class <em>KGame</em> provides many features that are needed in many games. 0018 It can be used for board games, card games, maze games, simulation games, strategy games and 0019 many more.<br> 0020 It does not (yet) include special features for realtime games, but can be used there, too. 0021 <LI><b>features one-player and multi-player games</b></br> 0022 A game developed with this library can easily support any number of simultaneous players. 0023 So use it for one-player games (like Tetris or KSame), for two-player games (like TicTacToe 0024 or chess) or for games with an arbitrary number of players. 0025 <LI><b>computer players can easily be developed</b><br> 0026 The class <em>KPlayer</em> represents an abstract player in a game. This can be a 0027 human player that gets the input from the mouse or the keyboard. Or it can be a computer 0028 player that makes moves by random or with artificial intelligence. All this can be achieved 0029 subclassing KPlayer. 0030 <LI><b>support for network games transparently</b><br> 0031 The class <em>KGame</em> contains lots of features for network game support. Developing 0032 a network game using a TCP/IP connection is very easy this way. But the default 0033 case is still the local game. So the user should not need to connect to the internet 0034 or to select a game server to play a game. 0035 <LI><b>support for turn based and for asynchronous games</b><br> 0036 You can use this library for turn based games, when only one player can make a move at a time 0037 (like most bord games or card games), but also for asynchronous games, when every player can 0038 make a move any time (like many action games). 0039 </UL> 0040 <!--------------------------------------------------------------------------------> 0041 <H3>The central game class: <em>KGame</em></H3> 0042 0043 When you want to develop your own KDE game using the KDE games library, you most likely want 0044 to use the <em>KGame</em> class. There are two possible ways to extend it to your own needs: 0045 Create a subclass and overwrite the virtual methods, or simply create an instance of KGame 0046 and connect to the appropriate signals.<P> 0047 0048 <<more code about KGame, an easy example>> 0049 0050 <!--------------------------------------------------------------------------------> 0051 <H3>Network games and related classes</H3> 0052 0053 One of the main principles in the design of <em>KGame</em> was to make network games possible 0054 with a minimum of effort for the game developer.<P> 0055 0056 A network game is a game with usually several players, that are on different computers. These 0057 computers are usually connected to the internet, and all the moves a player does are exchanged 0058 over this network.<P> 0059 0060 The exchange of moves and other information is done using the class <em>KMessageServer</em>. 0061 An object of this class is a server that waits for connections. Someone who wants to take part 0062 in the game has to connect to this server - usually using an internet socket connection. He does 0063 this by creating a <em>KMessageClient</em> object. This object connects to the message server.<P> 0064 0065 The transfer of data is realised by subclasses of the abstract class <em>KMessageIO</em>. One object 0066 of this class is created on the client side, one on the server side. Different types of networks can 0067 be supported by creating new subclasses of KMessageIO. There are already two subclasses of KMessageIO: 0068 <em>KMessageSocket</em> uses a internet socket connection to transfer the data from the message client 0069 to the message server or vice versa. <em>KMessageDirect</em> can be used if both the message server and 0070 the message client are within the same process. The data blocks are copied directly to the other side, 0071 so the transfer is faster and needs no network bandwidth.<P> 0072 0073 A typical network game situation could look like this:<P> 0074 0075 <IMG SRC="kmessageserver.png"><P> 0076 0077 Here, three KGame object (called message clients) are connected to the KMessageServer object. One 0078 is in the same process, so it uses KMessageDirect. The other two use KMessageSocket, so an internet 0079 socket connection is used. KGame doesn't talk directly to the message server, but uses a KMessageClient 0080 object instead. One of the KMessageClient objects is the admin of the message server. This client has some 0081 priviledges. It may e.g. kill the connection to other message clients, or limit the number of clients 0082 that may connect.<P> 0083 0084 The KGame objects are by default all equal. So the usual approach will be that every KGame object will 0085 store the complete status of the game, and any change or move will be broadcasted to the other KGame 0086 objects, so that they all change the status in identical ways. Sometimes it may be necessary (or just 0087 easier to implement) that one KGame object is a <em>game server</em> (i.e. he is repsonsible for everything, 0088 he coordinates the complete game and stores the game status), whereas the other KGame objects are 0089 only dumb stubs that are used to contact the <em>game server</em>. You can implement both approaches 0090 using the message server structure. If you need to elect the KGame object that shall be 0091 the game server, you may e.g. use the one that has the KMessageClient that is the admin of the message 0092 server. (Of course this is only a suggestion, you can use other approaches.)<P> 0093 0094 The main principle when developing the message server/client structure was, that the message server 0095 doesn't have <em>any</em> idea of the game and its rules that is played. The message server only forwards 0096 messages from one message client to the others without interpreting or manipulating the data. So always 0097 keep in mind that the message server is <em>not</em> a game server! It does not store any data about 0098 the game status. It is only a server for network connections and message broadcasting, <em>not</em> 0099 for game purposes. The reason for this principle is, that <em>any</em> game can be played using a 0100 KMessageServer on any computer. The computer being the message server doesn't need to know anything 0101 about the game that is played on it. So you don't have to install new versions of the game there. Only 0102 the clients need to be game specific.<P> 0103 0104 Usually you don't need to create <em>KMessageServer</em> or <em>KMessageClient</em> objects in your game, 0105 since <em>KGame</em> does this for you. There are three different scenarios fo network games that are 0106 all supported in <em>KGame</em>:<P> 0107 0108 <b>Scenario 1: local game</b><P> 0109 0110 The local game should always be the default state a game should be in. To avoid having this scenario 0111 as a special case, <em>KGame</em> automatically creates a KMessageServer object and a KMessageClient 0112 object. So every change and every move is sent to the message server and is returned to the KGame 0113 object before it is processed. Since the connection between the message client and the message server 0114 uses KMessageDirect the data transfer is very fast and wont hurt in most cases.<P> 0115 0116 <IMG SRC="scenario0.png"><P> 0117 0118 This is the default situation right after creating the <em>KGame</em> object.<P> 0119 0120 <b>Scenario 2: network game, started by one player</b><P> 0121 0122 If one user is bored of playing alone, he can open his game for connections from the outside world. 0123 He listens to a TCP/IP socket port (i.e. a number between 0 and 65535). Other players can create 0124 KGame objects of their own and connect to this port. They need to know the IP address of that computer 0125 and the port number. This situation will have this structure: 0126 0127 <IMG SRC="scenario1.png"><P> 0128 0129 The first player has to do something like:<P> 0130 0131 <PRE> 0132 KGame *myGame = new KGame (); 0133 // wait for connections on port 12345 0134 myGame->offerConnections (12345); 0135 </PRE> 0136 0137 And the other players have to do something like:<P> 0138 0139 <PRE> 0140 KGame *myGame = new KGame (); 0141 // connect to the message server 0142 myGame->connectToServer ("theServer.theDomain.com", 12345); 0143 </PRE> 0144 0145 This automatically removes the message server in these KGame objects and connects to the given 0146 one instead.<P> 0147 0148 <b>Scenario 3: network game, using a stand alone message server</b><P> 0149 0150 Sometimes it is not possible to let the message server run on one of the players computer. If e.g. all 0151 the players have their computer in a local network that uses masquerading to contact the internet, 0152 other computers cannot connect to them since the computer doesn't have a IP address to the outside 0153 world. Then the only way to play a network game is to have a standalone KMessageServer object on 0154 another server computer (somthing like "games.kde.org" e.g.). Since the KMessageServer isn't game 0155 specific at all, every game can be played using it. There doesn't have to be any special software 0156 installed on that server computer, only the program creating a KMessageServer object.<P> 0157 0158 This scenario has some more advantages: The message server can be a well known meeting point to 0159 start a game. This way one could play games against other players you never knew before. Furthermore 0160 the game is stopped brutally when the program that contains the message server in scenario 2 is 0161 quitted. (Migration of message servers is not yet implemented, but may be in the future.) Using a 0162 stand alone message server, the players may enter and leave the game as they want. 0163 0164 <IMG SRC="scenario2.png"><P> 0165 0166 To create this scenario, a special KMessageServer program has to be started on the computer 0167 that shall be the stand alone message server:<P> 0168 0169 <PRE> 0170 % kmessageserver -port=12345 0171 </PRE> 0172 0173 The other games that want to connect have to do this (supposed the stand alone message server 0174 has the IP address "games.kde.org"):<P> 0175 0176 <PRE> 0177 KGame *myGame = new KGame (); 0178 // connect to the message server 0179 myGame->connectToServer ("games.kde.org", 12345); 0180 </PRE> 0181 0182 0183 0184 0185 <!--------------------------------------------------------------------------------> 0186 </body> 0187 </html>