# Heimdall WoW Addon

Heimdall is a comprehensive World of Warcraft addon designed to provide advanced player tracking, notification, and group management features.

## Overview

Heimdall is a multi-module addon that offers various functionalities to enhance player interaction and awareness in the game. It consists of several key modules, each with a specific purpose:

### 1. Spotter Module (`Spotter.lua`)
- Tracks and reports player sightings in real-time
- Configurable notification settings:
  - Detect players by faction (Alliance, Horde)
  - Identify hostile players
  - Mark "stinky" players (predefined list)
- Sends notifications to a specified channel when players are spotted
- Provides detailed information about spotted players:
  - Name
  - Race
  - Faction
  - Health
  - Location
- **Example report:**
	- "I see (Hostile) Atomickitty of race Blood Elf (Horde) with health 6.8M/6.8M at Orgrimmar (Valley of Strength)"
	- "I see (<reaction>) <name> of race <race> (<faction>) with health <health>/<healthMax> at <location>"
- Configuration:
	- `enabled` - Whether the module is enabled
	- `everyone` - Whether to report to everyone in the channel
	- `hostile` - Whether to report hostile players (regardless of faction, ie. when a horde becomes alliance)
	- `alliance` - Whether to report alliance players
	- `stinky` - Whether to report only stinky players
	- `notifyChannel` - The channel to report to (by name)
	- `zoneOverride` - The zone to override the zone of the player to report (defaults to current zone/subzone)
	- `throttleTime` - The time to throttle the reports to (in seconds)
- Configuration example:
```
/run Heimdall_Data.config.spotter = {enabled=true,everyone=false,hostile=true,alliance=true,stinky=true,notifyChannel="Agent",zoneOverride=nil,throttleTime=10}
```

### 2. Whoer Module (`Whoer.lua`)
- Advanced player tracking and logging system
- Periodically performs WHO queries in specific zones
- Maintains a persistent database of player information:
  - First seen
  - Last seen
  - Seen count
  - Zone history
- Sends notifications when:
  - New players are detected
  - Players change zones
  - Players disappear from tracking
- Supports whisper notifications to predefined contacts
- Plays sound alerts for "stinky" players
- **Example report:**
  - Player appeared:
    - "Любящаядева of class Mage, race Human (Alliance) and guild Анонимное сообщество in Valley of Trials, first seen: 2024-12-27T15:54:38, last seen: never, times seen: 0"
    - "<name> of class <class>, race <race> (<faction>) and guild <guild> in <zone>, first seen: <firstSeen>, last seen: <lastSeen>, times seen: <timesSeen>"
  - Player changed zone:
    - "Thekinglord of class Paladin (Human - Alliance) and guild Caminantes Nocturnos R moved to Durotar"
    - "<name> of class <class> (<faction>) and guild <guild> moved to <zone>"
  - Player disappeared:
    - "Thekinglord of class Paladin and guild Caminantes Nocturnos R left Valley of Trials"
    - "<name> of class <class> and guild <guild> left <zone>"
- Configuration:
  - `enabled` - Whether the module is enabled
  - `notifyChannel` - The channel to report to (by name)
  - `ttl` - The time to live for a player (in seconds)
  - `doWhisper` - Whether to whisper to predefined contacts
  - `zoneNotifyFor` - Whether to notify for players in specific zones
- Configuration example:
```
/run Heimdall_Data.config.who = {enabled=true,notifyChannel="Agent",ttl=20,doWhisper=true,zoneNotifyFor={["Orgrimmar"]=true,["Thunder Bluff"]=true,["Undercity"]=true,["Durotar"]=true,["Echo Isles"]=true,["Valley of Trials"]=true}}
```

### 3. Messenger Module (`Messenger.lua`)
- Centralized message queuing and sending system
- Manages message delivery across different chat channels
- Handles channel joining and message routing
- Provides a reliable messaging infrastructure for other modules
- Configuration:
  - `enabled` - Whether the module is enabled
- Configuration example:
```
/run Heimdall_Data.config.messenger = {enabled=true}
```

### 4. Inviter Module (`Inviter.lua`)
- Automated group invitation system
- Listens to a specific channel for invitation requests
- Supports a configurable keyword for invitations
- Automatically promotes channel members to assistants in raid groups
- Configuration:
  - `enabled` - Whether the module is enabled
  - `keyword` - The keyword to listen for
  - `updateInterval` - The interval to update the list of channel members (in seconds)
  - `listeningChannel` - The channel to listen for invitations
- Configuration example:
```
/run Heimdall_Data.config.inviter = {enabled=true,keyword="+",updateInterval=10,listeningChannel="Agent"}
```

### 5. Death Reporter Module (`DeathReporter.lua`)
- Tracks and reports player deaths in combat
- Captures detailed death information:
  - Killer
  - Victim
  - Killing spell
  - Location
- Implements throttling to prevent spam
- Handles duel detection to avoid reporting duel-related deaths
- Sends notifications to a specified channel and optional whisper contacts
- **Example report:**
  - "Euotuie killed Wild Mature Swine with Demon's Bite in Durotar (The Dranosh'ar Blockade)"
  - "<killer> killed <victim> with <spell> in <zone> (<subzone>)"
- Configuration:
  - `enabled` - Whether the module is enabled
  - `notifyChannel` - The channel to report to (by name)
  - `doWhisper` - Whether to whisper to predefined contacts
- Configuration example:
```
/run Heimdall_Data.config.deathReporter = {enabled=true,notifyChannel="Agent",doWhisper=true}
```

### 6. Core Module (`Heimdall.lua`)
- Initializes and configures all other modules
- Manages global configuration and data persistence
- Provides utility functions for:
  - UTF-8 string handling
  - String padding
  - Data retrieval with defaults

## Stinky Players

The addon maintains a list of "stinky" players - users of interest that trigger special notifications and tracking.

## Slash Commands

- `/has [PlayerName]`: Toggle a player's "stinky" status


## Installation
1. Download the [addon](https://git.site.quack-lab.dev/dave/wow-Heimdall/media/branch/master/Heimdall.zip)
2. Extract the addon to your World of Warcraft `Interface/AddOns` directory
3. Ensure the addon is enabled in the character selection screen

---

# Аддон Heimdall для WoW

Heimdall - это комплексный аддон для World of Warcraft, предназначенный для расширенного отслеживания игроков, уведомлений и управления группами.

## Обзор

Heimdall - это многомодульный аддон, предоставляющий различные функции для улучшения взаимодействия между игроками и повышения осведомленности в игре. Он состоит из нескольких ключевых модулей:

### 1. Модуль Обнаружения (`Spotter.lua`)
- Отслеживает и сообщает об обнаружении игроков в реальном времени
- Настраиваемые параметры уведомлений:
  - Обнаружение игроков по фракции (Альянс, Орда)
  - Определение враждебных игроков
  - Отметка "подозрительных" игроков (предопределенный список)
- Отправляет уведомления в указанный канал при обнаружении игроков
- Предоставляет подробную информацию об обнаруженных игроках:
  - Имя
  - Раса
  - Фракция
  - Здоровье
  - Местоположение
- **Пример отчета:**
  - "Обнаружен (Враждебный) Atomickitty расы Эльф Крови (Орда) со здоровьем 6.8M/6.8M в Оргриммаре (Долина Силы)"
  - "Обнаружен (<реакция>) <имя> расы <раса> (<фракция>) со здоровьем <здоровье>/<макс_здоровье> в <локация>"
- Конфигурация:
  - `enabled` - Включен ли модуль
  - `everyone` - Сообщать ли всем в канале
  - `hostile` - Сообщать ли о враждебных игроках
  - `alliance` - Сообщать ли об игроках Альянса
  - `stinky` - Сообщать ли только о подозрительных игроках
  - `notifyChannel` - Канал для отправки сообщений (по имени)
  - `zoneOverride` - Зона для переопределения местоположения игрока
  - `throttleTime` - Время задержки между сообщениями (в секундах)
- Пример конфигурации:
```
/run Heimdall_Data.config.spotter = {enabled=true,everyone=false,hostile=true,alliance=true,stinky=true,notifyChannel="Agent",zoneOverride=nil,throttleTime=10}
```

### 2. Модуль WHO (`Whoer.lua`)
- Продвинутая система отслеживания и логирования игроков
- Периодически выполняет WHO запросы в определенных зонах
- Поддерживает постоянную базу данных информации об игроках:
  - Первое появление
  - Последнее появление
  - Количество появлений
  - История зон
- Отправляет уведомления когда:
  - Обнаружены новые игроки
  - Игроки меняют зоны
  - Игроки исчезают из отслеживания
- Поддерживает уведомления шепотом предопределенным контактам
- Проигрывает звуковые оповещения для "подозрительных" игроков
- **Пример отчета:**
  - Появление игрока:
    - "Любящаядева класса Маг, раса Человек (Альянс) из гильдии Анонимное сообщество в Долине Испытаний, первое появление: 2024-12-27T15:54:38, последнее появление: никогда, появлений: 0"
  - Смена зоны:
    - "Thekinglord класса Паладин (Человек - Альянс) из гильдии Caminantes Nocturnos R переместился в Дуротар"
  - Исчезновение:
    - "Thekinglord класса Паладин из гильдии Caminantes Nocturnos R покинул Долину Испытаний"
- Конфигурация:
  - `enabled` - Включен ли модуль
  - `notifyChannel` - Канал для отправки сообщений
  - `ttl` - Время жизни записи об игроке (в секундах)
  - `doWhisper` - Отправлять ли шепот контактам
  - `zoneNotifyFor` - Уведомлять ли об игроках в определенных зонах
- Пример конфигурации:
```
/run Heimdall_Data.config.who = {enabled=true,notifyChannel="Agent",ttl=20,doWhisper=true,zoneNotifyFor={["Orgrimmar"]=true,["Thunder Bluff"]=true,["Undercity"]=true,["Durotar"]=true,["Echo Isles"]=true,["Valley of Trials"]=true}}
```

### 3. Модуль Сообщений (`Messenger.lua`)
- Централизованная система очередей и отправки сообщений
- Управляет доставкой сообщений по разным чат-каналам
- Обрабатывает присоединение к каналам и маршрутизацию сообщений
- Предоставляет надежную инфраструктуру сообщений для других модулей
- Конфигурация:
  - `enabled` - Включен ли модуль
- Пример конфигурации:
```
/run Heimdall_Data.config.messenger = {enabled=true}
```

### 4. Модуль Приглашений (`Inviter.lua`)
- Автоматическая система приглашений в группу
- Прослушивает определенный канал на запросы приглашений
- Поддерживает настраиваемое ключевое слово для приглашений
- Автоматически повышает участников канала до помощников в рейдовых группах
- Конфигурация:
  - `enabled` - Включен ли модуль
  - `keyword` - Ключевое слово для прослушивания
  - `updateInterval` - Интервал обновления списка участников канала (в секундах)
  - `listeningChannel` - Канал для прослушивания приглашений
- Пример конфигурации:
```
/run Heimdall_Data.config.inviter = {enabled=true,keyword="+",updateInterval=10,listeningChannel="Agent"}
```

### 5. Модуль Отчетов о Смертях (`DeathReporter.lua`)
- Отслеживает и сообщает о смертях игроков в бою
- Сохраняет подробную информацию о смерти:
  - Убийца
  - Жертва
  - Убивающее заклинание
  - Местоположение
- Реализует задержку для предотвращения спама
- Обрабатывает определение дуэлей во избежание сообщений о смертях в дуэлях
- Отправляет уведомления в указанный канал и опционально шепотом контактам
- **Пример отчета:**
  - "Euotuie убил Wild Mature Swine с помощью Demon's Bite в Дуротаре (Блокпост Дранош'ар)"
- Конфигурация:
  - `enabled` - Включен ли модуль
  - `notifyChannel` - Канал для отправки сообщений
  - `doWhisper` - Отправлять ли шепот контактам
- Пример конфигурации:
```
/run Heimdall_Data.config.deathReporter = {enabled=true,notifyChannel="Agent",doWhisper=true}
```

### 6. Основной Модуль (`Heimdall.lua`)
- Инициализирует и настраивает все остальные модули
- Управляет глобальной конфигурацией и сохранением данных
- Предоставляет служебные функции для:
  - Обработки UTF-8 строк
  - Выравнивания строк
  - Получения данных с значениями по умолчанию

## Подозрительные Игроки

Аддон поддерживает список "подозрительных" игроков - пользователей, представляющих интерес, которые вызывают специальные уведомления и отслеживание.

## Слэш-команды

- `/has [ИмяИгрока]`: Переключить статус "подозрительного" игрока

## Установка
1. Скачайте [аддон](https://git.site.quack-lab.dev/dave/wow-Heimdall/media/branch/master/Heimdall.zip)
2. Распакуйте аддон в директорию World of Warcraft `Interface/AddOns`
3. Убедитесь, что аддон включен на экране выбора персонажа