TÀI LIỆU MÔ TẢ DỰ ÁN

TikTok Interactive Live Show

---

1. Giới thiệu

1.1 Mục tiêu

TikTok Interactive Live Show là một hệ thống cho phép chuyển toàn bộ tương tác của người xem trong một buổi TikTok Live thành các hoạt động diễn ra trong một thế giới ảo được hiển thị trực tiếp trên livestream.

Mỗi người xem khi tham gia và có tương tác sẽ được đại diện bởi một Sticker (nhân vật 2D) có hoạt ảnh. Người xem có thể nhảy, di chuyển, lên sân khấu VIP, nhận hiệu ứng đặc biệt hoặc thay đổi trạng thái dựa trên các hành động như bình luận, thích, theo dõi và tặng quà.

Streamer không cần chỉnh sửa mã nguồn mà có thể quản lý toàn bộ chương trình thông qua Dashboard, bao gồm quản lý sân khấu, nhân vật, hiệu ứng, luật xử lý sự kiện, nhạc và thống kê.

Mục tiêu lâu dài của dự án là xây dựng một Live Interaction Engine có thể tái sử dụng cho nhiều chủ đề khác nhau như quán bar, lễ hội, sân vận động, phòng game, sân khấu ca nhạc hoặc các sự kiện trực tuyến.

---

2. Phạm vi MVP

Phiên bản đầu tiên chỉ hỗ trợ:

• TikTok Live
• Một phòng livestream
• Một cửa sổ Game Engine
• Một Dashboard quản lý
• Một Scene đang hoạt động

Chưa hỗ trợ:

• Facebook Live
• YouTube Live
• Nhiều phòng cùng lúc
• Multiplayer giữa nhiều streamer

---

3. Kiến trúc hệ thống

Hệ thống gồm bốn thành phần chính:

3.1 TikTok Connector

Chịu trách nhiệm kết nối với TikTok Live và lắng nghe các sự kiện theo thời gian thực.

Các sự kiện bao gồm:

• Người xem vào live
• Bình luận
• Like
• Follow
• Gift
• Kết thúc livestream
• Mất kết nối
• Kết nối lại

---

3.2 Backend

Backend là trung tâm xử lý nghiệp vụ.

Nhiệm vụ:

• Quản lý toàn bộ Player
• Quản lý Scene
• Quản lý Stage
• Quản lý Rule
• Quản lý Music
• Quản lý Effect
• Tính toán Ranking
• Điều phối Game Engine
• Đồng bộ Dashboard

Backend hoàn toàn chịu trách nhiệm tính toán.

Không phụ thuộc vào TikTok để tính:

• BXH Donate
• Top Active
• VIP
• Combo
• Level
• XP

---

3.3 Game Engine

Game Engine chịu trách nhiệm hiển thị.

Bao gồm:

• Render Scene
• Render Sticker
• Render Animation
• Render Effect
• Render Background
• Render UI trong Game

Game Engine không xử lý nghiệp vụ.

Nó chỉ nhận lệnh từ Backend.

Ví dụ

Backend

↓

Player A lên VIP

↓

Game Engine

↓

Animation đi lên sân khấu.

---

3.4 Dashboard

Dashboard dùng để quản lý toàn bộ chương trình.

Dashboard không trực tiếp xử lý Game.

Chỉ gửi lệnh cho Backend.

---

4. Dashboard

Dashboard gồm các module.

---

4.1 Live Connection

Cho phép:

• Kết nối TikTok
• Ngắt kết nối
• Reconnect
• Hiển thị trạng thái

Thông tin:

• Live ID
• Trạng thái
• Ping
• FPS
• Running Time

---

4.2 TikTok Account

Quản lý các tài khoản.

Chức năng:

• Thêm tài khoản
• Xóa tài khoản
• Đổi tài khoản
• Chọn tài khoản livestream
• Lưu cấu hình kết nối

---

4.3 Dashboard

Theo dõi realtime.

Hiển thị:

• Viewer
• Join
• Comment
• Like
• Gift
• Follow
• Active User
• FPS
• CPU
• RAM

Có biểu đồ theo thời gian.

---

4.4 Player Manager

Danh sách toàn bộ người đang trong game.

Thông tin:

• Avatar
• Nickname
• Role
• Zone
• Slot
• Donate
• Level
• XP
• Join Time
• Online Time

Chức năng:

• Move
• Kick
• Highlight
• Mute
• Đổi Skin
• Đưa lên VIP

---

4.5 Rule Manager

Toàn bộ hành động được điều khiển bằng Rule.

Ví dụ:

Comment "hey"

↓

Dance

Gift Rose

↓

Move VIP

Comment "love"

↓

Heart Effect

Like ≥100

↓

Speed Up

Rule có thể:

• Thêm
• Sửa
• Xóa
• Bật/Tắt
• Sắp xếp độ ưu tiên

Rule có thể kết hợp nhiều điều kiện (AND/OR), thời gian chờ (Cooldown), xác suất kích hoạt và chuỗi hành động (Action Chain).

---

4.6 Music Manager

Quản lý Playlist.

Chức năng:

• Play
• Pause
• Stop
• Next
• Previous
• Volume
• Loop
• Shuffle

Hiển thị:

Current Song

Beat

Duration

Có thể đồng bộ BPM với Animation.

---

4.7 Effect Manager

Quản lý:

• Laser
• Smoke
• Firework
• Spotlight
• Confetti
• Flash

Cho phép bật:

• Theo Rule
• Theo Gift
• Theo Dashboard

---

4.8 Stage Editor

Đây là module quan trọng nhất.

Toàn bộ sân khấu được thiết kế bằng kéo thả.

Không cần sửa code.

---

5. Stage System

Stage được chia thành bốn cấp.

Scene

↓

Zone

↓

Row

↓

Slot

---

Scene

Là toàn bộ bản đồ.

Ví dụ:

Night Club

Festival

Beach

Cyberpunk

Halloween

Christmas

Mỗi Scene có:

• Background
• Nhạc
• Hiệu ứng
• Camera
• Spawn Rule

---

Zone

Scene gồm nhiều Zone.

Ví dụ:

Dance Floor

VIP Stage

DJ Booth

Entrance

Exit

Mỗi Zone có:

• Tên
• Layer
• Spawn Rule
• Giới hạn người
• Hiệu ứng riêng
• Camera riêng

---

Row

Mỗi Zone gồm nhiều hàng.

Có thể:

• Thêm hàng
• Xóa hàng
• Đổi vị trí
• Thay đổi khoảng cách
• Scale

Ví dụ:

Dance Floor

Row 1

Row 2

Row 3

---

Slot

Mỗi vị trí đứng là một Slot.

Sticker không đứng tự do.

Sticker luôn đứng trên Slot.

Slot có:

• X
• Y
• Scale
• Rotation
• Layer
• Occupied
• Enabled
• Allowed Roles

Admin có thể kéo Slot bằng chuột.

---

6. Spawn System

Người xem chỉ xuất hiện khi có tương tác đầu tiên (ví dụ comment).

Quy trình:

Comment

↓

Kiểm tra đã tồn tại Player chưa

↓

Nếu chưa

↓

Tạo Player

↓

Xác định Role

↓

Tìm Zone phù hợp

↓

Lấy toàn bộ Slot hợp lệ

↓

Lọc Slot còn trống

↓

Random

↓

Spawn

↓

Animation đi vào

Nếu người xem đã có Player, chỉ thực hiện hành động tương ứng (ví dụ hiển thị bong bóng chat hoặc animation).

---

7. Player System

Mỗi người xem có một Player.

Thông tin:

• User ID
• Nickname
• Avatar
• Sticker
• Animation
• Role
• Zone
• Slot
• Join Time
• Donate Coin
• Gift Count
• XP
• Level
• Energy
• Current Effect

---

8. Role System

Role quyết định nơi người xem được đứng.

Ví dụ:

Viewer

Follower

VIP

Moderator

Admin

Role quyết định:

• Spawn Zone
• Skin
• Hiệu ứng
• Animation
• Quyền ưu tiên

---

9. TikTok Event

Join

Có thể ghi nhận người xem vào thống kê (không nhất thiết tạo Player).

Comment

Nếu chưa có Player:

↓

Spawn

Nếu đã có:

↓

Animation

↓

Bubble Chat

Like

↓

Energy

↓

Combo

Follow

↓

Đổi Skin

↓

Hiệu ứng

Gift

↓

Tính Coin

↓

Cập nhật BXH

↓

Nếu thay đổi hạng

↓

Di chuyển Player

↓

Hiệu ứng

---

10. Donation Ranking

Backend tự tính.

Không phụ thuộc TikTok.

Mỗi Gift:

↓

Tra giá trị Coin

↓

Cộng Coin

↓

Sắp xếp

↓

Tính lại BXH

↓

Xác định Zone

↓

Nếu đổi hạng

↓

Game Engine di chuyển nhân vật

Ví dụ:

Top 1

↓

Center VIP

Top 2–5

↓

VIP Stage

Top 6–20

↓

Premium Zone

Còn lại

↓

Dance Floor

Việc thay đổi vị trí nên đi kèm animation (đi bộ, leo cầu thang, spotlight...) để tạo cảm giác phần thưởng rõ ràng.

---

11. Animation System

Sticker có nhiều trạng thái:

Idle

Walk

Dance

Jump

Celebrate

Wave

Happy

Cry

Sleep

Animation được kích hoạt bởi:

• Rule
• Gift
• Dashboard
• Event

---

12. Skin System

Sticker có thể thay đổi:

• Quần áo
• Mũ
• Kính
• Hiệu ứng
• Danh hiệu

Admin có thể upload:

• PNG
• GIF
• Sprite Sheet

---

13. Music System

Nhạc có thể:

• Đồng bộ BPM
• Đổi theo Scene
• Đổi theo Event
• Đổi theo Dashboard

Có Playlist riêng.

---

14. Effect System

Hiệu ứng:

• Laser
• Smoke
• Firework
• Spotlight
• Confetti
• Flash
• Particle

Có thể kích hoạt:

• Gift
• Rule
• Dashboard
• Event

---

15. Camera System

Camera có thể:

• Zoom
• Shake
• Follow Zone
• Focus VIP
• Auto Camera

Ví dụ:

Galaxy

↓

Camera Zoom

↓

Spotlight

↓

Firework

---

16. Analytics

Theo dõi:

• Viewer
• Join
• Comment
• Like
• Gift
• Donate
• Active User
• Top Donator
• Top Comment

Có biểu đồ theo thời gian thực.

---

17. Logging

Lưu:

• Join
• Leave
• Comment
• Gift
• Follow
• Like
• Error
• Reconnect

---

18. Cấu trúc dự án

text
tiktok-live-show/

backend/
│
├── app.py
├── config.py
├── tiktok.py
├── dashboard.py
├── game.py
├── player.py
├── stage.py
├── ranking.py
├── rules.py
├── music.py
├── effects.py
│
├── assets/
│   ├── stage/
│   ├── stickers/
│   ├── music/
│   ├── effects/
│   └── fonts/
│
├── data/
│   ├── accounts.json
│   ├── layouts/
│   ├── rules.json
│   └── settings.json
│
└── logs/

dashboard/
│
├── src/
└── package.json

---

19. Hướng phát triển

Sau khi hoàn thành MVP, hệ thống có thể mở rộng thêm:

• Hệ thống Level và XP theo nhiều buổi livestream.
• Hồ sơ người chơi lưu trữ lâu dài.
• Pet đi theo nhân vật.
• Kho vật phẩm và skin.
• Mini game theo sự kiện.
• Boss cộng đồng.
• Nhiều Scene và Theme khác nhau.
• Plugin để mở rộng Rule và Effect.
• AI NPC (DJ, bảo vệ, dancer...) tương tác với người xem.
• Chế độ sự kiện theo thời gian (Countdown, Happy Hour, Lucky Draw).
• Hệ thống nhiệm vụ và thành tựu.
• Đồng bộ dữ liệu giữa nhiều máy hoặc nhiều streamer trong tương lai.

---

20. Mục tiêu cuối cùng

Xây dựng một Interactive Live Engine dành riêng cho TikTok, nơi mọi tương tác của người xem đều được chuyển thành hành động trong một thế giới ảo theo thời gian thực.

Điểm cốt lõi của hệ thống là mọi thứ đều có thể cấu hình (Scene, Zone, Slot, Rule, Effect, Music, Ranking...) thông qua Dashboard và Stage Editor mà không cần sửa mã nguồn. Điều này giúp streamer dễ dàng tạo nhiều loại sân khấu và trải nghiệm khác nhau chỉ bằng cách thay đổi cấu hình, đồng thời tạo nền tảng để mở rộng thành một nền tảng tương tác livestream chuyên nghiệp trong tương lai.
tôi đang có hướng như này, cho tôi bản tài liệu đầy đủ, và tôi muốn thêm phần quản lý các sticker có hoạt ảnh nữa, nếu được thì cho thêm code của từng file