AC Time Attack Bot - README

This README provides an overview of the core Python services used to power the automated Assetto Corsa Time Attack League. Each service runs independently (usually via systemd) and works together to maintain your event rotation, leaderboards, season standings, Discord postings, and database updates.

---

📂 File Overview

The following scripts make up the core of the AC Time Attack automation system:

• post_leaderboard.py – Posts and updates the live leaderboard message in Discord.
• post_schedule.py – Posts the season schedule with track/car icons and updates when seasonConfig.json changes.
• event_watcher.py – Watches for changes to the current event and triggers Discord alerts.
• update_db.py – Processes results JSON files and updates DynamoDB with new lap data.
• update_server.py – Rotates the AC server to the next event based on seasonConfig.json.
• update_standings.py – Calculates full season standings and posts them to Discord.

---

🏁 post_leaderboard.py

This service manages the live leaderboard message for the current event.

What it does

• Loads the current event ID (e.g., season1#preseason2).
• Reads the latest leaderboard.json generated by update_db.py.
• Creates a formatted leaderboard message.
• Posts it to Discord once, or edits the message if it already exists.
• Detects new laps via file hashing and updates the post in real time.
• Normalizes driver names using alias lookup (optional).

Output Example

**🏁 Season 1 - Event 2 🏁**
1. Rob Macaroni — 1:35.228
2. Wattson_ — 1:35.334

Inputs

• leaderboard.json
• Current event ID
• Environment variables (.env)

---

📅 post_schedule.py

This script posts a visual season schedule to Discord.

What it does

• Loads seasonConfig.json.
• Generates a formatted schedule list including:
  • Event number
  • Track name with flag emoji
  • Car list with car icons
  • Start date
• Skips events containing the word preseason (configurable).
• Posts the schedule OR edits an existing message.
• Monitors seasonConfig.json for edits and refreshes automatically.

Special Features

• Full flag table for all tracks.
• Car-to-emoji mapping.
• Centered event labels.

Inputs

• seasonConfig.json
• Environment variables (.env)

---

🔍 event_watcher.py

This service listens for changes to the current event and notifies Discord.

What it does

• Monitors currentEvent.json for modifications.
• When the event ID changes:
  • Reads the new event name.
  • Sends a Discord message announcing the change.
  • (Optional) triggers post_leaderboard.py to refresh.

Why it's important

Content Manager or your admin scripts rotate events — this broadcasts those changes.

Inputs

• currentEvent.json
• Environment variables (.env)

---

📊 update_db.py

Processes AC server results and updates your DynamoDB tables.

What it does

• Watches the AC server's /results folder.
• For every new result JSON:
  • Extracts:
    • Event ID
    • Driver GUID & name
    • Valid laps
    • Best lap time
  • Writes the lap into DynamoDB (partition key: event ID).
• Prevents duplicate processing using processed_files.json.
• Regenerates leaderboard.json.

Why it's important

This script is the bridge between Assetto Corsa and your automated leaderboard.

Inputs

• Result JSON files
• DynamoDB table
• processed_files.json
• leaderboard.json (output)

---

🔄 update_server.py

Automates event rotation on the Assetto Corsa server.

What it does

• Reads seasonConfig.json.
• Compares scheduled start dates with the current time.
• Determines which event should be active.
• Writes currentEvent.json.
• Updates the AC server config files.
• Restarts the AC server process.

Optional Features

• "Kick all players" before restart (works around AC not writing results when players stay connected).
• Logging for all server decisions.

Inputs

• seasonConfig.json
• System time
• Environment variables

---

🏆 update_standings.py

Generates your season standings and posts them to Discord.

What it does

• Reads all DynamoDB entries for the season.
• Computes:
  • Points per event
  • Total season points
  • Tie-breaking via best average lap
• Produces seasonStandings.json.
• Posts the standings to a Discord channel.
• Edits message if already posted.

Output Example

**Season 1 Standings**
1. Rob Macaroni — 72 pts
2. Wattson_ — 68 pts
3. LuigiCool — 55 pts

Inputs

• DynamoDB table
• seasonConfig.json
• Environment variables

---

🧩 Services & Automation

Each script is normally run under systemd, for example:

assetto-corsa-server.service
update-dynamo-db.servce
event-watcher.service
discord-leaderboard.service
discord-schedule.service
discord-standings.service

---

☁️ AWS Setup Requirements

This project relies on several AWS services to run reliably on your EC2 instance. Below is a breakdown of everything needed on the AWS side to get the full system functioning.

EC2 Instance (Core Server)

• Recommended instance: t3.micro
• Ubuntu 22.04 LTS
• 10GB gp3 storage
• Install SteamCMD, AC Server, Python3, Git, tmux
• Clone the repo and set up virtual environments

DynamoDB Table

Create a table Results:

• Partition Key: eventId (String)
• Sort Key: lapKey (String driverId#lapTimestamp) Stores lap times, cars, timestamps, driver names.

Environment Variables

A .env file located at:

/home/ubuntu/ac-timeattack-bot/.env

Includes Discord tokens, channel IDs, file paths, and optional AWS keys.

Systemd Services

Create a systemd unit for each script, for example:

[Unit]
Description=AC Time Attack - Leaderboard Bot
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/ac-timeattack-bot/bot
ExecStart=/home/ubuntu/ac-timeattack-bot/bot/bot-venv/bin/python3 post_leaderboard.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start services using:

sudo systemctl enable discord-leaderboard
sudo systemctl start discord-leaderboard

Logging Directory

Create:

/var/log/ac-timeattack/

Add to .gitignore.

📘 Summary

This automation suite turns the Assetto Corsa server into a fully automatic time-attack league:

• Live leaderboard updating
• Automatic event rotation
• Season standings
• Dynamic schedule posts
• Discord integration everywhere
• Database-backed lap history

Everything works together to eliminate manual work and keep the league always up to date.

---