1 /*! \file
2  * \brief Savegame file handling.
3  * \details Functions and structs for reading, writing and modifying OMF:2097 savegame (CHR) files.
4  * \copyright MIT license.
5  * \date 2013-2014
6  * \author Andrew Thompson
7  * \author Tuomas Virtanen
8  */
9 
10 #ifndef _SD_CHR_H
11 #define _SD_CHR_H
12 
13 #include "shadowdive/palette.h"
14 #include "shadowdive/sprite.h"
15 #include "shadowdive/pilot.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 #define MAX_CHR_ENEMIES 256 ///< Maximum amount of enemies for a CHR file.
22 
23 /*! \brief CHR enemy state entry
24  *
25  * Contains information about the current state of an enemy in the selected tournament.
26  */
27 typedef struct {
28     sd_pilot pilot;      ///< Enemy pilot data
29     char unknown[25];    ///< Unknown data TODO: Find out what this does
30 } sd_chr_enemy;
31 
32 /*! \brief CHR Saved game
33  *
34  * Contains a saved game for a single player.
35  * \todo find out what the unknown data fields are.
36  */
37 typedef struct {
38     sd_pilot pilot;      ///< Pilot data
39     sd_palette pal;      ///< Pilot palette
40     uint32_t unknown_b;  ///< Unkown value. Maybe tells if there is photo data ?
41     sd_sprite *photo;    ///< Pilot photo
42     sd_chr_enemy *enemies[MAX_CHR_ENEMIES]; ///< List of enemy states in current tournament
43 } sd_chr_file;
44 
45 /*! \brief Initialize CHR structure
46  *
47  * Initializes the CHR structure with empty values.
48  *
49  * \retval SD_INVALID_INPUT CHR struct pointer was NULL
50  * \retval SD_SUCCESS Success.
51  *
52  * \param chr Allocated CHR struct pointer.
53  */
54 int sd_chr_create(sd_chr_file *chr);
55 
56 /*! \brief Free CHR structure
57  *
58  * Frees up all memory reserved by the CHR structure.
59  * All contents will be freed, all pointers to contents will be invalid.
60  *
61  * \param chr CHR struct to modify.
62  */
63 void sd_chr_free(sd_chr_file *chr);
64 
65 /*! \brief Load .CHR file
66  *
67  * Loads the given CHR file to memory. The structure must be initialized with sd_chr_create()
68  * before using this function. Loading to a previously loaded or filled sd_chr_file structure
69  * will result in old data and pointers getting lost. This is very likely to cause a memory leak.
70  *
71  * \retval SD_FILE_OPEN_ERROR File could not be opened.
72  * \retval SD_FILE_PARSE_ERROR File does not contain valid data or has syntax problems.
73  * \retval SD_OUT_OF_MEMORY Memory ran out. This struct should now be considered invalid and freed.
74  * \retval SD_SUCCESS Success.
75  *
76  * \param chr CHR struct pointer.
77  * \param filename Name of the CHR file to load from.
78  */
79 int sd_chr_load(sd_chr_file *chr, const char *filename);
80 
81 /*! \brief Save .CHR file
82  *
83  * Saves the given CHR file from memory to a file on disk. The structure must be at
84  * least initialized by using sd_chr_create() before running this.
85  *
86  * \retval SD_FILE_OPEN_ERROR File could not be opened for writing.
87  * \retval SD_SUCCESS Success.
88  *
89  * \param chr CHR struct pointer.
90  * \param filename Name of the CHR file to save into.
91  */
92 int sd_chr_save(sd_chr_file *chr, const char *filename);
93 
94 /*! \brief Returns an enemy entry.
95  *
96  * Returns a pointer to a tournament enemy savestate entry.
97  *
98  * The structure memory will be owned by the library; do not attempt to
99  * free it.
100  *
101  * \retval NULL If chr ptr was NULL or enemy entry does not exist.
102  * \retval sd_chr_enemy* Enemy entry pointer on success.
103  *
104  * \param chr CHR struct pointer.
105  * \param enemy_num Enemy number to find
106  */
107 const sd_chr_enemy* sd_chr_get_enemy(sd_chr_file *chr, int enemy_num);
108 
109 #ifdef __cplusplus
110 }
111 #endif
112 
113 #endif // _SD_CHR_H
114