ships.Class.BuildMetrics

@elite-dangerous-almanac/core / ships / BuildMetrics

Class: BuildMetrics

Defined in: src/ships/build-metrics.ts:425

Every figure a fitted build can be asked for.

Member index

• Attach — of.
• Jump — frameShiftDrive, frameShiftDriveMassFactor, maxJumpRange, jumpRange, ladenJumpRange, fuelPerJump, totalRange, jumpRangeSummary, standardLoad, standardLoadResult.
• Mass and cost — buildMass, buildCost.
• Power and heat — powerBudget, heatMetrics, heatMetricsResult.
• Mobility — thrusters, mobilityMetrics, mobilityMetricsResult, mobilityCapacitorMetrics, mobilityCapacitorMetricsResult.
• Defence — armourMetrics, shieldMetrics, shieldMetricsResult, shieldCapacitorMetrics, shieldCapacitorMetricsResult, shieldRecovery, shieldRecoveryResult, cellBanks.
• Offence — weaponMetrics, weaponsCapacitorMetrics, distributorMetrics, distributorMetricsResult.

Every member is a method. Nothing here is a fact the fit already carries — each one computes from build state — so there are no properties to confuse with them.

Methods

armourMetrics()

armourMetrics(): ArmourMetrics

Defined in: src/ships/build-metrics.ts:1261

The build's armour: hull hit points, the bulkhead and reinforcement each contribute, and the effective resistances.

Returns

ArmourMetrics

The ArmourMetrics, read off the fitted bulkhead.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const hull = metrics.armourMetrics();
hull.hitPoints; // -> total hull points
hull.resistances.explosive; // -> lightweight alloy is explosively weak
hull.effectiveHitPoints.thermal; // -> thermal damage the hull can soak

---

buildCost()

buildCost(): BuildCost

Defined in: src/ships/build-metrics.ts:812

Price the whole build from the catalogues: shop credits, Merc Coin and the engineering materials its modifications consume.

No modification is charged twice. A Mercenary article arrives at the grade it was sold at, so only the climb above that grade bills materials and further Merc Coin, and an experimental effect the article came with is free while one added on top is not. A fixed reward article — festive, Guardian, community-goal — identifies a recipe it was never rolled from, so it contributes no materials at all.

Returns

BuildCost

A frozen BuildCost. credits.modules, credits.total and credits.rebuy are lower bounds while BuildCredits.unpriced is non-empty; built-in hull fittings are free rather than unpriced.

Remarks

This is the one place the build metrics read the material and Merc Coin cost catalogues; import getBlueprintCost and getExperimentalEffectCost directly to price one recipe without a build.

Examples

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const build = ShipLoadout.default('Anaconda');
BuildMetrics.of(build).buildCost().credits.hull; // -> 142456440
build.applyBlueprint('FrameShiftDrive', 'FSD_LongRange', { grade: 5 });
BuildMetrics.of(build)
    .buildCost()
    .materials.find((material) => material.symbol === 'Arsenic')?.count; // -> 5

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { getPreEngineeredVariants } from '@elite-dangerous-almanac/core/ships/pre-engineered';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const variant = getPreEngineeredVariants('Hpt_Railgun_Fixed_Medium')
    .find((candidate) => candidate.acquisition === 'mercenary')!;
const build = ShipLoadout.default('Python')
    .setPreEngineeredVariant('MediumHardpoint1', variant);
BuildMetrics.of(build).buildCost().mercCoins; // -> 950

---

buildMass()

buildMass(options?): BuildMass

Defined in: src/ships/build-metrics.ts:753

Weigh the whole build: the hull, the fitted modules, and the load on top of them.

Parameters

options?

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank and cargo to 0, matching jumpRange and mobilityMetrics. Pass standardLoad to weigh one of the standard loads.

Returns

BuildMass

A frozen BuildMass, every figure in tonnes.

Remarks

The mass companion to buildCost, answering the same question in tonnes that that one answers in credits. Every module's mass is post-engineering, so a Lightweight roll is already in modules.

The reserve tank is not counted. The main tank is the fuel the drive and the flight model see, and it is what jumpRange and mobilityMetrics weigh; the game's statistics panel additionally counts the reserve in the current mass it displays, so add fuelCapacity.reserve to reproduce that reading.

Throws

If fuel or cargo is not finite and non-negative.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const build = ShipLoadout.default('Anaconda');
const mass = BuildMetrics.of(build).buildMass();
mass.hull; // -> 400
mass.modules; // -> 664
mass.total; // -> 1096, a full main tank and an empty hold
BuildMetrics.of(build).buildMass({ cargo: build.cargoCapacity }).total; // -> 1210

---

cellBanks()

cellBanks(): CellBankSummary

Defined in: src/ships/build-metrics.ts:1234

Every fitted shield cell bank and the usable rearmed reinforcement pool.

Every fitted bank remains in banks, where powered says whether it is switched on and its priority group is fed with hardpoints deployed. The totals include only those powered banks, so a build whose plant is switched off or outdrawn reports every bank unpowered and zero totals.

Returns

CellBankSummary

A frozen CellBankSummary; no banks is an empty list and zero totals.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.cellBanks().totalRestorable; // -> MJ across every powered fitted cell

---

distributorMetrics()

distributorMetrics(options?): DistributorMetrics | null

Defined in: src/ships/build-metrics.ts:1388

All three power-distributor capacitors at selected pip allocations.

Parameters

options?

DistributorOptions = {}

SYS, ENG and WEP pips in [0, 4], each defaulting independently to 4. The allocations need not sum to six, which permits independent comparisons of the three maxima.

Returns

DistributorMetrics | null

Capacity, rated four-pip recharge and actual pip-scaled recharge for SYS, ENG and WEP, or null when the distributor is not fitted, switched off, shed by the retracted power budget, or its six capacitor stats cannot be resolved. Use distributorMetricsResult to distinguish those four. That retracted state represents the distributor itself; firing endurance in weaponsCapacitorMetrics separately applies the deployed state.

Throws

If any pip allocation is outside [0, 4] or not finite.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const distributor = metrics.distributorMetrics({
    systemsPips: 2,
    enginesPips: 2,
    weaponsPips: 2,
});
distributor?.engines.rechargeRate; // MJ/s

---

distributorMetricsResult()

distributorMetricsResult(options?): CalculationResult<DistributorMetrics>

Defined in: src/ships/build-metrics.ts:1412

The build's distributor with a diagnostic when it is unavailable.

Parameters

options?

DistributorOptions = {}

SYS, ENG and WEP pips in [0, 4], each defaulting to 4.

Returns

CalculationResult<DistributorMetrics>

A complete DistributorMetrics value, otherwise null plus the fitted distributor's state: missing when none is fitted, disabled when it is switched off, shed when the retracted power budget does not feed it, and unresolved when its record does not state all six capacitor figures.

Throws

If any pip allocation is outside [0, 4] or not finite.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const build = ShipLoadout.default('Anaconda').setModuleEnabled('PowerDistributor', false);
const result = BuildMetrics.of(build).distributorMetricsResult();
result.complete; // -> false
result.issues[0]?.reason; // -> 'disabled'

---

frameShiftDrive()

frameShiftDrive(): FrameShiftDriveParams

Defined in: src/ships/build-metrics.ts:476

The resolved frame-shift-drive constants for this build — post-engineering, with any Guardian FSD Booster folded into jumpBoost.

Returns

FrameShiftDriveParams

The drive's constants.

Throws

If no frame shift drive is fitted, or the fitted drive's record is missing any of its required jump constants.

---

frameShiftDriveMassFactor()

frameShiftDriveMassFactor(options?): number

Defined in: src/ships/build-metrics.ts:541

The fitted frame shift drive's dimensionless mass factor at a chosen load.

Parameters

options?

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank and cargo to 0.

Returns

number

optMass / loadedMass: 1 at the drive's optimised mass, below 1 above it and above 1 below it.

Remarks

This is the mass term used by the jump equation, not the three-point performance curve used by thrusters and shield generators. Main-tank fuel contributes to the loaded mass; the Guardian FSD Booster's additive range does not contribute to the factor.

Throws

If the build has no usable frame shift drive.

Throws

If fuel or cargo is not finite and non-negative, or loaded mass is zero.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.frameShiftDriveMassFactor({ fuel: 8, cargo: 32 }); // dimensionless

---

fuelPerJump()

fuelPerJump(distance, options?): number

Defined in: src/ships/build-metrics.ts:602

The fuel a single jump of a given distance costs, in tonnes.

Parameters

distance

number

The jump distance, in light-years.

options?

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank, cargo to 0.

Returns

number

Fuel used, in tonnes (capped at the drive's max fuel per jump).

Throws

If the build has no usable frame shift drive.

Throws

If fuel or cargo is not finite and non-negative.

---

heatMetrics()

heatMetrics(): HeatMetrics | null

Defined in: src/ships/build-metrics.ts:922

The build's heat: what it idles at, what it runs at flying and jumping, and whether firing everything cooks it.

Every figure is post-engineering. The heat a build makes follows what the plant actually feeds, so a module switched off — or one in a priority group the plant cannot keep lit — contributes nothing.

Returns

HeatMetrics | null

The HeatMetrics, or null when the build has no powered power plant whose heat efficiency it can read. Use heatMetricsResult to distinguish the unavailable conditions.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const heat = metrics.heatMetrics();
heat?.idle.gauge; // -> 0.23, i.e. the gauge reads 23%
heat?.firingSustained.overheats; // -> false: the guns run cool enough to hold
heat?.firingDrained.secondsToOverheat; // -> how long an alpha strike has on an empty WEP

---

heatMetricsResult()

heatMetricsResult(): CalculationResult<HeatMetrics>

Defined in: src/ships/build-metrics.ts:942

The build's heat with a diagnostic when its power plant is unavailable.

Returns

CalculationResult<HeatMetrics>

A complete HeatMetrics value, otherwise null plus the fitted power plant's state: missing when none is fitted, disabled when it is switched off, and unresolved when its record does not state a heat efficiency.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const result = metrics.heatMetricsResult();
if (result.complete) result.value.idle.gauge; // 0 to 1
else result.issues[0].reason; // unavailable-state discriminator

---

jumpRange()

jumpRange(options?): number

Defined in: src/ships/build-metrics.ts:573

The range of a single jump for a chosen fuel and cargo load, in light-years.

Parameters

options?

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank, cargo to 0.

Returns

number

The jump's range, in light-years.

Throws

If the build has no usable frame shift drive.

Throws

If fuel or cargo is not finite and non-negative.

---

jumpRangeSummary()

jumpRangeSummary(): JumpRangeSummary

Defined in: src/ships/build-metrics.ts:706

Every jump figure at once — best, unladen, laden, and each load's total.

Returns

JumpRangeSummary

The JumpRangeSummary. Single-jump figures and each total's range are in light-years. For a partial load, call jumpRange for one jump or totalRange for every jump with the fuel and cargo you actually have.

Throws

If the build has no usable frame shift drive.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const jumps = metrics.jumpRangeSummary();
jumps.max; // -> 89.41  (one jump's fuel, empty hold)
jumps.laden; // -> the range with the hold full
jumps.totalMax.jumps; // the best jump expressed as a total

---

ladenJumpRange()

ladenJumpRange(): number

Defined in: src/ships/build-metrics.ts:588

Single-jump range on a full tank with a full cargo hold, in light-years.

Returns

number

The jump's range, in light-years.

Throws

If the build has no usable frame shift drive.

---

loadout()

loadout(): ShipLoadout

Defined in: src/ships/build-metrics.ts:464

The build this view reads.

Returns

ShipLoadout

The same ShipLoadout that was passed to of — the aggregate figures, the slots and the editors are all on it.

---

maxJumpRange()

maxJumpRange(): number

Defined in: src/ships/build-metrics.ts:559

Best single-jump range, in light-years — no cargo, and exactly one jump's fuel aboard (the lightest the ship jumps). This is the figure the game and EDSY label "maximum jump range".

Returns

number

The best single jump, in light-years, or 0 for a capture that states a main tank of 0.

Throws

If the build has no usable frame shift drive.

---

mobilityCapacitorMetrics()

mobilityCapacitorMetrics(options?): MobilityCapacitorMetrics | null

Defined in: src/ships/build-metrics.ts:1028

The build's speed and rotation rates at a chosen load and ENG-pip allocation.

Boost is not here: it does not move with the allocation, so it stays on mobilityMetrics beside the loaded mass and the two curve multipliers these figures share.

Parameters

options?

MobilityCapacitorOptions = {}

MobilityCapacitorOptions. Fuel defaults to a full main tank, cargo to 0, and enginesPips to 4 — which reproduces mobilityMetrics exactly.

Returns

MobilityCapacitorMetrics | null

The MobilityCapacitorMetrics, or null when no fully described thrusters are powered with hardpoints retracted. Use mobilityCapacitorMetricsResult to distinguish the unavailable conditions.

Throws

If fuel or cargo is not finite and non-negative, or enginesPips is outside [0, 4].

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const metrics = BuildMetrics.of(ShipLoadout.default('SideWinder'));
metrics.mobilityCapacitorMetrics({ enginesPips: 0 })?.enginesPips; // -> 0

---

mobilityCapacitorMetricsResult()

mobilityCapacitorMetricsResult(options?): CalculationResult<MobilityCapacitorMetrics>

Defined in: src/ships/build-metrics.ts:1054

The build's ENG capacitor with a diagnostic when its thrusters or retracted power supply is unavailable.

Parameters

options?

MobilityCapacitorOptions = {}

MobilityCapacitorOptions.

Returns

CalculationResult<MobilityCapacitorMetrics>

A complete MobilityCapacitorMetrics value, otherwise null plus the input or fitted-module state that prevented the calculation — the same diagnostics mobilityMetricsResult reports, since the two read one build.

Throws

If fuel or cargo is not finite and non-negative, or enginesPips is outside [0, 4].

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const grounded = ShipLoadout.default('SideWinder').setModuleEnabled('MainEngines', false);
const result = BuildMetrics.of(grounded).mobilityCapacitorMetricsResult();
result.issues[0]?.reason; // -> 'disabled'

---

mobilityMetrics()

mobilityMetrics(options?): MobilityMetrics | null

Defined in: src/ships/build-metrics.ts:978

The build's speed, boost and rotation rates at a chosen load and full ENG.

Parameters

options?

JumpOptions = {}

Fuel defaults to a full main tank and cargo to 0.

Returns

MobilityMetrics | null

Loaded MobilityMetrics, or null when no fully described thrusters are powered with hardpoints retracted. Use mobilityMetricsResult to distinguish the unavailable conditions.

Remarks

Main-tank fuel contributes to the flight model's loaded mass. Reserve-tank fuel does not: although the statistics panel includes it in the displayed current mass, ten observed builds reproduce their angular rates only when the reserve is excluded from the thruster mass curve.

These are the four-ENG-pip figures. A lower allocation is mobilityCapacitorMetrics, which owns the pip story the way weaponsCapacitorMetrics owns WEP's.

Throws

If fuel or cargo is not finite and non-negative.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.mobilityMetrics({ cargo: 32, fuel: 8 })?.speed; // -> m/s at four ENG pips

---

mobilityMetricsResult()

mobilityMetricsResult(options?): CalculationResult<MobilityMetrics>

Defined in: src/ships/build-metrics.ts:1000

The build's mobility with a diagnostic when its thrusters or retracted power supply is unavailable.

Parameters

options?

JumpOptions = {}

Fuel defaults to a full main tank and cargo to 0.

Returns

CalculationResult<MobilityMetrics>

A complete MobilityMetrics value, otherwise null plus the input or fitted-module state that prevented the calculation.

Throws

If fuel or cargo is not finite and non-negative.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const result = metrics.mobilityMetricsResult();
if (result.complete) result.value.speed; // metres per second
else result.issues[0].reason; // unavailable-state discriminator

---

powerBudget()

powerBudget(): PowerBudget

Defined in: src/ships/build-metrics.ts:889

The build's power budget: what the plant makes, what the modules draw with hardpoints retracted and deployed, and which priority groups stay lit.

Draws are post-engineering, modules switched off in the journal are skipped, and weapons (plus the utility fittings that are not always powered) count only towards the deployed total.

Returns

PowerBudget

The PowerBudget. consumers includes modules with positive draw; passive and zero-draw fittings are absent.

Throws

If a power capacity or module draw is negative or not finite.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const power = metrics.powerBudget();
power.available; // -> 20.4 MW generated
power.deployed; // -> 19.02 MW drawn, hardpoints out
power.withinBudget; // -> true
power.bands[4]?.poweredDeployed; // -> is priority group 5 still lit?

---

shieldCapacitorMetrics()

shieldCapacitorMetrics(options?): ShieldCapacitorMetrics | null

Defined in: src/ships/build-metrics.ts:1141

The build's SYS capacitor: what the pips hold and recharge, the resistance they add, and what the shields are worth with them folded in.

The effective resistances and hit points here are the ones the game's own panel shows while the allocation stands; shieldMetrics is the bare shield they are built from. Both come from one pass over the build, so a screen showing them side by side need not compute the shield twice.

Parameters

options?

ShieldCapacitorOptions = {}

ShieldCapacitorOptions. systemsPips (0–4) defaults to 4; at 0 the effective figures equal shieldMetrics.

Returns

ShieldCapacitorMetrics | null

The ShieldCapacitorMetrics, or null when the build has no shield generator powered with hardpoints retracted, or a fitted distributor does not state its SYS figures. Use shieldCapacitorMetricsResult to distinguish the unavailable conditions. With no distributor fitted, capacity and recharge are zero — the modelled truth for a build that has no SYS capacitor at all.

Throws

If systemsPips is outside [0, 4] or not finite.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const metrics = BuildMetrics.of(ShipLoadout.default('SideWinder'));
const sys = metrics.shieldCapacitorMetrics({ systemsPips: 4 });
sys?.systemsResistance; // -> 0.6
// Effective hit points behind those pips, against the shield's weakest type.
(sys?.effectiveHitPoints.thermal ?? 0) > (metrics.shieldMetrics()?.strength ?? 0); // -> true

---

shieldCapacitorMetricsResult()

shieldCapacitorMetricsResult(options?): CalculationResult<ShieldCapacitorMetrics>

Defined in: src/ships/build-metrics.ts:1166

The build's SYS capacitor with a diagnostic when its generator, retracted power supply or distributor record is unavailable.

Parameters

options?

ShieldCapacitorOptions = {}

ShieldCapacitorOptions. systemsPips defaults to 4.

Returns

CalculationResult<ShieldCapacitorMetrics>

A complete ShieldCapacitorMetrics value, otherwise null plus the input or fitted-module state that prevented the calculation: the shield diagnostics shieldMetricsResult reports, plus powerDistributor/unresolved for a fitted distributor whose record does not state its SYS capacity or recharge.

Throws

If systemsPips is outside [0, 4] or not finite.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const unshielded = ShipLoadout.default('SideWinder').removeModule('Slot01_Size2');
const result = BuildMetrics.of(unshielded).shieldCapacitorMetricsResult();
result.issues[0]?.reason; // -> 'missing'

---

shieldMetrics()

shieldMetrics(): ShieldMetrics | null

Defined in: src/ships/build-metrics.ts:1088

The build's shields: strength in megajoules, where it comes from, and the effective resistances.

Shield strength scales with the hull's mass, not the build's, so fitting more modules never weakens it. Boosters, Guardian shield reinforcement and any engineering are all folded in; switched-off or shed boosters and reinforcement are ignored, while a switched-off or shed generator makes the metric unavailable.

These are the pip-free figures, which is what an outfitting screen shows. What the SYS capacitor makes of them is shieldCapacitorMetrics, which owns the pip story the way weaponsCapacitorMetrics owns WEP's.

Returns

ShieldMetrics | null

The ShieldMetrics, or null when the build has no shield generator powered with hardpoints retracted. Use shieldMetricsResult to distinguish the unavailable conditions.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const shields = metrics.shieldMetrics();
shields?.strength; // -> MJ
shields?.resistances.thermal; // -> negative on a stock generator
metrics.shieldCapacitorMetrics()?.effectiveResistances.thermal; // -> with 4 pips to SYS

---

shieldMetricsResult()

shieldMetricsResult(): CalculationResult<ShieldMetrics>

Defined in: src/ships/build-metrics.ts:1108

The build's shields with a diagnostic when its hull, generator or retracted power supply is unavailable.

Returns

CalculationResult<ShieldMetrics>

A complete ShieldMetrics value, otherwise null plus the input or fitted-module state that prevented the calculation.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const result = metrics.shieldMetricsResult();
if (result.complete) result.value.strength; // megajoules
else result.issues[0].reason; // unavailable-state discriminator

---

shieldRecovery()

shieldRecovery(options?): ShieldRecovery | null

Defined in: src/ships/build-metrics.ts:1190

Time for this build's shield to rise after collapse and then regenerate to full.

Parameters

options?

ShieldRecoveryOptions = {}

ShieldRecoveryOptions. SYS pips in [0, 4], defaulting to 4 — not the 0 shieldMetrics defaults to.

Returns

ShieldRecovery | null

Recovery rates and seconds, or null when no shield generator is powered with hardpoints retracted. Use shieldRecoveryResult to distinguish the unavailable conditions. Insufficient zero-pip recharge produces Infinity.

Throws

If systemsPips is outside [0, 4] or not finite.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.shieldRecovery({ systemsPips: 4 })?.recoveryTime; // -> seconds from collapse to 50%

---

shieldRecoveryResult()

shieldRecoveryResult(options?): CalculationResult<ShieldRecovery>

Defined in: src/ships/build-metrics.ts:1213

The build's shield recovery with a diagnostic when its hull, generator or retracted power supply is unavailable.

Parameters

options?

ShieldRecoveryOptions = {}

ShieldRecoveryOptions. SYS pips in [0, 4], defaulting to 4.

Returns

CalculationResult<ShieldRecovery>

A complete ShieldRecovery value, otherwise null plus the input or fitted-module state that prevented the calculation.

Throws

If systemsPips is outside [0, 4] or not finite.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const result = metrics.shieldRecoveryResult();
if (result.complete) result.value.recoveryTime; // seconds
else result.issues[0].reason; // unavailable-state discriminator

---

standardLoad()

standardLoad(load): StandardLoadInputs | null

Defined in: src/ships/build-metrics.ts:659

One of the package's standard load conditions, or null when the fitted drive cannot support it.

Parameters

load

StandardLoad

'maximum' for one jump's fuel and no cargo, 'unladen' for a full main tank and no cargo, or 'laden' for a full main tank and full hold.

Returns

StandardLoadInputs | null

The fuel and cargo carried and the StandardLoadInputs.mass, or null. Only 'maximum' can answer null: it validates the whole fitted drive, jump booster included, so a non-null one can be passed straight to jumpRange. Use standardLoadResult to learn why it is unavailable.

Throws

If load is not a recognised standard load.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const metrics = BuildMetrics.of(ShipLoadout.default('Anaconda'));
metrics.standardLoad('laden')?.mass; // -> 1210, tonnes with a full tank and hold

---

standardLoadResult()

standardLoadResult(load): CalculationResult<StandardLoadInputs>

Defined in: src/ships/build-metrics.ts:682

Resolve one of the package's standard load conditions for jump and mobility views.

Parameters

load

StandardLoad

'maximum' for one jump's fuel and no cargo, 'unladen' for a full main tank and no cargo, or 'laden' for a full main tank and full hold.

Returns

CalculationResult<StandardLoadInputs>

The fuel and cargo carried, and the StandardLoadInputs.mass the ship weighs carrying them, all in tonnes. Only 'maximum' can come back incomplete: it validates the whole fitted drive, jump booster included, so a complete one can be passed straight to jumpRange.

Throws

If load is not a recognised standard load.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
const load = metrics.standardLoadResult('maximum');
if (load.complete) metrics.mobilityCapacitorMetrics({ ...load.value, enginesPips: 2 });

---

thrusters()

thrusters(): ThrusterParams | null

Defined in: src/ships/build-metrics.ts:514

The fitted thrusters' post-engineering mass curve, or null when the build has none — the thruster counterpart of frameShiftDrive.

Returns

ThrusterParams | null

Remarks

A ThrusterParams carries the three masses the curve is defined over and the multiplier at each, plus the separate speedCurve and rotationCurve an enhanced-performance thruster refines them with. Pass it straight to thrusterMassCurveMultiplier for the multiplier at a mass of your own, or read optMass and maxMass against loadedMass for where this build sits on the curve.

This is the fitted article's curve, so a switched-off or shed thruster still has one; mobilityMetricsResult is what judges whether the build can use it. It answers null rather than throwing — unlike frameShiftDrive, which the jump equation cannot do without — when no thrusters are fitted or the fitted record carries no complete curve.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const metrics = BuildMetrics.of(ShipLoadout.default('Anaconda'));
metrics.thrusters()?.optMass; // -> 1440, tonnes
metrics.thrusters()?.maxMass; // -> 2160, past which the ship does not move at all

---

totalRange()

totalRange(options?): TotalRangeDetails

Defined in: src/ships/build-metrics.ts:630

Total range and jump count for a chosen fuel and cargo load.

Parameters

options?

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank, cargo to 0.

Returns

TotalRangeDetails

Summed range in light-years and the jumps made before the tank is empty.

Throws

If the build has no usable frame shift drive.

Throws

If fuel or cargo is not finite and non-negative, or the fuel load would require more than 100,000 jumps.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.totalRange().jumps; // jumps available from one full main tank
metrics.totalRange({ fuel: 8, cargo: 32 }).range; // range for that partial load

---

weaponMetrics()

weaponMetrics(): BuildWeaponMetrics

Defined in: src/ships/build-metrics.ts:1292

The build's firepower: DPS, sustained DPS, weapons-capacitor draw, heat and power draw for every fitted weapon, plus the totals.

Every figure is post-engineering. A weapon switched off in the journal is still listed — with its own metrics — but left out of the totals.

Returns

BuildWeaponMetrics

The BuildWeaponMetrics.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;

const guns = metrics.weaponMetrics();
guns.total.damagePerSecond; // -> burst DPS across the hardpoints
guns.total.sustainedDamagePerSecond; // -> with reloads folded in
guns.total.energyPerSecond; // -> MW asked of the WEP capacitor
guns.total.powerDraw; // -> MW asked of the power plant when deployed
guns.weapons[0]?.metrics.damageByType.thermal;
guns.weapons[0]?.maximumRange; // post-engineering metres, when known
guns.weapons[0]?.armourPiercing; // post-engineering rating, when known
guns.weapons[0]?.ammunition?.total; // -> rounds aboard when fully rearmed

---

weaponsCapacitorMetrics()

weaponsCapacitorMetrics(options?): WeaponsCapacitorMetrics

Defined in: src/ships/build-metrics.ts:1346

WEP-capacitor recharge and endurance while every powered weapon fires.

Parameters

options?

WeaponsOptions = {}

WEP pips in [0, 4], defaulting to 4.

Returns

WeaponsCapacitorMetrics

Actual recharge, sustained draw, net drain and seconds from full to empty. The deployed power budget is applied to the distributor and weapons, so a module the plant sheds contributes nothing. With no powered distributor, capacity and recharge are zero. A load that draws no more than recharge reports Infinity for timeToDrain.

Throws

If weaponsPips is outside [0, 4] or not finite.

Example

import type { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';

declare const metrics: BuildMetrics;
metrics.weaponsCapacitorMetrics({ weaponsPips: 2 }).timeToDrain; // seconds

---

of()

static of(build): BuildMetrics

Defined in: src/ships/build-metrics.ts:453

Attach a metrics view to a build.

Parameters

build

ShipLoadout

The build to read. The view holds it rather than copying it, so later edits are visible to every subsequent call.

Returns

BuildMetrics

The view.

Throws

If build is not a ShipLoadout.

Example

import { BuildMetrics } from '@elite-dangerous-almanac/core/ships/build-metrics';
import { ShipLoadout } from '@elite-dangerous-almanac/core/ships/ship-loadout';

const build = ShipLoadout.default('Anaconda');
const metrics = BuildMetrics.of(build);
metrics.buildMass().modules; // -> 664
build.removeModule('Slot03_Size6'); // unfit the 40 t shield generator
metrics.buildMass().modules; // -> 624, the same view reading the edited build