ships.Class.BuildMetrics

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

Class: BuildMetrics

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

Every figure a fitted build can be asked for.

Member index

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

Methods

armourMetrics()

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.

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

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:711

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 mobilityMetricsResult. Pass a complete standardLoadResult value 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 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.

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

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

---

distributorMetricsResult()

distributorMetricsResult(options?): CalculationResult<DistributorMetrics>

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

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:458

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:523

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:584

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.

---

heatMetricsResult()

heatMetricsResult(): CalculationResult<HeatMetrics>

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

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:555

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:664

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:570

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:446

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

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.

---

mobilityCapacitorMetricsResult()

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.

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'

---

mobilityMetricsResult()

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.

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

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?

---

shieldCapacitorMetricsResult()

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.

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'

---

shieldMetricsResult()

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.

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

---

shieldRecoveryResult()

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.

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

---

standardLoadResult()

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.

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.mobilityCapacitorMetricsResult({ ...load.value, enginesPips: 2 });

---

thrusters()

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.

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:612

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

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:1130

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:435

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