<!--
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/. 
-->

# 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.
<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! 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**.




```mermaid
flowchart TD

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

  subgraph Fediverse
    B1[Fediverse instance]
  end

  subgraph Bot
    C1[Bot core in Python]
    C2[Notification parser]
    C3[Gacha roll logic]
    C4[Database interface]
    C5[Fediverse 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

```