############## 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. .. code-block:: . ..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 .. code-block:: html Below you can find some useful snippets of requests: List of item categories on RU realm ----------------------------------- .. code-block:: 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 ---------------------------------------- .. code-block:: 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 ---------------------------------------- .. code-block:: 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`` ------------------------------------------------- .. code-block:: 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 =============== .. image:: img/item-info-ui.png :width: 700 At the root level all items are described similar to the following example: .. code-block:: json { "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: .. code-block:: json "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: .. code-block:: json "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.