Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Awesome Lists containing this project

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)