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

Thả bóng một shot. Chọn row 8/12/16 và risk 1/2/3. Server trừ bet và cộng win trong cùng một response. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Demo peg pyramid

Hàng peg lệch nhau. Bucket vàng = bóng vừa rơi vào (position = 4, risk low row 8).

Index bucket 0…8 trái → phải. Animate path tới position rồi hiện multiplier × bet = win_amount. Đừng tự random bucket.

3. Auth & envelope

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

Mọi API dưới /api/v1 cần JWT. HTTP 200 + code = 0 là thành công; payload nằm trong msg.

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

4. GET /api/v1/gameplay

Gọi khi vào game. Trả bảng hệ số cho mọi (row, risk). Client render selector + paytable từ đây, không hardcode.

{
  "code": 0,
  "msg": {
    "user_money": 500000,
    "bets": [200, 1000, 2000, 10000],
    "show_bets": [200, 1000, 2000, 10000],
    "config": [
      {"row": 8, "risk": 1, "multipliers": [29, 4, 1.5, 0.3, 0.2, 0.3, 1.5, 4, 29]},
      {"row": 8, "risk": 2, "multipliers": [13, 3, 1.3, 0.7, 0.4, 0.7, 1.3, 3, 13]},
      {"row": 8, "risk": 3, "multipliers": [5.6, 2.1, 1.1, 1, 0.5, 1, 1.1, 2.1, 5.6]},
      {"row": 12, "risk": 1, "multipliers": [170, 24, 8.1, 2, 0.7, 0.2, 0.2, 0.2, 0.7, 2, 8.1, 24, 170]},
      {"row": 16, "risk": 1, "multipliers": [1000, 130, 26, 9, 4, 2, 0.2, 0.2, 0.2, 0.2, 0.2, 2, 4, 9, 26, 130, 1000]}
    ]
  }
}

Response thật đủ 9 board. Rút gọn ở đây. Risk 2/3 của row 12/16 cũng nằm trong config.

5. POST /api/v1/bet

Một drop. Debit bet rồi credit win trong cùng handler. user_money đã là số dư sau cả hai bước.

POST /api/v1/bet
{ "bet": 1000, "row": 8, "risk": 1 }

{
  "code": 0,
  "msg": {
    "user_money": 499200,
    "bet": 1000,
    "row": 8,
    "risk": 1,
    "position": 4,
    "multiplier": 0.2,
    "win_amount": 200
  }
}

{
  "code": 0,
  "msg": {
    "user_money": 528000,
    "bet": 1000,
    "row": 8,
    "risk": 1,
    "position": 0,
    "multiplier": 29,
    "win_amount": 29000
  }
}

Cheat (non-prod)

{ "bet": 1000, "row": 8, "risk": 1, "cheat_position": 8 }

Production bỏ qua field này, luôn random. Client không gửi trên build live. cheat_position phải > 0 và < số bucket.

6. GET /top-win · GET /history

GET /api/v1/top-win
{
  "code": 0,
  "msg": { "winners": [{ "rank": 1, "user_id": 1001, "username": "alice", "total_win": 2400000 }] }
}

GET /api/v1/history
{
  "code": 0,
  "msg": {
    "logs": [
      { "user_money": 499200, "win_amount": 200, "bet": 1000, "multiplier": 0.2, "row": 8, "created_at": 1720000000 }
    ]
  }
}

History không có field risk / position. created_at là unix second.

7. Luồng ghép

1. Mở game → GET /gameplay. Render selector row/risk, vẽ bucket theo multipliers, hiện money + bet chips.
2. User chọn bet (trong bets), row, risk. Disable Drop nếu user_money < bet.
3. POST /bet. Khóa nút tới khi xong animation.
4. Animate bóng rơi (peg pyramid) tới bucket position. Highlight bucket đó.
5. Hiện multiplier và win_amount. Cập nhật chip = user_money (đã net).
6. Mở khóa Drop. Không cần gọi lại /gameplay trừ khi code 69 / reconnect.

8. Error & tiền

9. Checklist client

• Vào game: GET /gameplay trước drop.
• Vẽ đúng multipliers.length bucket; position là index 0-based.
• Row/risk chỉ gửi cặp có trong config.
• Bet chỉ gửi giá trị trong bets.
• Animate theo position server — đừng tự random.
• Money = user_money sau response (đã −bet +win).
• cheat_position chỉ non-prod; production bỏ field.
• Không spam 2 drop song song — đợi response + bóng rơi xong.