//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------
/**
* Creates a new object.
*
* @constructor
*
* @param {string} id Unique application ID, matching Application.id.
* @throws {Error} If the application ID is missing or invalid.
* @param {number} length The number of positions per highscore table.
* @param {number} tables The number of highscore tables.
*
* @class
* @classdesc
*
* Represents one (or more) (local) highscore tables. A highscore consists of
* name, score and a timestamp (given in Unix time.) The table is sorted in
* numerical descending order, based on score. The actual data is saved in
* localstorage under a (for the application) unique key.
*/
rune.data.Highscores = function(id, length, tables) {
//--------------------------------------------------------------------------
// Private properties
//--------------------------------------------------------------------------
/**
* List containing objects where each object is a high score.
*
* @type {Array.<Object>}
* @private
*/
this.m_data = null;
/**
* App ID.
*
* @type {string}
* @private
*/
this.m_id = this.m_createID(id);
/**
* The number of positions per highscore table.
*
* @type {number}
* @private
*/
this.m_length = Math.max(1, parseInt(length, 10) || 10);
/**
* The number of highscore tables.
*
* @type {number}
* @private
*/
this.m_tables = Math.max(1, parseInt(tables, 10) || 1);
/**
* Pending synchronization cancellation functions.
* @type {Array.<Function>}
* @private
*/
this.m_syncCancels = [];
//--------------------------------------------------------------------------
// Private constants
//--------------------------------------------------------------------------
/**
* ID suffix used to generate the highscore key.
*
* @const {string}
* @private
*/
this.SUFFIX = ".highscores";
/**
* Maximum time to wait for synchronization, in milliseconds.
* @const {number}
* @private
*/
this.SYNC_TIMEOUT = 5000;
//--------------------------------------------------------------------------
// Constructor call
//--------------------------------------------------------------------------
/**
* Invokes secondary class constructor.
*/
this.m_construct();
};
//------------------------------------------------------------------------------
// Public getter and setter methods
//------------------------------------------------------------------------------
/**
* A string value that uniquely identifies the highscore data in localstorage.
* Useful when several applications are distributed via the same domain.
*
* @member {string} key
* @memberof rune.data.Highscores
* @instance
* @readonly
*/
Object.defineProperty(rune.data.Highscores.prototype, "key", {
/**
* @this rune.data.Highscores
* @ignore
*/
get : function() {
return rune.data.StorageKey.create(this.m_id, this.SUFFIX);
}
});
//------------------------------------------------------------------------------
// Public prototype methods (API)
//------------------------------------------------------------------------------
/**
* Removes all highscore data associated with the current application.
* Note that this action cannot be undone.
*
* @return {undefined}
*/
rune.data.Highscores.prototype.clear = function() {
try {
window.localStorage.removeItem(this['key']);
} catch (error) {}
this.m_constructData();
};
/**
* Gets a specific high score based on ranking. Note that first places start
* with index 0 and not 1.
*
* @param {number} ranking Requested ranking.
* @param {number} [table=0] Which table the data should be retrieved from.
*
* @return {Object}
*/
rune.data.Highscores.prototype.get = function(ranking, table) {
table = this.m_resolveTable(table);
ranking = parseInt(ranking, 10);
return table > -1 ? this.m_data[table][ranking] : null;
};
/**
* Returns an independent copy of all highscore tables.
*
* @return {Array.<Object>} Highscore tables.
*/
rune.data.Highscores.prototype.export = function() {
var data = [];
for (var i = 0; i < this.m_data.length; i++) {
var table = [];
for (var j = 0; j < this.m_data[i].length; j++) {
var entry = this.m_data[i][j];
table.push({name: entry.name, score: entry.score, date: entry.date});
}
data.push(table);
}
return data;
};
/**
* Replaces and saves all tables when the data matches this configuration.
* Entries must be sorted by score in descending order.
*
* @param {Array.<Object>} data Highscore tables to import.
* @return {boolean} True if the data was imported.
*/
rune.data.Highscores.prototype.import = function(data) {
if (this.m_validate(data) == false) return false;
for (var i = 0; i < data.length; i++) {
for (var j = 1; j < data[i].length; j++) {
if (data[i][j - 1].score < data[i][j].score) return false;
}
}
var copy = [];
for (var k = 0; k < data.length; k++) {
var table = [];
for (var n = 0; n < data[k].length; n++) {
var entry = data[k][n];
table.push({name: entry.name, score: entry.score, date: entry.date});
}
copy.push(table);
}
this.m_data = copy;
this.save();
return true;
};
/**
* Reloads highscore data from LocalStorage without replacing the current data
* when storage is unavailable or contains invalid data.
*
* @return {boolean} True if valid data was loaded.
*/
rune.data.Highscores.prototype.reload = function() {
var data;
try {
var stored = window.localStorage.getItem(this['key']);
if (stored == null) return false;
data = JSON.parse(stored);
} catch (error) {
return false;
}
if (!Array.isArray(data)) return false;
if (this.m_validate(data) == false) return false;
this.m_data = data;
return true;
};
/**
* Requests highscore synchronization from the host, if available. The callback
* is always invoked asynchronously with success and updated boolean properties.
* The local list remains available when synchronization cannot be performed.
* Pending callbacks are cancelled when this object is disposed.
*
* @param {Function} [callback] Called when synchronization finishes.
* @return {undefined}
*/
rune.data.Highscores.prototype.sync = function(callback) {
var host = window['runeos'];
var owner = this;
var finished = false;
var cancelled = false;
var timeout;
var callbackTimeout;
var remove = function() {
var index = owner.m_syncCancels.indexOf(cancel);
if (index != -1) owner.m_syncCancels.splice(index, 1);
};
var cancel = function() {
cancelled = true;
window.clearTimeout(timeout);
window.clearTimeout(callbackTimeout);
remove();
};
var complete = function(result) {
if (finished || cancelled) return;
finished = true;
window.clearTimeout(timeout);
var success = !!(result && result['success']);
var updated = success && !!result['updated'];
if (typeof callback == "function") {
callbackTimeout = window.setTimeout(function() {
remove();
if (!cancelled) callback({success: success, updated: updated});
}, 0);
} else {
remove();
}
};
this.m_syncCancels.push(cancel);
if (!host || typeof host['syncHighscores'] != "function") {
complete(null);
return;
}
timeout = window.setTimeout(function() {
complete(null);
}, this.SYNC_TIMEOUT);
try {
host['syncHighscores'](this.m_id, this, complete);
} catch (error) {
complete(null);
}
};
/**
* Saves all high-score data in the device's LocalStorage. The method is
* called automatically when new data is added to the object. There is thus
* no reason to include the method in the public documentation.
*
* @return {undefined}
* @ignore
*/
rune.data.Highscores.prototype.save = function() {
try {
window.localStorage.setItem(this['key'], JSON.stringify(this.m_data));
} catch (error) {}
};
/**
* Tests whether a score can qualify as a high score. The method returns the
* raking of the score in the form of an integer. The result -1 indicates that
* the score is outside the scope of the current high score table and thus not
* a high score. Note that a test does not affect the current high score list,
* nothing is saved or deleted when a test is performed. Non-finite scores
* cannot qualify and return -1.
*
* @param {number} score Score to test.
* @param {number} [table=0] Table to test against.
*
* @return {number} Current ranking on the highscore list.
*/
rune.data.Highscores.prototype.test = function(score, table) {
table = this.m_resolveTable(table);
score = parseFloat(score);
if (table == -1 || !isFinite(score)) {
return -1;
}
for (var i = 0; i < this.m_data[table].length; i++) {
if (score > this.m_data[table][i].score) {
return i;
}
}
return -1;
};
/**
* Sends data to the highscore list. The data is saved if it qualifies as a
* highscore.
*
* @param {number} score Score to save.
* @param {string} [name=Rune] Name of score holder.
* @param {number} [table=0] Which table to use.
*
* @return {number} Current ranking on the highscore list.
*/
rune.data.Highscores.prototype.send = function(score, name, table) {
table = this.m_resolveTable(table);
if (table == -1) {
return -1;
}
var index = this.test(score, table);
if (index > -1) {
this.m_data[table].splice(index, 0, {
name: name || "Rune",
score: parseFloat(score),
date: Date.now()
});
this.m_data[table].length = this.m_length;
this.save();
}
return index;
};
//------------------------------------------------------------------------------
// Public prototype methods (ENGINE)
//------------------------------------------------------------------------------
/**
* Initiates deallocation of this object.
*
* @return {undefined}
*/
rune.data.Highscores.prototype.dispose = function() {
while (this.m_syncCancels.length) this.m_syncCancels[0]();
this.m_data = null;
};
//------------------------------------------------------------------------------
// Protected prototype methods
//------------------------------------------------------------------------------
/**
* The class constructor.
*
* @return {undefined}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_construct = function() {
this.m_constructData();
};
/**
* Retrieves highscore data from LocalStorage. If no valid data can be
* retrieved, a new one is created.
*
* @return {undefined}
* @protected
* @ignore
* @suppress {checkTypes}
*/
rune.data.Highscores.prototype.m_constructData = function() {
try {
this.m_data = JSON.parse(window.localStorage.getItem(this['key']));
} catch (error) {
this.m_data = null;
}
if (this.m_validate(this.m_data) == false) {
this.m_data = [];
for (var i = 0; i < this.m_tables; i++) {
this.m_data.push(this.m_constructTable(this.m_length));
}
this.save();
}
};
/**
* Creates a new table.
*
* @param {number} [length] Length of table.
*
* @return {Array}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_constructTable = function(length) {
length = parseInt(length, 10) || this.m_length;
var table = [];
while (table.length < length) {
table.push({
name: "Rune",
score: 0,
date: Date.now()
});
}
return table;
};
/**
* Validates highscore data.
*
* @param {Array.<Object>} data Data to validate.
*
* @return {boolean}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_validate = function(data) {
if (Array.isArray(data)) {
if (data.length == this.m_tables) {
for (var i = 0; i < data.length; i++) {
if (!Array.isArray(data[i]) || data[i].length != this.m_length) {
return false;
}
for (var j = 0; j < data[i].length; j++) {
if (this.m_validateEntry(data[i][j]) == false) {
return false;
}
}
}
return true;
}
}
return false;
};
/**
* Validates the explicit application ID through the shared storage key helper.
*
* @param {string} id The App ID.
*
* @return {string}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_createID = function(id) {
return rune.data.StorageKey.createID(id);
};
/**
* Resolves a highscore table index.
*
* @param {number=} table Table index.
*
* @return {number}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_resolveTable = function(table) {
table = parseInt(table || 0, 10);
return table >= 0 && table < this.m_tables ? table : -1;
};
/**
* Validates a single highscore entry. Scores and timestamps must be finite
* numbers so JSON serialization cannot silently replace them with null.
*
* @param {Object} entry Highscore entry.
*
* @return {boolean}
* @protected
* @ignore
*/
rune.data.Highscores.prototype.m_validateEntry = function(entry) {
return entry != null &&
typeof entry.name == "string" &&
typeof entry.score == "number" &&
typeof entry.date == "number" &&
isFinite(entry.score) &&
isFinite(entry.date);
};