# GaimE (Game Automation & Intelligence Engine) — Hermes Handoff & Technical Briefing

## Executive Summary
GaimE is a C# WinForms application with a Visual Studio 2015-style docking interface (WeifenLuo DockPanel Suite) designed as an advanced memory manipulation, cheat engine table runner, and realtime game controller. Its primary current target is **Core Keeper** (Unity 2022.3+ / Unity DOTS ECS with Burst Compilation and Mono Bleeding Edge runtime).

---

## 1. Project Directory Structure & Key Files
- **Root Directory**: `C:\Users\mbogd\.gemini\antigravity\scratch\GaimE\`
- **Executable Output**: `C:\Users\mbogd\.gemini\antigravity\scratch\GaimE\bin\GaimE.exe`
- **Managed Dependencies (`lib\` and `bin\`)**:
  - `WeifenLuo.WinFormsUI.Docking.dll`
  - `WeifenLuo.WinFormsUI.Docking.ThemeVS2015.dll`
- **Key Source Code Files (`GaimEApp\`)**:
  - `MainForm.cs`: Main IDE shell, DockPanel container, status bar, and toolbar.
  - `NativeMethods.cs`: Win32 API wrappers (`OpenProcess`, `VirtualAllocEx`, `WriteProcessMemory`, `ReadProcessMemory`, `CreateRemoteThread`, `VirtualProtectEx`).
  - `ProcessAttacher.cs`: Module scanning, process handle management, base address resolution for `UnityPlayer.dll`, `mono-2.0-bdwgc.dll`.
  - `CoreKeeperHook.cs` & `CoreKeeperEngine.cs`: High-level automation state, pointer scanning, and feature hooks.
  - `CheatTableEngine.cs`: Parser and memory patcher for Cheat Engine `.CT` XML tables.
  - `LiveOffsetScannerView.cs`: Real-time memory inspection, pattern scanning, and offset verification.
  - `Views\CoreKeeperSurvivalView.cs`: UI controls for God Mode, Infinite Food, Durability, Mining Damage.

---

## 2. Core Keeper Architecture: Mono Bleeding Edge vs. Unity DOTS Burst

### The Dual-Runtime Architecture
Core Keeper uses a hybrid runtime:
1. **Mono Bleeding Edge (`mono-2.0-bdwgc.dll`)**:
   - Manages UI, menus, high-level game logic, and non-performance-critical systems.
   - Primary game logic assembly: `Pug.Other.dll` (located in `CoreKeeper_Data\Managed\Pug.Other.dll`).
2. **Unity DOTS (Data-Oriented Technology Stack) + Burst Compiler**:
   - Player entities, movement, vitality components, world generation, and combat run as pure unmanaged struct components inside ECS Chunks.
   - Native assemblies: `lib_burst_generated.dll`, `UnityPlayer.dll`.

### Critical Managed Internal Methods in `Pug.Other.dll`
Reverse engineering of `Pug.Other.dll` reveals the exact official methods handling player status:
- **God Mode / Creative Mode**: `PlayerController.SetGodModeCreative(bool active)`
- **Invincibility**: `PlayerController.SetInvincibility(bool active)`
- **Hunger / Satiety**: `PlayerController.AddHunger(int amount)` and `HungerSystem.Update()`
- **Durability**: `ChangeDurabilitySystem.ApplyDamage(Entity entity, int amount)`
- **Mining Damage**: `EntityUtility.GetDamageInfo(Entity miner, Entity target)`

---

## 3. Pitfalls Encountered & Root Causes of Previous Bugs

### Bug 1: Game Crash on Attach / Memory Read
- **Symptom**: Attaching GaimE to `CoreKeeper.exe` caused the game to abruptly crash with access violation `0xC0000005`.
- **Root Cause**: `LiveOffsetScannerView` and `playerMonitorTimer` polled hardcoded static offsets relative to `UnityPlayer.dll` every 100ms. In Unity DOTS, player entity addresses are dynamically allocated in ECS chunk memory on world load; reading or dereferencing old/stale pointers dereferenced uncommitted virtual pages (`PAGE_NOACCESS`), triggering game crash.
- **Rule for Future Development**: Never poll memory with tight timers without first verifying page state using `VirtualQueryEx`. Check `mbi.State == MEM_COMMIT && (mbi.Protect & PAGE_READWRITE)`.

### Bug 2: "Infinite Food" Clamped Health Bar Off-Screen
- **Symptom**: Activating the hunger checkbox caused the UI health bar to shoot off the left side of the screen.
- **Root Cause**: The cheat table wrote `0x7FFFFFFF` into an integer offset assumed to be Hunger, but the offset was actually mapped to the internal UI layout / anchor coordinate struct in the Canvas renderer.
- **Fix**: Use managed hook or signature scan for `Pug.Other.dll!PlayerController.AddHunger` instead of raw memory pointer chasing.

---

## 4. Dependencies & Build Instructions
- **Platform**: Windows x64 (.NET Framework 4.8 / Roslyn C# 9.0+)
- **Build Script**: `auto_build.ps1` at project root:
  ```powershell
  & "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe" /target:winexe /platform:x64 `
    /out:bin\GaimE.exe `
    /reference:lib\WeifenLuo.WinFormsUI.Docking.dll `
    /reference:lib\WeifenLuo.WinFormsUI.Docking.ThemeVS2015.dll `
    /reference:System.dll,System.Core.dll,System.Data.dll,System.Drawing.dll,System.Windows.Forms.dll,System.Xml.dll,System.Xml.Linq.dll `
    /recurse:GaimEApp\*.cs
  ```

---

## 5. Next Steps for Hermes / Future Development
1. **Mono Injection via `mono-2.0-bdwgc.dll`**:
   - Resolve `mono_get_root_domain()`, `mono_thread_attach()`, `mono_assembly_open()`.
   - Call `PlayerController.SetGodModeCreative(true)` directly via managed reflection.
2. **ECS Archetype Pattern Scanner**:
   - Signature scan for DOTS ComponentType ID for `PlayerVitalityComponent` in `UnityPlayer.dll`.
3. **Safe Memory Guard**:
   - Implement `SafeRead<T>` with `VirtualQueryEx` validation to completely eliminate access violation crashes.