@eveshipfit/dogma-engine 11.0.1 → 11.2.0

package/README.md

@@ -112,6 +112,37 @@ To make rendering a fit easier, these are calculated by this library, and presen
 Their identifier is always a negative value, to visually separate them.
 What additional attributes exist are defined in [EVEShipFit/sde-patched](https://github.com/EVEShipFit/sde-patched) repository.
 
+## Validation
+
+`validate()` checks if the fit violates any rules that would prevent you from flying it in-game.
+It returns the violations, grouped by the kind of rule and, within a kind, in the order of `items`.
+An empty list means the fit breaks no rules.
+
+Each violation has:
+
+- `target`: what the rule is about.
+  - `ship`, for what the ship carries as a whole.
+  - `item`, with the `index` into `items`.
+  - `charge`, with the `index` into `items` of the item holding it.
+- `rule`: the rule, and the values that failed it. `type` says which:
+  - `resource`: `resource` ran out, `used` of `available`.
+    One of `cpu`, `powergrid`, `calibration`, `drone_bay`, `drone_bandwidth`, `launched_drones`, `fighter_bay`, `fighter_tubes`, `light_fighter_tubes`, `support_fighter_tubes`, `heavy_fighter_tubes`, `cargo_bay` or `charge_capacity`.
+  - `slots`: more items in the `slot` rack than the ship has, `used` of `available`.
+    One of `high`, `medium`, `low`, `rig`, `subsystem`, `service`, `turret` or `launcher`; the last two are hardpoints a weapon takes on top of its slot.
+  - `wrong_slot`: the item belongs in the `expected` rack.
+  - `slot_taken`: another item of the fit is in this slot too.
+  - `wrong_slot_index`: an implant or booster outside the slot it occupies, which is `expected`.
+  - `subsystem_taken`: another subsystem covers the same part of the ship.
+  - `skill`: the character is missing `type_id`, or has it at `level` where the item asks for `required`.
+  - `rig_size`: a rig of size `item` where the `ship` takes another.
+  - `ship_restricted`: the item cannot go on this ship at all.
+  - `capital_item`: a capital item on a ship that is not a capital.
+  - `max_group`: `used` of `group_id` are `limit` (`fitted`, `online` or `active`), where `allowed` may be.
+    This is what keeps a second propulsion module from running: an afterburner and a microwarpdrive share a group.
+  - `max_type`: `used` of `type_id` are fitted, where `allowed` may be.
+  - `charge_group`: a charge of a group the module does not take.
+  - `charge_size`: a charge of size `charge` where the `module` takes another.
+
 ## Usage
 
 The engine is published for Rust, Javascript and Python; all three calculate the same way.
@@ -131,7 +162,7 @@ cargo add esf-dogma-engine esf-data
 
 ```rust
 use esf_data::{InfoSde, Sde};
-use esf_dogma_engine::{Fit, Options, beacon, calculate};
+use esf_dogma_engine::{Fit, Options, beacon, calculate, validate};
 
 let bytes = std::fs::read("sde.dat")?;
 let sde = Sde::new(&bytes)?;
@@ -157,6 +188,9 @@ let calculation = calculate(&info, &fit, &Options::default());
 let with_sources = calculate(&info, &fit, &Options { sources: true, ..Default::default() });
 // Or if you have a beacon in space (like wormhole effects):
 let with_beacon = calculate(&info, &Fit { incoming: beacon(&info, beacon_type_id), ..fit }, &Options::default());
+
+// What EVE would not let you fly:
+let violations = validate(&info, &fit, &calculation);
 ```
 
 ### Javascript (WebAssembly)
@@ -165,15 +199,24 @@ 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 built for bundlers (Vite, webpack 5, ...), which load the `.wasm` themselves.
+
 ```bash
 npm install @eveshipfit/dogma-engine @eveshipfit/sde
 ```
 
 ```js
-import init, { init as initPanicHook, load_sde, load_eft, calculate, beacon } from "@eveshipfit/dogma-engine";
-
-await init();
-initPanicHook();
+import {
+  init,
+  load_sde,
+  load_eft,
+  save_eft,
+  calculate,
+  validate,
+  beacon,
+} from "@eveshipfit/dogma-engine";
+
+init();
 
 const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
 const buildNumber = load_sde(new Uint8Array(sde));
@@ -190,6 +233,11 @@ 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);
 ```
 
 ### Python
@@ -228,6 +276,11 @@ 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)
 ```
 
 Fits and calculations are plain dicts, typed with `TypedDict` in `esf_dogma_engine.types`.
@@ -267,6 +320,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

package/esf_dogma_engine.d.ts

@@ -1,23 +1,448 @@
 /* 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 calculate(fit: Fit, options?: Options | null): Calculation;
 
 export function init(): void;
 
 /**
  * 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
@@ -31,3 +456,14 @@ export function load_names(bytes: Uint8Array): number;
  * error, as the first buffer is borrowed for the rest of the session.
  */
 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;
+
+/**
+ * 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(fit: Fit): Violation[];

package/esf_dogma_engine.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./esf_dogma_engine_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    beacon, calculate, init, load_eft, load_names, load_sde
+    beacon, calculate, init, load_eft, load_names, load_sde, save_eft, validate
 } from "./esf_dogma_engine_bg.js";

package/esf_dogma_engine_bg.js

@@ -2,7 +2,7 @@
  * 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.
  * @param {number} type_id
- * @returns {any}
+ * @returns {Projection}
  */
 export function beacon(type_id) {
     const ret = wasm.beacon(type_id);
@@ -13,13 +13,13 @@ export function beacon(type_id) {
 }
 
 /**
- * `js_options` may be left out; it then uses the defaults.
- * @param {any} js_fit
- * @param {any} js_options
- * @returns {any}
+ * `options` may be left out; it then uses the defaults.
+ * @param {Fit} fit
+ * @param {Options | null} [options]
+ * @returns {Calculation}
  */
-export function calculate(js_fit, js_options) {
-    const ret = wasm.calculate(js_fit, js_options);
+export function calculate(fit, options) {
+    const ret = wasm.calculate(fit, isLikeNone(options) ? 0 : addToExternrefTable0(options));
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -33,7 +33,7 @@ export function init() {
 /**
  * Load a fit from EFT, the text format EVE copies a fit to the clipboard in.
  * @param {string} eft
- * @returns {any}
+ * @returns {Fit}
  */
 export function load_eft(eft) {
     const ptr0 = passStringToWasm0(eft, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -77,6 +77,44 @@ export function load_sde(bytes) {
     }
     return ret[0];
 }
+
+/**
+ * Write a fit as EFT, the text format EVE copies a fit to the clipboard in.
+ * @param {Fit} fit
+ * @returns {string}
+ */
+export function save_eft(fit) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ret = wasm.save_eft(fit);
+        var ptr1 = ret[0];
+        var len1 = ret[1];
+        if (ret[3]) {
+            ptr1 = 0; len1 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Report the fitting rules the fit breaks. Calculates the fit itself, as
+ * every rule reads the values after skills and modules changed them.
+ * @param {Fit} fit
+ * @returns {Violation[]}
+ */
+export function validate(fit) {
+    const ret = wasm.validate(fit);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
 export function __wbg_Error_67e7344beaa85059(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return ret;
@@ -122,10 +160,6 @@ export function __wbg___wbindgen_is_function_fcda5e3902d732fe(arg0) {
     const ret = typeof(arg0) === 'function';
     return ret;
 }
-export function __wbg___wbindgen_is_null_5160b3e381865372(arg0) {
-    const ret = arg0 === null;
-    return ret;
-}
 export function __wbg___wbindgen_is_object_edb6b15aa3afe12e(arg0) {
     const val = arg0;
     const ret = typeof(val) === 'object' && val !== null;

package/package.json

@@ -5,7 +5,7 @@
     "EVEShipFit Team <info@eveship.fit>"
   ],
   "description": "Library to calculate statistics for EVE Online ship fits",
-  "version": "11.0.1",
+  "version": "11.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",