15 * You should have received a copy of the GNU General Public License |
15 * You should have received a copy of the GNU General Public License |
16 * along with this program; if not, write to the Free Software |
16 * along with this program; if not, write to the Free Software |
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 */ |
18 */ |
19 |
19 |
|
20 /** |
|
21 * This file contains functions for starting and interacting with a game run by the engine. |
|
22 * The general usage is to first create a gameconn object by calling one of the flib_gameconn_create |
|
23 * functions. That will cause the frontlib to listen on a random port which can be queried using |
|
24 * flib_gameconn_getport(). You should also register your callback functions right at the start |
|
25 * to ensure you don't miss any callbacks. |
|
26 * |
|
27 * Next, start the engine (that part is up to you) with the appropriate command line arguments |
|
28 * for starting a game. |
|
29 * |
|
30 * In order to allow the gameconn to run, you should regularly call flib_gameconn_tick(), which |
|
31 * performs network I/O and calls your callbacks on interesting events. |
|
32 * |
|
33 * Once the engine connects, the gameconn will send it the required commands for starting the |
|
34 * game you requested in your flib_gameconn_create call. |
|
35 * |
|
36 * When the game is finished (or the connection is lost), you will receive the onDisconnect |
|
37 * message. This is the signal to destroy the gameconn and stop calling tick(). |
|
38 */ |
|
39 |
20 #ifndef GAMECONN_H_ |
40 #ifndef GAMECONN_H_ |
21 #define GAMECONN_H_ |
41 #define GAMECONN_H_ |
22 |
42 |
23 #include "../model/gamesetup.h" |
43 #include "../model/gamesetup.h" |
24 |
44 |
25 #include <stddef.h> |
45 #include <stddef.h> |
26 #include <stdint.h> |
46 #include <stdint.h> |
27 #include <stdbool.h> |
47 #include <stdbool.h> |
28 |
48 |
|
49 /* |
|
50 * Different reasons for a disconnect. Only GAME_END_FINISHED signals a correctly completed game. |
|
51 */ |
29 #define GAME_END_FINISHED 0 |
52 #define GAME_END_FINISHED 0 |
30 #define GAME_END_INTERRUPTED 1 |
53 #define GAME_END_INTERRUPTED 1 |
31 #define GAME_END_HALTED 2 |
54 #define GAME_END_HALTED 2 |
32 #define GAME_END_ERROR 3 |
55 #define GAME_END_ERROR 3 |
33 |
56 |
34 typedef struct _flib_gameconn flib_gameconn; |
57 typedef struct _flib_gameconn flib_gameconn; |
35 |
58 |
|
59 /** |
|
60 * Create a gameconn that will start a local or network game with the indicated configuration. |
|
61 */ |
36 flib_gameconn *flib_gameconn_create(const char *playerName, const flib_gamesetup *setup, bool netgame); |
62 flib_gameconn *flib_gameconn_create(const char *playerName, const flib_gamesetup *setup, bool netgame); |
37 flib_gameconn *flib_gameconn_create_playdemo(const uint8_t *demo, size_t size); |
63 |
38 flib_gameconn *flib_gameconn_create_loadgame(const char *playerName, const uint8_t *save, size_t size); |
64 /** |
|
65 * Create a gameconn that will play back a demo. |
|
66 */ |
|
67 flib_gameconn *flib_gameconn_create_playdemo(const uint8_t *demoFileContent, size_t size); |
|
68 |
|
69 /** |
|
70 * Create a gameconn that will continue from a saved game. |
|
71 */ |
|
72 flib_gameconn *flib_gameconn_create_loadgame(const char *playerName, const uint8_t *saveFileContent, size_t size); |
|
73 |
|
74 /** |
|
75 * Create a gameconn that will start a campaign or training mission with the indicated script. |
|
76 * seed is the random seed to use as entropy source (any string). |
|
77 * script is the path and filename of a Campaign or Training script, relative to the Data directory |
|
78 * (e.g. "Missions/Training/Basic_Training_-_Bazooka.lua") |
|
79 */ |
39 flib_gameconn *flib_gameconn_create_campaign(const char *playerName, const char *seed, const char *script); |
80 flib_gameconn *flib_gameconn_create_campaign(const char *playerName, const char *seed, const char *script); |
40 |
81 |
|
82 /** |
|
83 * Release all resources of this gameconn, including the network connection, and free its memory. |
|
84 * It is safe to call this function from a callback. |
|
85 */ |
41 void flib_gameconn_destroy(flib_gameconn *conn); |
86 void flib_gameconn_destroy(flib_gameconn *conn); |
42 |
87 |
43 /** |
88 /** |
44 * Returns the port on which the gameconn is listening. Only fails if you |
89 * Returns the port on which the gameconn is listening. Only fails if you |
45 * pass NULL (not allowed), in that case 0 is returned. |
90 * pass NULL (not allowed), in that case 0 is returned. |
50 * Perform I/O operations and call callbacks if something interesting happens. |
95 * Perform I/O operations and call callbacks if something interesting happens. |
51 * Should be called regularly. |
96 * Should be called regularly. |
52 */ |
97 */ |
53 void flib_gameconn_tick(flib_gameconn *conn); |
98 void flib_gameconn_tick(flib_gameconn *conn); |
54 |
99 |
|
100 /** |
|
101 * Send an engine message to the engine. Only needed in net games, where you receive engine |
|
102 * messages from the server and have to pass them here. |
|
103 */ |
55 int flib_gameconn_send_enginemsg(flib_gameconn *conn, const uint8_t *data, size_t len); |
104 int flib_gameconn_send_enginemsg(flib_gameconn *conn, const uint8_t *data, size_t len); |
|
105 |
|
106 /** |
|
107 * Send an info message to the engine that will be displayed in the game's chatlog. |
|
108 * The msgtype determines the color of the message; in the QTFrontend, info messages and |
|
109 * normal chat messages use 1, emote-messages (those starting with /me) use 2, and |
|
110 * join/leave messages use 3. You should use flib_gameconn_send_chatmsg for chat messages |
|
111 * though because it automatically formats /me messages. |
|
112 * |
|
113 * Generally only needed in net games. |
|
114 */ |
56 int flib_gameconn_send_textmsg(flib_gameconn *conn, int msgtype, const char *msg); |
115 int flib_gameconn_send_textmsg(flib_gameconn *conn, int msgtype, const char *msg); |
|
116 |
|
117 /** |
|
118 * Send a chat message to be displayed in the game's chatlog. Messages starting with /me are |
|
119 * automatically formatted correctly. |
|
120 * |
|
121 * Generally only needed in net games. |
|
122 */ |
57 int flib_gameconn_send_chatmsg(flib_gameconn *conn, const char *playername, const char *msg); |
123 int flib_gameconn_send_chatmsg(flib_gameconn *conn, const char *playername, const char *msg); |
58 |
124 |
59 /** |
125 /** |
60 * handleConnect(void *context) |
126 * Request the engine to stop the game. |
|
127 * You can use this to shut down a game early without directly killing the engine process. |
|
128 */ |
|
129 int flib_gameconn_send_quit(flib_gameconn *conn); |
|
130 |
|
131 /** |
|
132 * Expected callback signature: void handleConnect(void *context) |
|
133 * The engine has successfully connected. You don't have to react to this in any way. |
61 */ |
134 */ |
62 void flib_gameconn_onConnect(flib_gameconn *conn, void (*callback)(void* context), void* context); |
135 void flib_gameconn_onConnect(flib_gameconn *conn, void (*callback)(void* context), void* context); |
63 |
136 |
64 /** |
137 /** |
65 * handleDisconnect(void *context, int reason) |
138 * Expected callback signature: void handleDisconnect(void *context, int reason) |
|
139 * The connection to the engine was closed, either because the game has ended normally, or |
|
140 * because it was interrupted/halted, or because of an error. The reason is provided as one |
|
141 * of the GAME_END_xxx constants. |
|
142 * |
|
143 * You should destroy the gameconn and - in a netgame - notify the server that the game has ended. |
66 */ |
144 */ |
67 void flib_gameconn_onDisconnect(flib_gameconn *conn, void (*callback)(void* context, int reason), void* context); |
145 void flib_gameconn_onDisconnect(flib_gameconn *conn, void (*callback)(void* context, int reason), void* context); |
68 |
146 |
69 /** |
147 /** |
70 * Receives error messages sent by the engine |
148 * Expected callback signature: void handleErrorMessage(void* context, const char *msg) |
71 * handleErrorMessage(void* context, const char *msg) |
149 * The engine sent an error message, you should probably display it to the user or at least log it. |
72 */ |
150 */ |
73 void flib_gameconn_onErrorMessage(flib_gameconn *conn, void (*callback)(void* context, const char *msg), void* context); |
151 void flib_gameconn_onErrorMessage(flib_gameconn *conn, void (*callback)(void* context, const char *msg), void* context); |
74 |
152 |
75 /** |
153 /** |
76 * handleChat(void* context, const char *msg, bool teamchat) |
154 * Expected callback signature: void handleChat(void* context, const char *msg, bool teamchat) |
|
155 * The player entered a chat or teamchat message. In a netgame, you should send it on to the server. |
77 */ |
156 */ |
78 void flib_gameconn_onChat(flib_gameconn *conn, void (*callback)(void* context, const char *msg, bool teamchat), void* context); |
157 void flib_gameconn_onChat(flib_gameconn *conn, void (*callback)(void* context, const char *msg, bool teamchat), void* context); |
79 |
158 |
80 /** |
159 /** |
81 * Called when the game ends |
160 * Expected callback signature: void handleGameRecorded(void *context, const uint8_t *record, size_t size, bool isSavegame) |
82 * handleGameRecorded(void *context, const uint8_t *record, int size, bool isSavegame) |
161 * The game has stopped, and a demo or savegame is available. You can store it in a file and later pass it back |
|
162 * to the engine to either watch a replay (if it's a demo) or to continue playing (if it's a savegame). |
83 */ |
163 */ |
84 void flib_gameconn_onGameRecorded(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *record, size_t size, bool isSavegame), void* context); |
164 void flib_gameconn_onGameRecorded(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *record, size_t size, bool isSavegame), void* context); |
85 |
165 |
86 /** |
166 /** |
87 * Called when the game ends |
167 * Expected callback signature: void handleEngineMessage(void *context, const uint8_t *em, size_t size) |
88 * TODO handleStats(???) |
168 * The engine has generated a message with player input. In a netgame, you should send it on to the server. |
89 */ |
|
90 |
|
91 /** |
|
92 * ...needs to be passed on to the server in a net game |
|
93 * handleEngineMessage(void *context, const uint8_t *em, size_t size) |
|
94 */ |
169 */ |
95 void flib_gameconn_onEngineMessage(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *em, size_t size), void* context); |
170 void flib_gameconn_onEngineMessage(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *em, size_t size), void* context); |
96 |
171 |
97 // TODO efinish |
|
98 |
|
99 #endif |
172 #endif |