# Wordtrack Trigger

Automatically tracks word usage by users and awards level-ups based on configurable thresholds.

## How It Works

The wordtrack trigger monitors all channel messages and counts occurrences of tracked words across different categories. Users automatically level up when they reach configured thresholds.

## Files

- `wordtrack.sh` - Main trigger script (called automatically on messages)
- `categories.sh` - Configuration file defining categories, words, and levels
- `data/<channel>/<nick>.dat` - Per-user tracking data

## Modules

Users can interact with wordtrack using these command modules:

### `.wordtrack-stats [nick]`
Shows word tracking statistics for yourself or another user.

Example:
```
.wordtrack-stats
.wordtrack-stats alice
```

Output: `alice's word tracking stats: coffee: Coffee Lover (50/100, 50 to next) | tea: Tea Sipper (12/25, 13 to next)`

### `.wordtrack-leaders <category>`
Shows top 5 users in a category.

Example:
```
.wordtrack-leaders coffee
.wordtrack-leaders
```

Output: `Top coffee users: 1. alice: Coffee Lover (50 words) | 2. bob: Coffee Drinker (30 words) | 3. charlie: Coffee Newbie (15 words)`

If no category is provided, lists available categories.

## Configuration

Edit `categories.sh` to add new categories or modify existing ones.

### Adding a New Category

1. Create a word array: `categoryWords=("word1" "word2" "word3")`
2. Create a levels array: `declare -A categoryLevels=([threshold1]="Level Name" [threshold2]="Level Name")`
3. Add category to the categories list: `categories=("coffee" "tea" "yournewcategory")`

Example:
```bash
# Category: programming
programmingWords=("code" "coding" "python" "javascript" "rust" "git" "debug")

declare -A programmingLevels=(
    [10]="Code Newbie"
    [25]="Junior Dev"
    [50]="Developer"
    [100]="Senior Dev"
    [200]="Code Wizard"
)

# Add to categories list
categories=("coffee" "tea" "gaming" "programming")
```

### Array Structure

- **Word arrays**: Simple indexed arrays containing words to track
  - Words are matched case-insensitively
  - Multiple word matches in one message count separately

- **Level arrays**: Associative arrays with threshold as key, level name as value
  - Keys must be integers representing word counts
  - Users advance when their count meets or exceeds the threshold
  - Thresholds can be any positive integer

## Data Format

User data files (`data/<channel>/<nick>.dat`) use simple key=value format:

```
coffee=45
tea=12
gaming=78
```

## Integration with bot.sh

The wordtrack trigger is called automatically for all channel messages from users not in the ignoreList (bot.sh:254-262). It processes messages after the keywords trigger.

Level-up announcements are sent to the channel automatically when thresholds are crossed.

## Notes

- Users in the `ignoreList` are not tracked
- Word matching is case-insensitive
- Multiple occurrences of tracked words in a single message all count
- Data persists across bot restarts (stored in flat files)
- Each channel has independent tracking data