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:
- Collect all needed record data from speedrun.com API for every level and category of Hitman 3
- 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
- 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:
- 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 asDISCORD_TOKEN
(See Discord Token Documentation) - Run
python main.py
- Code formatting:
black ./
(from root directory of this repo)
- 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
- Also helpful for cron job syntax: https://crontab.guru
- Add Railway variable for
Add the bot to your own Discord server with this URL or you can also DM it at Hitruns Records Bot#1656
.
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. eithershowstopper
orparis
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 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