Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation updates to some portal and entity functions. #1128

Closed
wants to merge 1 commit into from
Closed

Documentation updates to some portal and entity functions. #1128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 107 additions & 4 deletions code/entity_decode.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,96 @@

//there's also a 'placeholder' portal - generated from the data in links/fields. only has team/lat/lng

var CORE_PORTA_DATA_LENGTH = 4;
var CORE_PORTAL_DATA_LENGTH = 4;
var SUMMARY_PORTAL_DATA_LENGTH = 14;

/**
* Placeholder data for the portal. Typically used only at lower zoom levels (showing larger area).
* @typedef {Object} PortalDataCore
* @property {string} team - 'E' for Enlightened, 'R' for Resistance, 'N' for none.
* @property {number} latE6 - The latitude of the portal multiplied by 10^6. (49.185163 becomes 49185163).
* @property {number} longE6 - The longitude of the portal multiplied by 10^6.
*/

/**
* Extended data for the portal. Available at higher zoom levels. Is not a complete portal representation.
* @typedef {Object} PortalDataExtended
* @property {string} title - The title of the portal.
* @property {string} image - The URL of the portal image.
* @property {number} level - Indicates the level (1 through 8) of the portal. Note that unclaimed portals are reported as level 1.
* @property {number} resCount - The number of resonators (0 to 8) installed on the portal.*
* @property {number} health - The health of the portal as expressed as a number between 0 and 100.
* TODO Get ornaments type.
* @property {Object} ornaments - Provides ornament data.
* TODO Get mission type.
* @property {Object} mission - Provides mission data.
* TODO Get mission50plus type.
* @property {Object} mission50plus - Provides mission data.
* TODO Get artifactBrief type.
* @property {Object} artifactBrief - Provides artifact data.
* TODO Get timestamp type.
* @property {Object} timestamp.
*/

/**
* Complete portal data. Composite of {PortalDataCore} and {PortalDataExtended} objects.
* @typedef {Object} PortalData
* @property {string} team - 'E' for Enlightened, 'R' for Resistance, 'N' for none.
* @property {number} latE6 - The latitude of the portal multiplied by 10^6. (49.185163 becomes 49185163).
* @property {number} longE6 - The longitude of the portal multiplied by 10^6.
* @property {string} title - The title of the portal.
* @property {string} image - The URL of the portal image.
* @property {number} level - Indicates the level (1 through 8) of the portal. Note that unclaimed portals are reported as level 1.
* @property {number} resCount - The number of resonators (0 to 8) installed on the portal.*
* @property {number} health - The health of the portal as expressed as a number between 0 and 100.
* TODO Get ornaments type.
* @property {Object} ornaments - Provides ornament data.
* TODO Get mission type.
* @property {Object} mission - Provides mission data.
* TODO Get mission50plus type.
* @property {Object} mission50plus - Provides mission data.
* TODO Get artifactBrief type.
* @property {Object} artifactBrief - Provides artifact data.
* TODO Get timestamp type.
* @property {Object} timestamp.
*/

/**
* Complete portal data. Superset of {PortalData} data.
* @typedef {Object} PortalDataDetail
* @property {string} team - 'E' for Enlightened, 'R' for Resistance, 'N' for none.
* @property {number} latE6 - The latitude of the portal multiplied by 10^6. (49.185163 becomes 49185163).
* @property {number} longE6 - The longitude of the portal multiplied by 10^6.
* @property {string} title - The title of the portal.
* @property {string} image - The URL of the portal image.
* @property {number} level - Indicates the level (1 through 8) of the portal. Note that unclaimed portals are reported as level 1.
* @property {number} resCount - The number of resonators (0 to 8) installed on the portal.*
* @property {number} health - The health of the portal as expressed as a number between 0 and 100.
* TODO Get ornaments type.
* @property {Object} ornaments - Provides ornament data.
* TODO Get mission type.
* @property {Object} mission - Provides mission data.
* TODO Get mission50plus type.
* @property {Object} mission50plus - Provides mission data.
* TODO Get artifactBrief type.
* @property {Object} artifactBrief - Provides artifact data.
* TODO Get timestamp type. Confirm whether timestamp is update data, or something else.
* @property {Object} timestamp - Timestamp for the portal.
* TODO get mods type.
* @property {Object} mods - Mod data.
* TODO get resonators type.
* @property {Object} resonators - Resonator data.
* TODO get owner type.
* @property {Object} owner - Owner data.
* TODO get artifact detail type.
* @property {Object} artifactDetail - Artifact detail data.
*/

/**
* Returns a core portal data object.
* @param {Array} a - The entity array provided by server. Expected to contain four objects.
* @returns {PortalDataCore} The core data for this portal.
*/
function corePortalData(a) {
return {
// a[0] == type (always 'p')
Expand All @@ -75,7 +164,11 @@
}
};

var SUMMARY_PORTAL_DATA_LENGTH = 14;
/**
* Returns a core portal data object.
* @param {Array} a - The entity array provided by server. Expected to contain four objects.
* @returns {PortalDataCore} The core data for this portal.
*/
function summaryPortalData(a) {
return {
level: a[4],
Expand All @@ -91,15 +184,20 @@
};
};

var DETAILED_PORTAL_DATA_LENGTH = SUMMARY_PORTAL_DATA_LENGTH+4;
var DETAILED_PORTAL_DATA_LENGTH = SUMMARY_PORTAL_DATA_LENGTH+CORE_PORTAL_DATA_LENGTH;


/**
* Decodes the portal summary data.
* @param a - Array containing portal data.
* @returns {PortalDataCore, PortalData} Returns either a core data object, or a complete data object.
*/
window.decodeArray.portalSummary = function(a) {
if (!a) return undefined;

if (a[0] != 'p') throw 'Error: decodeArray.portalSUmmary - not a portal';

if (a.length == CORE_PORTA_DATA_LENGTH) {
if (a.length == CORE_PORTAL_DATA_LENGTH) {
return corePortalData(a);
}

Expand All @@ -113,6 +211,11 @@
return $.extend(corePortalData(a), summaryPortalData(a));
}

/**
* Decodes the portal detail data.
* @param a Array of portal data. Expected to include all portal data.
* @returns {PortalDataDetail} The portal detail object.
*/
window.decodeArray.portalDetail = function(a) {
if (!a) return undefined;

Expand Down
22 changes: 20 additions & 2 deletions code/portal_info.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,9 +295,27 @@ window.getPortalHackDetails = function(d) {
return {cooldown: cooldownTime, hacks: numHacks, burnout: cooldownTime*(numHacks-1)};
}

// given a detailed portal structure, return summary portal data, as seen in the map tile data
window.getPortalSummaryData = function(d) {

/**
* Summarizes a portal.
* @typedef {Object} PortalSummaryData
* @property {number} latE6 - The latitude of the portal multiplied by 10^6. (49.185163 becomes 49185163).
* @property {number} longE6 - The longitude of the portal multiplied by 10^6.
* @property {string} title - The title of the portal.
* @property {string} image - The URL of the portal image.
* @property {number} level - Indicates the level (1 through 8) of the portal. Note that unclaimed portals are reported as level 1.
* @property {string} team - The team of the portal, 'E' for Enlightened, 'R' for Resistance, or 'N' for none.
* @property {number} resCount - The number of resonators (0 to 8) installed on the portal.*
* @property {number} health - The health of the portal as expressed as a number between 0 and 100.
* @property {string} type - The type of the portal, always 'portal'.
*/

/**
* Returns a portal summary object.
* @param d Expects a portal data object with properties health
* @returns {PortalSummary}
*/
window.getPortalSummaryData = function(d) {
// NOTE: the summary data reports unclaimed portals as level 1 - not zero as elsewhere in IITC
var level = parseInt(getPortalLevel(d));
if (level == 0) level = 1; //niantic returns neutral portals as level 1, not 0 as used throughout IITC elsewhere
Expand Down
6 changes: 5 additions & 1 deletion code/portal_marker.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,11 @@ window.setMarkerStyle = function(marker, selected) {
}
}


/**
* Generates the default style marker options based on portal details.
* @param details {PortalData}
* @returns {{radius: number, stroke: boolean, color: *, weight: number, opacity: number, fill: boolean, fillColor: *, fillOpacity: number, dashArray: *}}
*/
window.getMarkerStyleOptions = function(details) {
var scale = window.portalMarkerScale();

Expand Down