/* global IITC, L, log -- eslint */
/**
* @namespace window.ornaments
* @description Manages the overlay of additional images (ornaments) on portals, such as beacons, frackers,
* and anomaly markers.
*
* Added as part of the Ingress #Helios in 2014, ornaments are additional image overlays for portals.
* currently there are 6 known types of ornaments: `ap$x$suffix`
* - `cluster portals` (without suffix)
* - `volatile portals` (_v)
* - `meeting points` (_start)
* - `finish points` (_end)
*
* Beacons and Frackers were introduced at the launch of the Ingress ingame store on November 1st, 2015
* - `Beacons` (pe$TAG - $NAME) ie: `peNIA - NIANTIC`
* - `Frackers` ('peFRACK')
* (there are 7 different colors for each of them)
*
* Ornament IDs are dynamic. NIANTIC might change them at any time without prior notice.
* New ornament IDs found on the map are recorded on this device, and the Ornaments page of the
* options window lists them with a checkbox to hide each; the hidden ones are an option, synced
* between devices. To exclude a set of ornaments, even if they have not yet shown up on the map,
* the user can add an entry to excludedOrnaments, which will compared (startsWith) to all known and
* future IDs. example: "ap" to exclude all Ornaments for anomalies (ap1, ap2, ap2_v)
*/
window.ornaments = {
/**
* Default size for ornament.
* @constant
* @type {number}
*/
OVERLAY_SIZE: 60,
/**
* Default opacity for ornament.
* @constant
* @type {number}
*/
OVERLAY_OPACITY: 0.6,
/**
* Object holding optional definitions for ornaments and beacons.
* The icon object holds optional definitions for the ornaments an beacons. The object shall
* be filled from a plugin
* ```
* 'ornamentID' : {
* name: 'meaningful name', // shows up on the Ornaments options page
* layer: 'name for the Layer', // shows up in layerchooser, optional, if not set
* // ornament will be in "Ornaments"
* url: 'url', // from which the image will be taken, optional,
* // 84x84px is default, if not set, stock images will be
* // used
* offset: [dx,dy], // optional, shift the ornament vertically or horizontally by
* // dx (vertical)and dy )horizontal.
* // [0, 0.5] to place right above the portal.
* // default is [0, 0] to center
* opacity: 0..1 // optional, default is 0.6
* }
* ```
*
* @property {object} icon - The icon object for ornaments and beacons.
*/
icon: {},
/**
* List of ornaments to be excluded.
* @property {string[]} excludedOrnaments - Patterns to be excluded from display.
*/
excludedOrnaments: [],
/**
* Known ornaments: the ones seen on this device and the hidden ones, each with whether it is hidden.
* @property {object} knownOrnaments - Object tracking known ornaments.
*/
knownOrnaments: {},
/**
* localStorage key of the IDs of the ornaments seen on this device, kept apart from the options
* @constant
* @type {string}
*/
KNOWN_KEY: 'iitc-ornaments-known',
// IDs of the ornaments seen on this device
_seen: new Set(),
// set while a redraw waits in the microtask queue, so changes in one task redraw once
_reloadQueued: false,
// set while storing the ornaments seen waits in the microtask queue, so new ones in one task are stored and
// shown once
_seenQueued: false,
/**
* Sets up the ornament layer and necessary event handlers.
*
* @function
* @memberof window.ornaments
*/
setup: function () {
this.registerOptions();
this._portals = {};
this.layerGroup = () => new L.LayerGroup();
if (window.map.options.preferCanvas && L.Browser.canvas && !window.DISABLE_CANVASICONLAYER) {
this.layerGroup = L.canvasIconLayer;
L.CanvasIconLayer.mergeOptions({ padding: L.Canvas.prototype.options.padding });
}
this.migrate();
this.load();
this.layers = {};
this.layers['Ornaments'] = window.ornaments.layerGroup();
this.layers['Excluded ornaments'] = window.ornaments.layerGroup(); // to keep excluded ornaments in an own layer
window.layerChooser.addOverlay(this.layers['Ornaments'], 'Ornaments');
window.layerChooser.addOverlay(this.layers['Excluded ornaments'], 'Excluded ornaments', { default: false });
},
/**
* Declares the `ornaments` options page: `excluded` is the comma-separated list of ID prefixes to hide,
* and `hidden` maps each hidden ornament ID to true. A change from the page, a backup or sync updates
* `excludedOrnaments` and `knownOrnaments` and schedules a redraw
*
* @memberof window.ornaments
*/
registerOptions() {
IITC.options.register('ornaments', {
title: 'Ornaments',
accesskey: 'o',
shortcut: { label: 'Ornaments Opt', title: 'Edit ornament exclusions' },
blocks: [
{
type: 'string',
key: 'excluded',
title: 'Hide ornaments that start with',
description: 'Separated by spaces or commas',
onChange: (text) => {
const prefixes = window.ornaments.parsePrefixes(text);
// a list save() stores from the one in use needs no reload
if (prefixes.join(',') === window.ornaments.excludedOrnaments.join(',')) return;
window.ornaments.excludedOrnaments = prefixes;
window.ornaments.scheduleReload();
},
},
{ type: 'heading', title: 'Known ornaments' },
{
type: 'text',
text: 'None seen yet; ornaments are listed as they show up on the map',
visible: () => !Object.keys(window.ornaments.knownOrnaments).length,
},
{
type: 'repeat',
// the ornaments seen here and the ones hidden on any device
over: () =>
Object.keys(window.ornaments.knownOrnaments)
.sort()
.map((id) => ({ id, title: window.ornaments.icon[id]?.name ? `${window.ornaments.icon[id].name} (${id})` : id })),
blocks: [
{
type: 'boolean',
key: 'hidden',
title: 'Hide',
// an ornament a prefix hides shows as hidden, and only the prefix can show it again
enabled: (item) => !window.ornaments.isExcluded(item.id),
value: (item) => (window.ornaments.isExcluded(item.id) ? true : undefined),
onChange: (hidden) => {
window.ornaments.knownOrnaments = window.ornaments.knownFrom(hidden);
window.ornaments.scheduleReload();
},
},
],
},
{
type: 'action',
title: 'Forget known ornaments',
description:
'Clears the Hide marks on every device and forgets the ornaments seen; the ones on the map now are listed again at once, and the prefixes stay',
button: 'Forget',
action: () => window.ornaments.initOrnaments(),
},
],
});
},
/**
* Redraws the ornaments once the current task is done, however many changes it makes
*
* @memberof window.ornaments
*/
scheduleReload() {
if (this._reloadQueued) return;
this._reloadQueued = true;
queueMicrotask(() => {
this._reloadQueued = false;
this.reload();
});
},
/**
* Builds `knownOrnaments` from the ornaments seen on this device and the hidden flags
*
* @memberof window.ornaments
* @param {Object<string, boolean>} hidden - Hidden flags by ornament ID, as the `hidden` option holds them
* @returns {Object<string, boolean>} Whether each known ornament is hidden
*/
knownFrom(hidden) {
const ids = new Set([...this._seen, ...Object.keys(hidden).filter((id) => hidden[id] === true)]);
return Object.fromEntries([...ids].map((id) => [id, hidden[id] === true]));
},
/**
* Reads the IDs of the ornaments seen on this device; none when the stored list cannot be read
*
* @memberof window.ornaments
* @returns {string[]}
*/
readSeen() {
try {
const ids = JSON.parse(localStorage.getItem(this.KNOWN_KEY));
return Array.isArray(ids) ? ids.filter((id) => typeof id === 'string') : [];
} catch (e) {
log.warn(`ornaments: cannot read "${this.KNOWN_KEY}": ${e}`);
return [];
}
},
/**
* Stores the IDs of the ornaments seen on this device once the current task is done, and redraws the
* options page of ornaments if it is shown, so it lists the new ones
*
* @memberof window.ornaments
*/
scheduleSeenSave() {
if (this._seenQueued) return;
this._seenQueued = true;
queueMicrotask(() => {
this._seenQueued = false;
localStorage.setItem(this.KNOWN_KEY, JSON.stringify([...this._seen]));
IITC.options.refresh('ornaments');
});
},
/**
* Moves the ornament options of older builds to the options, once: the prefixes from `excludedOrnaments`,
* and from `knownOrnaments` the hidden ornaments and the ornaments seen. The legacy keys go, values left out
* as unreadable with them; the list of ornaments seen marks the move as done
*
* @memberof window.ornaments
*/
migrate() {
if (localStorage.getItem(this.KNOWN_KEY) !== null) return;
const legacy = (key) => {
try {
return JSON.parse(localStorage.getItem(key));
} catch (e) {
log.warn(`ornaments: cannot read the legacy "${key}": ${e}`);
return null;
}
};
const excluded = legacy('excludedOrnaments');
if (Array.isArray(excluded))
IITC.options.set('ornaments.excluded', excluded.filter((prefix) => typeof prefix === 'string').join(','), { source: 'legacy' });
else if (excluded !== null) log.warn('ornaments: the legacy "excludedOrnaments" is not a list and is left out');
const known = legacy('knownOrnaments');
let seen = [];
if (known !== null && typeof known === 'object' && !Array.isArray(known)) {
seen = Object.keys(known);
// any truthy entry hid the ornament in older builds
IITC.options.set('ornaments.hidden', Object.fromEntries(seen.filter((id) => known[id]).map((id) => [id, true])), { source: 'legacy' });
} else if (known !== null) log.warn('ornaments: the legacy "knownOrnaments" is not a map and is left out');
localStorage.setItem(this.KNOWN_KEY, JSON.stringify(seen));
localStorage.removeItem('excludedOrnaments');
localStorage.removeItem('knownOrnaments');
},
/**
* Tells whether a prefix of `excludedOrnaments` hides an ornament
*
* @memberof window.ornaments
* @param {string} id - Ornament ID
* @returns {boolean}
*/
isExcluded(id) {
return this.excludedOrnaments.some((prefix) => id.startsWith(prefix));
},
/**
* Splits a list of ornament ID prefixes separated by spaces or commas
*
* @memberof window.ornaments
* @param {string} text - Prefixes as typed by the user
* @returns {string[]} Non-empty prefixes
*/
parsePrefixes(text) {
return text.split(/[\s,]+/).filter(Boolean);
},
/**
* Creates a new layer for a given ornament ID.
*
* @function
* @memberof window.ornaments
* @param {string} layerID - The ID for the new layer.
*/
createLayer: function (layerID) {
window.ornaments.layers[layerID] = window.ornaments.layerGroup();
window.layerChooser.addOverlay(window.ornaments.layers[layerID], layerID);
},
/**
* Adds ornament overlays to the specified portal.
*
* @function
* @memberof window.ornaments
* @param {object} portal - The portal to which ornaments are added.
*/
addPortal: function (portal) {
this.removePortal(portal);
var ornaments = portal.options.data.ornaments;
if (ornaments && ornaments.length) {
this._portals[portal.options.guid] = ornaments.map(function (ornament) {
var layer = this.layers['Ornaments'];
var opacity = this.OVERLAY_OPACITY;
var size = this.OVERLAY_SIZE * IITC.portal.marker.scale();
var anchor = [size / 2, size / 2];
var iconUrl = '//commondatastorage.googleapis.com/ingress.com/img/map_icons/marker_images/' + ornament + '.png';
if (!(ornament in this.knownOrnaments)) this.knownOrnaments[ornament] = false;
if (!this._seen.has(ornament)) {
this._seen.add(ornament);
this.scheduleSeenSave();
}
if (ornament in this.icon) {
if (this.icon[ornament].layer) {
if (this.layers[this.icon[ornament].layer] === undefined) {
log.debug('Add missing layer: ', this.icon[ornament].layer);
window.ornaments.createLayer(window.ornaments.icon[ornament].layer);
}
layer = this.layers[window.ornaments.icon[ornament].layer];
}
if (window.ornaments.icon[ornament].url) {
iconUrl = window.ornaments.icon[ornament].url;
if (this.icon[ornament].offset) {
var offset = this.icon[ornament].offset;
anchor = [size * offset[0] + anchor[0], size * offset[1] + anchor[1]];
}
if (this.icon[ornament].opacity) {
opacity = this.icon[ornament].opacity;
}
}
}
var exclude = false;
if (this.excludedOrnaments && !(this.excludedOrnaments.length === 1 && this.excludedOrnaments[0] === '')) {
exclude = this.excludedOrnaments.some(function (pattern) {
return ornament.startsWith(pattern);
});
}
exclude = exclude || this.knownOrnaments[ornament];
if (exclude) {
layer = this.layers['Excluded ornaments'];
}
return new L.Marker(portal.getLatLng(), {
icon: new L.Icon({
iconUrl: iconUrl,
iconSize: [size, size],
iconAnchor: anchor, // https://github.com/IITC-CE/Leaflet.Canvas-Markers/issues/4
className: 'no-pointer-events',
}),
interactive: false,
keyboard: false,
opacity: opacity,
layer: layer,
}).addTo(layer);
}, this);
}
},
/**
* Removes ornament overlays from the specified portal.
*
* @function
* @memberof window.ornaments
* @param {object} portal - The portal from which ornaments are removed.
*/
removePortal: function (portal) {
var guid = portal.options.guid;
if (this._portals[guid]) {
this._portals[guid].forEach(function (marker) {
marker.options.layer.removeLayer(marker);
});
delete this._portals[guid];
}
},
/**
* Forgets the ornaments seen on this device and clears the hidden ones on every device; the redraw lists the
* ornaments on the map again at once, and the prefixes stay
*
* @function
* @memberof window.ornaments
*/
initOrnaments: function () {
this._seen = new Set();
// an empty list rather than none, which would move the legacy options again
localStorage.setItem(this.KNOWN_KEY, '[]');
this.knownOrnaments = {};
IITC.options.reset('ornaments.hidden');
this.scheduleReload();
},
/**
* Loads the ornament options
*
* @function
* @memberof window.ornaments
*/
load: function () {
this.excludedOrnaments = this.parsePrefixes(IITC.options.get('ornaments.excluded'));
this._seen = new Set(this.readSeen());
this.knownOrnaments = this.knownFrom(IITC.options.get('ornaments.hidden'));
},
/**
* Stores `excludedOrnaments` and `knownOrnaments`, as the prefixes, the hidden ornaments and the ornaments
* seen, and redraws the ornaments
*
* @function
* @memberof window.ornaments
*/
save: function () {
const known = Object.entries(this.knownOrnaments);
for (const [id] of known) this._seen.add(id);
this.scheduleSeenSave();
IITC.options.set('ornaments.excluded', this.excludedOrnaments.join(','));
// any truthy entry hides, as for older builds
IITC.options.set('ornaments.hidden', Object.fromEntries(known.filter(([, hidden]) => hidden).map(([id]) => [id, true])));
this.scheduleReload();
},
/**
* Reloads all ornaments on the map.
* @function
* @memberof window.ornaments
*/
reload: function () {
// reload: addPortal also calls removePortal
for (var guid in window.ornaments._portals) {
window.ornaments.addPortal(window.portals[guid]);
}
},
/**
* Opens the Ornaments page of the options window, which replaces the options dialog
*
* @deprecated use `IITC.options.open('ornaments')` instead
* @memberof window.ornaments
*/
ornamentsOpt: () => IITC.options.open('ornaments'),
};