Lineage Bot Development Assistant

Expert assistant for developing and maintaining Python-based game automation bots for Lineage. Specializes in computer vision (OpenCV, YOLO), PyAutoGUI automation, threaded architecture, and state machine implementations.

What This Skill Does

This skill provides expert guidance for working with the Lineage bot codebase, which uses:

Computer vision (OpenCV, YOLO) for target detection

PyAutoGUI for automated game actions

Win32 API for window capture

Threaded architecture for real-time processing

State machines for bot behavior

Instructions

1. Project Understanding

When working with this codebase:

**Core Architecture**: The bot consists of three main threaded components:

- `WindowCapture`: Continuously captures game window screenshots using Win32 API

- `YoloDetection`: Processes frames for object detection in real-time

- `Bot`: Runs state machine logic and controls PyAutoGUI actions

**Coordinate Systems**: Always distinguish between:

- Screenshot coordinates (relative to captured image)

- Screen coordinates (absolute positions for PyAutoGUI)

- Use `get_screen_position()` for translation with 8px border and 30px titlebar offsets

**Character Position**: Always assumed to be at screen center (`window_w/2, window_h/2`)

2. Bot Development Workflow

When adding a new bot variant:

1. **Create bot directory structure**:

```

src/bots/new_area/

├── bot.py # Bot class with state machine

├── runner.py # Main entry point

└── variants/ # Optional variants (mage, warrior, etc.)

```

2. **Copy and customize bot class** from existing area (e.g., `chi2/bot.py`):

- Adjust tunable constants for area-specific behavior

- Configure detection radius (`INNER_IGNORE_RADIUS`, `OUTER_IGNORE_RADIUS`)

- Set skill cooldowns (`SKILL_F7_DELAY`, `SKILL_F9_DELAY`)

- Tune movement timers (`SKILL_MOVE_DELAY`, `DETECTION_WAITING_THRESHOLD`)

3. **Implement state machine logic** with states:

- `INITIALIZING`: Setup phase

- `SEARCHING`: Looking for targets

- `MOVING`: Character movement

- `MINING`: Combat/interaction

- `BACKTRACKING`: Recovery state

4. **Create runner script** in `scripts/run_new_area.py`:

- Initialize WindowCapture with game window title

- Initialize YoloDetection with model path (`models/yolo/area_name.pt`)

- Initialize Vision and Bot instances

- Coordinate threaded execution with proper Lock synchronization

5. **Add batch script** in `bin/new_area.bat` for Windows execution

3. Model Training and Integration

When working with detection models:

1. **Collect training data** using `tools/capture.py`

2. **Train YOLO model** using external tools (Ultralytics, Roboflow)

3. **Place trained model** in `models/yolo/area_name.pt`

4. **Test model** using `tools/train/test_yolo_img.py`

5. **Adjust confidence threshold** in runner script (typically 0.5-0.7)

4. Threading and Synchronization

When implementing threaded components:

Use `threading.Lock()` for shared state protection

Follow pattern: `Lock.acquire()` → modify state → `Lock.release()`

Set daemon threads appropriately (`daemon=True` for worker threads)

Implement clean shutdown with stop flags

5. Target Management

When implementing target detection and selection:

1. **Filter targets by distance** using `targets_ordered_by_distance()`:

- Apply inner/outer radius constraints

- Calculate pythagorean distance from screen center

2. **Deduplicate targets** using ignore list:

- Store summed coordinates `(x + y + distance)` in `ignore_positions`

- Check with `is_duplicated_target()` before attacking

- Clear on F5 press (movement action)

3. **Prioritize targets** by distance (closest first)

6. Debugging and Testing

When debugging bot behavior:

**Enable DEBUG mode**: Set `DEBUG = True` in runner script for OpenCV visualization

**Use keyboard controls**:

- `q`: Quit bot

- `p`: Pause execution

- `c`: Continue execution

**Monitor console output**: State transitions, target detections, timing logs

**Check ignore list growth**: Verify target deduplication is working

7. Code Organization

When organizing code:

**Use absolute imports** from project root: `from src.core.detection.yolo import YoloDetection`

**Place reusable components** in `src/core/`

**Place bot implementations** in `src/bots/area_name/`

**Place entry scripts** in `scripts/`

**Place models** in `models/yolo/` or `models/cascade/`

**Place development tools** in `tools/`

8. Bot Configuration

When configuring bot behavior:

```python

Detection range (pixels from screen center)

INNER_IGNORE_RADIUS = 0 # Minimum detection distance

OUTER_IGNORE_RADIUS = 500 # Maximum detection distance

Skill timing (seconds)

SKILL_F7_DELAY = 10.0 # F7 skill cooldown

SKILL_F9_DELAY = 15.0 # F9 skill cooldown

SKILL_MOVE_DELAY = 25.0 # Time before triggering movement

Detection behavior

DETECTION_WAITING_THRESHOLD = 6.0 # Timeout before moving (no targets)

ATTACK_INTERVAL = 1.2 # Duration of attack action

Feature flags

ENABLE_F7 = True

ENABLE_F9 = True

ENABLE_MOVING = True

```

9. Environment Setup

When setting up development environment:

1. **Create virtual environment**: `python -m venv .venv`

2. **Activate environment**:

- Windows: `.\.venv\Scripts\activate`

- macOS/Linux: `source .venv/bin/activate`

3. **Install dependencies**: `pip install -r requirements.txt`

4. **Note**: Requires Windows for Win32 API (pywin32 dependency)

10. Common Patterns

When implementing bot features:

**Skill timing**: Use `time.time()` to track last skill usage, check elapsed time before triggering

**State transitions**: Always log state changes for debugging

**Movement trigger**: Press F5 when no targets detected for threshold duration

**Window capture offsets**: Account for 8px border and 30px titlebar in coordinate translation

**Thread-safe state updates**: Always use locks when modifying shared state across threads

Examples

Example 1: Creating a New Bot for "Forest3" Area

```python

1. Create src/bots/forest3/bot.py

from src.core.bot_base import BotBase

class Forest3Bot(BotBase):

INNER_IGNORE_RADIUS = 50

OUTER_IGNORE_RADIUS = 450

SKILL_F7_DELAY = 12.0

SKILL_F9_DELAY = 18.0

SKILL_MOVE_DELAY = 30.0

# ... implement state machine logic

2. Create src/bots/forest3/runner.py

from src.core.window_capture import WindowCapture

from src.core.detection.yolo import YoloDetection

from src.bots.forest3.bot import Forest3Bot

def main():

wincap = WindowCapture('Lineage')

detector = YoloDetection('models/yolo/forest3.pt', conf=0.6)

bot = Forest3Bot(wincap, detector)

# Start threads and run...

3. Create scripts/run_forest3.py

from src.bots.forest3.runner import main

if __name__ == '__main__':

main()

4. Create bin/forest3.bat

... batch script to run scripts/run_forest3.py

```

Example 2: Implementing Target Selection Logic

```python

from src.core.utils.bot_utils import targets_ordered_by_distance, find_next_target

In bot's update() method

click_points = self.vision.get_click_points()

ordered_targets = targets_ordered_by_distance(

click_points,

self.wincap.w // 2,

self.wincap.h // 2,

self.INNER_IGNORE_RADIUS,

self.OUTER_IGNORE_RADIUS

)

target = find_next_target(ordered_targets, self.ignore_positions)

if target:

x, y, distance = target

screen_x, screen_y = self.wincap.get_screen_position((x, y))

pyautogui.click(screen_x, screen_y)

self.ignore_positions.append(x + y + distance)

```

Important Notes

**Windows-only**: Requires Win32 API (pywin32) for window capture

**Game window must be visible**: Bot captures active window, cannot work minimized

**Thread safety**: Always use locks when sharing state between threads

**Model paths**: Use relative paths from project root (e.g., `'models/yolo/chi2.pt'`)

**Legacy code**: `lin_bot/` directory and `tools/legacy/tutorial/` are deprecated but preserved for reference

**Coordinate translation**: Always use `get_screen_position()` when converting from screenshot to screen coordinates for PyAutoGUI actions

Lineage Bot Development Assistant

Lineage Bot Development Assistant

What This Skill Does

Instructions

1. Project Understanding

2. Bot Development Workflow

3. Model Training and Integration

4. Threading and Synchronization

5. Target Management

6. Debugging and Testing

7. Code Organization

8. Bot Configuration

Detection range (pixels from screen center)

Skill timing (seconds)

Detection behavior

Feature flags

9. Environment Setup

10. Common Patterns

Examples

Example 1: Creating a New Bot for "Forest3" Area

1. Create src/bots/forest3/bot.py

2. Create src/bots/forest3/runner.py

3. Create scripts/run_forest3.py

4. Create bin/forest3.bat

... batch script to run scripts/run_forest3.py

Example 2: Implementing Target Selection Logic

In bot's update() method

Important Notes

Reviews (0)