Theme đổi giao diện. Skin đổi khối.
Theme là bộ giao diện toàn app (nền, nút, HUD, popup, font, nhạc, rung); skin là bộ hình khối, màu ăn hàng và tiếng đặt/ăn. Hai thứ độc lập, mỗi người chơi có kho theme và kho skin riêng, bắt đầu mặc định hoặc theo nguồn cài. Theme đổi theo luật Remote Config (RC) gồm input + công thức; skin đổi khi thanh tiến độ đầy. Một số skin có trường theme_link để đổi hoặc cấp theme. Mỗi theme có version riêng.
Đọc trước để không hiểu nhầm
Theme và skin là hai thứ độc lập, mỗi thứ có kho riêng của từng người chơi. Bảng dưới định nghĩa các từ dùng trong trang này; cột cuối ghi điều hay bị hiểu nhầm.
| Thuật ngữ | Nghĩa | Không phải là |
|---|---|---|
| Theme | Bộ giao diện toàn app: nền, logo, nút, HUD, popup, font, màu, nhạc nền, âm UI, rung. Định danh bằng theme_id (vd default, ocean). | Không đổi hình khối. Đổi theme không làm đổi skin. |
| Skin (skin khối) | Bộ hình 7 khối, màu ăn hàng, tiếng đặt/ăn, FX ăn hàng riêng. Định danh bằng skin_id số (vd 1000, 4003). | Không đổi nền/nút/popup, trừ skin có theme_link. |
| Gói skin | Zip riêng của một skin (Remote_Skin_Material_<id>.zip): 7 ảnh khối + FX ăn hàng riêng. bundle{url,sha256,size} gắn thẳng vào skin. | Không phải theme. Thay trường family trong code (plan bỏ). |
| RC (Remote Config) | Bảng key/giá trị Firebase gửi xuống app: cờ, ID, URL, luật. Sửa trên Firebase, không cần phát hành app. | Không chứa từng đường dẫn ảnh. |
| Catalog | File JSON trên CDN: danh sách theme, version, Asset ID → file. | Không phải RC. |
| Asset ID | Tên ổn định của một chỗ hiển thị, vd home.button.play. | Không phải tên file. |
| Asset entry | Một dòng catalog: Asset ID → type, path, sha256, preload. | — |
| Token | Giá trị không phải file: màu, cỡ chữ, scale (tokens.*). | — |
| Kho (theme / skin) | Danh sách theme hoặc skin một người chơi đã có, lưu trong save trên máy. | Không phải pool chung của server. |
| Pool | Toàn bộ theme/skin server cho phép. | Không phải kho người chơi. |
| Rule (luật RC) | Điều kiện server cấu hình: input + công thức + cách chọn kết quả (pick). | Không phải code app. |
| Input | Biến app tự đếm đưa vào công thức: games_played, days_since_install, skin_id... | — |
| Công thức | Biểu thức như games_played >= 10 && games_played % 5 == 0, chạy bằng bộ đánh giá an toàn trong game/core/. | Không phải script tuỳ ý. |
| theme_link | Trường tuỳ chọn của một số skin: dùng skin đó thì đổi hoặc cấp một theme. | Không có ở mọi skin. |
| Fallback / LKG | Thiếu asset hoặc theme lỗi thì lấy bản đã tải đủ gần nhất (LKG), rồi tới default đóng gói. | — |
| Creative / deeplink | Mã quảng cáo / đường link người chơi bấm để cài hay mở app; dùng chọn theme và skin bắt đầu. | — |
| Resolver | ThemeService/AssetResolver: đổi Asset ID thành file thật theo theme hiện tại. | — |
| Ranh giới màn/ván | Lúc mở màn mới hoặc bắt đầu ván mới. Theme chỉ đổi tại đây; phiên bản tài nguyên mới tải (theme hoặc skin) chỉ kích hoạt tại đây. | Không áp cho đổi skin đã sẵn tài nguyên: skin được đổi trong ván. |
| Điểm an toàn trong ván | Sau khi lượt đặt khối xử lý xong (ăn hàng, điểm, FX của lượt), không có khối đang kéo. | — |
| Tiến độ đổi skin | Cộng số hàng + cột bị xoá mỗi lượt; đủ ngưỡng (mặc định 25) thì đổi skin kế, giữ phần dư. | Không phải số lượt, số ô, hay thanh hệ số điểm. |
Theme đổi
- Nền Home, nền Ingame, nền Adventure
- Logo, nút Play / Cơ bản / Nâng cao, icon nút
- Khung board, ô trống, HUD (điểm, số, nút cài đặt)
- Popup Ngôn ngữ, Cài Đặt+, Revive, Settlement
- Font, màu chữ, token màu/scale
- Nhạc nền, âm UI (bấm nút, mở popup), âm mở bàn
audio.game.start, âm xoá hàngaudio.block.clear, bảng rung
Skin đổi
- 7 hình khối trên board và khay
- Màu ăn hàng (
matchColors), danh sách màu sinh khối (colorPool, giữ nguyên list) - Tiếng đặt khối (
putAudioKey), tiếng dọn sạch bàn (allClearSfxKey, gốcClearSfxKey) - FX ăn hàng riêng của skin (trong gói của skin)
bgmName,bgColor: chỉ ghi đè theme khi khác rỗng- Thanh tiến độ (số hàng/cột xoá, mặc định 25) dẫn tới skin kế
- Một số skin:
theme_linkđổi/cấp theme
Không thuộc cả hai (RC fx_*)
- FX chung: combo, ăn nhiều hàng, rung màn, chữ khen
- Hệ số tốc độ, thời lượng FX
- Bật/tắt từng FX chung
ocean + skin 4003. Thanh tiến độ đầy, đổi sang skin 4010: khối và tiếng ăn đổi, nền và nút Play vẫn là ocean. Server bật luật đổi theme sang candy: nền và nút đổi, khối vẫn là 4010.Từ lúc mở app tới đổi theme, đổi skin
Trái: khởi động, chọn theme bắt đầu và tải an toàn. Phải trên: kho theme nhận theme theo nguồn; ở mỗi ranh giới màn/ván, luật RC (input + công thức) quyết định có đổi theme. Phải dưới: kho skin riêng; thanh tiến độ đầy thì đổi skin, theme không đổi, trừ skin có theme_link. Ô vàng là điểm quyết định, ô đỏ là đường lỗi/fallback, ô viền đứt là key RC.
Hai luật thời điểm: (1) phiên bản tài nguyên mới tải (theme hoặc skin) chỉ kích hoạt ở ranh giới màn/ván; (2) đổi sang skin đã sẵn tài nguyên được làm giữa ván, tại điểm an toàn sau lượt, không đổi hình khối đang kéo. Theme chỉ đổi ở ranh giới. Theme chưa tải đủ asset không được luật RC chọn; skin chưa tải đủ gói của nó không được chọn làm skin kế. Không tải code thực thi (shader, script) từ server. Không A/B bucket ở giai đoạn này.
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 (skin thuộc catalog riêng, viết ở đây để tra cùng chỗ). Danh sách key đầy đủ trong assets/tokens nằm ở mục 03.
Khung JSON của 1 theme
"ocean": {
"version": 2,
"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"]
},
"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"
}
}
}Một skin (catalog skin riêng, không nằm trong theme)
{
"id": 4042,
"icons": ["cube_1.png","cube_2.png","cube_3.png","cube_4.png",
"cube_5.png","cube_6.png","cube_7.png"],
"matchColors": [
["#F2ECE5","#A279A9","#3C253E"], ["#F5F8FA","#7C8BCC","#333565"],
["#F2ECE5","#A279A9","#3C253E"], ["#F5F8FA","#7C8BCC","#333565"],
["#F2ECE5","#A279A9","#3C253E"], ["#F5F8FA","#7C8BCC","#333565"],
["#F2ECE5","#A279A9","#3C253E"]
],
"colorPool": [1,2],
"putAudioKey": "s_put",
"allClearSfxKey": "",
"bgmName": "bgm_spring",
"bgColor": "",
"bundle": {
"url": "skins/Remote_Skin_Material_4042.zip",
"sha256": "64-hex",
"size": 812345
},
"theme_link": {
"theme_id": "ocean",
"mode": "while_active"
}
}Đọc khung này thế nào
- Cấp theme: version, fallback, min_app_version. Theme không có trường skin; đổi theme không đổi khối.
- activation: khi nào theme được bật lúc mở app (ngày, level, creative quảng cáo). Đổi theme trong lúc chơi do RC
theme_switch_rules(mục 04). - Skin khối: nằm ở catalog skin riêng (khung thứ hai). 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, nhạc riêng. Đổi khi thanh tiến độ đầy. Trường tuỳ chọn
theme_linkchỉ có ở một số skin. - 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
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+.
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.
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 độ).
10 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 cho kho theme + luật RC; Task 10 mới cho kho skin + theme_link. Adventure gameplay per-level giữ TBD.
Schema + validator
C++ thuần. ID, URL, hash, fallback cycle, activation, luật theme_switch_rules sai bị bỏ qua. Skin: bundle bắt buộc, validator colorPool list.
Store + LKG
Staging, activate nguyên tử, quota, offline, rollback.
Resolver + aliases
Semantic ID, 255 sprite alias, toàn bộ audio alias.
RC + deeplink
Chọn theme theo rule/creative, áp ở ranh giới màn.
UI toàn app
Home (Cơ bản), Nâng cao (chọn cấp + ingame), popup Ngôn ngữ, popup Cài Đặt+.
Ingame đầy đủ
Block, board, animation, sound, haptic, pet. FX độc lập theme đọc RC fx_*. Âm mở bàn audio.game.start, bảng sự kiện âm thanh, allClearSfxKey nối vào dọn sạch bàn.
Publish tooling
Validate, pack, hash, diff, path bất biến <theme>/v<N>/.
QA + rollback
Trước/sau, offline, file hỏng, LKG, crash context. Case skin: 24 + 2 hàng còn 1, khối đang kéo không đổi, pool qua resume, âm all-clear/mở bàn.
Kho theme + luật RC
Kho theme theo người chơi, grant theo nguồn, theme bắt đầu, bộ đánh giá công thức trong core, theme_switch_rules, version riêng. Không đụng skin.
Kho skin + theme_link
Kho skin theo người chơi, skin độc lập (bỏ family, thêm bundle), colorPool giữ list, skin bắt đầu theo nguồn, skin_progress_target (số hàng/cột) thay 25 hard-code, đổi skin giữa ván ở điểm an toàn, skin_next_rule, trường theme_link.
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.