## ScoreKeeper

### new

Initialize the **ScoreKeeper** object.

new([useEncryption])

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

useEncryption | Encrypt player scores. See the Encryption section. |
Boolean |
N |

**Returns**

A **ScoreKeeper** object on which all other methods are called.

**Examples**

*Default*

local ScoreKeeper = require("plugin.scorekeeper") local Scores = ScoreKeeper.new() -- ScoreKeeper Object

*Compact*

local Scores = require("plugin.scorekeeper").new()

**Notes**

*You should only initialize one ScoreKeeper object in your app.*

You can do this by placing the initialization in a "globals" Lua module, or adding it to the global Lua space (generally you don't want to add to the global space, but this would be considered a "responsable" global):

_G.Scores = require("plugin.scorekeeper").new()

You can then access the **ScoreKeeper** object anywhere in your code files.

--anyfile.lua Scores:save(200)

## ScoreKeeper Object

All of the following methods are called on a **ScoreKeeper** object. See **new** above.

### save

Save the players score.

save(score[, limit])

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

score | The players score value to save. | Number |
Y |

limit | Cap the amount of scores saved. See Notes below. |
Number |
N |

**Returns**

A *Table* array of the current saved scores from *highest to lowest*, or **nil** and an error.

**Examples**

*Default*

Scores:save(2000)

*Using return value*

local scores = Scores:save(2000) for i=1, #scores do print(i, scores[i]) end

*Save and cap to 10 scores*

local scores = Scores:save(154, 10) for i=1, #scores do print(i, scores[i]) end

*Using error checking*

local scores, err = Scores:save(1500) if not scores then print(err) else for i=1, #scores do print(i, scores[i]) end end

**Notes**

If you pass the `limit`

argument, the score list will be "capped" at that number. For example if you only want to keep the top 20 scores set the `limit`

to 20. Any new scores that are *higher than the lowest* score in the list will be replaced to keep the list capped to 20 scores.

You can change the `limit`

at any time, but be aware if you set it to a smaller number than what you started with, the extra scores (lowest to highest) will be dropped to match the new "cap" size.

### list

List players saved scores.

list([sort][, limit])

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

sort | Either 'high' or 'low'. The default is 'high'. See Notes below. |
String |
N |

limit | Cap the amount of scores returned. Defaults to all scores. | Number |
N |

**Returns**

A *Table* array of score values. By default the scores are sorted from *highest to lowest*. If no values have been saved yet, the array will be empty.

**Examples**

*List all saved scores, highest to lowest*

local scores = Scores:list() for i=1, #scores do print(i, scores[i]) end

*List top 5 saved scores (see also the top method)*

local scores = Scores:list(5) for i=1, #scores do print(i, scores[i]) end

*List all scores, lowest to highest*

local scores = Scores:list('low') for i=1, #scores do print(i, scores[i]) end

*List 10 scores, lowest to highest*

local scores = Scores:list('low', 10) for i=1, #scores do print(i, scores[i]) end

**Notes**

Possible `sort`

values

- 'high' returns the scores from
*highest to lowest*. - 'low' returns the scores from
*lowest to highest*.

See the **top** method below, which is a convenience function to get the top scores.

### top

List the players top saved scores from *highest to lowest*.

top([limit])

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

limit | Cap the amount of scores returned. Defaults to 10. | Number |
N |

**Returns**

A *Table* array of the top 10 score values (unless `limit`

is provided), sorted from *highest to lowest*. If no values have been saved yet, the array will be empty.

**Examples**

*Default (top 10)*

local scores = Scores:top() for i=1, #scores do print(i, scores[i]) end

*Load top 25 scores*

local scores = Scores:top(25) for i=1, #scores do print(i, scores[i]) end

### bottom

Load player scores from the bottom of the list. See **Notes** below.

bottom(limit)

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

limit | Cap the amount of scores returned. | Number |
Y |

**Returns**

A *Table* array of saved score values. If no values have been saved yet, the array will be empty. See **Notes** below.

**Example**

*List the bottom 5 scores, sorted highest to lowest*

local scores = Scores:bottom(5) for i=1, #scores do print(i, scores[i]) end

**Notes**

If you want an ordered list of scores from *lowest to highest*, you must use the **list** method. This method returns the lowest scores saved, capped by the `limit`

argument, sorted from *highest to lowest*.

If the `limit`

argument is equal to or greater than the amount of current scores saved, this method oprerate exactly like the **top** method.

If you don't pass the `limit`

argument, the lowest score will be returned in the *Table* array. See also **lowest**.

### highest

Get the players highest score saved.

highest()

**Arguments**

*This method takes no arguments.*

**Returns**

A *Number* value of the highest score. If no saved values exist returns 0.

**Example**

local score = Scores:highest()

**Notes**

This method returns a single value directly as a *Number*. It is not a *Table* array.

### lowest

Get the players lowest score saved.

lowest()

**Arguments**

*This method takes no arguments.*

**Returns**

A *Number* value of the lowest score. If no saved values exist returns 0.

**Example**

local score = Scores:lowest()

**Notes**

This method returns a single value directly as a *Number*. It is not a *Table* array.

### trim

Trim the players saved score list to the specified size and update the storage file.

trim(size)

**Arguments**

Name | Description | Type | Required |
---|---|---|---|

size | The length of the new score list. Must be greater than zero. See Notes below. |
Number |
Y |

**Returns**

A *Table* array of score values, sorted from *highest to lowest*, or **nil** and an error.

**Examples**

*Trim the list to contain only the top 10 scores*

local scores = Scores:trim(10) for i=1, #scores do print(i, scores[i]) end

*Using error checking*

local scores, err = Scores:trim(10) if not scores then print(err) else for i=1, #scores do print(i, scores[i]) end end

**Notes**

This method is destructive by nature. After the trim has been the processed, the results will immediately be saved to the stroage file.

Trim will remove any scores beyond the provided `size`

parameter. Scores are first sorted *highest to lowest* before the trim.

The `size`

argument must be greater than zero. To clear all score values from the list use the **empty** method below.

### empty

Empty the players score list. All saved scores are removed and the storage file is updated.

empty()

**Arguments**

*This method takes no arguments.*

**Returns**

An empty *Table* array, or **nil** and an error.

**Examples**

*Default*

Scores:empty()

*Using error checking*

local scores, err = Scores:empty() if not scores then print(err) else print("success") end

**Notes**

This method is destructive by nature. After the empty method has run, the results will immediately be saved to the stroage file (an empty *Table* array).

### flush

Deletes all scores and the storage file from the device.

flush()

**Arguments**

*This method takes no arguments.*

**Returns**

A *Boolean* `true`

on success, or **nil** and an error.

**Example**

local ok, err = Scores:flush() if not ok then print(err) else print("storage file removed") end

**Notes**

This method is destructive by nature. All scores and the storage file will no longer be accessible.

A new storage file will be created the next time the **save** method is used.

### debug

Utility method. Prints all saved scores to the Corona console.

**Example**

Scores:debug()