solderq35/hitruns-records-bot

Discord Bot that tracks miscellaneous Hitman speedrun statistics, such as untied world records and sums of bests

Hitruns Records Bot

Discord bot that tracks Hitman 3 speedrun statistics not on speedrun.com, such as fetching latest world records, filtering records by tie status, and calculating sums of bests.

Includes:

• Data Caching: The bot runs a daily cron job to:
  1. Collect all needed record data from speedrun.com API for every level and category of Hitman 3
  2. Transform and store record data in the bot's own database under a condensed and simplified schema
     • This reduces the number of API calls that would otherwise be needed for calculating sum of bests or fetching the latest records across all levels
  • For more implementation / usage details, see Setup and Commands sections below. Manually updating the bot's database is also supported
• Sorting records chronologically (oldest to newest, or newest to oldest)
• Filtering for untied vs tied records
• Full game theoretical Sum of Bests based on individual level best times
• Leaderboards for any given level / full game category (faster than going through speedrun.com itself)
• Video links included for all runs, and also a Time Calc link is included for full game runs

Credits: Although I've made a lot of improvements to this bot since, and also improved its reliability by using Railway for cloud based hosting, Juliend10 was a major collaborator early into the bot's development.

For a more traditional leaderboard implementation, also check out:

• HitRuns
  • GitHub Repo

Setup

Local Environment

• Make sure you have Python 3.8+ installed locally and in your PATH (for Windows)
• Pip version (if relevant): pip 23.3.1, from Python 3.8
• Run pip install -r requirements.txt
• Run pip freeze > requirements.txt to save library dependencies (only if you need to add a library or change dependencies for any other reason)
• Create a .env file with your Discord token listed as DISCORD_TOKEN (See Discord Token Documentation)
• Run python main.py
• Code formatting: black ./ (from root directory of this repo)

Remote Environment

• Dependencies should be handled by requirements.txt
• Deploy on Railway
  • Add Railway variable for DISCORD_TOKEN (See Discord Token Documentation)
  • I believe the default Python version on Railway is 3.8. (See this link for more info)
  • Set the start command to python cron.py && python main.py to ensure the data is updated before the bot starts
  • Set up a daily cron job to automatically update data by following https://bookmarklets.up.railway.app/cron-config/
    • Also helpful for cron job syntax: https://crontab.guru
      • I used this specific config for a cron job every day at 12 PM UTC

Usage Instructions

Add the bot to your own Discord server with this URL or you can also DM it at Hitruns Records Bot#1656.

Commands

You can also use !docs command to see this help menu in Discord itself.

• !records all <amount>
  • Returns both tied and untied records, sorted by oldest to newest
• !records all-new <amount>
  • Returns both tied and untied records, sorted by newest to oldest
• !records untied <amount>
  • Returns untied records, sorted by oldest to newest
• !records untied-new <amount>
  • Returns untied records, sorted by newest to oldest
• !records <level / fullgame category> <rating> <amount>
  • Returns a single leaderboard for a level / fullgame category and rating
  • Any substring of a <level name> or <fullgame category> long enough to uniquely identify it will work, e.g. either showstopper or paris would be valid. See data/levelDict.json and data/campaignDict.json (or !levelNames and !fgNames discord commands) for a full list of names
  • Any level or fullgame category name you input that contains a space (e.g. "season 3" or "a gilded cage") should be surrounded by quotes
  • Valid <rating> inputs: sa, saso, or `any
  • Unlike the other commands listed here, even if Recorddata (the bot's database) has not been updated recently, this command will still return up-to-date results
• !sobs
  • Calculates theoretical best times for full game categories, by summing up individual level record times
• !getLogs
  • See when Recorddata (the bot's database) was last updated (tracks both manual updates and cron job automated updates, which happen each day at 12 PM UTC)
• !updateRecords
  • Updates Recorddata (the bot's database) manually if you need more precision than last 24 hours
  • Can also be "queued" with some other commands, e.g. !updateRecords all-new <amount>, or !updateRecords sobs

Note: Bot will be down for a minute or two at 12 PM UTC each day for Recorddata (bot database) update

Note: <amount> is optional. If not set, the max amount of records will be returned

Command / Argument Troubleshooting

• Command names (anything starting with !) are case sensitive. Make sure to type !updateRecords with correct capitalization
• Arguments are case-insensitive (any capitalization will work)
• Arguments must be provided in the same order as in the Commands list above
• <amount> argument is optional for every command (bot will default to maximum length)
• !updateRecords can be a bit slow to update, it's normal to have to wait a minute or two for it to complete
• All arguments are generally optional for !updateRecords

Screenshots / Examples