104 lines
3.0 KiB
Markdown
104 lines
3.0 KiB
Markdown
# 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
|