1 /* This file is part of the Spring engine (GPL v2 or later), see LICENSE.html */ 2 3 #ifndef S_SKIRMISH_AI_LIBRARY_H 4 #define S_SKIRMISH_AI_LIBRARY_H 5 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 /** 11 * [string] 12 * Absolute data dir containing the AIs AIInfo.lua file. 13 * This property is set by the engine, not read from any file. 14 * example: "/home/john/spring/AI/Skirmish/RAI/0.601" 15 */ 16 #define SKIRMISH_AI_PROPERTY_DATA_DIR "dataDir" 17 18 /** 19 * [string] 20 * Absolute, version independent data dir. 21 * This property is set by the engine, not read from any file. 22 * example: "/home/john/spring/AI/Skirmish/RAI/common" 23 */ 24 #define SKIRMISH_AI_PROPERTY_DATA_DIR_COMMON "dataDirCommon" 25 26 /** 27 * [string: [a-zA-Z0-9_.]*] 28 * example: "RAI" 29 */ 30 #define SKIRMISH_AI_PROPERTY_SHORT_NAME "shortName" 31 32 /** 33 * [string: [a-zA-Z0-9_.]*] 34 * example: "0.601" 35 */ 36 #define SKIRMISH_AI_PROPERTY_VERSION "version" 37 38 /** 39 * [string] 40 * example: "Reth's Skirmish AI" 41 */ 42 #define SKIRMISH_AI_PROPERTY_NAME "name" 43 44 /** 45 * [string] 46 * example: "no config files required, works well with TA based mods and more" 47 */ 48 #define SKIRMISH_AI_PROPERTY_DESCRIPTION "description" 49 50 /** 51 * [string] 52 * example: "http://springrts.com/wiki/AI:RAI" 53 */ 54 #define SKIRMISH_AI_PROPERTY_URL "url" 55 56 /** [bool: "yes" | "no"] */ 57 #define SKIRMISH_AI_PROPERTY_LOAD_SUPPORTED "loadSupported" 58 59 /** 60 * [int] 61 * The engine version number the AI was compiled for, 62 * though it may work with newer or older engine versions too. 63 */ 64 #define SKIRMISH_AI_PROPERTY_ENGINE_VERSION "engineVersion" 65 66 /** 67 * [string: [a-zA-Z0-9_.]*] 68 * This AI Interface has to be used to load the AI. 69 * example: "C" 70 */ 71 #define SKIRMISH_AI_PROPERTY_INTERFACE_SHORT_NAME "interfaceShortName" 72 73 /** 74 * [string: [a-zA-Z0-9_.]*] 75 * The AI Interface version number the AI was written for. 76 * This value is seen as a minimum requirement, 77 * so loading the AI with an older version of 78 * the AI Interface will not be attempted. 79 * example: "0.1" 80 */ 81 #define SKIRMISH_AI_PROPERTY_INTERFACE_VERSION "interfaceVersion" 82 83 84 #include "ELevelOfSupport.h" 85 #include "System/exportdefines.h" 86 87 struct SSkirmishAICallback; 88 89 /** 90 * @brief Skirmish Artificial Intelligence library interface 91 * 92 * This is the interface between the engine and an implementation of a 93 * Skirmish AI. 94 * The engine will address AIs through this interface, but AIs will 95 * not actually implement it. It is the job of the AI Interface library, 96 * to make sure the engine can address AI implementations through 97 * instances of this struct. 98 * 99 * An example of loading a C AI through the C AI Interface: 100 * The C AI exports functions fitting the function pointers in this 101 * struct. When the engine requests C-AI-X on the C AI Interface, 102 * the interface loads the shared library, eg C-AI-X.dll, creates 103 * a new instance of this struct, and sets the member function 104 * pointers to the addresses of the fitting functions exported 105 * by the shared AI library. This struct then goes to the engine 106 * which calls the functions appropriately. 107 */ 108 struct SSkirmishAILibrary { 109 110 // static AI library functions 111 112 /** 113 * Level of Support for a specific engine version and AI interface version. 114 * 115 * [optional] 116 * An AI not exporting this function is still valid. 117 * 118 * @param aiShortName this is indisposable for non-native interfaces, 119 * as they need a means of redirecting from 120 * one wrapper function to the respective non-native 121 * libraries 122 * @param aiVersion see aiShortName 123 * @return the level of support for the supplied engine and AI interface 124 * versions 125 */ 126 enum LevelOfSupport (CALLING_CONV *getLevelOfSupportFor)( 127 const char* aiShortName, const char* aiVersion, 128 const char* engineVersionString, int engineVersionNumber, 129 const char* aiInterfaceShortName, const char* aiInterfaceVersion); 130 131 132 // team instance functions 133 134 /** 135 * This function is called, when an AI instance shall be created 136 * for skirmishAIId. It is called before the first call to handleEvent() 137 * for that AI instance. 138 * 139 * A typical series of events (engine point of view, conceptual): 140 * [code] 141 * KAIK.init(1) 142 * KAIK.handleEvent(EVENT_INIT, InitEvent(1)) 143 * RAI.init(2) 144 * RAI.handleEvent(EVENT_INIT, InitEvent(2)) 145 * KAIK.handleEvent(EVENT_UPDATE, UpdateEvent(0)) 146 * RAI.handleEvent(EVENT_UPDATE, UpdateEvent(0)) 147 * KAIK.handleEvent(EVENT_UPDATE, UpdateEvent(1)) 148 * RAI.handleEvent(EVENT_UPDATE, UpdateEvent(1)) 149 * ... 150 * [/code] 151 * 152 * This method exists only for performance reasons, which come into play on 153 * OO languages. For non-OO language AIs, this method can be ignored, 154 * because using only EVENT_INIT will cause no performance decrease. 155 * 156 * [optional] 157 * An AI not exporting this function is still valid. 158 * 159 * @param skirmishAIId the ID this library shall create an instance for 160 * @param callback the callback for this Skirmish AI 161 * @return 0: ok 162 * != 0: error 163 */ 164 int (CALLING_CONV *init)(int skirmishAIId, 165 const struct SSkirmishAICallback* callback); 166 167 /** 168 * This function is called, when an AI instance shall be deleted. 169 * It is called after the last call to handleEvent() for that AI instance. 170 * 171 * A typical series of events (engine point of view, conceptual): 172 * [code] 173 * ... 174 * KAIK.handleEvent(EVENT_UPDATE, UpdateEvent(654321)) 175 * RAI.handleEvent(EVENT_UPDATE, UpdateEvent(654321)) 176 * KAIK.handleEvent(EVENT_UPDATE, UpdateEvent(654322)) 177 * RAI.handleEvent(EVENT_UPDATE, UpdateEvent(654322)) 178 * KAIK.handleEvent(EVENT_RELEASE, ReleaseEvent(1)) 179 * KAIK.release(1) 180 * RAI.handleEvent(EVENT_RELEASE, ReleaseEvent(2)) 181 * RAI.release(2) 182 * [/code] 183 * 184 * This method exists only for performance reasons, which come into play on 185 * OO languages. For non-OO language AIs, this method can be ignored, 186 * because using only EVENT_RELEASE will cause no performance decrease. 187 * 188 * [optional] 189 * An AI not exporting this function is still valid. 190 * 191 * @param skirmishAIId the ID the library shall release the instance of 192 * @return 0: ok 193 * != 0: error 194 */ 195 int (CALLING_CONV *release)(int skirmishAIId); 196 197 /** 198 * Through this function, the AI receives events from the engine. 199 * For details about events that may arrive here, see file AISEvents.h. 200 * 201 * @param skirmishAIId the AI instance the event is addressed to 202 // * @param fromId the id of the AI the event comes from, 203 // * or FROM_ENGINE_ID if it comes from the engine 204 // * @param eventId used on asynchronous events. this allows the AI to 205 // * identify a possible result message, which was sent 206 // * with the same eventId 207 * @param topicId unique identifier of a message 208 * (see EVENT_* defines in AISEvents.h) 209 * @param data an topic specific struct, which contains the data 210 * associatedwith the event 211 * (see S*Event structs in AISEvents.h) 212 * @return 0: ok 213 * != 0: error 214 */ 215 int (CALLING_CONV *handleEvent)(int skirmishAIId, int topicId, 216 const void* data); 217 }; 218 219 #ifdef __cplusplus 220 } // extern "C" 221 #endif 222 223 #endif // S_SKIRMISH_AI_LIBRARY_H 224