desired_ilvl.json vs desired_ilvl_list.json in AzerothAuctionAssassin

The single-object desired_ilvl.json is deprecated legacy code, while the array-based desired_ilvl_list.json is the actively maintained format that supports multiple ilvl sniping rules and additional filtering options.

When configuring item level (ilvl) sniping in the ff14-advanced-market-search/azerothauctionassassin repository, users encounter two similarly named JSON files in the AzerothAuctionAssassinData/ directory. Understanding the difference between desired_ilvl.json and desired_ilvl_list.json is critical because only one format is actively used by the current scanner engine, while the other exists solely for backward compatibility.

Structural Differences Between the Two Formats

Legacy Single-Rule Format (desired_ilvl.json)

desired_ilvl.json stores a single JSON object defining one sniping rule. It supports basic fields including ilvl, buyout, sockets, speed, leech, avoidance, and item_ids.

{
  "ilvl": 360,
  "buyout": 1000,
  "sockets": false,
  "speed": true,
  "leech": false,
  "avoidance": false,
  "item_ids": [204965, 204930]
}

This format restricts users to one ilvl configuration and requires explicit item_ids. The file appears in .gitignore and the Dockerfile creates an empty placeholder with printf "{}" > /app/AzerothAuctionAssassinData/desired_ilvl.json to prevent deployment errors for legacy setups.

Modern Multi-Rule Format (desired_ilvl_list.json)

desired_ilvl_list.json stores a JSON array of objects, allowing multiple independent sniping rules in one file. Each object supports all legacy fields plus required_min_lvl, required_max_lvl, max_ilvl, and bonus_lists. Crucially, entries can omit item_ids to create "broad group" rules that match any item meeting the ilvl criteria.

[
  {
    "ilvl": 457,
    "buyout": 175001,
    "sockets": false,
    "speed": false,
    "leech": false,
    "avoidance": false,
    "item_ids": [208420]
  },
  {
    "ilvl": 470,
    "buyout": 250001,
    "sockets": false,
    "speed": false,
    "leech": false,
    "avoidance": false
  }
]

Code Implementation and Parsing

How the List Format Is Parsed

The active parsing logic resides in utils/mega_data_setup.py within the MegaData.__set_desired_ilvl_list() method (lines 320-388). This function reads desired_ilvl_list.json, groups entries by ilvl, and builds comprehensive sniping entries.

# utils/mega_data_setup.py

def __set_desired_ilvl_list(self, path_to_data=None):
    item_list_name = "desired_ilvl_list"
    file_name = f"{item_list_name}.json"
    env_var_name = item_list_name.upper()
    ilvl_info = {}

    # Group items by ilvl or treat as "broad" groups

    ilvl_groups = defaultdict(list)
    broad_groups = []
    for item in ilvl_info:
        if "item_ids" not in item or len(item["item_ids"]) == 0:
            broad_groups.append(item)
        else:
            ilvl_groups[item["ilvl"]].append(item["item_ids"])

    DESIRED_ILVL_LIST = []

    # Build a sniping entry for each ilvl group

    for ilvl, item_id_groups in ilvl_groups.items():
        all_item_ids = [i for g in item_id_groups for i in g]
        item_names, item_ids, base_ilvls, base_required_levels = get_ilvl_items(ilvl, all_item_ids)
        for item in ilvl_info:
            if item["ilvl"] == ilvl:
                snipe_info, _ = self.__set_desired_ilvl(item, item_names, base_ilvls, base_required_levels)
                DESIRED_ILVL_LIST.append(snipe_info)

    # Build entries for "broad" groups (no ilvl or IDs supplied)

    if broad_groups:
        item_names, item_ids, base_ilvls, base_required_levels = get_ilvl_items()
        for item in broad_groups:
            snipe_info, _ = self.__set_desired_ilvl(item, item_names, base_ilvls, base_required_levels)
            DESIRED_ILVL_LIST.append(snipe_info)

    return DESIRED_ILVL_LIST

The resulting self.DESIRED_ILVL_LIST contains fully populated dictionaries with item_names, base_ilvls, and required_min_lvl that the scanner consumes during live auctions.

The Deprecated Placeholder

In the same file, the code initializes self.DESIRED_ILVL_ITEMS and self.min_ilvl as empty placeholders marked for deprecation:

# utils/mega_data_setup.py

self.DESIRED_ILVL_ITEMS, self.min_ilvl = {}, 100000

No functional code path populates this variable from desired_ilvl.json. The scanner in mega_alerts.py (lines 299-322) exclusively iterates over self.DESIRED_ILVL_LIST, making the legacy file format operationally irrelevant.

Functional Capabilities and Use Cases

Capability	desired_ilvl.json	desired_ilvl_list.json
Structure	Single JSON object	JSON array of objects
Rule Count	One rule only	Unlimited rules
Required Fields	Must include item_ids	Can omit item_ids for broad matching
Advanced Filters	Not supported	Supports required_min_lvl, required_max_lvl, max_ilvl, bonus_lists
UI Support	None	Import/export via node-ui/mega-alerts.js and node-ui/main.js
Engine Usage	Ignored by scanner	Consumed by mega_alerts.py

The modern format enables complex scenarios like sniping any item above ilvl 470 regardless of specific ID, or setting different buyout thresholds for different ilvl ranges. The UI components in the node-ui/ directory specifically handle serialization and deserialization of desired_ilvl_list.json for user management.

Summary

• desired_ilvl.json is a deprecated, single-object format maintained only for backward compatibility; the scanner ignores its contents.
• desired_ilvl_list.json is the current standard—a JSON array supporting multiple rules, broad group matching (without item_ids), and advanced filtering options.
• The parsing logic in utils/mega_data_setup.py method __set_desired_ilvl_list() exclusively handles the list format, populating self.DESIRED_ILVL_LIST for use by mega_alerts.py.
• The Dockerfile creates an empty desired_ilvl.json placeholder to prevent legacy deployment scripts from failing, though the application never reads from it.

Frequently Asked Questions

Can I still use desired_ilvl.json for ilvl sniping?

No. The current engine only reads from DESIRED_ILVL_LIST, which is populated exclusively from desired_ilvl_list.json. The legacy file is initialized as an empty dictionary in utils/mega_data_setup.py and never processed by the scanning logic in mega_alerts.py.

How do I convert my old desired_ilvl.json to the new format?

Wrap your existing single object in square brackets to convert it to a JSON array, then rename the file to desired_ilvl_list.json. For example, change { "ilvl": 360... } to [ { "ilvl": 360... } ]. The UI components in node-ui/mega-alerts.js also provide import/export functionality to manage these configurations graphically.

What happens if both files exist in AzerothAuctionAssassinData?

The scanner prioritizes desired_ilvl_list.json through the __set_desired_ilvl_list() method. The DESIRED_ILVL_ITEMS variable remains an empty placeholder ({}, 100000), so desired_ilvl.json has no effect on live scans even if present in the directory.

Why does the Dockerfile create an empty desired_ilvl.json?

The build process runs printf "{}" > /app/AzerothAuctionAssassinData/desired_ilvl.json to maintain backward compatibility with legacy deployment scripts that expect the file to exist. This prevents runtime file-not-found errors for older configurations, even though the application logic no longer consumes the file's contents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}