Items Database

Information about most of the in-game items is available in json format in our GitHub Repository. Changes to that repository are automatically pushed when game is updated.

https://github.com/EXBO-Studio/stalcraft-database/

Database Structure

Database provides both item information, and icons. Items first grouped by realm, then by content type, then by category.

.<realm>
..items
...weapon
....pistol
.....0n9q.json
.....32XR.json
....sniper_rifle
.....1gE9.json
.....5DwQ.json
..icons
...weapon
....pistol
.....0N9q.png
.....32XR.png

Both jsons and icons named using Item ID to which they correspond to. When working with API treat Item IDs as opaque, case sensitive strings.

Acquiring Items Information

Locally

The easiest way to work with data is to just download it as zip archive and process it locally. To do that open github repository page, click on Code button, and then Download ZIP

Using Github API

Alternatively, you can utilise Github API to retrieve files in automated way, and always have access to last version of the data

You can also embed file content directly on your website. For example, to embed icon of the pistol weapon 0n9q you can use the following tag

<img src="https://github.com/EXBO-Studio/stalcraft-database/raw/main/ru/icons/weapon/pistol/0n9q.png"/>

Below you can find some useful snippets of requests:

List of item categories on RU realm

GET https://api.github.com/repos/EXBO-Studio/stalcraft-database/contents/ru/items/
Accept: application/vnd.github+json

List of weapon subcategories on RU realm

GET https://api.github.com/repos/EXBO-Studio/stalcraft-database/contents/ru/items/weapon
Accept: application/vnd.github+json

List of pistol weapons on RU realm

GET https://api.github.com/repos/EXBO-Studio/stalcraft-database/contents/ru/items/weapon/pistol
Accept: application/vnd.github+json

Get item information about pistol with id 0n9q

GET https://raw.githubusercontent.com/EXBO-Studio/stalcraft-database/main/ru/items/weapon/pistol/0n9q.json

Interpreting Items Information

JSON object which describes an item is a direct translation of in-game UI into a machine readable format.

Item Properties

_images/item-info-ui.png

At the root level all items are described similar to the following example:

{
  "id": "y1q9",
  "category": "weapon/submachine_gun",
  "name": {
    "type": "translation",
    "key": "item.wpn.mp5_mod.name",
    "args": {},
    "lines": {
      "ru": "«Гадюка»",
      "en": "Viper"
    }
  },
  "color": "RANK_STALKER",
  "status": {
    "state": "PERSONAL_ON_USE"
  },
  "infoBlocks": [ <...> ]
}
This object has following properties:

  • id - unique identifier of this items, matches file name

  • category - category in which item is located

  • name - text object which represents human readable item name. See Interpreting Translated String

  • color - semantic description of the color. For artefacts it will represent it’s quality, for all other items it will represent it’s rank

  • infoBlocks - rest of the item information is organized in so called ‘info blocks’. See Interpreting Information Blocks

Interpreting Translated String

Item information contains a lot of texts which are meant to be shown to the player. Since the game has to support multiple languages, texts are not represented as simple json strings, but as objects which knows how they should be displayed when translated.

For example, every item information object has a name property at the root level. Usually it looks like the following way:

"name": {
  "type": "translation",
  "key": "item.wpn.mp5_mod.name",
  "args": {},
  "lines": {
    "ru": "«Гадюка»",
    "en": "Viper"
  }
}
This object is of type translation, which implies that it will always have following parameters

  • key - unique key which identifies this line in all possible translations. Hint: these keys persistent, so you can use them to lookup specific information from item data.

  • args - some translated lines can be parametrised with arguments, in which case they will be listed in this dictionary

  • lines - contains translations of this line to all supported languages

Alternatively, string object may look like:

"name": {
 "type": "text",
 "text": "$5"
}

This object is of type text, which implies that it is just a simple text line which should be shown the same way for all languages. The text which must be shown is stored in text property.

Note

Occasionally some translated texts may contain ‘@’ symbols. They should be treated as line breaks.

Interpreting Information Blocks

Due to diversity of items in the game, we need to have a flexible format which allows to represent all kinds of data. This is solved by splitting information into several types of blocks, which contain different types of data.

All info blocks contain type parameter which allows to identify what type of data it contains and how it should be interpeted.

Text Block

The simplest info block type is text, contains following properties:

  • title - optional text object which represents title of the block

  • text - contains text object which is displayed in this block

Damage Ramp Block

Block which describes damage ramp which is shown in every weapon description, contains following properties:

  • startDamage - weapon damage at distance of 0 meters

  • damageDecreaseStart - distance in meters at which damage starts to decrease

  • damageDecreaseEnd - distance in meters at which damage stops decreasing

  • endDamage - weapon damage at distance defined by damageDecreaseEnd

  • maxDistance - max distance in meters after which weapon deals no damage

List Block

The most common type of block, which represents a list of elements which are displayed within it, contains following properties:

  • title - optional text object which represents title of the block

  • elements - similar to info blocks, it is a list of elements of various types which are displayed in this list. Type of element is also inferred from type property of each element. See below for types of elements.

Numeric Element
Element with type numeric, contains following properties:

  • name - text object which represents name of this element. Hint: you can extract specific values by looking at name.key property.

  • value - value of this element, as float.

An example of numeric element is the weight property which every item has. In game it can be shown as Weight: 2.5 kg.

Key-Value Element
Element with type key-value, contains following properties:

  • key - text object which represents name of this element

  • value - text object which represents value of this element

An example of key-value element is the Class property of items. For example in game it can be shown as Class: Backpacks and Containers

Range Element
Element with type range, contains following properties:

  • name - text object which represents name of this element

  • min - minimal value of the range, as float

  • max - maximum value of the range, as float

An example of range element is the parameters of artefacts which have not yet been researched. E.g. in game you can see Carry weight: [+3; +5]

Text Element

Element with type text, contains only property text, which is text object which is shown in place of this element.

This element is similar to Text Block, but can be shown a part of List Block.

Price Element
Element with type price, contains following properties:

  • currency - identifier of the currency

  • amount - price which should be displayed

Although items database currently doesn’t have an example of such element, it may be seen in game when hovering item while looking at the list of offers from trader NPC.

Item Element

Element with type item, contains only name property which is the name of some item which should be displayed.

Although functionally it is similar to text element, it is used to provide different semantic meaning.