1 /* This file is part of the Spring engine (GPL v2 or later), see LICENSE.html */ 2 3 #ifndef S_AI_INTERFACE_LIBRARY_H 4 #define S_AI_INTERFACE_LIBRARY_H 5 6 /* 7 * All this is not needed when building an AI, 8 * as it is strictly AI Interface related, 9 * and therefore only matters to the engine and AI Interfaces. 10 */ 11 #if !defined BUILDING_SKIRMISH_AI 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * [string] 19 * Absolute data dir containing the AIs AIInfo.lua file. 20 * This property is set by the engine, not read from any file. 21 * example: "/home/john/spring/AI/Interfaces/C/0.1" 22 */ 23 #define AI_INTERFACE_PROPERTY_DATA_DIR "dataDir" 24 25 /** 26 * [string] 27 * Absolute, version independent data dir. 28 * This property is set by the engine, not read from any file. 29 * example: "/home/john/spring/AI/Interfaces/C/common" 30 */ 31 #define AI_INTERFACE_PROPERTY_DATA_DIR_COMMON "dataDirCommon" 32 33 /** 34 * [string: [a-zA-Z0-9_.]*] 35 * example: "C" 36 */ 37 #define AI_INTERFACE_PROPERTY_SHORT_NAME "shortName" 38 39 /** 40 * [string: [a-zA-Z0-9_.]*] 41 * example: "0.1" 42 */ 43 #define AI_INTERFACE_PROPERTY_VERSION "version" 44 45 /** 46 * [string] 47 * example: "C/C++" 48 */ 49 #define AI_INTERFACE_PROPERTY_NAME "name" 50 51 /** 52 * [string] 53 * example: "supports loading native AIs written in C and/or C++" 54 */ 55 #define AI_INTERFACE_PROPERTY_DESCRIPTION "description" 56 57 /** 58 * [string] 59 * example: "http://springrts.com/wiki/AIInterface:C" 60 */ 61 #define AI_INTERFACE_PROPERTY_URL "url" 62 63 /** 64 * [string] 65 * example: "C, C++" 66 */ 67 #define AI_INTERFACE_PROPERTY_SUPPORTED_LANGUAGES "supportedLanguages" 68 69 /** 70 * [int] 71 * The engine version number the AI Interface was compiled for, 72 * though it may work with newer or older engine versions too. 73 */ 74 #define AI_INTERFACE_PROPERTY_ENGINE_VERSION "engineVersion" 75 76 /** 77 * [bool] 78 * Whether the AI Interface suports dynamic (at runtime) lookup of available 79 * Skirmish AIs through the list* functions, in addition to the ones defined 80 * through AIInfo.lua files. 81 * example: "0", "1", "false", "true" 82 */ 83 #define AI_INTERFACE_PROPERTY_SUPPORTS_LOOKUP "supportsLookup" 84 85 /* 86 * Everything following is (code wise) only interesting for the engine, 87 * not for AI Interfaces. 88 */ 89 #if !defined BUILDING_AI 90 91 #include "System/exportdefines.h" 92 //#include "ELevelOfSupport.h" 93 94 //enum ELevelOfSupport; 95 struct SSkirmishAILibrary; 96 struct SStaticGlobalData; 97 98 /** 99 * @brief Artificial Intelligence Interface library interface 100 * 101 * This is the interface between the engine and an implementation of 102 * an AI Interface. 103 * The engine will address AI Interfaces through this interface, 104 * but AI Interfaces will not actually implement it. It is the job 105 * of the engine, to make sure it can address AI Interface 106 * implementations through instances of this struct. 107 * 108 * An example of loading the C AI Interface: 109 * The C AI Interface library exports functions fitting the 110 * function pointers in this struct. When the engine needs therefore 111 * C AI Interface, it loads the shared library, eg C-AI-Interface.dll, 112 * creates a new instance of this struct, and sets the member function 113 * pointers to the addresses of the fitting functions exported 114 * by the shared library. The functions of the AI Interface are then 115 * allways called through this struct. 116 */ 117 struct SAIInterfaceLibrary { 118 119 // static AI interface library functions 120 121 /** 122 * This function is called right after the library is dynamically loaded. 123 * It can be used to initialize variables and to check or prepare 124 * the environment (os, engine, filesystem, ...). 125 * @see releaseStatic() 126 * 127 * [optional] 128 * An AI Interface not exporting this function is still valid. 129 * 130 * @param staticGlobalData contains global data about the engine and the 131 * environment; is guaranteed to be valid till 132 * releaseStatic() is called. 133 * @return 0: ok 134 * != 0: error 135 */ 136 int (CALLING_CONV *initStatic)(int interfaceId, 137 const struct SAIInterfaceCallback* const); 138 139 /** 140 * This function is called right right before the library is unloaded. 141 * It can be used to deinitialize variables and to cleanup the environment, 142 * for example the filesystem. 143 * 144 * See also initStatic(). 145 * 146 * [optional] 147 * An AI Interface not exporting this function is still valid. 148 * 149 * @return 0: ok 150 * != 0: error 151 */ 152 int (CALLING_CONV *releaseStatic)(); 153 154 // /** 155 // * Level of Support for a specific engine version. 156 // * 157 // * [optional] 158 // * An AI Interface not exporting this function is still valid. 159 // */ 160 // enum LevelOfSupport (CALLING_CONV *getLevelOfSupportFor)( 161 // const char* engineVersionString, int engineVersionNumber); 162 163 164 // skirmish AI methods 165 166 /** 167 * Loads the specified Skirmish AI. 168 * 169 * @return 0: ok 170 * != 0: error 171 */ 172 const struct SSkirmishAILibrary* (CALLING_CONV *loadSkirmishAILibrary)( 173 const char* const shortName, 174 const char* const version); 175 176 /** 177 * Unloads the specified Skirmish AI. 178 * 179 * @return 0: ok 180 * != 0: error 181 */ 182 int (CALLING_CONV *unloadSkirmishAILibrary)( 183 const char* const shortName, 184 const char* const version); 185 186 /** 187 * Unloads all Skirmish AI libraries currently loaded by this interface. 188 * 189 * @return 0: ok 190 * != 0: error 191 */ 192 int (CALLING_CONV *unloadAllSkirmishAILibraries)(); 193 194 /** 195 * Dynamic Skirmish AI library lookup system entry method. 196 * This system works as an alternative/addition to AIInfo.lua and 197 * AIOptions.lua files. 198 * 199 * [optional] 200 * An AI Interface not exporting this function is still valid. 201 * 202 * @see AI_INTERFACE_PROPERTY_SUPPORTS_LOOKUP 203 * @see listSkirmishAILibraryInfos 204 * @see listSkirmishAILibraryOptions 205 * @return the number of Skirmish AI libraries available through this 206 * interface through the dynamic lookup system 207 */ 208 int (CALLING_CONV *listSkirmishAILibraries)(int interfaceId); 209 210 /** 211 * Returns the number of info key-value pairs for a certain Skirmish AI 212 * library. 213 * 214 * [optional] 215 * An AI Interface not exporting this function is still valid. 216 * 217 * @see listSkirmishAILibraries 218 * @see listSkirmishAILibraryInfoKey 219 * @see listSkirmishAILibraryInfoValue 220 * @return the number of info key-value pairs for a certain Skirmish AI 221 * library. 222 */ 223 int (CALLING_CONV *listSkirmishAILibraryInfos)(int interfaceId, 224 int aiIndex); 225 /** 226 * Returns the key of an info item for a certain Skirmish AI library. 227 * 228 * [optional] 229 * An AI Interface not exporting this function is still valid. 230 * 231 * @see listSkirmishAILibraryInfos 232 * @see listSkirmishAILibraryInfoValue 233 * @return the key of an info item for a certain Skirmish AI library. 234 */ 235 const char* (CALLING_CONV *listSkirmishAILibraryInfoKey)(int interfaceId, 236 int aiIndex, int infoIndex); 237 /** 238 * Returns the value of an info item for a certain Skirmish AI library. 239 * 240 * [optional] 241 * An AI Interface not exporting this function is still valid. 242 * 243 * @see listSkirmishAILibraryInfos 244 * @see listSkirmishAILibraryInfoKey 245 * @return the value of an info item for a certain Skirmish AI library. 246 */ 247 const char* (CALLING_CONV *listSkirmishAILibraryInfoValue)(int interfaceId, 248 int aiIndex, int infoIndex); 249 250 /** 251 * Returns a string consisting of Lua code, that returns an options table. 252 * 253 * [optional] 254 * An AI Interface not exporting this function is still valid. 255 * 256 * @see listSkirmishAILibraries 257 * @return NULL for no options, otherwise 258 * a string consisting of Lua code that returns an options table 259 */ 260 const char* (CALLING_CONV *listSkirmishAILibraryOptions)(int interfaceId, 261 int aiIndex); 262 }; 263 264 #endif // !defined BUILDING_AI 265 266 #ifdef __cplusplus 267 } // extern "C" 268 #endif 269 270 #endif // !defined BUILDING_SKIRMISH_AI 271 #endif // S_AI_INTERFACE_LIBRARY_H 272