ogamejs 3.0.0 → 4.0.0

package/src/fleets/flight.js

@@ -0,0 +1,105 @@
+import getDistance from './distance.js';
+import { getFleetSpeed, getActiveDrive } from './speed.js';
+
+function assertSpeedPercent(speedPercent) {
+  if (!Number.isFinite(speedPercent) || speedPercent <= 0 || speedPercent > 100) {
+    throw new Error(`speedPercent must be between 1 and 100, received ${speedPercent}`);
+  }
+}
+
+/**
+ *
+ * Return the one way flight time of a fleet
+ *
+ * `(10 + 35000 / speedPercent * sqrt(distance * 10 / fleetSpeed)) / universeFleetSpeed`
+ * @param {number} distance The distance to cross, from `getDistance`
+ * @param {number} fleetSpeed The speed of the slowest ship, from `getFleetSpeed`
+ * @param {number} [speedPercent] The fleet speed slider, 10 to 100 in game
+ * @param {number} [universeFleetSpeed] The universe fleet speed
+ * @returns {number} The flight time, in seconds
+ */
+function getFlightTime(distance, fleetSpeed, speedPercent = 100, universeFleetSpeed = 1) {
+  assertSpeedPercent(speedPercent);
+
+  if (!(fleetSpeed > 0)) {
+    throw new Error(`fleetSpeed must be greater than 0, received ${fleetSpeed}`);
+  }
+
+  const seconds = 10 + (35000 / speedPercent) * Math.sqrt((distance * 10) / fleetSpeed);
+
+  return Math.round(seconds / universeFleetSpeed);
+}
+
+/**
+ *
+ * Return the deuterium a fleet burns for a one way trip
+ *
+ * `1 + round(sum(consumption * count) * distance / 35000 * (speedPercent / 100 + 1) ** 2)`
+ * @param {import('../types.js').FleetEntry[]} fleet The ships taking off
+ * @param {number} distance The distance to cross, from `getDistance`
+ * @param {number} [speedPercent] The fleet speed slider, 10 to 100 in game
+ * @param {import('../types.js').Drives} [drives] Drive levels, needed because a
+ *   ship that switched drive also changed its consumption
+ * @returns {number} The fuel needed, in deuterium
+ */
+function getFuelConsumption(fleet, distance, speedPercent = 100, drives = {}) {
+  assertSpeedPercent(speedPercent);
+
+  if (!Array.isArray(fleet) || fleet.length === 0) {
+    throw new Error('fleet must be a non empty array of { ship, count }');
+  }
+
+  const speedFactor = (speedPercent / 100 + 1) ** 2;
+
+  const consumption = fleet.reduce((total, { ship, count }) => {
+    // A ship that switched drive also changed how much it burns.
+    const { fuelConsumption } = getActiveDrive(ship, drives);
+
+    return total + fuelConsumption * count;
+  }, 0);
+
+  return 1 + Math.round((consumption * distance) / 35000 * speedFactor);
+}
+
+/**
+ *
+ * Return everything about a trip: distance, duration, fuel and cargo left
+ * @param {import('../types.js').FleetEntry[]} fleet The ships taking off
+ * @param {import('../types.js').Coordinates} origin Where the fleet leaves from
+ * @param {import('../types.js').Coordinates} target Where it goes
+ * @param {object} [options] Trip options
+ * @param {number} [options.speedPercent] The fleet speed slider, 10 to 100 in game
+ * @param {number} [options.universeFleetSpeed] The universe fleet speed
+ * @param {import('../types.js').Drives} [options.drives] The drive technology levels
+ * @param {boolean} [options.roundTrip] Whether to account for the way back too
+ * @returns {{
+ *   distance: number, fleetSpeed: number, duration: number, fuel: number,
+ *   cargo: number, cargoAfterFuel: number,
+ * }} The trip, with durations in seconds and `cargoAfterFuel` the room left once
+ *   the fuel is loaded
+ */
+function getTrip(fleet, origin, target, options = {}) {
+  const {
+    speedPercent = 100,
+    universeFleetSpeed = 1,
+    drives = {},
+    roundTrip = false,
+  } = options;
+
+  const distance = getDistance(origin, target);
+  const fleetSpeed = getFleetSpeed(fleet, drives);
+  const oneWay = getFlightTime(distance, fleetSpeed, speedPercent, universeFleetSpeed);
+  const fuel = getFuelConsumption(fleet, distance, speedPercent, drives) * (roundTrip ? 2 : 1);
+  const cargo = fleet.reduce((total, { ship, count }) => total + ship.cargo * count, 0);
+
+  return {
+    distance,
+    fleetSpeed,
+    duration: roundTrip ? oneWay * 2 : oneWay,
+    fuel,
+    cargo,
+    cargoAfterFuel: Math.max(0, cargo - fuel),
+  };
+}
+
+export { getFlightTime, getFuelConsumption, getTrip };

package/src/fleets/getDebris.js

@@ -1,19 +1,20 @@
 /**
  *
- * Returns the number of debris generated
- * @param {number} shipId The ship identifier
- * @param {number} number The number of ship
- * @param {number} factor The universe debris factor
- * @return {Object} The debris generated
+ * Return the debris field left behind by destroyed ships or defenses
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {number} number The number of destroyed units
+ * @param {number} factor The universe debris factor, e.g. 0.3 for 30%
+ * @param {number} [deuteriumFactor] The universe deuterium debris factor, 0 on most universes
+ * @return {import('../types.js').Resources} The debris generated
  */
-function getDebris(ship, number, factor) {
+function getDebris(ship, number, factor, deuteriumFactor = 0) {
   const { cost } = ship;
-  const metalDebris = cost.metal ? cost.metal * factor : 0;
-  const crystalDebris = cost.crystal ? cost.crystal * factor : 0;
+  const deuteriumCost = cost.deuterium ?? cost.deut ?? 0;
 
   return {
-    metal: metalDebris * number,
-    crystal: crystalDebris * number,
+    metal: (cost.metal ?? 0) * factor * number,
+    crystal: (cost.crystal ?? 0) * factor * number,
+    deuterium: deuteriumCost * deuteriumFactor * number,
   };
 }
 

package/src/fleets/index.js

@@ -1,7 +1,19 @@
 import getDebris from './getDebris.js';
+import getDistance from './distance.js';
+import getShipSpeed, { getActiveDrive, getFleetSpeed } from './speed.js';
+import { getFlightTime, getFuelConsumption, getTrip } from './flight.js';
+import simulateCombat from './combat.js';
 
 const Fleets = {
   getDebris,
+  getDistance,
+  getShipSpeed,
+  getActiveDrive,
+  getFleetSpeed,
+  getFlightTime,
+  getFuelConsumption,
+  getTrip,
+  simulateCombat,
 };
 
 export default Fleets;

package/src/fleets/speed.js

@@ -0,0 +1,108 @@
+import { ATTRIBUTES } from '../models/destroyable.js';
+
+const { DRIVES } = ATTRIBUTES;
+
+/** Each drive level adds that share of the ship base speed. */
+const DRIVE_BONUS = Object.freeze({
+  [DRIVES.COMBUSTION]: 0.1,
+  [DRIVES.IMPULSE]: 0.2,
+  [DRIVES.HYPERSPACE]: 0.3,
+  [DRIVES.NONE]: 0,
+});
+
+/** The research id backing each drive, handy to look the level up. */
+const DRIVE_RESEARCH = Object.freeze({
+  [DRIVES.COMBUSTION]: 115,
+  [DRIVES.IMPULSE]: 117,
+  [DRIVES.HYPERSPACE]: 118,
+});
+
+function driveLevel(drives, drive) {
+  if (!Object.hasOwn(DRIVE_BONUS, drive)) {
+    throw new Error(`unknown drive ${drive}`);
+  }
+
+  // eslint-disable-next-line security/detect-object-injection -- drive is a known key
+  const level = drives?.[drive] ?? 0;
+
+  if (!Number.isInteger(level) || level < 0) {
+    throw new Error(`drives.${drive} must be an integer >= 0, received ${level}`);
+  }
+
+  return level;
+}
+
+function speedWith(baseSpeed, drive, drives) {
+  // eslint-disable-next-line security/detect-object-injection -- drive is a known key
+  return Math.floor(baseSpeed * (1 + DRIVE_BONUS[drive] * driveLevel(drives, drive)));
+}
+
+/**
+ *
+ * Return the drive a ship actually flies on, and the speed it reaches
+ *
+ * A few ships switch to a better drive once the matching technology is high
+ * enough — a small cargo moves to the impulse drive at Impulse 5. When several
+ * drives are available the ship uses whichever ends up fastest.
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {import('../types.js').Drives} [drives] Drive levels
+ * @returns {{drive: string, speed: number, fuelConsumption: number}} The active drive
+ */
+function getActiveDrive(ship, drives = {}) {
+  if (!ship || !ship.drive) {
+    throw new Error('expected an entry of models/destroyable.js');
+  }
+
+  const candidates = [
+    { drive: ship.drive, speed: ship.speed, fuelConsumption: ship.fuelConsumption },
+    ...(ship.driveUpgrades ?? [])
+      .filter((upgrade) => driveLevel(drives, upgrade.drive) >= upgrade.minLevel),
+  ];
+
+  return candidates
+    .map(({ drive, speed, fuelConsumption }) => ({
+      drive,
+      speed: speedWith(speed, drive, drives),
+      fuelConsumption,
+    }))
+    .reduce((best, candidate) => (candidate.speed > best.speed ? candidate : best));
+}
+
+/**
+ *
+ * Return the speed of a ship, drive technologies included
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {import('../types.js').Drives} [drives] Drive levels
+ * @returns {number} The speed the ship flies at
+ */
+function getShipSpeed(ship, drives = {}) {
+  return getActiveDrive(ship, drives).speed;
+}
+
+/**
+ *
+ * Return the speed of a whole fleet, which is the speed of its slowest ship
+ * @param {import('../types.js').FleetEntry[]} fleet The ships taking off
+ * @param {import('../types.js').Drives} [drives] Drive levels
+ * @returns {number} The fleet speed
+ */
+function getFleetSpeed(fleet, drives = {}) {
+  if (!Array.isArray(fleet) || fleet.length === 0) {
+    throw new Error('fleet must be a non empty array of { ship, count }');
+  }
+
+  const speeds = fleet
+    .filter(({ count }) => count > 0)
+    .map(({ ship }) => getShipSpeed(ship, drives));
+
+  if (speeds.length === 0) {
+    throw new Error('fleet must hold at least one ship with a count above 0');
+  }
+
+  return Math.min(...speeds);
+}
+
+export {
+  getActiveDrive, getFleetSpeed, DRIVE_BONUS, DRIVE_RESEARCH,
+};
+export default getShipSpeed;

package/src/i18n.js

@@ -0,0 +1,43 @@
+const DEFAULT_LANG = 'en';
+
+const LANGS = Object.freeze(['en', 'fr']);
+
+/**
+ *
+ * Return the localised name of a model entry
+ * @param {{names: import('./types.js').Names}} entry An entry of Buildings, Destroyable or Research
+ * @param {import('./types.js').Lang} [lang] 'en' or 'fr', defaults to 'en'
+ * @returns {string} The localised name
+ */
+function getName(entry, lang = DEFAULT_LANG) {
+  if (!entry || !entry.names) {
+    throw new Error('entry has no names, is it a model entry?');
+  }
+
+  // eslint-disable-next-line security/detect-object-injection
+  return entry.names[lang] ?? entry.names[DEFAULT_LANG];
+}
+
+/**
+ *
+ * Look an entry up by any of its localised names, case and accent insensitive
+ * @param {Record<string|number, {names: import('./types.js').Names}>} model Buildings, Destroyable or Research
+ * @param {string} name The name to look for, in any supported language
+ * @returns {object|undefined} The matching entry, or undefined
+ */
+function findByName(model, name) {
+  const normalize = (value) => value
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .trim()
+    .toLowerCase();
+
+  const needle = normalize(name);
+
+  return Object.values(model).find((entry) => LANGS
+    // `lang` comes from the LANGS constant, never from the caller.
+    // eslint-disable-next-line security/detect-object-injection
+    .some((lang) => entry.names?.[lang] && normalize(entry.names[lang]) === needle));
+}
+
+export { getName, findByName, LANGS };

package/src/index.js

@@ -1,16 +1,27 @@
 import Trader from './trades/index.js';
 import Building from './buildings/index.js';
 import Fleets from './fleets/index.js';
+import Research from './research/index.js';
 import Buildings from './models/buildings.js';
-import Destroyable from './models/destroyable.js';
+import Destroyable, { ATTRIBUTES } from './models/destroyable.js';
+import ResearchModel from './models/research.js';
+import { getName, findByName, LANGS } from './i18n.js';
 
 const Ogame = {
   Trader,
   Building,
   Fleets,
+  Research,
+  i18n: {
+    getName,
+    findByName,
+    LANGS,
+  },
   models: {
     Buildings,
     Destroyable,
+    Research: ResearchModel,
+    ATTRIBUTES,
   },
 };
 

package/src/models/buildings.js

@@ -1,59 +1,319 @@
+const CATEGORIES = Object.freeze({
+  RESOURCES: 'resources',
+  FACILITIES: 'facilities',
+  MOON: 'moon',
+});
+
+/**
+ * Every building of the game, keyed by the id used by this library.
+ *
+ * Ids 1 to 5 are historical and kept for backward compatibility; every other
+ * entry uses the id OGame itself uses. `ogameId` always holds the official id,
+ * so it is the field to rely on when talking to the game.
+ *
+ * - `names` holds the localised labels.
+ * - `factor` is the per-level cost multiplier: cost(level) = base * factor ** (level - 1).
+ * - `base` holds the level 1 values, with every energy and deuterium flow named
+ *   after what it actually is:
+ *   - `metal` / `crystal` / `deuterium` — the resources paid to build it,
+ *   - `energyCost` — the energy paid to build it (Terraformer and Space Dock only),
+ *   - `energyConsumption` — the energy it consumes once built (mines),
+ *   - `deuteriumConsumption` — the deuterium it burns once built (Fusion Reactor),
+ *   - `production` — what it produces, resources or energy.
+ */
 const BUILDINGS = Object.freeze({
   1: {
-    name: 'Mine de métal',
+    ogameId: 1,
+    names: { en: 'Metal Mine', fr: 'Mine de métal' },
+    category: CATEGORIES.RESOURCES,
+    factor: 1.5,
     base: {
-      production: 30,
-      consumption: 0,
       metal: 60,
       crystal: 15,
-      deutrium: 0,
-      energy: 10,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 10,
+      deuteriumConsumption: 0,
+      production: 30,
     },
   },
   2: {
-    name: 'Mine de cristal',
+    ogameId: 2,
+    names: { en: 'Crystal Mine', fr: 'Mine de cristal' },
+    category: CATEGORIES.RESOURCES,
+    factor: 1.6,
     base: {
-      production: 20,
-      consumption: 0,
       metal: 48,
       crystal: 24,
-      deutrium: 0,
-      energy: 10,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 10,
+      deuteriumConsumption: 0,
+      production: 20,
     },
   },
   3: {
-    name: 'Synthétiseur de deutérium',
+    ogameId: 3,
+    names: { en: 'Deuterium Synthesizer', fr: 'Synthétiseur de deutérium' },
+    category: CATEGORIES.RESOURCES,
+    factor: 1.5,
     base: {
-      production: 10,
-      consumption: 0,
       metal: 225,
       crystal: 75,
-      deutrium: 0,
-      energy: 20,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 20,
+      deuteriumConsumption: 0,
+      production: 10,
     },
   },
   4: {
-    name: 'Centrale électrique solaire',
+    ogameId: 4,
+    names: { en: 'Solar Plant', fr: 'Centrale électrique solaire' },
+    category: CATEGORIES.RESOURCES,
+    factor: 1.5,
     base: {
-      production: 20,
-      consumption: 0,
       metal: 75,
       crystal: 30,
-      deutrium: 0,
-      energy: 0,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 20,
     },
   },
   5: {
-    name: 'Centrale électrique de fusion',
+    ogameId: 12,
+    names: { en: 'Fusion Reactor', fr: 'Centrale électrique de fusion' },
+    category: CATEGORIES.RESOURCES,
+    factor: 1.8,
     base: {
-      production: 30,
-      consumption: 10,
       metal: 900,
       crystal: 360,
-      deutrium: 180,
-      energy: 0,
+      deuterium: 180,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 10,
+      production: 30,
+    },
+  },
+  14: {
+    ogameId: 14,
+    names: { en: 'Robotics Factory', fr: 'Usine de robots' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 400,
+      crystal: 120,
+      deuterium: 200,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  15: {
+    ogameId: 15,
+    names: { en: 'Nanite Factory', fr: 'Usine de nanites' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 1000000,
+      crystal: 500000,
+      deuterium: 100000,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  21: {
+    ogameId: 21,
+    names: { en: 'Shipyard', fr: 'Chantier spatial' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 400,
+      crystal: 200,
+      deuterium: 100,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  22: {
+    ogameId: 22,
+    names: { en: 'Metal Storage', fr: 'Hangar de métal' },
+    category: CATEGORIES.RESOURCES,
+    factor: 2,
+    storage: 'metal',
+    base: {
+      metal: 1000,
+      crystal: 0,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  23: {
+    ogameId: 23,
+    names: { en: 'Crystal Storage', fr: 'Hangar de cristal' },
+    category: CATEGORIES.RESOURCES,
+    factor: 2,
+    storage: 'crystal',
+    base: {
+      metal: 1000,
+      crystal: 500,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  24: {
+    ogameId: 24,
+    names: { en: 'Deuterium Tank', fr: 'Réservoir de deutérium' },
+    category: CATEGORIES.RESOURCES,
+    factor: 2,
+    storage: 'deuterium',
+    base: {
+      metal: 1000,
+      crystal: 1000,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  31: {
+    ogameId: 31,
+    names: { en: 'Research Lab', fr: 'Laboratoire de recherche' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 200,
+      crystal: 400,
+      deuterium: 200,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  33: {
+    ogameId: 33,
+    names: { en: 'Terraformer', fr: 'Terraformeur' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 0,
+      crystal: 50000,
+      deuterium: 100000,
+      energyCost: 1000,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  34: {
+    ogameId: 34,
+    names: { en: 'Alliance Depot', fr: 'Dépôt de ravitaillement' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 20000,
+      crystal: 40000,
+      deuterium: 0,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  36: {
+    ogameId: 36,
+    names: { en: 'Space Dock', fr: 'Dock spatial' },
+    category: CATEGORIES.FACILITIES,
+    factor: 5,
+    // The space dock is the only building whose energy cost grows on its own
+    // factor, hence the extra `energyFactor`.
+    energyFactor: 2.5,
+    base: {
+      metal: 200,
+      crystal: 0,
+      deuterium: 50,
+      energyCost: 50,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  41: {
+    ogameId: 41,
+    names: { en: 'Lunar Base', fr: 'Base lunaire' },
+    category: CATEGORIES.MOON,
+    factor: 2,
+    base: {
+      metal: 20000,
+      crystal: 40000,
+      deuterium: 20000,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  42: {
+    ogameId: 42,
+    names: { en: 'Sensor Phalanx', fr: 'Phalange de capteur' },
+    category: CATEGORIES.MOON,
+    factor: 2,
+    base: {
+      metal: 20000,
+      crystal: 40000,
+      deuterium: 20000,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  43: {
+    ogameId: 43,
+    names: { en: 'Jump Gate', fr: 'Porte de saut spatial' },
+    category: CATEGORIES.MOON,
+    factor: 2,
+    base: {
+      metal: 2000000,
+      crystal: 4000000,
+      deuterium: 2000000,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
+    },
+  },
+  44: {
+    ogameId: 44,
+    names: { en: 'Missile Silo', fr: 'Silo de missiles' },
+    category: CATEGORIES.FACILITIES,
+    factor: 2,
+    base: {
+      metal: 20000,
+      crystal: 20000,
+      deuterium: 1000,
+      energyCost: 0,
+      energyConsumption: 0,
+      deuteriumConsumption: 0,
+      production: 0,
     },
   },
 });
 
+export { CATEGORIES };
 export default BUILDINGS;