diff --git a/docs/guides/glossary.md b/docs/guides/glossary.md index a79aaadb..aa6de172 100644 --- a/docs/guides/glossary.md +++ b/docs/guides/glossary.md @@ -4,75 +4,75 @@ This document is a list of common or unusual terms used in EVE third-party devel ### APIs & Data sources -* [*ESI*](../services/esi/overview.md) — "EVE Swagger Interface" +* [*ESI*](../services/esi/overview.md) — "EVE Swagger Interface" The official RESTful API for EVE third-party development -* [*SDE*](../services/sde/index.md) — "Static Data Export" - Export of static game data (only changing with game updates) -* *CREST* — "Carbon RESTful API" - Previous generation third-party development API (defunct since 2018) -* *XML API* - Previous generation third-party development API (defunct since 2018) -* *IGB* — "In-Game Browser" - In-game browser and related APIs (defunct since 2016) -* *Static Data Dump* - Prior version of the *SDE* +* [*SDE*](../services/static-data/index.md) — "Static Data Export" + Export of static game data (only changing with game updates) +* *CREST* — "Carbon RESTful API" + Previous generation third-party development API (defunct since 2018) +* *XML API* + Previous generation third-party development API (defunct since 2018) +* *IGB* — "In-Game Browser" + In-game browser and related APIs (defunct since 2016) +* *Static Data Dump* + Prior version of the *SDE* ### Data Formats -* [*EFT*](./fitting.md#eft) — "EVE Fitting Tool" - Human-Readable format for ship fittings from the now-defunct third-party program of the same name, used in-game for fit copying and pasting -* [*Ship DNA*](./fitting.md#dna) +* [*EFT*](./fitting.md#eft) — "EVE Fitting Tool" + Human-Readable format for ship fittings from the now-defunct third-party program of the same name, used in-game for fit copying and pasting +* [*Ship DNA*](./fitting.md#dna) Compact data format for ship fittings, used in-game for fit links -* [*XML Fitting*](./fitting.md#xml) +* [*XML Fitting*](./fitting.md#xml) XML-based fitting format, used in-game for file-based fit export/import ### Data Types -* *Type* - Game object. Types describe most "things" in the game; cargo items, ships, objects in space - Found in the SDE in `fsd/types.yaml`, through ESI under `/universe/types/` -* *Item* - An individual instance of a type; e.g., Type 648 ("Badger") describes all Badger ships, any individual assembled ship has a unique `itemID`. - An "object" as opposed to a "class" in programming terms -* *Group* - Collection of related *Types* - Not to be confused with *MetaGroup* or *MarketGroup* - Found in the SDE in `fsd/groups.yaml`, through ESI under `/universe/groups/` -* *Category* - Collection of related *Groups* - Usually differentiates the "kind" of object; E.g. "Ship" and "Module" are different Categories - Found in the SDE in `fsd/categories.yaml`, through ESI under `/universe/categories/` -* *MetaGroup* - Tech-tier such as T1/T2/T3/Faction - Not to be confused with regular item *Group* or *MarketGroup* - Found in the SDE in `fsd/metaGroups.yaml`, not available through ESI -* *MarketGroup* - A single tab (or tab group) in the market - Not to be confused with regular item *Group* or *MetaGroup* - Found in the SDE in `fsd/marketGroups.yaml`, through ESI under `/markets/groups/` -* *Icon* - Icon images, such as inventory icons, UI icons, overview icons, etc. - Found in the SDE in `fsd/iconIDs.yaml`, not available through ESI -* *Graphic* - Data about 3D models; Model geometry, textures, icons/renders of those models - Found in the SDE in `fsd/graphicIDs.yaml`, through ESI under `/universe/graphics/` -* *Attribute* - (Additional) properties of a *Type*, such as HP, maximum velocity, and other item stats - Found in the SDE in `fsd/dogmaAttributes.yaml`, through ESI under `/dogma/attributes/` -* *Effect* - Game logic element. Describes interactions between attributes - Some properties are also stored as effects rather than attributes (E.g. which slot a module uses) - Found in the SDE in `fsd/dogmaEffects.yaml`, through ESI under `/dogma/effects/` +* *Type* + Game object. Types describe most "things" in the game; cargo items, ships, objects in space + Found in the SDE in `fsd/types.yaml`, through ESI under `/universe/types/` +* *Item* + An individual instance of a type; e.g., Type 648 ("Badger") describes all Badger ships, any individual assembled ship has a unique `itemID`. + An "object" as opposed to a "class" in programming terms +* *Group* + Collection of related *Types* + Not to be confused with *MetaGroup* or *MarketGroup* + Found in the SDE in `fsd/groups.yaml`, through ESI under `/universe/groups/` +* *Category* + Collection of related *Groups* + Usually differentiates the "kind" of object; E.g. "Ship" and "Module" are different Categories + Found in the SDE in `fsd/categories.yaml`, through ESI under `/universe/categories/` +* *MetaGroup* + Tech-tier such as T1/T2/T3/Faction + Not to be confused with regular item *Group* or *MarketGroup* + Found in the SDE in `fsd/metaGroups.yaml`, not available through ESI +* *MarketGroup* + A single tab (or tab group) in the market + Not to be confused with regular item *Group* or *MetaGroup* + Found in the SDE in `fsd/marketGroups.yaml`, through ESI under `/markets/groups/` +* *Icon* + Icon images, such as inventory icons, UI icons, overview icons, etc. + Found in the SDE in `fsd/iconIDs.yaml`, not available through ESI +* *Graphic* + Data about 3D models; Model geometry, textures, icons/renders of those models + Found in the SDE in `fsd/graphicIDs.yaml`, through ESI under `/universe/graphics/` +* *Attribute* + (Additional) properties of a *Type*, such as HP, maximum velocity, and other item stats + Found in the SDE in `fsd/dogmaAttributes.yaml`, through ESI under `/dogma/attributes/` +* *Effect* + Game logic element. Describes interactions between attributes + Some properties are also stored as effects rather than attributes (E.g. which slot a module uses) + Found in the SDE in `fsd/dogmaEffects.yaml`, through ESI under `/dogma/effects/` ### Technical & other terms -* *BSD* — "Branched Static Data" - Old authoring format for game data, not all data has been ported over to the new *FSD* "File Static Data" - No meaningful difference to *FSD* for users -* *FSD* — "File Static Data" - New authoring format for game data, not all data has been ported over - No meaningful difference to *BSD* for users -* *Dogma* - Collective term for *Attributes*, *Effects* and the game logic around them -* *Monolith* - The EVE Online servers (in particular, the database) for the game itself, as opposed to other services like *ESI* +* *BSD* — "Branched Static Data" + Old authoring format for game data, not all data has been ported over to the new *FSD* "File Static Data" + No meaningful difference to *FSD* for users +* *FSD* — "File Static Data" + New authoring format for game data, not all data has been ported over + No meaningful difference to *BSD* for users +* *Dogma* + Collective term for *Attributes*, *Effects* and the game logic around them +* *Monolith* + The EVE Online servers (in particular, the database) for the game itself, as opposed to other services like *ESI* diff --git a/docs/guides/map-data/index.md b/docs/guides/map-data/index.md index 33a249cf..2290b751 100644 --- a/docs/guides/map-data/index.md +++ b/docs/guides/map-data/index.md @@ -2,19 +2,19 @@ ## General Information -Map data is available in the [SDE](../../services/sde/index.md) or through [ESI](../../services/esi/overview/). +Map data is available in the [SDE](../../services/static-data/index.md) or through [ESI](../../services/esi/overview/). Objects like regions, constellations, solarsystems, planets, moons, and other celestial bodies have a position. -There are two kinds of position, each using their own coordinate system: +There are two kinds of position, each using their own coordinate system: -* Relative to the center of the New Eden cluster. (Used by regions, constellations, solarsystems) - The center of the cluster lies near Zarzakh, labelled "Point of No Return" on the in-game map. (See the red dot on the cluster map below) +* Relative to the center of the New Eden cluster. (Used by regions, constellations, solarsystems) + The center of the cluster lies near Zarzakh, labelled "Point of No Return" on the in-game map. (See the red dot on the cluster map below) -* Relative to the center of a solarsystem. (used by planets, moons, stars, as well as other positions within a solarsystem such as killmails) +* Relative to the center of a solarsystem. (used by planets, moons, stars, as well as other positions within a solarsystem such as killmails) The center of a solarsystem is it's star. Not every solarsystem has a star object; for abyssal deadspace systems with neither star nor planet, the origin is an arbitrary point. - Note: The star objects themselves do not have an explicit position in the SDE or ESI, as their position is always `[0.0, 0.0, 0.0]`. + Note: The star objects themselves do not have an explicit position in the SDE or ESI, as their position is always `[0.0, 0.0, 0.0]`. -These coordinate systems have the same scale (1.0 = 1 meter), but different directions. +These coordinate systems have the same scale (1.0 = 1 meter), but different directions. ## Universe @@ -22,13 +22,13 @@ All region (& constellations, solarsystems) share a single coordinate system. Th The SDE organizes regions into folders by kind: -* `/abyssal/`: Abyssal Deadspace, entered through abyssal filaments. (Not to be confused with Pochven) -* `/eve/`: The New Eden Cluster, the main space of the game; Highsec, Lowsec, Nullsec. (Including Pochven) -* `/void/`: Void Regions. Used for the tutorial & certain events. -* `/wormhole/`: Wormhole Space. +* `/abyssal/`: Abyssal Deadspace, entered through abyssal filaments. (Not to be confused with Pochven) +* `/eve/`: The New Eden Cluster, the main space of the game; Highsec, Lowsec, Nullsec. (Including Pochven) +* `/void/`: Void Regions. Used for the tutorial & certain events. +* `/wormhole/`: Wormhole Space. (The SDE also contains a `/landmarks/` folder, which contains landmark information but not regions) -In ESI, the endpoints return data for all regions/constellations/systems. +In ESI, the endpoints return data for all regions/constellations/systems. For both SDE and ESI, different kinds of space can be identified through [ID ranges](../../guides/id-ranges.md). ### Map @@ -43,7 +43,7 @@ Note: This forms a **Left**-Handed coordinate system. If you are using a 3D grap ![New Eden map](./cluster_map.png) -Note on SDE data: +Note on SDE data: Regions, constellations, and solarsystems each have `max` and `min` fields denoting approximate bounding-boxes. These use a different coordinate system to the position field: The minimum and maximum `Z` values are negated. As-is the values are incorrect, and in most cases the `Z` position will not be in the range `Z_min to Z_max`, there are two workarounds: * Negate and swap z-axis `min` and `max` values; `Z_min, Z_max = -Z_max, -Z_min` @@ -57,7 +57,7 @@ When matching the 'Space North' orientation as used by the in-game map (see abov In this orientation, the coordinates have the following directions: -* `+X` is West/Left, `-X` is East/Right. +* `+X` is West/Left, `-X` is East/Right. * `+Y` is Up, `-Y` is Down. * `+Z` is North/Forward, `-Z` is South/Backward. @@ -67,12 +67,12 @@ Note: This is different with the Universe's coordinate system, and is **Right**- ### Combining the coordinate systems -Both coordinate systems have the same scale but different axes. To get the position of a planet within the larger 'universe' coordinate system, it's position can be added to that of the parent star with the x coordinate negated: -x = xsystem - xplanet -y = ysystem + yplanet +Both coordinate systems have the same scale but different axes. To get the position of a planet within the larger 'universe' coordinate system, it's position can be added to that of the parent star with the x coordinate negated: +x = xsystem - xplanet +y = ysystem + yplanet z = zsystem + zplanet -Caution: 32-bit floating point numbers do not have enough precision to handle both the 'large' scale of the interstellar distances and the 'small' scale of interplanetary distances. This results in a loss of precision and graphical glitches on objects distant from the origin. +Caution: 32-bit floating point numbers do not have enough precision to handle both the 'large' scale of the interstellar distances and the 'small' scale of interplanetary distances. This results in a loss of precision and graphical glitches on objects distant from the origin. This problem can be mitigated by either using 64-bit floating point numbers or by using "Floating Origin" techniques. diff --git a/docs/services/sde/index.md b/docs/services/sde/index.md deleted file mode 100644 index 93b1f792..00000000 --- a/docs/services/sde/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Static Data Export ---- -# Static Data Export (SDE) - -Export of static game data (only changing with game updates) - -- [Full SDE (sde.zip)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/sde.zip) - - [FSD Only (fsd.zip)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/fsd.zip) - [(checksum)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/fsd.zip.checksum) - - [BSD Only (bsd.zip)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/bsd.zip) - [(checksum)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/bsd.zip.checksum) - - [Universe Only (universe.zip)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/universe.zip) - [(checksum)](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/universe.zip.checksum) -- [All Checksums](https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/checksum) - -The `Full SDE` package contains the same files as the `FSD`, `BSD`, and `Universe` packages combined. - -Some community members have created tools to help manage the SDE, or to provide them in different formats. diff --git a/docs/services/static-data/index.md b/docs/services/static-data/index.md new file mode 100644 index 00000000..8424c929 --- /dev/null +++ b/docs/services/static-data/index.md @@ -0,0 +1,80 @@ +--- +title: Static Data +--- + +# Static Data + +The Static Data Export (SDE) contains static game data that only changes with game updates. +The latest SDE can be found at: [developers.eveonline.com/static-data/](https://developers.eveonline.com/static-data/) + +## Data formats + +The SDE is available in two formats: + +- [JSON Lines](https://jsonlines.org/) +- [YAML](https://yaml.org/) + +### JSON Lines + +JSON keys must be strings. +When the dataset contains integer keys, these are converted to a list format where each entry contains: + +- `_key`: The actual key value. +- `_value`: The value (when the value is not an object). + +### YAML + +YAML supports integer keys, so it does not require the special encoding used in JSON Lines. +Note that reading large YAML files can be memory-intensive and slow. +When working with large datasets such as `mapMoons` and similar files, consider using the JSON Lines format. + +## Schema Changes + +Schema changes are documented at: [developers.eveonline.com/static-data/tranquility/schema-changelog.yaml](https://developers.eveonline.com/static-data/tranquility/schema-changelog.yaml) + +## Automation + +For automated access to the SDE: + +- **Latest Build Number**: [developers.eveonline.com/static-data/tranquility/latest.jsonl](https://developers.eveonline.com/static-data/tranquility/latest.jsonl). + - The latest build number is in the record with the key `sde`. +- **Data URLs**: `https://developers.eveonline.com/static-data/tranquility/eve-online-static-data--.zip`. +- **Changes**: `https://developers.eveonline.com/static-data/tranquility/changes/.jsonl`. + - This contains the list of changes. + The record with key `_meta` contains `lastBuildNumber`, referring to the previous SDE. + +Lastly, there are a few short-hand URLs to always fetch the latest version. +This will redirect to the URL with the latest build number. + +- JSON Lines: [developers.eveonline.com/static-data/eve-online-static-data-latest-jsonl.zip](https://developers.eveonline.com/static-data/eve-online-static-data-latest-jsonl.zip) +- YAML: [developers.eveonline.com/static-data/eve-online-static-data-latest-yaml.zip](https://developers.eveonline.com/static-data/eve-online-static-data-latest-yaml.zip) + +## HTTP Caching + +All resources fully support ETag and Last-Modified headers. +Resources will only update when they actually change. +All non-static files are cached for 5 minutes. + +## Celestial names + +In the SDE there is generally no mention of the name of stars, planets, moons, asteroid belts, and NPC stations. +This is because they can be deduced from the solar system name, and a few fields related to the celestial object. + +There are a few exceptions; in those cases the celestial has a `name` field with their name. +In all other cases, follow the below table. + +| Celestial | Content | +| -------------------------------- | ------------------------------------------------- | +| Solar System | Solar system name as in `mapSolarSystems` | +| Stars | `` | +| Planets | ` ` | +| Moons | ` - Moon ` | +| Asteroid Belts | ` - Asteroid Belt ` | +| Stations (with `operationID`) | ` - ` | +| Stations (without `operationID`) | ` - ` | + +Note: + +- The `orbitName` is the name of the `orbitID` celestial, constructed via the table above. +- The `celestialIndex` should be represented in Roman numerals. +- For stations, use `corporationID` to look up the name via `npcCorporations`.