@eveshipfit/dogma-engine 9.0.0 → 10.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +165 -0
- package/esf_dogma_engine_bg.wasm +0 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# EVEShip.fit's Dogma Engine
|
|
2
|
+
|
|
3
|
+
[](https://crates.io/crates/esf-dogma-engine)
|
|
4
|
+
[](https://www.npmjs.com/package/@eveshipfit/dogma-engine)
|
|
5
|
+
[](https://github.com/EVEShipFit/dogma-engine/actions/workflows/testing.yml)
|
|
6
|
+
[](https://docs.rs/esf-dogma-engine)
|
|
7
|
+
|
|
8
|
+
[](https://discord.gg/S5V5BkvNf7)
|
|
9
|
+
|
|
10
|
+
This library calculates accurately statistics of an EVE Online ship fit.
|
|
11
|
+
|
|
12
|
+
The input are several data-files provided by EVE Online, together with a ship fit.
|
|
13
|
+
The output are all the Dogma attributes of the ship, its items and the character.
|
|
14
|
+
|
|
15
|
+
## Implementation
|
|
16
|
+
|
|
17
|
+
This Dogma engine implements a multi-pass approach.
|
|
18
|
+
|
|
19
|
+
- [pass 1](./crates/esf-dogma-engine/src/calculate/pass_1.rs): collect all the Dogma attributes of the hull and modules.
|
|
20
|
+
- [pass 2](./crates/esf-dogma-engine/src/calculate/pass_2.rs): collect all the Dogma effects of the hull and modules.
|
|
21
|
+
- [pass 3](./crates/esf-dogma-engine/src/calculate/pass_3.rs): apply all the Dogma effects to the hull/modules, calculating the actual Dogma attribute values.
|
|
22
|
+
- [pass 4](./crates/esf-dogma-engine/src/calculate/pass_4.rs): augment the Dogma attributes with EVEShip.fit specific attributes, that are too complex for the Dogma itself to handle.
|
|
23
|
+
|
|
24
|
+
## Input and output
|
|
25
|
+
|
|
26
|
+
`calculate` takes a fit and options, and returns a calculation.
|
|
27
|
+
All identifiers are those from the SDE.
|
|
28
|
+
|
|
29
|
+
### Fit
|
|
30
|
+
|
|
31
|
+
- `name` (optional): name of the fit.
|
|
32
|
+
- `ship`: the ship being fitted.
|
|
33
|
+
- `type_id`: its type.
|
|
34
|
+
- `items`: everything fitted or carried. Each item has:
|
|
35
|
+
- `type_id`: its type.
|
|
36
|
+
- `slot`: where the item is.
|
|
37
|
+
- `type`: `high`, `medium`, `low`, `rig`, `subsystem`, `service`, `drone_bay` or `cargo`.
|
|
38
|
+
_`cargo` is carried, but not calculated._
|
|
39
|
+
- `index`: position within that slot type, starting at 0. Absent for `drone_bay` and `cargo`.
|
|
40
|
+
- `quantity` (optional, default 1): stack size for drones and cargo.
|
|
41
|
+
- `state`: requested state; `offline`, `online`, `active` or `overload`.
|
|
42
|
+
- `charge` (optional): the loaded charge, as `type_id`.
|
|
43
|
+
- `character` (optional):
|
|
44
|
+
- `skills`: level (0 to 5) per skill type ID. A missing skill gives no bonuses.
|
|
45
|
+
|
|
46
|
+
### Options
|
|
47
|
+
|
|
48
|
+
- `sources` (optional, default false): report per attribute what its value was calculated from.
|
|
49
|
+
Leave it off unless you show it; it makes the calculation several times bigger.
|
|
50
|
+
|
|
51
|
+
### Calculation
|
|
52
|
+
|
|
53
|
+
- `ship`: result for the ship.
|
|
54
|
+
- `items`: one result per item of the fit, in the same order.
|
|
55
|
+
- `character`: result for the character.
|
|
56
|
+
|
|
57
|
+
Each result has:
|
|
58
|
+
|
|
59
|
+
- `attributes`: per attribute ID, its `base` value before effects and its final `value`.
|
|
60
|
+
With the `sources` option, also `sources`: every modifier on it, in the order they were applied. Each has:
|
|
61
|
+
- `from`: where it comes from; `type` is `ship`, `character`, `item` or `charge` (with the `index` into `items`), or `skill` (with its `type_id`).
|
|
62
|
+
- `effect_id`: the effect that modifies.
|
|
63
|
+
- `source_attribute_id`: the attribute on the source that holds `value`.
|
|
64
|
+
- `operator`: `pre_assign`, `pre_mul`, `pre_div`, `mod_add`, `mod_sub`, `post_mul`, `post_div`, `post_percent` or `post_assign`.
|
|
65
|
+
- `value`: the value of the modifying attribute.
|
|
66
|
+
- `quantity`: how many times it counts. A stacking penalised stack is listed once per item instead.
|
|
67
|
+
- `penalty`: the stacking penalty factor it got, or `null` if not penalised.
|
|
68
|
+
- `applied`: false when the source's state is too low for the effect.
|
|
69
|
+
|
|
70
|
+
How much each source added is not reported: multiplications compound and stacking penalties depend on order, so there is no single answer.
|
|
71
|
+
- `state`: the state the item reached, which can be lower than requested.
|
|
72
|
+
- `max_state`: the highest state the item can reach.
|
|
73
|
+
- `charge`: result for its charge, if it has one.
|
|
74
|
+
|
|
75
|
+
### Things to know
|
|
76
|
+
|
|
77
|
+
- A stack, like five drones, has the attributes of a single item; its bonuses count once per item in the stack.
|
|
78
|
+
|
|
79
|
+
## EVEShip.fit's specific attributes
|
|
80
|
+
|
|
81
|
+
`Pass 4` create Dogma attributes that do not exist in-game, but are rather complicated to calculate.
|
|
82
|
+
To make rendering a fit easier, these are calculated by this library, and presented as new Dogma attributes.
|
|
83
|
+
|
|
84
|
+
Their identifier is always a negative value, to visually separate them.
|
|
85
|
+
What additional attributes exist are defined in [EVEShipFit/sde-patched](https://github.com/EVEShipFit/sde-patched) repository.
|
|
86
|
+
|
|
87
|
+
## Development
|
|
88
|
+
|
|
89
|
+
Make sure you have [Rust installed](https://www.rust-lang.org/tools/install).
|
|
90
|
+
|
|
91
|
+
Next, we need the data-files.
|
|
92
|
+
They are Flatbuffers, built by [sde-patched](https://github.com/EVEShipFit/sde-patched) and published on npm as [`@eveshipfit/sde`](https://www.npmjs.com/package/@eveshipfit/sde):
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npm ci
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- `sde.dat` holds everything needed to calculate a fit.
|
|
99
|
+
- `names.dat` holds the type names in the other seven languages EVE supports.
|
|
100
|
+
It is optional.
|
|
101
|
+
|
|
102
|
+
English names live in `sde.dat`, so an EFT-fit written in English imports without it; `names.dat` is only consulted when a name does not match.
|
|
103
|
+
|
|
104
|
+
After that, we can run the application.
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
flatc --rust --gen-onefile -o crates/esf-data/src/sde/ node_modules/@eveshipfit/sde/specs/eve.fbs node_modules/@eveshipfit/sde/specs/names.fbs
|
|
108
|
+
cargo run --release -p esf-cli
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The regression suite reads the same paths; set `ESF_SDE` and `ESF_NAMES` to point it elsewhere.
|
|
112
|
+
|
|
113
|
+
## Regression
|
|
114
|
+
|
|
115
|
+
The engine is locked down by snapshot tests.
|
|
116
|
+
A case calculates one fit with one set of skills, and compares the result against a stored snapshot in [tests/snapshots](./tests/snapshots).
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
cargo test
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
If failures are expected differences, use `insta` to resolve them:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
cargo install cargo-insta
|
|
126
|
+
cargo insta review
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Integration
|
|
130
|
+
|
|
131
|
+
### Javascript (WebAssembly)
|
|
132
|
+
|
|
133
|
+
The primary goal of this library is to build a WebAssembly variant that can easily be used in the browser.
|
|
134
|
+
This means that there is no need for a server-component, and everything can be calculated in the browser.
|
|
135
|
+
|
|
136
|
+
This is done with [wasm-pack](https://rustwasm.github.io/wasm-pack/):
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
cargo install wasm-pack
|
|
140
|
+
wasm-pack build crates/esf-wasm --release --out-dir ../../pkg
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
In the `pkg` folder is now a NPM module to use.
|
|
144
|
+
|
|
145
|
+
Javascript hands over `sde.dat` once, and every lookup after that happens inside WebAssembly.
|
|
146
|
+
The file is a Flatbuffer, so nothing is parsed: the bytes are used where they land.
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
import init, { init as initPanicHook, load_sde, calculate } from "@eveshipfit/dogma-engine";
|
|
150
|
+
|
|
151
|
+
await init();
|
|
152
|
+
initPanicHook();
|
|
153
|
+
|
|
154
|
+
const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
|
|
155
|
+
const buildNumber = load_sde(new Uint8Array(sde));
|
|
156
|
+
const fit = {
|
|
157
|
+
ship: { type_id: 587 },
|
|
158
|
+
items: [{ type_id: 2873, slot: { type: "high", index: 0 }, state: "active", charge: { type_id: 185 } }],
|
|
159
|
+
character: { skills: { 3300: 5 } },
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
const calculation = calculate(fit);
|
|
163
|
+
/* Or if you want to know the source of the effects: */
|
|
164
|
+
const withSources = calculate(fit, { sources: true });
|
|
165
|
+
```
|
package/esf_dogma_engine_bg.wasm
CHANGED
|
Binary file
|