Zeus — tài liệu ghép client

Slot 6×5 pay-anywhere / tumble (Gates of Olympus style). Client nói HTTP JSON với server game. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Luồng ghép

1. Mở game → gửi GET /api/v1/gameplay với JWT. Render board preview, bet, paytable, money, FS state nếu đang giữa feature.
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). Xem mục 8.
5. Sau tumble, apply multiplier nếu applied_multiplier > 1.
6. Nếu is_bonus_free_spin → popup +N FS, chuyển UI sang free-spin mode.
7. Khi is_free_spin trên response spin: không trừ bet, tiếp tục POST /spins cho tới khi is_finish_free_spin.
8. Buy bonus → POST /api/v1/buy-freespins (không được gọi khi đang FS).
9. Luôn lấy số dư mới 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": { ... }
}

Lỗi nghiệp vụ thường trả HTTP 500, JWT sai/thiếu trả HTTP 401. Client luôn đọc field code.

4. Grid & symbol

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

reels[col][row]     // col 0..5 trái → phải; row 0..4 trên → dưới
orb_values[col][row] // cùng index; >0 chỉ khi symbol == 10 (multiplier)

Hàng đầu = row 0. Ô vàng = scatter (9). Ô xanh = multiplier orb (10).

Paytable

pay_table[symbol][band] là hệ số × bet. Band theo số lượng symbol:

Default: Crown [10, 25, 50] … Blue gem [0.25, 0.75, 2]. Luôn dùng pay_table từ /gameplay, đừng hardcode.

Công thức 1 line: win_amount = round(bet × multiplier). Tổng base win = cộng mọi line trên mọi tumble. Orbs nhân sau khi tumble xong.

5. GET /api/v1/gameplay

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

GET /api/v1/gameplay

{
  "code": 0,
  "msg": {
    "init_reels": [[8,7,6,5,4],[3,2,1,0,8],[7,6,5,4,3],[2,1,0,8,7],[6,5,4,3,2],[1,0,8,7,6]],
    "init_orb_values": [[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]],
    "user_money": 500000,
    "bet": 1000,
    "bets": [200, 1000, 2000, 10000],
    "show_bets": [200, 1000, 2000, 10000],
    "pay_table": [[10,25,50],[2.5,10,25],[2,5,15],[1.5,4,12],[1,1.5,10],[0.8,1.2,8],[0.5,1,5],[0.4,0.9,4],[0.25,0.75,2]],
    "is_free_spin": false,
    "free_spins": 0,
    "max_free_spins": 0,
    "free_spin_pot": 0,
    "total_multiplier": 0,
    "buy_free_spins_price": 100,
    "max_win_multiplier": 5000
  }
}

6. POST /api/v1/spins

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

• Phải gọi /gameplay trước.
• Base: trừ bet chip ngay. FS: không trừ, bet vẫn gửi (server bỏ qua đổi bet).
• Không đổi bet khi đang FS.
• reels / orb_values chỉ dùng cheat (mục 11). Production bỏ qua.

SpinResult

WinResult (một bước tumble)

WinLine

{
  "code": 0,
  "msg": {
    "bet": 1000,
    "price": 0,
    "is_buy": false,
    "user_money": 509000,
    "win_amount": 10000,
    "base_win_amount": 10000,
    "collected_multiplier": 0,
    "applied_multiplier": 0,
    "total_multiplier": 0,
    "win_tier": 0,
    "hit_max_win": false,
    "is_free_spin": false,
    "free_spins": 15,
    "free_spin_pot": 0,
    "is_finish_free_spin": false,
    "is_bonus_free_spin": true,
    "number_of_bonus_free_spins": 15,
    "max_free_spins": 15,
    "scatter_count": 4,
    "win_result": [
      {
        "lines": [{ "symbol": 0, "positions": [[0,1],[0],[0],[],[],[]], "win_amount": 10000, "line_size": 8, "multiplier": 10 }],
        "reels": [[0,0,1,7,6],[0,0,2,1,7],[0,0,3,2,1],[0,1,4,3,2],[4,6,5,4,3],[5,7,6,5,4]],
        "orb_values": [[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]],
        "orbs": [],
        "win_amount": 10000,
        "total_win_amount": 10000,
        "positions": [[0,1],[0],[0],[0],[],[]]
      }
    ]
  }
}

Sau bước có lines, phần tử tiếp theo trong mảng là board đã tumble. Phần tử cuối thường lines: [].

7. POST /api/v1/buy-freespins

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

• Giá = buy_free_spins_price × bet. Trừ ngay với reason buy.
• Cấm khi đang FS → popup code 1000.
• Response cùng shape SpinResult: is_buy = true, price = số chip đã trừ, guaranteed scatter trigger FS.
• Play animation giống một spin (có win_result), rồi vào FS mode.

8. Tumble / animation

1. Với mỗi win_result[i]: vẽ reels + orb_values.
2. Nếu lines.length > 0: highlight positions / từng line, cộng win_amount vào counter base win.
3. Xóa các ô thắng. Symbol còn lại rơi xuống (gravity theo cột, row lớn = dưới). Ô trống fill từ trên (row 0).
4. Board mới = win_result[i+1].reels. Đừng tự random — tin server.
5. Phần tử cuối thường lines = []: hết tumble. Đây là board để tính orb.
6. Nếu applied_multiplier > 1: animation nhân base_win_amount × applied_multiplier → win_amount.
7. Cập nhật money / FS UI từ field top-level, không suy ra từ tumble.

9. Multiplier orbs

Symbol 10. Value hợp lệ: 2, 3, 4, 5, 6, 8, 10, 12, 15, 20, 25, 50, 100, 250, 500. Hiển thị số trên orb, lấy từ orb_values[col][row] hoặc orbs[].value.

applied_multiplier ≤ 1 nghĩa là không nhân (giữ nguyên base win). Client chỉ play anim nhân khi > 1.

final_win = base_win                    // applied ≤ 1
final_win = base_win * applied_multiplier  // applied > 1

10. Free spins

• Spin trigger (base/buy) không set is_free_spin. Win spin đó credit ngay. Sau đó UI vào FS với free_spins.
• Các spin FS: is_free_spin = true, không trừ bet. Win cộng vào free_spin_pot, chưa cộng chip cho tới spin cuối.
• Spin cuối: is_finish_free_spin = true, win_amount = toàn bộ pot, user_money đã cộng pot, free_spin_pot = 0, total_multiplier = 0.
• hit_max_win: kết thúc FS ngay, credit cap, bỏ lượt còn lại.
• Giữa FS: disable đổi bet và nút buy. Vẫn POST /spins với bet hiện tại.

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

Trên môi trường không phải production, POST /spins nhận board cố định:

{
  "bet": 1000,
  "reels": [
    [0, 0, 1, 7, 6],
    [0, 0, 2, 1, 7],
    [0, 0, 3, 2, 1],
    [0, 1, 4, 3, 2],
    [4, 6, 5, 4, 3],
    [9, 9, 9, 9, 10]
  ],
  "orb_values": [
    [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,25]
  ]
}

• Đủ 6 cột, mỗi cột 5 hàng. Symbol 10 phải có orb_values > 0 (không gửi thì server gán 2).
• Production: field này bị bỏ qua, luôn random.

12. Error & tiền

Khi nào chip đổi

13. Checklist client

• Vào game: GET /gameplay trước mọi spin.
• Board luôn [col][row], 6×5, row 0 = top.
• Play tuần tự win_result; tumble theo gravity; đừng tự gen symbol.
• Highlight theo lines / positions; orb theo orbs.
• Nhân orb chỉ khi applied_multiplier > 1.
• Bet chỉ gửi giá trị trong bets.
• Giá buy = buy_free_spins_price * bet.
• FS: khóa bet/buy; tin free_spins; credit chip chỉ khi is_finish_free_spin.
• Win tier / max win: play fanfare theo win_tier và hit_max_win.
• Restore: nếu /gameplay trả is_free_spin, nhảy thẳng vào FS UI.
• Không gọi song song 2 spin cho 1 user — đợi response + animation xong.