RecAnalyst library
RecAnalyst is a software library that implements an analysis of AoE2 recorded games.
Library is licensed under the GNU Lesser General Public License (LGPL).
The download is available at https://sourceforge.net/projects/aoc-mgx-utils/files/recanalyst/
The archive contains:
- precompiled library recanalyst.dll in /bin
- source code of the library in /src
- Delphi interfaces for the library (for both static and dynamic linking) in /bin
- C interface for the library in /bin (or in /demo/src)
- simple demo written in C in /demo/src
Note: The latest API can always be found in the archive (see the /bin/recanalyst.h file).
typedef struct recanalyst recanalyst;
Recanalyst is represented by a pointer to an instance of the structure named "recanalyst". You can think of a recanalyst pointer as
an object. The recanalyst_create() is its constructor and recanalyst_free() is its destructor. Other routines are methods on a
recanalyst object.
typedef struct tagRECANALYST_INITIALSTATE {
DWORD dwFood;
DWORD dwWood;
DWORD dwStone;
DWORD dwGold;
int iStartingAge; /* one of the STARTING_AGE values */
DWORD dwHouseCapacity;
DWORD dwPopulation;
DWORD dwCivilianPop;
DWORD dwMilitaryPop;
DWORD dwExtraPop;
POINT ptPosition;
char szName[256];
szStartingAge: array[0..MAXBYTE] of AnsiChar;
} RECANALYST_INITIALSTATE, *LPRECANALYST_INITIALSTATE;
This structure contains information about an initial state of the player.
typedef struct tagRECANALYST_PLAYER {
char szName[256];
DWORD dwIndex;
BOOL bHuman;
DWORD dwTeam;
BOOL bOwner;
char szCivilization[256];
DWORD dwCivId; /* one of the CIVILIZATION values */
DWORD dwColorId;
BOOL bIsCooping;
DWORD dwFeudalTime;
DWORD dwCastleTime;
DWORD dwImperialTime;
DWORD dwResignTime;
DWORD dwDisconnectTime;
LPRECANALYST_INITIALSTATE lpis; /* pointer to initial state struct data */
} RECANALYST_PLAYER, *LPRECANALYST_PLAYER;
This structure contains information about a player.
typedef struct tagRECANALYST_VICTORY {
DWORD dwTimeLimit;
DWORD dwScoreLimit;
DWORD dwVictoryCondition; /* one of the VICTORY_CONDITION values */
char szVictory[256];
} RECANALYST_VICTORY, *LPRECANALYST_VICTORY;
This structure contains information about victory settings.
typedef struct tagRECANALYST_GAMESETTINGS {
DWORD dwGameType; /* one of the GAME_TYPE values */
DWORD dwMapStyle; /* one of the MAP_STYLE values */
DWORD dwDifficultyLevel; /* one of the DIFFICULTY_LEVEL values */
DWORD dwGameSpeed; /* one of the GAME_SPEED values */
DWORD dwRevealMap; /* one of the REVEAL_MAP values */
DWORD dwMapSize; /* one of the MAP_SIZE values */
BOOL bIsScenario;
DWORD dwPlayers;
DWORD dwPOV;
DWORD dwMapId;
DWORD dwPopLimit;
BOOL bLockDiplomacy;
DWORD dwPlayTime;
BOOL bInGameCoop;
BOOL bIsFFA;
DWORD dwVersion; /* one of the GAME_VERSION values */
char szMap[65536];
char szPlayersType[128];
char szPOV[256];
char szGameType[256];
char szMapStyle[256];
char szDifficultyLevel[256];
char szGameSpeed[256];
char szRevealMap[256];
char szMapSize[256];
char szVersion[256];
char szScFileName[65536];
LPRECANALYST_VICTORY lpVictory; /* pointer to victory struct data */
} RECANALYST_GAMESETTINGS, *LPRECANALYST_GAMESETTINGS;
This structure contains information about game settings.
typedef struct tagRECANALYST_CHATMESSAGE {
DWORD dwTime; /* always zero for pre-game chat messages */
DWORD dwPlayerId; /* zero for players who left the game before its start in pre-game
chat, zero for age advances, resign and disconnect messages in
in-game chat */
char szMessage[256];
} RECANALYST_CHATMESSAGE, *LPRECANALYST_CHATMESSAGE;
This structure contains information about a chat message.
typedef struct tagRECANALYST_TRIBUTE {
DWORD dwTime;
DWORD dwPlayerFrom;
DWORD dwPlayerTo;
DWORD dwResourceId; /* one of the RESOURCE_ID values */
DWORD dwAmount;
FLOAT fFee;
} RECANALYST_TRIBUTE, *LPRECANALYST_TRIBUTE;
This structure contains information about a tribute.
typedef struct tagRECANALYST_RESEARCH {
DWORD dwTime;
DWORD dwId;
DWORD dwPlayerId;
char szName[256];
} RECANALYST_RESEARCH, *LPRECANALYST_RESEARCH;
This structure contains information about a research.
#define RECANALYST_OK 0 /* Successful result */
/* analyze error codes */
#define RECANALYST_NOFILE -1 /* No file has been specified for analyzing */
#define RECANALYST_FILEEXT -2 /* Wrong file extension, file format not
supported */
#define RECANALYST_EMPTYHEADER -3 /* Header length is zero */
#define RECANALYST_DECOMP -4 /* Cannot decompress header section */
#define RECANALYST_FILEREAD -5 /* Cannot read sections */
#define RECANALYST_FILEOPEN -6 /* Cannot open file */
#define RECANALYST_UNKNOWN -7 /* Unknown error */
#define RECANALYST_HEADLENREAD -8 /* Unable to read the header length */
#define RECANALYST_NOTRIGG -9 /* "Trigger Info" block has not been found */
#define RECANALYST_NOGAMESETS -10 /* "Game Settings" block has not been found */
#define RECANALYST_READPLAYER -11 /* Error reading "PlayerInfo" block */
/* general error codes */
#define RECANALYST_INVALIDPTR -12 /* Invalid pointer */
#define RECANALYST_FREEOBJ -13 /* Unable to release object instance */
#define RECANALYST_NOCALLBACK -14 /* No callback function has been defined */
#define RECANALYST_ENUMP -15 /* Error enumerating players */
#define RECANALYST_ANALYZEF -16 /* Error analyzing file */
#define RECANALYST_NOTANALYZED -17 /* File has not been analyzed yet */
#define RECANALYST_TIMECONV -18 /* Error converting time to its string
representation */
#define RECANALYST_OBJECTIVES -19 /* Error getting an objectives string */
#define RECANALYST_ENUMPRECHAT -20 /* Error enumerating pre-game chat messages */
#define RECANALYST_ENUMINCHAT -21 /* Error enumerating in-game chat messages */
#define RECANALYST_ENUMT -22 /* Error enumerating tributes */
#define RECANALYST_ENUMR -23 /* Error enumerating researches */
#define RECANALYST_GAMESETTS -24 /* Error getting game settings data */
#define RECANALYST_GENMAP -25 /* Error generating map */
#define RECANALYST_ANLTIME -26 /* Error getting analyze time */
Return codes from api routines.
typedef enum STARTING_AGE {
SA_UNKNOWN = -1,
SA_DARKAGE = 0,
SA_FEUDALAGE = 1,
SA_CASTLEAGE = 2,
SA_IMPERIALAGE = 3,
SA_POSTIMPERIALAGE = 4
} STARTING_AGE;
typedef enum CIVILIZATION {
C_NONE,
C_BRITONS,
C_FRANKS,
C_GOTHS,
C_TEUTONS,
C_JAPANESE,
C_CHINESE,
C_BYZANTINES,
C_PERSIANS,
C_SARACENS,
C_TURKS,
C_VIKINGS,
C_MONGOLS,
C_CELTS,
C_SPANISH,
C_AZTECS,
C_MAYANS,
C_HUNS,
C_KOREANS,
C_ITALIANS,
C_INDIANS,
C_INCAS,
C_MAGYARS,
C_SLAVS
} CIVILIZATION;
typedef enum VICTORY_CONDITION {
VC_STANDARD,
VC_CONQUEST,
VC_TIMELIMIT,
VC_SCORELIMIT,
VC_CUSTOM
} VICTORY_CONDITION;
typedef enum GAME_TYPE {
GT_RANDOMMAP,
GT_REGICIDE,
GT_DEATHMATCH,
GT_SCENARIO,
GT_CAMPAIGN,
GT_KINGOFTHEHILL,
GT_WONDERRACE,
GT_DEFENDWONDER,
GT_TURBORANDOMMAP
} GAME_TYPE;
typedef enum MAP_STYLE {
MS_STANDARD,
MS_REALWORLD,
MS_CUSTOM
} MAP_STYLE;
typedef enum DIFFICULTY_LEVEL {
DL_HARDEST,
DL_HARD,
DL_MODERATE,
DL_STANDARD,
DL_EASIEST
} DIFFICULTY_LEVEL;
typedef enum GAME_SPEED {
GS_SLOW = 100,
GS_NORMAL = 150,
GS_FAST = 200
} GAME_SPEED;
typedef enum REVEAL_MAP {
RM_NORMAL,
RM_EXPLORED,
RM_ALLVISIBLE
} REVEAL_MAP;
typedef enum MAP_SIZE {
MS_TINY,
MS_SMALL,
MS_MEDIUM,
MS_NORMAL,
MS_LARGE,
MS_GIANT
} MAP_SIZE;
typedef enum GAME_VERSION {
GV_UNKNOWN,
GV_AOK,
GV_AOKTRIAL,
GV_AOK20,
GV_AOK20A,
GV_AOC,
GV_AOCTRIAL,
GV_AOC10,
GV_AOC10C,
GV_AOC11,
GV_AOC21
} GAME_VERSION;
typedef enum RESOURCE_ID {
RI_FOOD,
RI_WOOD,
RI_STONE,
RI_GOLD
} RESOURCE_ID;
typedef BOOL (CALLBACK* EnumPlayersProc)(LPRECANALYST_PLAYER lpPlayer, LPARAM
lParam);
The EnumPlayersProc routine is an application-defined callback function that receives
player data in tagRECANALYST_PLAYER structures as a result of a call to the
recanalyst_enumplayers() routine.
lpPlayer contains player data. See tagRECANALYST_PLAYER structure.
lParam specifies the application-defined value given in recanalyst_enumplayers().
To continue enumeration, the callback function must return TRUE, to stop enumeration,
it must return FALSE.
typedef BOOL (CALLBACK* EnumChatMessagesProc)(LPRECANALYST_CHATMESSAGE lpChatMessage,
LPARAM lParam);
The EnumChatMessagesProc routine is an application-defined callback function that receives
chat message data in tagRECANALYST_CHATMESSAGE structures as a result of a call to the
recanalyst_enumpregamechat() or recanalyst_enumingamechat() routines.
lpChatMessage contains chat message data. See tagRECANALYST_CHATMESSAGE structure.
lParam specifies the application-defined value given in recanalyst_enumpregamechat() or recanalyst_enumingamechat().
To continue enumeration, the callback function must return TRUE, to stop enumeration,
it must return FALSE.
typedef BOOL (CALLBACK* EnumTributesProc)(LPRECANALYST_TRIBUTE lpTribute, LPARAM
lParam);
The EnumTributesProc routine is an application-defined callback function that receives
tribute data in tagRECANALYST_TRIBUTE structures as a result of a call to the
recanalyst_enumtributes() routine.
lpTribute contains tribute data. See tagRECANALYST_TRIBUTE structure.
lParam specifies the application-defined value given in recanalyst_enumtributes().
To continue enumeration, the callback function must return TRUE, to stop enumeration,
it must return FALSE.
typedef BOOL (CALLBACK* EnumResearchesProc)(LPRECANALYST_RESEARCH lpResearch, LPARAM
lParam);
The EnumResearchesProc routine is an application-defined callback function that receives
research data in tagRECANALYST_RESEARCH structures as a result of a call to the
recanalyst_enumresearches() routine.
lpResearch contains research data. See tagRECANALYST_RESEARCH structure.
lParam specifies the application-defined value given in recanalyst_enumresearches().
To continue enumeration, the callback function must return TRUE, to stop enumeration,
it must return FALSE.
WINAPI recanalyst* recanalyst_create();
This routine creates a recanalyst object. If the object is created successfully, then
its pointer is returned. Otherwise NULL is returned.
WINAPI int recanalyst_free(recanalyst*);
This routine is the destructor for the recanalyst object. The parameter to
recanalyst_free() must be a recanalyst object obtained from recanalyst_create().
WINAPI int recanalyst_analyze(recanalyst*, LPSTR lpFileName);
This routine analyzes a file set by the lpFileName parameter. recanalyst_analyze()
can be called repeatedly on the recanalyst object.
lpFileName pointer to ANSI filename string.
WINAPI int recanalyst_getgamesettings(recanalyst*, LPRECANALYST_GAMESETTINGS
lpGameSettings);
This routine gets the game settings data. recanalyst_analyze() must first be called.
lpGameSettings points to a tagRECANALYST_GAMESETTINGS to receive the game settings data.
WINAPI int recanalyst_enumplayers(recanalyst*, EnumPlayersProc lpEnumFunc, LPARAM
lParam);
This routine enumerates all players by passing the tagRECANALYST_PLAYER of each player,
in turn, to an application-defined callback function. recanalyst_enumplayers() continues
until the last player is enumerated or the callback function returns FALSE. recanalyst_analyze()
must first be called.
lpEnumFunc points to an application-defined callback function. For more information, see
EnumPlayersProc callback function.
lParam specifies a 32-bit/64-bit, application-defined value to be passed to the callback function.
WINAPI int recanalyst_getobjectives(recanalyst*, LPTSTR lpObjectives);
This routine gets the objectives string from a file set by the recanalyst_setparams().
recanalyst_analyze() must first be called.
lpObjectives address of buffer for objectives string, you can get the size of buffer
required for objectives string by passing in a NULL parameter.
WINAPI int recanalyst_enumpregamechat(recanalyst*, EnumChatMessagesProc lpEnumFunc,
LPARAM lParam);
This routine enumerates pre-game chat messages by passing the
tagRECANALYST_CHATMESSAGE of each message, in turn, to an
application-defined callback function. recanalyst_enumpregamechat()
continues until the last message is enumerated or the callback function
returns FALSE. recanalyst_analyze() must first be called.
lpEnumFunc points to an application-defined callback function. For more
information, see EnumChatMessagesProc callback function.
lParam specifies a 32-bit/64-bit, application-defined value to be passed to
the callback function.
WINAPI int recanalyst_enumingamechat(recanalyst*, EnumChatMessagesProc lpEnumFunc,
LPARAM lParam);
This routine enumerates in-game chat messages by passing the
tagRECANALYST_CHATMESSAGE of each message, in turn, to an
application-defined callback function. recanalyst_enumingamechat()
continues until the last message is enumerated or the callback function
returns FALSE. recanalyst_analyze() must first be called.
lpEnumFunc points to an application-defined callback function. For more
information, see EnumChatMessagesProc callback function.
lParam specifies a 32-bit/64-bit, application-defined value to be passed to
the callback function.
WINAPI int recanalyst_enumtributes(recanalyst*, EnumTributesProc lpEnumFunc, LPARAM
lParam);
This routine enumerates tributes by passing the tagRECANALYST_TRIBUTE of each tribute,
in turn, to an application-defined callback function. recanalyst_enumtributes() continues
until the last tribute is enumerated or the callback function returns FALSE. recanalyst_analyze()
must first be called.
lpEnumFunc points to an application-defined callback function. For more information, see
EnumTributesProc callback function.
lParam specifies a 32-bit/64-bit, application-defined value to be passed to the callback function.
WINAPI int recanalyst_enumresearches(recanalyst*, EnumResearchesProc lpEnumFunc, LPARAM
lParam);
This routine enumerates researches by passing the tagRECANALYST_RESEARCH of each research,
in turn, to an application-defined callback function. recanalyst_enumresearches() continues
until the last research is enumerated or the callback function returns FALSE. recanalyst_analyze()
must first be called.
lpEnumFunc points to an application-defined callback function. For more information, see
EnumResearchesProc callback function.
lParam specifies a 32-bit/64-bit, application-defined value to be passed to the callback function.
WINAPI int recanalyst_generatemap(recanalyst*, DWORD dwWidth, DWORD dwHeight,
char *lpImageBuffer);
This routine generates a map image. recanalyst_analyze() must first be called.
dwWidth defines the map image width.
dwHeight defines the map image height.
lpImageBuffer address of buffer for map image, you can get the size of buffer required for image by passing in a NULL parameter.
WINAPI int recanalyst_analyzetime(recanalyst*);
This routine gets the analyze time in miliseconds.
WINAPI int recanalyst_timetostring(DWORD dwTime, LPTSTR lpTime);
This routine converts internal time representation into a string that represents its value.
dwTime internal time representation (miliseconds).
lpTime address of buffer for time string, you can get the size of buffer required for time string by passing in a NULL parameter.
WINAPI LPTSTR recanalyst_errmsg(int iErrCode);
This routine can be used to obtain an English language description of the error code defined by iErrCode parameter.
WINAPI LPTSTR recanalyst_libversion();
This routine returns the version of the recanalyst library.