Economy Data Dumps - Coder Documentation

The servers generate daily logs of economic activity. This data is publicly accessible and may have many uses. For example:

• Answering questions about the economy, such as relative rarities and the rate that new items are created.
• Tracking where stolen items are sent.
• Tracking PvP activity, including which ships are damaged and which ships take their items.
• Building leaderboards that track wealth, combat performance, or both.

General Information

Files are uploaded daily, at around 0 UTC. They contain data from the previous 24 hours. They should be accessible indefinitely, and once generated, they will not be modified (with the exception of the item schema).

The format should be reasonably stable, but some fields might change, and new information might be added to future dumps. Programs consuming the data shouldn't make assumptions. For instance, a ship ID might be present in the log file but missing from the active ship file.

Dumps do not include any data from the labs.

Dumps are stored at URLs of the form:

https://pub.drednot.io/{INSTANCE}/econ/{YEAR}_{MONTH}_{DAY}/{FILE}

• INSTANCE is either test or prod.
• YEAR, MONTH, and DAY are from the calendar date of the dump.
• FILE is either one of the files listed in the sections below.

FILE: summary.json

This file is un-compressed JSON, and contains some hopefully convenient stats. The hope is that if you want to build a simple app or run a quick test, you can just check the summary files without parsing the larger dumps. The file contains these fields:

• count_ships - The number of entries in the ships file.
• count_logs - The number of entries in the logs file.
• items_held - An object representing the total number of items inside active ships. Maps item ids to the count of that item.
• items_moved - An object representing all voluntary item transfers between ships. Does not include items shot out of ships, or ejected due to cramming. Maps item ids to the count of that item.
• items_new - An array representing all newly generated items, grouped by zone and source. Contains these fields:
  • zone - The zone name that the items were generated in. This is the "pretty" English name of the zone, so it is not stable and subject to change if zones are renamed.
  • src - A string describing the source of the item. These are not stable and may be changed in the future.
  • item - The id of the item.
  • total - The total count dropped. Includes destroyed/expired crates.
  • grabbed - The total count taken by ships. Does not include destroyed/expired crates.

FILE: ships.json.gz

This file is GZIP-COMPRESSED JSON, containing an array of objects. Each object represents a ship that was active and saved during that day, and has these fields:

• hex_code - The hex string used to identify the ship in the logs. Does not include the { } characters.
• name - The user-chosen name. Not filtered for profanity.
• color - The user-chosen color, stored as a 24 bit RGB integer.
• items - An object representing the items stored on the ship, in the final save of the day. Maps item ids to the count of that item.

FILE: log.json.gz

This file is GZIP-COMPRESSED JSON, containing an array of objects. Each object represents either an item being taken from an item crate by a ship, or an item crate being destroyed. These objects contain the following fields:

• time - The approximate unix timestamp of the action. Seconds since 00:00:00 January 1, 1970 UTC.
• zone - The zone that the action occurred in. This is the "pretty" English name of the zone, so it is not stable and subject to change if zones are renamed.
• serv - The server that the action occurred on. The is a zero-based integer, so it is 1 less than the indexes listed in the server dropdown.
• item - The item id in the crate.
• count - The count of the item that was transferred or destroyed.
• src - The source of the item crate. Entries of the form {XXX} represent ships, where XXX is the ship's hex code. Entries of the form {XXX} hurt indicate that the item was not ejected intentionally, it was either shot out or ejected due to cramming. All other entries are drops from bots or the world. These names are not stable and may be changed in the future.
• dst - The destination of the item crate. Entries of the form {XXX} represent ships. Otherwise, the value will be killed, which means the crate was destroyed.

Items intentionally ejected and picked up by the same ship are not included in this file.

FILE: item_schema.json

[NOTE] Only a single instance of this file is generated:

https://pub.drednot.io/{INSTANCE}/econ/item_schema.json

This file will change, but only between updates. Due to aggressive caching, it might take some time to obtain a fresh copy. If you are having trouble, you can try "cache busting" by appending a query parameter.

This file is un-compressed JSON, containing an array of objects. Each object represents a kind of item in the game. The meaning of most fields should be fairly obvious upon some inspection. The same information with more details can be found in the game code, but it seems stupid to tell users that they need to reverse the game to build anything with this.

FILE: bot_drops.txt

[NOTE] Only a single instance of this file is generated:

https://pub.drednot.io/{INSTANCE}/econ/bot_drops.txt

The same points about updates and caching from item_schema.json apply to this.

This file is user-readable plain-text, and lists the drop rates for most bots. Older bots such as those from Vulture are not included.

Initial Dump URLs

PROD: 2022_11_23

• https://pub.drednot.io/prod/econ/item_schema.json
• https://pub.drednot.io/prod/econ/bot_drops.txt
• https://pub.drednot.io/prod/econ/2022_11_23/summary.json
• https://pub.drednot.io/prod/econ/2022_11_23/ships.json.gz
• https://pub.drednot.io/prod/econ/2022_11_23/log.json.gz

TEST: 2022_11_13

• https://pub.drednot.io/test/econ/item_schema.json
• https://pub.drednot.io/test/econ/bot_drops.txt
• https://pub.drednot.io/test/econ/2022_11_13/summary.json
• https://pub.drednot.io/test/econ/2022_11_13/ships.json.gz
• https://pub.drednot.io/test/econ/2022_11_13/log.json.gz