WiseOldMan Rank-Up Tracker

A configurable application that queries the WiseOldMan API to identify clan members eligible for rank-ups based on customizable criteria such as activity, time in clan, experience levels, and more. Automatically generates reports and sends notifications to Discord.

Features

• 🎯 Intelligent Rule Engine: Configurable criteria for rank-up eligibility
• 📊 Activity Analysis: Tracks member activity using WiseOldMan gain data
• ⏰ Tenure Tracking: Considers time spent in the clan
• 🚫 Role Exclusions: Prevents promoting already high-ranking members
• 📝 Multiple Output Formats: JSON reports and human-readable summaries
• 🔔 Discord Integration: Automated webhook notifications with rich embeds
• 🛡️ Dry Run Mode: Test configurations without sending notifications

Installation

1. Download or Build

   # Option 1: Build from source
   git clone <repository-url>
   cd rankforge
   go build -o rankforge .
   
   # Option 2: Download pre-built binary (if available)
   # Download from releases page

2. Configuration

   # Copy the example configuration
   cp config.yaml my-clan-config.yaml
   
   # Edit with your clan's settings
   nano my-clan-config.yaml

Configuration

Edit config.yaml with your clan's specific settings. See config.example.yaml for a complete example.

# WiseOldMan group ID (find this in your group URL)
group_id: 139

# Discord webhook URL
discord_webhook: "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"

# Rank definitions with predecessor relationships
ranks:
  member:
    predecessors: []  # Entry-level rank

  member+:
    predecessors: [member]
    promotion_criteria:
      min_days_since_last_rankup: 7
      min_xp_since_last_rankup: 500000
      min_bosses_killed_since_last_rankup: 0
      activity_logic: "OR"

  recruit:
    predecessors: [member+]
    promotion_criteria:
      min_days_since_last_rankup: 14
      min_xp_since_last_rankup: 2000000
      min_bosses_killed_since_last_rankup: 10
      activity_logic: "AND"  # Must meet BOTH XP and boss requirements

  corporal:
    predecessors: [recruit]
    # Uses default criteria (no override)

  # ... additional ranks ...

# Global promotion rules
promotion_rules:
  exclude_roles: [leader, administrator]
  max_rank: "general"

  # Default criteria (applied unless rank overrides)
  default_criteria:
    min_days_since_last_rankup: 30
    min_xp_since_last_rankup: 1000000
    min_bosses_killed_since_last_rankup: 0
    activity_logic: "OR"  # XP OR bosses

Key Configuration Concepts:

• Predecessors: Each rank lists which rank(s) can be promoted to it
• Per-Rank Criteria: Customize promotion requirements for specific ranks
• Default Criteria: Applied to ranks without custom criteria
• Activity Logic:
  • "OR": Either XP or boss kills satisfies requirement
  • "AND": Both XP and boss kills must be met

Finding Your Group ID

1. Go to wiseoldman.net
2. Navigate to your group page
3. The group ID is in the URL: wiseoldman.net/groups/[GROUP_ID]

Setting Up Discord Webhook

1. In Discord, go to Server Settings → Integrations → Webhooks
2. Create a new webhook for your desired channel
3. Copy the webhook URL to your config file

Usage

Basic Usage

# Run with default config file (config.yaml)
./rankforge

# Use custom config file
./rankforge -config my-clan-config.yaml

# Specify custom output directory
./rankforge -output ./reports

# Enable verbose logging
./rankforge -verbose

Dry Run Mode

Test your configuration without sending Discord notifications:

./rankforge -dry-run

Command Line Options

• -config string: Path to configuration file (default: "config.yaml")
• -output string: Directory for output files (default: "output")
• -dry-run: Run without sending Discord notifications
• -verbose: Enable detailed logging

Output Files

The application generates three types of output files in the specified directory:

1. eligible_members_TIMESTAMP.json: JSON list of eligible members with detailed scoring
2. full_report_TIMESTAMP.json: Complete report including all members and their evaluation results
3. summary_TIMESTAMP.txt: Human-readable summary for quick review

Rule Engine

Eligibility Criteria

Members are evaluated against the following criteria for their target rank:

1. Role Exclusion: Members with excluded roles are automatically ineligible
2. Rank Ceiling: Must be below the configured maximum rank
3. Valid Predecessor: Current rank must be a valid predecessor to target rank
4. Time Since Last Rankup: Must have been at current rank for minimum days
5. Activity Requirements (evaluated based on activity_logic):
   • XP Gains: Minimum XP gained (since last rankup or in period)
   • Boss Kills: Minimum boss kills (since last rankup or in period)
   • Logic: "OR" (either) or "AND" (both) requirements must be met

Rank System

Ranks are defined in a predecessor-based graph where:

• Each rank declares which rank(s) can be promoted to it
• Multiple paths to a rank are supported
• Entry-level ranks have no predecessors
• The system validates for cycles and ensures all ranks are reachable

Example hierarchy:

member (entry) → member+ → recruit → corporal → sergeant → ...

Per-Rank Customization:

• Each rank can override default promotion criteria
• Allows for faster progression at lower ranks
• Stricter requirements for higher ranks
• Flexible boss kill requirements

Discord Notifications

The Discord webhook sends rich embed messages containing:

• 📊 Summary Statistics: Total members, eligible count, XP gains, boss kills
• 👥 Eligible Members List: Display names, rank transitions (current → next)
• 📈 Activity Metrics: Days since rankup, XP gained, boss kills
• 🎨 Color Coding: Green for eligible members, orange when none found

Example notification format:

1. PlayerName (member+ → recruit) | 45d since promo | 2.5M XP | 15 bosses

Automation

Cron Job Setup

Run automatically using cron:

# Edit crontab
crontab -e

# Run daily at 9 AM
0 9 * * * /path/to/rankforge -config /path/to/config.yaml

# Run weekly on Sundays at 10 AM
0 10 * * 0 /path/to/rankforge -config /path/to/config.yaml

Systemd Timer (Linux)

Create a systemd service and timer for more advanced scheduling:

# /etc/systemd/system/rankforge.service
[Unit]
Description=WiseOldMan Rank-Up Tracker
After=network.target

[Service]
Type=oneshot
ExecStart=/path/to/rankforge -config /path/to/config.yaml
User=your-user
Group=your-group

# /etc/systemd/system/rankforge.timer
[Unit]
Description=Run rankforge weekly
Requires=rankforge.service

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

Migrating from Old Config Format

If you're upgrading from an older version that used rank_hierarchy and global criteria:

1. See MIGRATION.md for detailed migration instructions
2. Use config.example.yaml as a reference
3. Key changes:
   • rank_hierarchy → ranks with predecessors
   • Global criteria → default_criteria with per-rank overrides
   • activity_requirements.min_exp_gained → min_xp_since_last_rankup
   • New: Boss kill tracking and AND/OR logic

Troubleshooting

Common Issues

1. "Failed to fetch group details"

   • Verify your group ID is correct
   • Check internet connectivity
   • Ensure the group exists and is public

2. "Failed to load configuration"

   • Verify the config file path and format
   • Check YAML syntax (use a YAML validator)
   • If upgrading, see MIGRATION.md for config format changes

3. "cycle detected in rank graph"

   • A rank lists itself as a predecessor (directly or indirectly)
   • Review your predecessors - each rank should only reference lower ranks

4. "rank 'X' is not reachable from any entry-level rank"

   • Ensure all ranks have a path from an entry-level rank (one with no predecessors)
   • Check that your rank graph is properly connected

5. "Webhook returned status code XXX"

   • Verify Discord webhook URL is correct
   • Check webhook permissions in Discord
   • Ensure the webhook hasn't been deleted

6. "Could not fetch gains for player" / "Could not fetch boss data"

   • This is often expected for inactive players
   • The application will continue processing other members
   • Boss data requires additional API calls (only fetched if needed)

Verbose Logging

Enable verbose logging to debug issues:

./rankforge -verbose

This provides detailed information about:

• API requests and responses
• Rank graph validation
• Per-rank criteria evaluation
• Boss kill tracking (if enabled)
• File generation process
• Discord notification attempts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

[Add your license information here]

Support

• Issues: Report bugs and feature requests on GitHub
• Documentation: Check this README and inline code comments
• WiseOldMan API: Refer to WiseOldMan API documentation

---

Note: This application respects WiseOldMan's API rate limits and includes appropriate error handling for network issues. Always test with -dry-run before deploying to production.