diff --git a/code/entity_decode.js b/code/entity_decode.js index 5a6398f4c..d968f43fb 100644 --- a/code/entity_decode.js +++ b/code/entity_decode.js @@ -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') @@ -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], @@ -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); } @@ -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; diff --git a/code/portal_info.js b/code/portal_info.js index 29d607c6c..d0975736e 100644 --- a/code/portal_info.js +++ b/code/portal_info.js @@ -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 diff --git a/code/portal_marker.js b/code/portal_marker.js index b9bfb764c..4da5ea6e6 100644 --- a/code/portal_marker.js +++ b/code/portal_marker.js @@ -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();