Artemis

Artemis is a full ranked Hide and Seek bot for the game Among Us. It is built using Python and the Nextcord library. It is designed to work with the Impostor server and is not intended for use with other servers.

Directory Structure

.
├── Artemis
│   ├── artemisMain.py
│   ├── leaderboardCog.py
│   ├── linkCog.py
│   ├── staticWorkers.py
│   ├── tokenization.py
│   └── universal_logging.py
└── ImpServ
    ├── Boot.Codes
    │   └── Boot.Codes.txt
    ├── Impostor.Api.pdb
    ├── Impostor.Api.xml
    ├── Impostor.Server
    ├── Impostor.Server.pdb
    ├── Impostor.Server.xml
    ├── Serilog.Sinks.File.dll
    ├── dir.txt
    ├── logs
    │   └── autogenerated Impostor Server log via Serilog
    ├── packages.lock.json
    └── plugins
        ├── Boot.Codes.dll
        ├── NewHideAndSeeker.dll
        ├── UtilityFunctions.py
        ├── dir.txt
        ├── hideAndSeek
        │   ├── hideAndSeek.db
        │   └── rawEventData
        │       └── multiple JSON files
        ├── hideAndSeekDB.py
        ├── infoClasses.py
        ├── newMatchProcessor.py
        ├── universalLogging.py
        └── universal_log.log

Current Install Instructions

1. Build the NewHideAndSeeker plugin from the HNSPlugin folder.
2. Install Python 3.10 or higher on the server.
3. Create a bot in the discord developer portal, get the token, and put it in the tokenization.py file.
4. Install the required packages using pip.

   Flask==3.0.3
   Flask-SQLAlchemy==3.1.1
   nextcord==2.6.0
   requests==2.25.1
   SQLAlchemy==2.0.34

5. Set up Impostor Server, and set up nginx to make the server accessible to mobile devices (needs SSL) For help with this, see the nginx-setup.md file.
6. Once the server is set up, create the plugins folder in the Impostor Server folder and copy the NewHideAndSeeker.dll file to the plugins folder
7. Then, copy hideAndSeekDB.py, infoClasses.py, newMatchProcessor.py, universalLogging.py, UtilityFunctions.py, and infoClasses.py to the plugins folder. GameSearchAPI.py and playerProfileProcessor.py are useless for now.
8. Impostor Server is now set up for use. When you want to launch the server, use the following commands for a screen session:

   screen -S imp #you can use -r if you already have a screen session open
   cd [Impostor Server Folder] 
   chmod +x Impostor.Server #only do this once to make the server executable
   ./Impostor.Server

9. Make a new folder for the Artemis bot, and copy the contents of the Artemis folder to the new folder.
10. Use screen to run the bot:

    screen -S artemis
    cd [Artemis Folder]
    python3 artemisMain.py

11. That's it! The bot should now be running, and able to handle all games and commands.

Current Commands (Artemis)

1. /link [name] - Links a user's Discord account to their Among Us name, adding it to the database if not already used or blacklisted.

2. /nickname - Retrieves and displays the user's linked Among Us name, if a link exists.

3. /leaderboard - Opens an interactive menu allowing users to select different leaderboard categories.

4. /overall - Displays a paginated leaderboard ranked by overall player scores.

5. /crew (or /crewmate) - Shows a paginated leaderboard ranked by crew scores.

6. /imp (or /impostor) - Displays a paginated leaderboard ranked by impostor scores.

7. /stats [member] - Displays detailed statistics for a specified player or the user if no member is mentioned.

8. /threshold [threshold] - Sets the minimum number of games required for leaderboard eligibility (restricted to bot owner).

9. /game_info [game_id] - Displays detailed information about a specific game by game ID.

Planned Features

Impostor Server Modifications

• Remove fast kill bug from server sided code. (will write separate md for this)
• Disabling zipline and ladder for Fungle
• Multi Lobby Support (PLUGIN REWRITE)
• Multi Map Support (NEXT UP!)

Artemis Bot Modifications

• SET GAME CUTOFF TO LAST 180 CREW, LAST 25 IMP GAMES
• Review Game commands
• Nickname Changing
• Live Match History
• Player Match History
• Game Specific Information

General Improvements

• Replay Viewer
• Frontend website for stats, leaderboards, and match history
• Rewrite bot for better readability and functionality.

Setup Improvements

• Easier setup for new people
• Containerization

Bot Architecture

The Artemis bot system consists of several components:

1. artemisMain.py: This is the main entry point of the bot. It initializes the Discord bot, sets up intents, and loads the necessary cogs (LinkCog and LeaderboardCog). It also handles the bot's ready event and sets the owner ID.

2. linkCog.py: This cog handles the linking of Discord accounts to Among Us names. It includes:

   • The /link command to associate a Discord ID with an Among Us name
   • Database interactions to store and retrieve link information
   • Blacklist functionality to prevent certain users from linking

3. leaderboardCog.py: This cog manages leaderboard-related functionality, including:

   • Various leaderboard commands (/leaderboard, /overall, /crew, /imp)
   • The /stats command for individual player statistics
   • The /threshold command to set minimum game requirements
   • The /game_info command to fetch specific game details
   • Interaction with an external API to fetch game data

4. staticWorkers.py: This file likely contains utility functions, such as database cursor creation, used across multiple cogs.

5. tokenization.py: This file manages bot tokens securely, keeping sensitive information separate from the main code.

The system works as follows:

1. Players link their Discord accounts to Among Us names using the /link command.
2. As games are played, the Impostor server likely sends game data to the bot or updates the database directly.
3. The bot processes this data, updating player statistics and leaderboards.
4. Users can then query various leaderboards, view individual stats, and get information about specific games using the provided commands.

Game Server Architecture

The game server architecture is as follows:

1. Impostor Server: The game server is the core of the system, handling game logic, player interactions, and communication with the bot. This is slightly modified, as sometimes on high ping, a player will click the kill button too fast on the same person, kicking them out of the game. This is fixed in the server sided code, but the server needs to be modded internally to fix it.

2. NewHideAndSeek Plugin: This plugin is used to add Hide and Seek functionality to the game. It is responsible for handling game start/end events, player kills, and other game related data, and inserts this data into the database.

3. hideAndSeekDB.py: This file contains the database schema for the game, paths for the database, and functions to interact with the database.

4. infoClasses.py: This file contains the data classes used to store game information.

5. newMatchProcessor.py: This file contains the code to process new matches and add them to the database. This includes the code to handle the game starting, ending, and processing kills.

6. universalLogging.py: This file contains the code to handle logging for the game. This is used to log game related data, such as player kills, game start/end events, and other game related information.

7. UtilityFunctions.py: This file contains utility functions used by the plugin. These are used to handle database operations, logging, and other tasks.

Database Schema

The database schema is as follows:

1. discord_links: This table stores the links between Discord IDs and Among Us names.

   • discordID (TEXT): The Discord ID of the player.
   • amongUsName (TEXT): The Among Us name of the player.
   • blacklist (INTEGER): A flag indicating if the player is blacklisted (0 or 1).

2. match: This table stores information about each game.

   • gameID (INTEGER): The ID of the game.
   • gameStarted (INTEGER): The timestamp of when the game started.
   • players (TEXT): The names of the players in the game.
   • impostor (TEXT): The name of the impostor in the game.
   • eventsLogFile (TEXT): The name of the file containing the game events.

3. held_for_review: This table stores information about games that are held for review.

   • reviewID (INTEGER): The ID of the review.
   • gameStarted (INTEGER): The timestamp of when the game started.
   • players (TEXT): The names of the players in the game.
   • impostor (TEXT): The name of the impostor in the game.
   • eventsLogFile (TEXT): The name of the file containing the game events.
   • reviewReason (TEXT): The reason the game is being reviewed.

4. player_points: This table stores the statistics for each player.

   • discordID (TEXT): The Discord ID of the player.
   • games (INTEGER): The number of games the player has played.
   • crew_points (INTEGER): The number of points the player has earned as a crewmate.
   • imp_points (INTEGER): The number of points the player has earned as an impostor.
   • crew_factor (INTEGER): An internal factor used to adjust the player's score for their performance over time.
   • imp_factor (INTEGER): An internal factor used to adjust the player's score for their performance over time.
   • avg_do_placement (INTEGER): The average placement of the player in death order.
   • crew_games (INTEGER): The number of games the player has played as a crewmate.
   • imp_games (INTEGER): The number of games the player has played as an impostor.
   • avg_kpg (INTEGER): The average number of kills per game for the player.
   • avg_contribution (INTEGER): The average task point contribution per game for the player.