Document save_file.h (#570)

autogen/lua_definitions/functions.lua

@@ -8176,27 +8176,32 @@ function reset_rumble_timers_2(m, a0)
 end
 
 --- @param flags integer
+--- Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing. Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save
 function save_file_clear_flags(flags)
     -- ...
 end
 
 --- @param fileIndex integer
 --- @param forceSave integer
+--- Saves the current state of the game into a specified save file. Includes data verification and backup management. Useful for maintaining game progress during play or when saving manually
 function save_file_do_save(fileIndex, forceSave)
     -- ...
 end
 
 --- @param fileIndex integer
+--- Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes. Useful for resetting a save file to its default state
 function save_file_erase(fileIndex)
     -- ...
 end
 
+--- Erases the backup data for the current save file without affecting the primary save data. Reloads the save file afterward
 function save_file_erase_current_backup_save()
     -- ...
 end
 
 --- @param capPos Vec3s
 --- @return integer
+--- Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter. Useful for tracking the cap's location after it has been dropped or lost
 function save_file_get_cap_pos(capPos)
     -- ...
 end
@@ -8204,6 +8209,7 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @return integer
+--- Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid. Useful for tracking player achievements and high scores
 function save_file_get_course_coin_score(fileIndex, courseIndex)
     -- ...
 end
@@ -8211,22 +8217,26 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @return integer
+--- Calculates the total number of stars collected in a specific course for a given save file. Useful for determining completion status of individual levels
 function save_file_get_course_star_count(fileIndex, courseIndex)
     -- ...
 end
 
 --- @return integer
+--- Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states. Useful for checking specific game progress details
 function save_file_get_flags()
     -- ...
 end
 
 --- @param courseIndex integer
 --- @return integer
+--- Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it. Useful for leaderboard-style comparisons and overall progress tracking
 function save_file_get_max_coin_score(courseIndex)
     -- ...
 end
 
 --- @return integer
+--- Returns the current sound mode (e.g., stereo, mono) stored in the save file. Useful for checking the audio output preferences when loading a save
 function save_file_get_sound_mode()
     -- ...
 end
@@ -8234,6 +8244,7 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @return integer
+--- Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1). Useful for evaluating level progress and completion
 function save_file_get_star_flags(fileIndex, courseIndex)
     -- ...
 end
@@ -8242,6 +8253,7 @@ end
 --- @param minCourse integer
 --- @param maxCourse integer
 --- @return integer
+--- Calculates the total number of stars collected across multiple courses within a specified range. Useful for determining the overall progress toward game completion
 function save_file_get_total_star_count(fileIndex, minCourse, maxCourse)
     -- ...
 end
@@ -8249,11 +8261,13 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @return integer
+--- Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false. Useful for tracking course-specific progress and enabling shortcuts
 function save_file_is_cannon_unlocked(fileIndex, courseIndex)
     -- ...
 end
 
 --- @param load_all integer
+--- Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified. Useful for reloading state after data corruption or during development debugging
 function save_file_reload(load_all)
     -- ...
 end
@@ -8261,6 +8275,7 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @param starFlagsToRemove integer
+--- Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars. Useful for undoing progress or debugging collected stars
 function save_file_remove_star_flags(fileIndex, courseIndex, starFlagsToRemove)
     -- ...
 end
@@ -8268,11 +8283,13 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @param coinScore integer
+--- Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter. Useful for manually setting achievements such as high coin counts in individual levels
 function save_file_set_course_coin_score(fileIndex, courseIndex, coinScore)
     -- ...
 end
 
 --- @param flags integer
+--- Adds new flags to the save file's flag bitmask. Useful for updating progress or triggering new gameplay features
 function save_file_set_flags(flags)
     -- ...
 end
@@ -8280,12 +8297,14 @@ end
 --- @param fileIndex integer
 --- @param courseIndex integer
 --- @param starFlags integer
+--- Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary. Useful for recording progress after star collection
 function save_file_set_star_flags(fileIndex, courseIndex, starFlags)
     -- ...
 end
 
 --- @param fileIndex integer
 --- @param courseIndex integer
+--- Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update. Useful for leaderboard tracking or displaying recent progress
 function touch_coin_score_age(fileIndex, courseIndex)
     -- ...
 end

docs/lua/functions-3.md

@@ -5514,7 +5514,7 @@ Creates a warp node in the current level and area with id `id` that goes to the
 - `integer`
 
 ### C Prototype
-`s32 lvl_set_current_level(UNUSED s16 arg0, s16 levelNum);`
+`s32 lvl_set_current_level(s16 arg0, s16 levelNum);`
 
 [:arrow_up_small:](#)
 

docs/lua/functions-5.md

@@ -4710,6 +4710,9 @@
 
 ## [save_file_clear_flags](#save_file_clear_flags)
 
+### Description
+Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing. Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save
+
 ### Lua Example
 `save_file_clear_flags(flags)`
 
@@ -4730,6 +4733,9 @@
 
 ## [save_file_do_save](#save_file_do_save)
 
+### Description
+Saves the current state of the game into a specified save file. Includes data verification and backup management. Useful for maintaining game progress during play or when saving manually
+
 ### Lua Example
 `save_file_do_save(fileIndex, forceSave)`
 
@@ -4751,6 +4757,9 @@
 
 ## [save_file_erase](#save_file_erase)
 
+### Description
+Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes. Useful for resetting a save file to its default state
+
 ### Lua Example
 `save_file_erase(fileIndex)`
 
@@ -4771,6 +4780,9 @@
 
 ## [save_file_erase_current_backup_save](#save_file_erase_current_backup_save)
 
+### Description
+Erases the backup data for the current save file without affecting the primary save data. Reloads the save file afterward
+
 ### Lua Example
 `save_file_erase_current_backup_save()`
 
@@ -4789,6 +4801,9 @@
 
 ## [save_file_get_cap_pos](#save_file_get_cap_pos)
 
+### Description
+Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter. Useful for tracking the cap's location after it has been dropped or lost
+
 ### Lua Example
 `local integerValue = save_file_get_cap_pos(capPos)`
 
@@ -4809,6 +4824,9 @@
 
 ## [save_file_get_course_coin_score](#save_file_get_course_coin_score)
 
+### Description
+Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid. Useful for tracking player achievements and high scores
+
 ### Lua Example
 `local integerValue = save_file_get_course_coin_score(fileIndex, courseIndex)`
 
@@ -4830,6 +4848,9 @@
 
 ## [save_file_get_course_star_count](#save_file_get_course_star_count)
 
+### Description
+Calculates the total number of stars collected in a specific course for a given save file. Useful for determining completion status of individual levels
+
 ### Lua Example
 `local integerValue = save_file_get_course_star_count(fileIndex, courseIndex)`
 
@@ -4851,6 +4872,9 @@
 
 ## [save_file_get_flags](#save_file_get_flags)
 
+### Description
+Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states. Useful for checking specific game progress details
+
 ### Lua Example
 `local integerValue = save_file_get_flags()`
 
@@ -4869,6 +4893,9 @@
 
 ## [save_file_get_max_coin_score](#save_file_get_max_coin_score)
 
+### Description
+Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it. Useful for leaderboard-style comparisons and overall progress tracking
+
 ### Lua Example
 `local integerValue = save_file_get_max_coin_score(courseIndex)`
 
@@ -4889,6 +4916,9 @@
 
 ## [save_file_get_sound_mode](#save_file_get_sound_mode)
 
+### Description
+Returns the current sound mode (e.g., stereo, mono) stored in the save file. Useful for checking the audio output preferences when loading a save
+
 ### Lua Example
 `local integerValue = save_file_get_sound_mode()`
 
@@ -4907,6 +4937,9 @@
 
 ## [save_file_get_star_flags](#save_file_get_star_flags)
 
+### Description
+Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1). Useful for evaluating level progress and completion
+
 ### Lua Example
 `local integerValue = save_file_get_star_flags(fileIndex, courseIndex)`
 
@@ -4928,6 +4961,9 @@
 
 ## [save_file_get_total_star_count](#save_file_get_total_star_count)
 
+### Description
+Calculates the total number of stars collected across multiple courses within a specified range. Useful for determining the overall progress toward game completion
+
 ### Lua Example
 `local integerValue = save_file_get_total_star_count(fileIndex, minCourse, maxCourse)`
 
@@ -4950,6 +4986,9 @@
 
 ## [save_file_is_cannon_unlocked](#save_file_is_cannon_unlocked)
 
+### Description
+Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false. Useful for tracking course-specific progress and enabling shortcuts
+
 ### Lua Example
 `local integerValue = save_file_is_cannon_unlocked(fileIndex, courseIndex)`
 
@@ -4971,6 +5010,9 @@
 
 ## [save_file_reload](#save_file_reload)
 
+### Description
+Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified. Useful for reloading state after data corruption or during development debugging
+
 ### Lua Example
 `save_file_reload(load_all)`
 
@@ -4991,6 +5033,9 @@
 
 ## [save_file_remove_star_flags](#save_file_remove_star_flags)
 
+### Description
+Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars. Useful for undoing progress or debugging collected stars
+
 ### Lua Example
 `save_file_remove_star_flags(fileIndex, courseIndex, starFlagsToRemove)`
 
@@ -5013,6 +5058,9 @@
 
 ## [save_file_set_course_coin_score](#save_file_set_course_coin_score)
 
+### Description
+Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter. Useful for manually setting achievements such as high coin counts in individual levels
+
 ### Lua Example
 `save_file_set_course_coin_score(fileIndex, courseIndex, coinScore)`
 
@@ -5035,6 +5083,9 @@
 
 ## [save_file_set_flags](#save_file_set_flags)
 
+### Description
+Adds new flags to the save file's flag bitmask. Useful for updating progress or triggering new gameplay features
+
 ### Lua Example
 `save_file_set_flags(flags)`
 
@@ -5055,6 +5106,9 @@
 
 ## [save_file_set_star_flags](#save_file_set_star_flags)
 
+### Description
+Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary. Useful for recording progress after star collection
+
 ### Lua Example
 `save_file_set_star_flags(fileIndex, courseIndex, starFlags)`
 
@@ -5077,6 +5131,9 @@
 
 ## [touch_coin_score_age](#touch_coin_score_age)
 
+### Description
+Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update. Useful for leaderboard tracking or displaying recent progress
+
 ### Lua Example
 `touch_coin_score_age(fileIndex, courseIndex)`
 

src/game/save_file.h

@@ -131,34 +131,132 @@ extern s8 gSaveFileModified;
 
 s8 get_level_num_from_course_num(s16 courseNum);
 s8 get_level_course_num(s16 levelNum);
+
+/* |description|
+Marks the coin score for a specific course as the newest among all save files. Adjusts the age of other scores to reflect the update.
+Useful for leaderboard tracking or displaying recent progress
+|descriptionEnd| */
 void touch_coin_score_age(s32 fileIndex, s32 courseIndex);
+
+/* |description|
+Saves the current state of the game into a specified save file. Includes data verification and backup management.
+Useful for maintaining game progress during play or when saving manually
+|descriptionEnd| */
 void save_file_do_save(s32 fileIndex, s8 forceSave);
+
+/* |description|
+Erases all data in a specified save file, including backup slots. Marks the save file as modified and performs a save to apply the changes.
+Useful for resetting a save file to its default state
+|descriptionEnd| */
 void save_file_erase(s32 fileIndex);
+
+/* |description|
+Erases the backup data for the current save file without affecting the primary save data. Reloads the save file afterward
+|descriptionEnd| */
 void save_file_erase_current_backup_save(void);
+
 BAD_RETURN(s32) save_file_copy(s32 srcFileIndex, s32 destFileIndex);
 void save_file_load_all(u8 reload);
+
+/* |description|
+Reloads the save file data into memory, optionally resetting all save files. Marks the save file as modified.
+Useful for reloading state after data corruption or during development debugging
+|descriptionEnd| */
 void save_file_reload(u8 load_all);
+
 void save_file_collect_star_or_key(s16 coinScore, s16 starIndex, u8 fromNetwork);
 s32 save_file_exists(s32 fileIndex);
+
+/* |description|
+Determines the maximum coin score for a course across all save files. Returns the score along with the file index of the save containing it.
+Useful for leaderboard-style comparisons and overall progress tracking
+|descriptionEnd| */
 u32 save_file_get_max_coin_score(s32 courseIndex);
+
+/* |description|
+Calculates the total number of stars collected in a specific course for a given save file.
+Useful for determining completion status of individual levels
+|descriptionEnd| */
 s32 save_file_get_course_star_count(s32 fileIndex, s32 courseIndex);
+
+/* |description|
+Calculates the total number of stars collected across multiple courses within a specified range.
+Useful for determining the overall progress toward game completion
+|descriptionEnd| */
 s32 save_file_get_total_star_count(s32 fileIndex, s32 minCourse, s32 maxCourse);
+
+/* |description|
+Adds new flags to the save file's flag bitmask.
+Useful for updating progress or triggering new gameplay features
+|descriptionEnd| */
 void save_file_set_flags(u32 flags);
+
+/* |description|
+Clears specific flags in the current save file. The flags are specified as a bitmask in the `flags` parameter. Ensures that the save file remains valid after clearing.
+Useful for removing specific game states, such as collected items or completed objectives, without resetting the entire save
+|descriptionEnd| */
 void save_file_clear_flags(u32 flags);
+
+/* |description|
+Retrieves the bitmask of flags representing the current state of the save file. Flags indicate collected items, completed objectives, and other game states.
+Useful for checking specific game progress details
+|descriptionEnd| */
 u32 save_file_get_flags(void);
+
+/* |description|
+Retrieves the bitmask of stars collected in a specific course or castle secret stars (-1).
+Useful for evaluating level progress and completion
+|descriptionEnd| */
 u32 save_file_get_star_flags(s32 fileIndex, s32 courseIndex);
+
+/* |description|
+Adds specific star flags to the save file, indicating collected stars for a course or castle secret stars. Updates the save file flags as necessary.
+Useful for recording progress after star collection
+|descriptionEnd| */
 void save_file_set_star_flags(s32 fileIndex, s32 courseIndex, u32 starFlags);
+
+/* |description|
+Removes specific star flags from the save file. This modifies the bitmask representing collected stars for a course or castle secret stars.
+Useful for undoing progress or debugging collected stars
+|descriptionEnd| */
 void save_file_remove_star_flags(s32 fileIndex, s32 courseIndex, u32 starFlagsToRemove);
+
+/* |description|
+Returns the highest coin score for a specified course in the save file. Performs checks to ensure the coin score is valid.
+Useful for tracking player achievements and high scores
+|descriptionEnd| */
 s32 save_file_get_course_coin_score(s32 fileIndex, s32 courseIndex);
+
+/* |description|
+Updates the coin score for a specific course in the save file. The new score is provided in the `coinScore` parameter.
+Useful for manually setting achievements such as high coin counts in individual levels
+|descriptionEnd| */
 void save_file_set_course_coin_score(s32 fileIndex, s32 courseIndex, u8 coinScore);
+
+/* |description|
+Checks whether the cannon in the specified course is unlocked. Returns true if the cannon is unlocked, otherwise false.
+Useful for tracking course-specific progress and enabling shortcuts
+|descriptionEnd| */
 s32 save_file_is_cannon_unlocked(s32 fileIndex, s32 courseIndex);
+
 void save_file_set_cannon_unlocked(void);
 void save_file_set_cap_pos(s16 x, s16 y, s16 z);
-s32 save_file_get_cap_pos(Vec3s capPos);
-void save_file_set_sound_mode(u16 mode);
-u16 save_file_get_sound_mode(void);
-void save_file_move_cap_to_default_location(void);
 
+/* |description|
+Retrieves the current position of Mario's cap, if it is on the ground in the current level and area. The position is stored in the provided `capPos` parameter.
+Useful for tracking the cap's location after it has been dropped or lost
+|descriptionEnd| */
+s32 save_file_get_cap_pos(Vec3s capPos);
+
+void save_file_set_sound_mode(u16 mode);
+
+/* |description|
+Returns the current sound mode (e.g., stereo, mono) stored in the save file.
+Useful for checking the audio output preferences when loading a save
+|descriptionEnd| */
+u16 save_file_get_sound_mode(void);
+
+void save_file_move_cap_to_default_location(void);
 void disable_warp_checkpoint(void);
 void check_if_should_set_warp_checkpoint(struct WarpNode *warpNode);
 s32 check_warp_checkpoint(struct WarpNode *warpNode);