1 /* This file is part of the Spring engine (GPL v2 or later), see LICENSE.html */ 2 3 #ifndef AI_S_EVENTS_H 4 #define AI_S_EVENTS_H 5 6 // IMPORTANT NOTE: external systems parse this file, 7 // so DO NOT CHANGE the style and format it uses without 8 // major though in advance, and deliberation with hoijui! 9 10 #ifdef __cplusplus 11 extern "C" { 12 #endif 13 14 // NOTE structs should not be empty (C90), so add a useless member if needed 15 16 #include "SSkirmishAICallback.h" 17 18 /** 19 * Each event type can be identified through a unique ID, 20 * which we call event topic. 21 * Events are sent from the engine to AIs. 22 * 23 * Note: Do NOT change the values assigned to these topics, 24 * as this would be bad for inter-version compatibility. 25 * You should always append new event topics at the end of this list, 26 * and adjust NUM_EVENTS. 27 * 28 * @see SSkirmishAILibrary.handleEvent() 29 */ 30 enum EventTopic { 31 EVENT_NULL = 0, 32 EVENT_INIT = 1, 33 EVENT_RELEASE = 2, 34 EVENT_UPDATE = 3, 35 EVENT_MESSAGE = 4, 36 EVENT_UNIT_CREATED = 5, 37 EVENT_UNIT_FINISHED = 6, 38 EVENT_UNIT_IDLE = 7, 39 EVENT_UNIT_MOVE_FAILED = 8, 40 EVENT_UNIT_DAMAGED = 9, 41 EVENT_UNIT_DESTROYED = 10, 42 EVENT_UNIT_GIVEN = 11, 43 EVENT_UNIT_CAPTURED = 12, 44 EVENT_ENEMY_ENTER_LOS = 13, 45 EVENT_ENEMY_LEAVE_LOS = 14, 46 EVENT_ENEMY_ENTER_RADAR = 15, 47 EVENT_ENEMY_LEAVE_RADAR = 16, 48 EVENT_ENEMY_DAMAGED = 17, 49 EVENT_ENEMY_DESTROYED = 18, 50 EVENT_WEAPON_FIRED = 19, 51 EVENT_PLAYER_COMMAND = 20, 52 EVENT_SEISMIC_PING = 21, 53 EVENT_COMMAND_FINISHED = 22, 54 EVENT_LOAD = 23, 55 EVENT_SAVE = 24, 56 EVENT_ENEMY_CREATED = 25, 57 EVENT_ENEMY_FINISHED = 26, 58 EVENT_LUA_MESSAGE = 27, 59 }; 60 const int NUM_EVENTS = 28; 61 62 63 64 #define AIINTERFACE_EVENTS_ABI_VERSION ( \ 65 sizeof(struct SInitEvent) \ 66 + sizeof(struct SReleaseEvent) \ 67 + sizeof(struct SUpdateEvent) \ 68 + sizeof(struct SMessageEvent) \ 69 + sizeof(struct SUnitCreatedEvent) \ 70 + sizeof(struct SUnitFinishedEvent) \ 71 + sizeof(struct SUnitIdleEvent) \ 72 + sizeof(struct SUnitMoveFailedEvent) \ 73 + sizeof(struct SUnitDamagedEvent) \ 74 + sizeof(struct SUnitDestroyedEvent) \ 75 + sizeof(struct SUnitGivenEvent) \ 76 + sizeof(struct SUnitCapturedEvent) \ 77 + sizeof(struct SEnemyEnterLOSEvent) \ 78 + sizeof(struct SEnemyLeaveLOSEvent) \ 79 + sizeof(struct SEnemyEnterRadarEvent) \ 80 + sizeof(struct SEnemyLeaveRadarEvent) \ 81 + sizeof(struct SEnemyDamagedEvent) \ 82 + sizeof(struct SEnemyDestroyedEvent) \ 83 + sizeof(struct SWeaponFiredEvent) \ 84 + sizeof(struct SPlayerCommandEvent) \ 85 + sizeof(struct SCommandFinishedEvent) \ 86 + sizeof(struct SSeismicPingEvent) \ 87 + sizeof(struct SLoadEvent) \ 88 + sizeof(struct SSaveEvent) \ 89 + sizeof(struct SEnemyCreatedEvent) \ 90 + sizeof(struct SEnemyFinishedEvent) \ 91 + sizeof(struct SLuaMessageEvent) \ 92 ) 93 94 /** 95 * This AI event initializes a Skirmish AI instance. 96 * It is sent only once per AI instance and game, as the very first event. 97 */ 98 struct SInitEvent { 99 int skirmishAIId; 100 const struct SSkirmishAICallback* callback; 101 }; //$ EVENT_INIT 102 103 /** 104 * This AI event tells a Skirmish AI instance, that it is no longer needed. It 105 * can be used to free memory or do other cleanup work. 106 * It is sent only once per AI instance and game, as the very last event. 107 * Values description for reason: 108 * 0: unspecified 109 * 1: game ended 110 * 2: team died 111 * 3: AI killed 112 * 4: AI crashed 113 * 5: AI failed to init 114 * 6: connection lost 115 * 7: other reason 116 */ 117 struct SReleaseEvent { 118 int reason; 119 }; //$ EVENT_RELEASE 120 121 /** 122 * This AI event is sent once per game frame, which is about 30 times per second 123 * by default. 124 */ 125 struct SUpdateEvent { 126 int frame; 127 }; //$ EVENT_UPDATE 128 129 /** 130 * This AI event is a notification about a chat message sent by one of the 131 * participants of this game, which may be a player or an AI, including this AI. 132 */ 133 struct SMessageEvent { 134 int player; 135 const char* message; 136 }; //$ EVENT_MESSAGE 137 138 /** 139 * This AI event triggers whenever any message 140 * is sent by a Lua widget or unsynced gadget. 141 */ 142 struct SLuaMessageEvent { 143 const char* inData; 144 }; //$ EVENT_LUA_MESSAGE 145 146 /** 147 * This AI event is sent whenever a unit of this team is created, and contains 148 * the created unit. Usually, the unit has only 1 HP at this time, and consists 149 * only of a nano frame (-> will not accept commands yet). 150 * See also the unit-finished event. 151 */ 152 struct SUnitCreatedEvent { 153 int unit; 154 int builder; 155 }; //$ EVENT_UNIT_CREATED INTERFACES:Unit(unit),UnitLifeState() 156 157 /** 158 * This AI event is sent whenever a unit is fully built, and contains the 159 * finished unit. Usually, the unit has full health at this time, and is ready 160 * to accept commands. 161 * See also the unit-created event. 162 */ 163 struct SUnitFinishedEvent { 164 int unit; 165 }; //$ EVENT_UNIT_FINISHED INTERFACES:Unit(unit),UnitLifeState() 166 167 /** 168 * This AI event is sent when a unit finished processing a command or just 169 * finished building, and it has currently no commands in it's queue. 170 */ 171 struct SUnitIdleEvent { 172 int unit; 173 }; //$ EVENT_UNIT_IDLE INTERFACES:Unit(unit) 174 175 /** 176 * This AI event is sent when a unit received a move command and is not able to 177 * fullfill it. Reasons for this are: 178 * - The unit is not able to move 179 * - The path to the target location is blocked 180 * - The unit can not move on the terain of the target location (for example, 181 * the target is on land, and the unit is a ship) 182 */ 183 struct SUnitMoveFailedEvent { 184 int unit; 185 }; //$ EVENT_UNIT_MOVE_FAILED INTERFACES:Unit(unit) 186 187 /** 188 * This AI event is sent when a unit was damaged. It contains the attacked unit, 189 * the attacking unit, the ammount of damage and the direction from where the 190 * damage was inflickted. In case of a laser weapon, the direction will point 191 * directly from the attacker to the attacked unit, while with artillery it will 192 * rather be from somewhere up in the sky to the attacked unit. 193 * See also the unit-destroyed event. 194 */ 195 struct SUnitDamagedEvent { 196 int unit; 197 /** 198 * may be -1, which means no attacker was directly involveld, 199 * or the attacker is not visible and cheat events are off 200 */ 201 int attacker; 202 float damage; 203 float* dir_posF3; 204 int weaponDefId; 205 /// if true, then damage is paralyzation damage, otherwise it is real damage 206 bool paralyzer; 207 }; //$ EVENT_UNIT_DAMAGED INTERFACES:Unit(unit) 208 209 /** 210 * This AI event is sent when a unit was destroyed; see also the unit-damaged 211 * event. 212 */ 213 struct SUnitDestroyedEvent { 214 int unit; 215 /** 216 * may be -1, which means no attacker was directly involveld, 217 * or the attacker is not visible and cheat events are off 218 */ 219 int attacker; 220 }; //$ EVENT_UNIT_DESTROYED INTERFACES:Unit(unit),UnitLifeState() 221 222 /** 223 * This AI event is sent when a unit changed from one team to another, 224 * either because the old owner gave it to the new one, or because the 225 * new one took it from the old one; see the /take command. 226 * Both giving and receiving team will get this event. 227 */ 228 struct SUnitGivenEvent { 229 int unitId; 230 int oldTeamId; 231 int newTeamId; 232 }; //$ EVENT_UNIT_GIVEN INTERFACES:Unit(unitId),UnitLifeState(),UnitTeamChange(oldTeamId,newTeamId) 233 234 /** 235 * This AI event is sent when a unit changed from one team to an other through 236 * capturing. 237 * Both giving and receiving team will get this event. 238 */ 239 struct SUnitCapturedEvent { 240 int unitId; 241 int oldTeamId; 242 int newTeamId; 243 }; //$ EVENT_UNIT_CAPTURED INTERFACES:Unit(unitId),UnitLifeState(),UnitTeamChange(oldTeamId,newTeamId) 244 245 /** 246 * This AI event is sent when an enemy unit entered the LOS of this team. 247 */ 248 struct SEnemyEnterLOSEvent { 249 int enemy; 250 }; //$ EVENT_ENEMY_ENTER_LOS INTERFACES:Unit(enemy),Enemy(enemy) 251 252 /** 253 * This AI event is sent when an enemy unit left the LOS of this team. 254 */ 255 struct SEnemyLeaveLOSEvent { 256 int enemy; 257 }; //$ EVENT_ENEMY_LEAVE_LOS INTERFACES:Unit(enemy),Enemy(enemy) 258 259 /** 260 * This AI event is sent when an enemy unit entered the radar covered area of 261 * this team. 262 */ 263 struct SEnemyEnterRadarEvent { 264 int enemy; 265 }; //$ EVENT_ENEMY_ENTER_RADAR INTERFACES:Unit(enemy),Enemy(enemy) 266 267 /** 268 * This AI event is sent when an enemy unit left the radar covered area of this 269 * team. 270 */ 271 struct SEnemyLeaveRadarEvent { 272 int enemy; 273 }; //$ EVENT_ENEMY_LEAVE_RADAR INTERFACES:Unit(enemy),Enemy(enemy) 274 275 /** 276 * This AI event is sent when an enemy unit was damaged. It contains the 277 * attacked unit, the attacking unit, the ammount of damage and the direction 278 * from where the damage was inflickted. In case of a laser weapon, the 279 * direction will point directly from the attacker to the attacked unit, while 280 * with artillery it will rather be from somewhere up in the sky to the attacked 281 * unit. 282 * See also the enemy-destroyed event. 283 */ 284 struct SEnemyDamagedEvent { 285 int enemy; 286 /** 287 * may be -1, which means no attacker was directly involveld, 288 * or the attacker is not allied with the team receiving this event 289 */ 290 int attacker; 291 float damage; 292 float* dir_posF3; 293 int weaponDefId; 294 /// if true, then damage is paralyzation damage, otherwise it is real damage 295 bool paralyzer; 296 }; //$ EVENT_ENEMY_DAMAGED INTERFACES:Unit(enemy),Enemy(enemy) 297 298 /** 299 * This AI event is sent when an enemy unit was destroyed; see also the 300 * enemy-damaged event. 301 */ 302 struct SEnemyDestroyedEvent { 303 int enemy; 304 /** 305 * may be -1, which means no attacker was directly involveld, 306 * or the attacker is not allied with the team receiving this event 307 */ 308 int attacker; 309 }; //$ EVENT_ENEMY_DESTROYED INTERFACES:Unit(enemy),Enemy(enemy),UnitLifeState() 310 311 /** 312 * This AI event is sent when certain weapons are fired. 313 * For performance reasons, it is not possible to send this event 314 * for all weapons. Therefore, it is currently only sent for manuall-fire 315 * weapons like for example the TA Commanders D-Gun or the Nuke. 316 */ 317 struct SWeaponFiredEvent { 318 int unitId; 319 int weaponDefId; 320 }; //$ EVENT_WEAPON_FIRED INTERFACES:Unit(unitId) 321 322 /** 323 * This AI event is sent when a user gives a command to one or multiple units 324 * belonging to a team controlled by the AI. 325 * For more info about the given commands, please use the 326 * Unit.getCurrentCommands() method of the callback. 327 */ 328 struct SPlayerCommandEvent { 329 int* unitIds; 330 int unitIds_size; 331 /// see COMMAND_* defines in AISCommands.h 332 int commandTopicId; 333 /// Id of the player that issued the command 334 int playerId; 335 }; //$ EVENT_PLAYER_COMMAND 336 337 /** 338 * This AI event is sent when a unit finished processing a command. 339 * @param commandId used on asynchronous commands only (is -1 for regular commands). 340 * this allows the AI to identify a possible result event, 341 * which would come with the same id 342 * @param commandTopicId unique identifier of a command 343 * (see COMMAND_* defines in AISCommands.h) 344 * @see callback.handleCommand(..., int commandId, ...) 345 */ 346 struct SCommandFinishedEvent { 347 int unitId; 348 int commandId; 349 int commandTopicId; 350 }; //$ EVENT_COMMAND_FINISHED INTERFACES:Unit(unitId) 351 352 /** 353 * This AI event is sent when a unit movement is detected by means of a seismic 354 * event. A seismic event means erruption/movement/shakings of the ground. This 355 * can be detected by only by special units usually, eg by the seismic detector 356 * building in Balanced Annihilation. 357 */ 358 struct SSeismicPingEvent { 359 float* pos_posF3; 360 float strength; 361 }; //$ EVENT_SEISMIC_PING 362 363 /** 364 * This AI event is sent when the AI should be loading its full state from a 365 * file. 366 */ 367 struct SLoadEvent { 368 /// Absolute file path, should be treated read-only 369 const char* file; 370 }; //$ EVENT_LOAD INTERFACES:LoadSave(file) 371 372 /** 373 * This AI event is sent when the AI should be saving its full state to a file. 374 */ 375 struct SSaveEvent { 376 /// Absolute file path, writable 377 const char* file; 378 }; //$ EVENT_SAVE INTERFACES:LoadSave(file) 379 380 /** 381 * This AI event is sent whenever a unit of an enemy team is created, 382 * and contains the created unit. Usually, the unit has only 1 HP at this time, 383 * and consists only of a nano frame. 384 * See also the enemy-finished event. 385 */ 386 struct SEnemyCreatedEvent { 387 int enemy; 388 }; //$ EVENT_ENEMY_CREATED INTERFACES:Unit(enemy),Enemy(enemy) 389 390 /** 391 * This AI event is sent whenever an enemy unit is fully built, and contains the 392 * finished unit. Usually, the unit has full health at this time. 393 * See also the unit-created event. 394 */ 395 struct SEnemyFinishedEvent { 396 int enemy; 397 }; //$ EVENT_ENEMY_FINISHED INTERFACES:Unit(enemy),Enemy(enemy) 398 399 #ifdef __cplusplus 400 } // extern "C" 401 #endif 402 403 #endif // AI_S_EVENTS_H 404