# 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.
=======
## Installation

## Roadmap

![Fediverse Gacha Bot Logo](./web/static/logo.png)

## 🔧 Features

### ✅ Implemented
- 🎲 Character roll system
- 🎴 Cards stats system
- 🧠 Core database structure for characters and stats
- 📦 Basic support for storing pulls per user
- ⏱️ Time-based limitations on rolls

### 🧩 In Progress
- 📝 Whitelist system to limit access
- ⚠️  Explicit account creation/deletion

## 🧠 Roadmap

[See our v2.0 board for more details](https://git.waifuism.life/waifu/kemoverse/projects/3)

### 🛒 Gameplay & Collection
- 🔁 **Trading system** between users
- ⭐ **Favorite characters** (pin them or set profiles)
- 📢 **Public post announcements** for rare card pulls
- 📊 **Stats** for cards
- 🎮 **Games** to play
  - ⚔️ Dueling
- 🧮 **Leaderboards**
  - Most traded Characters
  - Most owned Characters
  - Most voted Characters
  - Most popular Characters (via usage-based popularity metrics)
  - Users with the rarest Characters

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

## 🧪 Installation

1. 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
```

2. 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
```

4. Setup database

To set up the database, run:

```sh
KEMOVERSE_ENV=dev python3 setup_db.py
```

5. Run the bot

```sh
KEMOVERSE_ENV=dev ./startup.sh
```

If all goes well, you should now be able to interact with the bot.

6. 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? 🤨)

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

  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

```