updates for linux and windows

Author: maple-underscore

.github/copilot-instructions.md

@@ -1,50 +1,138 @@
 # Copilot instructions for arrastools
 
-Purpose: Help AI coding agents work productively in this repo of desktop automation tools and a PPO-based Arras AI. Scripts control keyboard/mouse, read pixels, and automate gameplay/UI flows on macOS.
+Purpose: Help AI coding agents work productively in this repo of desktop automation tools and a PPO-based Arras AI. Scripts control keyboard/mouse, read pixels, and automate gameplay/UI flows across macOS, Linux, and Windows.
 
 ## Architecture and key files
 - This is a collection of standalone Python scripts (no package/pytest). Common patterns repeat across files.
 - Screen + input automation:
   - `arrastools.py` — hotkey-driven macros using pynput. Listeners run at module end and spawn daemon threads via `start_*` helpers.
+  - `arrastools2.py` — alternative version with similar functionality and cross-platform support.
   - `arrasbot.py` — a watchdog that samples screen pixels with `mss`, reacts to state (disconnected/died/banned), and logs/screenshots.
+  - `arrascopypasta.py` — copypasta automation with platform-agnostic file path handling using pathlib.
 - PPO AI prototype:
   - `arrasai.py` — defines PPO agent (PolicyNetwork, PPOMemory, ArrasAI) and training/exec loops over screen observations sampled in a polygon (`GAME_REGION`). Models saved to `arras_models/` (e.g., `arras_model.pt_best`).
 - Assets/data: `arras_models/`, `logs/`, `copypastas/`.
 
-## Runtime assumptions and permissions (macOS)
-- Requires Accessibility (keyboard/mouse control) and Screen Recording permissions for Terminal/VS Code (pynput + mss).
-- Coordinates are absolute screen pixels for a specific UI layout. Retina scaling handled manually:
-  - `arrasbot.py`: `MONITOR_INDEX` (default 1) and `SCALE` (2 on Retina, 1 on non-Retina). Convert global to local with these.
-  - If your resolution/layout differs, update `GAME_REGION` and bounds used by `arrastools.py` and `arrasai.py` (e.g., mouse x in [2,1693], y in [128,1094]).
+## Cross-platform support and runtime assumptions
 
-## Dependencies used across scripts
-- Core: `pynput`, `mss`, `numpy`.
-- Bot: `ping3`, `Pillow`, `mss.tools`.
-- AI: `torch`, `shapely`, `pytesseract` (requires system Tesseract), `Pillow`.
-- Example install (Python 3.10+): pynput, mss, numpy, ping3, pillow, torch, shapely, pytesseract.
+### Platform detection
+All main scripts now include platform detection using `platform.system().lower()`:
+- Returns: `'darwin'` (macOS), `'linux'`, `'windows'`
+- Scripts print platform on startup and warn if unsupported
+
+### Platform-specific behaviors
+- **macOS (primary development platform)**:
+  - Requires Accessibility + Screen Recording permissions (System Settings > Privacy & Security)
+  - Retina displays: Set `SCALE=2` in `arrasbot.py`
+  - Modifier keys: `Option+Arrow` for 1px mouse nudges
+  - Coordinate system: May differ from Linux/Windows due to Retina scaling
+  
+- **Linux (Arch, Debian, Ubuntu)**:
+  - Install dependencies via package manager: `sudo apt install python3-tk tesseract-ocr` (Debian/Ubuntu) or `sudo pacman -S tk tesseract` (Arch)
+  - Accessibility permissions may vary by DE/WM (check pynput documentation)
+  - Standard displays: Set `SCALE=1` in `arrasbot.py`
+  - Modifier keys: `Alt+Arrow` for 1px mouse nudges
+  - Wayland vs X11: pynput works best on X11; Wayland may have limitations
+  
+- **Windows**:
+  - Install Tesseract OCR separately: Download from https://github.com/UB-Mannheim/tesseract/wiki
+  - May require running as Administrator for input automation
+  - Standard displays: Set `SCALE=1` in `arrasbot.py`
+  - Modifier keys: `Alt+Arrow` for 1px mouse nudges
+  - Path separators: Now handled automatically via pathlib
+  
+- **Android**:
+  - Limited/experimental support
+  - pynput may not work on all devices
+  - Consider using Termux with X11 server for best compatibility
+
+### Display scaling and coordinates
+- Coordinates are absolute screen pixels for a specific UI layout
+- **Critical**: Adjust based on YOUR display resolution:
+  - `arrasbot.py`: `MONITOR_INDEX` (default 1) and `SCALE` (2 on Retina, 1 on standard displays)
+  - `arrasai.py`: Update `GAME_REGION` polygon coordinates to match your game window
+  - `arrastools.py`: Update mouse bounds in `on_press()` and click positions in `conq_quickstart()`
+- Use `arrasbot.py` CLI command `probe` to sample pixel colors and positions on your setup
+- Retina/HiDPI displays require coordinate conversion: multiply or divide by `SCALE` as needed
+
+## Dependencies and installation
+
+### Python requirements
+- **Python version**: 3.10+ recommended
+- **Core libraries**: `pynput`, `mss`, `numpy`, `pathlib` (built-in)
+- **Bot utilities**: `ping3`, `Pillow`, `mss.tools`
+- **AI/ML**: `torch`, `shapely`, `pytesseract`, `Pillow`
+
+### System dependencies (platform-specific)
+- **macOS**: Tesseract via Homebrew: `brew install tesseract`
+- **Linux**: `sudo apt install python3-tk tesseract-ocr` (Debian/Ubuntu) or equivalent
+- **Windows**: Download Tesseract installer from GitHub, add to PATH
+- **All platforms**: Ensure Python tkinter is installed (usually bundled)
+
+### Quick setup
+```bash
+# Create virtual environment (recommended)
+python3 -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# OR
+.venv\Scripts\activate  # Windows
+
+# Install dependencies
+pip install pynput mss numpy ping3 pillow torch shapely pytesseract
+
+# Platform-specific system packages
+# macOS: brew install tesseract
+# Linux: sudo apt install tesseract-ocr python3-tk
+# Windows: Install Tesseract from GitHub releases
+```
 
 ## How to run and control
-- `arrastools.py` hotkeys (hold Ctrl):
+- `arrastools.py` / `arrastools2.py` hotkeys (hold Ctrl):
   - `Ctrl+1` one/two/three presses within 2s: `$arena size` automation type 1/2/3 (`start_arena_automation`).
-  - `Ctrl+y` begin “Controlled Nuke”: click 2 points in 10s to spray `k` within rectangle (uses global mouse listener).
+  - `Ctrl+y` begin "Controlled Nuke": click 2 points in 10s to spray `k` within rectangle (uses global mouse listener).
+  - `Alt+Arrow` (Option+Arrow on macOS): Move mouse 1 pixel in arrow direction (for precise positioning).
   - Safety: `Esc` stops activities; `Ctrl+Esc` immediate exit.
   - Other examples: `Ctrl+6` double-press within 5s triggers `ballcrash()`; `Ctrl+9` runs `nuke()`; `Ctrl+m` benchmarks ball spam.
 - `arrasbot.py` CLI commands (typed in terminal while running): `stop`, `setscale <1|2>`, `setmon <index>`, `dbgmon`, `screenshot`, `status`, `ping`, `probe`, `forcedisconnect`, `forcedeath`, `forcereconnect`.
-  - Logs: `logs/abss_*.log`; screenshots: `~/Desktop/abss/<session>/`. Uses `color_close()` for tolerant RGB checks.
+  - Logs: `logs/abss_*.log`; screenshots: `~/Desktop/abss/<session>/` (Linux/macOS) or `C:\Users\<user>\Desktop\abss\<session>\` (Windows).
+  - Uses `color_close()` for tolerant RGB checks (accounts for antialiasing).
 - `arrasai.py` training:
   - Hotkeys while running: `Esc` force-stop (hard exit), `p` pause/resume, `r` simulate death.
   - Samples RGB at `OBSERVATION_POINTS = sample_points_in_polygon(GAME_REGION, step=10)` using `mss`; outputs: action (W/A/S/D/Space), mouse target, Sum42 head, and upgrade path.
   - Models saved in `arras_models/` with suffixes `_best`, `_final`, `_interrupted` based on training flow.
+- `arrascopypasta.py`: Reads `.txt` files from `copypastas/` directory (uses pathlib for cross-platform compatibility).
 
 ## Conventions and patterns to follow
-- Threading: Use `threading.Thread(..., daemon=True)` for background actions; toggle with global flags (e.g., `slowballs`, `randomwalld`). Provide `start_*` helpers to avoid duplicate threads.
-- Input synthesis: Use a single `KeyboardController`/`MouseController` per module; batch keystrokes within backtick-quoted console in-game by `controller.press("`")` … `controller.release("`")`.
-- Color detection: Prefer `color_close(tupleRGB, tupleRGB, tol=6)` rather than strict equality to account for antialiasing/transparency.
-- File outputs: Prefer timestamped paths from `timestamp()`; keep bot logs under `logs/` and images under `~/Desktop/abss/<session>/`.
+- **Threading**: Use `threading.Thread(..., daemon=True)` for background actions; toggle with global flags (e.g., `slowballs`, `randomwalld`). Provide `start_*` helpers to avoid duplicate threads.
+- **Input synthesis**: Use a single `KeyboardController`/`MouseController` per module; batch keystrokes within backtick-quoted console in-game by `controller.press("`")` … `controller.release("`")`.
+- **Color detection**: Prefer `color_close(tupleRGB, tupleRGB, tol=6)` rather than strict equality to account for antialiasing/transparency.
+- **File paths**: Use `pathlib.Path` for cross-platform compatibility (see `arrascopypasta.py` for example). Avoid hardcoded `/` or `\`.
+- **File outputs**: Prefer timestamped paths from `timestamp()`; keep bot logs under `logs/` and images under `~/Desktop/abss/<session>/`.
+- **Modifier key detection**: Use helper functions `is_ctrl()`, `is_alt()`, `is_modifier_for_arrow_nudge()` to handle cross-platform modifier key variants (Key.ctrl vs Key.ctrl_l vs Key.ctrl_r).
 
 ## When extending
 - For new macros, mirror `arrastools.py` style: add a function, a `start_*` wrapper if it loops, and wire a Ctrl+<key> branch in `on_press()` with debouncing if needed.
 - For new detectors, add small, monitor-relative probes (`probe` in `arrasbot.py`) and gate user-visible actions with tolerant checks + cooldowns.
 - If changing layout/resolution, update `GAME_REGION`, bounds and any hard-coded click points in `arrastools.py` (e.g., `conq_quickstart()` positions).
+- **Platform testing**: Test on target platforms before committing. Use virtual machines or containers for cross-platform validation.
+- Add platform detection at script start: `PLATFORM = platform.system().lower()` with appropriate warnings.
+
+## Troubleshooting
+
+### Permission issues
+- **macOS**: Grant Accessibility + Screen Recording in System Settings > Privacy & Security
+- **Linux**: Check X11 vs Wayland; pynput may need additional configuration for Wayland
+- **Windows**: Run Terminal/IDE as Administrator if input automation fails
+
+### Coordinate/scaling issues
+- Use `arrasbot.py` command `dbgmon` to list all monitors and their properties
+- Use `probe` command to check pixel colors at cursor position
+- Adjust `SCALE` variable to match your display (2 for Retina/HiDPI, 1 for standard)
+- Re-map `GAME_REGION` coordinates for your screen resolution
+
+### Dependency issues
+- Ensure Tesseract OCR is installed system-wide and in PATH
+- Virtual environment recommended to isolate Python packages
+- Check pynput documentation for platform-specific requirements
 
-References: `arrastools.py`, `arrasbot.py`, `arrasai.py`, `arras_models/`, `logs/`, `copypastas/`. Keep changes minimal and aligned with existing patterns.
+References: `arrastools.py`, `arrastools2.py`, `arrasbot.py`, `arrasai.py`, `arrascopypasta.py`, `arras_models/`, `logs/`, `copypastas/`. Keep changes minimal and aligned with existing patterns.

README.md

@@ -1 +1,214 @@
-# arrastools
+# arrastools
+
+Desktop automation tools and a PPO-based AI for Arras.io gameplay. Cross-platform support for macOS, Linux, and Windows.
+
+## Features
+
+- **Hotkey-driven automation** (`arrastools.py`, `arrastools2.py`): Control gameplay with keyboard shortcuts
+- **Game state monitoring** (`arrasbot.py`): Automatic detection of disconnection, death, and bans with logging
+- **PPO Reinforcement Learning AI** (`arrasai.py`): Train an AI agent to play Arras.io
+- **Copypasta automation** (`arrascopypasta.py`): Send text automatically with timing control
+- **Cross-platform**: Works on macOS, Linux (Arch/Debian/Ubuntu), and Windows
+
+## Platform Support
+
+### macOS
+✅ **Primary development platform** - Fully tested
+
+**Requirements:**
+- macOS 10.14 or later
+- Accessibility + Screen Recording permissions (System Settings > Privacy & Security)
+- Homebrew (recommended): `brew install tesseract`
+
+### Linux
+✅ **Tested on Arch, Debian, Ubuntu**
+
+**Requirements:**
+```bash
+# Debian/Ubuntu
+sudo apt install python3-tk tesseract-ocr
+
+# Arch
+sudo pacman -S tk tesseract
+```
+
+**Notes:**
+- Works best on X11; Wayland may have limitations with pynput
+- Accessibility permissions may vary by desktop environment
+- Use `SCALE=1` for standard displays
+
+### Windows
+✅ **Tested on Windows 10/11**
+
+**Requirements:**
+- [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki) (install separately, add to PATH)
+- May require running Terminal as Administrator for input automation
+- Use `SCALE=1` for standard displays
+
+### Android
+⚠️ **Experimental** - Limited support
+- pynput may not work on all devices
+- Consider using Termux with X11 server
+
+## Installation
+
+### 1. Clone the repository
+```bash
+git clone https://github.com/maple-underscore/arrastools.git
+cd arrastools
+```
+
+### 2. Create a virtual environment (recommended)
+```bash
+# Linux/macOS
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows
+python -m venv .venv
+.venv\Scripts\activate
+```
+
+### 3. Install Python dependencies
+```bash
+pip install pynput mss numpy ping3 pillow torch shapely pytesseract
+```
+
+### 4. Install system dependencies
+
+**macOS:**
+```bash
+brew install tesseract
+```
+
+**Linux (Debian/Ubuntu):**
+```bash
+sudo apt install python3-tk tesseract-ocr
+```
+
+**Windows:**
+- Download and install [Tesseract OCR](https://github.com/UB-Mannheim/tesseract/wiki)
+- Add Tesseract to your system PATH
+
+## Quick Start
+
+### Automation Tools
+```bash
+python arrastools.py
+```
+
+**Key shortcuts (hold Ctrl):**
+- `Ctrl+1` (press 1-3 times): Arena size automation
+- `Ctrl+y`: Controlled nuke (click two points)
+- `Alt+Arrow` (`Option+Arrow` on macOS): 1-pixel mouse movement
+- `Ctrl+9`: Nuke
+- `Ctrl+m`: Benchmark balls
+- `Esc`: Stop current activity
+- `Ctrl+Esc`: Emergency exit
+
+### Bot Monitor
+```bash
+python arrasbot.py
+```
+
+**CLI commands:**
+- `status`: Check bot state
+- `screenshot`: Take manual screenshot
+- `probe`: Sample pixel color at mouse position
+- `dbgmon`: List all monitors
+- `setscale <1|2>`: Set display scaling
+- `ping`: Check connection to arras.io
+
+### AI Training
+```bash
+python arrasai.py
+```
+
+**Hotkeys while training:**
+- `Esc`: Force stop
+- `p`: Pause/resume
+- `r`: Simulate death
+
+## Configuration
+
+### Display Scaling
+Adjust `SCALE` in `arrasbot.py` based on your display:
+- **Retina/HiDPI displays (macOS)**: `SCALE = 2`
+- **Standard displays (Windows/Linux)**: `SCALE = 1`
+
+### Game Region
+Update `GAME_REGION` coordinates in `arrasai.py` to match your screen resolution:
+```python
+GAME_REGION = Polygon([
+    (x1, y1), (x2, y2), ...  # Your screen coordinates
+])
+```
+
+Use `arrasbot.py` with the `probe` command to find your coordinates.
+
+### Click Positions
+Hard-coded positions in `arrastools.py` (e.g., `conq_quickstart()`) may need adjustment for different resolutions.
+
+## Project Structure
+
+```
+arrastools/
+├── arrastools.py          # Main automation script
+├── arrastools2.py         # Alternative automation script
+├── arrasbot.py            # Game state monitor
+├── arrasai.py             # PPO AI trainer
+├── arrascopypasta.py      # Text automation
+├── copypastas/            # Text files for copypasta
+├── arras_models/          # Saved AI models
+├── logs/                  # Bot logs
+└── .github/
+    └── copilot-instructions.md  # AI coding agent guidance
+```
+
+## Troubleshooting
+
+### Permission Issues
+
+**macOS:**
+- Go to System Settings > Privacy & Security
+- Enable Accessibility for your Terminal/IDE
+- Enable Screen Recording for your Terminal/IDE
+
+**Linux:**
+- Check if running on X11 (pynput works better than Wayland)
+- Accessibility permissions vary by desktop environment
+
+**Windows:**
+- Run Terminal as Administrator if automation fails
+- Ensure Tesseract is in your system PATH
+
+### Coordinate/Scaling Issues
+1. Use `arrasbot.py` command `dbgmon` to list monitor properties
+2. Use `probe` command to check pixel colors at cursor position
+3. Adjust `SCALE` variable (2 for HiDPI, 1 for standard)
+4. Re-map coordinates for your resolution
+
+### Dependency Issues
+- Ensure Tesseract OCR is installed system-wide
+- Use virtual environment to isolate Python packages
+- Check pynput documentation for platform-specific issues
+
+## Development
+
+See [.github/copilot-instructions.md](.github/copilot-instructions.md) for detailed development guidelines, conventions, and architecture notes.
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please:
+1. Test on your target platform (macOS/Linux/Windows)
+2. Use `pathlib` for file paths (cross-platform)
+3. Follow existing patterns (see copilot-instructions.md)
+4. Add platform detection for new scripts
+
+## Disclaimer
+
+This tool is for educational purposes. Use responsibly and in accordance with game terms of service.