Country Bounce Live

1. Introduction

Welcome to Country Bounce Live! Thank you for purchasing this product.

Country Bounce Live is a highly interactive, physics-based game designed specifically for TikTok Live streamers. Viewers can type country names in your stream's chat to spawn their country's ball into the arena. Viewers can also send TikTok Gifts to launch bombs that shrink the arena, leading to a chaotic battle where the last country standing wins.

This project is built using Python (Flask) for the secure backend and TikTok API connection, and Matter.js for the smooth HTML5 physics frontend.

2. Requirements

Before installing the game, ensure your computer meets the following minimum requirements:

• Operating System: Windows 10/11, macOS, or Linux.
• Python: Python 3.9 or newer installed. (Make sure to check "Add Python to PATH" during installation on Windows).
• OBS Studio: Or any streaming software that supports Browser Sources (e.g., Streamlabs OBS).
• Internet Connection: Required to connect to the TikTok Live API.

3. Installation Guide

Follow these steps to get your server running on your local machine.

1. Extract the downloaded zip file and open the Source folder.
2. Open your Terminal or Command Prompt.
3. Navigate to the Source folder inside the extracted project (replace the path below with wherever you extracted the zip):
   # Windows cd path\to\CountryBounce\Source # macOS / Linux cd path/to/CountryBounce/Source
4. Install the required Python dependencies by running:
   pip install -r requirements.txt
5. Once installed, start the game server:
   python app.py

4. OBS Studio Setup

To display the game on your TikTok Live, you need to add it to OBS Studio.

1. Open OBS Studio and create a new Scene.
2. In the Sources panel, click the + button and select Browser.
3. Name it "Country Bounce Game" and click OK.
4. In the Properties window, configure the following:
   • URL: http://localhost:5000/
   • Width: 1080
   • Height: 1920
   • Custom CSS: Leave default or clear it.
   • Check the box for "Control audio via OBS" if you want to control game volume in OBS.
5. Click OK. The game arena should now perfectly fill your vertical canvas.

5. Admin Panel & TikTok Setup

The Admin Panel allows you to control the game securely from your browser while streaming.

Accessing the Panel

Open your web browser (Chrome, Edge, Safari) and go to:

Logging In

The first time you run the server, it will prompt you to create an Admin password. On subsequent visits, enter that password to log in. This prevents unauthorized access to your game controls.

Connecting to TikTok

1. In the Admin Panel, find the TikTok Live Connection card.
2. Enter your exact TikTok Username (without the @ symbol). Note: Your account MUST be currently Live.
3. Click Connect. The status badge will change to a green Connected.

6. How It Works (Communication Flow)

Understanding the data flow helps when troubleshooting or extending the script. There are three moving parts, all running locally on your machine:

1. TikTok Live connection: when you click Connect in the Admin Panel, tiktok_connector.py opens a connection to your live room and listens for two event types: chat comments and gifts.
2. Comment → Spawn: each comment is matched (case-insensitively) against the bundled country name/code list. A match is emitted as a spawn_ball Socket.IO event.
3. Gift → Bomb: each gift is looked up in your configured Gift Mapping to get a bomb count, then emitted as an add_rockets Socket.IO event.
4. Backend → Frontend: Flask-SocketIO broadcasts these events over a WebSocket connection to every connected browser tab (your OBS Browser Source, and any preview tab you have open).
5. Frontend rendering: game.js listens for these events and drives the Matter.js physics engine — spawning balls, firing bombs, shrinking the arena, and detecting the winner — entirely client-side, so gameplay stays smooth even on a modest server.
6. Persistence: the current match state (phase, timer, leaderboard, balls in play) is periodically saved to Source/game_state.json on the server, so a page refresh (e.g. OBS reloading the source) resumes the match instead of losing progress.

The Admin Panel itself talks to the backend two ways: instant actions (simulate spawn/gift, start battle, reset) go over the same Socket.IO connection, while configuration changes (gift mapping, sounds, game settings, password) are saved via regular HTTP requests to /api/tiktok/config and written to Source/tiktok_config.json.

7. Gameplay Mechanics

Spawning Countries

Viewers simply need to type the name of a country or its abbreviation in the TikTok chat. The system is case-insensitive.

• Example: Indonesia or indonesia
• Example: ID or id

The Phases

• WAITING: The arena sits empty until the first viewer joins. If nobody joins within 20 seconds, the game automatically spawns a bot to kick things off so the show never stalls.
• PRE_SPAWN (15s): Once the first player joins, a 15-second "Waiting for Players" countdown starts. Any viewer can still join during this window.
• SPAWN / GET READY (10s): A final 10-second countdown before battle. The match requires a minimum number of players (configurable in the Admin Panel, default 5) — if real viewers don't fill the arena, bots are spawned gradually to reach the minimum so the match always starts on time.
• BATTLE: The balls begin to move and collide.
• CHAOS: The outer ring disappears, and the arena boundary closes in rapidly. Any ball that touches the boundary is eliminated. The last ball remaining wins!

Bomb System

During the Battle and Chaos phases, a default bomb drops automatically every 5 seconds. Viewers can send specific TikTok Gifts to spawn additional bombs instantly, drastically speeding up the game and causing massive chaos.

On-Screen Indicators

• ALIVE: Number of balls currently in the arena.
• Timer: Countdown for the current phase (or "CHAOS" once the arena starts closing in).
• NEXT SPAWN: Comments typed while a match is already in Battle/Chaos can't spawn immediately — they're queued for the next match. This counter shows how many are waiting, so viewers know their comment was received even while the current match is still playing out.
• 💣 Bomb Counter: Number of bombs queued to be fired.

8. Customization (Audio & Assets)

You can customize almost every aspect of the game through the Admin Panel.

Audio SFX Configuration

In the Admin Panel's 🎵 Audio SFX tab, you can easily change the sound effects without touching any code.

1. Click the Choose File button under the sound you want to change (Collision, Bomb, Win, or Countdown).
2. Select an .mp3, .wav, or .ogg file from your computer (Max 5MB).
3. The file will automatically upload securely to your server.
4. Adjust the Volume slider to your preference.
5. Click Save All Configurations.

The Countdown sound plays once per second during the "GET READY" countdown just before Battle starts.

Gift Mapping

In the Gift Configurations tab, you can define exactly how many bombs a specific TikTok gift will spawn. Type the exact name of the gift (e.g., "Rose", "Doughnut") and assign a bomb value.

Game Master Settings

In the 🕹️ Game Master tab you can configure:

• Max Balls per Arena: Hard cap on how many balls can exist in a single match.
• Min Players to Start Match: The minimum number of balls required before Battle can begin. If real viewers don't reach this number by the end of the countdown, the game fills the remaining slots with bots automatically.

9. Branding & Rebranding

You don't need any coding experience to make this game feel like your own. Here's exactly where to look:

Browser Tab Title

Change the text shown in the browser tab / OBS source name:

• Game page: edit the <title> tag in Source/templates/game.html.
• Admin page: edit the <title> tag in Source/templates/admin.html.

Admin Panel Colors

The Admin Panel's color scheme is controlled by CSS variables at the top of Source/templates/admin.html, inside the :root block:

Change any of these hex values and the entire Admin Panel (buttons, borders, glows) updates to match — no need to hunt through the file.

In-Game HUD Colors

The on-screen boxes (ALIVE, Timer, Next Spawn, Bomb Counter) get their colors from the .box-cyan, .box-red, .box-orange, and .box-purple classes in Source/static/style.css. Update the border/color/box-shadow hex values in each class to match your own brand palette.

Fonts

The game and Admin Panel both use the Outfit font, loaded locally from Source/static/fonts/ (no external font CDN required). To use a different font, replace the .woff2 files and adjust the @font-face rules in Source/static/fonts/outfit.css, then update the font-family references in style.css and admin.html.

Adding a Logo

There's no logo image baked into the canvas by default (to keep the arena view clean for streaming). If you'd like to add a watermark or logo:

• Simplest: add your logo as an absolutely-positioned <img> inside #ui-layer in Source/templates/game.html, and position it with CSS in style.css.
• Admin sidebar: replace the ⚙️ Admin Panel text in the .sidebar-header of admin.html with your own <img> logo tag.

10. Troubleshooting

Game isn't showing in OBS

Ensure that the Python terminal is running. If it crashed or was closed, open the terminal and run python app.py again. Then double-click your Browser Source in OBS and click "Refresh cache of current page".

TikTok connection fails

Make sure your TikTok account is currently Live. The TikTok API cannot connect to an offline account. Also, ensure you typed the username exactly as it appears, without the @ symbol.

Sounds are not playing

Modern browsers block autoplaying sounds until the user interacts with the page. In OBS, this is usually bypassed automatically. If opening in a regular browser, click anywhere on the page once to enable audio context.

11. Support

If you have any questions or run into issues not covered in this documentation, please reach out via the item support page on CodeCanyon. When requesting support, please include:

• A detailed description of the problem.
• Screenshots of the error (especially any text in the Python terminal).
• The operating system you are using.

Happy Streaming!