Mahjong Ways — tài liệu ghép client

Slot Megaways cố định 5 cột × 4 hàng. Tumble cascade, multiplier tăng theo lượt nổ. 3 scatter = 12 free spin. Không jackpot, không mua bonus. 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. Vào game → GET /gameplay. Render board preview 5×4, bet, paytable, FS nếu đang dở.
2. Base: POST /spins {"bet":...}. Play tuần tự win_result[].
3. is_bonus_free_spin → popup +12 FS, mini_game_type = 1.
4. FS: is_free_spin, không trừ bet. Line win cộng pot; chỉ credit chip khi is_finish_free_spin.
5. Luôn lấy số dư từ user_money của response vừa nhận.

3. Auth & envelope

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. HTTP 200 + code = 0 là thành công; payload nằm trong msg.

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

4. Grid & symbol

Mỗi ô là packed int. 4 bit thấp là symbol id (0–9); bit 4 là cờ golden. Cột dọc, hàng 0 ở trên.

Ví dụ: 0 là Fa thường, 16 là Fa golden; 8 là Wild thường, 24 là Wild golden. Field lines[].symbol vẫn luôn là symbol id thô.

JavaScript: pack / unpack

const SYMBOL_MASK = 0b0000_1111;
const GOLDEN_MASK = 0b0001_0000;

function packSymbol(symbol, isGolden = false) {
  return (symbol & SYMBOL_MASK) | (isGolden ? GOLDEN_MASK : 0);
}

function unpackSymbol(value) {
  return {
    symbol: value & SYMBOL_MASK,
    isGolden: (value & GOLDEN_MASK) !== 0,
  };
}

// 16 → { symbol: 0, isGolden: true }
// 24 → { symbol: 8, isGolden: true }
const { symbol, isGolden } = unpackSymbol(reels[col][row]);

mini_game_type: 0 base · 1 free spin. Dùng pay_table từ /gameplay, đừng hardcode. pay_table[symbol][n-1] = hệ số khi ăn n cột (n ≥ 3 mới > 0).

5. Multiplier

Mỗi spin (kể cả FS) bắt đầu multiplier = 1. Lượt nổ sau nhân với multiplier của lượt trước. Tăng sau tumble thắng.

• win_result[i].multiplier = hệ số áp vào win của tumble đó.
• bonus_multiplier = số vừa tăng để dùng tumble sau (0 nếu tumble không thắng).
• Không cộng dồn giữa các spin FS — mỗi FS spin reset về ×1.

6. GET /api/v1/gameplay

Gọi 1 lần khi vào game. Thiếu bước này thì spin 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": [[0,0,2,4,8],[0,0,1.5,3,5],[0,0,1.2,2.5,4],[0,0,1,2,3],[0,0,0.8,1.5,2.5],[0,0,0.6,1.2,2],[0,0,0.4,0.8,1.5],[0,0,0.4,0.8,1.5],[0,0,0,0,0],[0,0,0,0,0]],
    "is_free_spin": false, "free_spins": 0, "max_free_spins": 0, "free_spin_pot": 0, "free_spin_multiplier": 1,
    "init_reels": [[0,1,2,3],[1,4,5,6],[2,8,0,7],[3,5,6,1],[9,7,4,2]],
    "mini_game_type": 0
  }
}

7. POST /api/v1/spins

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

• Phải /gameplay trước.
• Base trừ bet ngay. FS không trừ; vẫn gửi bet hiện tại, không đổi bet.

SpinResult

WinResult / WinLine

lines[].positions luôn 5 cột (cột không ăn = []). Row 0-indexed.

{
  "code": 0,
  "msg": {
    "bet": 1000, "user_money": 499000, "win_amount": 8000,
    "mini_game_type": 0, "is_free_spin": false, "free_spins": 0, "free_spin_pot": 0,
    "is_finish_free_spin": false, "is_bonus_free_spin": false, "bonus_mini_game_type": 0,
    "number_of_bonus_free_spins": 0, "max_free_spins": 0, "multiplier": 2,
    "win_result": [{
      "lines": [{ "symbol": 0, "positions": [[0,1],[0],[2],[],[]], "win_amount": 8000, "line_size": 3, "number_of_lines": 2 }],
      "reels": [[16,0,1,2],[0,4,5,6],[8,5,0,7],[3,5,6,1],[7,4,2,2]],
      "positions": [[0,1],[0],[2],[],[]], "multiplier": 1, "bonus_multiplier": 1, "mega_ways": 1024
    }]
  }
}

8. Animation / tumble

1. Vẽ win_result[i].reels (5×4, row 0 trên).
2. Highlight positions / từng lines. Hiện multiplier của bước.
3. Ô thắng thường biến mất. Ô thắng có isGolden = true phải animate thành Wild (id 8), không biến mất. Sau đó gravity theo cột; board mới = phần tử tiếp theo — đừng tự random.
4. Nếu bonus_multiplier > 0: animate tăng multiplier (base +1, FS nhảy 1→2 rồi +2).
5. FS: cộng line win vào counter pot; chỉ credit chip khi is_finish_free_spin.

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

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

5 cột × 4 hàng. Có thể gửi symbol id thô 0–9 hoặc packed value từ packSymbol để test golden, ví dụ packSymbol(0, true) = 16. Ô trống / thiếu → server random. Production bỏ qua reels.

10. Error & tiền

11. Checklist client

• GET /gameplay trước mọi spin.
• Grid 5×4 dùng packed symbol; unpack trước khi chọn sprite, và render cờ golden. Không top reel / mallet / jackpot / buy.
• Play tuần tự win_result. Bet chỉ giá trị trong bets.
• 3 scatter → đúng 12 FS. Trong FS không vẽ scatter.
• Multiplier reset mỗi spin; base max 5, FS max 10.
• FS line win vào pot. Không gọi song song 2 request cho 1 user.