TraderX_Tools/README.md

# 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

```bash
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:

```yaml
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](docs/source-format.md) for the full schema.

---

## Documentation

| Document | Contents |
|---|---|
| [docs/source-format.md](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](docs/importing.md) | How TraderPlus / Expansion / plain exports and an existing TraderX config are mapped into the source |
| [docs/compat.md](docs/compat.md) | Using weapon compatibility files (`@compat`, `@compat_mags`) and the `compat` lookup command |
| [docs/checking.md](docs/checking.md) | `traderx_check.py`: what it detects, what `--fix` changes, exit codes |
| [docs/traderx-configuration-guide.md](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/](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:

```bash
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](LICENSE).