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 Swadgesona 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.

Go to the source code of this file.

Data Structures
struct	score_t
struct	highScores_t

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	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	initHighScoreSonas (highScores_t *hs, swadgesona_t sonas[])
	Load the usernames and Swadgesona images for the high score table into memory. When you are finished with the Swadgesona images, call freeHighScoreSonas() to free the memory. It is safe to call this function multiple times before calling freeHighScoreSonas().
void	freeHighScoreSonas (highScores_t *hs, swadgesona_t sonas[])
	Free memory used for Swadgesona 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.
swadgesonaCore_t	swadgesona	The Swadgesona 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 Swadgesona and username 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.

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

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

initHighScoreSonas()

void initHighScoreSonas	(	highScores_t *	hs,
		swadgesona_t	sonas[] )

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

Parameters

hs	The highScores_t struct that contains the high scores
sonas	Array of swadgesona structs. nameData_t.nameBuffer in swadgesona_t.name and swadgesona_t.image will be populated. This array must be the same length as highScores_t.highScoreCount.

freeHighScoreSonas()

void freeHighScoreSonas	(	highScores_t *	hs,
		swadgesona_t	sonas[] )

Free memory used for Swadgesona images.

Parameters

hs	The highScores_t struct that contains the high scores
sonas	Array of swadgesona structs. This array must be the same length as highScores_t.highScoreCount.