ogamejs 4.0.2 → 4.2.0

package/src/fleets/expedition.js

@@ -0,0 +1,124 @@
+/**
+ * The maximum metal an expedition can find, tiered by the score of the
+ * universe's top player. `below` is an exclusive upper bound; above the last
+ * tier every universe shares `EXPEDITION_TOP_TIER_BASE`.
+ */
+const EXPEDITION_FIND_TIERS = Object.freeze([
+  Object.freeze({ below: 1e4, base: 40000 }),
+  Object.freeze({ below: 1e5, base: 500000 }),
+  Object.freeze({ below: 1e6, base: 1200000 }),
+  Object.freeze({ below: 5e6, base: 1800000 }),
+  Object.freeze({ below: 25e6, base: 2400000 }),
+  Object.freeze({ below: 50e6, base: 3000000 }),
+  Object.freeze({ below: 75e6, base: 3600000 }),
+  Object.freeze({ below: 100e6, base: 4200000 }),
+]);
+const EXPEDITION_TOP_TIER_BASE = 5000000;
+
+/** The Discoverer class bonus on expedition finds, `explorerBonusIncreasedExpeditionOutcome` in serverData. */
+const DEFAULT_EXPLORER_BONUS = 0.5;
+
+/** The share of base cargo each Hyperspace Technology level adds, `cargoHyperspaceTechMultiplier` in serverData. */
+const DEFAULT_HYPERSPACE_MULTIPLIER = 5;
+
+function assertBonus(name, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${name} must be a number >= 0, received ${value}`);
+  }
+}
+
+/**
+ *
+ * Return the expedition find base of a universe, before any multiplier
+ * @param {number} topScore The points of the universe's top player
+ * @return {number} The base, in metal
+ */
+function getExpeditionFindBase(topScore) {
+  if (!Number.isFinite(topScore) || topScore < 0) {
+    throw new Error(`topScore must be a number >= 0, received ${topScore}`);
+  }
+
+  const tier = EXPEDITION_FIND_TIERS.find(({ below }) => topScore < below);
+  return tier ? tier.base : EXPEDITION_TOP_TIER_BASE;
+}
+
+/**
+ *
+ * Return the largest metal find a single expedition can bring back
+ *
+ * `base * classFactor * (pathfinder ? 2 : 1) * (1 + lifeformResourceBonus)`
+ *
+ * - a Discoverer gets `classFactor = (1 + explorerBonus * (1 + lifeformExplorerBonus)) * economySpeed`:
+ *   the lifeform class enhancement amplifies the class bonus itself, and only
+ *   the Discoverer's finds scale with the economy speed;
+ * - any other class gets `classFactor = 1`.
+ *
+ * Crystal and deuterium finds are smaller than metal finds. Every bonus is a
+ * fraction: 0.2 for the 20 % the in-game lifeform bonus page shows.
+ * @param {object} options The universe and the player's bonuses
+ * @param {number} options.topScore The points of the universe's top player
+ * @param {number} options.economySpeed The universe economy speed
+ * @param {boolean} [options.explorer] Whether the player is a Discoverer
+ * @param {boolean} [options.pathfinder] Whether the fleet holds a Pathfinder
+ * @param {number} [options.explorerBonus] The Discoverer class bonus, 0.5 by default
+ * @param {number} [options.lifeformExplorerBonus] The lifeform Discoverer enhancement
+ * @param {number} [options.lifeformResourceBonus] The lifeform expedition resource bonus
+ * @return {number} The maximum find, in metal
+ */
+function getExpeditionMaxFind({
+  topScore,
+  economySpeed,
+  explorer = false,
+  pathfinder = false,
+  explorerBonus = DEFAULT_EXPLORER_BONUS,
+  lifeformExplorerBonus = 0,
+  lifeformResourceBonus = 0,
+}) {
+  if (!(economySpeed > 0)) {
+    throw new Error(`economySpeed must be greater than 0, received ${economySpeed}`);
+  }
+  assertBonus('explorerBonus', explorerBonus);
+  assertBonus('lifeformExplorerBonus', lifeformExplorerBonus);
+  assertBonus('lifeformResourceBonus', lifeformResourceBonus);
+
+  const classFactor = explorer
+    ? (1 + explorerBonus * (1 + lifeformExplorerBonus)) * economySpeed
+    : 1;
+
+  return getExpeditionFindBase(topScore) * classFactor * (pathfinder ? 2 : 1) * (1 + lifeformResourceBonus);
+}
+
+/**
+ *
+ * Return the cargo capacity of one ship, with its bonuses
+ *
+ * `ship.cargo * (1 + hyperspaceLevel * hyperspaceMultiplier / 100 + bonus)`:
+ * every bonus is a share of the base cargo, so they add up.
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {object} [options] The bonuses
+ * @param {number} [options.hyperspaceLevel] The Hyperspace Technology level
+ * @param {number} [options.hyperspaceMultiplier] The % of base cargo per level, 5 by default
+ * @param {number} [options.bonus] Any other bonus as a fraction: class (Collector 0.25 on cargo ships), lifeform…
+ * @return {number} The capacity
+ */
+function getCargoCapacity(ship, {
+  hyperspaceLevel = 0,
+  hyperspaceMultiplier = DEFAULT_HYPERSPACE_MULTIPLIER,
+  bonus = 0,
+} = {}) {
+  if (!Number.isInteger(hyperspaceLevel) || hyperspaceLevel < 0) {
+    throw new Error(`hyperspaceLevel must be an integer >= 0, received ${hyperspaceLevel}`);
+  }
+  assertBonus('hyperspaceMultiplier', hyperspaceMultiplier);
+  assertBonus('bonus', bonus);
+
+  return ship.cargo * (1 + (hyperspaceLevel * hyperspaceMultiplier) / 100 + bonus);
+}
+
+export {
+  getExpeditionFindBase,
+  getExpeditionMaxFind,
+  getCargoCapacity,
+  EXPEDITION_FIND_TIERS,
+  EXPEDITION_TOP_TIER_BASE,
+};

package/src/fleets/index.js

@@ -2,7 +2,25 @@ 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';
+import simulateCombat, { DEFAULT_REPAIR_FACTOR, DEFAULT_PLUNDER_RATIO } from './combat.js';
+import { getCombatStatistics, simulateCombats, DEFAULT_RUNS } from './combatStatistics.js';
+import {
+  getWaveChance,
+  getMoonbreakWaves,
+  getMoonbreakChance,
+  getMoonbreakLosses,
+  MIN_MOON_SIZE,
+  MAX_MOON_SIZE,
+  WAVES_PER_ATTACKER,
+} from './moonbreak.js';
+import {
+  getExpeditionFindBase,
+  getExpeditionMaxFind,
+  getCargoCapacity,
+  EXPEDITION_FIND_TIERS,
+  EXPEDITION_TOP_TIER_BASE,
+} from './expedition.js';
+import { getMoonLockShips, MOON_DEBRIS_THRESHOLD, MAX_MOON_CHANCE } from './moonLock.js';
 
 const Fleets = {
   getDebris,
@@ -14,6 +32,29 @@ const Fleets = {
   getFuelConsumption,
   getTrip,
   simulateCombat,
+  simulateCombats,
+  getCombatStatistics,
+  getWaveChance,
+  getMoonbreakWaves,
+  getMoonbreakChance,
+  getMoonbreakLosses,
+  getExpeditionFindBase,
+  getExpeditionMaxFind,
+  getCargoCapacity,
+  getMoonLockShips,
+};
+
+export {
+  MIN_MOON_SIZE,
+  MAX_MOON_SIZE,
+  WAVES_PER_ATTACKER,
+  EXPEDITION_FIND_TIERS,
+  EXPEDITION_TOP_TIER_BASE,
+  MOON_DEBRIS_THRESHOLD,
+  MAX_MOON_CHANCE,
+  DEFAULT_REPAIR_FACTOR,
+  DEFAULT_PLUNDER_RATIO,
+  DEFAULT_RUNS,
 };
 
 export default Fleets;

package/src/fleets/moonLock.js

@@ -0,0 +1,31 @@
+/** The debris that gives a moon its maximum chance to appear. */
+const MOON_DEBRIS_THRESHOLD = 2000000;
+
+/** The maximum moon chance, in %, reached at `MOON_DEBRIS_THRESHOLD`. */
+const MAX_MOON_CHANCE = 20;
+
+/**
+ *
+ * Return how many ships must be destroyed on a position to reach the maximum moon chance
+ *
+ * Only metal and crystal land in the debris field here, and the universe keeps
+ * `debrisFactor` of them.
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {number} debrisFactor The universe debris factor, e.g. 0.3 for 30%
+ * @param {number} [threshold] The debris to reach, 2 000 000 by default
+ * @return {number} The number of ships
+ */
+function getMoonLockShips(ship, debrisFactor, threshold = MOON_DEBRIS_THRESHOLD) {
+  if (!(debrisFactor > 0)) {
+    throw new Error(`debrisFactor must be greater than 0, received ${debrisFactor}`);
+  }
+
+  const debris = (ship.cost.metal ?? 0) + (ship.cost.crystal ?? 0);
+  if (!(debris > 0)) {
+    throw new Error('the ship leaves no metal or crystal debris');
+  }
+
+  return Math.ceil(threshold / (debrisFactor * debris));
+}
+
+export { getMoonLockShips, MOON_DEBRIS_THRESHOLD, MAX_MOON_CHANCE };

package/src/fleets/moonbreak.js

@@ -0,0 +1,133 @@
+/** A moon size, in km, can only be in this range. */
+const MIN_MOON_SIZE = 3464;
+const MAX_MOON_SIZE = 8944;
+
+/** Each attacker spreads their Deathstars over this many waves. */
+const WAVES_PER_ATTACKER = 6;
+
+function assertMoonSize(moonSize) {
+  if (!Number.isFinite(moonSize) || moonSize < MIN_MOON_SIZE || moonSize > MAX_MOON_SIZE) {
+    throw new Error(`moonSize must be between ${MIN_MOON_SIZE} and ${MAX_MOON_SIZE}, received ${moonSize}`);
+  }
+}
+
+function assertFleets(fleets) {
+  if (!Array.isArray(fleets) || fleets.length === 0) {
+    throw new Error('fleets must be a non-empty array of Deathstar counts');
+  }
+  for (const rip of fleets) {
+    if (!Number.isInteger(rip) || rip < 0) {
+      throw new Error(`each fleet must be an integer >= 0, received ${rip}`);
+    }
+  }
+}
+
+/**
+ *
+ * Return the chance that a single wave of Deathstars destroys the moon
+ *
+ * `(100 - sqrt(moonSize)) * sqrt(rip) / 100`, capped at 1
+ * @param {number} moonSize The moon diameter, in km
+ * @param {number} rip The number of Deathstars in the wave
+ * @return {number} The chance, between 0 and 1
+ */
+function getWaveChance(moonSize, rip) {
+  return Math.min(1, ((100 - Math.sqrt(moonSize)) * Math.sqrt(rip)) / 100);
+}
+
+/**
+ *
+ * Return the waves one attacker sends, in firing order
+ *
+ * The Deathstars are spread over 6 waves: when the count is not a multiple of 6,
+ * the first waves carry one extra ship. Under 6 Deathstars, the last waves are
+ * empty, which neither threaten the moon nor lose a ship.
+ * @param {number} rip The attacker's Deathstars
+ * @return {number[]} The size of each of the 6 waves
+ */
+function getMoonbreakWaves(rip) {
+  const base = Math.floor(rip / WAVES_PER_ATTACKER);
+  const remainder = rip % WAVES_PER_ATTACKER;
+
+  return Array.from({ length: WAVES_PER_ATTACKER }, (_, i) => (i < remainder ? base + 1 : base));
+}
+
+/**
+ *
+ * Return the chance that a coordinated attack destroys the moon
+ *
+ * The attackers fire one after the other and the moon is gone as soon as one
+ * wave succeeds, so the attack fails only when every wave fails.
+ * @param {number} moonSize The moon diameter, in km (3464 to 8944)
+ * @param {number[]} fleets The Deathstars of each attacker, in firing order
+ * @return {number} The chance, between 0 and 1
+ */
+function getMoonbreakChance(moonSize, fleets) {
+  assertMoonSize(moonSize);
+  assertFleets(fleets);
+
+  const failure = fleets
+    .flatMap(getMoonbreakWaves)
+    .reduce((acc, rip) => acc * (1 - getWaveChance(moonSize, rip)), 1);
+
+  return 1 - failure;
+}
+
+/**
+ *
+ * Return the expected Deathstar losses of a coordinated attack
+ *
+ * Each Deathstar of a wave is destroyed with probability `sqrt(moonSize) / 200`,
+ * and a wave only costs ships if every wave before it failed. The variance sums
+ * the per-wave binomial variances (the waves are treated as independent), and
+ * the spread is summarised as a gaussian around the mean: 1σ / 2σ / 3σ for the
+ * 68 / 95 / 99 % bands, clamped between 0 and the whole fleet.
+ * @param {number} moonSize The moon diameter, in km (3464 to 8944)
+ * @param {number[]} fleets The Deathstars of each attacker, in firing order
+ * @return {{
+ *   mean: number, sigma: number,
+ *   bands: { confidence: number, min: number, max: number }[],
+ * }} The losses, unrounded
+ */
+function getMoonbreakLosses(moonSize, fleets) {
+  assertMoonSize(moonSize);
+  assertFleets(fleets);
+
+  const destructionRate = Math.sqrt(moonSize) / 200;
+  const total = fleets.reduce((acc, rip) => acc + rip, 0);
+
+  let mean = 0;
+  let variance = 0;
+  // The chance that every wave so far has failed, so that this one fires.
+  let reached = 1;
+
+  for (const size of fleets.flatMap(getMoonbreakWaves)) {
+    const p = destructionRate * reached;
+    mean += size * p;
+    variance += size * p * (1 - p);
+    reached *= 1 - getWaveChance(moonSize, size);
+  }
+
+  const sigma = Math.sqrt(variance);
+  const band = (confidence, sigmas) => ({
+    confidence,
+    min: Math.max(mean - sigmas * sigma, 0),
+    max: Math.min(mean + sigmas * sigma, total),
+  });
+
+  return {
+    mean,
+    sigma,
+    bands: [band(68, 1), band(95, 2), band(99, 3)],
+  };
+}
+
+export {
+  getWaveChance,
+  getMoonbreakWaves,
+  getMoonbreakChance,
+  getMoonbreakLosses,
+  MIN_MOON_SIZE,
+  MAX_MOON_SIZE,
+  WAVES_PER_ATTACKER,
+};

package/types/fleets/combat.d.ts

@@ -1,19 +1,84 @@
 declare const ROUNDS = 6;
+/** The share of destroyed defenses that come back after a battle, on most universes. */
+declare const DEFAULT_REPAIR_FACTOR = 0.7;
+/** The share of the defender's resources a winning attacker can carry away. */
+declare const DEFAULT_PLUNDER_RATIO = 0.5;
 /**
  * A tiny deterministic PRNG (mulberry32), so a battle can be replayed.
  */
 declare function createRandom(seed: any): () => number;
+export type CombatResult = {
+    /**
+     * Who won
+     */
+    winner: 'attacker' | 'defender' | 'draw';
+    /**
+     * How many rounds it lasted
+     */
+    rounds: number;
+    /**
+     * The PRNG seed it ran with
+     */
+    seed: number;
+    /**
+     *   What is left of the attacker, and what it lost
+     */
+    attacker: {
+        survivors: import('../types.js').FleetEntry[];
+        losses: import('../types.js').FleetEntry[];
+    };
+    /**
+     * What is left of the defender, what it lost, and which of its lost defenses come back
+     */
+    defender: {
+        survivors: import('../types.js').FleetEntry[];
+        losses: import('../types.js').FleetEntry[];
+        rebuilt: import('../types.js').FleetEntry[];
+    };
+    /**
+     * The debris field
+     */
+    debris: import('../types.js').Resources;
+    /**
+     * The moon chance it gives, in %
+     */
+    moonChance: number;
+    /**
+     * What the attacker carries away
+     */
+    plunder: import('../types.js').Resources;
+};
+/**
+ * @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
@@ -22,13 +87,16 @@ declare function createRandom(seed: any): () => number;
  * @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
  */
 declare function simulateCombat(attacker: {
     fleet: import('../types.js').FleetEntry[];
@@ -38,20 +106,16 @@ declare function simulateCombat(attacker: {
     debrisFactor?: number;
     deuteriumDebrisFactor?: number;
     defenseDebris?: boolean;
-}): {
-    winner: 'attacker' | 'defender' | 'draw';
-    rounds: number;
-    seed: number;
-    attacker: {
-        survivors: import('../types.js').FleetEntry[];
-        losses: import('../types.js').FleetEntry[];
+    defenseDebrisFactor?: number;
+    repairFactor?: number;
+    plunder?: {
+        resources: import('../types.js').Resources;
+        ratio?: number;
+        hyperspaceLevel?: number;
+        hyperspaceMultiplier?: number;
+        bonus?: number;
     };
-    defender: {
-        survivors: import('../types.js').FleetEntry[];
-        losses: import('../types.js').FleetEntry[];
-    };
-    debris: import('../types.js').Resources;
-};
-export { createRandom, ROUNDS };
+}): CombatResult;
+export { createRandom, ROUNDS, DEFAULT_REPAIR_FACTOR, DEFAULT_PLUNDER_RATIO };
 export default simulateCombat;
 //# sourceMappingURL=combat.d.ts.map

package/types/fleets/combat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"combat.d.ts","sourceRoot":"","sources":["../../src/fleets/combat.js"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,IAAI,CAAC;AAmCjB;;GAEG;AACH,iBAAS,YAAY,CAAC,IAAI,KAAA,gBAWzB;AAqJD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAS,cAAc,CAAC,QAAQ,EAf7B;IAAqD,KAAK,EAAlD,OAAO,aAAa,EAAE,UAAU,EAAE,CAC1C;IAAqD,KAAK,AAA1D,CACA,EADQ,OAAO,aAAa,EAAE,WAAW,CACzC;CAa6B,EAAE,QAAQ,EAb/B,MAa+B,EAAE,OAAO,AAZhD,CAKA,EAJA;IAAyB,IAAI,AAA7B,CACA,EADQ,MAAM,CACd;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;IAAyB,qBAAqB,AAA9C,CACA,EADQ,MAAM,CACd;IAA0B,aAAa,AAAvC,CACA,EADQ,OAAO,CACf;CAOqD,GAP3C;IACR,MAAM,EAAE,UAAU,GAAC,UAAU,GAAC,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IACnE,QAAQ,EAAE;QAAC,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAA;KAAC,CAAC;IACtG,QAAQ,EAAE;QAAC,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAA;KAAC,CAAC;IACtG,MAAM,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;CACzC,CA6DH;AAED,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;eACjB,cAAc"}
+{"version":3,"file":"combat.d.ts","sourceRoot":"","sources":["../../src/fleets/combat.js"],"names":[],"mappings":"AAKA,QAAA,MAAM,MAAM,IAAI,CAAC;AAcjB,wFAAwF;AACxF,QAAA,MAAM,qBAAqB,MAAM,CAAC;AAElC,+EAA+E;AAC/E,QAAA,MAAM,qBAAqB,MAAM,CAAC;AA0BlC;;GAEG;AACH,iBAAS,YAAY,CAAC,IAAI,KAAA,gBAWzB;AAuNE,YAAkB,YAAY,GAC9B;;;;IAAyC,MAAM,EAApC,UAAU,GAAC,UAAU,GAAC,MAAM,CACvC;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAwG,QAAQ,EAArG;QAAC,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAA;KAAC,CAEtG;;;;IAGG,QAAQ,EAHA;QACT,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAC1F,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;KAC7C,CACD;;;;IAA4C,MAAM,EAAvC,OAAO,aAAa,EAAE,SAAS,CAC1C;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAA4C,OAAO,EAAxC,OAAO,aAAa,EAAE,SAAS,CAC5C;CAAA,CAAA;AAdD;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,iBAAS,cAAc,CAAC,QAAQ,EAlB7B;IAAqD,KAAK,EAAlD,OAAO,aAAa,EAAE,UAAU,EAAE,CAC1C;IAAqD,KAAK,AAA1D,CACA,EADQ,OAAO,aAAa,EAAE,WAAW,CACzC;CAgB6B,EAAE,QAAQ,EAhB/B,MAgB+B,EAAE,OAAO,AAfhD,CAaA,EAZA;IAAyB,IAAI,AAA7B,CACA,EADQ,MAAM,CACd;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;IAAyB,qBAAqB,AAA9C,CACA,EADQ,MAAM,CACd;IAA0B,aAAa,AAAvC,CACA,EADQ,OAAO,CACf;IAAyB,mBAAmB,AAA5C,CACA,EADQ,MAAM,CACd;IAAyB,YAAY,AAArC,CACA,EADQ,MAAM,CACd;IAAyB,OAAO,AAAhC,CAMA,EALA;QAAyD,SAAS,EAA1D,OAAO,aAAa,EAAE,SAAS,CACvC;QAAiC,KAAK,AAAtC,CACA,EADQ,MAAM,CACd;QAAiC,eAAe,AAAhD,CACA,EADQ,MAAM,CACd;QAAiC,oBAAoB,AAArD,CACA,EADQ,MAAM,CACd;QAAiC,KAAK,AAAtC,CACA,EADQ,MAAM,CACd;KAAA,CAAA;CAEqD,GAF3C,YAAY,CAsExB;AAED,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,CAAC;eAC/D,cAAc"}

package/types/fleets/combatStatistics.d.ts

@@ -0,0 +1,67 @@
+import simulateCombat from './combat.js';
+/** Enough runs for the averages to settle, without making a big battle wait. */
+declare const DEFAULT_RUNS = 100;
+/**
+ *
+ * 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
+ */
+declare function getCombatStatistics(results: import('./combat.js').CombatResult[]): {
+    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;
+};
+/**
+ *
+ * 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`
+ */
+declare function simulateCombats(attacker: Parameters<typeof simulateCombat>[0], defender: Parameters<typeof simulateCombat>[1], options?: Parameters<typeof simulateCombat>[2] & {
+    runs?: number;
+}): ReturnType<typeof getCombatStatistics>;
+export { getCombatStatistics, simulateCombats, DEFAULT_RUNS };
+//# sourceMappingURL=combatStatistics.d.ts.map

package/types/fleets/combatStatistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combatStatistics.d.ts","sourceRoot":"","sources":["../../src/fleets/combatStatistics.js"],"names":[],"mappings":"AAAA,OAAO,cAAc,MAAM,aAAa,CAAC;AAEzC,gFAAgF;AAChF,QAAA,MAAM,YAAY,MAAM,CAAC;AAoEzB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,mBAAmB,CAAC,OAAO,EAlBzB,OAAO,aAAa,EAAE,YAAY,EAkBT,GAjBvB;IACR,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QACR,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAC1F,aAAa,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;KAChD,CAAC;IACF,QAAQ,EAAE;QACR,SAAS,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAC1F,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC;QAAC,aAAa,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;KAC7F,CAAC;IACF,MAAM,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,aAAa,EAAE,SAAS,CAAC;CAC1C,CAiEH;AAED;;;;;;;;;;GAUG;AACH,iBAAS,eAAe,CAAC,QAAQ,EANtB,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAMb,EAAE,QAAQ,EALhC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAKH,EAAE,OAAO,AAJjD,CAEA,EAFQ,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAIP,GAF5C,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAgBlD;AAED,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC"}

package/types/fleets/expedition.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The maximum metal an expedition can find, tiered by the score of the
+ * universe's top player. `below` is an exclusive upper bound; above the last
+ * tier every universe shares `EXPEDITION_TOP_TIER_BASE`.
+ */
+declare const EXPEDITION_FIND_TIERS: readonly (Readonly<{
+    below: 10000;
+    base: 40000;
+}> | Readonly<{
+    below: 100000;
+    base: 500000;
+}> | Readonly<{
+    below: 1000000;
+    base: 1200000;
+}> | Readonly<{
+    below: 5000000;
+    base: 1800000;
+}> | Readonly<{
+    below: 25000000;
+    base: 2400000;
+}> | Readonly<{
+    below: 50000000;
+    base: 3000000;
+}> | Readonly<{
+    below: 75000000;
+    base: 3600000;
+}> | Readonly<{
+    below: 100000000;
+    base: 4200000;
+}>)[];
+declare const EXPEDITION_TOP_TIER_BASE = 5000000;
+/**
+ *
+ * Return the expedition find base of a universe, before any multiplier
+ * @param {number} topScore The points of the universe's top player
+ * @return {number} The base, in metal
+ */
+declare function getExpeditionFindBase(topScore: number): number;
+/**
+ *
+ * Return the largest metal find a single expedition can bring back
+ *
+ * `base * classFactor * (pathfinder ? 2 : 1) * (1 + lifeformResourceBonus)`
+ *
+ * - a Discoverer gets `classFactor = (1 + explorerBonus * (1 + lifeformExplorerBonus)) * economySpeed`:
+ *   the lifeform class enhancement amplifies the class bonus itself, and only
+ *   the Discoverer's finds scale with the economy speed;
+ * - any other class gets `classFactor = 1`.
+ *
+ * Crystal and deuterium finds are smaller than metal finds. Every bonus is a
+ * fraction: 0.2 for the 20 % the in-game lifeform bonus page shows.
+ * @param {object} options The universe and the player's bonuses
+ * @param {number} options.topScore The points of the universe's top player
+ * @param {number} options.economySpeed The universe economy speed
+ * @param {boolean} [options.explorer] Whether the player is a Discoverer
+ * @param {boolean} [options.pathfinder] Whether the fleet holds a Pathfinder
+ * @param {number} [options.explorerBonus] The Discoverer class bonus, 0.5 by default
+ * @param {number} [options.lifeformExplorerBonus] The lifeform Discoverer enhancement
+ * @param {number} [options.lifeformResourceBonus] The lifeform expedition resource bonus
+ * @return {number} The maximum find, in metal
+ */
+declare function getExpeditionMaxFind({ topScore, economySpeed, explorer, pathfinder, explorerBonus, lifeformExplorerBonus, lifeformResourceBonus, }: {
+    topScore: number;
+    economySpeed: number;
+    explorer?: boolean;
+    pathfinder?: boolean;
+    explorerBonus?: number;
+    lifeformExplorerBonus?: number;
+    lifeformResourceBonus?: number;
+}): number;
+/**
+ *
+ * Return the cargo capacity of one ship, with its bonuses
+ *
+ * `ship.cargo * (1 + hyperspaceLevel * hyperspaceMultiplier / 100 + bonus)`:
+ * every bonus is a share of the base cargo, so they add up.
+ * @param {import('../types.js').DestroyableEntry} ship An entry of models/destroyable.js
+ * @param {object} [options] The bonuses
+ * @param {number} [options.hyperspaceLevel] The Hyperspace Technology level
+ * @param {number} [options.hyperspaceMultiplier] The % of base cargo per level, 5 by default
+ * @param {number} [options.bonus] Any other bonus as a fraction: class (Collector 0.25 on cargo ships), lifeform…
+ * @return {number} The capacity
+ */
+declare function getCargoCapacity(ship: import('../types.js').DestroyableEntry, { hyperspaceLevel, hyperspaceMultiplier, bonus, }?: {
+    hyperspaceLevel?: number;
+    hyperspaceMultiplier?: number;
+    bonus?: number;
+}): number;
+export { getExpeditionFindBase, getExpeditionMaxFind, getCargoCapacity, EXPEDITION_FIND_TIERS, EXPEDITION_TOP_TIER_BASE, };
+//# sourceMappingURL=expedition.d.ts.map

package/types/fleets/expedition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expedition.d.ts","sourceRoot":"","sources":["../../src/fleets/expedition.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;KASzB,CAAC;AACH,QAAA,MAAM,wBAAwB,UAAU,CAAC;AAczC;;;;;GAKG;AACH,iBAAS,qBAAqB,CAAC,QAAQ,EAH5B,MAG4B,GAF3B,MAAM,CASjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iBAAS,oBAAoB,CAAC,EAC5B,QAAQ,EACR,YAAY,EACZ,QAAgB,EAChB,UAAkB,EAClB,aAAsC,EACtC,qBAAyB,EACzB,qBAAyB,GAC1B,EAjBE;IAAwB,QAAQ,EAAxB,MAAM,CACd;IAAwB,YAAY,EAA5B,MAAM,CACd;IAA0B,QAAQ,AAAlC,CACA,EADQ,OAAO,CACf;IAA0B,UAAU,AAApC,CACA,EADQ,OAAO,CACf;IAAyB,aAAa,AAAtC,CACA,EADQ,MAAM,CACd;IAAyB,qBAAqB,AAA9C,CACA,EADQ,MAAM,CACd;IAAyB,qBAAqB,AAA9C,CACA,EADQ,MAAM,CACd;CAUF,GAVW,MAAM,CAuBjB;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,gBAAgB,CAAC,IAAI,EAPnB,OAAO,aAAa,EAAE,gBAOH,EAAE,EAC9B,eAAmB,EACnB,oBAAoD,EACpD,KAAS,GACV,AAVE,CAIA,EAHA;IAAyB,eAAe,AAAxC,CACA,EADQ,MAAM,CACd;IAAyB,oBAAoB,AAA7C,CACA,EADQ,MAAM,CACd;IAAyB,KAAK,AAA9B,CACA,EADQ,MAAM,CACd;CAMG,GANM,MAAM,CAcjB;AAED,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,GACzB,CAAC"}