@elite-dangerous-almanac/core 0.1.7 → 0.2.0

package/dist/ships/shields.d.ts

@@ -1,4 +1,4 @@
-import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './resistances.js';
+import { DamageResistances, DamageTypeValues, DamageResistanceParams } from './resistances.js';
 
 /**
  * **Shields** — strength in megajoules and the resistances that decide what that
@@ -16,9 +16,10 @@ import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './r
  * ```
  *
  * Resistances stack separately, with their own diminishing returns — see
- * `./resistances`.
+ * `./resistances`. Everything here is **pip-free**: the SYS capacitor's own resistance,
+ * and the effective figures it buys, live in `./shield-capacitor`.
  *
- * This module is data-free. {@link ShipLoadout.shieldMetrics} (in `./ship-loadout`)
+ * This module is data-free. {@link BuildMetrics.shieldMetrics} (in `./build-metrics`)
  * pulls the generator, boosters and reinforcement packages out of a build,
  * post-engineering, and calls {@link shieldMetrics} for you.
  *
@@ -56,6 +57,13 @@ import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './r
  * moves. Every field is optional because the type accepts those records; a generator
  * **missing** any of the six curve fields cannot be placed on the curve at all, and
  * raises no shield ({@link shieldMassCurveMultiplier} returns `0`).
+ *
+ * A generator that carries all six is held to the curve's shape: every value finite and
+ * non-negative, masses strictly ordered `minMass < optMass < maxMass` (or all equal, for
+ * a constant curve), multipliers strictly ordered
+ * `minMultiplier < optMultiplier < maxMultiplier` (or all equal), and equal multipliers
+ * wherever the masses are all equal. Anything else is a `RangeError` rather than a
+ * plausible-looking number.
  */
 interface ShieldGeneratorParams extends DamageResistanceParams {
     /** Hull mass at which the generator performs at `maxMultiplier`, in tonnes. */
@@ -101,15 +109,15 @@ interface ShieldInput {
      * {@link ShieldMetrics.reinforcement} is `0`.
      */
     readonly reinforcement?: number;
-    /**
-     * Pips to the systems capacitor, `0`–`4`, folded into the reported resistances when
-     * a generator is fitted; with none, they are reported only as
-     * {@link ShieldMetrics.systemsResistance}.
-     * Defaults to `0` — the bare shield, as an outfitting screen shows it.
-     */
-    readonly systemsPips?: number;
 }
-/** A build's shield strength, where it comes from, and what it resists. */
+/**
+ * A build's shield strength, where it comes from, and what it resists.
+ *
+ * @remarks
+ * Frozen — nested records and lists included — so a result can be held, cached and
+ * shared without a defensive copy. Derive a changed figure with a spread rather than
+ * by assigning into one.
+ */
 interface ShieldMetrics {
     /** Total shield strength, in megajoules. `0` when no generator is fitted. */
     readonly strength: number;
@@ -131,9 +139,17 @@ interface ShieldMetrics {
      */
     readonly boostMultiplier: number;
     /**
-     * Effective resistances, generator and boosters stacked with diminishing returns,
-     * and the SYS pips folded in. `0` for every damage type when no generator is fitted;
-     * the pips are then reported only in {@link ShieldMetrics.systemsResistance}.
+     * Effective resistances, generator and boosters stacked with diminishing returns.
+     * The SYS pips are **not** in these — they belong to the capacitor, and
+     * {@link shieldCapacitorMetrics} folds them in. `0` for every damage type when no
+     * generator is fitted.
+     *
+     * @remarks
+     * Fractions rather than percentages, and **unrounded**: the stacking is
+     * floating-point arithmetic, so a nominal −20% reads as `-0.19999999999999996`
+     * rather than `-0.2`. Round where the figure is displayed, not before it is
+     * composed further — {@link ShieldMetrics.effectiveHitPoints} is derived from
+     * exactly these values.
      */
     readonly resistances: DamageResistances;
     /**
@@ -142,24 +158,35 @@ interface ShieldMetrics {
      * `Infinity` where a resistance reaches 100%.
      */
     readonly effectiveHitPoints: DamageTypeValues;
-    /** The extra resistance the SYS pips contribute, as a fraction. */
-    readonly systemsResistance: number;
 }
 /**
  * A shield generator's strength multiplier at a given hull mass.
  *
- * @param hullMass - The **hull's** mass, in tonnes (not the loaded ship's).
- * @param generator - The generator's mass/multiplier curve, post-engineering.
+ * @param hullMass - The **hull's** mass, in tonnes (not the loaded ship's). Finite and
+ * non-negative.
+ * @param generator - The generator's mass/multiplier curve, post-engineering. Either all
+ * six curve fields, or a record the catalogue left incomplete — see the `0` cases below.
  * @returns The multiplier to apply to the hull's base shield strength: `minMultiplier`
  * for a hull sitting exactly on `maxMass`, no more than `maxMultiplier` for a
  * featherweight one, and **`0` past `maxMass`** — a generator cannot raise a shield
  * around a hull heavier than it is rated for. Also `0` for a generator whose record is
  * missing part of its curve.
+ * @throws {RangeError} If `hullMass` is not a finite number of zero or more, or if the
+ * generator carries all six curve fields and they are not a physical curve: every one
+ * has to be finite and non-negative, the masses strictly ordered
+ * `minMass < optMass < maxMass` (or all equal, for a constant curve), the multipliers
+ * strictly ordered `minMultiplier < optMultiplier < maxMultiplier` (or all equal), and an
+ * all-equal mass curve must have equal multipliers. A curve that is merely *absent* still
+ * answers `0`: a catalogue record missing any of the six fields is incomplete data, not a
+ * non-physical curve, and this is the only mass-curve outcome that is not a number or a
+ * throw.
  * @remarks
  * The curve is a power law fitted through the generator's three declared points:
  * normalize the mass into `[0, 1]` between `maxMass` and `minMass`, raise it to the
  * exponent that makes the curve pass through `(optMass, optMultiplier)`, then
- * interpolate between `minMultiplier` and `maxMultiplier`.
+ * interpolate between `minMultiplier` and `maxMultiplier`. It is the same curve
+ * `thrusterMassCurveMultiplier` reads a thruster's performance off, and the two agree on
+ * every input they both accept.
  * @example
  * ```ts
  * import { shieldMassCurveMultiplier } from '@elite-dangerous-almanac/core/ships/shields';
@@ -170,6 +197,24 @@ interface ShieldMetrics {
  *   minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
  * }); // -> 1.434…
  * ```
+ * @example
+ * ```ts
+ * import { shieldMassCurveMultiplier } from '@elite-dangerous-almanac/core/ships/shields';
+ *
+ * // A generator whose optimal mass sits on its maximum is not a curve at all
+ * try {
+ *   shieldMassCurveMultiplier(400, {
+ *     minMass: 270, optMass: 1350, maxMass: 1350,
+ *     minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
+ *   });
+ * } catch (error) {
+ *   (error as Error).message;
+ *   // -> 'shieldMassCurveMultiplier: generator: masses must be strictly ordered minMass < optMass < maxMass, or all equal'
+ * }
+ *
+ * // A record the catalogue left incomplete is data that is missing, not data that is wrong
+ * shieldMassCurveMultiplier(400, { optMass: 540, optMultiplier: 1.2 }); // -> 0
+ * ```
  */
 declare function shieldMassCurveMultiplier(hullMass: number, generator: ShieldGeneratorParams): number;
 /**
@@ -180,24 +225,37 @@ declare function shieldMassCurveMultiplier(hullMass: number, generator: ShieldGe
  * @param generator - The fitted generator, post-engineering.
  * @param boostMultiplier - The boosters' combined multiplier — `1 + Σ shieldBoost`.
  * Defaults to `1` (no boosters).
- * @returns The shield's megajoules, before any Guardian reinforcement addition.
+ * @returns The shield's megajoules, before any Guardian reinforcement addition. `0` for a
+ * hull past the generator's `maxMass`, and `0` for a generator whose record is missing
+ * part of its curve — see {@link shieldMassCurveMultiplier}.
+ * @throws {RangeError} If `hullMass` is not a finite number of zero or more, or the
+ * generator carries a complete but non-physical curve — the contract
+ * {@link shieldMassCurveMultiplier} documents, reported as `shieldStrength`.
  */
 declare function shieldStrength(hullMass: number, baseShieldStrength: number, generator: ShieldGeneratorParams, boostMultiplier?: number): number;
 /**
- * Everything an outfitting screen shows about a build's shields: strength, where it
- * comes from, and the effective resistances.
+ * A build's bare shields: strength, where it comes from, and the resistances the
+ * generator and boosters stack up between them.
+ *
+ * These are the **pip-free** figures, the ones an outfitting screen shows. The SYS
+ * capacitor is a separate story with its own entry point,
+ * {@link shieldCapacitorMetrics}, which takes what this returns and folds a pip
+ * allocation into it.
  *
  * @param input - The hull's mass and base shield strength, the fitted generator, and
- * any powered boosters, Guardian reinforcement and SYS pips.
+ * any powered boosters and Guardian reinforcement.
  * @returns The {@link ShieldMetrics}. With no generator fitted there is no shield for
  * a resistance to apply to: every strength figure is `0` — any `reinforcement` passed is
  * dropped, since a Guardian package has no shield to reinforce — and `resistances` and
- * `effectiveHitPoints` are `0` for every damage type, so a hull with no shields gets no
- * benefit from the SYS pips. The pips are still reported on their own, as
- * `systemsResistance`. `massCurveMultiplier` is `0` and `boostMultiplier` is `1`,
+ * `effectiveHitPoints` are `0` for every damage type.
+ * `massCurveMultiplier` is `0` and `boostMultiplier` is `1`,
  * whatever boosters are fitted, since there is no generator strength to multiply.
- * @throws {RangeError} If `systemsPips` is not a finite number in `[0, 4]`. The pips are
- * checked before the generator, so this applies with no generator fitted too.
+ * @throws {RangeError} With a generator fitted, if `hullMass` is not a finite number of
+ * zero or more, or the generator
+ * carries a complete but non-physical curve — the contract
+ * {@link shieldMassCurveMultiplier} documents, reported as `shieldMetrics`. A generator
+ * whose record is simply *missing* part of its curve is not a failure: `hullMass` is
+ * never read, and `massCurveMultiplier` and every strength figure are `0`.
  * @example
  * ```ts
  * import { shieldMetrics } from '@elite-dangerous-almanac/core/ships/shields';

package/dist/ships/shields.js

@@ -1 +1 @@
-export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength}from"../chunk-2FHHMYDC.js";                             //# sourceMappingURL=shields.js.map
+export{shieldMassCurveMultiplier,shieldMetrics,shieldStrength}from"../chunk-QTAMQ6ME.js";                                                                                       //# sourceMappingURL=shields.js.map