@eveshipfit/dogma-engine 11.1.0 → 12.0.0

package/README.md

@@ -199,15 +199,25 @@ The WebAssembly variant is published on npm as
 [`@eveshipfit/dogma-engine`](https://www.npmjs.com/package/@eveshipfit/dogma-engine).
 [`@eveshipfit/sde`](https://www.npmjs.com/package/@eveshipfit/sde) ships `sde.dat` in its `dist` folder; serve or bundle that file.
 
+The package is an ES module with TypeScript types included, and it runs anywhere: under a bundler
+(Vite, webpack, ...), from a CDN, or in a plain `<script type="module">`.
+Its default export loads the WebAssembly and has to be awaited once before any other function is called.
+
 ```bash
 npm install @eveshipfit/dogma-engine @eveshipfit/sde
 ```
 
 ```js
-import init, { init as initPanicHook, load_sde, load_eft, calculate, validate, beacon } from "@eveshipfit/dogma-engine";
+import wasmInit, {
+  load_sde,
+  load_eft,
+  save_eft,
+  calculate,
+  validate,
+  beacon,
+} from "@eveshipfit/dogma-engine";
 
-await init();
-initPanicHook();
+await wasmInit();
 
 const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
 const buildNumber = load_sde(new Uint8Array(sde));
@@ -224,6 +234,8 @@ const withSources = calculate(fit, { sources: true });
 const withBeacon = calculate({ ...fit, incoming: beacon(beaconTypeId) });
 /* Or if you have an EFT, the text format EVE copies a fit to the clipboard in: */
 const imported = calculate(load_eft("[Rifter, My Rifter]\n200mm AutoCannon I"));
+/* And to write a fit back out as EFT: */
+const eft = save_eft(fit);
 
 /* What EVE would not let you fly; it calculates the fit itself: */
 const violations = validate(fit);
@@ -265,6 +277,8 @@ with_sources = dogma.calculate(fit, {"sources": True})
 with_beacon = dogma.calculate({**fit, "incoming": dogma.beacon(beacon_type_id)})
 # Or if you have an EFT, the text format EVE copies a fit to the clipboard in:
 imported = dogma.calculate(dogma.load_eft("[Rifter, My Rifter]\n200mm AutoCannon I"))
+# And to write a fit back out as EFT:
+eft = dogma.save_eft(fit)
 
 # What EVE would not let you fly; it calculates the fit itself:
 violations = dogma.validate(fit)
@@ -307,6 +321,13 @@ printf '[Nergal, Spool]\nLight Entropic Disintegrator II, Occult S\n' \
 
 It prints a table on a terminal and JSON otherwise; see `--help` for the rest.
 
+Or to write the fit back out as EFT, instead of calculating it:
+
+```bash
+printf '[Nergal, Spool]\nLight Entropic Disintegrator II, Occult S\n' \
+  | cargo run --release -p esf-cli -- --eft
+```
+
 The regression suite reads the same paths; set `ESF_SDE` and `ESF_NAMES` to point it elsewhere.
 
 ## Regression
@@ -346,7 +367,7 @@ This is done with [wasm-pack](https://rustwasm.github.io/wasm-pack/):
 
 ```bash
 cargo install wasm-pack
-wasm-pack build crates/esf-wasm --release --out-dir ../../pkg
+wasm-pack build crates/esf-wasm --release --target web --out-dir ../../pkg
 ```
 
 In the `pkg` folder is now a NPM module to use.

package/esf_dogma_engine.d.ts

@@ -1,23 +1,446 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A charge loaded in a module.
+ */
+export interface Charge {
+    /**
+     * The type id of the charge.
+     */
+    type_id: number;
+}
+
+/**
+ * A module, drone, fighter squadron, implant, booster or item in cargo.
+ */
+export interface FitItem {
+    /**
+     * The type id of the item.
+     */
+    type_id: number;
+    /**
+     * Where the item is.
+     */
+    slot: Slot;
+    /**
+     * 1 for modules. Stack size for drones, fighters and cargo; for fighters
+     * in a tube, the size of the squadron.
+     */
+    quantity?: number;
+    /**
+     * The state asked for; the calculation lowers it when the item cannot
+     * reach it.
+     */
+    state: State;
+    /**
+     * The charge loaded in the module, if any.
+     */
+    charge?: Charge;
+    /**
+     * Only for mutated modules and drones.
+     */
+    mutation?: Mutation;
+    /**
+     * Only for fighters: the abilities used, by effect id. `None` uses the
+     * abilities the fighter uses by default.
+     */
+    fighter_abilities?: number[];
+    /**
+     * Only for boosters: the side effects rolled, by effect id. Empty means
+     * none.
+     */
+    booster_side_effects?: number[];
+    /**
+     * How far a module whose bonus grows every cycle has spooled.
+     * Only per-second stats use it; volley is always unspooled.
+     * `None` is fully spooled.
+     */
+    spool?: Spool;
+}
+
+/**
+ * A projected buff (like command bursts).
+ */
+export interface ProjectedBuff {
+    /**
+     * Which buff, as `dbuffCollections` in the SDE numbers them.
+     */
+    id: number;
+    /**
+     * How strong it is, in whatever the buff's operation reads.
+     */
+    value: number;
+}
+
+/**
+ * A projected dogma effect.
+ */
+export interface ProjectedEffect {
+    /**
+     * The type the effect belongs to.
+     */
+    type_id: number;
+    /**
+     * Which effect, as `dogmaEffects` in the SDE numbers them.
+     */
+    effect_id: number;
+    /**
+     * Every attribute and its value the effect reads.
+     */
+    attributes?: Map<number, number> | Record<number, number>;
+}
+
+/**
+ * A rack of slots, or a hardpoint a weapon needs.
+ */
+export type SlotKind = "high" | "medium" | "low" | "rig" | "subsystem" | "service" | "turret" | "launcher";
+
+/**
+ * A resource the ship only has so much of.
+ */
+export type Resource = "cpu" | "powergrid" | "calibration" | "drone_bay" | "drone_bandwidth" | "launched_drones" | "fighter_bay" | "fighter_tubes" | "light_fighter_tubes" | "support_fighter_tubes" | "heavy_fighter_tubes" | "cargo_bay" | "charge_capacity";
+
+/**
+ * A rule of EVE's, and the values that failed it.
+ *
+ * What an item would accept instead is not repeated here; it is on the item
+ * itself, as `chargeGroup1`, `canFitShipType1` and the like.
+ */
+export type Rule = { type: "resource"; resource: Resource; used: number; available: number } | { type: "slots"; slot: SlotKind; used: number; available: number } | { type: "wrong_slot"; expected: SlotKind } | { type: "slot_taken" } | { type: "wrong_slot_index"; expected: number } | { type: "subsystem_taken" } | { type: "skill"; type_id: number; required: number; level: number } | { type: "rig_size"; ship: number; item: number } | { type: "ship_restricted" } | { type: "capital_item" } | { type: "structure_item" } | { type: "ship_item" } | { type: "max_group"; group_id: number; limit: GroupLimit; used: number; allowed: number } | { type: "max_type"; type_id: number; used: number; allowed: number } | { type: "charge_group" } | { type: "charge_size"; module: number; charge: number };
+
+/**
+ * A ship, what is fitted to it, and the character flying it.
+ */
+export interface Fit {
+    /**
+     * Only for display; the calculation does not use it.
+     */
+    name?: string;
+    /**
+     * The ship.
+     */
+    ship: Ship;
+    /**
+     * Modules, drones, fighters, implants, boosters and cargo.
+     */
+    items: FitItem[];
+    /**
+     * The character flying the ship.
+     */
+    character?: Character;
+    /**
+     * Where the ship is.
+     */
+    environment?: Environment;
+    /**
+     * What projections to apply on this fit.
+     */
+    incoming?: Projection;
+}
+
+/**
+ * How a modifier changes an attribute. They are applied in this order.
+ */
+export type EffectOperator = "pre_assign" | "pre_mul" | "pre_div" | "mod_add" | "mod_sub" | "post_mul" | "post_div" | "post_percent" | "post_assign";
+
+/**
+ * How a module or drone was mutated.
+ */
+export interface Mutation {
+    /**
+     * The type id of the item before it was mutated.
+     */
+    base: number;
+    /**
+     * The rolled value of each mutated attribute, by attribute id.
+     */
+    attributes?: Map<number, number> | Record<number, number>;
+}
+
+/**
+ * How far a module has spooled.
+ */
+export type Spool = { multiplier_bonus: number };
+
+/**
+ * How incoming damage is split over the four damage types. Only the ratio
+ * matters; the calculation scales the four to add up to one.
+ */
+export interface DamageProfile {
+    /**
+     * EM damage.
+     */
+    em?: number;
+    /**
+     * Explosive damage.
+     */
+    explosive?: number;
+    /**
+     * Kinetic damage.
+     */
+    kinetic?: number;
+    /**
+     * Thermal damage.
+     */
+    thermal?: number;
+}
+
+/**
+ * One attribute, before and after the effects on it.
+ */
+export interface AttributeValue {
+    /**
+     * The value from the SDE.
+     */
+    base: number;
+    /**
+     * The value after every effect is applied.
+     */
+    value: number;
+    /**
+     * In the order pass 3 applied them; empty unless `Options::sources` is set.
+     */
+    sources?: Source[];
+}
+
+/**
+ * One modifier on an attribute, and where it came from.
+ */
+export interface Source {
+    /**
+     * The object the effect belongs to.
+     */
+    from: SourceRef;
+    /**
+     * The effect that holds the modifier; `None` for a buff, which has none.
+     */
+    effect_id: number | undefined;
+    /**
+     * The attribute on the source that holds `value`; `None` for a buff,
+     * which carries its own strength.
+     */
+    source_attribute_id: number | undefined;
+    /**
+     * How `value` changes the attribute.
+     */
+    operator: EffectOperator;
+    /**
+     * The source attribute's value, as pass 3 used it.
+     */
+    value: number;
+    /**
+     * A penalised stack is split into one entry per item, as each gets its own penalty.
+     */
+    quantity: number;
+    /**
+     * The stacking penalty factor applied; `None` when not penalised.
+     */
+    penalty: number | undefined;
+    /**
+     * False when the source's state is too low for the effect.
+     */
+    applied: boolean;
+}
+
+/**
+ * One rule the fit breaks, and what breaks it.
+ */
+export interface Violation {
+    /**
+     * What the rule is about.
+     */
+    target: Target;
+    /**
+     * The rule, and the values that failed it.
+     */
+    rule: Rule;
+}
+
+/**
+ * The calculated attributes of the ship, its mode, the character, or one item.
+ */
+export interface ItemResult {
+    /**
+     * Every attribute, by attribute id.
+     */
+    attributes: Map<number, AttributeValue>;
+    /**
+     * The state actually reached, which may be below what was requested.
+     */
+    state: State;
+    /**
+     * The highest state the item can reach.
+     */
+    max_state: State;
+    /**
+     * The charge loaded in the module, if any.
+     */
+    charge: ItemResult | undefined;
+}
+
+/**
+ * The character flying the ship.
+ */
+export interface Character {
+    /**
+     * The level of each skill, by type id. A skill that is not listed is not
+     * trained, and gives no bonus.
+     */
+    skills?: Map<number, number> | Record<number, number>;
+    /**
+     * -10.0 to 5.0. Only a few ships have a bonus that scales with it.
+     */
+    security_status?: number;
+}
+
+/**
+ * The external buffs and effects that can be applied to another ship.
+ *
+ * A calculation reports what the fit hands out; put that in
+ * [`Fit::incoming`](crate::Fit::incoming) of another fit to have it applied.
+ */
+export interface Projection {
+    /**
+     * Buffs, like command burst hands.
+     */
+    buffs?: ProjectedBuff[];
+    /**
+     * Effects, like webifiers, remote reps, etc.
+     */
+    effects?: ProjectedEffect[];
+}
+
+/**
+ * The result of [`calculate()`](crate::calculate).
+ */
+export interface Calculation {
+    /**
+     * The ship.
+     */
+    ship: ItemResult;
+    /**
+     * The active mode, if the ship has one.
+     */
+    mode?: ItemResult;
+    /**
+     * Index-parallel to `Fit::items`: same length, same order.
+     */
+    items: ItemResult[];
+    /**
+     * The character.
+     */
+    character: ItemResult;
+    /**
+     * The buffs that landed, ordered by id: those of `Fit::incoming`, plus
+     * the ones the fit's own bursts hand out. What is missing lost to another
+     * source of the same buff, or the SDE has no such buff.
+     */
+    buffs?: ProjectedBuff[];
+    /**
+     * All outgoing projections (effects and buffs).
+     */
+    outgoing?: Projection;
+}
+
+/**
+ * The security of a solar system.
+ */
+export type Security = "high_sec" | "low_sec" | "null_sec" | "wormhole";
+
+/**
+ * The ship of a fit.
+ */
+export interface Ship {
+    /**
+     * The type id of the ship.
+     */
+    type_id: number;
+    /**
+     * The type id of the active mode, for ships that have modes.
+     */
+    mode?: number;
+}
+
+/**
+ * The state of an item, lowest first.
+ */
+export type State = "offline" | "online" | "active" | "overload";
+
+/**
+ * What [`calculate()`] reports on top of the values.
+ */
+export interface Options {
+    /**
+     * Report per attribute the modifiers its value was calculated from.
+     */
+    sources?: boolean;
+}
+
+/**
+ * What a Reactive Armor Hardener shifts its resistances towards.
+ *
+ * EVE shows it as a plain 15/15/15/15 hardener, as the client has no damage
+ * to shift it against. `DoNotAdapt` reports the same, and is the default.
+ */
+export type ReactiveArmor = "do_not_adapt" | "damage_profile" | { profile: DamageProfile };
+
+/**
+ * What a [`Violation`] is about. `Item` and `Charge` index into `Fit::items`.
+ */
+export type Target = { type: "ship" } | { type: "item"; index: number } | { type: "charge"; index: number };
+
+/**
+ * Where an item is. The number is the position in its rack, starting at 0;
+ * for implants and boosters, the slot as EVE numbers it, starting at 1.
+ */
+export type Slot = { type: "high"; index: number } | { type: "medium"; index: number } | { type: "low"; index: number } | { type: "rig"; index: number } | { type: "subsystem"; index: number } | { type: "service"; index: number } | { type: "fighter_tube"; index: number } | { type: "fighter_bay" } | { type: "implant"; index: number } | { type: "booster"; index: number } | { type: "drone_bay" } | { type: "cargo" };
+
+/**
+ * Where the ship is.
+ */
+export interface Environment {
+    /**
+     * The damage the ship is assumed to take, for effective hitpoints.
+     */
+    damage_profile?: DamageProfile;
+    /**
+     * The security of the solar system.
+     */
+    security?: Security;
+    /**
+     * What a Reactive Armor Hardener shifts its resistances towards.
+     */
+    reactive_armor?: ReactiveArmor;
+}
+
+/**
+ * Which state a group limit counts.
+ */
+export type GroupLimit = "fitted" | "online" | "active";
+
+/**
+ * `Item` and `Charge` index into `Fit::items`, `Projected` into
+ * `Fit::incoming.effects`. A skill and a buff are not in the result, so they
+ * carry their own id.
+ */
+export type SourceRef = { type: "ship" } | { type: "mode" } | { type: "character" } | { type: "item"; index: number } | { type: "charge"; index: number } | { type: "skill"; type_id: number } | { type: "projected"; index: number } | { type: "buff"; id: number };
+
 
 /**
  * What a beacon in space hands to every fit in there with it. Put the result
  * in `incoming` of a fit to have it applied.
  */
-export function beacon(type_id: number): any;
+export function beacon(type_id: number): Projection;
 
 /**
- * `js_options` may be left out; it then uses the defaults.
+ * `options` may be left out; it then uses the defaults.
  */
-export function calculate(js_fit: any, js_options: any): any;
-
-export function init(): void;
+export function calculate(fit: Fit, options?: Options | null): Calculation;
 
 /**
  * Load a fit from EFT, the text format EVE copies a fit to the clipboard in.
  */
-export function load_eft(eft: string): any;
+export function load_eft(eft: string): Fit;
 
 /**
  * Load `names.dat`, so an EFT written in another language than English also
@@ -32,8 +455,59 @@ export function load_names(bytes: Uint8Array): number;
  */
 export function load_sde(bytes: Uint8Array): number;
 
+/**
+ * Write a fit as EFT, the text format EVE copies a fit to the clipboard in.
+ */
+export function save_eft(fit: Fit): string;
+
+export function set_panic_hook(): void;
+
 /**
  * Report the fitting rules the fit breaks. Calculates the fit itself, as
  * every rule reads the values after skills and modules changed them.
  */
-export function validate(js_fit: any): any;
+export function validate(fit: Fit): Violation[];
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly beacon: (a: number) => [number, number, number];
+    readonly calculate: (a: any, b: number) => [number, number, number];
+    readonly load_eft: (a: number, b: number) => [number, number, number];
+    readonly load_names: (a: number, b: number) => [number, number, number];
+    readonly load_sde: (a: number, b: number) => [number, number, number];
+    readonly save_eft: (a: any) => [number, number, number, number];
+    readonly set_panic_hook: () => void;
+    readonly validate: (a: any) => [number, number, number];
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;