traderx-tools

Command-line tools for administering the TraderX DayZ trader mod (https://github.com/TheDmitri/TraderX) without hand-editing hundreds of JSON files.

Tool	What it does
traderx_build.py	Maintain your whole trader setup in one human-readable YAML/JSON file (class names, words instead of bitfields, reusable attachment groups, presets) and compile it into the mod's Products/, Categories/, TraderXPresets/ files and trader assignments. Imports TraderPlus, Expansion Market and plain class-list exports.
traderx_check.py	Validate (and optionally fix) an existing TraderX config in place: invalid file names the mod silently skips, dangling references, wrong types, license ids, trader assignments, stale compiled files.
docs/	A configuration guide for TraderX written from the mod's source code – file formats, bitfields, pricing formula, load order and gotchas.

Pure Python 3.8+, standard library only. pyyaml is optional (enables .yaml sources; .json sources work without it).

---

Quick start

git clone <this repo> traderx-tools && cd traderx-tools
pip install -r requirements.txt        # optional, for YAML

# 1. Health-check what you have now (changes nothing)
python3 traderx_check.py ~/serverprofile/TraderX

# 2. Turn the existing config into one editable source file
python3 traderx_build.py import-traderx ~/serverprofile/TraderX -o traderx.yaml

# 3. Add a mod's export as a new category, assigned to a trader
python3 traderx_build.py import-expansion  Terje_Tools.json      --trader Eve   --into traderx.yaml
python3 traderx_build.py import-traderplus SnafuTraderPlus.json  --trader Boris --into traderx.yaml
python3 traderx_build.py import-plain      cans.txt --price 100  --trader Eve   --into traderx.yaml

# 4. Edit traderx.yaml, then preview and write (server stopped)
python3 traderx_build.py build traderx.yaml --out ~/serverprofile/TraderX --dry-run
python3 traderx_build.py build traderx.yaml --out ~/serverprofile/TraderX

Every build takes a timestamped backup, only touches files that actually changed, lists stale files (deleted only with --clean), refuses to write when there are errors, and warns if a Compiled/ folder would shadow your files.

---

Why

TraderX's native format has three properties that make it painful to manage by hand:

1. References by opaque product id (prod_snafu_ak12a_001) instead of class name – attachments, variants, presets and categories all point at ids, and a typo silently drops the reference.
2. Bitfields – tradeQuantity: 78644644 and stockSettings: 138 encode several settings each.
3. No reuse – "every AK gets these 12 optics" means editing 40 files.

traderx_build.py treats the mod's files as a build output. You edit this instead:

groups:
  ak_optics: [SNAFU_AKAimpoint_M5, SNAFU_AKKahles, SNAFU_AKTrijicon]

categories:
  - name: Assault Rifles
    traders: [Boris]
    licenses: [Weapons License]
    price: 1200
    items:
      - SNAFU_AK12A:
          attachments: [ak_optics, "@compat_mags"]
          variants: [SNAFU_AK12A_Tan]
          presets:
            "CQB*": [SNAFU_AKAimpoint_M5]
      - SNAFU_AK103A: {stock: 5, coefficient: 0.95, restart: reset}
  - name: Ammo
    traders: [Boris]
    price: 60
    buy: static 30
    sell: any
    items: [Ammo_762x39, Ammo_545x39]

See docs/source-format.md for the full schema.

---

Documentation

Document	Contents
docs/source-format.md	The YAML/JSON source schema for traderx_build.py – every key, defaults cascade, groups, variants, presets, quantity words
docs/importing.md	How TraderPlus / Expansion / plain exports and an existing TraderX config are mapped into the source
docs/compat.md	Using weapon compatibility files (@compat, @compat_mags) and the compat lookup command
docs/checking.md	traderx_check.py: what it detects, what --fix changes, exit codes
docs/traderx-configuration-guide.md	Reference for TraderX itself: directory layout, load order, product/category/settings files, bitfield layouts, pricing formula, licenses, vehicles, safe zone, troubleshooting
examples/	Sample source files and one sample of each import format

---

Command overview

traderx_build.py import-traderx    <TraderX dir> [-o FILE]
traderx_build.py import-traderplus <file.json>  [--category NAME] [--trader T]... (-o FILE | --into FILE)
traderx_build.py import-expansion  <file|dir>   [--category NAME] [--trader T]... (-o FILE | --into FILE)
traderx_build.py import-plain      <file.txt>   --price N [--category NAME] [--trader T]... (-o FILE | --into FILE)
traderx_build.py build   <source> --out <TraderX dir> [--dry-run] [--clean] [--strict] [--compat FILE]... [--no-backup]
traderx_build.py check   <source> [--strict] [--compat FILE]...
traderx_build.py compat  <ClassName> <compat.json>...

traderx_check.py <TraderX dir> [--fix] [--fix-settings] [--no-backup] [--decode] [--ignore TEXT]... [--no-group] [--quiet-info]

--trader accepts a trader's givenName or npcId from TraderXGeneralSettings.json and is repeatable.

---

Pre-start validation

scripts/prestart-check.sh runs check on the source and traderx_check.py on the profile and exits non-zero on errors, so it can gate a server start:

scripts/prestart-check.sh ~/serverprofile/TraderX traderx.yaml compat.json && ./start-server.sh

---

Compatibility

Written against TraderX main (mod version string 1.0.1, September 2026). The file-name rules, bitfield layouts and preset format are taken from the mod's Enforce Script sources; if a future TraderX release changes them, the constants at the top of both scripts are the place to adjust.

License

MIT – see LICENSE.