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
• 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 score_t.swadgePassUsername.

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

---

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.
int32_t	swadgePassUsername	The SwadgePass user who achieved this score, or 0 for this Swadge's user.

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,
		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()
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