highScores.h File Reference

Detailed Description

A SwadgePass-aware high score persistence utility.

Overview

This util is intended to make saving a high score table as painless as possible. Features:

• Save a configurable number of high scores to NVS, up to MAX_HIGH_SCORE_COUNT
• Include scores from SwadgePass in high score table, max one per SwadgePass user, along with user image and username data
• Keep at least one score from this Swadge's user, even if they suck SwadgePass scores would overtake theirs

Implementing

The steps to add high scores to your mode are:

1. Instantiate a highScores_t struct and set highScores_t.highScoreCount
2. Call initHighScores()
3. Implement get and set callback functions in your mode for your swadgePassPacket_t high score field
4. Retrieve SwadgePasses and pass them to saveHighScoresFromSwadgePass(), ideally once on mode start
5. In your mode's swadgeMode.fnAddToSwadgePassPacket, call addHighScoreToSwadgePassPacket()
6. When the player has finished a game, submit their score(s) via updateHighScores()
7. The high score array in highScores_t.highScores will always be up-to-date, so it can be used to display high scores without any other considerations. See nameList.h for how to get display names from ::swadgesonaCore_t.packedName, or use ::initHighScoreSonas() to initialize names and Swadgesona images all at once.

There is an example implementation in highScoreTest.c that may be helpful to use a guide.

Go to the source code of this file.

Data Structures
struct	score_t
struct	highScores_t
struct	displayScore_t
	Struct for displaying the high score table entry. Includes usernames and rendered user images. More...

Macros
#define	MAX_HIGH_SCORE_COUNT   20

Functions
void	initHighScores (highScores_t *hs, const char *nvsNamespace)
	Load high score data from NVS.
bool	updateHighScores (highScores_t *hs, const char *nvsNamespace, score_t newScores[], uint8_t numNewScores)
	Update the high score table and user high score with new scores from the player or SwadgePass and persist to NVS. This function handles sorting and limiting the number of scores, so no preprocessing is necessary.
void	saveHighScoresFromSwadgePass (highScores_t *hs, const char *nvsNamespace, list_t swadgePasses, const struct swadgeMode *mode, int32_t(*fnGetSwadgePassHighScore)(const swadgePassPacket_t *packet))
	Extract high score data received from SwadgePass and save to the high score table. This should be called from your mode's fnEnterMode function after calling initHighScores().
void	clearHighScores (const char *nvsNamespace)
	Clear high score data from NVS.
void	addHighScoreToSwadgePassPacket (const char *nvsNamespace, swadgePassPacket_t *packet, void(*fnSetSwadgePassHighScore)(swadgePassPacket_t *packet, int32_t highScore))
	Write high score data to SwadgePass packet for sending to other swadges. This should be called from your mode's fnAddToSwadgePassPacket function.
void	initDisplayHighScores (highScores_t *hs, displayScore_t ds[])
	Load the usernames and user images for the high score table into memory. When you are finished with the images, call ::freeHighScoreUserImages() to free the memory. It is safe to call this function multiple times before calling ::freeHighScoreUserImages().
void	freeDisplayHighScores (highScores_t *hs, displayScore_t ds[])
	Free memory used for user images.

---

Data Structure Documentation

score_t

struct score_t

Data Fields
int32_t	score	The point value of this score. This will be 0 for uninitialized scores.
char	spKey[NVS_KEY_NAME_MAX_SIZE]	The SwadgePass key for this score, to ensure we only save one score from a given SP user. This will be empty if this score is from this Swadge's user and not from Swadgepass.
int32_t	packedName	The username of the player who achieved this score. If the score is from this Swadge's user, this data will be all 00; built-in methods to load the current SP username should be used instead.
fairy_t	fairy	The fairy of the player who achieved this score. If the score is from this Swadge's user, this data will be all 00; built-in methods to load the current SP fairy image should be used instead.

highScores_t

struct highScores_t

Data Fields
uint8_t	highScoreCount	Number of high scores to save. Defaults to MAX_HIGH_SCORE_COUNT if not set.
int32_t	userHighScore	The highest score achieved by this Swadge's user, for sending via SwadgePass and ensuring we don't kick ourselves off of the leaderboard.
score_t	highScores[MAX_HIGH_SCORE_COUNT]	High score list, sorted from high to low.

displayScore_t

struct displayScore_t

Data Fields
int32_t	score	The point value of this score. This will be 0 for uninitialized scores.
nameData_t	name	The Swadgepass username.
wsg_t	image	The Swadgepass user's rendered profile picture.

Macro Definition Documentation

MAX_HIGH_SCORE_COUNT

#define MAX_HIGH_SCORE_COUNT   20

Function Documentation

initHighScores()

void initHighScores	(	highScores_t *	hs,
		const char *	nvsNamespace )

Load high score data from NVS.

Parameters

hs	The struct that contains the high scores. highScores_t.highScoreCount should be set; other fields will be overwritten
nvsNamespace	The NVS namespace to read saved high score data from

updateHighScores()

bool updateHighScores	(	highScores_t *	hs,
		const char *	nvsNamespace,
		score_t	newScores[],
		uint8_t	numNewScores )

Update the high score table and user high score with new scores from the player or SwadgePass and persist to NVS. This function handles sorting and limiting the number of scores, so no preprocessing is necessary.

Parameters

hs	The struct that contains the high scores
nvsNamespace	The NVS namespace to write data to
newScores	Array of scores to add to the table
numNewScores	Count of scores in the array

Returns

true if the high score table changed, false if it didn't

saveHighScoresFromSwadgePass()

void saveHighScoresFromSwadgePass	(	highScores_t *	hs,
		const char *	nvsNamespace,
		list_t	swadgePasses,
		const struct swadgeMode *	mode,
		int32_t(*	fnGetSwadgePassHighScore )(const swadgePassPacket_t *packet) )

Extract high score data received from SwadgePass and save to the high score table. This should be called from your mode's fnEnterMode function after calling initHighScores().

Parameters

hs	The highScores_t struct that contains the high scores
nvsNamespace	The NVS namespace to write data to
swadgePasses	A list_t of SwadgePasses from getSwadgePasses()
mode	The swadgeMode that is consuming these SwadgePasses. They will be marked as used by this mode.
fnGetSwadgePassHighScore	Pointer to a function that returns your mode's high score from a SwadgePass packet

clearHighScores()

void clearHighScores

(

const char *

nvsNamespace

)

Clear high score data from NVS.

Parameters

nvsNamespace

The NVS namespace to clear saved high score data from

addHighScoreToSwadgePassPacket()

void addHighScoreToSwadgePassPacket	(	const char *	nvsNamespace,
		swadgePassPacket_t *	packet,
		void(*	fnSetSwadgePassHighScore )(swadgePassPacket_t *packet, int32_t highScore) )

Write high score data to SwadgePass packet for sending to other swadges. This should be called from your mode's fnAddToSwadgePassPacket function.

Parameters

nvsNamespace	The NVS namespace to read data from
packet	The SwadgePass packet to modify
fnSetSwadgePassHighScore	Pointer to a function that sets your mode's high score field in a SwadgePass packet

initDisplayHighScores()

void initDisplayHighScores	(	highScores_t *	hs,
		displayScore_t	ds[] )

Load the usernames and user images for the high score table into memory. When you are finished with the images, call ::freeHighScoreUserImages() to free the memory. It is safe to call this function multiple times before calling ::freeHighScoreUserImages().

Parameters

hs	The highScores_t struct that contains the high scores
ds	Array of display structs to be populated. This array must be the same length as highScores_t.highScoreCount.

freeDisplayHighScores()

void freeDisplayHighScores	(	highScores_t *	hs,
		displayScore_t	ds[] )

Free memory used for user images.

Parameters

hs	The highScores_t struct that contains the high scores
ds	The ::displayScores_t array that contains user images to be freed