simulation done
This commit is contained in:
parent
0e7de0a5f3
commit
05bbcb244f
55 changed files with 4367 additions and 756 deletions
188
docs/architecture-overview.md
Normal file
188
docs/architecture-overview.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
# Nexus — Architecture Overview
|
||||
|
||||
## What Is This
|
||||
|
||||
A modular C# automation framework for POE2. The system reads game memory, builds a structured game state, runs AI systems (combat, navigation, threat assessment), and emits input commands. A separate trade pipeline monitors the trade site via a Node.js daemon and executes buy flows.
|
||||
|
||||
When the real game isn't available, a standalone **Simulator** replaces the memory layer with a procedural game world — same bot systems, same interfaces, zero game dependency.
|
||||
|
||||
## Solution Structure
|
||||
|
||||
```
|
||||
Nexus.sln (net8.0-windows10.0.19041.0)
|
||||
│
|
||||
├── Core Layer (shared types, no dependencies)
|
||||
│ └── Nexus.Core
|
||||
│
|
||||
├── Infrastructure Layer (reads from external sources)
|
||||
│ ├── Nexus.GameOffsets Pure offset structs for memory reading
|
||||
│ ├── Nexus.Memory Process memory reading (RPM, pattern scan)
|
||||
│ ├── Nexus.Screen Screen capture, OCR, grid detection
|
||||
│ ├── Nexus.Log Client.txt game log watcher
|
||||
│ └── Nexus.Input Win32 SendInput / Interception driver
|
||||
│
|
||||
├── Data Layer (transforms raw data into typed game state)
|
||||
│ └── Nexus.Data EntityMapper, EntityClassifier, GameDataCache, MemoryPoller, GameStateEnricher
|
||||
│
|
||||
├── Logic Layer (AI systems that decide what to do)
|
||||
│ ├── Nexus.Systems ThreatSystem, MovementSystem, CombatSystem, ResourceSystem, LootSystem
|
||||
│ ├── Nexus.Engine BotEngine (orchestrator), AreaProgressionSystem, MovementKeyTracker
|
||||
│ └── Nexus.Pathfinding NavigationController, A* PathFinder
|
||||
│
|
||||
├── Game Interaction Layer (acts on the game)
|
||||
│ ├── Nexus.Game Window focus, input sending, clipboard
|
||||
│ ├── Nexus.Items Item parsing via Sidekick
|
||||
│ ├── Nexus.Inventory Stash/inventory grid management
|
||||
│ ├── Nexus.Navigation Minimap-based real-time navigation
|
||||
│ └── Nexus.Trade Trade daemon IPC (Node.js Playwright)
|
||||
│
|
||||
├── Orchestration Layer (top-level coordination)
|
||||
│ ├── Nexus.Bot BotOrchestrator, Trade/Mapping/Crafting executors
|
||||
│ └── Nexus.Ui Avalonia 11.2 desktop GUI (entry point)
|
||||
│
|
||||
└── Testing Layer
|
||||
└── Nexus.Simulator Standalone game world for bot testing
|
||||
```
|
||||
|
||||
## Dependency Flow
|
||||
|
||||
```
|
||||
Nexus.Core
|
||||
│
|
||||
├── Nexus.GameOffsets ──→ Nexus.Memory ──→ Nexus.Data ──→ Nexus.Engine
|
||||
│ │ │
|
||||
├── Nexus.Input │ Nexus.Systems
|
||||
│ │ │
|
||||
├── Nexus.Screen ◄───────────────────────────────┘ │
|
||||
├── Nexus.Game │
|
||||
├── Nexus.Log │
|
||||
│ │
|
||||
├── Nexus.Pathfinding ◄─────────────────────────────────────────┘
|
||||
│
|
||||
├── Nexus.Items, Nexus.Inventory, Nexus.Navigation, Nexus.Trade
|
||||
│
|
||||
├── Nexus.Bot (consumes all above)
|
||||
│
|
||||
├── Nexus.Ui (DI hub, entry point, consumes all)
|
||||
│
|
||||
└── Nexus.Simulator (Core, Data, Systems, Pathfinding — NOT Memory/Input/Screen)
|
||||
```
|
||||
|
||||
## Data Flow — Per Tick
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ MemoryPoller Thread (60Hz hot / 10Hz cold) │
|
||||
│ │
|
||||
│ Hot tick (4 RPM calls): │
|
||||
│ Camera matrix, Player position, Player vitals, Loading state │
|
||||
│ │
|
||||
│ Cold tick (full hierarchical read): │
|
||||
│ Entity tree traversal → classification → EntitySnapshot[] │
|
||||
│ Terrain grid, Skills, Quests, UI elements │
|
||||
│ │
|
||||
│ Writes to GameDataCache (volatile references, lock-free) │
|
||||
└────────────────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ BotEngine Logic Thread (25Hz default) │
|
||||
│ │
|
||||
│ 1. Read latest GameState from cache │
|
||||
│ 2. GameStateEnricher → NearestEnemies, ThreatMap, DangerLevel │
|
||||
│ 3. Clear ActionQueue │
|
||||
│ 4. NavigationController.Update() → path, DesiredDirection │
|
||||
│ 5. Run systems in priority order: │
|
||||
│ ThreatSystem (50) → MovementSystem (100) → │
|
||||
│ AreaProgressionSystem (199) → NavigationSystem (200) → │
|
||||
│ CombatSystem (300) → ResourceSystem (400) → LootSystem (500) │
|
||||
│ 6. ActionQueue.Resolve() → conflict resolution │
|
||||
│ 7. ExecuteActions() → IInputController │
|
||||
└────────────────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ IInputController (Win32 SendInput or Interception driver) │
|
||||
│ │
|
||||
│ WASD keys (scan codes), mouse movement (Bézier curves), │
|
||||
│ skill casts, flask presses, clicks │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Action Resolution
|
||||
|
||||
Systems submit actions to a shared `ActionQueue`. The queue resolves conflicts:
|
||||
|
||||
| Action Type | Behavior |
|
||||
|-------------|----------|
|
||||
| FlaskAction | Always passes through |
|
||||
| MoveAction (priority ≤ 10) | Urgent flee — blocks CastAction |
|
||||
| MoveAction (priority > 10) | Normal move — allows CastAction alongside |
|
||||
| CastAction | Passes unless blocked by urgent flee |
|
||||
| Other (Key, Click, Chat) | Always passes through |
|
||||
|
||||
Priority values: lower number = higher priority. ThreatSystem uses priority 5 for emergency flee (blocks all casting).
|
||||
|
||||
## System Priority Table
|
||||
|
||||
| Priority | System | Purpose |
|
||||
|----------|--------|---------|
|
||||
| 50 | ThreatSystem | Emergency flee on High/Critical danger |
|
||||
| 100 | MovementSystem | Soft avoidance via inverse-square repulsion |
|
||||
| 199 | AreaProgressionSystem | Quest-driven area traversal and transitions |
|
||||
| 200 | NavigationSystem | Submits NavigationController's direction |
|
||||
| 300 | CombatSystem | Skill rotation, target selection, kiting |
|
||||
| 400 | ResourceSystem | Flask usage on life/mana thresholds |
|
||||
| 500 | LootSystem | Item pickup (stub) |
|
||||
|
||||
## Thread Model
|
||||
|
||||
| Thread | Rate | Responsibility |
|
||||
|--------|------|----------------|
|
||||
| MemoryPoller | 60Hz hot, 10Hz cold | Read game memory → GameDataCache |
|
||||
| BotEngine Logic | 25Hz | Run AI systems → emit actions |
|
||||
| Render (Simulator only) | vsync | ImGui + Veldrid drawing |
|
||||
| Trade Daemon | event-driven | Node.js Playwright → stdin/stdout JSON IPC |
|
||||
| Log Watcher | 200ms poll | Client.txt → area/whisper/trade events |
|
||||
|
||||
Cross-thread safety: GameDataCache uses `volatile` references. No locks — writer (MemoryPoller) atomically swaps reference types, readers (BotEngine) get consistent snapshots.
|
||||
|
||||
## Simulator Architecture
|
||||
|
||||
When the real game isn't available, `Nexus.Simulator` replaces the memory pipeline:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Nexus.Simulator.exe │
|
||||
│ │
|
||||
│ ┌──────────┐ GameState ┌──────────────────┐ │
|
||||
│ │ SimWorld │───────────────►│ GameDataCache │ │
|
||||
│ │ (terrain, │ SimPoller + │ (same as prod) │ │
|
||||
│ │ enemies, │ StateBuilder └────────┬─────────┘ │
|
||||
│ │ player) │ │ │
|
||||
│ └─────┬────┘ ┌────────▼─────────┐ │
|
||||
│ │ │ Bot Systems │ │
|
||||
│ │◄─────────────────────│ (unchanged) │ │
|
||||
│ │ SimInputController └──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────▼───────────────────────────────────────┐ │
|
||||
│ │ ImGui + Veldrid Renderer (isometric 2D) │ │
|
||||
│ └─────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Bot systems don't know they're in a simulation — they see identical `GameState` objects and emit actions to `IInputController`.
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Immutable records (GameState, EntitySnapshot) | Thread-safe sharing without locks |
|
||||
| Priority-based ActionQueue | Natural conflict resolution without hardcoded if-else |
|
||||
| Two-tier memory polling (hot/cold) | Balance responsiveness (position at 60Hz) with CPU cost (entities at 10Hz) |
|
||||
| Scan codes over virtual keys | Games read hardware scan codes, not VK codes |
|
||||
| Separate Memory → Data layers | Memory reads raw bytes; Data interprets and classifies. Clean testability. |
|
||||
| IInputController interface | Swap real Win32 input for simulated input without changing bot logic |
|
||||
| BFS exploration + A* pathfinding | BFS finds what to explore; A* finds how to get there |
|
||||
| CharacterProfile auto-detection | Automatically applies combat/flask settings per character name |
|
||||
| External daemons (Trade, OCR) | Isolate browser/OCR concerns from main process |
|
||||
158
docs/core.md
Normal file
158
docs/core.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# Nexus.Core — Shared Types & Abstractions
|
||||
|
||||
The foundation layer. Every other project depends on Core. Contains no logic — only types, interfaces, configuration, and utilities.
|
||||
|
||||
## GameState
|
||||
|
||||
Central immutable snapshot updated once per tick. All systems read from this; none mutate it.
|
||||
|
||||
```
|
||||
GameState
|
||||
├── Timing: TickNumber, DeltaTime, TimestampMs
|
||||
├── Player: PlayerState
|
||||
│ ├── CharacterName, Position, Z, HasPosition
|
||||
│ ├── Life/Mana/ES: Current, Total, Percent (derived)
|
||||
│ ├── ActionId (actor animation state)
|
||||
│ ├── Skills: SkillState[] (cooldowns, charges, cast state)
|
||||
│ ├── Flasks: FlaskState[] (charges, active, cooldown)
|
||||
│ └── Buffs: Buff[] (name, duration, charges, isDebuff)
|
||||
├── Entities: EntitySnapshot[] (all game entities)
|
||||
├── HostileMonsters: EntitySnapshot[] (alive monsters, filtered)
|
||||
├── NearbyLoot: EntitySnapshot[] (world items, filtered)
|
||||
├── NearestEnemies: EntitySnapshot[] (sorted by distance — enriched)
|
||||
├── Terrain: WalkabilitySnapshot (grid, offsets)
|
||||
├── Area: AreaHash, AreaLevel, CurrentAreaName
|
||||
├── UI: IsLoading, IsEscapeOpen, CameraMatrix
|
||||
├── Quests: ActiveQuests[], UiQuests[], Quests[] (enriched with paths)
|
||||
├── Threats: ThreatMap (zone buckets, centroid, rarity flags)
|
||||
├── Danger: DangerLevel (Safe/Low/Medium/High/Critical — enriched)
|
||||
└── GroundEffects: GroundEffect[] (hazard positions)
|
||||
```
|
||||
|
||||
## EntitySnapshot
|
||||
|
||||
Immutable record for any game entity:
|
||||
|
||||
- **Identity**: Id (uint), Path, Metadata, Category (EntityCategory enum)
|
||||
- **Spatial**: Position (Vector2), Z, DistanceToPlayer
|
||||
- **Combat**: IsAlive, LifeCurrent/Total, IsTargetable, ThreatLevel, Rarity, ModNames
|
||||
- **State**: ActionId, IsAttacking, IsMoving, Components (HashSet)
|
||||
- **Special**: TransitionName/State, ItemBaseName, IsQuestItem, LabelOffset
|
||||
|
||||
**EntityCategory** (17 types): Unknown, Player, Monster, Npc, WorldItem, Chest, Shrine, Portal, AreaTransition, Effect, Terrain, MiscObject, Waypoint, Door, Doodad, TownPortal, Critter
|
||||
|
||||
**MonsterRarity**: White, Magic, Rare, Unique
|
||||
|
||||
**MonsterThreatLevel**: None, Normal, Magic, Rare, Unique
|
||||
|
||||
## Actions
|
||||
|
||||
Polymorphic action system. All inherit from `BotAction` with a `Priority` field.
|
||||
|
||||
| Action | Fields | Purpose |
|
||||
|--------|--------|---------|
|
||||
| MoveAction | Direction (Vector2) | WASD movement |
|
||||
| CastAction | SkillScanCode, TargetScreenPos or TargetEntityId | Skill usage |
|
||||
| FlaskAction | FlaskScanCode | Flask consumption |
|
||||
| KeyAction | ScanCode, Type (Press/Down/Up) | Raw keyboard |
|
||||
| ClickAction | ScreenPosition, Type (Left/Right/Middle) | Mouse click |
|
||||
| ChatAction | Message | Send chat message |
|
||||
| WaitAction | DurationMs | Delay |
|
||||
|
||||
## ActionQueue
|
||||
|
||||
Manages conflict resolution between competing system outputs.
|
||||
|
||||
**Resolve() rules:**
|
||||
1. FlaskActions always pass through
|
||||
2. Get highest-priority MoveAction and CastAction
|
||||
3. If MoveAction priority ≤ 10 (urgent flee): include move, **block** cast
|
||||
4. Else: include both move and cast
|
||||
5. All other action types pass through
|
||||
|
||||
## ISystem Interface
|
||||
|
||||
```csharp
|
||||
public interface ISystem
|
||||
{
|
||||
int Priority { get; } // Execution order (lower = first)
|
||||
string Name { get; }
|
||||
bool IsEnabled { get; set; }
|
||||
void Update(GameState state, ActionQueue actions);
|
||||
}
|
||||
```
|
||||
|
||||
**SystemPriority constants**: Threat=50, Movement=100, Navigation=200, Combat=300, Resource=400, Loot=500
|
||||
|
||||
## IInputController Interface
|
||||
|
||||
Abstraction over Win32 input. Two implementations: SendInputController (vanilla), InterceptionInputController (driver).
|
||||
|
||||
```csharp
|
||||
public interface IInputController
|
||||
{
|
||||
bool IsInitialized { get; }
|
||||
void KeyDown(ushort scanCode);
|
||||
void KeyUp(ushort scanCode);
|
||||
void KeyPress(ushort scanCode, int holdMs = 50);
|
||||
void MouseMoveTo(int x, int y);
|
||||
void SmoothMoveTo(int x, int y); // Bézier curve interpolation
|
||||
void LeftClick(int x, int y);
|
||||
void RightClick(int x, int y);
|
||||
void MiddleClick(int x, int y);
|
||||
void LeftDown(); void LeftUp();
|
||||
void RightDown(); void RightUp();
|
||||
}
|
||||
```
|
||||
|
||||
## WalkabilitySnapshot
|
||||
|
||||
Grid-based terrain with offset support for infinite expansion:
|
||||
|
||||
```csharp
|
||||
public record WalkabilitySnapshot
|
||||
{
|
||||
public int Width, Height;
|
||||
public byte[] Data; // Row-major; 0=wall, nonzero=walkable
|
||||
public int OffsetX, OffsetY; // Absolute grid coords of top-left corner
|
||||
|
||||
public bool IsWalkable(int gx, int gy)
|
||||
{
|
||||
var lx = gx - OffsetX; // Absolute → local
|
||||
var ly = gy - OffsetY;
|
||||
if (out of bounds) return false;
|
||||
return Data[ly * Width + lx] != 0;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Coordinate conversion: `WorldToGrid = 23f / 250f ≈ 0.092`
|
||||
- World → Grid: `gx = (int)(worldX * WorldToGrid)`
|
||||
- Grid → World: `worldX = gx / WorldToGrid`
|
||||
|
||||
## Configuration
|
||||
|
||||
**BotConfig** — Static bot parameters:
|
||||
- Tick rates: LogicTickRateHz=60, MemoryPollRateHz=30
|
||||
- Movement: SafeDistance=400, RepulsionWeight=1.5, WaypointReachedDistance=80
|
||||
- Humanization: MinReactionDelayMs=50, MaxReactionDelayMs=150, ClickJitterRadius=3, MaxApm=250
|
||||
|
||||
**CharacterProfile** — Per-character settings:
|
||||
- Skills (8 slots: LMB, RMB, MMB, Q, E, R, T, F) with priority, cooldown, range, target selection
|
||||
- Flasks (thresholds, scan codes, cooldown)
|
||||
- Combat (global cooldown, attack/safe/kite ranges)
|
||||
|
||||
**SkillProfile** — Per-skill configuration:
|
||||
- InputType (KeyPress/LeftClick/RightClick/MiddleClick)
|
||||
- TargetSelection (Nearest/All/Rarest/MagicPlus/RarePlus/UniqueOnly)
|
||||
- RequiresTarget, IsAura, IsMovementSkill, MaintainPressed
|
||||
- MinMonstersInRange (AOE threshold)
|
||||
|
||||
## Utilities
|
||||
|
||||
- **WorldToScreen.Project()** — Matrix projection: world coords → screen coords via camera matrix
|
||||
- **TerrainQuery.HasLineOfSight()** — Bresenham line walk on walkability grid
|
||||
- **TerrainQuery.FindWalkableDirection()** — Rotates direction ±45°/90°/135°/180° to find clear path
|
||||
- **Helpers.Sleep()** — Task delay with ±10% variance
|
||||
- **DangerLevel**: Safe, Low, Medium, High, Critical
|
||||
- **ThreatMap**: TotalHostiles, CloseRange(<300), MidRange(300-600), FarRange(600-1200), ClosestDistance, ThreatCentroid, HasRareOrUnique
|
||||
229
docs/data-and-memory.md
Normal file
229
docs/data-and-memory.md
Normal file
|
|
@ -0,0 +1,229 @@
|
|||
# Nexus.Data & Nexus.Memory — The Data Pipeline
|
||||
|
||||
## Overview
|
||||
|
||||
Two-layer architecture: **Memory** reads raw bytes from the game process; **Data** interprets, classifies, and caches them. This separation keeps memory reading logic free of business rules and makes the data layer testable independently.
|
||||
|
||||
```
|
||||
Game Process (RPM)
|
||||
│
|
||||
▼
|
||||
Nexus.Memory (raw reads, no business logic)
|
||||
│ GameMemoryReader → hierarchical state tree
|
||||
│ EntityList → red-black tree traversal
|
||||
│ ComponentReader → ECS component extraction
|
||||
│
|
||||
▼
|
||||
Nexus.Data (interpretation, classification, caching)
|
||||
│ MemoryPoller → two-tier event loop
|
||||
│ EntityMapper → Memory.Entity → Core.EntitySnapshot
|
||||
│ EntityClassifier → path + components → EntityCategory
|
||||
│ GameStateEnricher → derived threat/danger metrics
|
||||
│
|
||||
▼
|
||||
GameDataCache (volatile references, lock-free)
|
||||
│
|
||||
▼
|
||||
Bot Systems (read-only consumers)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GameDataCache — Single Source of Truth
|
||||
|
||||
Thread-safe, volatile reference holder. Writer: MemoryPoller thread. Readers: bot systems.
|
||||
|
||||
**Hot fields** (updated at 60Hz — 4 lightweight RPM calls):
|
||||
- CameraMatrix (64 bytes)
|
||||
- PlayerPosition (X, Y, Z)
|
||||
- PlayerVitals (HP, mana, ES current/max)
|
||||
- IsLoading, IsEscapeOpen
|
||||
|
||||
**Cold fields** (updated at 10Hz — full hierarchical read):
|
||||
- Entities, HostileMonsters, NearbyLoot
|
||||
- Terrain (WalkabilitySnapshot)
|
||||
- AreaHash, AreaLevel, CurrentAreaName
|
||||
- Quest data (linked lists, UI groups, state entries)
|
||||
- LatestState (complete GameState)
|
||||
|
||||
**Slow fields** (updated at 1Hz):
|
||||
- Character name
|
||||
- Quest linked lists, quest state entries
|
||||
|
||||
No locks — relies on volatile reference semantics for atomic swaps.
|
||||
|
||||
---
|
||||
|
||||
## MemoryPoller — Two-Tier Event Loop
|
||||
|
||||
Owns the memory-reading background thread.
|
||||
|
||||
### Hot Tick (60Hz)
|
||||
|
||||
4 pre-resolved RPM calls using cached addresses:
|
||||
1. Camera matrix (64 bytes from cached address)
|
||||
2. Player position (12 bytes: X, Y, Z)
|
||||
3. Player vitals (24 bytes: HP, mana, ES)
|
||||
4. Loading/escape state (pointer dereference + int)
|
||||
|
||||
No allocations, no GC. Targeting ~3-5ms per tick.
|
||||
|
||||
### Cold Tick (10Hz, every 6th hot tick)
|
||||
|
||||
Full hierarchical read:
|
||||
1. `GameMemoryReader.ReadSnapshot()` — cascades through state tree
|
||||
2. Re-resolve hot addresses via `ResolveHotAddresses()`
|
||||
3. `BuildGameState()` — map entities, filter lists, process quests
|
||||
4. `GameStateEnricher.Enrich()` — compute derived fields
|
||||
5. Update all cache fields
|
||||
|
||||
### BuildGameState() Flow
|
||||
|
||||
```
|
||||
ReadSnapshot() → GameStateSnapshot (raw)
|
||||
│
|
||||
├── Entity mapping:
|
||||
│ for each entity in snapshot:
|
||||
│ EntityMapper.MapEntity(entity, playerPos) → EntitySnapshot
|
||||
│
|
||||
├── Filter into:
|
||||
│ - HostileMonsters (Category==Monster && IsAlive)
|
||||
│ - NearbyLoot (Category==WorldItem)
|
||||
│ - All entities
|
||||
│
|
||||
├── Quest processing:
|
||||
│ - Filter active (StateId > 0)
|
||||
│ - Resolve state text via QuestStateLookup
|
||||
│ - Convert to QuestProgress, QuestInfo
|
||||
│
|
||||
└── Returns GameState
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GameMemoryReader — Hierarchical State Tree
|
||||
|
||||
Top-level orchestrator. Creates sub-readers on `Attach()`:
|
||||
|
||||
```
|
||||
GameStates (top)
|
||||
└── InGameState
|
||||
├── AreaInstance
|
||||
│ ├── EntityList (MSVC std::map red-black tree)
|
||||
│ ├── PlayerSkills (Actor component)
|
||||
│ ├── QuestStates (dat file entries)
|
||||
│ └── Terrain (walkability grid)
|
||||
├── UIElements (quest linked lists, UI tree)
|
||||
└── WorldData (camera matrix)
|
||||
```
|
||||
|
||||
Each `RemoteObject` caches its data and depends on parent for context. Single `Update()` call cascades through tree.
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **ProcessMemory**: P/Invoke wrapper for ReadProcessMemory. Tracks reads/sec and KB/sec.
|
||||
- **MemoryContext**: Shared state — process handle, offsets, module base, pattern scanner.
|
||||
- **ComponentReader**: Reads ECS components (Life, Render, Mods, etc.) from entities.
|
||||
- **MsvcStringReader**: Reads MSVC std::wstring (SSO-aware: inline if capacity ≤ 8, heap pointer otherwise).
|
||||
- **PatternScanner**: AOB scan for resolving base addresses.
|
||||
|
||||
---
|
||||
|
||||
## EntityList — Tree Traversal
|
||||
|
||||
Reads entities from AreaInstance's MSVC std::map (red-black tree, in-order traversal).
|
||||
|
||||
**Tree node layout:**
|
||||
```
|
||||
+0x00: left child ptr
|
||||
+0x08: parent ptr
|
||||
+0x10: right child ptr
|
||||
+0x28: entity pointer
|
||||
```
|
||||
|
||||
**Optimization**: Tree order is cached — re-walked only when entity count changes.
|
||||
|
||||
**Per-entity reads:**
|
||||
1. Path (EntityDetails → std::wstring)
|
||||
2. Skip low-priority types (effects, terrain, critters — no components read)
|
||||
3. Position (Render component: X, Y, Z)
|
||||
4. Component lookup (STL hash map: name → index)
|
||||
5. Component data:
|
||||
- Targetable (bool flag)
|
||||
- Mods/ObjectMagicProperties (rarity)
|
||||
- Life (HP, dynamic — re-read every frame for monsters)
|
||||
- Actor (action ID)
|
||||
- WorldItem (inner entity for ground loot)
|
||||
- AreaTransition (destination area)
|
||||
|
||||
**Caching strategy:**
|
||||
- Stable per entity: path, component list, targetable, rarity, transition name
|
||||
- Dynamic (re-read every frame): monster HP, action ID
|
||||
|
||||
---
|
||||
|
||||
## EntityClassifier — Path + Components → Category
|
||||
|
||||
Single source of truth for entity classification.
|
||||
|
||||
1. **Path-based** (primary): Parses `Metadata/[Category]/...` path segments
|
||||
2. **Component override**: Monster, Chest, Shrine, Waypoint, AreaTransition, Portal, TownPortal, NPC, Player
|
||||
|
||||
Output: `EntityCategory` (Core enum, 17 types)
|
||||
|
||||
---
|
||||
|
||||
## EntityMapper — Memory.Entity → Core.EntitySnapshot
|
||||
|
||||
Transforms raw memory data to enriched snapshots:
|
||||
|
||||
```
|
||||
Memory.Entity (raw)
|
||||
│
|
||||
├── Copy: ID, path, metadata, position, Z, vitals, components, mods
|
||||
├── Classify: EntityClassifier.Classify(path, components) → EntityCategory
|
||||
├── Threat level: Rarity → MonsterThreatLevel
|
||||
├── Area name: AreaNameLookup.Resolve() for transitions
|
||||
├── Distance: Vector2.Distance(position, playerPos)
|
||||
└── Alive state: HasVitals ? LifeCurrent > 0 : true
|
||||
│
|
||||
▼
|
||||
Core.EntitySnapshot (public, classified, enriched)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GameStateEnricher — Derived Metrics
|
||||
|
||||
Computed once per cold tick, before systems run.
|
||||
|
||||
**NearestEnemies**: HostileMonsters sorted by distance to player.
|
||||
|
||||
**ThreatMap**:
|
||||
- TotalHostiles, CloseRange (<300u), MidRange (300-600u), FarRange (600-1200u)
|
||||
- ClosestDistance, ThreatCentroid (position average), HasRareOrUnique
|
||||
|
||||
**DangerLevel** — Weighted threat score:
|
||||
```
|
||||
score = Σ (distance_weight × rarity_multiplier)
|
||||
|
||||
Distance weights: <200u = 3×, <400u = 2×, else = 1×
|
||||
Rarity multipliers: Unique=5×, Rare=3×, Magic=1.5×, White=1×
|
||||
|
||||
Life override: HP < 30% → Critical, HP < 50% → High
|
||||
Score thresholds: ≥15 = Critical, ≥8 = High, ≥4 = Medium, >0 = Low, 0 = Safe
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Architectural Patterns
|
||||
|
||||
| Pattern | Implementation |
|
||||
|---------|---------------|
|
||||
| Lock-free cross-thread | Volatile references in GameDataCache; no locks needed |
|
||||
| Two-tier polling | Hot (4 RPM, 60Hz) + Cold (full read, 10Hz) |
|
||||
| Hierarchical caching | Each RemoteObject caches data, re-reads only on change |
|
||||
| Entity caching | Stable data cached per entity/zone; dynamic data (HP) re-read per frame |
|
||||
| Separation of concerns | Memory: raw bytes. Data: interpretation + classification |
|
||||
| Area name resolution | AreaNameLookup loads areas.json, caches ID → display name |
|
||||
| Area graph | BFS pathfinding for quest progression ordering |
|
||||
197
docs/engine-and-systems.md
Normal file
197
docs/engine-and-systems.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
# Nexus.Engine & Nexus.Systems — Bot Brain
|
||||
|
||||
## BotEngine (Orchestrator)
|
||||
|
||||
The main loop. Owns systems, navigation, profiles, and action execution.
|
||||
|
||||
### Logic Loop (25Hz, background thread)
|
||||
|
||||
```
|
||||
1. Wait for MemoryPoller to provide latest GameState
|
||||
2. CheckCharacterProfile() → auto-load profile if character changed
|
||||
3. GameStateEnricher.Enrich() → compute NearestEnemies, ThreatMap, DangerLevel
|
||||
4. Clear ActionQueue
|
||||
5. NavigationController.Update(state) → compute path, set DesiredDirection
|
||||
6. Run all ISystem implementations in priority order
|
||||
7. NavigationSystem submits MoveAction if DesiredDirection is set
|
||||
8. ActionQueue.Resolve() → merge conflicts
|
||||
9. ExecuteActions() → emit key/mouse/click commands via IInputController
|
||||
```
|
||||
|
||||
### Action Execution
|
||||
|
||||
| Action | Execution |
|
||||
|--------|-----------|
|
||||
| MoveAction | Direction → MovementKeyTracker → WASD key state changes (delta-based) |
|
||||
| CastAction | SmoothMoveTo target + key press. Re-projects moving entities. Adds ±30-50px jitter. |
|
||||
| FlaskAction | Direct key press |
|
||||
| KeyAction | Press/Down/Up operations |
|
||||
| ClickAction | Left/Right/Middle click at screen position |
|
||||
|
||||
### MovementKeyTracker
|
||||
|
||||
Converts world-space direction vectors to WASD keys for isometric camera:
|
||||
|
||||
```
|
||||
1. Rotate direction 45° to align with isometric axes
|
||||
2. sx = dir.X * cos(45°) - dir.Y * sin(45°)
|
||||
3. sy = dir.X * sin(45°) + dir.Y * cos(45°)
|
||||
4. W if sy > 0.3, S if sy < -0.3, D if sx > 0.3, A if sx < -0.3
|
||||
5. Only emit key changes (delta-based — no redundant KeyDown/KeyUp)
|
||||
```
|
||||
|
||||
### Mouse Drift (Navigation)
|
||||
|
||||
During navigation, lazily repositions the mouse toward enemy clusters:
|
||||
- Projects enemy centroid ahead of player movement
|
||||
- Applies ±25° angular offset for organic appearance
|
||||
- Fires every 800-1500ms (randomized)
|
||||
|
||||
### Safety
|
||||
|
||||
- Releases all held keys when loading screen or escape menu detected
|
||||
- CombatSystem's `ReleaseAllHeld()` called on state transitions
|
||||
|
||||
---
|
||||
|
||||
## Systems
|
||||
|
||||
### ThreatSystem (Priority 50)
|
||||
|
||||
Emergency threat response. Runs first, only acts on elevated danger.
|
||||
|
||||
| Danger | Response |
|
||||
|--------|----------|
|
||||
| Safe / Low | No action |
|
||||
| Medium | No action (MovementSystem handles soft avoidance) |
|
||||
| High | Flee toward safety (priority 50, allows casting) |
|
||||
| Critical or point-blank (<150 units) | **Urgent flee (priority 5) — blocks all casting** |
|
||||
|
||||
**Flee direction**: `Player.Position - ThreatCentroid`, validated against terrain via `FindWalkableDirection()`.
|
||||
|
||||
### MovementSystem (Priority 100)
|
||||
|
||||
Continuous soft avoidance via **inverse-square repulsion field**.
|
||||
|
||||
For each hostile monster within SafeDistance (400 units):
|
||||
```
|
||||
force += (playerPos - enemyPos) / distanceSquared * RepulsionWeight
|
||||
```
|
||||
Normalizes sum, validates against terrain, submits as lower-priority MoveAction.
|
||||
|
||||
Effect: Player gently drifts away from enemies without hard fleeing.
|
||||
|
||||
### AreaProgressionSystem (Priority 199)
|
||||
|
||||
High-level area traversal. Runs before NavigationSystem to take precedence.
|
||||
|
||||
**State machine (7 phases):**
|
||||
```
|
||||
Exploring → Looting → NavigatingToChest → InteractingChest →
|
||||
NavigatingToTransition → Interacting → TalkingToNpc
|
||||
```
|
||||
|
||||
**Exploration strategy:**
|
||||
1. Check for elite enemies (Rare/Unique within 800u) → yield to combat
|
||||
2. Check for quest chests → navigate and interact
|
||||
3. Check for loot (if danger ≤ Low) → pick up within 600u
|
||||
4. Once fully explored → find area transition matching quest target
|
||||
5. In towns with active quest → talk to NPC
|
||||
|
||||
**Quest integration**: Queries active quests for target areas. Prioritizes tracked quests, then lowest act, then shortest path. Blacklists failed transitions after 5s timeout.
|
||||
|
||||
**Navigation delegation**: Uses `NavigationController.NavigateToEntity()` and `.Explore()`. Sets targets and yields until reached.
|
||||
|
||||
### NavigationSystem (Priority 200)
|
||||
|
||||
Ultra-thin passthrough. If `NavigationController.DesiredDirection` is set, submits a MoveAction. All actual pathfinding logic lives in NavigationController (see [pathfinding.md](pathfinding.md)).
|
||||
|
||||
### CombatSystem (Priority 300)
|
||||
|
||||
Skill rotation and target selection. Hot-swappable via CharacterProfile.
|
||||
|
||||
**Rotation loop:**
|
||||
```
|
||||
1. Check global cooldown (skip if recently cast)
|
||||
2. For each skill in priority order:
|
||||
a. Check per-skill cooldown
|
||||
b. Match skill to memory via slot index (fallback to name)
|
||||
c. If aura: cast once per zone
|
||||
d. If damage: find target → submit CastAction
|
||||
3. Release held keys for skills without valid targets
|
||||
```
|
||||
|
||||
**Target selection pipeline:**
|
||||
```
|
||||
1. Filter by TargetSelection (Nearest, Rarest, MagicPlus, RarePlus, UniqueOnly)
|
||||
2. Filter by range (SkillProfile.RangeMin/RangeMax)
|
||||
3. Filter by line-of-sight (terrain query)
|
||||
4. Check MinMonstersInRange (AOE threshold)
|
||||
5. Pick best: Rarest mode → prefer higher rarity then nearer; others → nearest
|
||||
6. Project to screen coordinates
|
||||
```
|
||||
|
||||
**Skill input types:**
|
||||
- LeftClick/RightClick/MiddleClick: Direct click at target position
|
||||
- KeyPress with MaintainPressed: Hold key continuously
|
||||
- KeyPress normal: Single tap
|
||||
|
||||
**Kiting/orbit (during global cooldown):**
|
||||
- Computes enemy centroid
|
||||
- Moves perpendicular to centroid (orbital movement)
|
||||
- Applies radial bias to maintain ideal distance
|
||||
- Flips orbit direction if terrain blocks path
|
||||
- Persists orbit sign across ticks for smooth motion
|
||||
|
||||
**Cooldown management:**
|
||||
- Per-skill: `max(skill.CooldownMs, globalCd + 50)` for rotation
|
||||
- MaintainPressed skills: use skill.CooldownMs directly
|
||||
- Area reset: clears aura tracking, resets orbit
|
||||
|
||||
### ResourceSystem (Priority 400)
|
||||
|
||||
Flask automation based on life/mana thresholds.
|
||||
|
||||
```
|
||||
if LifePercent < LifeFlaskThreshold (50%) && cooldown expired → FlaskAction
|
||||
if ManaPercent < ManaFlaskThreshold (50%) && cooldown expired → FlaskAction
|
||||
```
|
||||
|
||||
Flask cooldown: 4000ms default. Hot-swappable on character profile change.
|
||||
|
||||
### LootSystem (Priority 500)
|
||||
|
||||
Stub — disabled by default. Item pickup logic handled by AreaProgressionSystem's looting phase.
|
||||
|
||||
---
|
||||
|
||||
## System Interaction Diagram
|
||||
|
||||
```
|
||||
GameState (read-only, shared)
|
||||
│
|
||||
├─→ ThreatSystem ──→ MoveAction (priority 5 or 50)
|
||||
│ [blocks casting if priority ≤ 10]
|
||||
│
|
||||
├─→ MovementSystem ──→ MoveAction (priority 100)
|
||||
│ [soft repulsion, overridable]
|
||||
│
|
||||
├─→ AreaProgressionSystem ──→ NavigateTo/Explore commands
|
||||
│ [drives NavigationController]
|
||||
│
|
||||
├─→ NavigationSystem ──→ MoveAction (priority 200)
|
||||
│ [passthrough from NavigationController]
|
||||
│
|
||||
├─→ CombatSystem ──→ CastAction (priority 300)
|
||||
│ [skill rotation + target selection]
|
||||
│
|
||||
├─→ ResourceSystem ──→ FlaskAction (priority 400)
|
||||
│ [always passes through]
|
||||
│
|
||||
└─→ ActionQueue.Resolve()
|
||||
│
|
||||
├── Highest MoveAction wins
|
||||
├── CastAction passes unless blocked by urgent flee
|
||||
├── FlaskAction always passes
|
||||
└──→ ExecuteActions() → IInputController
|
||||
```
|
||||
207
docs/infrastructure.md
Normal file
207
docs/infrastructure.md
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
# 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.
|
||||
67
docs/input.md
Normal file
67
docs/input.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# Nexus.Input — Input Controllers & Humanization
|
||||
|
||||
## IInputController Implementations
|
||||
|
||||
### SendInputController (Default, No Driver)
|
||||
|
||||
Uses Win32 `SendInput` API with **KEYEVENTF_SCANCODE** flag. Games read hardware scan codes, not virtual key codes.
|
||||
|
||||
- **KeyDown/KeyUp**: Raw keyboard scan code via SendInput struct
|
||||
- **KeyPress**: Down → Sleep(holdMs) → Up with humanization
|
||||
- **SmoothMoveTo**: Cubic Bézier curve interpolation (10-40 steps) with random perpendicular spread
|
||||
- **MouseMoveTo**: Direct `SetCursorPos()` (instant teleport)
|
||||
- **Clicks**: Smooth move to target → humanized delay → click
|
||||
|
||||
### InterceptionInputController (Driver-Based)
|
||||
|
||||
Uses Interception keyboard/mouse driver for lower-level control:
|
||||
- Delegates to `KeyboardHook` and `MouseHook` via InputInterceptor COM library
|
||||
- Same smooth movement and humanization as SendInput
|
||||
- Returns false from `Initialize()` if driver not installed (graceful fallback)
|
||||
|
||||
### SimInputController (Simulator)
|
||||
|
||||
Implements `IInputController` but doesn't make Win32 calls. Instead:
|
||||
- **WASD** → Tracks held state, converts to direction vector with 45° isometric rotation
|
||||
- **Skills** → Queues skill casts to SimWorld via `QueueSkill()`
|
||||
- **Mouse** → Tracks screen position, converts to world coords via inverse camera matrix
|
||||
- **Visualization** → Maintains flash timers (0.15s) for InputOverlayRenderer
|
||||
|
||||
## Scan Codes
|
||||
|
||||
```
|
||||
Movement: W=0x11 A=0x1E S=0x1F D=0x20
|
||||
Skills: Q=0x10 E=0x12 R=0x13 T=0x14
|
||||
Numbers: 1=0x02 2=0x03 3=0x04 4=0x05 5=0x06
|
||||
Modifiers: LShift=0x2A LCtrl=0x1D LAlt=0x38
|
||||
Other: Space=0x39 Enter=0x1C Escape=0x01 Slash=0x35
|
||||
```
|
||||
|
||||
## Humanizer
|
||||
|
||||
Anti-detection layer applied to all input operations.
|
||||
|
||||
| Method | Purpose |
|
||||
|--------|---------|
|
||||
| GaussianDelay(baseMs) | Adds gaussian noise (Box-Muller transform), clamped to [50ms, 150ms] |
|
||||
| JitterPosition(x, y) | Random pixel offset within ClickJitterRadius (3px) |
|
||||
| ShouldThrottle() | Tracks actions in 60-second rolling window, blocks if APM > MaxApm (250) |
|
||||
| RecordAction() | Enqueues timestamp for APM tracking |
|
||||
| RandomizedInterval(baseMs) | Adds ±20% jitter to poll intervals |
|
||||
|
||||
## MovementKeyTracker
|
||||
|
||||
Converts normalized direction vectors to WASD key state for isometric camera:
|
||||
|
||||
```
|
||||
Rotate direction 45°:
|
||||
sx = dir.X * cos(45°) - dir.Y * sin(45°)
|
||||
sy = dir.X * sin(45°) + dir.Y * cos(45°)
|
||||
|
||||
Key mapping:
|
||||
W if sy > 0.3, S if sy < -0.3
|
||||
D if sx > 0.3, A if sx < -0.3
|
||||
|
||||
Delta-based: only sends KeyDown/KeyUp when state changes.
|
||||
Supports holding multiple keys (W+D for diagonal).
|
||||
```
|
||||
153
docs/pathfinding.md
Normal file
153
docs/pathfinding.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
# Nexus.Pathfinding — Navigation & Exploration
|
||||
|
||||
## Overview
|
||||
|
||||
Two classes: **NavigationController** (state machine — decides *where* to go) and **PathFinder** (A* algorithm — decides *how* to get there).
|
||||
|
||||
---
|
||||
|
||||
## NavigationController
|
||||
|
||||
### Modes
|
||||
|
||||
| Mode | Trigger | Behavior |
|
||||
|------|---------|----------|
|
||||
| Idle | `Stop()` | No movement |
|
||||
| NavigatingToPosition | `NavigateTo(pos)` | Path to fixed world coordinates |
|
||||
| NavigatingToEntity | `NavigateToEntity(id)` | Chase a moving entity (re-targets each tick) |
|
||||
| Exploring | `Explore()` | BFS frontier exploration of unmapped terrain |
|
||||
|
||||
### Update Loop (called every tick)
|
||||
|
||||
```
|
||||
1. Area change detection → clear path, explored grid, stuck history
|
||||
2. EnsureExploredGrid() → allocate/resize to match terrain (preserves old data on expansion)
|
||||
3. MarkExplored(playerPos) → mark cells near player as visited (radius 150 grid cells)
|
||||
4. ResolveGoal() → get target position based on mode
|
||||
5. If no goal and Exploring → PickExploreTarget() via BFS
|
||||
6. Reach detection → within WaypointReachedDistance (80u), clear goal or stop
|
||||
7. Stuck detection → if < 30u movement in 60 ticks (~1s), repath or pick new target
|
||||
8. Pathfinding → A* from player to goal (with explored grid bias in explore mode)
|
||||
9. Waypoint advancement → advance index as player reaches each waypoint
|
||||
10. Output → DesiredDirection (normalized vector to next waypoint)
|
||||
```
|
||||
|
||||
### Explored Grid
|
||||
|
||||
Parallel bool array matching terrain dimensions. Tracks which cells the player has visited.
|
||||
|
||||
- **Mark radius**: 150 grid cells (~1630 world units) — circular region around player
|
||||
- **Preservation**: On terrain expansion, overlapping explored data is copied to new grid
|
||||
- **Offset-aware**: Uses same OffsetX/OffsetY as terrain for absolute grid coordinates
|
||||
|
||||
### BFS Exploration (PickExploreTarget)
|
||||
|
||||
When Exploring mode needs a new goal:
|
||||
|
||||
1. **BFS frontier search** (up to 100,000 iterations)
|
||||
- 8-directional BFS outward from player
|
||||
- Finds nearest unexplored walkable cell
|
||||
- Returns that cell as world coordinates
|
||||
|
||||
2. **Random distant target** (if BFS finds nothing)
|
||||
- 20 attempts at random directions, 1500-3500 world units away
|
||||
- Pushes player toward terrain edges where expansion triggers
|
||||
|
||||
3. **Edge fallback** (if random fails)
|
||||
- Heads toward nearest terrain boundary (10 cells from edge)
|
||||
- Guarantees continued exploration with infinite terrain
|
||||
|
||||
4. **Exploration complete** (only if all fallbacks fail)
|
||||
- Sets `IsExplorationComplete = true`
|
||||
- Prevents expensive re-BFS every tick
|
||||
- Reset on area change
|
||||
|
||||
### Stuck Detection
|
||||
|
||||
- **Window**: Last 60 positions (~1 second at 60Hz)
|
||||
- **Threshold**: Must move at least 30 world units in window
|
||||
- **Grace period**: 120 ticks (2 seconds) after picking new explore target
|
||||
- **On stuck while exploring**: Mark failed goal as explored, pick new target, set grace period
|
||||
- **On stuck otherwise**: Repath
|
||||
|
||||
### Path Failure Handling
|
||||
|
||||
- **Explored bias fallback**: If A* with explored grid bias fails, retry without bias (bias can make distant targets unreachable)
|
||||
- **Cooldown**: 3 seconds before retrying after path failure (prevents CPU burn on impossible paths)
|
||||
|
||||
---
|
||||
|
||||
## PathFinder — A* Implementation
|
||||
|
||||
### Signature
|
||||
|
||||
```csharp
|
||||
public static List<Vector2>? FindPath(
|
||||
WalkabilitySnapshot terrain, Vector2 start, Vector2 goal, float worldToGrid,
|
||||
bool[]? exploredGrid, int exploredWidth, int exploredHeight,
|
||||
int exploredOffsetX, int exploredOffsetY)
|
||||
```
|
||||
|
||||
Returns world-coordinate waypoints or null if unreachable.
|
||||
|
||||
### Movement Model
|
||||
|
||||
- **8-directional grid**: Cardinal + diagonal
|
||||
- **Costs**: Cardinal = 1.0, Diagonal = √2 ≈ 1.414
|
||||
- **Explored penalty**: ×1.5 multiplier for explored cells (biases paths through unexplored territory)
|
||||
|
||||
### Heuristic
|
||||
|
||||
```
|
||||
h = max(dx, dy) + 0.414 * min(dx, dy)
|
||||
```
|
||||
Diagonal/Chebyshev-based. Admissible and consistent.
|
||||
|
||||
### Algorithm
|
||||
|
||||
1. **Snap to walkable**: If start/goal in wall, BFS search for nearest walkable cell (radius up to 20)
|
||||
2. **A* search** (budget: 200,000 iterations):
|
||||
- Priority queue ordered by f = g + h
|
||||
- 8 neighbors per expansion
|
||||
- **Corner-cut check**: Diagonals require at least one adjacent cardinal cell walkable
|
||||
- **Explored grid bias**: Multiply step cost by 1.5 for explored cells
|
||||
- Track `bestNode` (closest reachable) for fallback
|
||||
3. **Path reconstruction**: Backtrack via cameFrom map
|
||||
4. **Simplification**: Remove collinear waypoints, keep only turning points
|
||||
5. **Fallback**: If goal unreachable but bestNode is meaningfully closer (within 80% of starting heuristic), path to closest reachable cell
|
||||
|
||||
### Data Structures
|
||||
|
||||
| Structure | Type | Purpose |
|
||||
|-----------|------|---------|
|
||||
| Open set | PriorityQueue<(int,int), float> | Nodes to expand, ordered by f-score |
|
||||
| Closed set | HashSet<(int,int)> | Already expanded nodes |
|
||||
| gScore | Dictionary<(int,int), float> | Best known cost to each node |
|
||||
| cameFrom | Dictionary<(int,int), (int,int)> | Backtracking map |
|
||||
|
||||
---
|
||||
|
||||
## Integration
|
||||
|
||||
```
|
||||
AreaProgressionSystem
|
||||
│ .Explore() / .NavigateTo() / .NavigateToEntity()
|
||||
▼
|
||||
NavigationController
|
||||
│ .Update(GameState) → computes path, sets DesiredDirection
|
||||
│ calls PathFinder.FindPath() for A* routing
|
||||
▼
|
||||
NavigationSystem
|
||||
│ reads DesiredDirection → submits MoveAction
|
||||
▼
|
||||
ActionQueue → BotEngine → MovementKeyTracker → WASD keys
|
||||
```
|
||||
|
||||
### Coordinate Systems
|
||||
|
||||
| Space | Example | Conversion |
|
||||
|-------|---------|------------|
|
||||
| World | (1517, 4491) | Raw game units |
|
||||
| Grid | (139, 413) | world × WorldToGrid (23/250) |
|
||||
| Local grid | (139-ox, 413-oy) | grid - terrain offset |
|
||||
| Screen | project via CameraMatrix | WorldToScreen.Project() |
|
||||
180
docs/simulator.md
Normal file
180
docs/simulator.md
Normal file
|
|
@ -0,0 +1,180 @@
|
|||
# Nexus.Simulator — Standalone Game World
|
||||
|
||||
## Purpose
|
||||
|
||||
Test bot systems (combat, navigation, threat assessment) without the real game. Replaces the memory-reading pipeline with a procedural game world. Bot systems run unmodified — they see identical `GameState` objects and emit actions to `IInputController`.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
SimWorld (game tick loop)
|
||||
│
|
||||
├── SimPoller (60Hz background thread)
|
||||
│ ├── FlushToWorld() → transfer input to SimWorld
|
||||
│ ├── Tick(dt) → advance simulation
|
||||
│ ├── SimStateBuilder.Build() → SimWorld → GameState
|
||||
│ └── Push to GameDataCache
|
||||
│
|
||||
├── SimInputController (captures bot actions)
|
||||
│ ├── WASD → MoveDirection vector (45° isometric conversion)
|
||||
│ ├── Skills → QueueSkill(scanCode, targetWorldPos)
|
||||
│ ├── Mouse → track position, screen↔world conversion
|
||||
│ └── Flash timers for input visualization
|
||||
│
|
||||
├── Bot Logic Thread (60Hz)
|
||||
│ ├── GameStateEnricher.Enrich(state)
|
||||
│ ├── All 6 systems: Threat, Movement, Navigation, Combat, Resource, Loot
|
||||
│ ├── NavigationController.Update()
|
||||
│ └── ExecuteActions() → SimInputController
|
||||
│
|
||||
└── Render Thread (ImGui + Veldrid)
|
||||
├── TerrainRenderer (diamond cells, isometric)
|
||||
├── EntityRenderer (player, enemies, health bars)
|
||||
├── EffectRenderer (melee cones, AOE circles, projectile lines)
|
||||
├── PathRenderer (A* waypoints)
|
||||
├── InputOverlayRenderer (keyboard + mouse state)
|
||||
└── DebugPanel (system toggles, stats, spawn controls)
|
||||
```
|
||||
|
||||
## SimWorld — Game Loop
|
||||
|
||||
### Tick (dt-based, 60Hz)
|
||||
|
||||
```
|
||||
1. CheckAndExpandTerrain() → expand when player within 50 cells of edge
|
||||
2. MovePlayer(dt) → WASD direction × speed × dt, collision with terrain
|
||||
3. ProcessSkills() → dequeue skill casts, dispatch by scan code
|
||||
4. UpdateProjectiles(dt) → move, check terrain/enemy collisions
|
||||
5. UpdateEffects(dt) → decay visual effects (0.3s duration)
|
||||
6. UpdateEnemies(dt) → AI state machine per enemy
|
||||
7. UpdateRespawns(dt) → cull far enemies, spawn new groups
|
||||
```
|
||||
|
||||
### Terrain
|
||||
|
||||
- Procedural: all walkable with scattered obstacles (rock clusters, wall segments, pillars)
|
||||
- 500×500 initial grid, `WorldToGrid = 23/250`
|
||||
- **Infinite expansion**: Expands 250 cells per side when player within 50 cells of edge
|
||||
- Preserves existing data via array copy with offset adjustment
|
||||
|
||||
### Player
|
||||
|
||||
- Position (Vector2), Health/Mana with regen (5 HP/s, 10 MP/s)
|
||||
- Move speed: 400 world units/s
|
||||
- Collision: slide-along-X / slide-along-Y fallback if direct move blocked
|
||||
|
||||
### Skills
|
||||
|
||||
| Scan Code | Type | Behavior |
|
||||
|-----------|------|----------|
|
||||
| Q (0x10), R (0x13) | AOE | Damage all enemies within 250u of target position |
|
||||
| E (0x12), T (0x14) | Projectile | Spawn projectile, 1200 speed, 800 range, 80u hit radius |
|
||||
| LMB, RMB | Melee | 150u cone, 120° angle from player toward target |
|
||||
|
||||
Base damage: 200 per hit. Configurable via SimConfig.
|
||||
|
||||
### Enemy AI
|
||||
|
||||
```
|
||||
State machine per SimEnemy:
|
||||
|
||||
Idle → wander randomly within 200u of spawn, new target every 2-5s
|
||||
│ player within 600u (aggro range)
|
||||
▼
|
||||
Chasing → move toward player at 75% player speed
|
||||
│ player within 100u (attack range)
|
||||
▼
|
||||
Attacking → stand still, deal 30 damage every 1.5s
|
||||
│ player escapes attack range
|
||||
▼ back to Chasing
|
||||
│ health ≤ 0
|
||||
▼
|
||||
Dead → visible for 2s → queue for respawn (5s delay)
|
||||
```
|
||||
|
||||
### Enemy Spawning
|
||||
|
||||
- **Groups**: 3-7 enemies per spawn, leader keeps rolled rarity, rest are Normal
|
||||
- **Rarity distribution**: 70% Normal, 20% Magic, 8% Rare, 2% Unique
|
||||
- **HP multipliers**: Magic=1.5×, Rare=3×, Unique=5× base (200)
|
||||
- **Spawn ring**: 800-2000 world units from player
|
||||
- **Direction bias**: ±90° cone ahead of player's movement direction
|
||||
- **Culling**: Remove enemies > 3000u from player
|
||||
- **Population**: Maintain 25 enemies, spawn new groups as needed
|
||||
|
||||
## Bridge Layer
|
||||
|
||||
### SimPoller
|
||||
|
||||
Replaces MemoryPoller. Background thread at 60Hz:
|
||||
1. `FlushToWorld()` — transfer accumulated input
|
||||
2. `world.Tick(dt)` — advance simulation (dt clamped to 0.1s max)
|
||||
3. `SimStateBuilder.Build()` — convert to GameState
|
||||
4. Push to GameDataCache (same fields as production)
|
||||
|
||||
### SimStateBuilder
|
||||
|
||||
Converts SimWorld state → GameState:
|
||||
- Each SimEnemy → EntitySnapshot (with rarity, threat level, AI state, HP)
|
||||
- SimPlayer → PlayerState (position, vitals, skills)
|
||||
- Camera matrix: orthographic projection (12800×7200 world units → 2560×1440 screen)
|
||||
|
||||
### SimInputController
|
||||
|
||||
Implements IInputController, captures actions instead of sending Win32 input:
|
||||
- WASD → direction vector (with 45° isometric inversion)
|
||||
- Skills → `SimWorld.QueueSkill(scanCode, worldPos)`
|
||||
- Mouse → screen position tracking, inverse camera transform for world coords
|
||||
- Input visualization: flash timers for keyboard/mouse overlay
|
||||
|
||||
## Rendering
|
||||
|
||||
### ViewTransform (Isometric Camera)
|
||||
|
||||
45° counter-clockwise rotation matching the game's camera:
|
||||
|
||||
```
|
||||
World → Grid: gx = worldX × WorldToGrid
|
||||
Grid → Screen: rx = (gx - gy) × cos(45°)
|
||||
ry = -(gx + gy) × cos(45°)
|
||||
Screen = canvasOrigin + viewOffset + (rx, ry) × zoom
|
||||
```
|
||||
|
||||
### Renderers
|
||||
|
||||
| Renderer | Draws |
|
||||
|----------|-------|
|
||||
| TerrainRenderer | Diamond cells (rotated grid), explored overlay, minimap |
|
||||
| EntityRenderer | Player (green circle), enemies (colored by rarity), health/mana bars |
|
||||
| EffectRenderer | Melee cones (red triangle fan), AOE circles (blue), projectile lines (cyan) |
|
||||
| PathRenderer | Cyan waypoint lines and dots from A* path |
|
||||
| InputOverlayRenderer | Keyboard (3 rows: 1-5, QWERT, ASDF) + mouse (L/R/M buttons) |
|
||||
| DebugPanel | Pause/speed, player stats, enemy counts, system toggles, threat info |
|
||||
|
||||
### VeldridImGuiRenderer
|
||||
|
||||
Custom ImGui backend for Veldrid 4.9.0 + D3D11:
|
||||
- HLSL shaders compiled at runtime via D3DCompiler P/Invoke
|
||||
- Dynamic vertex/index buffers, font texture from ImGui atlas
|
||||
- Alpha blending pipeline with scissor rect support
|
||||
|
||||
## SimConfig
|
||||
|
||||
```
|
||||
Terrain: 500×500, WorldToGrid=23/250, ExpandThreshold=50, ExpandAmount=250
|
||||
Player: Speed=400, HP=1000, MP=500, HPRegen=5/s, MPRegen=10/s
|
||||
Enemies: Count=25, Aggro=600u, Attack=100u, Speed=75%, HP=200, Damage=30
|
||||
Spawning: Ring=800-2000u, Groups=3-7, Cull=3000u
|
||||
Skills: Melee=150u/120°, AOE=250u, Projectile=1200speed/800range, Damage=200
|
||||
Rarity: Normal=70%, Magic=20%, Rare=8%, Unique=2%
|
||||
Simulation: SpeedMultiplier=1×, Pauseable
|
||||
```
|
||||
|
||||
## Running
|
||||
|
||||
```
|
||||
dotnet run --project src/Nexus.Simulator
|
||||
```
|
||||
|
||||
Dependencies: Core, Data, Systems, Pathfinding, ImGui.NET, Veldrid, Veldrid.StartupUtilities
|
||||
Does NOT depend on: Memory, Input, Screen, Game, Bot, Ui, Trade
|
||||
95
docs/test.html
Normal file
95
docs/test.html
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Hold Timer</title>
|
||||
<style>
|
||||
body {
|
||||
font-family: Arial, sans-serif;
|
||||
display: flex;
|
||||
min-height: 100vh;
|
||||
margin: 0;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
background: #111;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.wrap {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
button {
|
||||
font-size: 24px;
|
||||
padding: 30px 60px;
|
||||
cursor: pointer;
|
||||
border: none;
|
||||
border-radius: 12px;
|
||||
}
|
||||
|
||||
#result {
|
||||
margin-top: 24px;
|
||||
font-size: 32px;
|
||||
}
|
||||
|
||||
#live {
|
||||
margin-top: 12px;
|
||||
font-size: 20px;
|
||||
opacity: 0.85;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrap">
|
||||
<button id="btn">PRESS AND HOLD</button>
|
||||
<div id="result">Last hold: 0 ms</div>
|
||||
<div id="live">Current hold: 0 ms</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
const btn = document.getElementById("btn");
|
||||
const result = document.getElementById("result");
|
||||
const live = document.getElementById("live");
|
||||
|
||||
let startTime = 0;
|
||||
let holding = false;
|
||||
let rafId = 0;
|
||||
|
||||
function updateLive() {
|
||||
if (!holding) return;
|
||||
const now = performance.now();
|
||||
live.textContent = "Current hold: " + (now - startTime).toFixed(2) + " ms";
|
||||
rafId = requestAnimationFrame(updateLive);
|
||||
}
|
||||
|
||||
function startHold() {
|
||||
if (holding) return;
|
||||
holding = true;
|
||||
startTime = performance.now();
|
||||
updateLive();
|
||||
}
|
||||
|
||||
function endHold() {
|
||||
if (!holding) return;
|
||||
holding = false;
|
||||
cancelAnimationFrame(rafId);
|
||||
const duration = performance.now() - startTime;
|
||||
result.textContent = "Last hold: " + duration.toFixed(2) + " ms";
|
||||
live.textContent = "Current hold: 0 ms";
|
||||
}
|
||||
|
||||
btn.addEventListener("mousedown", startHold);
|
||||
btn.addEventListener("mouseup", endHold);
|
||||
btn.addEventListener("mouseleave", endHold);
|
||||
|
||||
btn.addEventListener("touchstart", (e) => {
|
||||
e.preventDefault();
|
||||
startHold();
|
||||
}, { passive: false });
|
||||
|
||||
btn.addEventListener("touchend", endHold);
|
||||
btn.addEventListener("touchcancel", endHold);
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Add table
Add a link
Reference in a new issue