160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
<!--
|
|
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
|
|
|
|
```
|