# 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>

## 📝 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, but the server only works using a Misskey instance. Want to rewrite the program in Elixir for Pleroma? Let us know!

## 🗃️ Tech Stack

- Python (3.12+)
- SQLite
- Fediverse API integration (via Misskey endpoints)
- Flask
- Modular DB design for extensibility

## 💡 Philosophy

The bot is meant to feel *light, fun, and competitive*. Mixing social, gacha and duel tactics.

## 📝 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means:

- You are free to use, modify, and redistribute this software under the same license.

- If you modify and deploy the software (for example, as part of a web service), you must also make the source code of your modified version available to users of that service.

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/.
The full license text can be found here: https://www.gnu.org/licenses/agpl-3.0.html

The AGPL is designed to ensure that software freedom is preserved, especially in networked environments. If you improve this project or build something on top of it, please give back to the community by sharing your changes too.

Unless another license is listed, every file in the project is licensed under the GNU General Public License version 3 (or at your option), any later version.

```mermaid
flowchart TD

  subgraph Player Interaction
    A1[Misskey bot]
    A2[Web]
  end

  subgraph Misskey
    B1[Misskey instance]
  end

  subgraph Bot
    C1[Bot core in Python]
    C2[Notification parser]
    C3[Gacha roll logic]
    C4[Database interface]
    C5[Misskey API poster]
  end

  subgraph Website
    D1[Flask backend]
    D2[User account system]
    D3[Image gallery]
  end

  subgraph Backend
    E1[Shared database]
    E2[Virtual environment]
    E3[Debian Linux server]
  end

  A1 <-->|Send or receive mention| B1
  B1 -->|Send mention| C2
  C2 -->|Command and information| C3
  C3 <-->|Ask for command information and confirmed roll setting| C4
  C4 <--> E1
  C3 -->|Command result and info| C5
  C5 -->|Resulting Mention| B1

  A2 --> D1
  D1 --> D2
  D1 --> D3
  D2 --> E1
  D3 --> E1

  C1 --> E2
  D1 --> E2

  E1 --> E3
  B1 --> E3

```