Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/plasmoapp/jigsaw-bot
Turn any image into a Jigsaw Puzzle and solve it together with friends without leaving Telegram
https://github.com/plasmoapp/jigsaw-bot
axum godot rust telegram telegram-miniapp-contest-2023 teloxide
Last synced: about 1 month ago
JSON representation
Turn any image into a Jigsaw Puzzle and solve it together with friends without leaving Telegram
- Host: GitHub
- URL: https://github.com/plasmoapp/jigsaw-bot
- Owner: plasmoapp
- License: mit
- Created: 2023-09-26T18:49:06.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2023-10-12T17:31:53.000Z (8 months ago)
- Last Synced: 2024-05-03T19:19:18.193Z (about 2 months ago)
- Topics: axum, godot, rust, telegram, telegram-miniapp-contest-2023, teloxide
- Language: Rust
- Homepage: https://t.me/jigsawpuzzlebot
- Size: 5.94 MB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-stars - jigsaw-bot
README
# Jigsaw Puzzle Bot
Turn any image into a Jigsaw Puzzle and solve it together with friends without leaving Telegram
Made with [Rust](https://www.rust-lang.org/) 🚀, [Godot](https://godotengine.org/) and [Redis](https://redis.io/)
Try it out now: [@jigsawpuzzlebot](https://t.me/jigsawpuzzlebot)
https://github.com/plasmoapp/jigsaw-bot/assets/27863947/33d762f9-6c69-4896-9314-4dc6cb318ad7
## Project overview
---
**[jigsaw-generator](./jigsaw-generator)**
- Made with Rust
- Subscribed for a [Redis PubSub](https://redis.io/docs/interact/pubsub/) request to generate a puzzle from an image
- Stores processed images in the file system and puzzle state in Redis
- Publishes a [Redis PubSub](https://redis.io/docs/interact/pubsub/) event when a puzzle is generated. Or when it fails to generate a puzzle
---
**[jigsaw-bot](./jigsaw-bot)**
- Made with [Teloxide](https://github.com/teloxide/teloxide) Rust framework
- An entry point of the Mini App
- Takes images from users and publishes a [Redis PubSub](https://redis.io/docs/interact/pubsub/) request to [jigsaw-generator](./jigsaw-generator) to generate a puzzle
- Notifies users when a puzzle finished or failed generating
- Allows users to share puzzles with friends using [Inline Query](https://core.telegram.org/bots/features#inline-requests)
---
**[jigsaw-game](./jigsaw-game)**
- Made with [Godot Engine](https://godotengine.org/)
- Frontend of the Mini App
- Uses version 3.5 of Godot because version 4.x has worse HTML support
---
**[jigsaw-backend](./jigsaw-backend)**
- Made with [Axum](https://github.com/tokio-rs/axum) Rust framework
- HTTP and WebSocket server
- Serves images generated by [jigsaw-generator](./jigsaw-generator)
- Serves [jigsaw-game](./jigsaw-game) exported as HTML
- Real-time multiplayer powered by WebSockets
---
**[jigsaw-common](./jigsaw-common)**
- Common Rust module shared between all other Rust modules
---
## Documentation
Most of the code has comments so if you're feeling courageous – clone the repo and jump straight into it
Here is also a list of specific features you might want to use in your project
### Mini App authorization flow on WebSockets
- [/jigsaw-game/components/web_socket_client/web_socket_manager.gd](/jigsaw-game/components/web_socket_client/web_socket_manager.gd)
- [/jigsaw-backend/src/websocket/unauthorized_handler.rs](/jigsaw-backend/src/websocket/unauthorized_handler.rs)
- [Read Telegram Docs on Validating data](https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app)
### Custom HTML shell for Godot
The shell affects how the loading screen looks. This custom shell will match Telegram theme
- [/jigsaw-game/custom_shell.html](/jigsaw-game/custom_shell.html)
- [Read more on Godot Custom HTML Page](https://docs.godotengine.org/en/3.5/tutorials/platform/customizing_html5_shell.html)
### Sync Godot Theme with Telegram Theme
- [/jigsaw-game/global/theme_manager/theme_manager.gd](/jigsaw-game/global/theme_manager/theme_manager.gd)
### Access Telegram startParam inside of Godot
- [/jigsaw-game/components/game_manager/game_manager.gd#L30](/jigsaw-game/components/game_manager/game_manager.gd)
## How to setup a developer enviroment
### 1. Download Docker
Docker Compose will allow us to install dependencies and launch multiple processes with one simple command
Install Docker Engine: https://docs.docker.com/engine/install/#desktop
### 2. Setup Ngrok
You need a secure HTTP connection for a Telegram Web App. To test the app locally you can use ngrok
Download: https://ngrok.com/download
Then use this command to open a tunnel
```bash
ngrok http 3030
```
Keep the URL that looks like this: `https://-.ngrok-free.app`
### 3. Create a Telegram Bot and a Web App
Create a bot using [@BotFather](https://t.me/BotFather). Don't forget to copy and save the bot token as you will need it later
```
/newbot
```
Enable Inline Mode
```
/setinline
```
Create a Web App. Set URL to the one you got from ngrok. The app can have any name
```
/newapp
```
### 4. Clone the repo
```
git clone https://github.com/plasmoapp/jigsaw-bot.git
cd jigsaw-bot
```
### 5. Create .env file inside of the cloned repo
```bash
touch .env
```
```env
# URL of the Web App
CONFIG.WEB_APP_URL=https://-.ngrok-free.app
# Name of the bot. Like in @ or t.me/
CONFIG.BOT_NAME=jigsawpuzzlebot
# Name of the Telegram Web App. Like in t.me//
CONFIG.WEB_APP_NAME=game
# Bot Token
CONFIG.BOT_TOKEN=
# Enable logs
RUST_LOG=DEBUG
```
### 6. Start the containers
```bash
docker-compose up --build -d
```
```bash
# View status of the containers
docker-compose ps -a
# View logs
docker-compose logs -f
# Build a specific container
docker-compose up --build -d backend
docker-compose up --build -d bot
docker-compose up --build -d generator
# Stop everything
docker-compose stop
# If you want to build it in the release mode use this instead
docker-compose -f docker-compose-release.yaml up --build -d
```
### Keep in mind
[jigsaw-game](./jigsaw-game) project is built inside of the [jigsaw-backend](./jigsaw-backend) Dockerfile
After you've made changed to the [jigsaw-game](./jigsaw-game) project – you need to restart the `backend` container
App runs on the port `3030`. You can change it in `docker-compose.yaml`
## Planned features
I've made a list of features that I wanted to implement but didn't have time because of the contest deadline
Probably will work on them eventually but I also welcome contributions 😊
- [Chat UI #6](https://github.com/plasmoapp/jigsaw-bot/issues/6)
- [Allow different tile dimensions #4](https://github.com/plasmoapp/jigsaw-bot/issues/4)
- [Online player count #5](https://github.com/plasmoapp/jigsaw-bot/issues/5)
- [Fix dragging ghost #8](https://github.com/plasmoapp/jigsaw-bot/issues/8)
- [Sound effects #2](https://github.com/plasmoapp/jigsaw-bot/issues/2)
- [Fix Z-index on tiles that don't snap to grid #7](https://github.com/plasmoapp/jigsaw-bot/issues/7)
- [Check of user id collisions](https://github.com/plasmoapp/jigsaw-bot/issues/3)
- [Send a picture or a gif on /start #1](https://github.com/plasmoapp/jigsaw-bot/issues/1)