Sugar Rush — tài liệu ghép client

Slot cluster / tumble 7×7. Sticky multiplier trong free spins. Có buy FS và buy Super FS. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Luồng ghép

1. Mở game → GET /api/v1/gameplay. Render board, bet, paytable, money, sticky nếu đang FS.
2. User chọn bet chỉ khi is_free_spin = false.
3. Spin thường → POST /api/v1/spins body {"bet": ...}.
4. Play tuần tự từng phần tử win_result[] (tumble). Highlight cluster theo positions.
5. Nếu is_bonus_free_spin → popup +N FS, chuyển UI free-spin. Hiện sticky theo multipliers.
6. Khi is_free_spin: không trừ bet, tiếp tục POST /spins tới is_finish_free_spin.
7. Buy → POST /buy-freespins hoặc POST /buy-super-freespins (cấm khi đang FS).
8. Luôn lấy số dư từ user_money của response vừa nhận.

3. Auth & envelope

Header

Authorization: Bearer <access_token>
Content-Type: application/json

Mọi API dưới /api/v1 đều cần JWT. Trang docs không cần token.

Envelope

HTTP 200 + code = 0 là thành công. Payload nằm trong msg.

{
  "code": 0,
  "msg": { ... }
}

4. Grid & symbol

Mọi board (init_reels, win_result[].reels, cheat reels) đều là mảng cột:

reels[col][row]          // col 0..6 trái → phải; row 0..6 trên → dưới
multipliers[col][row]    // sticky count; display = 2^(count-1) khi count ≥ 1

Hàng đầu = row 0. Ô vàng viền = cluster Lollipop (0) thắng. Ô scatter (7) góc trên phải.

Luôn dùng pay_table từ /gameplay. Line win = round(bet × multiplier × bonus_multiplier). bonus_multiplier lấy từ sticky trên các ô của cluster.

5. GET /api/v1/gameplay

Gọi 1 lần khi vào game. Thiếu bước này thì POST /spins trả code 69.

GET /api/v1/gameplay

{
  "code": 0,
  "msg": {
    "init_reels": [[6,1,2,3,4,5,6],[1,0,0,2,3,4,5],[2,0,0,0,1,2,3],[3,4,5,6,1,2,3],[4,5,6,1,2,3,4],[5,6,1,2,3,4,5],[7,1,2,3,4,5,6]],
    "user_money": 500000,
    "bet": 1000,
    "bets": [200, 1000, 2000, 10000],
    "show_bets": [200, 1000, 2000, 10000],
    "pay_table": [[50,20,10],[25,10,5],[15,8,4],[10,5,2],[8,3,1.5],[5,2,1],[3,1.5,0.8]],
    "is_free_spin": false,
    "free_spins": 0,
    "max_free_spins": 0,
    "free_spin_pot": 0,
    "free_spin_type": 0,
    "multipliers": [[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0]],
    "buy_free_spins_price": 100,
    "buy_super_free_spins_price": 200
  }
}

6. POST /api/v1/spins

POST /api/v1/spins
{ "bet": 1000 }

• Phải gọi /gameplay trước.
• Base: trừ bet ngay. FS: không trừ, vẫn gửi bet (server bỏ qua đổi bet).
• reels chỉ dùng cheat non-prod.

SpinResult

WinResult / WinLine

{
  "code": 0,
  "msg": {
    "bet": 1000, "price": 0, "user_money": 509000, "win_amount": 10000,
    "is_free_spin": false, "free_spins": 10, "free_spin_pot": 0,
    "is_finish_free_spin": false, "is_bonus_free_spin": true,
    "number_of_bonus_free_spins": 10, "free_spin_type": 1, "max_free_spins": 10,
    "win_result": [{
      "lines": [{ "symbol": 0, "positions": [[1,2],[1,2],[1,2],[],[],[],[]], "win_amount": 10000, "line_size": 5, "multiplier": 10, "bonus_multiplier": 1 }],
      "reels": [[6,1,2,3,4,5,6],[1,0,0,2,3,4,5],[2,0,0,0,1,2,3],[3,4,5,6,1,2,3],[4,5,6,1,2,3,4],[5,6,1,2,3,4,5],[7,7,7,3,4,5,6]],
      "win_amount": 10000, "total_win_amount": 10000,
      "multipliers": [[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0],[0,0,0,0,0,0,0]],
      "positions": [[1,2],[1,2],[1,2],[],[],[],[]]
    }]
  }
}

7. POST /buy-freespins & /buy-super-freespins

POST /api/v1/buy-freespins
{ "bet": 1000 }

POST /api/v1/buy-super-freespins
{ "bet": 1000 }

• Giá FS = buy_free_spins_price × bet. Super = buy_super_free_spins_price × bet.
• Cấm khi đang FS → popup code 1000.
• Response cùng shape SpinResult: price = chip đã trừ, guaranteed scatter trigger FS.
• Super: mọi ô seed sticky count = 2 → display ×2 ngay từ đầu.

{
  "code": 0,
  "msg": {
    "bet": 1000, "price": 200000, "user_money": 300000, "win_amount": 0,
    "is_free_spin": false, "free_spins": 10, "free_spin_pot": 0,
    "is_finish_free_spin": false, "is_bonus_free_spin": true,
    "number_of_bonus_free_spins": 10, "free_spin_type": 2, "max_free_spins": 10,
    "win_result": []
  }
}

8. Tumble / sticky / animation

1. Với mỗi win_result[i]: vẽ reels + overlay sticky từ multipliers.
2. Nếu lines.length > 0: highlight cluster, cộng win_amount vào counter.
3. Xóa ô thắng. Gravity theo cột (row lớn = dưới). Fill từ trên (row 0).
4. Board mới = win_result[i+1].reels. Đừng tự random.
5. Phần tử cuối thường lines = []: hết tumble.
6. Sticky display = 2^(count-1). Count 1 → ×1, count 2 → ×2, count 3 → ×4, count 4 → ×8…

9. Free spins

• Spin trigger không set is_free_spin. Win spin đó credit ngay.
• Các spin FS: không trừ bet. Win cộng free_spin_pot, chưa cộng chip tới spin cuối.
• Spin cuối: is_finish_free_spin = true, win_amount = cả pot, user_money đã cộng pot.
• Giữa FS: disable đổi bet và cả hai nút buy.

10. Cheat (chỉ non-prod / cheater)

{
  "bet": 1000,
  "reels": [
    [0,0,1,2,3,4,5],[0,0,0,1,2,3,4],[0,0,0,6,1,2,3],
    [4,5,6,1,2,3,4],[5,6,1,2,3,4,5],[6,1,2,3,4,5,6],[7,7,7,1,2,3,4]
  ]
}

Đủ 7 cột, mỗi cột 7 hàng. Production: field bị bỏ qua, luôn random.

11. Error & tiền

12. Checklist client

• Vào game: GET /gameplay trước mọi spin.
• Board luôn [col][row], 7×7, row 0 = top.
• Play tuần tự win_result; tumble gravity; đừng tự gen symbol.
• Sticky overlay = 2^(multipliers[col][row]-1).
• Bet chỉ gửi giá trị trong bets.
• Giá buy = price field × bet. Super seed ×2 mọi ô.
• FS: khóa bet/buy; tin free_spins; credit chip chỉ khi is_finish_free_spin.
• Restore: nếu /gameplay trả is_free_spin, nhảy thẳng FS UI kèm sticky.
• Không gọi song song 2 spin cho 1 user.