stormbot/triggers/wordtrack/README.md

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:

# 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