Skip to main content

Crate esf

Crate esf 

Source
Expand description

§esf

crates.io docs.rs CI

Discord

Read and write esf/1, the plain-text format for EVE Online ship fits. Text, canonical and binary forms. No dependencies.

cargo add esf

§Usage

use esf::{Catalog, Entry, EsfFit, Location, State};

fn example(catalog: &dyn Catalog) -> Result<(), esf::Error> {
    let item = |type_id| Entry { type_id: Some(type_id), ..Entry::default() };
    let fit = EsfFit {
        hull: Some(587), // Rifter
        name: Some("Shield Buffer".to_string()),
        mode: None,
        entries: vec![
            Entry { count: Some(3), charge: Some(21898), ..item(2889) }, // 3 guns, a full load of ammo each
            Entry { location: Some(Location::High), ..Entry::default() }, // an empty high slot
            Entry { state: Some(State::Off), ..item(448) }, // an offline module
            item(2048), // goes in its own rack
            Entry { count: Some(5), ..item(2456) }, // 5 drones
            Entry { count: Some(1000), location: Some(Location::Cargo), ..item(21898) },
        ],
    };

    let text = esf::save(&[fit.clone()], catalog)?; // canonical text
    let data = esf::save_binary(&[fit], catalog)?; // binary
    let fits = esf::load(&data, catalog)?; // text or binary

    let url = esf::to_base64url(&data); // the binary form in a URL
    let data = esf::from_base64url(&url)?;
    Ok(())
}

save() and save_binary() take entries in any order, and check every rule of the spec. load() returns fits in canonical form. All three return an esf::Error when a rule is broken. It says where: line for text, or fit and entry (counting from 1) for fits.

§Fits

An EsfFit is one fit: hull, name, tactical mode and its entries. hull is None for a fit without a ship. A document can hold more than one fit.

Each Entry is one line of the fit. None means the default:

fieldwhat it isNone means
type_idThe type ID.An empty slot.
countHow many.One; for fighters, a full squadron.
fit_nameThe name of another fit in the list, which this ship or container carries.Carries no fit.
chargeThe charge loaded.
charge_countHow many charges.A full load.
mutaplasmidThe mutaplasmid applied.
overridesAttribute values by attribute ID.
stateState::Off, On or Heat.Active if the type can be, else on.
locationCargo, Bay or another hold; a rack, like High or Tube, for an empty slot or with slot.Where the type goes by default.
slotThe slot in the location rack, counting from 1. load() never sets it: it returns the rack in slot order, with empty slots between.The next free slot.

§The Catalog

The library holds no game data. You give it a Catalog: a type that looks up types and attributes in your copy of the SDE.

use esf::{AttributeRecord, Catalog, MutaplasmidRecord, TypeRecord};

struct MyCatalog;

impl Catalog for MyCatalog {
    fn type_by_name(&self, folded_name: &str) -> Option<&TypeRecord> { todo!() }
    fn type_by_id(&self, type_id: u32) -> Option<&TypeRecord> { todo!() }
    fn attribute_by_name(&self, folded_name: &str) -> Option<&AttributeRecord> { todo!() }
    fn attribute_by_id(&self, attribute_id: u32) -> Option<&AttributeRecord> { todo!() }

    // Optional. Without them, no hull has tactical modes and no type has mutaplasmids.
    fn modes(&self, hull_id: u32) -> &[TypeRecord] { todo!() }
    fn mutaplasmids(&self, type_id: u32) -> &[MutaplasmidRecord] { todo!() }
}

Each method and field says what to return and where in the SDE it comes from. esf::sde has helpers for the parts that take more than a lookup:

use std::collections::HashMap;

use esf::{TypeRecord, sde};

// One row of types.jsonl.
struct SdeType {
    id: u32,
    name: String,
    published: bool,
    group_id: u32,
    capacity: Option<f64>,
    volume: Option<f64>,
}

fn type_names(types: &[SdeType]) -> HashMap<String, u32> {
    sde::name_index(types, |t| t.id, |t| &t.name, |t| t.published)
}

// effects: (effectID, effectCategoryID) in file order; attributes: (attributeID, value)
fn record(
    t: &SdeType,
    category_id: u32,
    effects: &[(u32, u32)],
    attributes: &[(u32, f64)],
) -> TypeRecord {
    TypeRecord {
        id: t.id,
        name: t.name.clone(),
        kind: sde::kind(category_id, t.group_id, effects.iter().map(|&(id, _)| id)),
        active: sde::active(effects.iter().copied()),
        capacity: t.capacity.unwrap_or(0.0),
        volume: t.volume.unwrap_or(0.0),
        squadron_size: sde::squadron_size(attributes.iter().copied()),
    }
}

examples/sde_jsonl_catalog.rs is a complete example on the official SDE in JSONL: copy it into your project.

§ESI

ESI gives each item in a ship a location_flag. esf::esi turns it into a location and a slot:

fn entry(type_id: u32, flag: &str) -> esf::Entry {
    esf::Entry {
        type_id: Some(type_id),
        location: Some(esf::esi::location(flag).unwrap_or(esf::Location::Cargo)),
        slot: esf::esi::slot(flag),
        ..esf::Entry::default()
    }
}

HiSlot2 gives High and slot 3, and ShipHangar gives Maintenance. A flag that is not inside a ship, like Hangar, gives None; the example puts those items in the cargo hold.

§Tests

The test cases live in esf-format:

git clone --branch v1.0 https://github.com/EVEShipFit/esf-format
cargo build --example program
uv run --project esf-format/tools esf-test -- target/debug/examples/program
cargo test

Modules§

esi
Helpers to turn an ESI location_flag into an Entry::location and Entry::slot.
sde
Helpers to build a Catalog from the SDE, for the fields that take more than a lookup.

Structs§

AttributeRecord
One dogma attribute, like “speedFactor”, as the library needs it.
Entry
One line of a fit: an item, an empty slot, or another fit carried by this one.
Error
A broken rule of esf/1, and where: a line of text, or a fit and entry, counting from 1.
EsfFit
One fit: a ship and everything on it, or a plain list of items.
MutaplasmidRecord
One mutaplasmid that can be applied to a base type, like “Unstable 5MN Microwarpdrive Mutaplasmid”.
TypeRecord
One type, like “Rifter” or “200mm AutoCannon II”, as the library needs it.

Enums§

Kind
What a type is, which decides where it goes in a fit (esf/1 spec §5).
Location
Where an entry goes, when not where its type goes by default (esf/1 spec §5).
State
Whether an item is offline, online or running, when that is not its default (esf/1 spec §6.4).

Traits§

Catalog
Where the library looks up game data. You write this, on top of your copy of the SDE.

Functions§

fold
Unicode simple case folding.
from_base64url
The binary form from base64url without padding (§10.4).
is_text
Whether a document is text, by its first character (§10).
load
Read a text or binary document, in canonical form.
save
Write fits as canonical text (§8).
save_binary
Write fits in the binary form (§10).
to_base64url
The binary form as base64url without padding, for URLs (§10.4).