ogamejs 4.1.0 → 4.3.0

package/README.md

@@ -44,8 +44,8 @@ Ogame.Fleets.getTrip(
   { galaxy: 3, system: 42, position: 6 },
   { drives: { combustion: 16, hyperspace: 12 } },
 );
-// → { distance: 40000, fleetSpeed: 19500, duration: 1595, fuel: 258287,
-//     cargo: 6650000, cargoAfterFuel: 6391713 }
+// → { distance: 40000, fleetSpeed: 19500, duration: 15862, fuel: 216148,
+//     cargo: 6650000, cargoAfterFuel: 6433852 }
 
 // And how it would go
 Ogame.Fleets.simulateCombat(
@@ -259,19 +259,29 @@ Ogame.Research.getResearchTime(Ogame.models.Research[122], 10, 12, 2); // Plasma
 
 ### `Ogame.Fleets`
 
-#### `getDistance(origin, target)`
+#### `getDistance(origin, target, universe = {})`
 
 Coordinates are `{ galaxy, system, position }`. The scale is not linear.
 
 ```javascript
 Ogame.Fleets.getDistance({ galaxy: 1, system: 1, position: 1 }, { galaxy: 4, system: 1, position: 1 });
 // → 60000
+
+// Most universes are donuts: the last galaxy touches the first
+Ogame.Fleets.getDistance(
+  { galaxy: 1, system: 1, position: 1 },
+  { galaxy: 6, system: 1, position: 1 },
+  { galaxies: 6, systems: 499, donutGalaxy: true, donutSystem: true },
+);
+// → 20000
 ```
 
-#### `getShipSpeed(ship, drives = {})` / `getFleetSpeed(fleet, drives = {})` / `getActiveDrive(ship, drives = {})`
+#### `getShipSpeed(ship, drives = {}, bonus = 0)` / `getFleetSpeed(fleet, drives = {})` / `getActiveDrive(ship, drives = {}, bonus = 0)`
 
 `drives` holds the `{ combustion, impulse, hyperspace }` levels. Each level adds 10%, 20% or 30% of the ship's base speed, and only the drive the ship actually flies on counts.
 
+`bonus` adds to that, as a share of the base speed: `1` for the class bonus that doubles a ship's speed (Collector transporters, General warships), `0.05` for a 5% life form bonus. In a fleet, each entry carries its own `speedBonus`.
+
 A few ships switch to a better drive once the matching technology is high enough. `getActiveDrive` tells you which one is in use — and since a switch also changes the fuel burn, it reports that too.
 
 ```javascript
@@ -287,11 +297,15 @@ Ogame.Fleets.getFleetSpeed([{ ship: Ogame.models.Destroyable[1], count: 100 }],
 
 #### `getFlightTime(distance, fleetSpeed, speedPercent = 100, universeFleetSpeed = 1)`
 
-`(10 + 35000 / speedPercent × √(distance × 10 / fleetSpeed)) / universeFleetSpeed`, in seconds.
+`(10 + 350000 / speedPercent × √(distance × 10 / fleetSpeed)) / universeFleetSpeed`, in seconds — at 100%, the familiar `10 + 3500 × √(distance × 10 / fleetSpeed)`.
 
-#### `getFuelConsumption(fleet, distance, speedPercent = 100, drives = {})`
+#### `getFuelConsumption(fleet, distance, speedPercent = 100, drives = {}, options = {})`
 
-`1 + round(Σ(consumption × count) × distance / 35000 × (speedPercent / 100 + 1)²)`, in deuterium.
+Each ship type is billed on its own, at least one unit, then the bills add up:
+`Σ max(1, round(consumption × count × distance / 35000 × (shipSpeedValue / 10 + 1)²))`, in deuterium.
+`shipSpeedValue` is `speedPercent / 10` for the slowest ship and `speedPercent / 10 × √(fleetSpeed / shipSpeed)` for the faster ones it holds back, which burn less than at full throttle.
+
+`consumption` is the ship's own after the universe factor (`options.deuteriumFactor`, `globalDeuteriumSaveFactor` in the API) and the entry's `fuelReduction` (General, life forms, capped at `MAX_FUEL_REDUCTION`, 90%), each rounded down and never below one unit.
 
 #### `getTrip(fleet, origin, target, options = {})`
 
@@ -304,10 +318,12 @@ Ogame.Fleets.getTrip(
   { galaxy: 3, system: 42, position: 6 },
   { drives: { combustion: 16, hyperspace: 12 }, speedPercent: 100, roundTrip: false },
 );
-// → { distance: 40000, fleetSpeed: 19500, duration: 1595, fuel: 258287,
-//     cargo: 6650000, cargoAfterFuel: 6391713 }
+// → { distance: 40000, fleetSpeed: 19500, duration: 15862, fuel: 216148,
+//     cargo: 6650000, cargoAfterFuel: 6433852 }
 ```
 
+`options` also takes `universeFleetSpeed`, `deuteriumFactor` and `universe` (the donut shape passed to `getDistance`).
+
 `cargoAfterFuel` is what is left once the deuterium is loaded — the number that decides whether a raid is worth flying.
 
 #### `getDebris(ship, number, factor, deuteriumFactor = 0)`
@@ -321,7 +337,7 @@ Ogame.Fleets.getDebris(Ogame.models.Destroyable[1], 100, 0.3);
 
 #### `simulateCombat(attacker, defender, options = {})`
 
-A full battle: 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's shield bounce off, shields come back every round, and a unit under 70% hull may explode at the end of the round.
+A full battle: 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's shield bounce off, shields come back every round, and a unit hit while under 70% hull may explode. Afterwards, destroyed defenses are rebuilt (70% chance each), the debris field gives the moon chance, and a winning attacker loads what its surviving ships can carry.
 
 ```javascript
 const battle = Ogame.Fleets.simulateCombat(
@@ -333,26 +349,50 @@ const battle = Ogame.Fleets.simulateCombat(
     fleet: [{ ship: Ogame.models.Destroyable[201], count: 200 }],
     techs: { weapons: 10, shielding: 10, armour: 10 },
   },
-  { seed: 42, debrisFactor: 0.3 },
+  {
+    seed: 42,
+    debrisFactor: 0.3,
+    plunder: { resources: { metal: 500000, crystal: 200000, deuterium: 100000 }, hyperspaceLevel: 8 },
+  },
 );
 // → {
 //   winner: 'attacker' | 'defender' | 'draw',
 //   rounds: Number,
 //   seed: Number,
 //   attacker: { survivors: [{ ship, count }], losses: [{ ship, count }] },
-//   defender: { survivors: [...], losses: [...] },
+//   defender: { survivors: [...], losses: [...], rebuilt: [...] },
 //   debris: { metal, crystal, deuterium },
+//   moonChance: Number, // in %
+//   plunder: { metal, crystal, deuterium },
 // }
 ```
 
-A battle is **random**, so one run is one possible outcome. Pass a `seed` to replay the exact same fight; average several seeds to get a feel for the likely result:
+| Option | Default | |
+| --- | --- | --- |
+| `seed` | `Date.now()` | replays the exact same fight |
+| `debrisFactor` | `0.3` | share of the destroyed ships' metal and crystal left as debris |
+| `deuteriumDebrisFactor` | `0` | same for deuterium |
+| `defenseDebrisFactor` | `0` (`debrisFactor` with `defenseDebris: true`) | same for destroyed defenses |
+| `repairFactor` | `0.7` | chance for each destroyed defense to be rebuilt |
+| `plunder` | none | `{ resources, ratio = 0.5, hyperspaceLevel, hyperspaceMultiplier, bonus }`; the loot is spread like the resources on the planet |
+
+#### `simulateCombats(attacker, defender, options = {})` / `getCombatStatistics(results)`
+
+A battle is **random**, so one run is one possible outcome. `simulateCombats` runs the same battle `runs` times (100 by default, seeds `seed`, `seed + 1`…) and averages them; `getCombatStatistics` does the averaging on results you simulated yourself, for instance in batches from a Web Worker.
 
 ```javascript
-const runs = Array.from({ length: 100 }, (_, seed) => simulateCombat(a, d, { seed }));
-const winRate = runs.filter((run) => run.winner === 'attacker').length / runs.length;
+Ogame.Fleets.simulateCombats(attacker, defender, { runs: 100, seed: 1, debrisFactor: 0.3 });
+// → {
+//   runs: 100,
+//   outcomes: { attacker: 0.92, defender: 0, draw: 0.08 }, // shares, from 0 to 1
+//   rounds: 2.4,
+//   attacker: { survivors, losses, lostResources },
+//   defender: { survivors, losses, rebuilt, lostResources },
+//   debris, moonChance, plunder,
+// }
 ```
 
-Destroyed defenses are left out of the debris field unless you pass `defenseDebris: true`. Defense repair after a battle is not modelled.
+Counts are averages, so not whole numbers. `lostResources` is what the units lost for good cost: rebuilt defenses do not count.
 
 #### `getMoonbreakChance(moonSize, fleets)` / `getMoonbreakLosses(moonSize, fleets)` / `getMoonbreakWaves(rip)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ogamejs",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "OGame formulas as a dependency-free ESM library: building and research costs, production, build times, fleet debris and marketplace rates.",
   "type": "module",
   "main": "src/index.js",

package/src/fleets/combat.js

@@ -1,5 +1,7 @@
 import DESTROYABLE, { ATTRIBUTES } from '../models/destroyable.js';
 import getDebris from './getDebris.js';
+import { getCargoCapacity } from './expedition.js';
+import { MOON_DEBRIS_THRESHOLD, MAX_MOON_CHANCE } from './moonLock.js';
 
 const ROUNDS = 6;
 
@@ -12,9 +14,18 @@ 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. */
+/** Below that share of its hull, a unit hit by a shot may explode on the spot. */
 const EXPLOSION_THRESHOLD = 0.7;
 
+/** The share of destroyed defenses that come back after a battle, on most universes. */
+const DEFAULT_REPAIR_FACTOR = 0.7;
+
+/** The share of the defender's resources a winning attacker can carry away. */
+const DEFAULT_PLUNDER_RATIO = 0.5;
+
+/** Every 100 000 units of debris add 1% to the moon chance. */
+const MOON_DEBRIS_PER_PERCENT = MOON_DEBRIS_THRESHOLD / MAX_MOON_CHANCE;
+
 /** 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)]),
@@ -106,6 +117,10 @@ function rapidFireAgainst(unit, target) {
 /**
  * One unit fires at a random enemy, then keeps firing while its rapid-fire
  * bonus rolls in its favour.
+ *
+ * Every shot that gets through may blow up a target left under 70% of its
+ * hull, so a unit hit several times in a round gets several rolls. A wrecked
+ * unit stays a target until the end of the round, and shots on it are wasted.
  */
 function fire(unit, enemies, random) {
   for (let shots = 0; shots < MAX_SHOTS; shots += 1) {
@@ -117,13 +132,19 @@ function fire(unit, enemies, random) {
     const damage = unit.attack;
 
     // A shot too weak to dent the shield bounces off without doing anything.
-    if (damage >= target.shield * BOUNCE_RATIO) {
+    if (target.hull > 0 && damage >= target.shield * BOUNCE_RATIO) {
       if (damage <= target.shield) {
         target.shield -= damage;
       } else {
         target.hull -= damage - target.shield;
         target.shield = 0;
       }
+
+      const integrity = target.hull / target.maxHull;
+
+      if (target.hull > 0 && integrity < EXPLOSION_THRESHOLD && random() < 1 - integrity) {
+        target.hull = 0;
+      }
     }
 
     const rapid = rapidFireAgainst(unit, target);
@@ -135,11 +156,8 @@ function fire(unit, enemies, random) {
   }
 }
 
-/**
- * Destroyed units are removed, damaged ones may explode, survivors get their
- * shield back for the next round.
- */
-function endRound(units, random) {
+/** Destroyed units are removed, survivors get their shield back for the next round. */
+function endRound(units) {
   const survivors = [];
 
   for (const unit of units) {
@@ -147,12 +165,6 @@ function endRound(units, random) {
       continue;
     }
 
-    const integrity = unit.hull / unit.maxHull;
-
-    if (integrity < EXPLOSION_THRESHOLD && random() < 1 - integrity) {
-      continue;
-    }
-
     unit.shield = unit.maxShield;
     survivors.push(unit);
   }
@@ -186,12 +198,13 @@ function summarise(units, initial) {
 }
 
 function debrisOf(losses, options) {
-  const { debrisFactor, deuteriumDebrisFactor, defenseDebris } = options;
+  const { debrisFactor, deuteriumDebrisFactor, defenseDebrisFactor } = 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))
+    // On most universes only ships leave debris behind, defenses have their own factor.
+    .map(({ ship, count }) => (ship.category === ATTRIBUTES.CATEGORIES.SHIPS
+      ? getDebris(ship, count, debrisFactor, deuteriumDebrisFactor)
+      : getDebris(ship, count, defenseDebrisFactor, deuteriumDebrisFactor > 0 ? defenseDebrisFactor : 0)))
     .reduce((total, debris) => ({
       metal: total.metal + debris.metal,
       crystal: total.crystal + debris.crystal,
@@ -199,17 +212,101 @@ function debrisOf(losses, options) {
     }), { metal: 0, crystal: 0, deuterium: 0 });
 }
 
+/** Each destroyed defense is rebuilt, or not, on its own roll. */
+function rebuild(losses, repairFactor, random) {
+  const rebuilt = [];
+
+  for (const { ship, count } of losses) {
+    if (ship.category !== ATTRIBUTES.CATEGORIES.DEFENSES) {
+      continue;
+    }
+
+    let back = 0;
+
+    for (let i = 0; i < count; i += 1) {
+      if (random() < repairFactor) {
+        back += 1;
+      }
+    }
+
+    if (back > 0) {
+      rebuilt.push({ ship, count: back });
+    }
+  }
+
+  return rebuilt;
+}
+
+/**
+ * The surviving ships carry away up to `ratio` of the defender's resources,
+ * spread in proportion to what lies on the planet.
+ */
+function plunderOf(survivors, plunder) {
+  const {
+    resources, ratio = DEFAULT_PLUNDER_RATIO, hyperspaceLevel, hyperspaceMultiplier, bonus,
+  } = plunder;
+
+  const lootable = {
+    metal: (resources.metal ?? 0) * ratio,
+    crystal: (resources.crystal ?? 0) * ratio,
+    deuterium: (resources.deuterium ?? 0) * ratio,
+  };
+  const total = lootable.metal + lootable.crystal + lootable.deuterium;
+  const capacity = survivors
+    .map(({ ship, count }) => getCargoCapacity(ship, { hyperspaceLevel, hyperspaceMultiplier, bonus }) * count)
+    .reduce((sum, value) => sum + value, 0);
+
+  if (total === 0 || capacity >= total) {
+    return lootable;
+  }
+
+  const share = capacity / total;
+
+  return {
+    metal: Math.floor(lootable.metal * share),
+    crystal: Math.floor(lootable.crystal * share),
+    deuterium: Math.floor(lootable.deuterium * share),
+  };
+}
+
+function moonChanceOf(debris) {
+  const total = debris.metal + debris.crystal + debris.deuterium;
+
+  return Math.min(MAX_MOON_CHANCE, Math.floor(total / MOON_DEBRIS_PER_PERCENT));
+}
+
+/**
+ * @typedef {object} CombatResult One simulated battle
+ * @property {'attacker'|'defender'|'draw'} winner Who won
+ * @property {number} rounds How many rounds it lasted
+ * @property {number} seed The PRNG seed it ran with
+ * @property {{survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[]}} attacker
+ *   What is left of the attacker, and what it lost
+ * @property {{
+ *   survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[],
+ *   rebuilt: import('../types.js').FleetEntry[],
+ * }} defender What is left of the defender, what it lost, and which of its lost defenses come back
+ * @property {import('../types.js').Resources} debris The debris field
+ * @property {number} moonChance The moon chance it gives, in %
+ * @property {import('../types.js').Resources} plunder What the attacker carries away
+ */
+
 /**
  *
  * 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.
+ * shield bounce off, shields come back every round, and a unit hit while under
+ * 70% hull may explode.
+ *
+ * Afterwards, each destroyed defense is rebuilt with a `repairFactor` chance,
+ * the debris field gives the moon chance (1% per 100 000, up to 20%), and a
+ * winning attacker loads what it can of the defender's resources when
+ * `plunder` says what lies on the planet.
  *
  * 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.
+ * reproducible; `getCombatStatistics` averages several of them.
  * @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
@@ -218,13 +315,16 @@ function debrisOf(losses, 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
+ * @param {boolean} [options.defenseDebris] Whether destroyed defenses leave debris, at `debrisFactor`
+ * @param {number} [options.defenseDebrisFactor] The universe defense debris factor, overrides `defenseDebris`
+ * @param {number} [options.repairFactor] The chance for a destroyed defense to be rebuilt, 0.7 by default
+ * @param {object} [options.plunder] What the attacker may carry away if it wins
+ * @param {import('../types.js').Resources} options.plunder.resources The resources on the planet
+ * @param {number} [options.plunder.ratio] The share of them up for grabs, 0.5 by default
+ * @param {number} [options.plunder.hyperspaceLevel] The attacker's Hyperspace Technology level
+ * @param {number} [options.plunder.hyperspaceMultiplier] The % of base cargo per level, 5 by default
+ * @param {number} [options.plunder.bonus] Any other cargo bonus, as a fraction
+ * @returns {CombatResult} Who won, how long it took, what is left on each side, and what the battle left behind
  */
 function simulateCombat(attacker, defender, options = {}) {
   const {
@@ -232,6 +332,9 @@ function simulateCombat(attacker, defender, options = {}) {
     debrisFactor = 0.3,
     deuteriumDebrisFactor = 0,
     defenseDebris = false,
+    defenseDebrisFactor = defenseDebris ? debrisFactor : 0,
+    repairFactor = DEFAULT_REPAIR_FACTOR,
+    plunder,
   } = options;
 
   const random = createRandom(seed);
@@ -258,8 +361,8 @@ function simulateCombat(attacker, defender, options = {}) {
       fire(unit, attackers, random);
     }
 
-    attackers = endRound(attackers, random);
-    defenders = endRound(defenders, random);
+    attackers = endRound(attackers);
+    defenders = endRound(defenders);
   }
 
   const attackerResult = summarise(attackers, attackerFleet);
@@ -273,19 +376,25 @@ function simulateCombat(attacker, defender, options = {}) {
     winner = 'defender';
   }
 
+  const debris = debrisOf([...attackerResult.losses, ...defenderResult.losses], {
+    debrisFactor,
+    deuteriumDebrisFactor,
+    defenseDebrisFactor,
+  });
+
   return {
     winner,
     rounds,
     seed,
     attacker: attackerResult,
-    defender: defenderResult,
-    debris: debrisOf([...attackerResult.losses, ...defenderResult.losses], {
-      debrisFactor,
-      deuteriumDebrisFactor,
-      defenseDebris,
-    }),
+    defender: { ...defenderResult, rebuilt: rebuild(defenderResult.losses, repairFactor, random) },
+    debris,
+    moonChance: moonChanceOf(debris),
+    plunder: plunder && winner === 'attacker'
+      ? plunderOf(attackerResult.survivors, plunder)
+      : { metal: 0, crystal: 0, deuterium: 0 },
   };
 }
 
-export { createRandom, ROUNDS };
+export { createRandom, ROUNDS, DEFAULT_REPAIR_FACTOR, DEFAULT_PLUNDER_RATIO };
 export default simulateCombat;

package/src/fleets/combatStatistics.js

@@ -0,0 +1,189 @@
+import simulateCombat from './combat.js';
+
+/** Enough runs for the averages to settle, without making a big battle wait. */
+const DEFAULT_RUNS = 100;
+
+const NO_RESOURCES = Object.freeze({ metal: 0, crystal: 0, deuterium: 0 });
+
+function addResources(total, resources) {
+  return {
+    metal: total.metal + resources.metal,
+    crystal: total.crystal + resources.crystal,
+    deuterium: total.deuterium + resources.deuterium,
+  };
+}
+
+function scaleResources(resources, factor) {
+  return {
+    metal: resources.metal * factor,
+    crystal: resources.crystal * factor,
+    deuterium: resources.deuterium * factor,
+  };
+}
+
+function costOf(fleet) {
+  return fleet
+    .map(({ ship, count }) => ({
+      metal: (ship.cost.metal ?? 0) * count,
+      crystal: (ship.cost.crystal ?? 0) * count,
+      deuterium: (ship.cost.deuterium ?? ship.cost.deut ?? 0) * count,
+    }))
+    .reduce(addResources, NO_RESOURCES);
+}
+
+/** Two copies of the same model entry are the same ship. */
+function keyOf(ship) {
+  return ship.ogameId ?? ship;
+}
+
+/** Sum the counts of every run, keeping the order ships first appear in. */
+function addFleets(totals, fleet) {
+  for (const { ship, count } of fleet) {
+    const key = keyOf(ship);
+    const entry = totals.get(key);
+
+    if (entry) {
+      entry.count += count;
+    } else {
+      totals.set(key, { ship, count });
+    }
+  }
+}
+
+function averageFleet(totals, runs) {
+  return [...totals.values()].map(({ ship, count }) => ({ ship, count: count / runs }));
+}
+
+/**
+ * Take back what was rebuilt from what was lost, ship by ship.
+ * @param {import('../types.js').FleetEntry[]} losses What was destroyed
+ * @param {import('../types.js').FleetEntry[]} rebuilt What came back
+ * @returns {import('../types.js').FleetEntry[]} What is gone for good
+ */
+function subtractFleet(losses, rebuilt) {
+  return losses
+    .map(({ ship, count }) => ({
+      ship,
+      count: count - (rebuilt.find((entry) => keyOf(entry.ship) === keyOf(ship))?.count ?? 0),
+    }))
+    .filter(({ count }) => count > 0);
+}
+
+/**
+ *
+ * Average a set of simulated battles
+ *
+ * Counts are averages, so they are not whole numbers. `lostResources` is what
+ * the units lost for good would cost to build again: every loss for the
+ * attacker, the defender's losses minus its rebuilt defenses.
+ * @param {import('./combat.js').CombatResult[]} results Battles from `simulateCombat`
+ * @returns {{
+ *   runs: number,
+ *   outcomes: {attacker: number, defender: number, draw: number},
+ *   rounds: number,
+ *   attacker: {
+ *     survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[],
+ *     lostResources: import('../types.js').Resources,
+ *   },
+ *   defender: {
+ *     survivors: import('../types.js').FleetEntry[], losses: import('../types.js').FleetEntry[],
+ *     rebuilt: import('../types.js').FleetEntry[], lostResources: import('../types.js').Resources,
+ *   },
+ *   debris: import('../types.js').Resources,
+ *   moonChance: number,
+ *   plunder: import('../types.js').Resources,
+ * }} The share of battles each side won (from 0 to 1), and the average of everything else
+ */
+function getCombatStatistics(results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    throw new Error('results must be a non empty array of simulateCombat results');
+  }
+
+  const runs = results.length;
+  const outcomes = { attacker: 0, defender: 0, draw: 0 };
+  const fleets = {
+    attackerSurvivors: new Map(),
+    attackerLosses: new Map(),
+    defenderSurvivors: new Map(),
+    defenderLosses: new Map(),
+    defenderRebuilt: new Map(),
+  };
+  let rounds = 0;
+  let moonChance = 0;
+  let debris = NO_RESOURCES;
+  let plunder = NO_RESOURCES;
+  let attackerLost = NO_RESOURCES;
+  let defenderLost = NO_RESOURCES;
+
+  for (const result of results) {
+    outcomes[result.winner] += 1;
+    rounds += result.rounds;
+    moonChance += result.moonChance;
+    debris = addResources(debris, result.debris);
+    plunder = addResources(plunder, result.plunder);
+    attackerLost = addResources(attackerLost, costOf(result.attacker.losses));
+    defenderLost = addResources(
+      defenderLost,
+      costOf(subtractFleet(result.defender.losses, result.defender.rebuilt)),
+    );
+
+    addFleets(fleets.attackerSurvivors, result.attacker.survivors);
+    addFleets(fleets.attackerLosses, result.attacker.losses);
+    addFleets(fleets.defenderSurvivors, result.defender.survivors);
+    addFleets(fleets.defenderLosses, result.defender.losses);
+    addFleets(fleets.defenderRebuilt, result.defender.rebuilt);
+  }
+
+  return {
+    runs,
+    outcomes: {
+      attacker: outcomes.attacker / runs,
+      defender: outcomes.defender / runs,
+      draw: outcomes.draw / runs,
+    },
+    rounds: rounds / runs,
+    attacker: {
+      survivors: averageFleet(fleets.attackerSurvivors, runs),
+      losses: averageFleet(fleets.attackerLosses, runs),
+      lostResources: scaleResources(attackerLost, 1 / runs),
+    },
+    defender: {
+      survivors: averageFleet(fleets.defenderSurvivors, runs),
+      losses: averageFleet(fleets.defenderLosses, runs),
+      rebuilt: averageFleet(fleets.defenderRebuilt, runs),
+      lostResources: scaleResources(defenderLost, 1 / runs),
+    },
+    debris: scaleResources(debris, 1 / runs),
+    moonChance: moonChance / runs,
+    plunder: scaleResources(plunder, 1 / runs),
+  };
+}
+
+/**
+ *
+ * Simulate the same battle many times and average the outcomes
+ *
+ * Run `i` uses the seed `seed + i`, so the whole set is reproducible.
+ * @param {Parameters<typeof simulateCombat>[0]} attacker The attacking side, as for `simulateCombat`
+ * @param {Parameters<typeof simulateCombat>[1]} defender The defending side, as for `simulateCombat`
+ * @param {Parameters<typeof simulateCombat>[2] & {runs?: number}} [options] The `simulateCombat`
+ *   options, plus `runs`, how many battles to simulate (100 by default)
+ * @returns {ReturnType<typeof getCombatStatistics>} The averaged outcome, see `getCombatStatistics`
+ */
+function simulateCombats(attacker, defender, options = {}) {
+  const { runs = DEFAULT_RUNS, seed = Date.now(), ...rest } = options;
+
+  if (!Number.isInteger(runs) || runs < 1) {
+    throw new Error(`runs must be an integer >= 1, received ${runs}`);
+  }
+
+  const results = [];
+
+  for (let i = 0; i < runs; i += 1) {
+    results.push(simulateCombat(attacker, defender, { ...rest, seed: seed + i }));
+  }
+
+  return getCombatStatistics(results);
+}
+
+export { getCombatStatistics, simulateCombats, DEFAULT_RUNS };

package/src/fleets/distance.js

@@ -6,26 +6,49 @@ function assertCoordinates(coordinates, name) {
   }
 }
 
+// In a donut universe the fleet takes the shorter way round.
+function gap(from, to, size, donut) {
+  const direct = Math.abs(from - to);
+
+  if (!donut) {
+    return direct;
+  }
+
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new Error(`a donut universe needs its size, received ${size}`);
+  }
+
+  return Math.min(direct, size - direct);
+}
+
 /**
  *
  * 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.
+ * system, which costs far more than moving inside one. Most universes are
+ * donuts: the last galaxy (or system) touches the first, and the fleet takes the
+ * shorter way round.
  * @param {import('../types.js').Coordinates} origin Where the fleet leaves from
  * @param {import('../types.js').Coordinates} target Where it goes
+ * @param {import('../types.js').UniverseShape} [universe] How the universe wraps,
+ *   flat when left out
  * @returns {number} The distance
  */
-function getDistance(origin, target) {
+function getDistance(origin, target, universe = {}) {
   assertCoordinates(origin, 'origin');
   assertCoordinates(target, 'target');
 
+  const {
+    galaxies, systems, donutGalaxy = false, donutSystem = false,
+  } = universe;
+
   if (origin.galaxy !== target.galaxy) {
-    return 20000 * Math.abs(origin.galaxy - target.galaxy);
+    return 20000 * gap(origin.galaxy, target.galaxy, galaxies, donutGalaxy);
   }
 
   if (origin.system !== target.system) {
-    return 2700 + 95 * Math.abs(origin.system - target.system);
+    return 2700 + 95 * gap(origin.system, target.system, systems, donutSystem);
   }
 
   if (origin.position !== target.position) {