A full-stack Vietnamese card game (Tiến Lên) built for the web. Play solo against AI or create multiplayer rooms with friends.
Tien Len (Tiến Lên, "Go Forward") is the most popular card game in Vietnam. Players race to empty their hand by playing increasingly powerful card combinations. Twos are the highest card. Bombs beat twos. First to empty wins.
The game supports 2–8 players, with AI opponents filling empty seats in solo mode.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, Tailwind v4, Framer Motion |
| 3D | Three.js via React Three Fiber |
| State | Zustand (two-store architecture) |
| Multiplayer | Socket.io with JWT authentication |
| Game Engine | Pure TypeScript, server-authoritative |
| Monorepo | Turborepo + pnpm workspaces |
| Testing | Vitest (83 tests) |
tien-len/
├── apps/
│ ├── web/ Next.js frontend
│ └── server/ Socket.io multiplayer server
├── packages/
│ ├── engine/ Game logic, AI, validation (83 tests)
│ └── shared/ Types, constants, Zod schemas
├── docs/ Diataxis-style documentation
└── turbo.json Turborepo configuration
# Install dependencies
npx pnpm install
# Run tests
npx pnpm --filter @tienlen/engine test
# Start the dev server
npx pnpm --filter web devVisit http://localhost:3000 and click Solo to play against AI.
For multiplayer, also start the game server:
npx pnpm --filter @tienlen/server devAll documentation follows the Diataxis framework, organized into four categories by purpose.
Step-by-step lessons to get you started.
- Getting Started — Set up the dev environment
- Your First Game — Play a solo game against AI
- Host Multiplayer — Create a room and play with friends
Practical guides for specific tasks.
- Run Tests — Run and write engine tests
- Deploy — Deploy frontend to Vercel and server to Docker
- Add House Rules — Customize game settings
- Customize Theme — Change colors, fonts, and styles
- Add AI Difficulty — Create harder AI opponents
Background knowledge and design decisions.
- Architecture — Monorepo structure and data flow
- Game Rules — Complete Tien Len rules reference
- Security Model — Server-authoritative validation
- State Management — Zustand two-store architecture
Technical specifications and API docs.
- Game Engine API — TienLenGame class and utilities
- Socket Events — WebSocket event contracts
- Environment Variables — Configuration reference
- Design System — Colors, typography, components
- Component Library — UI component props and usage
The UI draws from Vietnamese and Chinese festive aesthetics — deep reds paired with gold, a Ma Shan Zheng brush calligraphy font, and a golden felt poker table. The landing page features 3D playing cards floating in space via Three.js.
Players are represented by deterministic pixel-art avatars (Facehash) with rainbow ring borders. The game table supports 2–8 players seated around an elliptical layout with red ribbon name banners and animated status indicators.
MIT