# Infrastructure & Game Interaction Projects

## Nexus.GameOffsets — Memory Layout Definitions

Pure offset structs for POE2 game memory. No logic, no reading — just struct layouts.

**Contents:**
- **Entities/**: `EntityStruct`, `EntityDetails`, `ComponentLookup`, `ComponentNameAndIndex`, `ItemStruct`, `EntityTreeNode`
- **Components/** (22 structs): Actor, Animated, Buffs, Chest, Life, Mods, Player, Positioned, Render, Stats, Targetable, Transitionable, WorldItem, etc.
- **States/**: `InGameState`, `AreaInstance`, `AreaLoading`, `ServerData`, `WorldData`, `Inventory`, `ImportantUiElements`
- **Natives/**: C++ STL memory layouts — `StdVector`, `StdMap`, `StdList`, `StdBucket`, `StdWString`, `StdTuple`

**Key offsets:**
- Actor skills: 0xB00 (ActiveSkillsVector), 0xB18 (CooldownsVector)
- UIElement: 0x10 (Children), 0x98 (StringId), 0x180 (Flags), 0x448 (Text)
- Entity: 0x80 (ID), 0x84 (Flags), 0x08 (EntityDetails)

**Dependencies**: None. Used by Memory and Data layers.

---

## Nexus.Screen — Screen Capture, OCR & Detection

Screen capture, OCR, image processing, grid/item detection, loot label detection.

### Core Components

| Class | Purpose |
|-------|---------|
| ScreenReader | Main facade — OCR, template matching, screenshot, diff OCR |
| IScreenCapture | Desktop duplication or GDI capture |
| IOcrEngine | Interface for OCR backends (Win native, EasyOCR, OneOCR, WinOCR) |
| PythonOcrBridge | Calls Python script via subprocess for EasyOCR/YOLO |

### Grid & Item Detection

| Class | Purpose |
|-------|---------|
| GridReader | Reads stash/inventory grids (12-col 70×70px or 24-col 35×35px) |
| GridHandler | Template matching for cell occupancy, item size detection |
| TemplateMatchHandler | NCC-based visual matching (find identical items in grid) |
| DetectGridHandler | Edge detection to find grid boundaries |

### Detection Systems

| Class | Purpose |
|-------|---------|
| EnemyDetector | YOLO/ONNX object detection for enemy positions |
| BossDetector | Boss-specific recognition |
| HudReader | HUD element OCR (HP bar, mana, buffs) |
| GameStateDetector | Main menu vs in-game state |
| ScreenReader.DetectLootLabels() | Three-pass loot detection (polygon, contour, yellow text) |

### Frame Pipeline

Pub-sub for screen frames: `FramePipeline` distributes captured frames to multiple `IFrameConsumer` implementations (GameState, Enemy, Boss detectors, Minimap, Navigation).

**Used by**: Bot, Navigation, Inventory, Ui

---

## Nexus.Game — Game Interaction

Low-level game control — window focus, input sending, clipboard operations.

| Class | Purpose |
|-------|---------|
| GameController | Main facade — focus, chat, input, shortcuts |
| InputSender | Win32 SendInput (scan codes), Bézier mouse movement, Ctrl+click |
| WindowManager | SetForegroundWindow (with alt-key trick), GetWindowRect |
| ClipboardHelper | System clipboard read/write |

**Key operations:**
- `FocusWindow()` — SetForegroundWindow + alt-key trick (required for background processes)
- `CtrlRightClick()` — buying from seller stash
- `MoveMouse()` — Bézier curve smooth move
- `MoveMouseInstant()` — direct teleport (no interpolation)
- `TypeText()`, `SelectAll()`, `Paste()` — clipboard operations

**Used by**: Inventory, Trade, Items, Navigation, Bot

---

## Nexus.Log — Game Log Watcher

Parses Client.txt game log at 200ms poll intervals.

| Event | Pattern |
|-------|---------|
| AreaEntered | `[SCENE] Set Source [AreaName]` or `You have entered AreaName` |
| WhisperReceived | Incoming whisper messages |
| WhisperSent | Outgoing whisper messages |
| TradeAccepted | Trade completion |
| PartyJoined/Left | Party state changes |
| LineReceived | Raw log lines |

`CurrentArea` detected from log tail on startup. Used by Bot (reset navigation on area change), Inventory (wait for area transitions), Navigation.

---

## Nexus.Trade — Trade Daemon IPC

Manages trade search monitoring via external Node.js Playwright daemon.

### TradeDaemonBridge

Spawns `node tools/trade-daemon/daemon.mjs`, communicates via stdin/stdout JSON.

**Commands (→ daemon):**
- `start`, `addSearch`, `addDiamondSearch`
- `pauseSearch`, `clickTravel`
- `openScrapPage`, `reloadScrapPage`, `closeScrapPage`

**Events (← daemon):**
- `newListings` → `NewListings(searchId, items[])`
- `diamondListings` → `DiamondListings(searchId, pricedItems[])`
- `wsClose` → websocket disconnection

**Trade flow**: Website "Travel to Hideout" button → stash opens → Ctrl+right-click to buy → `/hideout` to go home → store items

---

## Nexus.Items — Item Parsing

Parse item text from clipboard (Ctrl+C) using Sidekick item parser library.

| Class | Purpose |
|-------|---------|
| ItemReader | Move to item → Ctrl+C → read clipboard → parse |
| SidekickBootstrapper | Initialize Sidekick parser on first use |

**Used by**: Bot (identify items during scraping)

---

## Nexus.Inventory — Stash & Grid Management

Scan player inventory, track item placement, deposit to stash.

| Class | Purpose |
|-------|---------|
| InventoryManager | Main interface — scan, deposit, clear |
| InventoryTracker | Cell occupancy matrix + item metadata |
| StashCalibrator | Grid boundary calibration via edge detection |

**Key operations:**
- `ScanInventory()` → screenshot + grid scan → populate tracker
- `DepositItemsToStash()` → find stash NPC → click items with Shift+Ctrl
- `DepositAllToOpenStash()` → scan → click first occupied → repeat
- `ClearToStash()` → scan → deposit all → return to hideout
- `EnsureAtOwnHideout()` → `/hideout` command if needed

**Grid calibration (2560×1440):**
- Cell sizes: 70×70px (12-col) or 35×35px (24-col), all 840px wide
- Inventory (12×5): origin (1696, 788)
- Stash 12×12: origin (23, 169) or (23, 216) in folder

---

## Nexus.Navigation — Minimap-Based Movement

Real-time navigation using minimap image matching + pathfinding. Separate from Nexus.Pathfinding (which is grid-based A*).

| Class | Purpose |
|-------|---------|
| NavigationExecutor | State machine: Capture → Process → Plan → Move → Stuck |
| MinimapCapture | Frame pipeline consumer — wall color detection, checkpoint detection |
| WorldMap | Position matching via cross-correlation, canvas stitching |
| StuckDetector | No-progress detection |
| WallColorTracker | Learns wall palette from initial spawn |

**Flow**: Capture minimap → detect position via wall color stitching → pathfind → send WASD keys

---

## Nexus.Bot — Top-Level Orchestration

Central coordinator that wires everything together.

| Class | Purpose |
|-------|---------|
| BotOrchestrator | DI container, state machine, frame pipeline management |
| TradeExecutor | Single trade flow (navigate → buy → deposit) |
| MappingExecutor | Map exploration (navigate + loot) |
| KulemakExecutor | Boss fight with arena mechanics |
| CraftingExecutor | Crafting bench operations |
| DiamondExecutor | Diamond trade handling |
| ScrapExecutor | Vendor scrapping |
| TradeQueue | FIFO queue of trade tasks |
| LinkManager | Trade search management |

**Bot modes**: Trading, Mapping, Crafting (via BotMode enum)

---

## Nexus.Ui — Avalonia Desktop Application

Entry point executable. Avalonia 11.2 + CommunityToolkit.MVVM + FluentTheme.

**App.xaml.cs** wires all DI:
- Services: ConfigStore, GameController, ScreenReader, ClientLogWatcher, TradeMonitor, InventoryManager
- Bot: FramePipelineService, LinkManager, TradeExecutor, TradeQueue, BotOrchestrator, ModPoolService
- ViewModels: Main, Debug, Settings, Mapping, Atlas, Crafting, Memory, Nexus, ObjectBrowser

**Additional dependencies**: Vortice.Direct2D1 (overlay rendering), Microsoft.Extensions.DependencyInjection

**Views**: MainWindow, DebugWindow, SettingsWindow, MappingWindow, etc. with MVVM bindings.