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

package/dist/ships/blueprint-journal.d.ts

@@ -0,0 +1,116 @@
+/**
+ * **Reading a journal `BlueprintName` against the module it was written for** — the one
+ * question that needs the journal-collision catalogue and the engineering menus at the
+ * same time.
+ *
+ * Almost every blueprint id means one recipe wherever it appears, and for those
+ * `getBlueprint(id)` is the answer. Three ids are not like that, and this is where that is
+ * dealt with. One of the three is `Weapon_Overcharged` on a multi-cannon, so any consumer
+ * reading journals from combat ships meets this — it is not the corner case the two scanner
+ * ids alone would make it.
+ *
+ * It lives in its own module because the join depends on both menus and the three
+ * colliding journal spellings. Keeping those spellings in a tiny purpose-specific
+ * catalogue means this resolver does not load every blueprint grade, modifier and
+ * material. `package.test.mjs` guards that package boundary.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The blueprint whose numbers a module actually rolls when a journal names `blueprint` on
+ * it — the same id back, except where the game spells two different recipes alike.
+ *
+ * **One `BlueprintName`, two recipes.** Long Range and Wide Angle are offered on the
+ * internal sensor suite and on the KWS/manifest/wake scanners, and the game writes the
+ * same id for both families. The two roll different stats, in opposite directions:
+ *
+ * | On a sensor suite | On a utility scanner |
+ * | --- | --- |
+ * | Long Range: `Mass` ×1.20, `ScannerRange` +0…15% | Long Range: `PowerDraw` ×1.10, `ScannerRange` +0…24% |
+ * | Wide Angle: `PowerDraw` ×1.10, `ScannerRange` −4% | Wide Angle: `Mass` ×1.20, `ScannerTimeToScan` +10% |
+ *
+ * (Grade 1 shown; both pairs share their `SensorTargetScanAngle` leg.) `BLUEPRINTS` keys
+ * the scanner side under `Scanner_LongRange` / `Scanner_WideAngle`, which is the spelling
+ * the scanner menus list — so on a scanner this resolves `Sensor_LongRange` to
+ * `Scanner_LongRange`, and folding the id as written would charge the build mass where the
+ * game charges power draw.
+ *
+ * **One `BlueprintName`, two recipes — again, on the multi-cannons.** The game writes
+ * `Weapon_Overcharged` for every weapon's Overcharged, but a multi-cannon's also cuts the
+ * clip — 3% at grade 1 falling to 15% at grade 5 — which the recipe the other weapons take
+ * does not. `BLUEPRINTS` keys the multi-cannon side under `MC_Overcharged`, the spelling
+ * the multi-cannon menus list, so on a multi-cannon this resolves `Weapon_Overcharged` to
+ * `MC_Overcharged` and folding the id as written would report a clip the build does not
+ * have. This is the common case of the three: 70 of the build corpus's 1902 declared
+ * entries go through it, against one for the scanners.
+ *
+ * The clip penalty is folded on a multi-cannon — anti-xeno ones included — and on nothing
+ * else. The cannons, fragment cannons and plasma accelerators take no clip leg, which is
+ * the game's own answer on all three groups: journal captures of a large gimballed cannon
+ * at grade 5, of a medium fragment cannon at grade 4 and of a medium plasma accelerator at
+ * grade 1, each rolled under this id, report no `AmmoClipSize` modifier. See
+ * [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md)
+ * § "Multi-cannon Overcharged" for the captures.
+ *
+ * **The pairing is global, not repeated per menu.** A purpose-specific catalogue maps
+ * each of the three recipe ids to the colliding id the journal writes. This function
+ * supplies the half only a menu knows, by asking which mapped recipe *this module is
+ * offered*. Keeping one global map avoids repeating aliases on every scanner or
+ * multi-cannon group and silently forgetting the next one.
+ *
+ * Only the module can settle it, which is why this takes one. It resolves **into** a menu
+ * and never out of one: a sensor suite's `Sensor_LongRange` is already its own menu's id
+ * and comes back unchanged, and asking for `Scanner_LongRange` on a sensor suite returns
+ * it unchanged too — unchanged is not the same as offered, and `getBlueprintsForModule`
+ * still says a suite does not take it.
+ *
+ * **Only the numbers differ, not the price.** All three pairs cost the same materials at
+ * every grade, so `getBlueprintCost` from `ships/blueprint-costs` needs no module and
+ * either spelling bills correctly; cross-catalogue tests hold upstream to that. It is the
+ * stat block that has to be resolved.
+ *
+ * **Not a generic-spelling resolver.** A generic `Misc_*` id — `Misc_Shielded` where a
+ * life support's menu says `LifeSupport_Shielded` — comes back as it went in. That pair is
+ * one recipe under two spellings, both published with their own numbers, so the id a
+ * caller names is the one to roll. This function exists for the case where the id names no
+ * recipe the module has: the game never rolls a sensor suite's Long Range on a scanner.
+ *
+ * @param symbol - A module symbol, e.g. `"Hpt_CloudScanner_Size0_Class5"`.
+ * @param fdname - A blueprint catalogue or journal id, matched case-insensitively and
+ * trimmed. Colliding journal spellings are resolved against `symbol`.
+ * @returns The id to join to `BLUEPRINTS`, in that catalogue's spelling when a journal
+ * name resolved, and otherwise `fdname` exactly as it was passed — byte for byte, so a
+ * caller who never meets the collision never sees their own spelling rewritten.
+ *
+ * @throws {TypeError} If `fdname` is not a string, including when it is missing — this
+ * returns an id rather than reporting whether one is known, so there is no miss for a
+ * nullish one to be. A nullish `symbol` *is* a miss: an unknown module offers no menu,
+ * and `fdname` comes back unchanged.
+ * @example
+ * ```ts
+ * import { resolveBlueprintForModule } from '@elite-dangerous-almanac/core/ships/blueprint-journal';
+ *
+ * // A wake scanner's Long Range is the scanner recipe, whichever way the build spells it.
+ * resolveBlueprintForModule('Hpt_CloudScanner_Size0_Class5', 'Sensor_LongRange');
+ * // -> 'Scanner_LongRange'
+ * resolveBlueprintForModule('Hpt_CloudScanner_Size0_Class5', 'Scanner_LongRange');
+ * // -> 'Scanner_LongRange'
+ *
+ * // The sensor suite keeps its own, and every other module keeps whatever it was given.
+ * resolveBlueprintForModule('Int_Sensors_Size4_Class5', 'Sensor_LongRange');
+ * // -> 'Sensor_LongRange'
+ * resolveBlueprintForModule('Int_Hyperdrive_Size5_Class5', 'FSD_LongRange');
+ * // -> 'FSD_LongRange'
+ *
+ * // A multi-cannon's Overcharged is the multi-cannon recipe, clip penalty and all.
+ * resolveBlueprintForModule('Hpt_MultiCannon_Fixed_Medium', 'Weapon_Overcharged');
+ * // -> 'MC_Overcharged'
+ * resolveBlueprintForModule('Hpt_ATMultiCannon_Gimbal_Medium', 'Weapon_Overcharged');
+ * // -> 'MC_Overcharged'
+ * resolveBlueprintForModule('Hpt_BeamLaser_Fixed_Small', 'Weapon_Overcharged');
+ * // -> 'Weapon_Overcharged'
+ * ```
+ */
+declare function resolveBlueprintForModule(symbol: string, fdname: string): string;
+
+export { resolveBlueprintForModule };

package/dist/ships/blueprint-journal.js

@@ -0,0 +1 @@
+export{resolveBlueprintForModule}from"../chunk-L2ZZXEZM.js";                                                                                                                    //# sourceMappingURL=blueprint-journal.js.map

package/dist/ships/blueprint-journal.js.map

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

package/dist/ships/blueprints.d.ts

@@ -0,0 +1,103 @@
+import { Blueprint, BlueprintGrade } from './engineering.js';
+import './slef.js';
+import './modules.js';
+import './engineering-options.js';
+import './slots.js';
+
+/**
+ * The **blueprint mechanics catalogue** — every engineering blueprint's per-grade stat
+ * modifiers, keyed by the blueprint's Frontier `fdname`
+ * (as it appears in a journal `Loadout` event's `Engineering.BlueprintName`).
+ *
+ * Its own module (and data file) so consumers who never engineer a build do not bundle
+ * it. Each grade is a {@link BlueprintGrade} — its `features` (feed to
+ * {@link computeModifiers} from `./engineering`) and optional converted
+ * `damageDistribution`. Read it with {@link getBlueprintGrade}. Material shopping lists
+ * live separately in `ships/blueprint-costs`, so build calculations do not bundle them.
+ *
+ * Keys are Frontier `fdname`s — normally the exact strings a journal `Loadout` event
+ * carries in `Engineering.BlueprintName` (e.g. `"FSD_LongRange"`), not the in-game display
+ * names. **Three keys collide**: each is a recipe the game writes under an id another
+ * record already answers to:
+ * `Scanner_LongRange` and `Scanner_WideAngle` are coriolis keys for recipes the game writes
+ * as `Sensor_LongRange` / `Sensor_WideAngle`, the ids it also writes for the sensor suites'
+ * different recipes of the same name; `MC_Overcharged` is its multi-cannon Overcharged,
+ * which cuts the clip by 3–15% where the `Weapon_Overcharged` the game writes for both
+ * leaves it alone. `ships/blueprint-journal` keeps those three spellings apart from this
+ * full mechanics catalogue and resolves one against a module.
+ *
+ * A further 25 keys are the **Operations** ids: 21 recipes a module is *sold*
+ * carrying (`ships/pre-engineered`) and four Operations recipes a player rolls at an
+ * engineer (`ships/engineering-options`). No journal spelling has been observed for those
+ * Operations ids — a gap in the evidence, not a claim that the game writes none.
+ *
+ * **Every recipe is keyed once.** Anti-Guardian Zone Resistance is
+ * `GuardianModule_Sturdy`, the id the game writes on Guardian weapons as well as on
+ * Guardian modules; the Inara registry's `recipe_guardianmodule_sturdy` and
+ * `recipe_guardianweapon_sturdy` are that registry's own spellings of the same recipe and
+ * are not keys here.
+ * Enumerate the 107 blueprints with `Object.keys(BLUEPRINTS)`.
+ *
+ * Data from EDCD/coriolis-data (`modifications/blueprints.json`): `features` from the
+ * grade with journal Labels resolved via EDSY; see
+ * [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Every blueprint, keyed by Frontier `fdname` (e.g. `"FSD_LongRange"`). Each is a
+ * {@link Blueprint} — its display `name` and its per-grade `grades`, where each grade
+ * carries its `features` (modifiers) and optional converted `damageDistribution`.
+ *
+ * @example
+ * ```ts
+ * import { BLUEPRINTS } from '@elite-dangerous-almanac/core/ships/blueprints';
+ *
+ * BLUEPRINTS['FSD_LongRange']?.name;               // -> 'Increased range'
+ * BLUEPRINTS['FSD_LongRange']?.grades['5']?.features;  // -> [{ label: 'Integrity', ... }, ...]
+ * BLUEPRINTS['BeamLaser_ThermalPlasmaConversion']?.grades['5']?.damageDistribution;
+ * // -> { thermal: 0.845, absolute: 0.155 }
+ * ```
+ */
+declare const BLUEPRINTS: Readonly<Record<string, Blueprint>>;
+/**
+ * Look up a blueprint by its Frontier `fdname`, case-insensitively.
+ *
+ * @param fdname - The blueprint id, e.g. `"FSD_LongRange"`.
+ * @returns The blueprint (its `name` and `grades`), or `null` if this catalogue stores no
+ * blueprint under that id.
+ * @remarks
+ * **`null` is not always an unknown id.** The game writes a handful of cosmetic
+ * transformations in the same `BlueprintName` / `EngineerModifications` field, and they
+ * name no recipe — no grade, no materials, and no engineer who applies one.
+ * {@link isDecorativeModification} from `ships/decorative-modifications` is what tells one
+ * of those apart from an id this library has never heard of. Note that such an id is not a
+ * claim that the module is unmodified: read a fitted one's stats from the journal's own
+ * `Engineering.Modifiers`.
+ * @throws {TypeError} If `fdname` is present and not a string. A nullish
+ * `fdname` is a miss, answered the way an unrecognised one is.
+ */
+declare function getBlueprint(fdname: string): Blueprint | null;
+/**
+ * Look up one complete grade of a blueprint, case-insensitively.
+ *
+ * @param fdname - The blueprint id, e.g. `"FSD_LongRange"`.
+ * @param grade - The grade, `1`–`5`.
+ * @returns The grade record — its modifier `features` and optional converted
+ * `damageDistribution` — or `null` if the catalogue holds no such blueprint or grade.
+ * See {@link getBlueprint} for what an absent blueprint can mean besides "unknown".
+ * @throws {RangeError} If `grade` is not an integer from 1 through 5.
+ * @throws {TypeError} If `fdname` is present and not a string. A nullish
+ * `fdname` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getBlueprintGrade } from '@elite-dangerous-almanac/core/ships/blueprints';
+ *
+ * const grade = getBlueprintGrade('FSD_LongRange', 5);
+ * grade?.features;  // -> [{ label: 'Integrity', ... }, ...]
+ * ```
+ */
+declare function getBlueprintGrade(fdname: string, grade: number): BlueprintGrade | null;
+
+export { BLUEPRINTS, getBlueprint, getBlueprintGrade };

package/dist/ships/blueprints.js

@@ -0,0 +1 @@
+export{BLUEPRINTS,getBlueprint,getBlueprintGrade}from"../chunk-Q5MR36RW.js";                                                                                       //# sourceMappingURL=blueprints.js.map

package/dist/ships/blueprints.js.map

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

package/dist/ships/decorative-modifications.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The **decorative modification catalogue** — the festive transformations the game
+ * records in the same field as an engineering blueprint, keyed by the Frontier `fdname`
+ * a journal writes (`EngineerModifications` on a `StoredModules` entry,
+ * `Engineering.BlueprintName` on a `Loadout` module).
+ *
+ * **Not engineering.** A decorative modification has no grade, costs no materials, and no
+ * engineer offers one. So these ids are **not** in {@link BLUEPRINTS} — there is no recipe
+ * to store — and no menu in `ships/engineering-options` lists one, because that catalogue
+ * answers what a player may apply. This module is what makes the id resolve to something
+ * rather than to nothing.
+ *
+ * **Not cosmetic-only, either.** A festive launcher fires fireworks rather than flak, and
+ * the transformation cuts the module's `Damage` by 99% to match — the one stat any of them
+ * moves, carried in {@link DecorativeModification.modifiers}. So a record here is never a
+ * claim that the module is unmodified. Feed the modifiers to {@link computeModifiers} to
+ * resolve a fitted launcher, the same way a pre-engineered variant's are resolved.
+ *
+ * Resolving the id is the whole of its job, and it is why it is worth having. A consumer
+ * reading a real journal meets `Decorative_Green` on a stored module and needs to tell "an
+ * id this library has never heard of" from "an id that is real and names no recipe"; only
+ * the second is true here. {@link ShipLoadout.applyBlueprint} reads it for the same
+ * reason: it refuses a decorative id, but refuses it by name.
+ *
+ * Three modifications are known — `Decorative_Green`, `Decorative_Red` and
+ * `Decorative_Yellow` — and one module is observed carrying them, the medium turreted
+ * Remote Release Flak Launcher (`Hpt_FlakMortar_Turret_Medium`). Enumerate them with
+ * `Object.keys(DECORATIVE_MODIFICATIONS)`.
+ *
+ * Its own module (and data file), a few hundred bytes, so nothing else has to grow to
+ * hold three records that belong to none of it.
+ *
+ * Ids and the module they sit on from a `StoredModules` capture contributed by the
+ * repository owner, the `Damage` cut from the same contributor's outfitting panel; EDSY
+ * lists the same three transformations and gives them no modifiers, which the cut shows to
+ * be an incomplete record. See
+ * [`data/ships/SOURCES.md`](https://github.com/DarkSession/Elite-Dangerous-Almanac/blob/main/data/ships/SOURCES.md).
+ *
+ * @packageDocumentation
+ */
+/**
+ * One hand-set stat change a decorative modification arrives with.
+ *
+ * Deliberately the same shape as {@link PreEngineeredModifier}, and for the same reason: a
+ * transformation that arrives on the module is a fixed article, not a roll, so there is no
+ * `min`/`max` to bound it. The two are kept as separate types because a festive launcher is
+ * not a pre-engineered purchase — but anything that handles one handles the other, and
+ * {@link computeModifiers} takes both once each value is read as its own `min` and `max`.
+ */
+interface DecorativeModifier {
+    /** Journal Modifier Label, e.g. `"Damage"`. */
+    readonly label: string;
+    /** How the value applies to the base stat. */
+    readonly method: 'multiplicative' | 'additive' | 'overwrite';
+    /**
+     * The modifier value: a fraction for `multiplicative` (`-0.99` is `−99%`), an absolute
+     * delta for `additive`, and the replacement value for `overwrite`.
+     */
+    readonly value: number;
+}
+/** One festive transformation a module can carry in place of engineering. */
+interface DecorativeModification {
+    /**
+     * The festive naming paired with the colour the id spells, e.g. `"Festive Green"`. No
+     * registry publishes the outfitting panel's own string for these, so this is what the
+     * transformation is known as rather than a sourced label.
+     */
+    readonly name: string;
+    /**
+     * Every module symbol observed carrying this transformation, e.g.
+     * `["Hpt_FlakMortar_Turret_Medium"]`. Joins to the module catalogues.
+     *
+     * This is what has been **seen**, not what the game permits: the list comes from a
+     * journal capture, so a module absent from it is one no capture has shown carrying
+     * the transformation.
+     */
+    readonly modules: readonly string[];
+    /**
+     * The stat changes the transformation arrives with — for every one of these, a single
+     * `Damage` cut of −99%, which is what turns a flak launcher into a firework launcher.
+     *
+     * Never empty: a decorative modification names no engineering *recipe*, but it is not
+     * inert, and reading it as cosmetic-only would overstate a fitted launcher's damage a
+     * hundredfold.
+     *
+     * @example
+     * ```ts
+     * import { DECORATIVE_MODIFICATIONS } from '@elite-dangerous-almanac/core/ships/decorative-modifications';
+     *
+     * DECORATIVE_MODIFICATIONS['Decorative_Green']?.modifiers;
+     * // -> [{ label: 'Damage', method: 'multiplicative', value: -0.99 }]
+     * // on the medium turreted launcher: 34 damage -> 0.34, 0.17 DPS
+     * ```
+     */
+    readonly modifiers: readonly DecorativeModifier[];
+}
+/**
+ * Every decorative modification, keyed by Frontier `fdname` (e.g. `"Decorative_Green"`).
+ *
+ * @example
+ * ```ts
+ * import { DECORATIVE_MODIFICATIONS } from '@elite-dangerous-almanac/core/ships/decorative-modifications';
+ *
+ * Object.keys(DECORATIVE_MODIFICATIONS);
+ * // -> ['Decorative_Green', 'Decorative_Red', 'Decorative_Yellow']
+ * DECORATIVE_MODIFICATIONS['Decorative_Green']?.modules;
+ * // -> ['Hpt_FlakMortar_Turret_Medium']
+ * DECORATIVE_MODIFICATIONS['Decorative_Green']?.modifiers;
+ * // -> [{ label: 'Damage', method: 'multiplicative', value: -0.99 }]
+ * ```
+ */
+declare const DECORATIVE_MODIFICATIONS: Readonly<Record<string, DecorativeModification>>;
+/**
+ * Look up a decorative modification by its Frontier `fdname`, case-insensitively.
+ *
+ * @param fdname - The modification id, e.g. `"Decorative_Green"`.
+ * @returns The modification — its `name`, the `modules` observed carrying it and the
+ * `modifiers` it arrives with — or `null` if the id is not a decorative modification.
+ * @throws {TypeError} If `fdname` is present and not a string. A nullish
+ * `fdname` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { getDecorativeModification } from '@elite-dangerous-almanac/core/ships/decorative-modifications';
+ *
+ * getDecorativeModification('decorative_red')?.name; // -> 'Festive Red'
+ * getDecorativeModification('FSD_LongRange');        // -> null
+ * ```
+ */
+declare function getDecorativeModification(fdname: string): DecorativeModification | null;
+/**
+ * Whether an id names a decorative modification rather than an engineering blueprint.
+ *
+ * The question to ask of a journal `EngineerModifications` / `BlueprintName` value that
+ * {@link getBlueprint} answered `null` for: `true` means the id is real and names no
+ * recipe, and only a `false` here leaves "this library does not know the id" as the
+ * remaining reading. It does **not** mean the module is unmodified — read
+ * {@link DecorativeModification.modifiers} for what it does change.
+ *
+ * @param fdname - The id to test, matched case-insensitively and trimmed.
+ * @returns `true` when {@link getDecorativeModification} would find it.
+ * @throws {TypeError} If `fdname` is present and not a string. A nullish
+ * `fdname` is a miss, answered the way an unrecognised one is.
+ * @example
+ * ```ts
+ * import { isDecorativeModification } from '@elite-dangerous-almanac/core/ships/decorative-modifications';
+ *
+ * isDecorativeModification('Decorative_Yellow'); // -> true
+ * isDecorativeModification('Weapon_Efficient');  // -> false
+ * ```
+ */
+declare function isDecorativeModification(fdname: string): boolean;
+/**
+ * Every decorative modification a module has been observed carrying.
+ *
+ * Matching is case-insensitive and trims whitespace, so a raw journal value can be passed
+ * straight in. A module no capture shows carrying one yields an empty array, never
+ * `null`, so the result is always safe to iterate — and an empty answer is "none seen on
+ * this module", not "this module cannot have one".
+ *
+ * @param symbol - A module symbol, e.g. `"Hpt_FlakMortar_Turret_Medium"`.
+ * @returns The modification ids, in catalogue order. Join to
+ * {@link DECORATIVE_MODIFICATIONS}.
+ * @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 { getDecorativeModificationsForModule } from '@elite-dangerous-almanac/core/ships/decorative-modifications';
+ *
+ * getDecorativeModificationsForModule('Hpt_FlakMortar_Turret_Medium');
+ * // -> ['Decorative_Green', 'Decorative_Red', 'Decorative_Yellow']
+ * getDecorativeModificationsForModule('Hpt_BeamLaser_Fixed_Small'); // -> []
+ * ```
+ */
+declare function getDecorativeModificationsForModule(symbol: string): readonly string[];
+
+export { DECORATIVE_MODIFICATIONS, type DecorativeModification, type DecorativeModifier, getDecorativeModification, getDecorativeModificationsForModule, isDecorativeModification };

package/dist/ships/decorative-modifications.js

@@ -0,0 +1 @@
+export{DECORATIVE_MODIFICATIONS,getDecorativeModification,getDecorativeModificationsForModule,isDecorativeModification}from"../chunk-6LUEKHO5.js";                                                                                       //# sourceMappingURL=decorative-modifications.js.map

package/dist/ships/decorative-modifications.js.map

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