Merge pull request 'Version 1.1' (#55) from dev into master

Reviewed-on: waifu/kemoverse#55

.gitignore

@@ -185,3 +185,5 @@ cython_debug/
 gacha_game*.db
 gacha_game*.db.*
 config*.ini
+
+.idea

bot/add_card.py

@@ -1,28 +1,27 @@
 import requests
 from misskey.exceptions import MisskeyAPIException
 from client import client_connection
-from db_utils import insert_character
+from db_utils import insert_card
-from custom_types import Character
+from custom_types import Card
+from config import RARITY_TO_WEIGHT
 
 
-def add_character(
+def add_card(
         name: str,
         rarity: int,
-        weight: float,
         image_url: str) -> tuple[int, str]:
     '''
-    Adds a character to the database, uploading the image from a public URL to
+    Adds a card to the database, uploading the image from a public URL to
     the bot's Misskey Drive.
 
     Args:
-        name (str): Character name.
+        name (str): Card name.
-        rarity (int): Character rarity (e.g., 1-5).
+        rarity (int): Card rarity (e.g., 1-5).
-        weight (float): Pull weight (e.g., 0.02).
         image_url (str): Public URL of the image from the post (e.g., from
             note['files'][i]['url']).
 
     Returns:
-        tuple[int, str]: Character ID and bot's Drive file_id.
+        tuple[int, str]: Card ID and bot's Drive file_id.
 
     Raises:
         ValueError: If inputs are invalid.
@@ -33,11 +32,11 @@ def add_character(
 
     # Validate inputs
     if not stripped_name:
-        raise ValueError('Character name cannot be empty.')
+        raise ValueError('Card name cannot be empty.')
     if rarity < 1:
         raise ValueError('Rarity must be a positive integer.')
-    if weight <= 0:
+    if rarity not in RARITY_TO_WEIGHT.keys():
-        raise ValueError('Weight must be a positive number.')
+        raise ValueError(f'Invalid rarity: {rarity}')
     if not image_url:
         raise ValueError('Image URL must be provided.')
 
@@ -56,10 +55,10 @@ def add_character(
                 from e
 
     # Insert into database
-    character_id = insert_character(
+    card_id = insert_card(
             stripped_name,
             rarity,
-            float(weight),
+            RARITY_TO_WEIGHT[rarity],
             file_id
     )
-    return character_id, file_id
+    return card_id, file_id

bot/bot_app.py

@@ -12,6 +12,9 @@ if __name__ == '__main__':
     # Connect to DB
     db.connect()
 
+    # Setup default administrators
+    db.setup_administrators()
+
     print('Listening for notifications...')
     while True:
         if not process_notifications(client):

bot/config.py

@@ -1,5 +1,6 @@
 '''Essentials for the bot to function'''
 import configparser
+import json
 from os import environ, path
 
 
@@ -22,6 +23,17 @@ def get_config_file() -> str:
     return config_path
 
 
+def get_rarity_to_weight(
+        config_section: configparser.SectionProxy) -> dict[int, float]:
+    """Parses Rarity_X keys from config and returns a {rarity: weight} dict."""
+    rarity_weights = {}
+    for key, value in config_section.items():
+        if key.startswith("rarity_"):
+            rarity = int(key.removeprefix("rarity_"))
+            rarity_weights[rarity] = float(value)
+    return rarity_weights
+
+
 config = configparser.ConfigParser()
 config.read(get_config_file())
 
@@ -32,14 +44,17 @@ KEY = config['credentials']['Token']
 # Bot's Misskey instance URL
 INSTANCE = config['credentials']['Instance'].lower()
 
-# TODO: move this to db
 # Fedi handles in the traditional 'user@domain.tld' style, allows these users
 # to use extra admin exclusive commands with the bot
-ADMINS = config['application']['DefaultAdmins']
+ADMINS = json.loads(config['application']['DefaultAdmins'])
 # SQLite Database location
 DB_PATH = config['application']['DatabaseLocation']
+# Whether to enable the instance whitelist
+USE_WHITELIST = config['application']['UseWhitelist']
 
 NOTIFICATION_POLL_INTERVAL = int(config['notification']['PollInterval'])
 NOTIFICATION_BATCH_SIZE = int(config['notification']['BatchSize'])
 
 GACHA_ROLL_INTERVAL = int(config['gacha']['RollInterval'])
+
+RARITY_TO_WEIGHT = get_rarity_to_weight(config['gacha'])

bot/custom_types.py

@@ -5,7 +5,7 @@ BotResponse = TypedDict('BotResponse', {
     'attachment_urls': List[str] | None
 })
 
-Character = TypedDict('Character', {
+Card = TypedDict('Card', {
     'id': int,
     'name': str,
     'rarity': int,

bot/db_utils.py

@@ -1,7 +1,7 @@
 from random import choices
 import sqlite3
 import config
-from custom_types import Character
+from custom_types import Card
 
 DB_PATH = config.DB_PATH
 CONNECTION: sqlite3.Connection
@@ -18,73 +18,197 @@ def connect() -> None:
     CURSOR = CONNECTION.cursor()
 
 
-def get_random_character() -> Character | None:
+def setup_administrators() -> None:
-    ''' Gets a random character from the database'''
+    '''Creates administrator players for each handle in the config file'''
-    CURSOR.execute('SELECT * FROM characters')
+    # Get default admins from config
-    characters = CURSOR.fetchall()
+    for username in config.ADMINS:
+        player_id = get_player(username)
+        if player_id == 0:
+            # Create player if not exists
+            print(f'Creating administrator player: {username}')
+            CURSOR.execute(
+                'INSERT INTO players (username, has_rolled, is_administrator) \
+                    VALUES (?, ?, ?)',
+                (username, False, True)
+            )
+        else:
+            # Update is_administrator if exists
+            print(f'Granting administrator to player: {username}')
+            CURSOR.execute(
+                'UPDATE players SET is_administrator = 1 WHERE id = ?',
+                (player_id,)
+            )
 
-    if not characters:
+
+def get_random_card() -> Card | None:
+    ''' Gets a random card from the database'''
+    CURSOR.execute('SELECT * FROM cards')
+    cards = CURSOR.fetchall()
+
+    if not cards:
         return None
 
-    weights = [c['weight'] for c in characters]
+    weights = [config.RARITY_TO_WEIGHT[c['rarity']] for c in cards]
-    chosen = choices(characters, weights=weights, k=1)[0]
+    chosen = choices(cards, weights=weights, k=1)[0]
 
     return {
         'id': chosen['id'],
         'name': chosen['name'],
         'rarity': chosen['rarity'],
-        'weight': chosen['weight'],
+        'weight': config.RARITY_TO_WEIGHT[chosen['rarity']],
         'image_url': chosen['file_id']
     }
 
 
-def get_or_create_user(username: str) -> int:
+def get_player(username: str) -> int:
-    '''Retrieves an ID for a given user, if the user does not exist, it will be
+    '''Retrieve a player ID by username, or return None if not found.'''
-    created.'''
-    CURSOR.execute('SELECT id FROM users WHERE username = ?', (username,))
-    user = CURSOR.fetchone()
-    if user:
-        return int(user[0])
-
-    # New user starts with has_rolled = False
     CURSOR.execute(
-        'INSERT INTO users (username, has_rolled) VALUES (?, ?)',
+        'SELECT id FROM players WHERE username = ?',
+        (username,)
+    )
+    player = CURSOR.fetchone()
+    if player:
+        return int(player[0])
+    return 0
+
+
+def insert_player(username: str) -> int:
+    '''Insert a new player with default has_rolled = False and return their
+    player ID.'''
+    CURSOR.execute(
+        'INSERT INTO players (username, has_rolled) VALUES (?, ?)',
         (username, False)
     )
-    user_id = CURSOR.lastrowid
+    return CURSOR.lastrowid if CURSOR.lastrowid else 0
-    return user_id if user_id else 0
 
 
-def insert_character(
+def delete_player(username: str) -> bool:
-        name: str, rarity: int, weight: float, file_id: str) -> int:
+    '''Permanently deletes a player and all their pulls.'''
-    '''Inserts a character'''
     CURSOR.execute(
-        'INSERT INTO characters (name, rarity, weight, file_id) VALUES \
+        'SELECT id FROM players WHERE username = ?',
+        (username,)
+    )
+    player = CURSOR.fetchone()
+
+    if not player:
+        return False
+
+    player_id = player[0]
+
+    # Delete pulls
+    CURSOR.execute(
+        'DELETE FROM pulls WHERE player_id = ?',
+        (player_id,)
+    )
+
+    # Delete player
+    CURSOR.execute(
+        'DELETE FROM players WHERE id = ?',
+        (player_id,)
+    )
+
+    return True
+
+
+def ban_player(username: str) -> bool:
+    '''Adds a player to the ban list.'''
+    try:
+        CURSOR.execute(
+            'INSERT INTO banned_players (handle) VALUES (?)',
+            (username,)
+        )
+        return True
+    except sqlite3.IntegrityError:
+        return False
+
+
+def unban_player(username: str) -> bool:
+    '''Removes a player from the ban list.'''
+    CURSOR.execute(
+        'DELETE FROM banned_players WHERE handle = ?',
+        (username,)
+    )
+    return CURSOR.rowcount > 0
+
+
+def is_player_banned(username: str) -> bool:
+    CURSOR.execute(
+        'SELECT * FROM banned_players WHERE handle = ?',
+        (username,)
+    )
+    row = CURSOR.fetchone()
+    return row is not None
+
+
+def is_player_administrator(username: str) -> bool:
+    CURSOR.execute(
+        'SELECT is_administrator FROM players WHERE username = ? LIMIT 1',
+        (username,)
+    )
+    row = CURSOR.fetchone()
+    return row[0] if row else False
+
+
+def insert_card(
+        name: str, rarity: int, weight: float, file_id: str) -> int:
+    '''Inserts a card'''
+    CURSOR.execute(
+        'INSERT INTO cards (name, rarity, weight, file_id) VALUES \
 (?, ?, ?, ?)',
         (name, rarity, weight, file_id)
     )
-    character_id = CURSOR.lastrowid
+    card_id = CURSOR.lastrowid
-    return character_id if character_id else 0
+    return card_id if card_id else 0
 
 
-def insert_pull(user_id: int, character_id: int) -> None:
+def insert_pull(player_id: int, card_id: int) -> None:
     '''Creates a pull in the database'''
     CURSOR.execute(
-        'INSERT INTO pulls (user_id, character_id) VALUES (?, ?)',
+        'INSERT INTO pulls (player_id, card_id) VALUES (?, ?)',
-        (user_id, character_id)
+        (player_id, card_id)
     )
 
 
-def get_last_rolled_at(user_id: int) -> int:
+def get_last_rolled_at(player_id: int) -> int:
-    '''Gets the timestamp when the user last rolled'''
+    '''Gets the timestamp when the player last rolled'''
     CURSOR.execute(
-        "SELECT timestamp FROM pulls WHERE user_id = ? ORDER BY timestamp \
+        "SELECT timestamp FROM pulls WHERE player_id = ? ORDER BY timestamp \
 DESC",
-        (user_id,))
+        (player_id,))
     row = CURSOR.fetchone()
     return row[0] if row else 0
 
 
+def add_to_whitelist(instance: str) -> bool:
+    '''Adds an instance to the whitelist, returns false if instance was already
+    present'''
+    try:
+        CURSOR.execute(
+            'INSERT INTO instance_whitelist (tld) VALUES (?)', (instance,)
+        )
+        return True
+    except sqlite3.IntegrityError:
+        return False
+
+
+def remove_from_whitelist(instance: str) -> bool:
+    '''Removes an instance to the whitelist, returns false if instance was not
+    present'''
+    CURSOR.execute(
+        'DELETE FROM instance_whitelist WHERE tld = ?', (instance,))
+    return CURSOR.rowcount > 0
+
+
+def is_whitelisted(instance: str) -> bool:
+    '''Checks whether an instance is in the whitelist'''
+    if instance == 'local':
+        return True
+    CURSOR.execute(
+        'SELECT * FROM instance_whitelist WHERE tld = ?', (instance,))
+    row = CURSOR.fetchone()
+    return row is not None
+
+
 def get_config(key: str) -> str:
     '''Reads the value for a specified config key from the db'''
     CURSOR.execute("SELECT value FROM config WHERE key = ?", (key,))

bot/notification.py

@@ -4,9 +4,9 @@ from typing import Dict, Any
 import misskey
 from misskey.exceptions import MisskeyAPIException
 
-from config import NOTIFICATION_BATCH_SIZE
+from config import NOTIFICATION_BATCH_SIZE, USE_WHITELIST
 from parsing import parse_notification
-from db_utils import get_config, set_config
+from db_utils import get_config, set_config, is_whitelisted, is_player_banned
 from response import generate_response
 from custom_types import BotResponse
 
@@ -24,7 +24,7 @@ def process_notification(
     host = user.get('host')  # None if local user
     instance = host if host else 'local'
 
-    if not (instance in WHITELISTED_INSTANCES or instance == 'local'):
+    if USE_WHITELIST and not is_whitelisted(instance):
         print(f'⚠️ Blocked notification from untrusted instance: {instance}')
         return
 
@@ -44,6 +44,11 @@ def process_notification(
     if not parsed_notification:
         return
 
+    author = parsed_notification['author']
+    if is_player_banned(author):
+        print(f'⚠️ Blocked notification from banned player: {author}')
+        return
+
     # Get the note Id to reply to
     note_id = notification.get('note', {}).get('id')
 

bot/parsing.py

@@ -24,6 +24,8 @@ def parse_notification(
     note_id = note_obj.get("id")
 
     note = note_text.strip().lower() if note_text else ""
+    # Split words into tokens
+    parts = note.split()
 
     # Check for both short and fully-qualified name mentions
     username_variants = [
@@ -31,18 +33,16 @@ def parse_notification(
         f'@{config.USER.split("@")[1]}'
     ]
 
-    # Make sure the notification text explicitly mentions the bot
+    # Notifs must consist of the initial mention and at least one other token
-    if not any(variant in note for variant in username_variants):
+    if len(parts) <= 1:
         return None
 
-    # Find command and arguments after the mention
+    # Make sure the first token is a mention to the bot
-    # Removes all mentions
+    if not parts[0] in username_variants:
-    # regex = mentions that start with @ and may contain @domain
+        return None
-    cleaned_text = re.sub(r"@\w+(?:@\S+)?", "", note).strip()
-    parts = cleaned_text.split()
 
-    command = parts[0].lower() if parts else None
+    command = parts[1].lower()
-    arguments = parts[1:] if len(parts) > 1 else []
+    arguments = parts[2:] if len(parts) > 2 else []
 
     return {
         'author': full_user,

bot/response.py

@@ -1,18 +1,22 @@
 from datetime import datetime, timedelta, timezone
 from typing import TypedDict, Any, List, Dict
-from db_utils import get_or_create_user, insert_pull, get_last_rolled_at, \
+import db_utils as db
-        get_random_character
+from add_card import add_card
-from add_character import add_character
 from config import GACHA_ROLL_INTERVAL
 from custom_types import BotResponse, ParsedNotification
 
 
-def do_roll(full_user: str) -> BotResponse:
+def do_roll(author: str) -> BotResponse:
-    '''Determines whether the user can roll, then pulls a random character'''
+    '''Determines whether the user can roll, then pulls a random card'''
-    user_id = get_or_create_user(full_user)
+    user_id = db.get_player(author)
-
+    if not user_id:
+        return {
+            'message': f'{author} 🛑 You haven’t signed up yet! Use the \
+`signup` command to start playing.',
+            'attachment_urls': None
+        }
     # Get date of user's last roll
-    date = get_last_rolled_at(user_id)
+    date = db.get_last_rolled_at(user_id)
 
     # No date means it's users first roll
     if date:
@@ -36,26 +40,45 @@ def do_roll(full_user: str) -> BotResponse:
                 remaining_duration = f'{duration.seconds} seconds'
 
             return {
-                'message': f'{full_user} ⏱️ Please wait another \
+                'message': f'{author} ⏱️ Please wait another \
 {remaining_duration} before rolling again.',
                 'attachment_urls': None
             }
 
-    character = get_random_character()
+    card = db.get_random_card()
 
-    if not character:
+    if not card:
         return {
-            'message': f'{full_user} Uwaaa... something went wrong! No \
+            'message': f'{author} Uwaaa... something went wrong! No \
-characters found. 😿',
+cards found. 😿',
             'attachment_urls': None
         }
 
-    insert_pull(user_id, character['id'])
+    db.insert_pull(user_id, card['id'])
-    stars = '⭐️' * character['rarity']
+    stars = '⭐️' * card['rarity']
     return {
-        'message': f'@{full_user} 🎲 Congrats! You rolled {stars} \
+        'message': f'{author} 🎲 Congrats! You rolled {stars} \
-**{character['name']}**\nShe\'s all yours now~ 💖✨',
+**{card['name']}**\nShe\'s all yours now~ 💖✨',
-        'attachment_urls': [character['image_url']]
+        'attachment_urls': [card['image_url']]
+    }
+
+
+def do_signup(author: str) -> BotResponse:
+    '''Registers a new user if they haven’t signed up yet.'''
+    user_id = db.get_player(author)
+
+    if user_id:
+        return {
+            'message': f'{author} 👀 You’re already signed up! Let the rolling \
+begin~ 🎲',
+            'attachment_urls': None
+        }
+
+    new_user_id = db.insert_player(author)
+    return {
+            'message': f'{author} ✅ Signed up successfully! Your gacha \
+destiny begins now... ✨ Use the roll command to start!',
+            'attachment_urls': None
         }
 
 
@@ -69,49 +92,48 @@ def is_float(val: Any) -> bool:
 
 
 def do_create(
-        full_user: str,
+        author: str,
         arguments: List[str],
         note_obj: Dict[str, Any]) -> BotResponse:
-    '''Creates a character'''
+    '''Creates a card'''
     # Example call from bot logic
     image_url = note_obj.get('files', [{}])[0].get('url') \
         if note_obj.get('files') else None
 
     if not image_url:
         return {
-            'message': f'{full_user} You need an image to create a character, \
+            'message': f'{author} You need an image to create a card, \
 dumbass.',
             'attachment_urls': None
         }
 
-    if len(arguments) != 3:
+    if len(arguments) != 2:
         return {
-            'message': f'{full_user} Please specify the following attributes \
+            'message': f'{author} Please specify the following attributes \
-in order: name, rarity, drop weighting',
+in order: name, rarity',
             'attachment_urls': None
         }
 
     if not (arguments[1].isnumeric() and 1 <= int(arguments[1]) <= 5):
         return {
-            'message': f'{full_user} Invalid rarity: \'{arguments[1]}\' must \
+            'message': f'{author} Invalid rarity: \'{arguments[1]}\' must \
 be a number between 1 and 5',
             'attachment_urls': None
         }
     if not (is_float(arguments[2]) and 0.0 < float(arguments[2]) <= 1.0):
         return {
-            'message': f'{full_user} Invalid drop weight: \'{arguments[2]}\' \
+            'message': f'{author} Invalid drop weight: \'{arguments[2]}\' \
 must be a decimal value between 0.0 and 1.0',
             'attachment_urls': None
         }
 
-    character_id, file_id = add_character(
+    card_id, file_id = add_card(
         name=arguments[0],
         rarity=int(arguments[1]),
-        weight=float(arguments[2]),
         image_url=image_url
     )
     return {
-        'message': f'{full_user} Added {arguments[0]}, ID {character_id}.',
+        'message': f'{author} Added {arguments[0]}, ID {card_id}.',
         'attachment_urls': [file_id]
     }
 
@@ -120,16 +142,117 @@ def do_help(author: str) -> BotResponse:
     '''Provides a list of commands that the bot can do.'''
     return {
         'message': f'{author} Here\'s what I can do:\n\
-- `roll` Pulls a random character.\n\
+- `roll` Pulls a random card.\n\
-- `create <name> <rarity> <weight>` Creates a character using a given image.\n\
+- `create <name> <rarity>` Creates a card using a given image.\n\
-- `help` Shows this message.',
+- `signup` Registers your account.\n\
+- `delete_account` Deletes your account.\n\
+- `help` Shows this message',
         'attachment_urls': None
     }
 
 
-def do_signup() -> BotResponse:
+def delete_account(author: str) -> BotResponse:
     return {
-        'message': '',
+        'message': f'{author} ⚠️ This will permanently delete your account \
+and all your cards.\n'
+        'If you\'re sure, reply with `confirm_delete_account` to proceed.\n\n'
+        '**There is no undo.** Your gacha luck will be lost to the void... 💀✨',
+        'attachment_urls': None
+
+    }
+
+
+def confirm_delete(author: str) -> BotResponse:
+    db.delete_player(author)
+
+    return {
+        'message': f'{author} 🧼 Your account and all your cards have been \
+deleted. RIP your gacha history 🕊️✨',
+        'attachment_urls': None
+    }
+
+
+def do_whitelist(author: str, args: list[str]) -> BotResponse:
+    if len(args) == 0:
+        return {
+            'message': f'{author} Please specify an instance to whitelist',
+            'attachment_urls': None
+        }
+
+    if db.add_to_whitelist(args[0]):
+        return {
+            'message': f'{author} Whitelisted instance: {args[0]}',
+            'attachment_urls': None
+        }
+    else:
+        return {
+            'message': f'{author} Instance already whitelisted: {args[0]}',
+            'attachment_urls': None
+        }
+
+
+def do_unwhitelist(author: str, args: list[str]) -> BotResponse:
+    if len(args) == 0:
+        return {
+            'message': f'{author} Please specify an instance to remove from \
+the whitelist',
+            'attachment_urls': None
+        }
+
+    if db.remove_from_whitelist(args[0]):
+        return {
+            'message': f'{author} Unwhitelisted instance: {args[0]}',
+            'attachment_urls': None
+        }
+    else:
+        return {
+            'message': f'{author} Instance not whitelisted: {args[0]}',
+            'attachment_urls': None
+        }
+
+
+def do_ban(author: str, args: list[str]) -> BotResponse:
+    if len(args) == 0:
+        return {
+            'message': f'{author} Please specify a user to ban',
+            'attachment_urls': None
+        }
+
+    if db.is_player_administrator(args[0]):
+        return {
+            'message': f'{author} Cannot ban other administrators.',
+            'attachment_urls': None
+        }
+
+    if db.ban_player(args[0]):
+        # Delete banned player's account
+        db.delete_player(args[0])
+        return {
+            'message': f'{author} 🔨 **BONK!** Get banned, {args[0]}!',
+            'attachment_urls': None
+        }
+    else:
+        return {
+            'message': f'{author} Player is already banned: {args[0]}',
+            'attachment_urls': None
+        }
+
+
+def do_unban(author: str, args: list[str]) -> BotResponse:
+    if len(args) == 0:
+        return {
+            'message': f'{author} Please specify a user to unban',
+            'attachment_urls': None
+        }
+
+    if db.unban_player(args[0]):
+        return {
+            'message': f'{author} Player unbanned: {args[0]}!',
+            'attachment_urls': None
+        }
+    else:
+        return {
+            'message': f'{author} Player was not banned: {args[0]}',
             'attachment_urls': None
         }
 
@@ -140,40 +263,56 @@ def generate_response(notification: ParsedNotification) -> BotResponse | None:
 
     # Temporary response variable
     res: BotResponse | None = None
-    # TODO: Check if the user has an account
     author = notification['author']
-    user_id = get_or_create_user(author)
+    player_id = db.get_player(author)
     command = notification['command']
-    # Check if the user is an administrator
-    # user_is_administrator = user_is_administrator()
 
     # Unrestricted commands
     match command:
+        case 'roll':
+            res = do_roll(author)
         case 'signup':
-            res = do_signup()
+            res = do_signup(author)
         case 'help':
             res = do_help(author)
         case _:
             pass
 
-    if not user_id:
+    # Commands beyond this point require the user to have an account
+    if not player_id:
         return res
 
     # User commands
     match command:
-        case 'delete_account':
-            pass
-        case 'roll':
-            res = do_roll(author)
         case 'create':
             res = do_create(
                 author,
                 notification['arguments'],
                 notification['note_obj']
             )
+        case 'delete_account':
+            res = delete_account(author)
+        case 'confirm_delete_account':
+            res = confirm_delete(author)
         case _:
             pass
-    # if not user_is_administrator:
+
+    # Commands beyond this point require the user to be an administrator
+    if not db.is_player_administrator(author):
         return res
 
+    # Admin commands
+    match command:
+        case 'whitelist':
+            res = do_whitelist(author, notification['arguments'])
+        case 'unwhitelist':
+            res = do_unwhitelist(author, notification['arguments'])
+        case 'ban':
+            res = do_ban(author, notification['arguments'])
+        case 'unban':
+            res = do_unban(author, notification['arguments'])
+        case _:
+            pass
+
     # Administrator commands go here
+    return res

docs/index.md

@@ -0,0 +1,24 @@
+# 🎲 Kemoverse Documentation
+
+Welcome to the developer documentation for **Kemoverse**, a gacha trading card game in the Fediverse!
+
+Features collectible cards, rarity-based pulls, and integration with Misskey.
+
+Name comes from Kemonomimi and Fediverse.
+
+---
+
+## 📁 Table of Contents
+
+- [Installation](./install.md)
+- [Game Design](./design.md)
+- [Bot Architecture](./bot.md)
+- [Database Structure](./database.md)
+- [Card System](./cards.md)
+- [Web UI](./web.md)
+- [Theming and Assets](./theme.md)
+- [Contributing](./contributing.md)
+- [FAQ](./faq.md)
+
+---
+

docs/install.md

@@ -0,0 +1,83 @@
+
+## 🧪 Installation
+
+### Download and install dependencies
+
+Clone the repo
+
+```sh
+git clone https://git.waifuism.life/waifu/kemoverse.git
+cd kemoverse
+```
+
+Setup a virtual environment (Optional, recommended)
+
+```sh
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install project dependencies via pip
+
+```sh
+python3 -m pip install -r requirements.txt
+```
+
+### Setup config file
+
+A sample config file is included with the project as a template: `example_config.ini`
+
+Create a copy of this file and replace its' values with your own. Consult the
+template for more information about individual config values and their meaning.
+
+Config files are environment-specific. Use `config_dev.ini` for development and
+`config_prod.ini` for production. Switch between environments using the
+`KEMOVERSE_ENV` environment variable.
+
+```sh
+cp example_config.ini config_dev.ini
+# Edit config_dev.ini
+```
+
+### Setup database
+
+To set up the database, run:
+
+```sh
+KEMOVERSE_ENV=dev python3 setup_db.py
+```
+
+### Run the bot
+
+```sh
+KEMOVERSE_ENV=dev ./startup.sh
+```
+
+If all goes well, you should now be able to interact with the bot.
+
+### Running in production
+
+To run the the in a production environment, use `KEMOVERSE_ENV=prod`. You will
+also need to create a `config_prod.ini` file and run the database setup step
+again if pointing prod to a different database. (you are pointing dev and prod
+to different databases, right? 🤨)
+
+### Updating
+
+To update the bot, first pull new changes from upstream:
+
+```sh
+git pull
+```
+
+Then run any database migrations. We recommend testing in dev beforehand to
+make sure nothing breaks in the update process.
+
+**Always backup your prod database before running any migrations!**
+
+```sh
+# Backup database file
+cp gacha_game_dev.db gacha_game_dev.db.bak
+# Run migrations
+KEMOVERSE_ENV=dev python3 setup_db.py
+```

docs/theme.md

@@ -0,0 +1,33 @@
+Welcome to the **Visual Identity** guide for the Kemoverse. This page contains the standard colors, logos, and graphic elements used across the game (cards, UI, web presence, bots, etc). Please follow these guidelines to ensure consistency.
+
+---
+
+## 🟢 Primary Color Palette
+
+| Color Name     | Hex Code   | Usage                                |
+|----------------|------------|--------------------------------------|
+| Green  | `#5aa02c`  | Main buttons, links, headers         |
+| Midnight Black | `#1A1A1A`  | Backgrounds, dark mode               |
+| Misty White    | `#FAFAFA`  | Default backgrounds, light text bg  |
+| Soft Gray      | `#CCCCCC`  | Borders, placeholders, separators   |
+| Highlight Green | `#8dd35f`  | Alerts, emphasis, icons        |
+| Rarity Gold    | `#FFD700`  | Special rare cards, SSR outlines    |
+| Rarity Silver  | `#C0C0C0`  | Rare card text, stat glow effects   |
+
+> ✅ Use `Green` and `Misty White` for the standard UI. Avoid mixing in extra palettes unless explicitly needed.
+
+---
+
+## 🖼 Logos
+
+### Main Logo
+
+<p align="center">
+  <img src="../web/static/logo.png" alt="Fediverse Gacha Bot Logo" width="300" height="auto">
+</p>
+
+- File: `web/static/logo.png`
+- Usage: Website header, favicon, bot avatar, watermark
+
+
+---

example_config.ini

@@ -2,13 +2,24 @@
 [application]
 ; Comma separated list of fedi handles for any administrator users
 ; More can be added through the application
-DefaultAdmins    = ['admin@example.tld']
+DefaultAdmins    = ["@localadmin", "@remoteadmin@example.tld"]
 ; SQLite Database location
 DatabaseLocation = ./gacha_game.db
+; Whether to lmit access to the bot via an instance whitelist
+; The whitelist can be adjusted via the application
+UseWhitelist     = False
 
 [gacha]
 ; Number of seconds players have to wait between rolls
 RollInterval = 72000
+; Rarity drop weights (1 to 5 stars)
+; Format: rarity=weight per line
+; In order: common, uncommon, rare, epic and legendary (Example values below)
+Rarity_1 = 0.7   
+Rarity_2 = 0.2
+Rarity_3 = 0.08
+Rarity_4 = 0.015
+Rarity_5 = 0.005 
 
 [notification]
 ; Number of seconds to sleep while awaiting new notifications

migrations/0002_weigh_infer.sql

@@ -0,0 +1 @@
+ALTER TABLE characters DROP COLUMN weight;

migrations/0003_rename_tables.sql

@@ -0,0 +1,4 @@
+ALTER TABLE users RENAME TO players;
+ALTER TABLE characters RENAME TO cards;
+ALTER TABLE pulls RENAME user_id TO player_id;
+ALTER TABLE pulls RENAME character_id TO card_id;

migrations/0004_add_administrators.sql

@@ -0,0 +1 @@
+ALTER TABLE players ADD COLUMN is_administrator BOOLEAN NOT NULL DEFAULT 0;

migrations/0005_add_whitelist.sql

@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS instance_whitelist (
+    tld TEXT UNIQUE PRIMARY KEY
+);
+
+CREATE TABLE IF NOT EXISTS banned_players (
+    handle TEXT UNIQUE PRIMARY KEY
+);

readme.md

@@ -1,12 +1,15 @@
 # Kemoverse
 
 A gacha-style bot for the Fediverse built with Python. Users can roll for characters, trade, duel, and perhaps engage with popularity-based mechanics. Currently designed for use with Misskey. Name comes from Kemonomimi and Fediverse.
+<p align="center">
+  <img src="./web/static/logo.png" alt="Fediverse Gacha Bot Logo" width="300" height="auto">
+</p>
 
-## Installation
+## 📝 Docs
 
-## Roadmap
+👉 [**Start reading the docs**](./docs/index.md)
 
-![Fediverse Gacha Bot Logo](./web/static/logo.png)
+🤌 [**Install instructions for those in a rush**](docs/install.md)
 
 ## 🔧 Features
 
@@ -15,10 +18,11 @@ A gacha-style bot for the Fediverse built with Python. Users can roll for charac
 - 🧠 Core database structure for cards
 - 📦 Basic support for storing pulls per player
 - ⏱️ Time-based limitations on rolls
+- ⚠️  Explicit account creation/deletion
 
 ### 🧩 In Progress
 - 📝 Whitelist system to limit access
-- ⚠️  Explicit account creation/deletion
+
 
 ## 🧠 Roadmap
 
@@ -57,89 +61,6 @@ A gacha-style bot for the Fediverse built with Python. Users can roll for charac
 
 The bot is meant to feel *light, fun, and competitive*. Mixing social, gacha and duel tactics.
 
-## 🧪 Installation
-
-### Download and install dependencies
-
-Clone the repo
-
-```sh
-git clone https://git.waifuism.life/waifu/kemoverse.git
-cd kemoverse
-```
-
-Setup a virtual environment (Optional, recommended)
-
-```sh
-python3 -m venv venv
-source venv/bin/activate
-```
-
-Install project dependencies via pip
-
-```sh
-python3 -m pip install -r requirements.txt
-```
-
-### Setup config file
-
-A sample config file is included with the project as a template: `example_config.ini`
-
-Create a copy of this file and replace its' values with your own. Consult the
-template for more information about individual config values and their meaning.
-
-Config files are environment-specific. Use `config_dev.ini` for development and
-`config_prod.ini` for production. Switch between environments using the
-`KEMOVERSE_ENV` environment variable.
-
-```sh
-cp example_config.ini config_dev.ini
-# Edit config_dev.ini
-```
-
-### Setup database
-
-To set up the database, run:
-
-```sh
-KEMOVERSE_ENV=dev python3 setup_db.py
-```
-
-### Run the bot
-
-```sh
-KEMOVERSE_ENV=dev ./startup.sh
-```
-
-If all goes well, you should now be able to interact with the bot.
-
-### Running in production
-
-To run the the in a production environment, use `KEMOVERSE_ENV=prod`. You will
-also need to create a `config_prod.ini` file and run the database setup step
-again if pointing prod to a different database. (you are pointing dev and prod
-to different databases, right? 🤨)
-
-### Updating
-
-To update the bot, first pull new changes from upstream:
-
-```sh
-git pull
-```
-
-Then run any database migrations. We recommend testing in dev beforehand to
-make sure nothing breaks in the update process.
-
-**Always backup your prod database before running any migrations!**
-
-```sh
-# Backup database file
-cp gacha_game_dev.db gacha_game_dev.db.bak
-# Run migrations
-KEMOVERSE_ENV=dev python3 setup_db.py
-```
-
 ```mermaid
 flowchart TD
 

web/app.py

@@ -1,6 +1,8 @@
-from flask import Flask, render_template
 import sqlite3
 
+from flask import Flask, render_template, abort
+from werkzeug.exceptions import HTTPException
+
 app = Flask(__name__)
 DB_PATH = "./gacha_game.db"  # Adjust path if needed
 
@@ -9,6 +11,14 @@ def get_db_connection():
     conn.row_factory = sqlite3.Row
     return conn
 
+@app.errorhandler(HTTPException)
+def handle_exception(error):
+    return render_template("_error.html", error=error), error.code
+
+@app.route("/i404")
+def i404():
+    return abort(404)
+
 @app.route('/')
 def index():
     conn = get_db_connection()
@@ -33,6 +43,8 @@ def user_profile(user_id):
 
     cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))
     user = cursor.fetchone()
+    if user is None:
+        abort(404)
 
     cursor.execute('''
         SELECT pulls.timestamp, characters.name as character_name, characters.rarity

web/static/style.css

@@ -0,0 +1,92 @@
+body {
+            font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
+            background-color: #f4f6fa;
+            color: #333;
+            margin: 0;
+            padding: 0;
+        }
+
+        header {
+            background-color: #7289da;
+            color: white;
+            padding: 20px;
+            text-align: center;
+        }
+
+        header h1 {
+            margin: 0;
+            font-size: 2.5em;
+        }
+
+        header p {
+            margin-top: 5px;
+            font-size: 1.1em;
+        }
+
+        .container {
+            max-width: 800px;
+            margin: 30px auto;
+            padding: 20px;
+            background-color: #ffffff;
+            border-radius: 10px;
+            box-shadow: 0 3px 10px rgba(0, 0, 0, 0.07);
+        }
+
+        h2 {
+            border-bottom: 1px solid #ccc;
+            padding-bottom: 8px;
+            margin-top: 30px;
+        }
+
+        ul {
+            list-style-type: none;
+            padding-left: 0;
+        }
+
+        li {
+            margin: 10px 0;
+        }
+
+        a {
+            text-decoration: none;
+            color: #2c3e50;
+            font-weight: bold;
+            background-color: #e3eaf3;
+            padding: 8px 12px;
+            border-radius: 6px;
+            display: inline-block;
+            transition: background-color 0.2s;
+        }
+
+        a:hover {
+            background-color: #cdd8e6;
+        }
+
+        .leaderboard-entry {
+            margin-bottom: 8px;
+            padding: 6px 10px;
+            background: #f9fafc;
+            border-left: 4px solid #7289da;
+            border-radius: 5px;
+        }
+
+        footer {
+            text-align: center;
+            margin-top: 40px;
+            font-size: 0.9em;
+            color: #888;
+        }
+
+        .note {
+            background: #fcfcf0;
+            border: 1px dashed #bbb;
+            padding: 10px;
+            border-radius: 8px;
+            margin-top: 30px;
+            font-size: 0.95em;
+            color: #666;
+        }
+
+        .footer-link {
+            margin: 0 10px;
+        }

web/templates/_base.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='style.css') }}">
+    <link rel="shortcut icon" href="{{ url_for('static', filename='logo.png') }}">
+    <title>
+    {% if title %}
+        {{ title }}
+    {% else %}
+        {% block title %}{% endblock %}
+    {% endif %}
+        &nbsp;|&nbsp;Kemoverse
+    </title>
+</head>
+<body>
+    <header>
+        {% block header %}{% endblock %}
+    </header>
+
+    <div class="container">
+    {% block content %}{% endblock %}
+    </div>
+
+    <footer>
+        <a class="footer-link" href="{{ url_for('about') }}">About</a>
+        <a class="footer-link" href="{{ url_for('submit_character') }}">Submit a Character</a>
+        {% block footer_extra %}{% endblock %}
+    </footer>
+</body>
+</html>

web/templates/_error.html

@@ -0,0 +1,8 @@
+{% extends "_base.html" %}
+{% block title %}
+	{{ error.code }}
+{% endblock %}
+{% block content %}
+    <h2>{{ error.code }}&nbsp;-&nbsp;{{ error.name }} </h2>
+    <p>{{ error.description }}</p>
+{% endblock %}

web/templates/about.html

@@ -1,13 +1,9 @@
-<!DOCTYPE html>
+{% extends "_base.html" %}
-<html>
+
-<head>
+{% block content %}
-    <title>About - Misskey Gacha Center</title>
-</head>
-<body>
     <h1>About This Gacha</h1>
     <p>This is a playful Misskey-themed gacha tracker made with Flask and SQLite.</p>
     <p>All rolls are stored, stats are tracked, and characters are added manually for now.</p>
     <p>Built with love, chaos, and way too much caffeine ☕.</p>
     <a href="{{ url_for('index') }}">← Back to Home</a>
-</body>
+{% endblock %}
-</html>

web/templates/index.html

@@ -1,110 +1,11 @@
-<!DOCTYPE html>
+{% extends "_base.html" %}
-<html>
-<head>
-    <title>Misskey Gacha Center</title>
-    <style>
-        body {
-            font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
-            background-color: #f4f6fa;
-            color: #333;
-            margin: 0;
-            padding: 0;
-        }
 
-        header {
+{% block header %}
-            background-color: #7289da;
-            color: white;
-            padding: 20px;
-            text-align: center;
-        }
-
-        header h1 {
-            margin: 0;
-            font-size: 2.5em;
-        }
-
-        header p {
-            margin-top: 5px;
-            font-size: 1.1em;
-        }
-
-        .container {
-            max-width: 800px;
-            margin: 30px auto;
-            padding: 20px;
-            background-color: #ffffff;
-            border-radius: 10px;
-            box-shadow: 0 3px 10px rgba(0, 0, 0, 0.07);
-        }
-
-        h2 {
-            border-bottom: 1px solid #ccc;
-            padding-bottom: 8px;
-            margin-top: 30px;
-        }
-
-        ul {
-            list-style-type: none;
-            padding-left: 0;
-        }
-
-        li {
-            margin: 10px 0;
-        }
-
-        a {
-            text-decoration: none;
-            color: #2c3e50;
-            font-weight: bold;
-            background-color: #e3eaf3;
-            padding: 8px 12px;
-            border-radius: 6px;
-            display: inline-block;
-            transition: background-color 0.2s;
-        }
-
-        a:hover {
-            background-color: #cdd8e6;
-        }
-
-        .leaderboard-entry {
-            margin-bottom: 8px;
-            padding: 6px 10px;
-            background: #f9fafc;
-            border-left: 4px solid #7289da;
-            border-radius: 5px;
-        }
-
-        footer {
-            text-align: center;
-            margin-top: 40px;
-            font-size: 0.9em;
-            color: #888;
-        }
-
-        .note {
-            background: #fcfcf0;
-            border: 1px dashed #bbb;
-            padding: 10px;
-            border-radius: 8px;
-            margin-top: 30px;
-            font-size: 0.95em;
-            color: #666;
-        }
-
-        .footer-link {
-            margin: 0 10px;
-        }
-    </style>
-</head>
-<body>
-
-    <header>
     <h1>Misskey Gacha Center</h1>
     <p>Track your luck. Compare your pulls. Compete with friends.</p>
-    </header>
+{% endblock %}
 
-    <div class="container">
+{% block content %}
 
         <h2>🎖️ Leaderboard: Most Rolls</h2>
         {% for user in top_users %}
@@ -125,13 +26,4 @@
         <div class="note">
             🚀 This is a fun little gacha tracker! More features coming soon. Want to help shape it?
         </div>
-
+{% endblock %}
-    </div>
-
-    <footer>
-        <a class="footer-link" href="{{ url_for('about') }}">About</a>
-        <a class="footer-link" href="{{ url_for('submit_character') }}">Submit a Character</a>
-    </footer>
-
-</body>
-</html>

web/templates/submit.html

@@ -1,12 +1,8 @@
-<!DOCTYPE html>
+{% extends "_base.html" %}
-<html>
+
-<head>
+{% block content %}
-    <title>Submit a Character - Misskey Gacha Center</title>
-</head>
-<body>
     <h1>Submit a Character</h1>
     <p>Want to add a new character to the gacha pool?</p>
     <p>This feature will be available soon. Stay tuned!</p>
     <a href="{{ url_for('index') }}">← Back to Home</a>
-</body>
+{% endblock %}
-</html>

web/templates/user.html

@@ -1,57 +1,5 @@
-<!DOCTYPE html>
+{% extends "_base.html" %}
-<html>
+{% block content %}
-<head>
-    <title>{{ user['username'] }}'s Rolls</title>
-    <style>
-        body {
-            font-family: Arial, sans-serif;
-            background-color: #f4f4f8;
-            margin: 0;
-            padding: 20px;
-        }
-        .profile, .pulls {
-            background-color: white;
-            padding: 15px;
-            border-radius: 10px;
-            box-shadow: 0 0 10px rgba(0,0,0,0.1);
-            margin-bottom: 20px;
-        }
-        h1, h2 {
-            margin-top: 0;
-        }
-        ul {
-            list-style-type: none;
-            padding: 0;
-        }
-        li {
-            padding: 10px 0;
-            border-bottom: 1px solid #eee;
-        }
-        .rarity {
-            color: gold;
-            font-weight: bold;
-            margin-left: 8px;
-        }
-        .timestamp {
-            color: #888;
-            font-size: 0.9em;
-        }
-        a {
-            display: inline-block;
-            margin-top: 20px;
-            color: #333;
-            text-decoration: none;
-            background-color: #ddd;
-            padding: 8px 12px;
-            border-radius: 5px;
-        }
-        a:hover {
-            background-color: #bbb;
-        }
-    </style>
-</head>
-<body>
-
     <div class="profile">
         <h1>{{ user['username'] }}'s Gacha Rolls</h1>
         <p>User ID: {{ user['id'] }}</p>
@@ -72,6 +20,4 @@
     </div>
 
     <a href="{{ url_for('index') }}">← Back to Users</a>
-
+{% endblock %}
-</body>
-</html>