ScoreKeeper

new

Initialize the ScoreKeeper object.

new([useEncryption])

Arguments

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

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

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

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

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

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