ogamejs 3.0.0 → 4.0.1

package/src/buildings/production.js

@@ -0,0 +1,150 @@
+import getMetalMine from './metal.js';
+import getCrystalMine from './crystal.js';
+import getDeutSynth from './deut.js';
+import BUILDINGS from '../models/buildings.js';
+
+/**
+ * Plasma technology is worth more on metal than on crystal, and more on crystal
+ * than on deuterium.
+ */
+const PLASMA_BONUS = Object.freeze({ metal: 0.01, crystal: 0.0066, deuterium: 0.0033 });
+
+/** The geologist officer adds a flat 10% to the three mines. */
+const GEOLOGIST_BONUS = 0.1;
+
+/** The collector class adds 25% to mine production. */
+const COLLECTOR_BONUS = 0.25;
+
+/**
+ * Every planet produces this much per hour on its own, mines or not. It is a
+ * flat income: no bonus applies to it.
+ */
+const BASE_INCOME = Object.freeze({ metal: 30, crystal: 15, deuterium: 0 });
+
+const RESOURCES = Object.freeze(['metal', 'crystal', 'deuterium']);
+
+function clampRatio(value, name) {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error(`${name} must be a number between 0 and 1, received ${value}`);
+  }
+
+  return value;
+}
+
+/**
+ *
+ * Return the production multiplier of each resource
+ *
+ * The multipliers add up, they are not compounded: plasma 15, a geologist and
+ * the collector class give 1 + 0.15 + 0.1 + 0.25 on metal.
+ * @param {object} [options] The bonuses that apply
+ * @param {number} [options.plasmaTech] The Plasma Technology level
+ * @param {boolean} [options.geologist] Whether the geologist officer is hired
+ * @param {boolean} [options.collectorClass] Whether the player plays collector
+ * @param {object} [options.items] Booster items in place, as fractions per
+ *   resource — a 30% metal booster is `{ metal: 0.3 }`
+ * @returns {import('../types.js').Resources} One multiplier per resource
+ */
+function getProductionBonus(options = {}) {
+  const {
+    plasmaTech = 0,
+    geologist = false,
+    collectorClass = false,
+    items = {},
+  } = options;
+
+  if (!Number.isInteger(plasmaTech) || plasmaTech < 0) {
+    throw new Error(`plasmaTech must be an integer >= 0, received ${plasmaTech}`);
+  }
+
+  const flat = (geologist ? GEOLOGIST_BONUS : 0) + (collectorClass ? COLLECTOR_BONUS : 0);
+
+  return Object.fromEntries(RESOURCES.map((resource) => {
+    /* eslint-disable security/detect-object-injection -- resource comes from RESOURCES */
+    const item = clampRatio(items[resource] ?? 0, `items.${resource}`);
+
+    return [resource, 1 + PLASMA_BONUS[resource] * plasmaTech + flat + item];
+    /* eslint-enable security/detect-object-injection */
+  }));
+}
+
+/**
+ *
+ * Return the hourly production of a whole planet, bonuses included
+ *
+ * Mine levels, planet position and temperature give the raw mine output; the
+ * plasma, officer, class and item bonuses are then applied, and the flat planet
+ * income is added on top.
+ * @param {object} planet The planet description
+ * @param {number} planet.metalMine The metal mine level
+ * @param {number} planet.crystalMine The crystal mine level
+ * @param {number} planet.deutSynth The deuterium synthesizer level
+ * @param {number} planet.position The planet position, 1 to 3 produce more crystal
+ * @param {number} planet.temperature The planet average temperature
+ * @param {number} [planet.universeSpeed] The universe economy speed
+ * @param {number} [planet.energyEfficiency] The share of the required energy that
+ *   is actually available, between 0 and 1 — mines run at that rate when the
+ *   planet is in an energy deficit
+ * @param {object} [bonuses] Passed straight to `getProductionBonus`
+ * @returns {import('../types.js').Resources & {energyConsumption: number, bonus: import('../types.js').Resources}}
+ *   The hourly production, what it costs in energy, and the multipliers used
+ */
+function getPlanetProduction(planet, bonuses = {}) {
+  const {
+    metalMine,
+    crystalMine,
+    deutSynth,
+    position,
+    temperature,
+    universeSpeed = 1,
+    energyEfficiency = 1,
+  } = planet;
+
+  clampRatio(energyEfficiency, 'energyEfficiency');
+
+  for (const [name, level] of Object.entries({ metalMine, crystalMine, deutSynth })) {
+    if (!Number.isInteger(level) || level < 0) {
+      throw new Error(`${name} must be an integer >= 0, received ${level}`);
+    }
+  }
+
+  // A mine that is not built yet neither produces nor consumes anything, and
+  // has no level 0 cost to speak of.
+  const idle = { production: 0, energyConsumption: 0 };
+  const mines = {
+    metal: metalMine > 0 ? getMetalMine(BUILDINGS[1], metalMine, universeSpeed) : idle,
+    crystal: crystalMine > 0
+      ? getCrystalMine(BUILDINGS[2], crystalMine, position, universeSpeed)
+      : idle,
+    deuterium: deutSynth > 0
+      ? getDeutSynth(BUILDINGS[3], deutSynth, temperature, universeSpeed)
+      : idle,
+  };
+
+  const bonus = getProductionBonus(bonuses);
+
+  const production = Object.fromEntries(RESOURCES.map((resource) => {
+    /* eslint-disable security/detect-object-injection -- resource comes from RESOURCES */
+    const mined = mines[resource].production * bonus[resource] * energyEfficiency;
+
+    return [resource, Math.floor(mined) + BASE_INCOME[resource] * universeSpeed];
+    /* eslint-enable security/detect-object-injection */
+  }));
+
+  return {
+    ...production,
+    energyConsumption: RESOURCES
+      // eslint-disable-next-line security/detect-object-injection
+      .reduce((total, resource) => total + mines[resource].energyConsumption, 0),
+    bonus,
+  };
+}
+
+export {
+  getProductionBonus,
+  PLASMA_BONUS,
+  GEOLOGIST_BONUS,
+  COLLECTOR_BONUS,
+  BASE_INCOME,
+};
+export default getPlanetProduction;

package/src/buildings/solar-plant.js

@@ -1,33 +1,25 @@
+import buildingInfo from './info.js';
+
 function getEnergyProduction(baseProduction, targetLevel) {
   const levelFactor = 1.1 ** targetLevel;
-  return Math.floor(baseProduction * targetLevel * levelFactor);
-}
 
-function getMetalCost(baseMetalCost, targetLevel) {
-  const level = targetLevel - 1;
-  return Math.floor(baseMetalCost * 1.5 ** level);
-}
-
-function getCrystalCost(baseCrystalCost, targetLevel) {
-  const level = targetLevel - 1;
-  return Math.floor(baseCrystalCost * 1.5 ** level);
+  return Math.floor(baseProduction * targetLevel * levelFactor);
 }
 
 /**
  *
- * Return information about the solar plant given a specific level
- * @param {object} solarPlant The solarPlant base information
- * @param {number} targetLevel
- * @returns {Object} informations about the solar plant at this specific level
+ * Return information about the solar plant at a given level
+ * @param {import('../types.js').BuildingEntry} solarPlant The solar plant entry, `Buildings[4]`
+ * @param {number} targetLevel The level to reach, >= 1
+ * @returns {import('../types.js').BuildingInfo} Cost of the plant, and the energy it produces
  */
 function getSolarPlant(solarPlant, targetLevel) {
-  return {
-    crystal: getCrystalCost(solarPlant.crystal, targetLevel),
-    energy: 0,
-    deuterium: 0,
-    metal: getMetalCost(solarPlant.metal, targetLevel),
-    production: getEnergyProduction(solarPlant.production, targetLevel),
-  };
+  return buildingInfo(
+    solarPlant,
+    targetLevel,
+    1,
+    (base) => getEnergyProduction(base.production, targetLevel),
+  );
 }
 
 export default getSolarPlant;

package/src/buildings/storage.js

@@ -0,0 +1,59 @@
+import getCost, { assertLevel } from '../cost.js';
+
+/**
+ *
+ * Return the capacity of a storage building at a given level
+ *
+ * Level 0 is the free 10.000 units every planet starts with.
+ * @param {number} level The storage level, >= 0
+ * @returns {number} The protected capacity, in resource units
+ */
+function getStorageCapacity(level) {
+  if (!Number.isInteger(level) || level < 0) {
+    throw new Error(`level must be an integer >= 0, received ${level}`);
+  }
+
+  return 5000 * Math.floor(2.5 * Math.exp((20 * level) / 33));
+}
+
+/**
+ *
+ * Return the cost and the capacity of a storage building at a given level
+ * @param {import('../types.js').BuildingEntry} storage A storage entry of models/buildings.js (22, 23 or 24)
+ * @param {number} targetLevel The level to reach, >= 1
+ * @returns {import('../types.js').Cost & {capacity: number}} The cost of that level plus the capacity
+ */
+function getStorage(storage, targetLevel) {
+  assertLevel(targetLevel);
+
+  if (!storage || !storage.storage) {
+    throw new Error('storage must be a storage building entry (Buildings 22, 23 or 24)');
+  }
+
+  return {
+    ...getCost(storage, targetLevel),
+    capacity: getStorageCapacity(targetLevel),
+  };
+}
+
+/**
+ *
+ * Return the lowest storage level able to protect a given amount of resources
+ * @param {number} amount The amount of resources to protect
+ * @returns {number} The required storage level
+ */
+function getStorageLevelFor(amount) {
+  if (!Number.isFinite(amount) || amount < 0) {
+    throw new Error(`amount must be a positive number, received ${amount}`);
+  }
+
+  let level = 0;
+  while (getStorageCapacity(level) < amount) {
+    level += 1;
+  }
+
+  return level;
+}
+
+export { getStorageCapacity, getStorageLevelFor };
+export default getStorage;

package/src/cost.js

@@ -0,0 +1,70 @@
+function assertLevel(targetLevel) {
+  if (!Number.isInteger(targetLevel) || targetLevel < 1) {
+    throw new Error(`targetLevel must be an integer >= 1, received ${targetLevel}`);
+  }
+}
+
+/**
+ * Guard against the pre-4.0 habit of passing `Buildings[id].base` around.
+ * Every calculator now needs the whole entry, because the cost `factor` lives
+ * on it and not on its `base`.
+ */
+function assertEntry(entry, targetLevel) {
+  assertLevel(targetLevel);
+
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('expected a Buildings or Research entry, received nothing');
+  }
+
+  if (!entry.base || !entry.factor) {
+    const looksLikeABase = 'metal' in entry && 'crystal' in entry;
+
+    throw new Error(
+      looksLikeABase
+        ? 'expected a Buildings or Research entry, received its `base`: pass Buildings[id], not Buildings[id].base'
+        : 'expected a Buildings or Research entry with a `base` and a `factor`',
+    );
+  }
+}
+
+function levelCost(baseCost, factor, level, roundTo) {
+  const cost = baseCost * factor ** (level - 1);
+
+  if (roundTo) {
+    return Math.ceil(cost / roundTo) * roundTo;
+  }
+
+  return Math.floor(cost);
+}
+
+/**
+ *
+ * Return the cost of a building or a technology at a given level
+ *
+ * Works for anything carrying a `base` and a `factor`, so both
+ * `models/buildings.js` and `models/research.js` entries are accepted.
+ * Use the dedicated `getMetalMine`/`getCrystalMine`/... helpers when you also
+ * need the production or the consumption of a mine or a plant.
+ *
+ * @param {import('./types.js').BuildingEntry|import('./types.js').ResearchEntry} entry A Buildings or
+ *   Research entry (not its `base`)
+ * @param {number} targetLevel The level to reach, >= 1
+ * @returns {import('./types.js').Cost} The resources, and the energy, paid to reach that level
+ */
+function getCost(entry, targetLevel) {
+  assertEntry(entry, targetLevel);
+
+  const { base, factor, roundTo } = entry;
+  // Only the space dock scales its energy cost on a factor of its own.
+  const energyFactor = entry.energyFactor ?? factor;
+
+  return {
+    metal: levelCost(base.metal, factor, targetLevel, roundTo),
+    crystal: levelCost(base.crystal, factor, targetLevel, roundTo),
+    deuterium: levelCost(base.deuterium, factor, targetLevel, roundTo),
+    energyCost: levelCost(base.energyCost, energyFactor, targetLevel, roundTo),
+  };
+}
+
+export { assertLevel, assertEntry };
+export default getCost;

package/src/fleets/combat.js

@@ -0,0 +1,291 @@
+import DESTROYABLE, { ATTRIBUTES } from '../models/destroyable.js';
+import getDebris from './getDebris.js';
+
+const ROUNDS = 6;
+
+/**
+ * A unit with a rapid fire of 1250 legitimately chains hundreds of shots, but
+ * the chain is unbounded in principle, so cap it rather than risk a hang.
+ */
+const MAX_SHOTS = 10000;
+
+/** A shot weaker than this share of the target shield simply bounces off. */
+const BOUNCE_RATIO = 0.01;
+
+/** Below that share of its hull, a unit may explode at the end of the round. */
+const EXPLOSION_THRESHOLD = 0.7;
+
+/** Rapid-fire tables point at library ids, so we need the way back. */
+const LIBRARY_ID = new Map(
+  Object.entries(DESTROYABLE).map(([id, entry]) => [entry, Number(id)]),
+);
+
+/** Callers routinely spread a model entry, which loses object identity. */
+const LIBRARY_ID_BY_OGAME_ID = new Map(
+  Object.entries(DESTROYABLE).map(([id, entry]) => [entry.ogameId, Number(id)]),
+);
+
+function libraryIdOf(ship) {
+  const id = LIBRARY_ID.get(ship) ?? LIBRARY_ID_BY_OGAME_ID.get(ship.ogameId);
+
+  if (id === undefined) {
+    // Without an id the rapid-fire tables, which point at ids, cannot resolve.
+    throw new Error('every ship must come from models/destroyable.js, or at least carry its ogameId');
+  }
+
+  return id;
+}
+
+/**
+ * A tiny deterministic PRNG (mulberry32), so a battle can be replayed.
+ */
+function createRandom(seed) {
+  let state = seed >>> 0;
+
+  return () => {
+    state += 0x6d2b79f5;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Two entries for the same ship would otherwise be counted twice. */
+function mergeFleet(fleet, side) {
+  if (!Array.isArray(fleet) || fleet.length === 0) {
+    throw new Error(`${side} fleet must be a non empty array of { ship, count }`);
+  }
+
+  const merged = new Map();
+
+  for (const { ship, count } of fleet) {
+    if (!ship || !Array.isArray(ship.rapidFire)) {
+      throw new Error(`${side} fleet must hold entries of models/destroyable.js`);
+    }
+
+    if (!Number.isInteger(count) || count < 0) {
+      throw new Error(`${side} fleet counts must be integers >= 0, received ${count}`);
+    }
+
+    merged.set(ship, (merged.get(ship) ?? 0) + count);
+  }
+
+  return [...merged].map(([ship, count]) => ({ ship, count }));
+}
+
+/**
+ * Turn a fleet into individual units with live hull and shield values. Hull
+ * points are a tenth of the metal plus crystal cost.
+ */
+function deploy(fleet, techs) {
+  const { weapons = 0, shielding = 0, armour = 0 } = techs;
+  const units = [];
+
+  for (const { ship, count } of fleet) {
+    const maxHull = (ship.structure / 10) * (1 + 0.1 * armour);
+    const maxShield = ship.shield * (1 + 0.1 * shielding);
+    const attack = ship.attack * (1 + 0.1 * weapons);
+    const libraryId = libraryIdOf(ship);
+
+    for (let i = 0; i < count; i += 1) {
+      units.push({
+        ship, libraryId, maxHull, hull: maxHull, maxShield, shield: maxShield, attack,
+      });
+    }
+  }
+
+  return units;
+}
+
+function rapidFireAgainst(unit, target) {
+  return unit.ship.rapidFire.find((entry) => entry.target === target.libraryId)?.fire ?? 1;
+}
+
+/**
+ * One unit fires at a random enemy, then keeps firing while its rapid-fire
+ * bonus rolls in its favour.
+ */
+function fire(unit, enemies, random) {
+  for (let shots = 0; shots < MAX_SHOTS; shots += 1) {
+    if (enemies.length === 0) {
+      return;
+    }
+
+    const target = enemies[Math.floor(random() * enemies.length)];
+    const damage = unit.attack;
+
+    // A shot too weak to dent the shield bounces off without doing anything.
+    if (damage >= target.shield * BOUNCE_RATIO) {
+      if (damage <= target.shield) {
+        target.shield -= damage;
+      } else {
+        target.hull -= damage - target.shield;
+        target.shield = 0;
+      }
+    }
+
+    const rapid = rapidFireAgainst(unit, target);
+
+    // With a rapid fire of N, the unit shoots again with a (N - 1) / N chance.
+    if (rapid <= 1 || random() >= (rapid - 1) / rapid) {
+      return;
+    }
+  }
+}
+
+/**
+ * Destroyed units are removed, damaged ones may explode, survivors get their
+ * shield back for the next round.
+ */
+function endRound(units, random) {
+  const survivors = [];
+
+  for (const unit of units) {
+    if (unit.hull <= 0) {
+      continue;
+    }
+
+    const integrity = unit.hull / unit.maxHull;
+
+    if (integrity < EXPLOSION_THRESHOLD && random() < 1 - integrity) {
+      continue;
+    }
+
+    unit.shield = unit.maxShield;
+    survivors.push(unit);
+  }
+
+  return survivors;
+}
+
+function summarise(units, initial) {
+  const remaining = new Map();
+
+  for (const unit of units) {
+    remaining.set(unit.ship, (remaining.get(unit.ship) ?? 0) + 1);
+  }
+
+  const survivors = [];
+  const losses = [];
+
+  for (const { ship, count } of initial) {
+    const left = remaining.get(ship) ?? 0;
+
+    if (left > 0) {
+      survivors.push({ ship, count: left });
+    }
+
+    if (count - left > 0) {
+      losses.push({ ship, count: count - left });
+    }
+  }
+
+  return { survivors, losses };
+}
+
+function debrisOf(losses, options) {
+  const { debrisFactor, deuteriumDebrisFactor, defenseDebris } = options;
+
+  return losses
+    // On most universes only ships leave debris behind.
+    .filter(({ ship }) => defenseDebris || ship.category === ATTRIBUTES.CATEGORIES.SHIPS)
+    .map(({ ship, count }) => getDebris(ship, count, debrisFactor, deuteriumDebrisFactor))
+    .reduce((total, debris) => ({
+      metal: total.metal + debris.metal,
+      crystal: total.crystal + debris.crystal,
+      deuterium: total.deuterium + debris.deuterium,
+    }), { metal: 0, crystal: 0, deuterium: 0 });
+}
+
+/**
+ *
+ * Simulate a battle between two fleets
+ *
+ * Follows the game rules: up to six rounds, every unit fires once per round at a
+ * random enemy, rapid fire grants extra shots, shots below 1% of the target
+ * shield bounce off, shields come back every round, and a unit under 70% hull
+ * may explode at the end of the round.
+ *
+ * A battle is random, so one run is one possible outcome. The `seed` makes a run
+ * reproducible; average several seeds to get a feel for the likely result.
+ * @param {object} attacker The attacking side
+ * @param {import('../types.js').FleetEntry[]} attacker.fleet Its ships
+ * @param {import('../types.js').CombatTechs} [attacker.techs] Its combat technology levels
+ * @param {object} defender The defending side, same shape, defenses included
+ * @param {object} [options] Simulation options
+ * @param {number} [options.seed] The PRNG seed, for a reproducible battle
+ * @param {number} [options.debrisFactor] The universe debris factor
+ * @param {number} [options.deuteriumDebrisFactor] The universe deuterium debris factor
+ * @param {boolean} [options.defenseDebris] Whether destroyed defenses leave debris
+ * @returns {{
+ *   winner: 'attacker'|'defender'|'draw', rounds: number, seed: number,
+ *   attacker: {survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[]},
+ *   defender: {survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[]},
+ *   debris: import('../types.js').Resources,
+ * }} Who won, how long it took, what is left on each side, and the debris field
+ */
+function simulateCombat(attacker, defender, options = {}) {
+  const {
+    seed = Date.now(),
+    debrisFactor = 0.3,
+    deuteriumDebrisFactor = 0,
+    defenseDebris = false,
+  } = options;
+
+  const random = createRandom(seed);
+  const attackerFleet = mergeFleet(attacker.fleet, 'attacker');
+  const defenderFleet = mergeFleet(defender.fleet, 'defender');
+
+  let attackers = deploy(attackerFleet, attacker.techs ?? {});
+  let defenders = deploy(defenderFleet, defender.techs ?? {});
+
+  let rounds = 0;
+
+  while (rounds < ROUNDS && attackers.length > 0 && defenders.length > 0) {
+    rounds += 1;
+
+    // Both sides shoot with the units they started the round with.
+    const shootingAttackers = [...attackers];
+    const shootingDefenders = [...defenders];
+
+    for (const unit of shootingAttackers) {
+      fire(unit, defenders, random);
+    }
+
+    for (const unit of shootingDefenders) {
+      fire(unit, attackers, random);
+    }
+
+    attackers = endRound(attackers, random);
+    defenders = endRound(defenders, random);
+  }
+
+  const attackerResult = summarise(attackers, attackerFleet);
+  const defenderResult = summarise(defenders, defenderFleet);
+
+  let winner = 'draw';
+
+  if (attackers.length > 0 && defenders.length === 0) {
+    winner = 'attacker';
+  } else if (defenders.length > 0 && attackers.length === 0) {
+    winner = 'defender';
+  }
+
+  return {
+    winner,
+    rounds,
+    seed,
+    attacker: attackerResult,
+    defender: defenderResult,
+    debris: debrisOf([...attackerResult.losses, ...defenderResult.losses], {
+      debrisFactor,
+      deuteriumDebrisFactor,
+      defenseDebris,
+    }),
+  };
+}
+
+export { createRandom, ROUNDS };
+export default simulateCombat;

package/src/fleets/distance.js

@@ -0,0 +1,39 @@
+function assertCoordinates(coordinates, name) {
+  const { galaxy, system, position } = coordinates ?? {};
+
+  if (![galaxy, system, position].every((value) => Number.isInteger(value) && value > 0)) {
+    throw new Error(`${name} must be a { galaxy, system, position } of positive integers`);
+  }
+}
+
+/**
+ *
+ * Return the distance between two coordinates, in OGame distance units
+ *
+ * The scale is not linear: crossing a galaxy costs far more than crossing a
+ * system, which costs far more than moving inside one.
+ * @param {import('../types.js').Coordinates} origin Where the fleet leaves from
+ * @param {import('../types.js').Coordinates} target Where it goes
+ * @returns {number} The distance
+ */
+function getDistance(origin, target) {
+  assertCoordinates(origin, 'origin');
+  assertCoordinates(target, 'target');
+
+  if (origin.galaxy !== target.galaxy) {
+    return 20000 * Math.abs(origin.galaxy - target.galaxy);
+  }
+
+  if (origin.system !== target.system) {
+    return 2700 + 95 * Math.abs(origin.system - target.system);
+  }
+
+  if (origin.position !== target.position) {
+    return 1000 + 5 * Math.abs(origin.position - target.position);
+  }
+
+  // Same planet: a moon to planet hop, or a planet to its own debris field.
+  return 5;
+}
+
+export default getDistance;