Theme là lớp sự kiện. Skin đổi ván chơi.

Trong themes.json (backend)

{
  "id": "halloween",
  "bundle": { "url": "themes/halloween_a1b2c3d4.zip", "sha256": "64 ký tự hex", "size": 1823112 },
  "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": ["halloween_ad"]
  },
  "audio": { "home": "bgm_halloween" },
  "tokens": {
    "ui.text.title": "#FFB347",
    "ui.text.item": "#FFFFFF",
    "color.text.accent": "#FF7A00",
    "logo.loopDurationMs": 2000,
    "logo.loopDelayMs": 3000,
    "ghost.intervalMs": 15000,
    "ghost.durationMs": 4000,
    "ghost.path": "left_to_right",
    "ghost.layer": "above_background",
    "adventure_button.intervalMs": 5000,
    "adventure_button.pressDepth": 0.08,
    "adventure_button.durationMs": 300,
    "button_tap.maxConcurrent": 3,
    "button_tap.cooldownMs": 300,
    "button_tap.particleCount": 5,
    "button_tap.lifetimeMs": 1200,
    "button_tap.spawnAnchor": "tap_point"
  }
}

Gốc themes.json: map audio dùng chung

{
  "themes": [ /* các theme như trên */ ],
  "audio": {
    "bgm_halloween": { "url": "audio/bgm_halloween_9f8e7d6c.ogg", "sha256": "64-hex", "size": 812345 }
  }
}

Một skin (catalog skin riêng, không nằm trong theme)

{
  "id": 4042,
  "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",
  "lineClearSfxKey": "marble_streak",
  "bgmName": "bgm_spring",
  "bgColor": "",
  "bundle": {
    "url": "skins/Remote_Skin_Material_4042.zip",
    "sha256": "64-hex",
    "size": 812345
  }
}

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

• Cấp theme (themes.json): id, bundle, min_app_version, audio, tokens. Không có version; định danh bản là bundle.sha256 (DEC-254). Theme không có trường skin; đổi theme không đổi khối.
• activation: theme sự kiện (lớp 4): ngày, level, creative quảng cáo; xét ở mọi ranh giới, không ghi vào theme riêng của người chơi. Theme riêng đổi do RC theme_switch_rules (mục 05).
• 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.
• tokens (trong theme, DEC-254): màu chữ, chu kỳ anim, giới hạn FX (tab tokens). Token sai bị bỏ, dùng mặc định; theme vẫn bật.
• audio.home: key nhạc Home trong map audio ở gốc themes.json, không nằm trong zip.
• File ảnh/Spine: nằm trong zip theo tên cố định (mục 03). Thiếu file nào thì slot đó giữ art gốc.

Zip theme · themes/halloween_a1b2c3d4.zip

halloween/
├── home/
│   ├── logo.png
│   ├── logo_anim.json
│   ├── logo_anim.atlas
│   ├── logo_anim.png
│   ├── ghost.json
│   ├── ghost.atlas
│   └── ghost.png
├── fx/
│   ├── button_tap.json
│   ├── button_tap.atlas
│   └── button_tap.png
└── settings/
    ├── popup_bg.png
    ├── popup_inner.png
    ├── popup_ornament.png
    ├── close.png
    ├── toggle_sound_on.png
    ├── toggle_sound_on_press.png
    ├── toggle_sound_off.png
    ├── toggle_sound_off_press.png
    ├── toggle_bgm_on.png
    ├── toggle_bgm_on_press.png
    ├── toggle_bgm_off.png
    ├── toggle_bgm_off_press.png
    ├── toggle_vibration_on.png
    ├── toggle_vibration_on_press.png
    ├── toggle_vibration_off.png
    └── toggle_vibration_off_press.png

Không có trong zip:
  nhạc Home   → themes.json: audio.home + map audio
  màu, chu kỳ → themes.json: tokens
  nút Nâng cao lún (EA-05) → tween, chỉ cần tokens

Zip skin · skins/Remote_Skin_Material_1022.zip

1022/
├── block/
│   ├── cube_1.png
│   ├── cube_2.png
│   ├── cube_3.png
│   ├── cube_4.png
│   ├── cube_5.png
│   ├── cube_6.png
│   └── cube_7.png
├── shadow.png
├── bg.png
├── board.png
├── crown.png
└── effects/
    ├── gameplay_eliminate_022.json
    ├── gameplay_eliminate_022.atlas
    ├── gameplay_eliminate_022.png
    ├── gameplay_ready_eliminate_022.json
    ├── gameplay_ready_eliminate_022.atlas
    └── gameplay_ready_eliminate_022.png

022 = 3 số cuối của id skin, đệm 0 (skin 4042 → 042).

Không có trong zip:
  putAudioKey, lineClearSfxKey, bgmName → key trong map audio của skins.json
  matchColors, colorPool → skins.json

Đếm thật trên 46 zip mẫu:
  cube_1..7 46/46 · shadow 46 · bg, board 44
  crown 32 · eliminate 24 · ready_eliminate 7