@elite-dangerous-almanac/core 0.1.0-beta.1

package/dist/ships/resistances.d.ts

@@ -0,0 +1,208 @@
+/**
+ * **Damage resistances** — how a build's shield and hull resistances stack, including
+ * the diminishing returns the game applies once they get high.
+ *
+ * A resistance is the fraction of incoming damage removed: `0.4` means 40% of that
+ * damage type never lands, and a *negative* value is a weakness (every shield generator
+ * is `-0.2` against thermal). Its complement is the **damage multiplier**, `1 −
+ * resistance`, which is what stacking actually multiplies.
+ *
+ * Sources stack multiplicatively on the multiplier — two 20% resisters leave
+ * `0.8 × 0.8 = 0.64`, i.e. 36% resisted rather than 40% — and then the game bends the
+ * result so that stacking cannot run away:
+ *
+ * - **Shields.** Once the boosters push the multiplier below 70% of what the generator
+ *   alone gives, the remaining gain is halved: the range `[0, max]` is squeezed into
+ *   `[max/2, max]`, where `max` is `0.7 ×` the generator's own multiplier.
+ * - **Hull.** Once the stack drops the multiplier below the lowest single source's
+ *   multiplier (capped at `0.7`), the range `[0, max]` is squeezed into `[0.35, max]`.
+ *   If the squeeze would *raise* the multiplier above `0.7`, the plain product stands.
+ *
+ * This module is data-free — pass fractions in, get fractions out. {@link ShipLoadout}
+ * (`./ship-loadout`), `./shields` and `./armour` gather the numbers for you.
+ *
+ * @remarks
+ * Reference implementation: EDCD/Coriolis,
+ * `src/app/shipyard/Calculations.js` (`diminishingReturnsShields`,
+ * `diminishingReturnsArmour`, `mapIntoDiminishingRange`, `sysResistance`), commit
+ * `68c042ca6e3db62372cbbb2077cf972345511712`. The algorithm is ported as fact, not code;
+ * credit and licence terms are in [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
+ *
+ * @example
+ * ```ts
+ * import { stackShieldResistance } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * // A stock shield generator (40% kinetic) under four 20% resistance-augmented boosters
+ * stackShieldResistance(0.4, [0.2, 0.2, 0.2, 0.2]); // -> 0.667…, not 0.4 + 4 × 0.2
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * One value per damage type — whatever the value happens to be: a resistance, a pool of
+ * effective hit points, a share of incoming damage.
+ *
+ * @remarks
+ * Absolute damage is not listed: no resistance reduces it, so there is nothing per-type
+ * to say about it. The unit is the one the field that carries this type documents.
+ */
+interface DamageTypeValues {
+    /** The kinetic figure. */
+    readonly kinetic: number;
+    /** The thermal figure. */
+    readonly thermal: number;
+    /** The explosive figure. */
+    readonly explosive: number;
+    /** The caustic figure. */
+    readonly caustic: number;
+}
+/**
+ * The four resistances a build carries, each the **fraction** of that damage type
+ * removed: `0.4` is 40% resisted, and a negative value is a weakness. Values run in
+ * `(-∞, 1]`.
+ */
+type DamageResistances = DamageTypeValues;
+/**
+ * The four resistances one **fitted module** contributes, each an optional fraction of
+ * that damage type removed: `0.4` is 40% resisted, and a negative value is a weakness. A
+ * field the record does not carry counts as `0` — no resistance and no weakness.
+ *
+ * @remarks
+ * The four fittings that carry resistances inherit these fields rather than restating
+ * them — {@link ShieldGeneratorParams}, {@link ShieldBoosterParams},
+ * {@link BulkheadParams} and {@link HullReinforcementParams} — so an
+ * {@link OutfittingModule} record, which spells them the same way, satisfies each of
+ * them as it comes. A module reinforcement package carries none of these four: what it
+ * absorbs is `moduleProtection`, one type-agnostic figure over module damage.
+ *
+ * This is the *input* shape, one module at a time. {@link DamageResistances} is the
+ * *output*: four required figures for a whole stack, keyed by bare damage type.
+ */
+interface DamageResistanceParams {
+    /** Kinetic resistance, as a fraction (negative is a weakness). Defaults to `0`. */
+    readonly kineticResistance?: number;
+    /** Thermal resistance, as a fraction (negative is a weakness). Defaults to `0`. */
+    readonly thermalResistance?: number;
+    /** Explosive resistance, as a fraction (negative is a weakness). Defaults to `0`. */
+    readonly explosiveResistance?: number;
+    /** Caustic resistance, as a fraction (negative is a weakness). Defaults to `0`. */
+    readonly causticResistance?: number;
+}
+/**
+ * One of the four damage types a {@link DamageTypeValues} carries a figure for.
+ *
+ * @remarks
+ * This is the **defensive** set — what a shield or a hull resists. Absolute damage is
+ * absent because nothing resists it. A weapon's *output* is broken down over a different
+ * set, {@link DamageDistribution} in `./modules`, which carries `absolute` and `antiXeno`
+ * and no `caustic`; the two are not interchangeable.
+ */
+type DamageType = keyof DamageTypeValues;
+/**
+ * Build a {@link DamageTypeValues} by calling `value` once per damage type.
+ *
+ * @param value - Called with each damage type in turn; returns that type's figure.
+ * @returns The four figures in one record.
+ * @remarks
+ * Every {@link DamageTypeValues} this module, `./shields` and `./armour` return is
+ * assembled here, so the four names are written out once rather than at each site that
+ * fans out over them.
+ * @example
+ * ```ts
+ * import { mapDamageTypes } from '@elite-dangerous-almanac/core/ships/resistances';
+ * import type {
+ *     DamageResistances,
+ *     DamageTypeValues,
+ * } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * declare const incoming: DamageTypeValues; // the resistible share of incoming damage
+ * declare const shields: DamageResistances;
+ *
+ * // What each type actually lands, the resistances having taken their share.
+ * mapDamageTypes((type) => incoming[type] * (1 - shields[type]));
+ * ```
+ */
+declare function mapDamageTypes(value: (type: DamageType) => number): DamageTypeValues;
+/**
+ * How much raw damage of each type a pool of hit points can soak — `total / (1 −
+ * resistance)`.
+ *
+ * @param total - The pool, in whatever unit it is measured: hull points for armour,
+ * megajoules for shields.
+ * @param resistances - The effective resistances the pool sits behind, already stacked.
+ * @returns The effective hit points per damage type, in the same unit as `total`, and
+ * `Infinity` at or above 100% — nothing of that type gets through, and a resistance past
+ * the documented `(-∞, 1]` range never reports a negative pool.
+ * @remarks
+ * A *negative* resistance is a weakness and reports **fewer** effective hit points than
+ * the pool holds, which is the point: lightweight alloy soaks less kinetic damage than
+ * its hull points suggest.
+ * @example
+ * ```ts
+ * import { effectiveHitPoints } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * // 945 hull points behind lightweight alloy's -20% kinetic
+ * effectiveHitPoints(945, { kinetic: -0.2, thermal: 0, explosive: -0.4, caustic: 0 })
+ *     .kinetic; // -> 787.5
+ * ```
+ */
+declare function effectiveHitPoints(total: number, resistances: DamageResistances): DamageTypeValues;
+/**
+ * A shield stack's effective resistance to one damage type.
+ *
+ * @param generator - The shield generator's resistance to this damage type, as a
+ * fraction (negative for a weakness).
+ * @param boosters - Each **powered** shield booster's resistance to the same type, as
+ * fractions.
+ * @returns The effective resistance, as a fraction — the share of incoming damage of
+ * that type the shields remove.
+ * @example
+ * ```ts
+ * import { stackShieldResistance } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * stackShieldResistance(0.4);                 // -> 0.4   (generator alone)
+ * stackShieldResistance(-0.2, [0.1, 0.1]);    // -> a thermal weakness, partly patched
+ * ```
+ */
+declare function stackShieldResistance(generator: number, boosters?: readonly number[]): number;
+/**
+ * A hull stack's effective resistance to one damage type.
+ *
+ * @param bulkhead - The fitted armour's resistance to this damage type, as a fraction
+ * (lightweight alloy is `-0.2` to kinetic — a weakness).
+ * @param reinforcements - Each fitted hull reinforcement package's resistance to the
+ * same type, as fractions.
+ * @returns The effective resistance, as a fraction.
+ * @example
+ * ```ts
+ * import { stackArmourResistance } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * // Reactive surface composite (+25% kinetic) with three 1.5% hull reinforcements
+ * stackArmourResistance(0.25, [0.015, 0.015, 0.015]); // -> 0.28…
+ * ```
+ */
+declare function stackArmourResistance(bulkhead: number, reinforcements?: readonly number[]): number;
+/**
+ * The extra shield resistance pips to SYS buy, on top of the generator and boosters.
+ *
+ * @param pips - Pips to the systems capacitor, `0`–`4`. Fractional pips are allowed —
+ * the game's own curve is continuous.
+ * @returns The resistance the pips add, as a fraction: `0` at no pips rising to `0.6`
+ * (60%) at four, following `0.6 × (pips / 4) ^ 0.85`.
+ * @throws {RangeError} If `pips` is not a finite number in `[0, 4]`.
+ * @remarks
+ * This applies to **every** damage type including absolute, and multiplies with the
+ * shield's own resistance rather than adding to it: incoming damage is scaled by
+ * `(1 − shieldResistance) × (1 − sysResistance)`.
+ * @example
+ * ```ts
+ * import { systemsResistance } from '@elite-dangerous-almanac/core/ships/resistances';
+ *
+ * systemsResistance(0); // -> 0
+ * systemsResistance(2); // -> 0.333
+ * systemsResistance(4); // -> 0.6
+ * ```
+ */
+declare function systemsResistance(pips: number): number;
+
+export { type DamageResistanceParams, type DamageResistances, type DamageType, type DamageTypeValues, effectiveHitPoints, mapDamageTypes, stackArmourResistance, stackShieldResistance, systemsResistance };

package/dist/ships/resistances.js

@@ -0,0 +1 @@
+export{effectiveHitPoints,mapDamageTypes,stackArmourResistance,stackShieldResistance,systemsResistance}from"../chunk-ZNCXENNB.js";//# sourceMappingURL=resistances.js.map

package/dist/ships/resistances.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}

package/dist/ships/shields.d.ts

@@ -0,0 +1,221 @@
+import { DamageResistanceParams, DamageResistances, DamageTypeValues } from './resistances.js';
+
+/**
+ * **Shields** — strength in megajoules and the resistances that decide what that
+ * strength is worth against each damage type.
+ *
+ * A generator's strength multiplier is read off a curve against the ship's **hull
+ * mass** — the bare hull, *not* the loaded ship, so fitting more modules never weakens
+ * your shields. The curve runs through three points the generator declares (`minMass`
+ * → `maxMultiplier`, `optMass` → `optMultiplier`, `maxMass` → `minMultiplier`); past
+ * `maxMass` the generator will not raise a shield at all.
+ *
+ * ```text
+ * strength = baseShieldStrength × massCurve(hullMass) × (1 + Σ booster boosts)
+ *          + Σ Guardian shield reinforcement
+ * ```
+ *
+ * Resistances stack separately, with their own diminishing returns — see
+ * `./resistances`.
+ *
+ * This module is data-free. {@link ShipLoadout.shieldMetrics} (in `./ship-loadout`)
+ * pulls the generator, boosters and reinforcement packages out of a build,
+ * post-engineering, and calls {@link shieldMetrics} for you.
+ *
+ * @remarks
+ * Reference implementation: EDCD/Coriolis, `src/app/shipyard/Calculations.js`
+ * (`shieldStrength`, `shieldMetrics`), commit
+ * `68c042ca6e3db62372cbbb2077cf972345511712`. The algorithm is ported as fact, not code;
+ * credit and licence terms are in [ATTRIBUTIONS.md](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/ATTRIBUTIONS.md).
+ *
+ * @example
+ * ```ts
+ * import { shieldMetrics } from '@elite-dangerous-almanac/core/ships/shields';
+ *
+ * shieldMetrics({
+ *   hullMass: 400,             // Anaconda
+ *   baseShieldStrength: 350,
+ *   generator: {               // 6A shield generator
+ *     minMass: 270, optMass: 540, maxMass: 1350,
+ *     minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
+ *     kineticResistance: 0.4, thermalResistance: -0.2, explosiveResistance: 0.5,
+ *   },
+ * }).strength; // -> the shield's megajoules, before boosters
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The shield generator constants a strength calculation needs — all post-engineering.
+ *
+ * @remarks
+ * An {@link OutfittingModule} record satisfies this as-is, so a catalogue entry can be
+ * passed straight in — the six curve fields and the resistances are exactly what a
+ * generator's record carries. `optMultiplier` is what a Reinforced/Thermic blueprint
+ * 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`).
+ */
+interface ShieldGeneratorParams extends DamageResistanceParams {
+    /** Hull mass at which the generator performs at `maxMultiplier`, in tonnes. */
+    readonly minMass?: number;
+    /** Hull mass at which the generator performs to spec, in tonnes. */
+    readonly optMass?: number;
+    /** Hull mass beyond which the generator cannot raise a shield, in tonnes. */
+    readonly maxMass?: number;
+    /** Minimum strength multiplier, reached at `maxMass` (the heaviest hull). */
+    readonly minMultiplier?: number;
+    /** Strength multiplier at `optMass`. */
+    readonly optMultiplier?: number;
+    /** Maximum strength multiplier, reached at `minMass` (the lightest hull). */
+    readonly maxMultiplier?: number;
+}
+/** One fitted, powered shield booster's contribution. */
+interface ShieldBoosterParams extends DamageResistanceParams {
+    /** Strength bonus, as a fraction (`0.2` = +20%). Defaults to `0`. */
+    readonly shieldBoost?: number;
+}
+/** Everything {@link shieldMetrics} needs about a build. */
+interface ShieldInput {
+    /**
+     * The **hull's** mass, in tonnes — `Ship.hullMass`, not the build's unladen mass.
+     * Shields scale with the hull alone, so fitted modules and cargo do not weaken them.
+     */
+    readonly hullMass: number;
+    /** The hull's base shield strength, in megajoules (`Ship.baseShieldStrength`). */
+    readonly baseShieldStrength: number;
+    /** The fitted shield generator, or `null`/absent when the build has none. */
+    readonly generator?: ShieldGeneratorParams | null;
+    /** Each fitted, powered shield booster. Defaults to none. */
+    readonly boosters?: readonly ShieldBoosterParams[];
+    /**
+     * Megajoules added flat by Guardian shield reinforcement packages
+     * (`OutfittingModule.shieldAddition`), summed. Defaults to `0`.
+     *
+     * @remarks
+     * This addition is not multiplied by the generator's curve or the boosters — it is
+     * a flat top-up, and it stands alone when the generator's curve contributes nothing,
+     * as it does for a hull past the generator's maximum mass. With **no** generator
+     * fitted it is dropped entirely, and the reported
+     * {@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. */
+interface ShieldMetrics {
+    /** Total shield strength, in megajoules. `0` when no generator is fitted. */
+    readonly strength: number;
+    /** The generator's own contribution, in megajoules. */
+    readonly generator: number;
+    /** What the boosters add on top of the generator, in megajoules. */
+    readonly boosters: number;
+    /**
+     * What Guardian shield reinforcement packages add, in megajoules. `0` with no
+     * generator, whatever `reinforcement` was passed — a package has no shield to
+     * reinforce.
+     */
+    readonly reinforcement: number;
+    /** The generator's strength multiplier at this hull mass. `0` with no generator. */
+    readonly massCurveMultiplier: number;
+    /**
+     * The boosters' combined multiplier, `1` with none fitted (`1.6` = +60%). `1` with
+     * no generator, whatever boosters are fitted — there is nothing for them to multiply.
+     */
+    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}.
+     */
+    readonly resistances: DamageResistances;
+    /**
+     * Effective hit points against each damage type, in megajoules —
+     * `strength / (1 − resistance)`, the raw damage of that type the shield can soak.
+     * `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.
+ * @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.
+ * @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`.
+ * @example
+ * ```ts
+ * import { shieldMassCurveMultiplier } from '@elite-dangerous-almanac/core/ships/shields';
+ *
+ * // A 6A generator (opt 540 t) on a 400 t Anaconda performs slightly above spec
+ * shieldMassCurveMultiplier(400, {
+ *   minMass: 270, optMass: 540, maxMass: 1350,
+ *   minMultiplier: 0.7, optMultiplier: 1.2, maxMultiplier: 1.7,
+ * }); // -> 1.434…
+ * ```
+ */
+declare function shieldMassCurveMultiplier(hullMass: number, generator: ShieldGeneratorParams): number;
+/**
+ * A build's shield strength, in megajoules.
+ *
+ * @param hullMass - The **hull's** mass, in tonnes.
+ * @param baseShieldStrength - The hull's base shield strength, in megajoules.
+ * @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.
+ */
+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.
+ *
+ * @param input - The hull's mass and base shield strength, the fitted generator, and
+ * any powered boosters, Guardian reinforcement and SYS pips.
+ * @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`,
+ * 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.
+ * @example
+ * ```ts
+ * import { shieldMetrics } from '@elite-dangerous-almanac/core/ships/shields';
+ * import type { ShieldGeneratorParams } from '@elite-dangerous-almanac/core/ships/shields';
+ *
+ * declare const gen: ShieldGeneratorParams;
+ *
+ * const shields = shieldMetrics({
+ *   hullMass: 400,
+ *   baseShieldStrength: 350,
+ *   generator: gen,
+ *   boosters: [{ shieldBoost: 0.2, kineticResistance: 0 }],
+ * });
+ * shields.strength;                 // -> MJ
+ * shields.resistances.kinetic;      // -> effective kinetic resistance
+ * shields.effectiveHitPoints.kinetic; // -> kinetic damage the shield can soak
+ * ```
+ */
+declare function shieldMetrics(input: ShieldInput): ShieldMetrics;
+
+export { type ShieldBoosterParams, type ShieldGeneratorParams, type ShieldInput, type ShieldMetrics, shieldMassCurveMultiplier, shieldMetrics, shieldStrength };

package/dist/ships/shields.js

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

package/dist/ships/shields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}

package/dist/ships/ship-loadout.d.ts

@@ -0,0 +1,16 @@
+import './slef.js';
+import './jump-range.js';
+import './slots.js';
+import './modules.js';
+import './power.js';
+import './shields.js';
+import './armour.js';
+import './weapons.js';
+import './ammunition.js';
+export { A as ApplyBlueprintOptions, a as AvailableBlueprint, B as BuildWeaponMetrics, D as DefenceOptions, b as FittedWeaponMetrics, J as JumpOptions, c as JumpRangeSummary, L as LoadoutExportOptions, S as ShipLoadout, e as SlefExportOptions } from '../ship-loadout-Ba63RDf-.js';
+import './source-purchase.js';
+import './loadout-calculations.js';
+import './loadout-validation.js';
+import './engineering-options.js';
+import './resistances.js';
+import './pre-engineered.js';

package/dist/ships/ship-loadout.js

@@ -0,0 +1 @@
+export{ShipLoadout}from"../chunk-RD73TFGS.js";                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   //# sourceMappingURL=ship-loadout.js.map

package/dist/ships/ship-loadout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}

package/dist/ships/ships.d.ts

@@ -0,0 +1,191 @@
+import { CoreSlots, HardpointSlotSpec, OptionalSlotSpec, ShipSlots } from './slots.js';
+
+/**
+ * The Elite Dangerous ship catalogue — every player-flyable hull's **identity, its
+ * stats, and its slot layout in one record**, with the lookups an app needs to turn
+ * an internal symbol or a display name into a {@link Ship}.
+ *
+ * There is only one list of ships and it is tiny (48 records), so the lookups here
+ * take no catalogue argument at all — they always search {@link SHIPS}. Importing one
+ * bundles the whole ship list, which is what you wanted anyway.
+ *
+ * Identity from EDCD FDevIDs (`shipyard.csv`); stats and slot layout from
+ * EDCD/coriolis-data, joined on `symbol`; see [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One ship hull — its **identity, stats and slot layout** in one record.
+ *
+ * @remarks
+ * The identity fields (`symbol`, `name`, `entitlement`) come from Frontier's
+ * shipyard registry and are always present. The stats fields (`hullMass`, `speed`,
+ * …) and the slot-layout fields (`core`, `hardpoints`, `optional`, …) come from
+ * coriolis-data and are present for every hull it covers. The Lynx Highliner
+ * (`MediumTransport01`), which is absent from the pinned coriolis-data revision, carries equivalent fields
+ * sourced from EDSY and Frontier's update notes. Masses are tonnes, `speed`/`boost`
+ * are metres per second at 4 pips to engines, rotation rates are degrees per second.
+ */
+interface Ship {
+    /**
+     * Internal identifier, e.g. `"Empire_Trader"` (Imperial Clipper).
+     *
+     * @remarks
+     * The journal's `Ship` field carries this lower-cased (`"empire_trader"`);
+     * {@link getShipBySymbol} matches case-insensitively so either form resolves.
+     * This is the hull's key — Frontier's numeric ship-type id is not carried.
+     */
+    readonly symbol: string;
+    /** Display name, e.g. `"Imperial Clipper"`. Unique across the catalogue. */
+    readonly name: string;
+    /**
+     * Frontier's DLC / purchase-grant entitlement token, e.g.
+     * `"ELITE_HORIZONS_V_PLANETARY_LANDINGS"`.
+     *
+     * @remarks
+     * Present only when the hull is gated behind an entitlement; absent (rather than
+     * empty) for hulls available to everyone.
+     */
+    readonly entitlement?: string;
+    /** Empty-hull mass, in tonnes. A build's unladen mass is this plus every fitted module. */
+    readonly hullMass: number;
+    /** Top speed at 4 pips to engines, in metres per second. */
+    readonly speed: number;
+    /** Boost speed, in metres per second. */
+    readonly boost: number;
+    /** Base shield strength, in megajoules, before generator and boosters. */
+    readonly baseShieldStrength: number;
+    /** Base armour (hull hit points) before reinforcement. */
+    readonly baseArmour: number;
+    /** Hull hardness — resistance to armour piercing. */
+    readonly hardness: number;
+    /** Mass-lock factor — how strongly the hull impedes a smaller ship's FSD. */
+    readonly masslock?: number;
+    /** Number of crew seats (SLF/multicrew). */
+    readonly crew: number;
+    /** Heat capacity — how much heat the hull absorbs before taking damage. */
+    readonly heatCapacity?: number;
+    /** Reserve tank capacity, in tonnes (feeds the main tank from empty). */
+    readonly reserveFuelCapacity: number;
+    /**
+     * Standard price of the **hull alone**, in credits, before any discount. This is
+     * the figure a shipyard quotes when you already own the modules.
+     */
+    readonly hullCost: number;
+    /**
+     * Standard price of the hull **with its default module loadout**, in credits — the
+     * "retail" price a shipyard shows for a ready-to-fly ship. Always ≥ {@link hullCost}.
+     */
+    readonly retailCost: number;
+    /** Pitch rate, in degrees per second. */
+    readonly pitch: number;
+    /** Roll rate, in degrees per second. */
+    readonly roll: number;
+    /** Yaw rate, in degrees per second. */
+    readonly yaw: number;
+    /** Minimum thrust as a percentage — the throttle floor. */
+    readonly minThrust: number;
+    /** Speed gained per pip to engines, as a fraction of base speed. */
+    readonly pipSpeed?: number;
+    /** The seven core-internal mount sizes. */
+    readonly core: CoreSlots;
+    /**
+     * Weapon hardpoints, largest first (1 Small – 4 Huge). A mount carries a
+     * `restriction` only when it takes one family of weapons and nothing else — on
+     * the Type-11 Prospector's four mining mounts alone.
+     */
+    readonly hardpoints: readonly HardpointSlotSpec[];
+    /** Number of tiny utility mounts. */
+    readonly utility: number;
+    /**
+     * Optional-internal mounts, largest first. A mount carries a `name` only where the
+     * game's slot key is not what `enumerateSlots` would number it — the Anaconda's
+     * `Slot14_Size1`, the Type-9 Heavy's `Slot00_Size8`, the Keelback's
+     * `Slot03_Size3`.
+     */
+    readonly optional: readonly OptionalSlotSpec[];
+}
+/**
+ * Every player-flyable ship hull, in Frontier's shipyard order (roughly the order
+ * the registry order, beginning with Sidewinder).
+ *
+ * @example
+ * ```ts
+ * import { SHIPS } from '@elite-dangerous-almanac/core/ships/ships';
+ *
+ * SHIPS.length;                                  // -> 48
+ * SHIPS.find((s) => s.symbol === 'Anaconda')?.name; // -> 'Anaconda'
+ * ```
+ */
+declare const SHIPS: readonly Ship[];
+/**
+ * Look up a ship by its internal symbol, case-insensitively.
+ *
+ * @param symbol - The internal identifier, e.g. `"Empire_Trader"`. Leading/trailing
+ * whitespace and case are ignored, so the journal's lower-cased form
+ * (`"empire_trader"`) resolves too.
+ * @returns The matching {@link Ship}, or `null` if no hull has that symbol.
+ * @remarks
+ * The hulls form one small, unsplit catalogue, so unlike module, material,
+ * micro-resource and commodity lookups there is no useful subset argument to narrow.
+ * @throws {TypeError} If `symbol` is present and not a string. A nullish
+ * `symbol` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getShipBySymbol } from '@elite-dangerous-almanac/core/ships/ships';
+ *
+ * getShipBySymbol('empire_trader')?.name; // -> 'Imperial Clipper'
+ * ```
+ */
+declare function getShipBySymbol(symbol: string): Ship | null;
+/**
+ * Look up a ship by display name, case-insensitively.
+ *
+ * @param name - The display name as the shipyard spells it, e.g.
+ * `"Imperial Clipper"`. Leading/trailing whitespace and case are ignored, but
+ * matching is otherwise exact.
+ * @returns The matching {@link Ship}, or `null` if no hull has that name.
+ * @remarks
+ * The hulls form one small, unsplit catalogue, so unlike module, material,
+ * micro-resource and commodity lookups there is no useful subset argument to narrow.
+ * @throws {TypeError} If `name` is present and not a string. A nullish
+ * `name` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getShipByName } from '@elite-dangerous-almanac/core/ships/ships';
+ *
+ * getShipByName('imperial clipper')?.symbol; // -> 'Empire_Trader'
+ * ```
+ */
+declare function getShipByName(name: string): Ship | null;
+/**
+ * A hull's slot layout as a self-contained {@link ShipSlots}, ready to feed
+ * {@link enumerateSlots}.
+ *
+ * @param symbol - The internal identifier, e.g. `"Anaconda"` (case-insensitive).
+ * @returns The hull's slot layout, or `null` if no hull with that symbol is carried
+ * or its catalogue record has no slot data. This is a projection of the slot-bearing
+ * fields already on {@link Ship}.
+ * @remarks
+ * This is the **read-only** layout, for your own outfitting UI (feed it to
+ * `enumerateSlots`). To assemble and edit an actual build — fit modules, engineer
+ * them, read jump range — start a `ShipLoadout` instead and use its live
+ * `slots()` / `slots('core')` views.
+ * @throws {TypeError} If `symbol` is present and not a string. A nullish
+ * `symbol` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getShipSlots } from '@elite-dangerous-almanac/core/ships/ships';
+ *
+ * getShipSlots('anaconda')?.hardpoints;
+ * // -> [{ size: 4 }, { size: 3 }, { size: 3 }, { size: 3 }, { size: 2 }, ...]
+ * getShipSlots('LakonMiner')?.hardpoints[0];
+ * // -> { size: 3, restriction: 'mining', name: 'LargeMiningHardpoint1' }
+ * getShipSlots('Anaconda')?.optional?.at(-2);   // -> { size: 1, name: 'Slot14_Size1' }
+ * getShipSlots('Sidewinder')?.optional?.at(-2); // -> { size: 1 } — the rules fit
+ * ```
+ */
+declare function getShipSlots(symbol: string): ShipSlots | null;
+
+export { SHIPS, type Ship, getShipByName, getShipBySymbol, getShipSlots };

package/dist/ships/ships.js

@@ -0,0 +1 @@
+export{SHIPS,getShipByName,getShipBySymbol,getShipSlots}from"../chunk-462OKHXR.js";                                                                                       //# sourceMappingURL=ships.js.map

package/dist/ships/ships.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"O"}