1 /*

     2  * Hedgewars, a free turn based strategy game

     3  * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com>

     4  *

     5  * This program is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU General Public License

     7  * as published by the Free Software Foundation; either version 2

     8  * of the License, or (at your option) any later version.

     9  *

    10  * This program is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    13  * GNU General Public License for more details.

    14  *

    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

    17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

    18  */

    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 

    40 #ifndef GAMECONN_H_

    41 #define GAMECONN_H_

    42 

    43 #include "../model/gamesetup.h"

    44 

    45 #include <stddef.h>

    46 #include <stdint.h>

    47 #include <stdbool.h>

    48 

    49 /*

    50  * Different reasons for a disconnect. Only GAME_END_FINISHED signals a correctly completed game.

    51  */

    52 #define GAME_END_FINISHED 0

    53 #define GAME_END_INTERRUPTED 1

    54 #define GAME_END_HALTED 2

    55 #define GAME_END_ERROR 3

    56 

    57 typedef struct _flib_gameconn flib_gameconn;

    58 

    59 /**

    60  * Create a gameconn that will start a local or network game with the indicated configuration.

    61  */

    62 flib_gameconn *flib_gameconn_create(const char *playerName, const flib_gamesetup *setup, bool netgame);

    63 

    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  */

    80 flib_gameconn *flib_gameconn_create_campaign(const char *playerName, const char *seed, const char *script);

    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  */

    86 void flib_gameconn_destroy(flib_gameconn *conn);

    87 

    88 /**

    89  * Returns the port on which the gameconn is listening. Only fails if you

    90  * pass NULL (not allowed), in that case 0 is returned.

    91  */

    92 int flib_gameconn_getport(flib_gameconn *conn);

    93 

    94 /**

    95  * Perform I/O operations and call callbacks if something interesting happens.

    96  * Should be called regularly.

    97  */

    98 void flib_gameconn_tick(flib_gameconn *conn);

    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  */

   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  */

   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  */

   123 int flib_gameconn_send_chatmsg(flib_gameconn *conn, const char *playername, const char *msg);

   124 

   125 /**

   126  * Request the engine to stop the game (efinish).

   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  * Send an arbitrary command to the engine, e.g. "eforcequit" to shut down the engine

   133  * quickly. Commands prefixed with "e" will be processed by the engine's ProcessCommand

   134  * method (with the e removed, so e.g. efinish will be parsed as finish).

   135  */

   136 int flib_gameconn_send_cmd(flib_gameconn *conn, const char *cmdString);

   137 

   138 /**

   139  * Expected callback signature: void handleConnect(void *context)

   140  * The engine has successfully connected. You don't have to react to this in any way.

   141  */

   142 void flib_gameconn_onConnect(flib_gameconn *conn, void (*callback)(void* context), void* context);

   143 

   144 /**

   145  * Expected callback signature: void handleDisconnect(void *context, int reason)

   146  * The connection to the engine was closed, either because the game has ended normally, or

   147  * because it was interrupted/halted, or because of an error. The reason is provided as one

   148  * of the GAME_END_xxx constants.

   149  *

   150  * You should destroy the gameconn and - in a netgame - notify the server that the game has ended.

   151  */

   152 void flib_gameconn_onDisconnect(flib_gameconn *conn, void (*callback)(void* context, int reason), void* context);

   153 

   154 /**

   155  * Expected callback signature: void handleErrorMessage(void* context, const char *msg)

   156  * The engine sent an error message, you should probably display it to the user or at least log it.

   157  */

   158 void flib_gameconn_onErrorMessage(flib_gameconn *conn, void (*callback)(void* context, const char *msg), void* context);

   159 

   160 /**

   161  * Expected callback signature: void handleChat(void* context, const char *msg, bool teamchat)

   162  * The player entered a chat or teamchat message. In a netgame, you should send it on to the server.

   163  */

   164 void flib_gameconn_onChat(flib_gameconn *conn, void (*callback)(void* context, const char *msg, bool teamchat), void* context);

   165 

   166 /**

   167  * Expected callback signature: void handleGameRecorded(void *context, const uint8_t *record, size_t size, bool isSavegame)

   168  * The game has stopped, and a demo or savegame is available. You can store it in a file and later pass it back

   169  * to the engine to either watch a replay (if it's a demo) or to continue playing (if it's a savegame).

   170  */

   171 void flib_gameconn_onGameRecorded(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *record, size_t size, bool isSavegame), void* context);

   172 

   173 /**

   174  * Expected callback signature: void handleEngineMessage(void *context, const uint8_t *em, size_t size)

   175  * The engine has generated a message with player input. In a netgame, you should send it on to the server.

   176  */

   177 void flib_gameconn_onEngineMessage(flib_gameconn *conn, void (*callback)(void *context, const uint8_t *em, size_t size), void* context);

   178 

   179 #endif