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

Payline slot 5×3, scatter / wild, free spins pot. Giữa FS không trừ bet; credit chip khi is_finish_free_spin. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Luồng ghép

1. Mở game → GET /gameplay. Render board preview, bet, paytable, money, FS nếu đang feature.
2. User chọn bet chỉ khi is_free_spin = false.
3. POST /spins body {"bet": ...} (giá trị trong bets).
4. Highlight từng win_lines[]. Hiện scatter nếu scatter_win_amount > 0.
5. Nếu is_bonus → popup +N FS từ number_of_bonus_free_spins.
6. Khi is_free_spin: không trừ bet, tiếp tục /spins tới is_finish_free_spin.
7. 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 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

Board luôn mảng cột. Demo: payline thắng + Wild + Scatter được highlight.

Hàng đầu = row 0. Ô vàng = payline High1 (8) với Wild (11, xanh lá). Ô vàng đậm = Scatter (12) trên 2 cột — đủ scatter pay / tiến tới FS.

Paytable & line win

Luôn dùng pay_table từ /gameplay. Mỗi win_lines[] tách:

• symbol_win_amount — thắng của paying symbol (có wild thay thế).
• wild_win_amount — thắng nếu line được tính như cụm wild.
• symbol_win_multiplier — hệ số paytable đã apply.
• Tổng line client highlight = không tự cộng; tin từng field, tổng spin nằm ở win_amount top-level.

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": {
    "user_money": 500000,
    "bet": 1000,
    "bets": [200, 1000, 2000, 10000],
    "show_bets": [200, 1000, 2000, 10000],
    "pay_table": [[1,2,5],[1.5,3,8],[2,4,10],[2.5,5,12],[3,8,15],[4,10,20],[5,12,25],[8,15,40],[10,25,80],[15,40,100],[20,50,150]],
    "is_free_spin": false,
    "free_spins": 0,
    "max_free_spins": 0,
    "free_spin_pot": 0,
    "init_reels": [[8,2,0],[11,5,6],[8,12,9],[4,1,7],[12,3,10]]
  }
}

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ỉ cheat non-prod.

SpinResult

WinLine

{
  "code": 0,
  "msg": {
    "user_money": 499000,
    "win_amount": 8500,
    "bet": 1000,
    "is_bonus": true,
    "number_of_bonus_free_spins": 10,
    "is_free_spin": false,
    "free_spins": 10,
    "max_free_spins": 10,
    "free_spin_pot": 0,
    "is_finish_free_spin": false,
    "win_lines": [{
      "line": [8, 11, 8, 4, 12],
      "line_number": 0,
      "symbol": 8,
      "number_of_symbols": 3,
      "number_of_wilds": 1,
      "symbol_win_amount": 8000,
      "wild_win_amount": 0,
      "symbol_win_multiplier": 8
    }],
    "reels": [[8,2,0],[11,5,6],[8,12,9],[4,1,7],[12,3,10]],
    "number_of_scatter_cols": 2,
    "scatter_win_amount": 500
  }
}

Spin trigger FS: is_bonus = true nhưng is_free_spin = false. Win spin này credit ngay (kể scatter). Các spin sau mới là FS.

7. Free spins

• Trigger khi đủ scatter cột (server quyết, client tin is_bonus).
• Số lượt = number_of_bonus_free_spins (config number_of_free_spins).
• Giữa FS: is_free_spin = true, không trừ bet, win cộng free_spin_pot.
• Spin cuối: is_finish_free_spin = true, win_amount = cả pot, user_money đã cộng, free_spin_pot = 0.
• Retrigger: is_bonus trong lúc FS → cộng thêm lượt, popup +N, free_spins tăng.
• Khóa đổi bet suốt FS. Vẫn gửi bet hiện tại.

{
  "code": 0,
  "msg": {
    "user_money": 520000, "win_amount": 21000, "bet": 1000,
    "is_bonus": false, "number_of_bonus_free_spins": 0,
    "is_free_spin": true, "free_spins": 0, "max_free_spins": 10,
    "free_spin_pot": 0, "is_finish_free_spin": true,
    "win_lines": [], "reels": [[1,2,3],[4,5,6],[7,8,9],[0,1,2],[3,4,5]],
    "number_of_scatter_cols": 0, "scatter_win_amount": 0
  }
}

8. Animation

1. Vẽ reels 5×3, row 0 trên cùng.
2. Lần lượt highlight từng win_lines[] theo line / line_number.
3. Wild (11): overlay riêng; nếu wild_win_amount > 0 play nhánh wild.
4. Scatter: đếm cột từ board hoặc tin number_of_scatter_cols. Cộng scatter_win_amount.
5. is_bonus → popup FS rồi chuyển mode.
6. FS: counter free_spins / max_free_spins, pot meter. Finish → cộng chip một lần.

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

{
  "bet": 1000,
  "reels": [
    [8, 2, 0],
    [11, 5, 6],
    [8, 12, 9],
    [4, 1, 7],
    [12, 3, 10]
  ]
}

• Đủ 5 cột, mỗi cột 3 hàng. Production: field bị bỏ qua, luôn random.
• Dùng để force wild + scatter trên board test.

10. Error & tiền

Khi nào chip đổi

11. Checklist client

• Vào game: GET /gameplay trước mọi spin.
• Board luôn [col][row], 5×3, row 0 = top.
• Highlight theo win_lines; wild/scatter overlay riêng.
• Tin number_of_scatter_cols + scatter_win_amount.
• Bet chỉ gửi giá trị trong bets.
• FS: khóa bet; 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.
• Không gọi song song 2 spin cho 1 user — đợi response + animation xong.