Tiến Lên Star — tài liệu ghép client

Giống Tiến Lên, thêm hệ số sao (1–4). Server random sao lúc chia bài và gửi luôn trong gói deal. Không còn bước user chọn sao. DealTime dài hơn (~10s) để client diễn animation chia bài + random sao.

1. Tổng quan

ID lá bài: rank × 4 + suit. Rank 0=2 … 12=A. Suit 0=♠ 1=♣ 2=♦ 3=♥. Ví dụ 3♠ = 4.

2. Proto cho client

Tải file .proto rồi generate code (protoc / buf). Frame WS là binary protobuf, không JSON.

GET /tienlenstar/tienlenstar_event.proto
GET /tienlenstar/game_event.proto
# Host = domain DOCUMENT (trang docs này), không phải domain GAME.

3. Demo bàn (CSS)

DealTime: chia bài + random sao. Client quay ★ rồi dừng đúng deal.star (ví dụ 3). User không bấm chọn.

Animation random trong DealTime (~10s) rồi khóa vào giá trị server gửi. Không gửi request nào lúc này.

4. Kết nối & envelope

Mọi frame WebSocket là binary protobuf — không JSON. Một user chỉ được một connection; login trùng → lobby error 102.

GET /ws?access_token=<JWT>
# Host = domain GAME (không phải docs). Frame = bytes proto, không text JSON.

Envelope lobby package game_event (internal/proto/game-event). Payload bàn nằm trong data_send.data (C→S) và game_message.data (S→C) — bytes của proto game.

5. Lobby C→S (game_event.Request)

create_room { bet: 1000, password: "", max_players: 4, name: "ban-1" }
join_room   { room_id: 42, password: "", is_viewer: false }
data_send   { room_id: 42, data: <marshal(game Request)> }
data_send   { room_id: 42, auto_leave: {} }

6. Lobby S→C (game_event.Response)

RoomType (trong room_config)

Flag room_config: disable_create · disable_find · disable_get_list · disable_select (chỉ Play now) · play_now · best_choice (bet gợi ý). Room: room_id, is_private, bet, create_time, metadata map, name. metadata thường có max_players, number_of_players, label.

game_message.msg

error.tag — gói nào gây lỗi

Luồng sảnh (mọi game WS này)

1. Mở WS GET /ws?access_token= trên domain GAME. Đọc close code nếu fail.
2. Gửi room_config. Render mức cược; ẩn nút theo disable_* ; Play now nếu play_now.
3. Tuỳ UI: get_room_list / find_room / create_room / join_any_room / join_room.
4. Ngồi bàn: nhận user_joined (kể cả mình), có thể room_state trong game_message.data.
5. Đủ người: start_countdown rồi start_game. Từ đây chỉ gửi action qua data_send.data.
6. Chat: send_chat_message → chat_message. Mời: free_users_list → invite → đối phương nhận someone_invited_you.
7. Hết ván: reset_game. Rời: leave_room hoặc data_send.auto_leave (out sau ván).

7. Gameplay C→S (proto tienlenstar_event)

Marshal message dưới thành bytes, gửi trong data_send.data. Chỉ play trong ván thường — không có chose_star.

play { cards: [4], combination: Card }          // TagPlay=1
play { cards: [], combination: Pass }

8. Gameplay S→C

Nằm trong game_message.data. Reconnect: unmarshal room_state trước, rồi sync UI.

WinPenalty: winner_id, loser_id, win_amount, lose_amount, winner_money, loser_money — đã nhân star. Animate chặt heo rồi mới cập nhật chip.

9. Luồng ghép

1. Connect WS, join bàn, đợi start_countdown / start_game như mọi PvP.
2. Nhận deal: render 13 lá + đọc deal.star (1–4). Diễn animation chia bài và random sao trong DealTime (~10s). Không gửi gì.
3. Hết DealTime → player_turn. Nếu instant win → chờ finish (star vẫn áp dụng).
4. Khi player_turn.user_id = mình: chọn bộ, gửi play. Hết giờ server is_auto.
5. Mọi client play animation player_play, cập nhật table_cards.
6. Round mới (is_new_round): xóa bài bàn. win_penalty nếu có chặt heo (đã × star).
7. finish: lật bài còn lại, cộng winAmount (đã × star), hiện penalty.

10. Error codes

11. Checklist client

• Tải proto: tienlenstar_event.proto + game_event.proto.
• Xóa UI chọn sao / request chose_star.
• Lấy sao từ deal.star; animation random trong DealTime (~10s) rồi khóa đúng giá trị đó.
• room_state.star restore sau reconnect (kể cả đang DealTime).
• Hiện sao trên bàn suốt ván — nhân tiền chặt đồ và settle.
• Play/pass/auto giống tienlen; envelope lobby đầy đủ như mục 5–6.