# Importing

All importers produce (or append to) a source file; they never write into the TraderX
profile directly. Review the result, then `build`.

Common options:

| Option | Meaning |
|---|---|
| `-o FILE` | Write a new source file (default `source.yaml`, or `source.json` without pyyaml) |
| `--into FILE` | Append the imported categories into an existing source (creates it if missing). Name clashes get ` (imported)` appended. |
| `--category NAME` | Override the category name |
| `--trader T` | Assign the category to trader `T` (givenName or npcId). Repeatable. |

---

## `import-traderx` – reverse-import an existing config

```bash
python3 traderx_build.py import-traderx ~/serverprofile/TraderX -o traderx.yaml
```

Reads `TraderXConfig/Products`, `Categories`, `TraderXPresets` and `TraderXGeneralSettings.json`:

- every product keeps its `id:` so stock files in `TraderXDatabase/Stock/` keep matching;
- bitfields are decoded to words (`buy: static 22`, `restart: reset`);
- attachments/variants/presets are written as class names;
- products in no category go under top-level `items:`;
- license ids become license names; trader assignments become `traders:`.

Files the mod would skip (bad names, invalid JSON, non-object files) are skipped here
too and printed. Run `traderx_check.py` first if you want them fixed.

After the import the file is verbose – every product spells out its options. Most of it
collapses once you move shared attachment lists into `groups:` and delete options that
equal the defaults.

---

## `import-traderplus` – TraderPlus v1 `TraderPlusPriceConfig.json`

```bash
python3 traderx_build.py import-traderplus SnafuTraderPlus.json --trader Boris --into traderx.yaml
```

Accepts the full file (`TraderCategories: [...]`), a single category object, or a bare list
of category objects. Each `CategoryName` becomes a category. Product lines
`class,coefficient,maxStock,tradeQuantity,buyPrice,sellPrice` map 1:1; whitespace around
class names is trimmed, malformed lines are reported and skipped.

Options equal to the defaults (`coefficient 1`, `maxStock -1`, `buy full / sell full`) are
omitted to keep the output short.

---

## `import-expansion` – Expansion Market `.json` (file or folder)

```bash
python3 traderx_build.py import-expansion ExpansionMod/Market/ --trader Eve --into traderx.yaml
```

A folder imports every `*.json` inside as one category each. Mapping per item:

| Expansion | Source |
|---|---|
| `DisplayName` | category `name` (`#Terje_Tools` → `Terje Tools`) |
| `ClassName` | item |
| `MaxPriceThreshold` | `price` |
| `SellPricePercent` (≥0) | `sell` = price × percent |
| `SellPricePercent` (-1) | omitted → `sell_percent` default applies |
| `MaxStockThreshold > 1` and `Min ≠ Max price` | `stock` = max, `coefficient` ≈ (min/max)^(1/(stock−1)) |
| otherwise | unlimited, flat price |
| `QuantityPercent` 0 / 100 / n | `buy: empty` / `full` / `coef n%` |
| `SpawnAttachments` | `attachments` |
| `Variants` | `variants` |

Expansion's `MaxStockThreshold: 1, MinStockThreshold: 1` with equal prices is its idiom for
"always available at a fixed price", which is what unlimited flat stock means in TraderX.

---

## `import-plain` – class list

```bash
python3 traderx_build.py import-plain cans.txt --category Cans --price 100 --trader Eve --into traderx.yaml
```

One class per line. Lines may carry `,buyPrice[,sellPrice]`; lines without a price get the
category `price` from `--price`. `#` comments and blank lines are ignored. Separators can
be `,`, `;` or tab.

---

## Merging strategy

A typical layout is one source file per server with imported categories appended over
time. If you prefer one file per mod, keep them in JSON/YAML and concatenate the
`categories` lists yourself, or use `--into` with a scratch file and copy blocks across.
The builder doesn't care where a category came from.