Runelite-EssentialsPlus/Item Information.md

# Item Information – Zusammenlegung der Item-Helper

## Ziel

`Item prices`, `Item charges` und das neue Feature `Banked items` werden unter einem gemeinsamen Helper zusammengeführt.

Empfohlener Name:

**Item information**

Alternativen: `Item details`, `Item info`.

Der Nutzer soll einen einzigen Hauptschalter haben. Die einzelnen Informationsarten bleiben per Rechtsklick separat aktivierbar.

## Aktueller Zustand

### Item prices

Implementierung: `helpers/ItemPriceOverlay.java`

- Hover-Tooltip über Inventar- und Bank-Items
- GE-Preis
- High-Alchemy-Wert
- Mengen werden berücksichtigt
- Coins und Platinum-Tokens werden ignoriert
- Optionen:
  - `Show GE price`
  - `Show HA price`

### Item charges

Implementierung:

- `helpers/ItemCharges.java`
- `helpers/ItemChargesOverlay.java`

- Permanente Werte direkt auf Item-Icons
- Inventar
- Ausrüstung
- optional Bank
- Unterstützt viele Charge-/Füllstandsquellen, unter anderem:
  - Varbits
  - Barrows
  - Moon-Ausrüstung
  - Blowpipe mit mehreren Werten
  - Dragonfire-Schilde
  - Schmuck und Tränke
  - Bags, Pouches und Container
  - Master Scroll Book
  - weitere Spezialitems
- Optionen:
  - `Show weapons and armor`
  - `Show looting and coal bags`
  - `Show charges in bank`
  - Textgröße
  - Low-Charge-Warnschwelle
  - Primärfarbe
  - Sekundärfarbe
  - Warnfarbe
  - gespeicherte Charges zurücksetzen
  - Coal-Bag-Daten vergessen

## Neues Feature: Banked items

Beim Hover über ein Item soll im Tooltip zusätzlich die Bankmenge erscheinen.

Beispiel:

```text
GE: 12.3k gp  HA: 4.8k gp
Banked: 300
```

Regeln:

- Die Bankmenge wird nur angezeigt, wenn sie bekannt ist.
- Bei unbekanntem Bestand keine `Banked: 0`-Zeile anzeigen.
- Noted und unnoted Items müssen zusammengefasst werden.
- Die Zuordnung muss über `ItemManager.canonicalize()` erfolgen.
- Bei geöffneter Bank ist der Live-Bankcontainer maßgeblich.
- Bei geschlossener Bank wird der zuletzt bekannte Bankbestand verwendet.
- Bankänderungen müssen über `ItemContainerChanged` berücksichtigt werden.
- Die bestehende Bank-/Container-Speicherung des Plugins soll wiederverwendet werden.

## Zieloberfläche

In der Helpers-Karte gibt es nur noch eine Checkbox:

```text
Item information
```

Tooltip:

```text
Shows item prices, banked quantities and charge information. Right-click for options.
```

Die bisherigen Checkboxen `Item prices` und `Item charges` entfallen.

## Ziel-Rechtsklick-Menü

### Informationsarten

- `Show GE price`
- `Show High Alchemy value`
- `Show banked quantity`
- `Show item charges`

### Charge-Kategorien

Nur relevant, wenn `Show item charges` aktiv ist:

- `Weapons and armor`
- `Bags and containers`

Die bestehende Option `Show charges in bank` wird in den Bereich Anzeigeorte verschoben.

### Anzeigeorte

Preise und Bankmengen sind Hover-Informationen:

- `Show in inventory`
- `Show in bank`

Charges sind Icon-Informationen:

- `Show charges in inventory`
- `Show charges in equipment`
- `Show charges in bank`

Falls eine zu große Anzahl an Optionen vermieden werden soll, kann `Show in inventory` entfallen, weil Inventar standardmäßig immer aktiv ist. Dann bleibt nur:

- `Show in bank`
- `Show charges in equipment`

### Darstellung

- `Text size`
- `Primary color`
- `Secondary color`
- `Warning color`

### Warnungen

`Low-charge warning` mit:

- `Off`
- `≤ 10`
- `≤ 50`
- `≤ 100`
- `≤ 500`
- `≤ 1000`

### Datenverwaltung

- `Reset saved charges`
- `Forget coal bag`

### Zurücksetzen

- `Reset appearance`

## Tooltip-Design

Der bestehende Preis-Tooltip soll zu einem gemeinsamen Tooltip-Builder erweitert werden.

Empfohlene Reihenfolge:

1. GE-Preis
2. High-Alchemy-Wert
3. Bankmenge

Beispiel mit allen Informationen:

```text
GE: 12.3k gp  HA: 4.8k gp
Banked: 300
```

Wenn nur einzelne Informationen aktiviert sind, werden nur diese Zeilen ausgegeben.

Die Charge-Werte bleiben auf den Item-Icons und werden nicht in den Hover-Tooltip verschoben, außer dies wird später ausdrücklich gewünscht.

## Empfohlene interne Struktur

### Gemeinsamer Helper-Schalter

Neuer Hauptschlüssel:

```text
itemInformation
```

Mögliche neue Unteroptionen:

```text
itemInformationGe
itemInformationHa
itemInformationBanked
itemInformationCharges
itemInformationChargesWeapons
itemInformationChargesBags
itemInformationBank
itemInformationEquipment
itemInformationSize
itemInformationColor
itemInformationSecondaryColor
itemInformationLowColor
itemInformationLowAt
```

Die genaue Benennung kann noch angepasst werden. Wichtig ist ein einheitliches Präfix.

### Overlay-Struktur

Empfohlene Varianten:

1. `ItemInformationOverlay` übernimmt den Hover-Tooltip und ruft Preis- und Banked-Provider auf.
2. `ItemChargesOverlay` bleibt für die Icon-Anzeige bestehen.
3. Beide verwenden denselben gemeinsamen Hauptschalter und dieselben zentralen Optionen.

Damit muss die komplexe Charge-Logik nicht unnötig mit der Tooltip-Logik vermischt werden.

Alternativ kann der bestehende `ItemPriceOverlay` umbenannt und erweitert werden. Inhaltlich sollte er aber als allgemeiner Item-Information-Tooltip behandelt werden.

### Bankbestand

Für den Bankbestand sollte keine neue parallele Speicherung eingeführt werden, wenn die vorhandenen Plugin-Daten verwendet werden können.

Benötigt wird eine Methode nach diesem Muster:

```java
long getBankedQuantity(int itemId)
```

Die Methode sollte:

- die Item-ID kanonisieren
- noted/unnoted zusammenführen
- die aktuelle Bank bevorzugen, wenn sie geöffnet ist
- ansonsten den letzten bekannten Bestand verwenden
- bei unbekanntem Item `0` oder einen klar unterscheidbaren „unknown“-Zustand liefern

Wichtig: `0` darf nicht automatisch als „unbekannt“ interpretiert werden. Ein bekannter leerer Bestand und ein unbekannter Bestand müssen unterscheidbar sein.

## Rückwärtskompatibilität

Bestehende Konfigurationswerte sollen zunächst gelesen werden können:

- `itemPrices`
- `itemPricesGe`
- `itemPricesHa`
- `itemCharges`
- `itemChargesWeapons`
- `itemChargesBags`
- `itemChargesBank`
- `itemChargesSize`
- `itemChargesColor`
- `itemChargesSecondaryColor`
- `itemChargesLowColor`
- `itemChargesLowAt`

Mögliche Strategie:

- Neuer Hauptschalter verwendet neue Keys.
- Falls neue Keys noch nicht existieren, werden die alten Werte als Fallback gelesen.
- Alte Einstellungen werden nicht sofort gelöscht.
- Ein späterer Migrationsschritt kann alte Keys übernehmen oder dauerhaft weiter unterstützen.

## Tests

Vor der Implementierung sollten die vorhandenen Tests ausgeführt werden. Relevant sind insbesondere:

- `ItemChargesTest`
- `ItemChargesFullTest`
- Bank-/Container-Tests
- Tests für `ItemManager.canonicalize()`-Verhalten, falls vorhanden

Neue Tests sollten abdecken:

1. GE-Preis allein
2. HA-Wert allein
3. GE und HA zusammen
4. Bankmenge bei normalem Item
5. Bankmenge bei noted/unnoted Kombination
6. unbekannter Bankbestand wird nicht angezeigt
7. bekannter Bankbestand von `0`
8. Bankbestand aktualisiert sich nach Containeränderung
9. gemeinsamer Hauptschalter deaktiviert beide Overlay-Arten
10. Charge-Unteroptionen bleiben funktionsfähig
11. alte Konfigurationswerte werden korrekt übernommen
12. Tooltip erscheint nicht bei Coins/Platinum, sofern das bestehende Verhalten beibehalten werden soll

## Offene Fragen vor der Implementierung

1. Soll der endgültige Name `Item information`, `Item details` oder `Item info` sein?
2. Soll `Banked: 0` bei bekannt leerem Bestand angezeigt werden oder komplett entfallen?
3. Soll der Bankbestand auch beim Hover über ein Item im Bankfenster selbst angezeigt werden?
4. Soll die Bankmenge inklusive Items im Inventar angezeigt werden oder ausschließlich der Bestand in der Bank?
5. Soll `Show in inventory` entfallen, weil Inventar immer aktiv sein soll?
6. Sollen Preise und Bankmenge optional auch auf Item-Icons statt nur im Tooltip erscheinen?
7. Soll die Anzeige von Charges im Bankfenster weiterhin separat schaltbar sein?
8. Soll eine gemeinsame Farbe für alle Tooltip-Zeilen verwendet werden oder behalten GE/HA/Banked eigene Farben?
9. Sollen die alten Config-Keys dauerhaft unterstützt oder nur einmalig migriert werden?
10. Soll das neue Feature standardmäßig deaktiviert bleiben, wie die bisherigen Helper?

## Empfohlene Standardentscheidung

Für eine einfache und übersichtliche erste Version:

- Name: `Item information`
- Ein Hauptschalter
- GE, HA, Banked und Charges separat toggelbar
- Inventar immer aktiv
- Bank-Hover separat toggelbar
- Equipment-Charges separat toggelbar
- Banked zählt nur Bankbestand, nicht Inventar
- unbekannter Bestand wird nicht angezeigt
- vorhandene Charge-Unteroptionen bleiben erhalten
- alte Config-Keys werden als Fallback unterstützt
- Tooltip-Informationen bleiben getrennt von den Charge-Zahlen auf Item-Icons