ogamejs 2.1.6 → 4.0.0

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;

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

@@ -0,0 +1,21 @@
+/**
+ *
+ * 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, deuteriumFactor = 0) {
+  const { cost } = ship;
+  const deuteriumCost = cost.deuterium ?? cost.deut ?? 0;
+
+  return {
+    metal: (cost.metal ?? 0) * factor * number,
+    crystal: (cost.crystal ?? 0) * factor * number,
+    deuterium: deuteriumCost * deuteriumFactor * number,
+  };
+}
+
+export default getDebris;

package/src/fleets/index.js

@@ -0,0 +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;