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

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

Every figure a fitted build can be asked for.

• Attach — of.
• Jump — frameShiftDrive, frameShiftDriveMassFactor, maxJumpRange, jumpRange, ladenJumpRange, fuelPerJump, totalRange, jumpRangeSummary, standardLoadResult.
• Mass and cost — buildMass, buildCost.
• Power and heat — powerBudget, heatMetricsResult.
• Mobility — thrusters, mobilityMetricsResult, mobilityCapacitorMetricsResult.
• Defence — armourMetrics, shieldMetricsResult, shieldCapacitorMetricsResult, shieldRecoveryResult, cellBanks.
• Offence — weaponMetrics, weaponsCapacitorMetrics, 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.

armourMetrics(): ArmourMetrics

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

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

ArmourMetrics

The ArmourMetrics, read off the fitted bulkhead.

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

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

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.

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.

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.

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(options?): BuildMass

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

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

JumpOptions = {}

JumpOptions. fuel defaults to a full main tank and cargo to 0, matching jumpRange and mobilityMetricsResult. Pass a complete standardLoadResult value to weigh one of the standard loads.

BuildMass

A frozen BuildMass, every figure in tonnes.

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 mobilityMetricsResult weigh; the game's statistics panel additionally counts the reserve in the current mass it displays, so add fuelCapacity.reserve to reproduce that reading.

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

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(): CellBankSummary

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

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.

CellBankSummary

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

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

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

distributorMetricsResult(options?): CalculationResult<DistributorMetrics>

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

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

DistributorOptions = {}

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

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.

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

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(): FrameShiftDriveParams

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

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

FrameShiftDriveParams

The drive's constants.

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

frameShiftDriveMassFactor(options?): number

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

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

JumpOptions = {}

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

number

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

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.

If the build has no usable frame shift drive.

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

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

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

fuelPerJump(distance, options?): number

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

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

number

The jump distance, in light-years.

JumpOptions = {}

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

number

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

If the build has no usable frame shift drive.

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

heatMetricsResult(): CalculationResult<HeatMetrics>

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

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

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.

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(options?): number

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

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

JumpOptions = {}

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

number

The jump's range, in light-years.

If the build has no usable frame shift drive.

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

jumpRangeSummary(): JumpRangeSummary

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

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

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.

If the build has no usable frame shift drive.

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(): number

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

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

number

The jump's range, in light-years.

If the build has no usable frame shift drive.

loadout(): ShipLoadout

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

The build this view reads.

ShipLoadout

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

maxJumpRange(): number

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

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".

number

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

If the build has no usable frame shift drive.

mobilityCapacitorMetricsResult(options?): CalculationResult<MobilityCapacitorMetrics>

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

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

MobilityCapacitorOptions = {}

MobilityCapacitorOptions.

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.

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

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'

mobilityMetricsResult(options?): CalculationResult<MobilityMetrics>

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

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

JumpOptions = {}

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

CalculationResult<MobilityMetrics>

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

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

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

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

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.

PowerBudget

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

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

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?

shieldCapacitorMetricsResult(options?): CalculationResult<ShieldCapacitorMetrics>

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

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

ShieldCapacitorOptions = {}

ShieldCapacitorOptions. systemsPips defaults to 4.

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.

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

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'

shieldMetricsResult(): CalculationResult<ShieldMetrics>

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

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

CalculationResult<ShieldMetrics>

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

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

shieldRecoveryResult(options?): CalculationResult<ShieldRecovery>

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

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

ShieldRecoveryOptions = {}

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

CalculationResult<ShieldRecovery>

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

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

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

standardLoadResult(load): CalculationResult<StandardLoadInputs>

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

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

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.

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.

If load is not a recognised standard load.

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

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

thrusters(): ThrusterParams | null

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

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

ThrusterParams | null

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.

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(options?): TotalRangeDetails

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

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

JumpOptions = {}

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

TotalRangeDetails

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

If the build has no usable frame shift drive.

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

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(): BuildWeaponMetrics

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

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.

BuildWeaponMetrics

The BuildWeaponMetrics.

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(options?): WeaponsCapacitorMetrics

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

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

WeaponsOptions = {}

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

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.

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

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

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

static of(build): BuildMetrics

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

Attach a metrics view to a build.

ShipLoadout

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

BuildMetrics

The view.

If build is not a ShipLoadout.

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