Theme server blueprint · cập nhật 27.10.2026

Một ID. Đổi cả game.

Theme gồm khối, board, UI, animation, FX, sound và haptic. Mỗi người chơi có kho theme riêng theo nguồn tải và công thức mở. Theme hiện tại, theme bắt đầu và theme kế tiếp (khi thanh tiến độ đạt 25/25) đều điều khiển bằng Remote Config (RC). Mỗi theme có version riêng.

255sprite ID hiện tại

280skin đã có metadata

25mốc đổi theme (hard-code)

7RC key mới cho kho/tiến độ

01 / LUỒNG

Từ lúc mở app tới theme kế tiếp

Trái: khởi động, chọn theme bắt đầu và tải an toàn. Phải: trong chế độ Cơ bản, kho theme nhận theme theo nguồn; khi đạt 25/25 thì chọn theme kế. Ô vàng là điểm quyết định, ô đỏ là đường lỗi/fallback.

Bước xử lýQuyết địnhLỗi / fallbackKết quả trên mànRC key điều khiển

Nguyên tắc

Không đổi asset giữa ván. Theme chưa tải đủ asset không được chọn làm theme kế. Không tải code thực thi (shader, script) từ server. Không A/B bucket ở giai đoạn này.

02 / MỘT THEME

Toàn bộ trường cần cho 1 theme

Một theme là một object trong catalog.themes.<theme_id>. Bên trái là khung JSON đầy đủ. Các tab bên dưới giải thích từng trường, kể cả trường nhỏ bên trong activation, asset entry và skin khối. Danh sách key đầy đủ trong assets/tokens nằm ở mục 03.

Khung JSON của 1 theme

"ocean": {
  "version": 2,
  "skin_id": 4003,
  "ui_scope": "full",
  "fallback_theme_id": "default",
  "min_app_version": "1.4.0",
  "activation": {
    "enabled": true,
    "priority": 10,
    "start_at": "2027-10-25",
    "end_at": "2027-11-02",
    "min_level": 5,
    "max_level": 0,
    "creative_ids": ["ocean_ad"]
  },
  "skin": {
    "family": "ocean",
    "icons": ["b1.png","b2.png"],
    "matchColors": [["#3FA9F5","#A8DCFF","#1B5E8C"]],
    "colorPool": [1,2,3,4,5,6,7],
    "putAudioKey": "s_put",
    "clearSfxKey": "",
    "bgmName": "",
    "bgColor": "#0F3550"
  },
  "tokens": {
    "color.background.ingame": "#0F3550",
    "font_scale.ui": 1.0
  },
  "assets": {
    "home.background": {
      "path": "ocean/v2/home/bg.webp",
      "type": "image",
      "sha256": "64 ký tự hex",
      "size_bytes": 182340,
      "atlas_path": "",
      "frame": "",
      "preload": "boot"
    }
  }
}

Đọc khung này thế nào

Cấp theme: version, skin_id, ui_scope, fallback, min_app_version. Quy định theme đổi tới đâu và dự phòng ra sao.
activation: khi nào theme tự bật (ngày, level, creative quảng cáo).
Skin khối: skin_id trỏ tới bộ khối (tối đa 7 màu, thiếu màu nào dùng mặc định), màu hiệu ứng, âm thanh và nhạc riêng. Đây là phần đổi khi thanh đạt 25/25. Trên server khối skin nằm trong catalog skin, theme chỉ trỏ tới bằng skin_id; viết gộp ở đây cho dễ nhìn.
tokens: màu, font, scale, âm lượng (key ở mục 03, tab Design tokens).
assets: mỗi Asset ID ở mục 03 ứng với một asset entry. Theme khác default chỉ cần khai ID muốn đổi.

Giải thích từng trường

03 / INVENTORY

Danh mục asset ID theo từng tab

Đây là toàn bộ key nằm trong assets và tokens của một theme (tab Design tokens thuộc tokens, còn lại thuộc assets; tab Theme khối thuộc catalog skin). Cột Thấy ở đâu trong game nói bằng lời thường ID đó vẽ/phát cái gì. Mỗi tab khớp một mục 5.x trong PLAN. Cột Type hiện tại là định dạng game đang dùng thật (đo từ game/Content và game/Source). Cột Ghi chú nêu type đề xuất cho server nếu khác. Lưới ảnh trên mỗi bảng là sprite hiện tại mà ID thay thế. Chỉ gồm 6 màn/popup đang có trong port: Home (Cơ bản), Nâng cao chọn cấp, Ingame Cơ bản, Ingame Nâng cao, popup Ngôn ngữ, popup Cài Đặt+.

Không bỏ sót

Ngoài ID semantic, cả 255 tên trong layout/_sprites.json tự import thành legacy.sprite.<name>. Mọi key trong config/audio.json tự import thành legacy.audio.<key>. Theme chỉ cần override ID muốn đổi; ID còn lại fallback về default.

04 / FIELDS

Từng field làm gì, ví dụ ra sao

RC (Remote Config) là cấu hình trên Firebase, đổi được không cần phát hành app. Mỗi tab là một nhóm key. Field bên trong một theme (catalog) đã giải thích ở mục 02. Tab cuối là dữ liệu người chơi lưu trên máy (kho + tiến độ).

05 / DELIVERY

9 task, một đường rollback

Tách core schema, store, resolver, từng consumer, kho theme và QA để review độc lập. Task 9 mới thêm cho kho/tiến độ/version. Adventure gameplay per-level giữ TBD.

TASK 1

Schema + validator

C++ thuần. ID, URL, hash, fallback cycle, activation, ui_scope, skin_id.

TASK 2

Store + LKG

Staging, activate nguyên tử, quota, offline, rollback.

TASK 3

Resolver + aliases

Semantic ID, 255 sprite alias, toàn bộ audio alias.

TASK 4

RC + deeplink

Chọn theme theo rule/creative, áp ở ranh giới màn.

TASK 5

UI toàn app

Home (Cơ bản), Nâng cao (chọn cấp + ingame), popup Ngôn ngữ, popup Cài Đặt+.

TASK 6

Ingame đầy đủ

Block, board, animation, sound, haptic, pet. FX độc lập theme đọc RC fx_*.

TASK 7

Publish tooling

Validate, pack, hash, diff, path bất biến <theme>/v<N>/.

TASK 8

QA + rollback

Trước/sau, offline, file hỏng, LKG, crash context.

TASK 9 · MỚI

Kho + tiến độ + version

Kho theo người chơi, grant theo nguồn, công thức mở, theme bắt đầu, theme kế khi 25/25, UI theo theme, version riêng.

TASK 1 ├── TASK 2 ──┐ ├── TASK 3 ──┼── TASK 4 ──┬── TASK 9 ──┐ │ ├── TASK 5 ──┼────────────┤ │ └── TASK 6 ──┴────────────┼── TASK 8 └── TASK 7 ────────────────────────────┘

TBD

Adventure nâng cao: target, layout, difficulty, mission, theme riêng từng level từ server. Bổ sung sau, không chặn theme UI toàn app.