kemoverse/readme.md

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

🔧 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

🛒 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

git clone https://git.waifuism.life/waifu/kemoverse.git
cd kemoverse

Setup a virtual environment (Optional, recommended)

python3 -m venv venv
source venv/bin/activate

Install project dependencies via pip

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.

cp example_config.ini config_dev.ini
# Edit config_dev.ini

4. Setup database

To set up the database, run:

KEMOVERSE_ENV=dev python3 setup_db.py

5. Run the bot

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:

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!

# Backup database file
cp gacha_game_dev.db gacha_game_dev.db.bak
# Run migrations
KEMOVERSE_ENV=dev python3 setup_db.py

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