# ItemMetadata Dormant Tables — Wiring Notes

**Status as of v12.67.0:** Three tables in `Data/ItemMetadata.lua` are populated
with curated data but have zero consumers. They were prepared for tooltip and
filter features that were planned but not yet shipped. This document captures
what each table holds, how to read it, and what the eventual feature would
look like.

The tables are now lazy-loaded — they cost nothing at runtime today (no
decoder runs because nothing accesses them). When a future feature is wired
up, the first indexed access materializes all five ItemMetadata tables in one
shot via the `_ItemMetadataLoader` hook.

---

## Table 1: PvPSourceItems

**Shape:** `[itemID] = true` — sparse boolean set.
**Population:** 5,832 items flagged as PvP-sourced (honor, conquest, arena,
battlegrounds vendors).

### How to use

Truthy check:
```lua
if ETB.PvPSourceItems and ETB.PvPSourceItems[itemID] then
    -- This item is PvP-sourced
end
```

If iterating (e.g., to count PvP items in a category, or pre-build a filter):
```lua
if ETB._ItemMetadataLoader then
    ETB._ItemMetadataLoader()
    ETB._ItemMetadataLoader = nil
end
for itemID in pairs(ETB.PvPSourceItems) do ... end
```

### Suggested feature integrations

1. **Filter toggle in MainFrame**: "Hide PvP gear" / "Show only PvP gear"
   checkbox in the sidebar. Filtering implementation lives in
   `Modules/Filtering.lua` — add a new filter predicate that consults
   `ETB.PvPSourceItems[itemID]`.

2. **Tooltip line in TooltipEnhancer**: When hovering an item that's in
   the set, append a "Source: PvP" line near the existing source-info
   panel. This pairs naturally with the existing source-type taxonomy
   (`SOURCE_TYPES.VENDOR_HONOR`, `VENDOR_CONQUEST` etc. from the planning
   docs).

3. **Source category tag**: Show a small icon or color marker on item
   rows in the main grid for PvP-sourced gear, so users browsing
   transmog can see at a glance what came from PvP.

### Caveats

- The data is presence-only — it doesn't distinguish honor vs conquest vs
  arena vs BG. If finer-grained breakdown is needed later, the source data
  would need re-extraction.
- Items added in patches after the data was scraped will be missing.

---

## Table 2: VendorCosts

**Shape:** `[itemID] = { {tag, ...}, {tag, ...}, ... }`
where each cost is one of:
- `{"i", costItemID, qty}` — costs an item (e.g., a token)
- `{"c", currencyID, qty}` — costs a currency (e.g., Justice Points = 395,
  Valor Points = 396)
- `{"g", copperAmount}` — costs gold (no item/currency, just `tag` + amount)

**Population:** 3,559 items with vendor cost data. Distribution: 3,617 item
costs, 552 currency costs, 12 gold costs (one item can have multiple costs).

### How to use

Lookup:
```lua
local costs = ETB.VendorCosts and ETB.VendorCosts[itemID]
if costs then
    for _, cost in ipairs(costs) do
        local tag = cost[1]
        if tag == "i" then
            local costItemID, qty = cost[2], cost[3]
            -- e.g., "Costs 25 of [Greater Mark of Honor]"
        elseif tag == "c" then
            local currencyID, qty = cost[2], cost[3]
            -- e.g., "Costs 2,200 Justice Points"
        elseif tag == "g" then
            local copper = cost[2]
            -- e.g., "Costs 1,250g 0s 0c" (1,250 gold = 12,500,000 copper)
        end
    end
end
```

### Suggested feature integrations

1. **Tooltip line in TooltipEnhancer**: Below the existing item info,
   show "Vendor cost: 2,200 Justice Points" or "Vendor cost: 1,250g".
   Use Blizzard's built-in `GetCurrencyInfo(currencyID)` for currency
   names. Use `GetCoinTextureString(copper)` for gold formatting.

2. **Sort by cost**: A "sort by vendor cost" option in the item grid,
   useful for users farming a specific currency.

3. **Currency-budget filter**: "Show items I can afford with my current
   Justice Points" — needs live currency-balance lookup via
   `GetCurrencyInfo` + filter that compares.

### Caveats

- **Currency IDs are Blizzard-defined.** Some MoP-era currencies (Justice
  395, Valor 396, Conquest 390, Honor 392) survive into MoP Classic;
  others may not.
- **Gold amounts are in copper.** WoW stores gold as copper internally
  (1g = 10000c). The 12 gold-cost entries appear to be high-end vendor
  items.
- The "i" item cost form is mostly for tokens (e.g., Honor tokens, raid
  tier tokens) — `GetItemInfo(costItemID)` will give the token's name.

---

## Table 3: ReputationReqs

**Shape:** `[itemID] = {factionID, repAmount}`
**Population:** 912 items with reputation requirements.

### Important: rep amount, not standing level

The original comment at the table header says:
> Standings: 0=Hated 1=Hostile 2=Unfriendly 3=Neutral 4=Friendly 5=Honored 6=Revered 7=Exalted

**That comment is misleading.** The actual second value is the *raw reputation
amount* (e.g., 9000, 21000, 42000), not a standing-level index. To convert:

| Standing  | Raw rep threshold | Raw value seen in data |
|-----------|-------------------|------------------------|
| Hated     | -42000 to -6001   | (none)                 |
| Hostile   | -6000 to -3001    | (none)                 |
| Unfriendly| -3000 to 0        | (none)                 |
| Neutral   | 0 to 2999         | (none seen)            |
| Friendly  | 3000 to 8999      | (some at 3000)         |
| Honored   | 9000 to 20999     | **9000** (most common) |
| Revered   | 21000 to 41999    | **21000**              |
| Exalted   | 42000+            | **42000**              |

So `[itemID] = {529, 21000}` means "requires Revered with faction 529
(Argent Dawn)".

### How to use

```lua
local req = ETB.ReputationReqs and ETB.ReputationReqs[itemID]
if req then
    local factionID, repAmount = req[1], req[2]
    local factionName, _, standingID, barMin, barMax, currentRep =
        GetFactionInfoByID(factionID)
    if factionName then
        local needed = repAmount - currentRep
        if needed <= 0 then
            -- player meets the requirement
        else
            -- player needs `needed` more rep with `factionName`
        end
    end
end
```

### Suggested feature integrations

1. **Tooltip line**: "Requires: Revered with Argent Dawn" below the
   existing requirements lines. Convert raw value to standing label
   using the threshold table above.

2. **Player-aware tooltip**: If we know the player's current rep with
   the faction (via `GetFactionInfoByID`), color-code the requirement
   green if met, yellow if close, red if far.

3. **Filter "items I can buy now"**: Cross-reference player's current
   rep across all factions and filter items where they meet the
   requirement.

### Caveats

- `GetFactionInfoByID` may return nil for factions the player has never
  encountered. Handle nil gracefully.
- Some factions have negative reputation requirements (anti-rep) for
  hostile factions — the data here shouldn't have any (all 912 entries
  use positive values), but defensive code is good practice.
- Faction IDs are Blizzard's internal IDs; they're stable across patches
  but you'll need to know which one is which (e.g., 529 = Argent Dawn,
  510 = Sha'tar). A lookup table or just calling `GetFactionInfoByID`
  to get the name is fine.

---

## How to wire up a feature using these tables

The general pattern matches existing tooltip enhancements in
`Modules/TooltipEnhancer.lua`:

```lua
-- In TooltipEnhancer.lua's tooltip-add hook:

local function _addPvPSourceLine(tooltip, itemID)
    if ETB.PvPSourceItems and ETB.PvPSourceItems[itemID] then
        tooltip:AddLine("|cff66bbffSource: PvP|r", 1, 1, 1)
    end
end

local function _addVendorCostLines(tooltip, itemID)
    local costs = ETB.VendorCosts and ETB.VendorCosts[itemID]
    if not costs then return end
    tooltip:AddLine("|cff888888Vendor cost:|r", 1, 1, 1)
    for _, cost in ipairs(costs) do
        local tag = cost[1]
        if tag == "g" then
            tooltip:AddLine("  " .. GetCoinTextureString(cost[2]), 1, 1, 1)
        elseif tag == "c" then
            local info = GetCurrencyInfo(cost[2])  -- currency name + icon
            tooltip:AddLine(string.format("  %d %s", cost[3], info or ("currency#" .. cost[2])), 1, 1, 1)
        elseif tag == "i" then
            local name = GetItemInfo(cost[2])
            tooltip:AddLine(string.format("  %d x %s", cost[3], name or ("item#" .. cost[2])), 1, 1, 1)
        end
    end
end

local function _addRepReqLine(tooltip, itemID)
    local req = ETB.ReputationReqs and ETB.ReputationReqs[itemID]
    if not req then return end
    local factionID, repAmount = req[1], req[2]
    local factionName = GetFactionInfoByID(factionID)
    if not factionName then return end
    local standing = "Friendly"
    if repAmount >= 42000 then standing = "Exalted"
    elseif repAmount >= 21000 then standing = "Revered"
    elseif repAmount >= 9000 then standing = "Honored"
    end
    tooltip:AddLine(string.format("|cffff8800Requires: %s with %s|r",
        standing, factionName), 1, 1, 1)
end
```

These hooks can be wired up incrementally — none of them require
materializing the tables ahead of time, because indexed access via
`ETB.X[itemID]` triggers the lazy-loader on first hit.

---

## Why these tables stayed dormant

Best guess from the planning docs: the original ETB roadmap called for a
comprehensive item-source taxonomy, with tooltip enrichment being part of
the broader source-info project. The taxonomy work and the boss-loot
tooltip got built. The vendor-cost / reputation / PvP-source tooltip
features were lower-priority polish items that never got prioritized
above the next round of item data quality work.

The data itself was probably extracted along with everything else from
AtlasLoot's MIT-licensed source files, since AtlasLoot has all of this
information for the same items. So the cost of populating these tables
was already paid; only the consumer-side wiring is missing.
