{"id":22874491,"url":"https://github.com/txtsd/idlezpgbot","last_synced_at":"2025-03-31T12:43:23.786Z","repository":{"id":266482616,"uuid":"898369707","full_name":"txtsd/IdleZPGBot","owner":"txtsd","description":"The #IdleZPG Bot","archived":false,"fork":false,"pushed_at":"2024-12-30T10:43:11.000Z","size":229,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T18:52:33.903Z","etag":null,"topics":["idle-game","idlerpg","irc","irc-bot","zpg"],"latest_commit_sha":null,"homepage":"https://github.com/txtsd/IdleZPGBot","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/txtsd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-04T09:19:34.000Z","updated_at":"2024-12-30T10:43:14.000Z","dependencies_parsed_at":"2024-12-30T04:33:21.543Z","dependency_job_id":null,"html_url":"https://github.com/txtsd/IdleZPGBot","commit_stats":null,"previous_names":["txtsd/idlezpgbot"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txtsd%2FIdleZPGBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txtsd%2FIdleZPGBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txtsd%2FIdleZPGBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txtsd%2FIdleZPGBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/txtsd","download_url":"https://codeload.github.com/txtsd/IdleZPGBot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246472582,"owners_count":20783225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["idle-game","idlerpg","irc","irc-bot","zpg"],"created_at":"2024-12-13T14:38:01.679Z","updated_at":"2025-03-31T12:43:23.761Z","avatar_url":"https://github.com/txtsd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IdleZPGBot\n\n## Overview\n\nIdleZPGBot is an IRCv3 bot designed to connect securely to an IRC server, authenticate using the SASL PLAIN mechanism,\nand award experience points (XP) to users who are idling in the channel. It maintains user data, including XP and\nlevels, in an SQLite database.\n\n## Features\n\n- **Secure Connection**: Connects to IRC servers using SSL/TLS.\n- **SASL Authentication**: Authenticates securely using the SASL PLAIN mechanism.\n- **Experience System**: Awards XP to users periodically, tracks levels, and announces level-ups in the channel.\n- **Database Integration**: Stores and manages user data in an SQLite database asynchronously.\n- **Automatic User Management**: Automatically adds new users to the database when they join the channel.\n- **Penalties**: Applies penalties for talking, parting, quitting, changing nicks, and being kicked.\n- **Item System**: Characters can find and upgrade items as they level up.\n\n## Usage Notes\n\n- Ensure you have a `config.toml` file in the same directory with the appropriate configuration settings for the bot to\n  function correctly.\n- The bot expects certain fields in the configuration file, such as server details, nickname, username, real name,\n  password, channel to join, and database configuration.\n- Install the required dependencies before running the bot.\n\n### Installing Dependencies\n\n```shell\npip install aiosqlite toml argon2-cffi\n```\n\nor\n\n```shell\nuv sync\n```\n\n### Running the Bot\n\n```shell\npython idlezpgbot.py\n```\n\nor\n\n```shell\nuv run idlezpgbot.py\n```\n\n## Configuration\n\nThe bot is configured using a `config.toml` file. Below is an example configuration with detailed explanations for each\nsection.\n\n### Example `config.toml`\n\n```toml\n[irc]\nserver = \"irc.example.net\"          # IRC server address\nport = 6697                         # IRC server port (usually 6697 for SSL)\nnickname = \"YourBotNick\"            # Bot's nickname\nusername = \"YourBotUser\"            # Bot's username\nrealname = \"Your Bot Real Name\"     # Bot's real name\nnickserv_password = \"YourPassword\"  # Password for SASL authentication\nchannel = \"#yourchannel\"            # IRC channel to join\nquit_message = \"Goodbye!\"           # Message sent upon disconnect\nmax_reconnect_attempts = 10         # Maximum number of reconnect attempts\nreconnect_delay = 10                # Delay between reconnect attempts (in seconds)\nread_timeout = 300                  # Read timeout in seconds\nignored_users = [\"ExampleUser\"]     # Users to ignore for XP awards and penalties\n\n[database]\npath = \"idlezpgbot.db\"              # Path to the SQLite database file\n\n[game]\nxp_interval = 60                    # Time interval in seconds to award XP\nxp_per_interval = 10                # XP awarded per interval\nmax_level = 100                     # Maximum level for characters\nprecompute_base_time = 600          # Base time for initial level-up calculations\nprecompute_exponent = 1.16          # Exponent for level-up time scaling\nadditional_time_per_level = 86400   # Additional time per level after level 60 (in seconds)\nrefresh_interval = 60               # Refresh user list every X seconds\npenalty_multiplier = 1.0            # Multiplier for penalty XP (penalty XP = xp_per_interval * penalty_multiplier)\n\n[logging]\nconsole_log_level = \"INFO\"          # Log level for console output (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n```\n\n### Configuration Sections\n\n#### `[irc]` Section\n\n- **server**: The address of the IRC server you want the bot to connect to.\n- **port**: The port number for the IRC server. Typically, port `6697` is used for SSL/TLS connections.\n- **nickname**: The nickname that the bot will use on the IRC server.\n- **username**: The username for the bot. This is often the same as the nickname.\n- **realname**: The real name of the bot, which is displayed in the IRC client.\n- **nickserv_password**: The password for SASL authentication. Ensure this is kept secure.\n- **channel**: The IRC channel that the bot will join upon connecting.\n- **quit_message**: A custom message sent to the server when the bot disconnects.\n- **max_reconnect_attempts**: The maximum number of times the bot will attempt to reconnect to the server if the\n  connection is lost.\n- **reconnect_delay**: The delay in seconds between reconnect attempts.\n- **read_timeout**: The timeout in seconds for reading data from the server.\n- **ignored_users**: A list of users to ignore for XP awards and penalties.\n\n#### `[database]` Section\n\n- **path**: Specifies the file path for the SQLite database where user data (XP and levels) will be stored. Ensure that\n  the bot has read and write permissions for this path.\n\n#### `[game]` Section\n\n- **xp_interval**: The time interval in seconds at which XP is awarded to users.\n- **xp_per_interval**: The amount of XP awarded per interval.\n- **max_level**: The maximum level that characters can reach.\n- **precompute_base_time**: The base time for initial level-up calculations.\n- **precompute_exponent**: The exponent used for scaling the time required to level up.\n- **additional_time_per_level**: The additional time in seconds required per level after level 60.\n- **refresh_interval**: The interval in seconds at which the user list is refreshed.\n- **penalty_multiplier**: The multiplier applied to the XP penalty for actions such as talking, parting, quitting,\n  changing nicks, and being kicked.\n\n#### `[logging]` Section\n\n- **console_log_level**: The log level for console output. Possible values are `DEBUG`, `INFO`, `WARNING`, `ERROR`, and\n  `CRITICAL`.\n\n### Database Details\n\nIdleZPGBot uses an SQLite database to store user data, allowing it to persist XP and level information across restarts.\nThe database is managed asynchronously using `aiosqlite`, ensuring non-blocking operations.\n\n#### Database Schema\n\nUpon initialization, the bot will create a `characters` table if it doesn't already exist. The schema is as follows:\n\n- **character_name** (`TEXT`, `PRIMARY KEY`): The name of the character.\n- **class_name** (`TEXT`, `NOT NULL`): The class of the character.\n- **password_hash** (`TEXT`, `NOT NULL`): The hashed password for the character.\n- **owner_nick** (`TEXT`, `NOT NULL`): The IRC nickname of the user who owns the character.\n- **xp** (`INTEGER`, `NOT NULL`, `DEFAULT 0`): The accumulated experience points of the character.\n- **level** (`INTEGER`, `NOT NULL`, `DEFAULT 0`): The current level of the character based on their XP.\n- **highest_item_level_awarded** (`INTEGER`, `NOT NULL`, `DEFAULT 0`): The highest level at which an item was awarded.\n\n#### User Management\n\n- **Adding Users**: Users must register a character with the bot to participate. The bot checks if they exist in the\n  database and adds them if not.\n- **Awarding XP**: The bot periodically awards XP to all users currently in the channel. It also checks if users have\n  leveled up and announces it in the channel.\n- **Level Up Announcements**: When a user reaches a new level, the bot announces the achievement and informs them of\n  the time remaining until the next level.\n- **Penalties**: The bot applies penalties for talking, parting, quitting, changing nicks, and being kicked, which can\n  result in XP loss and level-downs.\n- **Item System**: Characters can find and upgrade items as they level up.\n\n### Commands\n\n#### Register Command\n\nUsers must register a character with the bot to participate in the game. The registration command follows this format:\n\n```irc\n/msg \u003cbot\u003e register \u003ccharacter_name\u003e \u003cclass_name\u003e \u003cpassword\u003e\n```\n\n- **character_name**: The name of the character (must be \u003c= 16 letters).\n- **class_name**: The class of the character (must be \u003c= 16 letters).\n- **password**: A password to secure the character.\n\nExample:\n\n```irc\n/msg IdleZPGBot register Gandalf Wizard mysecretpassword\n```\n\n#### Unregister Command\n\nUsers can unregister their character from the bot using the following command:\n\n```irc\n/msg \u003cbot\u003e unregister\n```\n\nThis will remove the character associated with the user's nickname from the database.\n\n#### Help Command\n\nUsers can request a list of available commands by sending the following command:\n\n```irc\n/msg \u003cbot\u003e help\n```\n\nThis will send a private message to the user with a list of commands they can use.\n\n#### Info Command\n\nUsers can request information about the bot, including which operators are online, by sending the following command:\n\n```irc\n/msg \u003cbot\u003e info\n```\n\nThis will send a private message to the user with details about the bot and a list of online operators.\n\n## Logging\n\nIdleZPGBot uses Python's `logging` module to log various events and messages. The logging configuration is set up to\nlog messages to different files and the console.\n\n### Log Files\n\n- **irc.log**: Logs all messages received from the IRC server.\n- **privmsg.log**: Logs all private messages and channel messages sent by the bot.\n- **bot.log**: Logs general bot activities, including connection status, errors, and other significant events.\n\n### Console Logging\n\nThe log level for console output can be configured in the `config.toml` file under the `[logging]` section. The default\nlog level is `INFO`, but it can be set to any of the following levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.\n\n## Important Notes\n\n- **Security**: The bot uses SASL PLAIN authentication over an SSL/TLS connection for secure communication. Ensure that\n  your `nickserv_password` is kept confidential.\n- **Server Compatibility**: Ensure that the IRC server you are connecting to supports SASL authentication and that your\n  credentials are correct.\n- **Database Persistence**: The SQLite database ensures that user data persists even if the bot restarts. Regular\n  backups are recommended to prevent data loss.\n- **Bot Permissions**: The bot must have the necessary permissions to join the specified channel and send messages.\n  Ensure that the bot’s nickname is registered and has the appropriate access rights on the IRC server.\n\n## Troubleshooting\n\n- **Connection Issues**: Verify that the IRC server address and port are correct and that there are no network issues\n  preventing the bot from connecting.\n- **Authentication Failures**: Ensure that the `nickserv_password` is correct and that the IRC server supports SASL\n  PLAIN authentication.\n- **Database Errors**: Check that the specified database path is correct and that the bot has the necessary permissions\n  to read/write to the file.\n- **Unexpected Behavior**: Review the console logs printed by the bot for any error messages or warnings that can help\n  identify the issue.\n\n## Contributing\n\nContributions are welcome! Please fork the repository and submit a pull request with your enhancements or bug fixes.\n\n## License\n\nThis project is licensed under the `GPL-3.0-or-later` license. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxtsd%2Fidlezpgbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftxtsd%2Fidlezpgbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxtsd%2Fidlezpgbot/lists"}