@eveshipfit/dogma-engine 10.3.0 → 11.0.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![crates.io](https://img.shields.io/crates/v/esf-dogma-engine.svg)](https://crates.io/crates/esf-dogma-engine)
 [![npm](https://img.shields.io/npm/v/%40eveshipfit%2Fdogma-engine.svg)](https://www.npmjs.com/package/@eveshipfit/dogma-engine)
+[![PyPI](https://img.shields.io/pypi/v/eveshipfit-dogma-engine.svg)](https://pypi.org/project/eveshipfit-dogma-engine/)
 [![CI](https://github.com/EVEShipFit/dogma-engine/actions/workflows/testing.yml/badge.svg)](https://github.com/EVEShipFit/dogma-engine/actions/workflows/testing.yml)
 [![docs.rs](https://img.shields.io/docsrs/esf-dogma-engine)](https://docs.rs/esf-dogma-engine)
 
@@ -36,15 +37,38 @@ All identifiers are those from the SDE.
 - `items`: everything fitted or carried. Each item has:
   - `type_id`: its type.
   - `slot`: where the item is.
-    - `type`: `high`, `medium`, `low`, `rig`, `subsystem`, `service`, `fighter_tube`, `fighter_bay`, `drone_bay` or `cargo`.
-      _`cargo` is carried, but not calculated._
-    - `index`: position within that slot type, starting at 0. Absent for `fighter_bay`, `drone_bay` and `cargo`.
+    - `type`: `high`, `medium`, `low`, `rig`, `subsystem`, `service`, `fighter_tube`, `fighter_bay`, `implant`, `booster`, `drone_bay` or `cargo`.
+    - `index`: position within that slot type, starting at 0 (`implant` and `booster` starting at 1).
+      Absent for `fighter_bay`, `drone_bay` and `cargo`.
   - `quantity` (optional, default 1): stack size for drones, fighters and cargo. For fighters in a tube, the squadron size.
   - `state`: requested state; `offline`, `online`, `active` or `overload`.
   - `charge` (optional): the loaded charge, as `type_id`.
+  - `mutation` (optional): for mutated items (Abyssal modules, mutated drones, ...).
+    - `base`: type ID of the item before it was mutated.
+    - `attributes`: the rolled value per attribute ID.
   - `fighter_abilities` (optional): the abilities a fighter uses, as effect IDs. Absent means the fighter's default abilities.
+  - `booster_side_effects` (optional): the side effects a booster rolled, as effect IDs. Absent means none.
+  - `spool` (optional): for modules whose bonus grows every cycle, how far it has spooled.
+    Only per-second stats use it; volley is always unspooled. Absent means fully spooled.
+    - `multiplier_bonus`: the bonus reached so far; 0.0 is unspooled, 2.125 is +212.5%.
 - `character` (optional):
   - `skills`: level (0 to 5) per skill type ID. A missing skill gives no bonuses.
+  - `security_status` (optional, default 0.0): the pilot's security status, -10.0 to 5.0.
+- `environment` (optional): where the fit is.
+  - `damage_profile` (optional, default 0.25 each): incoming damage for effective hitpoints, as `em`, `explosive`, `kinetic` and `thermal` (relative to each other).
+  - `security` (optional, default `high_sec`): `high_sec`, `low_sec`, `null_sec` or `wormhole`.
+  - `reactive_armor` (optional, default `do_not_adapt`): what a Reactive Armor Hardener shifts its resistances towards.
+    `do_not_adapt` leaves them where EVE shows them, `damage_profile` shifts towards `damage_profile`, and
+    `{"profile": {..}}` shifts towards a profile of its own, written the same way as `damage_profile`.
+- `incoming` (optional): what effects and buffs to apply that come from outside the ship.
+  A calculation reports the same shape as `outgoing`: feed one fit's result into another's `incoming` links them up.
+  - `buffs` (optional, default none): buffs to apply, like the ones a command burst hands out.
+    - `id`: which buff, as `dbuffCollections` in the SDE numbers them.
+    - `value`: how strong it is, in whatever the buff's operation reads.
+  - `effects` (optional, default none): effects aimed at the fit, like a stasis webifier.
+    - `type_id`: the type the effect belongs to; its category decides the stacking penalty.
+    - `effect_id`: which effect, as `dogmaEffects` in the SDE numbers them.
+    - `attributes`: the value per attribute ID the effect reads, worked out by the fit that aimed it.
 
 ### Options
 
@@ -57,16 +81,20 @@ All identifiers are those from the SDE.
 - `mode`: result for the mode; absent when the fit has no mode.
 - `items`: one result per item of the fit, in the same order.
 - `character`: result for the character.
+- `buffs`: the buffs that landed, ordered by id. Those of `incoming`, plus the ones the fit's own bursts hand out: a fleet boost reaches the ship running it. What is missing lost to another source of the same buff, or the SDE has no such buff.
+  - `id`: which buff, as `dbuffCollections` in the SDE numbers them.
+  - `value`: how strong it is, in whatever the buff's operation reads.
+- `outgoing`: what the fit hands to other fits, in the shape `incoming` takes.
 
 Each result has:
 
 - `attributes`: per attribute ID, its `base` value before effects and its final `value`.
   With the `sources` option, also `sources`: every modifier on it, in the order they were applied. Each has:
-  - `from`: where it comes from; `type` is `ship`, `mode`, `character`, `item` or `charge` (with the `index` into `items`), or `skill` (with its `type_id`).
-  - `effect_id`: the effect that modifies.
-  - `source_attribute_id`: the attribute on the source that holds `value`.
+  - `from`: where it comes from; `type` is `ship`, `mode`, `character`, `item` or `charge` (with the `index` into `items`), `projected` (with the `index` into `incoming.effects`), `skill` (with its `type_id`) or `buff` (with its `id`).
+  - `effect_id`: the effect that holds the modifier; `null` for a buff, which has none.
+  - `source_attribute_id`: the attribute on the source that holds `value`; `null` for a buff, which carries its own strength.
   - `operator`: `pre_assign`, `pre_mul`, `pre_div`, `mod_add`, `mod_sub`, `post_mul`, `post_div`, `post_percent` or `post_assign`.
-  - `value`: the value of the modifying attribute.
+  - `value`: the value of the modifying attribute, or the strength of the buff.
   - `quantity`: how many times it counts. A stacking penalised stack is listed once per item instead.
   - `penalty`: the stacking penalty factor it got, or `null` if not penalised.
   - `applied`: false when the source's state is too low for the effect.
@@ -84,6 +112,128 @@ 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.
 
+## Usage
+
+The engine is published for Rust, Javascript and Python; all three calculate the same way.
+Each hands over `sde.dat` once, and every lookup after that happens inside Rust.
+An EFT import matches the English names in `sde.dat`; hand over `names.dat` too to also match the other languages EVE supports.
+
+How each package is built is explained under [Integration](#integration).
+
+### Rust
+
+The crate is published on crates.io as [`esf-dogma-engine`](https://crates.io/crates/esf-dogma-engine).
+`esf-data` reads `sde.dat`.
+
+```bash
+cargo add esf-dogma-engine esf-data
+```
+
+```rust
+use esf_data::{InfoSde, Sde};
+use esf_dogma_engine::{Fit, Options, beacon, calculate};
+
+let bytes = std::fs::read("sde.dat")?;
+let sde = Sde::new(&bytes)?;
+let info = InfoSde::new(&sde);
+
+let fit: Fit = serde_json::from_str(
+    r#"{
+        "ship": {"type_id": 587},
+        "items": [
+            {
+                "type_id": 2873,
+                "slot": {"type": "high", "index": 0},
+                "state": "active",
+                "charge": {"type_id": 185}
+            }
+        ],
+        "character": {"skills": {"3300": 5}}
+    }"#,
+)?;
+
+let calculation = calculate(&info, &fit, &Options::default());
+// Or if you want to know the source of the effects:
+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());
+```
+
+### Javascript (WebAssembly)
+
+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.
+
+```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();
+
+const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
+const buildNumber = load_sde(new Uint8Array(sde));
+const fit = {
+  ship: { type_id: 587 },
+  items: [{ type_id: 2873, slot: { type: "high", index: 0 }, state: "active", charge: { type_id: 185 } }],
+  character: { skills: { 3300: 5 } },
+};
+
+const calculation = calculate(fit);
+/* Or if you want to know the source of the effects: */
+const withSources = calculate(fit, { sources: true });
+/* Or if you have a beacon in space (like wormhole effects): */
+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"));
+```
+
+### Python
+
+The Python variant is published on PyPI as
+[`eveshipfit-dogma-engine`](https://pypi.org/project/eveshipfit-dogma-engine/).
+The `sde` extra brings in [`eveshipfit-sde`](https://pypi.org/project/eveshipfit-sde/), which ships `sde.dat`.
+
+```bash
+pip install eveshipfit-dogma-engine[sde]
+```
+
+```python
+import esf_dogma_engine as dogma
+from eveshipfit_sde import sde_path
+
+build_number = dogma.load_sde_from_file(sde_path())
+
+fit = {
+    "ship": {"type_id": 587},
+    "items": [
+        {
+            "type_id": 2873,
+            "slot": {"type": "high", "index": 0},
+            "state": "active",
+            "charge": {"type_id": 185},
+        }
+    ],
+    "character": {"skills": {3300: 5}},
+}
+
+calculation = dogma.calculate(fit)
+# Or if you want to know the source of the effects:
+with_sources = dogma.calculate(fit, {"sources": True})
+# Or if you have a beacon in space (like wormhole effects):
+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"))
+```
+
+Fits and calculations are plain dicts, typed with `TypedDict` in `esf_dogma_engine.types`.
+
+`load_eft`, `calculate` and `beacon` release the GIL while they work, so a thread pool calculates fits in parallel.
+
 ## Development
 
 Make sure you have [Rust installed](https://www.rust-lang.org/tools/install).
@@ -108,6 +258,15 @@ flatc --rust --gen-onefile -o crates/esf-data/src/sde/ node_modules/@eveshipfit/
 cargo run --release -p esf-cli
 ```
 
+For example, some attributes of a fit with every skill at L0 except two:
+
+```bash
+printf '[Nergal, Spool]\nLight Entropic Disintegrator II, Occult S\n' \
+  | cargo run --release -p esf-cli -- -l 0 --skill "Gunnery=4" --skill "Rapid Firing=2" -a damage -a speed
+```
+
+It prints a table on a terminal and JSON otherwise; see `--help` for the rest.
+
 The regression suite reads the same paths; set `ESF_SDE` and `ESF_NAMES` to point it elsewhere.
 
 ## Regression
@@ -128,6 +287,16 @@ cargo insta review
 
 ## Integration
 
+Every variant is built from the same Rust crates; the `flatc` step from [Development](#development) comes first.
+
+### Rust
+
+The engine itself is a plain crate; [`esf-cli`](./crates/esf-cli) is an example of using it.
+
+```bash
+cargo build --release -p esf-dogma-engine
+```
+
 ### Javascript (WebAssembly)
 
 The primary goal of this library is to build a WebAssembly variant that can easily be used in the browser.
@@ -142,24 +311,13 @@ wasm-pack build crates/esf-wasm --release --out-dir ../../pkg
 
 In the `pkg` folder is now a NPM module to use.
 
-Javascript hands over `sde.dat` once, and every lookup after that happens inside WebAssembly.
-The file is a Flatbuffer, so nothing is parsed: the bytes are used where they land.
+### Python
 
-```js
-import init, { init as initPanicHook, load_sde, calculate } from "@eveshipfit/dogma-engine";
+This is done with [maturin](https://www.maturin.rs/):
 
-await init();
-initPanicHook();
-
-const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
-const buildNumber = load_sde(new Uint8Array(sde));
-const fit = {
-  ship: { type_id: 587 },
-  items: [{ type_id: 2873, slot: { type: "high", index: 0 }, state: "active", charge: { type_id: 185 } }],
-  character: { skills: { 3300: 5 } },
-};
-
-const calculation = calculate(fit);
-/* Or if you want to know the source of the effects: */
-const withSources = calculate(fit, { sources: true });
+```bash
+cargo install maturin
+maturin build --release
 ```
+
+In the `target/wheels` folder is now a wheel to install.

package/esf_dogma_engine.d.ts

@@ -1,6 +1,12 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * 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;
+
 /**
  * `js_options` may be left out; it then uses the defaults.
  */
@@ -8,6 +14,18 @@ export function calculate(js_fit: any, js_options: any): any;
 
 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;
+
+/**
+ * Load `names.dat`, so an EFT written in another language than English also
+ * imports. Optional; without it only English names match. Has to be called
+ * after `load_sde`, and calling it twice is an error.
+ */
+export function load_names(bytes: Uint8Array): number;
+
 /**
  * Load `sde.dat`. Has to be called before `calculate`; calling it twice is an
  * error, as the first buffer is borrowed for the rest of the session.

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 {
-    calculate, init, load_sde
+    beacon, calculate, init, load_eft, load_names, load_sde
 } from "./esf_dogma_engine_bg.js";

package/esf_dogma_engine_bg.js

@@ -1,3 +1,17 @@
+/**
+ * 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}
+ */
+export function beacon(type_id) {
+    const ret = wasm.beacon(type_id);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * `js_options` may be left out; it then uses the defaults.
  * @param {any} js_fit
@@ -16,6 +30,38 @@ export function init() {
     wasm.init();
 }
 
+/**
+ * Load a fit from EFT, the text format EVE copies a fit to the clipboard in.
+ * @param {string} eft
+ * @returns {any}
+ */
+export function load_eft(eft) {
+    const ptr0 = passStringToWasm0(eft, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.load_eft(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Load `names.dat`, so an EFT written in another language than English also
+ * imports. Optional; without it only English names match. Has to be called
+ * after `load_sde`, and calling it twice is an error.
+ * @param {Uint8Array} bytes
+ * @returns {number}
+ */
+export function load_names(bytes) {
+    const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.load_names(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0];
+}
+
 /**
  * Load `sde.dat`. Has to be called before `calculate`; calling it twice is an
  * error, as the first buffer is borrowed for the rest of the session.

package/package.json

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