guandan.dev

https://git.tonybtw.com/guandan.dev.git git://git.tonybtw.com/guandan.dev.git

3,525 bytes raw

#+AUTHOR: Tony
#+STARTUP: overview

* Guan Dan BTW
A real-time multiplayer web implementation of Guan Dan (掼蛋), a popular Chinese climbing card game for 4 players in 2v2 teams.

[[./assets/guandan.png]]

* Table of Contents :toc:
- [[#guan-dan-btw][Guan Dan BTW]]
- [[#features][Features]]
- [[#installation][Installation]]
- [[#usage][Usage]]
- [[#development][Development]]
- [[#project-structure][Project Structure]]
- [[#game-rules][Game Rules]]
- [[#future-plans][Future Plans]]
- [[#license][License]]

* Features
- Real-time multiplayer via WebSockets
- Room-based lobbies (create/join with room code)
- Full Guan Dan ruleset:
  - Level system (2 through A)
  - Wild cards (heart of current level)
  - Bomb hierarchy (4-10 of a kind, straight flush, 4-joker)
  - Tribute system between hands
- Bot players ("Fill with Bots" button for testing)
- Play log sidebar (track recent plays)
- Turn/play highlighting (visual feedback for whose turn and who just played)

* Installation
Requires Go 1.23+ and Node.js 18+.

#+begin_src sh
git clone https://github.com/tonybanters/guandanbtw
cd guandanbtw
nix develop
#+end_src

* Usage
Run both server and client:
#+begin_src sh
just dev    # or: mprocs
#+end_src

Or run separately:
#+begin_src sh
cd server && air        # go server with hot reload
cd client && npm run dev  # vite dev server
#+end_src

Open =http://localhost:5173=, create a room, and share the room code with 3 friends. Use "Fill with Bots" to test without 4 players.

* Development
Using Nix (recommended):
#+begin_src sh
nix develop
#+end_src

Dev shell includes: go, gopls, air, nodejs, typescript, just, mprocs.

* Project Structure
#+begin_src
server/
├── main.go               [Entry point, HTTP/WS server]
├── game/
│   ├── card.go           [Card types, deck, ranking]
│   ├── combination.go    [Valid play detection]
│   ├── bomb.go           [Bomb hierarchy]
│   └── state.go          [Game state machine]
├── room/
│   ├── hub.go            [WebSocket hub, room management]
│   ├── room.go           [Room logic, game flow]
│   └── client.go         [Client connection handling]
└── protocol/
    └── messages.go       [JSON message types]

client/
├── src/
│   ├── App.tsx           [Main app, state management]
│   ├── components/
│   │   ├── Card.tsx      [Card component]
│   │   ├── Hand.tsx      [Player hand]
│   │   ├── Table.tsx     [Center play area]
│   │   ├── Lobby.tsx     [Create/join room UI]
│   │   └── Game.tsx      [Main game layout]
│   ├── hooks/
│   │   └── use_websocket.ts
│   └── game/
│       └── types.ts      [Shared types]
└── package.json
#+end_src

* Game Rules
- 4 players, 2v2 teams (partners sit opposite)
- 2 decks + 4 jokers = 108 cards, 27 each
- Teams race to empty their hands
- Current level card ranks highest; heart of level is wild
- Valid plays: singles, pairs, triples, full houses, straights, tubes, plates
- Bombs beat everything (ranked by size, then straight flush, then 4-joker)
- Winners advance levels based on finish order

Full rules: [[https://www.pagat.com/climbing/guan_dan.html][pagat.com]]

* Future Plans
- Tribute UI on frontend
- Sound effects and better animations
- Card sorting options
- Spectator mode
- Mobile responsive layout
- Deployment (fly.io/railway)

* License
[[https://www.gnu.org/licenses/gpl-3.0.en.html][GPL v3]]

1	`#+AUTHOR: Tony`
2	`#+STARTUP: overview`
3
4	`* Guan Dan BTW`
5	`A real-time multiplayer web implementation of Guan Dan (掼蛋), a popular Chinese climbing card game for 4 players in 2v2 teams.`
6
7	`[[./assets/guandan.png]]`
8
9	`* Table of Contents :toc:`
10	`- [[#guan-dan-btw][Guan Dan BTW]]`
11	`- [[#features][Features]]`
12	`- [[#installation][Installation]]`
13	`- [[#usage][Usage]]`
14	`- [[#development][Development]]`
15	`- [[#project-structure][Project Structure]]`
16	`- [[#game-rules][Game Rules]]`
17	`- [[#future-plans][Future Plans]]`
18	`- [[#license][License]]`
19
20	`* Features`
21	`- Real-time multiplayer via WebSockets`
22	`- Room-based lobbies (create/join with room code)`
23	`- Full Guan Dan ruleset:`
24	`- Level system (2 through A)`
25	`- Wild cards (heart of current level)`
26	`- Bomb hierarchy (4-10 of a kind, straight flush, 4-joker)`
27	`- Tribute system between hands`
28	`- Bot players ("Fill with Bots" button for testing)`
29	`- Play log sidebar (track recent plays)`
30	`- Turn/play highlighting (visual feedback for whose turn and who just played)`
31
32	`* Installation`
33	`Requires Go 1.23+ and Node.js 18+.`
34
35	`#+begin_src sh`
36	`git clone https://github.com/tonybanters/guandanbtw`
37	`cd guandanbtw`
38	`nix develop`
39	`#+end_src`
40
41	`* Usage`
42	`Run both server and client:`
43	`#+begin_src sh`
44	`just dev # or: mprocs`
45	`#+end_src`
46
47	`Or run separately:`
48	`#+begin_src sh`
49	`cd server && air # go server with hot reload`
50	`cd client && npm run dev # vite dev server`
51	`#+end_src`
52
53	`Open =http://localhost:5173=, create a room, and share the room code with 3 friends. Use "Fill with Bots" to test without 4 players.`
54
55	`* Development`
56	`Using Nix (recommended):`
57	`#+begin_src sh`
58	`nix develop`
59	`#+end_src`
60
61	`Dev shell includes: go, gopls, air, nodejs, typescript, just, mprocs.`
62
63	`* Project Structure`
64	`#+begin_src`
65	`server/`
66	`├── main.go [Entry point, HTTP/WS server]`
67	`├── game/`
68	`│ ├── card.go [Card types, deck, ranking]`
69	`│ ├── combination.go [Valid play detection]`
70	`│ ├── bomb.go [Bomb hierarchy]`
71	`│ └── state.go [Game state machine]`
72	`├── room/`
73	`│ ├── hub.go [WebSocket hub, room management]`
74	`│ ├── room.go [Room logic, game flow]`
75	`│ └── client.go [Client connection handling]`
76	`└── protocol/`
77	`└── messages.go [JSON message types]`
78
79	`client/`
80	`├── src/`
81	`│ ├── App.tsx [Main app, state management]`
82	`│ ├── components/`
83	`│ │ ├── Card.tsx [Card component]`
84	`│ │ ├── Hand.tsx [Player hand]`
85	`│ │ ├── Table.tsx [Center play area]`
86	`│ │ ├── Lobby.tsx [Create/join room UI]`
87	`│ │ └── Game.tsx [Main game layout]`
88	`│ ├── hooks/`
89	`│ │ └── use_websocket.ts`
90	`│ └── game/`
91	`│ └── types.ts [Shared types]`
92	`└── package.json`
93	`#+end_src`
94
95	`* Game Rules`
96	`- 4 players, 2v2 teams (partners sit opposite)`
97	`- 2 decks + 4 jokers = 108 cards, 27 each`
98	`- Teams race to empty their hands`
99	`- Current level card ranks highest; heart of level is wild`
100	`- Valid plays: singles, pairs, triples, full houses, straights, tubes, plates`
101	`- Bombs beat everything (ranked by size, then straight flush, then 4-joker)`
102	`- Winners advance levels based on finish order`
103
104	`Full rules: [[https://www.pagat.com/climbing/guan_dan.html][pagat.com]]`
105
106	`* Future Plans`
107	`- Tribute UI on frontend`
108	`- Sound effects and better animations`
109	`- Card sorting options`
110	`- Spectator mode`
111	`- Mobile responsive layout`
112	`- Deployment (fly.io/railway)`
113
114	`* License`
115	`[[https://www.gnu.org/licenses/gpl-3.0.en.html][GPL v3]]`