# AutoHotkey v2 Project Copilot Instructions

## Core Language & Syntax Rules

- **AHK Version:** Strict AutoHotkey v2 syntax ONLY. Do NOT write AHK v1 code (no `%var%` syntax, legacy commands, or unquoted strings).
- **Case Sensitivity & Naming:** AutoHotkey is case-insensitive. Never name a variable and a class with the same name, regardless of casing (e.g., do NOT use `playerState := PlayerState()`). Use descriptive variable names like `currentPlayerState` or `playerStateInst`.
- **Verification Workflow:** Do NOT run code verification, syntax tests, or execution commands after code changes unless explicitly instructed.
- **Object Keys** Property names should not be in double quotes when returning objects.

## Data Persistence & JSON Management

- **Library Choice:** Use `cJson.ahk` (or `JSON.ahk` for AHK v2) for high-performance JSON parsing and stringifying.
- **State Files:**
  - Load initial configuration files on launch using `FileRead` and parse via JSON.
  - Maintain runtime state in memory and persist updates to `player_state.json` via `FileOpen(path, "w", "UTF-8").Write(jsonString)`.

## High-Performance OCR

- **Engine:** Use the native Windows 10/11 OCR API (`Windows.Media.Ocr` via WinRT/COM) for multi-line English extraction. Avoid calling external slow CLI tools.
- **Optimization:**
  - Restrict the OCR scan region strictly to the target screen area—do NOT capture full screens unnecessarily.
  - Pre-crop the screen memory buffer using GDI+ (`gdip.ahk` for AHK v2) before passing pixels to the WinRT engine to maximize processing speed.

## Anchor Point & Image Matching

- **Function:** Use `ImageSearch` with built-in variation tolerance syntax: `ImageSearch(&foundX, &foundY, x1, y1, x2, y2, "*Variation path/to/anchor.png")`.
- **Tolerances:** Default to a minor variation allowance (e.g., `*15` to `*30`) to accommodate subtle rendering or anti-aliasing shifts.
- **Anchor Logic:** Define relative offsets from matched UI anchors to locate dynamic interactable elements.

## High-Speed Automation & Input

- **Input Speed:** Set global speed parameters at script startup:
  ```ahk
  SetControlDelay(-1)
  SetMouseDelay(-1)
  SetKeyDelay(-1, -1)
  SendMode("Input")
  Execution: Do not add artificial human jitter or random movement delays unless explicitly requested. Use Click and MouseMove directly for high-throughput input sequence delivery.
  ```

## NEXT STEPS TO CONSIDER

- Generate a high-performance WinRT OCR wrapper for AHK v2
  Write an AutoHotkey v2 function using Windows native WinRT OCR to rapidly extract multi-line text from a specified screen bounding box.

- Create a JSON state management helper class
  Write an AHK v2 class for loading, updating, and saving state data to player_state.json using cJson.

- Build an anchor-relative UI clicker function
  Write an AHK v2 function that finds an anchor image with variation tolerance and clicks at a relative offset.


## Usage

This is a game and f keys are used already. Lets use del to start the app, end to  stop and page down to reload the app.

## Flow

- On app start, load the state and databases.

- Show a gui with the following tabs:
  - Mission Picker:
    Show a grid of boxes 5x5. User can select 3 boxes. When a box is clicked, show a dropdown to select a mission. (specialization - mission name)
  
  - Settings:
    - Show the current settings of the app.


## Resolution Management
All coordinates and offsets are taken in 3440x1440 environment.
The game ui size is same for both 21:9 and 16:9 ratios. In 21:9 it adds empty padding to the sides so ui is the same.
A resolution manager is needed to convert the coordinates and offsets and dimensions etc to the right size of the users resolution running the script
For example 21:9 resolution of the developer has 440px padding on both sides of the ui compared to 16:9 2560x1440 resolution. 
So each x coordinate should be reduced by 440 if its a 16:9 1440p system. If its another resolution like 1080p it should scale the value first then reduce it.
This should be an easy to use class like ResolutionManager.coords(x,y). This should return the scaled resolution for the user while the x,y values are coming from the developers 21:9 1440p values.
The class should handle coords, dimensions, addToCoords 


## Creating Overlays:

#Requires AutoHotkey v2.0

; Configuration (X, Y, Width, Height, Border Thickness)
x := 500, y := 300, w := 400, h := 200, thickness := 3

; 1. Create a borderless, always-on-top GUI
box := Gui("-Caption +AlwaysOnTop +E0x20 +ToolWindow")

; 2. Set the window background to red
box.SetFont()
box.BackColor := "Red"

; 3. Cut out the middle to make it transparent, leaving only the border
WinSetTransColor("0x000001", box)
box.AddText("x" thickness " y" thickness " w" (w - thickness * 2) " h" (h - thickness * 2) " Background000001")

; 4. Display the GUI
box.Show("x" x " y" y " w" w " h" h " NoActivate")