` Creates a card using a given image.\n\
+- `signup` Registers your account.\n\
+- `delete_account` Deletes your account.\n\
+- `help` Shows this message',
+ 'attachment_urls': None
+ }
-def generate_response(parsed_command):
+
+def delete_account(author: str) -> BotResponse:
+ return {
+ '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
+ }
+
+
+def generate_response(notification: ParsedNotification) -> BotResponse | None:
'''Given a command with arguments, processes the game state and
returns a response'''
- command, full_user, arguments, note_obj = parsed_command
+ # Temporary response variable
+ res: BotResponse | None = None
+ author = notification['author']
+ player_id = db.get_player(author)
+ command = notification['command']
+
+ # Unrestricted commands
match command:
case 'roll':
- return do_roll(full_user)
- case 'create':
- return do_create(full_user, arguments, note_obj)
+ res = do_roll(author)
+ case 'signup':
+ res = do_signup(author)
case 'help':
- return do_help(command)
+ res = do_help(author)
case _:
- return None
+ pass
+
+ # Commands beyond this point require the user to have an account
+ if not player_id:
+ return res
+
+ # User commands
+ match command:
+ 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
+
+ # 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
diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..5858d9e
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,49 @@
+
+
+# Contributing to Kemoverse
+
+Contributions are welcome with the following requirements:
+
+## Licensing
+
+- All contributions must be licensed under the **AGPLv3-or-later** or a compatible license.
+- If you include code from another project (e.g., MIT Expat), please **list the license and copyright holders** clearly.
+- If your contribution introduces code under a different license, you **must clarify this**, so the project can remain license-compliant.
+
+## Attribution
+
+- Please **add your name** to the license header of any file where you’ve made a **nontrivial change**.
+- Nontrivial changes include:
+ - New features
+ - Logic changes
+ - Major refactoring or structure changes
+ - Not: typo fixes or simple reformatting
+
+## Commit Messages (optional but appreciated)
+
+- Try to write clear, descriptive commit messages.
+
+## Communication
+
+- If you're planning a major change or feature, please open an issue or contact the maintainers first.
+- This helps avoid duplicated work and makes collaboration easier.
+
+---
+
+Thank you for helping grow the Kemoverse 💫
\ No newline at end of file
diff --git a/db.py b/db.py
deleted file mode 100644
index 3849481..0000000
--- a/db.py
+++ /dev/null
@@ -1,73 +0,0 @@
-import sqlite3
-
-# Connect to SQLite database (or create it if it doesn't exist)
-conn = sqlite3.connect('gacha_game.db')
-cursor = conn.cursor()
-
-# Create tables
-cursor.execute('''
-CREATE TABLE IF NOT EXISTS users (
- id INTEGER PRIMARY KEY AUTOINCREMENT,
- username TEXT UNIQUE NOT NULL,
- has_rolled BOOLEAN NOT NULL DEFAULT 0
-)
-''')
-
-cursor.execute('''
-CREATE TABLE IF NOT EXISTS characters (
- id INTEGER PRIMARY KEY AUTOINCREMENT,
- name TEXT NOT NULL,
- rarity INTEGER NOT NULL,
- weight REAL NOT NULL,
- file_id TEXT NOT NULL
-)
-''')
-
-cursor.execute('''
-CREATE TABLE IF NOT EXISTS pulls (
- id INTEGER PRIMARY KEY AUTOINCREMENT,
- user_id INTEGER,
- character_id INTEGER,
- timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
- FOREIGN KEY (user_id) REFERENCES users(id),
- FOREIGN KEY (character_id) REFERENCES characters(id)
-)
-''')
-
-cursor.execute("""
- CREATE TABLE IF NOT EXISTS config (
- key TEXT PRIMARY KEY,
- value TEXT
- )
- """)
-
-cursor.execute('''
-CREATE TABLE IF NOT EXISTS character_stats (
- character_id INTEGER PRIMARY KEY,
- power INTEGER NOT NULL DEFAULT abs(random() % 9999),
- charm INTEGER NOT NULL DEFAULT abs(random() % 9999),,
- FOREIGN KEY(character_id) REFERENCES characters(id)
-)
-''')
-
-# Initialize essential config key
-cursor.execute('INSERT INTO config VALUES ("last_seen_notif_id", 0)')
-
-""" # Insert example characters into the database if they don't already exist
-characters = [
- ('Murakami-san', 1, 0.35),
- ('Mastodon-kun', 2, 0.25),
- ('Pleroma-tan', 3, 0.2),
- ('Misskey-tan', 4, 0.15),
- ('Syuilo-mama', 5, 0.05)
-]
-
-
-cursor.executemany('''
-INSERT OR IGNORE INTO characters (name, rarity, weight) VALUES (?, ?, ?)
-''', characters)
-"""
-
-# Commit changes and close
-conn.commit()
-conn.close()
diff --git a/dev_runner.py b/dev_runner.py
index b39a434..92fd0aa 100644
--- a/dev_runner.py
+++ b/dev_runner.py
@@ -1,3 +1,19 @@
+# Kemoverse - a gacha-style bot for the Fediverse.
+# Copyright © 2025 Waifu
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see https://www.gnu.org/licenses/.
+
import subprocess
import os
from watchdog.observers import Observer
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f6ad524
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,41 @@
+
+# 🎲 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)
+
+---
+
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..8584b79
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,100 @@
+
+
+## 🧪 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
+```
diff --git a/docs/theme.md b/docs/theme.md
new file mode 100644
index 0000000..f3f54b4
--- /dev/null
+++ b/docs/theme.md
@@ -0,0 +1,50 @@
+
+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
+
+
+
+
+- File: `web/static/logo.png`
+- Usage: Website header, favicon, bot avatar, watermark
+
+
+---
\ No newline at end of file
diff --git a/example_config.ini b/example_config.ini
index d7f1c14..b147f34 100644
--- a/example_config.ini
+++ b/example_config.ini
@@ -1,14 +1,49 @@
+; Kemoverse - a gacha-style bot for the Fediverse.
+; Copyright © 2025 Waifu and VD15
+
+; This program is free software: you can redistribute it and/or modify
+; it under the terms of the GNU Affero General Public License as
+; published by the Free Software Foundation, either version 3 of the
+; License, or (at your option) any later version.
+
+; This program is distributed in the hope that it will be useful,
+; but WITHOUT ANY WARRANTY; without even the implied warranty of
+; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+; GNU Affero General Public License for more details.
+
+; You should have received a copy of the GNU Affero General Public License
+; along with this program. If not, see https://www.gnu.org/licenses/.
+
+
; Rename me to config.ini and put your values in here
[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
+; Instance type - either "misskey" or "pleroma"
+InstanceType = misskey
+; Web server port (default: 5000)
+WebPort = 5000
+; Web server bind address (default: 127.0.0.1, set to 0.0.0.0 to listen on all interfaces)
+BindAddress = 127.0.0.1
+
+; 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
@@ -24,4 +59,3 @@ User = @bot@example.tld
; API key for the bot
; Generate one by going to Settings > API > Generate access token
Token = abcdefghijklmnopqrstuvwxyz012345
-
diff --git a/migrations/0000_setup.sql b/migrations/0000_setup.sql
new file mode 100644
index 0000000..2f0dd85
--- /dev/null
+++ b/migrations/0000_setup.sql
@@ -0,0 +1,45 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 VD15 and contributors.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+CREATE TABLE IF NOT EXISTS users (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ username TEXT UNIQUE NOT NULL,
+ has_rolled BOOLEAN NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS characters (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ name TEXT NOT NULL,
+ rarity INTEGER NOT NULL,
+ weight REAL NOT NULL,
+ file_id TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS pulls (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ user_id INTEGER,
+ character_id INTEGER,
+ timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+ FOREIGN KEY (user_id) REFERENCES users(id),
+ FOREIGN KEY (character_id) REFERENCES characters(id)
+);
+
+CREATE TABLE IF NOT EXISTS config (
+ key TEXT PRIMARY KEY,
+ value TEXT
+);
+INSERT OR IGNORE INTO config VALUES ("schema_version", 0);
diff --git a/migrations/0001_fix_notif_id.sql b/migrations/0001_fix_notif_id.sql
new file mode 100644
index 0000000..bf7eb2e
--- /dev/null
+++ b/migrations/0001_fix_notif_id.sql
@@ -0,0 +1,18 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 VD15 and contributors.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+INSERT OR IGNORE INTO config VALUES ("last_seen_notif_id", 0);
diff --git a/migrations/0002_weigh_infer.sql b/migrations/0002_weigh_infer.sql
new file mode 100644
index 0000000..cf571f1
--- /dev/null
+++ b/migrations/0002_weigh_infer.sql
@@ -0,0 +1,19 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 Waifu and contributors.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+
+ALTER TABLE characters DROP COLUMN weight;
diff --git a/migrations/0003_rename_tables.sql b/migrations/0003_rename_tables.sql
new file mode 100644
index 0000000..7d9e0c4
--- /dev/null
+++ b/migrations/0003_rename_tables.sql
@@ -0,0 +1,22 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 VD15 and contributors.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+
+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;
diff --git a/migrations/0004_add_administrators.sql b/migrations/0004_add_administrators.sql
new file mode 100644
index 0000000..51bef49
--- /dev/null
+++ b/migrations/0004_add_administrators.sql
@@ -0,0 +1,19 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 VD15
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+
+ALTER TABLE players ADD COLUMN is_administrator BOOLEAN NOT NULL DEFAULT 0;
diff --git a/migrations/0005_add_whitelist.sql b/migrations/0005_add_whitelist.sql
new file mode 100644
index 0000000..7769253
--- /dev/null
+++ b/migrations/0005_add_whitelist.sql
@@ -0,0 +1,25 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 VD15
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+
+CREATE TABLE IF NOT EXISTS instance_whitelist (
+ tld TEXT UNIQUE PRIMARY KEY
+);
+
+CREATE TABLE IF NOT EXISTS banned_players (
+ handle TEXT UNIQUE PRIMARY KEY
+);
diff --git a/migrations/0006_card_stats.sql b/migrations/0006_card_stats.sql
new file mode 100644
index 0000000..5a67de8
--- /dev/null
+++ b/migrations/0006_card_stats.sql
@@ -0,0 +1,24 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 Waifu
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+*/
+
+CREATE TABLE IF NOT EXISTS card_stats (
+ card_id INTEGER PRIMARY KEY,
+ power INTEGER NOT NULL DEFAULT abs(random() % 9999),
+ charm INTEGER NOT NULL DEFAULT abs(random() % 9999),,
+ FOREIGN KEY(card_id) REFERENCES card(id)
+)
\ No newline at end of file
diff --git a/readme.md b/readme.md
index 9da5b60..40e41e3 100644
--- a/readme.md
+++ b/readme.md
@@ -1,35 +1,120 @@
-# Readme
+
+
+# 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. Supports both Misskey and Pleroma instances. Name comes from Kemonomimi and Fediverse.
+
+
+
+## 📝 Docs
+
+👉 [**Start reading the docs**](./docs/index.md)
+
+🤌 [**Install instructions for those in a rush**](docs/install.md)
+
+## 🔧 Features
+
+### ✅ Implemented
+- 🎲 Character roll system
+- 🧠 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
+
+
+## 🧠 Roadmap
+
+[See our v2.0 board for more details](https://git.waifuism.life/waifu/kemoverse/projects/3)
+
+### 🛒 Gameplay & Collection
+- 🔁 **Trading system** between players
+- ⭐ **Favorite characters** (pin them or set profiles)
+- 📢 **Public post announcements** for rare card pulls
+- 📊 **Stats** for cards
+- 🎮 **Games** to play
+ - ⚔️ Dueling
+- 🧮 **Leaderboards**
+ - Most traded cards
+ - Most owned cards
+ - Most voted cards
+ - Most popular cards (via usage-based popularity metrics)
+ - Users with the rarest cards
+
+### 🎨 Card Aesthetics
+- 🖼️ Simple card template for character rendering
+- 🌐 Web app to generate cards from images
+
+### 🌍 Fediverse Support
+✅ Anyone from the fediverse can play! The bot supports both Misskey and Pleroma instances through configurable backends.
+
+## 🗃️ Tech Stack
+
+- Python (3.12+)
+- SQLite
+- Fediverse API integration (Misskey and Pleroma support)
+- Flask
+- Modular DB design for extensibility
+
+## 💡 Philosophy
+
+The bot is meant to feel *light, fun, and competitive*. Mixing social, gacha and duel tactics.
+
+## 📝 License
+
+Unless stated otherwise, this repository is:
+
+**Copyright © 2025 Waifu and contributors**
+**Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**
+
+---
+
+### 🛠️ What this means for you:
+
+- You are free to **use**, **modify**, and **redistribute** the code, as long as you preserve the same license.
+- If you run a modified version of this software as part of a service (e.g., a website or bot), you must also **share the source code** of your modifications with users.
+
+A copy of the license should also be included in this repository.
+If not, you can always find it at [gnu.org/licenses](https://www.gnu.org/licenses/).
+
+---
+
+The AGPL exists to **protect user freedom**, especially in networked and server-side software. If you enhance or build upon this project, please help the community by sharing your changes too.
+
+Unless explicitly stated otherwise, **all files in this repository are covered by the AGPL v3.0 or any later version**.
-To-do:
-- Whitelist system for users
-- Time limitation on rolls
-Long term:
-- Trading
-- Card burning
-- Favorite characters
-- Public post for rare cards
-- Leaderboards
- - Most traded Characters
- - Most owned Characters
- - Most voted Characters
- - Most popular Characters
- - Users with the rarest Characters
-- Simple card template
- - Website to place images in the card
-- Add Pleroma support
```mermaid
flowchart TD
subgraph Player Interaction
- A1[Misskey bot]
+ A1[Fediverse bot]
A2[Web]
end
- subgraph Misskey
- B1[Misskey instance]
+ subgraph Fediverse
+ B1[Fediverse instance]
end
subgraph Bot
@@ -37,7 +122,7 @@ flowchart TD
C2[Notification parser]
C3[Gacha roll logic]
C4[Database interface]
- C5[Misskey API poster]
+ C5[Fediverse API poster]
end
subgraph Website
diff --git a/requirements.txt b/requirements.txt
index 1db6f9b..d747e71 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,19 @@
+# Kemoverse - a gacha-style bot for the Fediverse.
+# Copyright © 2025 Waifu
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see https://www.gnu.org/licenses/.
+
blinker==1.9.0
click==8.1.8
Flask==3.1.0
@@ -6,3 +22,5 @@ Jinja2==3.1.6
MarkupSafe==3.0.2
Werkzeug==3.1.3
Misskey.py==4.1.0
+Mastodon.py==1.8.1
+filetype==1.2.0
diff --git a/setup_db.py b/setup_db.py
new file mode 100644
index 0000000..45b3aba
--- /dev/null
+++ b/setup_db.py
@@ -0,0 +1,142 @@
+#Kemoverse - a gacha-style bot for the Fediverse.
+#Copyright © 2025 Waifu
+#
+#This program is free software: you can redistribute it and/or modify
+#it under the terms of the GNU Affero General Public License as
+#published by the Free Software Foundation, either version 3 of the
+#License, or (at your option) any later version.
+#
+#This program is distributed in the hope that it will be useful,
+#but WITHOUT ANY WARRANTY; without even the implied warranty of
+#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#GNU Affero General Public License for more details.
+#
+#You should have received a copy of the GNU Affero General Public License
+#along with this program. If not, see https://www.gnu.org/licenses/.
+
+import sqlite3
+import traceback
+import os
+import argparse
+from configparser import ConfigParser
+from typing import List, Tuple
+
+class DBNotFoundError(Exception):
+ '''Could not find the database location'''
+
+class InvalidMigrationError(Exception):
+ '''Migration file has an invalid name'''
+
+class KemoverseEnvUnset(Exception):
+ '''KEMOVERSE_ENV is not set or has an invalid value'''
+
+class ConfigError(Exception):
+ '''Could not find the config file for the current environment'''
+
+def get_migrations() -> List[Tuple[int, str]] | InvalidMigrationError:
+ '''Returns a list of migration files in numeric order.'''
+ # Store transaction id and filename separately
+ sql_files: List[Tuple[int, str]] = []
+ migrations_dir = 'migrations'
+
+ for filename in os.listdir(migrations_dir):
+ joined_path = os.path.join(migrations_dir, filename)
+
+ # Ignore anything that isn't a .sql file
+ if not (os.path.isfile(joined_path) and filename.endswith('.sql')):
+ print(f'{filename} is not a .sql file, ignoring...')
+ continue
+
+ parts = filename.split('_', 1)
+
+ # Invalid filename format
+ if len(parts) < 2 or not parts[0].isdigit():
+ raise InvalidMigrationError(f'Invalid migration file: {filename}')
+
+ sql_files.append((int(parts[0]), joined_path))
+
+ # Get sorted list of files by migration number
+ sql_files.sort(key=lambda x: x[0])
+ return sql_files
+
+def perform_migration(cursor: sqlite3.Cursor, migration: tuple[int, str]) -> None:
+ '''Performs a migration on the DB'''
+ print(f'Performing migration {migration[1]}...')
+
+ # Open and execute the sql script
+ with open(migration[1], encoding='utf-8') as file:
+ script = file.read()
+ cursor.executescript(script)
+ # Update the schema version
+ cursor.execute('UPDATE config SET value = ? WHERE key = "schema_version"', (migration[0],))
+
+def get_db_path() -> str | DBNotFoundError:
+ '''Gets the DB path from config.ini'''
+ env = os.environ.get('KEMOVERSE_ENV')
+
+ config_path = f'config_{env}.ini'
+
+ if not os.path.isfile(config_path):
+ raise ConfigError(f'Could not find {config_path}')
+
+ print(f'Running in "{env}" mode')
+
+ config = ConfigParser()
+ config.read(config_path)
+ db_path = config['application']['DatabaseLocation']
+ if not db_path:
+ raise DBNotFoundError()
+ return db_path
+
+def get_current_migration(cursor: sqlite3.Cursor) -> int:
+ '''Gets the current schema version of the database'''
+ try:
+ cursor.execute('SELECT value FROM config WHERE key = ?', ('schema_version',))
+ version = cursor.fetchone()
+ return -1 if not version else int(version[0])
+ except sqlite3.Error:
+ print('Error getting schema version')
+ # Database has not been initialized yet
+ return -1
+
+def main():
+ '''Does the thing'''
+ # Connect to the DB
+ db_path = ''
+ try:
+ db_path = get_db_path()
+ except ConfigError as ex:
+ print(ex)
+ return
+ except KemoverseEnvUnset:
+ print('Error: KEMOVERSE_ENV is either not set or has an invalid value.')
+ print(traceback.format_exc())
+ return
+
+ conn = sqlite3.connect(db_path, autocommit=False)
+ conn.row_factory = sqlite3.Row
+ cursor = conn.cursor()
+
+ # Obtain list of migrations to run
+ migrations = get_migrations()
+ # Determine schema version
+ current_migration = get_current_migration(cursor)
+ print(f'Current schema version: {current_migration}')
+
+ # Run any migrations newer than current schema
+ for migration in migrations:
+ if migration[0] <= current_migration:
+ print(f'Migration already up: {migration[1]}')
+ continue
+ try:
+ perform_migration(cursor, migration)
+ conn.commit()
+ except Exception as ex:
+ print(f'An error occurred while applying {migration[1]}: {ex}, aborting...')
+ print(traceback.format_exc())
+ conn.rollback()
+ break
+ conn.close()
+
+if __name__ == '__main__':
+ main()
diff --git a/startup.sh b/startup.sh
index 7c216b6..3741e71 100755
--- a/startup.sh
+++ b/startup.sh
@@ -1,5 +1,21 @@
#!/bin/bash
+# Kemoverse - a gacha-style bot for the Fediverse.
+# Copyright © 2025 Waifu and VD15
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see https://www.gnu.org/licenses/.
+
# Navigate to the project directory (optional)
cd "$(dirname "$0")"
diff --git a/web/app.py b/web/app.py
index f68084c..f125784 100644
--- a/web/app.py
+++ b/web/app.py
@@ -1,14 +1,45 @@
-from flask import Flask, render_template
+#Kemoverse - a gacha-style bot for the Fediverse.
+#Copyright © 2025 Waifu
+#
+#This program is free software: you can redistribute it and/or modify
+#it under the terms of the GNU Affero General Public License as
+#published by the Free Software Foundation, either version 3 of the
+#License, or (at your option) any later version.
+#
+#This program is distributed in the hope that it will be useful,
+#but WITHOUT ANY WARRANTY; without even the implied warranty of
+#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+#GNU Affero General Public License for more details.
+#
+#You should have received a copy of the GNU Affero General Public License
+#along with this program. If not, see https://www.gnu.org/licenses/.
+
import sqlite3
+import sys
+import os
+
+# Add bot directory to path to import config
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'bot'))
+import config
+
+from flask import Flask, render_template, abort
+from werkzeug.exceptions import HTTPException
app = Flask(__name__)
-DB_PATH = "./gacha_game.db" # Adjust path if needed
def get_db_connection():
- conn = sqlite3.connect(DB_PATH)
+ conn = sqlite3.connect(config.DB_PATH)
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 +64,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
@@ -56,4 +89,4 @@ def submit_character():
if __name__ == '__main__':
- app.run(host='0.0.0.0', port=5000, debug=True)
+ app.run(host=config.BIND_ADDRESS, port=config.WEB_PORT, debug=True)
diff --git a/web/static/logo.png b/web/static/logo.png
new file mode 100644
index 0000000..a94cfdb
Binary files /dev/null and b/web/static/logo.png differ
diff --git a/web/static/style.css b/web/static/style.css
new file mode 100644
index 0000000..95380a8
--- /dev/null
+++ b/web/static/style.css
@@ -0,0 +1,109 @@
+/*
+Kemoverse - a gacha-style bot for the Fediverse.
+Copyright © 2025 Waifu
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.
+ */
+body {
+ font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
+ background-color: #FAFAFA;
+ color: #333;
+ margin: 0;
+ padding: 0;
+ }
+
+ header {
+ background-color: #5aa02c;
+ 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;
+ }
\ No newline at end of file
diff --git a/web/templates/_base.html b/web/templates/_base.html
new file mode 100644
index 0000000..f025c75
--- /dev/null
+++ b/web/templates/_base.html
@@ -0,0 +1,47 @@
+
+
+
+
+
+ {% if title %}
+ {{ title }}
+ {% else %}
+ {% block title %}{% endblock %}
+ {% endif %}
+ | Kemoverse
+
+
+
+
+ {% block header %}{% endblock %}
+
+
+
+ {% block content %}{% endblock %}
+
+
+
+
+
+ {% block footer_extra %}{% endblock %}
+
+
+
diff --git a/web/templates/_error.html b/web/templates/_error.html
new file mode 100644
index 0000000..6d18f04
--- /dev/null
+++ b/web/templates/_error.html
@@ -0,0 +1,25 @@
+
+{% extends "_base.html" %}
+{% block title %}
+ {{ error.code }}
+{% endblock %}
+{% block content %}
+ {{ error.code }} - {{ error.name }}
+ {{ error.description }}
+{% endblock %}
\ No newline at end of file
diff --git a/web/templates/about.html b/web/templates/about.html
index 89519db..b704664 100644
--- a/web/templates/about.html
+++ b/web/templates/about.html
@@ -1,13 +1,26 @@
-
-
-
- About - Misskey Gacha Center
-
-
+
+{% extends "_base.html" %}
+
+{% block content %}
About This Gacha
This is a playful Misskey-themed gacha tracker made with Flask and SQLite.
All rolls are stored, stats are tracked, and characters are added manually for now.
Built with love, chaos, and way too much caffeine ☕.
← Back to Home
-
-
+{% endblock %}
\ No newline at end of file
diff --git a/web/templates/index.html b/web/templates/index.html
index e9b1680..6f2351d 100644
--- a/web/templates/index.html
+++ b/web/templates/index.html
@@ -1,110 +1,29 @@
-
-
-
- Misskey Gacha Center
-
-
-
-
-
-
-
+{% block content %}
🎖️ Leaderboard: Most Rolls
{% for user in top_users %}
@@ -125,13 +44,4 @@
🚀 This is a fun little gacha tracker! More features coming soon. Want to help shape it?
-
-
Submit a Character - Misskey Gacha Center
-
-
+
+{% extends "_base.html" %}
+
+{% block content %}
Submit a Character
Want to add a new character to the gacha pool?
This feature will be available soon. Stay tuned!
← Back to Home
-
-
+{% endblock %}
\ No newline at end of file
diff --git a/web/templates/user.html b/web/templates/user.html
index 0004052..1ccb447 100644
--- a/web/templates/user.html
+++ b/web/templates/user.html
@@ -1,57 +1,22 @@
-
-
-
- {{ user['username'] }}'s Rolls
-
-
-
+
+{% extends "_base.html" %}
+{% block content %}
{{ user['username'] }}'s Gacha Rolls
User ID: {{ user['id'] }}
@@ -72,6 +37,4 @@
← Back to Users
-
-
-
+{% endblock %}
\ No newline at end of file
+
+