# ScanAlbion — Full Reference

This document outlines the underlying math and data definitions utilized by the ScanAlbion platform.

---

## 1. Quality Codes & Multipliers
- **Normal (1)**: multiplier = 1.0
- **Good (2)**: multiplier = 1.25
- **Outstanding (3)**: multiplier = 1.5
- **Excellent (4)**: multiplier = 6.24
- **Masterpiece (5)**: multiplier = N/A (final state)

---

## 2. Standard Flip Profit Calculation
- **Net Profit**: `netProfit = bmPrice - buyPrice - salesTax - listingFee`
- **Tax rates**: 
  - Premium Active = 4% tax
  - Premium Inactive = 8% tax
  - Listing fee on Black Market (BM) = 0%
  - Listing fee on Royal Markets = 2.5%
- **Cross-Quality Matching**: An Outstanding item (Q3) can satisfy a Good order (Q2) if the profit is higher. Allowed when `qualityBuy >= qualitySell` (item quality bought is higher than or equal to the quality sold to the order).

---

## 3. Reroll Flip (Markov Chain Solver)
Reroll low-quality items to higher qualities at the repair station.
- **Item Value (IV) Formula**: `IV = (Base + Artifact) * 2^enchant`
  - Base: `16 * 3^(tier - 4)`
  - Artifact Offsets: Rune +50, Soul +100, Relic +150, Avalon +200. The offsets are scaled by `3^(tier - 4)` before the enchant multiplier.
  - Final Formula: `IV = (16 * 3^(tier-4) + ArtifactOffset * 3^(tier-4)) * 2^enchant`
- **Quality Probabilities ($P$)**: 
  - Masterpiece = 0.1%
  - Excellent = 0.9%
  - Outstanding = 9.0%
  - Good = 30.0%
  - Normal = 60.0%
- **Expected Reroll Cost**:
  - Expected clicks from state $i$ to target $T$:
    `E(i) = (C_i + sum_{j > i} P_{i -> j} * E(j)) / (1 - P_{i -> i})`
  - Click Cost $C_i$:
    `C_i = IV * 3.97 * qualityMultiplier_i`
  - Cost Multipliers (`qualityMultiplier`):
    - Normal = 1.0
    - Good = 1.25
    - Outstanding = 1.5
    - Excellent = 6.24

---

## 4. Upgrade Flip Material Counts
Counts of upgrade materials (Runes/Souls/Relics/Siphoned) needed to upgrade items by slot type:
- **2H Weapons**: 384
- **Main Hand (1H Weapons)**: 288
- **Armor, Bag**: 192
- **Head, Shoes, Cape, Offhand, Backpack, Tool**: 96
- **Upgrade Paths**: `.0 -> .1` (Runes), `.1 -> .2` (Souls), `.2 -> .3` (Relics), `.3 -> .4` (Siphoned).
- **Total Cost**: `totalCost = buyPrice + (materialPrice * getEnchantMatCount(tier, slot))`

---

## 5. Cargo Optimizer (Bounded Knapsack)
- Sorts stackable commodities by profit density (`profitDensity = netProfit / itemWeight`) descending.
- Greedily fills mount weight capacity within the silver budget:
  - **Stag**: 227 kg
  - **Ox**: 3200 kg
  - **Mammoth**: 22521 kg

---

## 6. Siphoned Energy Tracker Log Format
- Parsed logs are tab-separated (TSV) or comma-separated (CSV) records:
  `Date`, `Player`, `Reason`, `Amount`
  - **Reason**: 'Deposit' or 'Withdrawal' (mapped from 'withdraw', 'wdr', etc.).
  - **Amount**: Integer value.
  - **Net Balance**: `netBalance = totalDeposited - totalWithdrawn`.

---

## 7. WTS Catalog Layout Specifications
- Renders customizable grids for trade lists.
  - Grid Sizes: 3x3, 4x4, 5x5, 6x6.
  - Features: Drag-and-drop cell swaps, client-side canvas compression for base64 images, and browser localStorage to cloud sync database endpoint merging.