UnoChess is not just chess. It is not just UNO. It is a strategic hybrid where every move matters, every card can change the fate of the game, and every match tells a different story. ๐ฒโจ
- What Is UnoChess? ๐ค
- Main Features ๐
- How to Play ๐ฏ
- Quick Card Guide ๐
- Game Modes ๐ฎ
- AI Difficulty Levels ๐ค
- Time Controls โฑ๏ธ
- Account System & Lichess Login ๐
- Online Multiplayer ๐
- Available Languages ๐
- Technologies Used ๐ ๏ธ
- Project Structure ๐
- Local Installation and Development ๐ป
- Deployment ๐
- Future Roadmap ๐ฎ
- Project Philosophy ๐
- Contributing ๐ค
- License ๐
- Useful Links ๐
UnoChess is a browser-based strategy game that blends the depth of classic chess with the unpredictability of UNO cards. ๐ง ๐ฅ
Instead of simply moving pieces, you draw a card every turn. That card determines how many moves you can make, which special actions trigger, and how the board changes. Got a +2? Draw extra moves or recover a piece. Got a Reverse? The turn changes hands and the board flips. Got a Wild? Teleport a piece to any square. ๐ฑ
The result is a game that feels familiar to chess players yet accessible to anyone who enjoys a mental challenge. You do not need to be a grandmaster to winโฆ but it helps. ๐
๐ฏ Goal: Checkmate the opposing king, or capture it, by using your cards and pieces intelligently.
- ๐ Unique card system: 4 colors, number cards (0โ9), action cards (+2, Skip, Reverse), and Wilds (Wild, Wild +4). Each card is tied to chess mechanics.
- โ๏ธ Complete chess rules: Castling, en passant, promotion, check, checkmate, stalemate.
- ๐ค AI with 10 difficulty levels: From ~400 Elo to ~2200 Elo. The AI uses cards strategically, chooses Wild colors, and decides when to teleport or attack.
- ๐ฅ Local multiplayer: Play on the same device in Tabletop (both see the board) or Pass & Play (screen hidden between turns).
- ๐ Account system & Lichess login: Create an account or sign in with your Lichess credentials to save your progress, stats, and online profile.
- ๐ Online multiplayer: Play against other players online or invite friends to a private match with a shareable link.
- โฑ๏ธ Varied time controls: Unlimited, Bullet, Blitz, Rapid, and Classical presets.
- ๐ 25-language interface: Automatic browser detection and manual selector.
- ๐จ Modern responsive design: Tailwind CSS, Motion animations, Lucide icons. Works on desktop, tablet, and mobile.
- ๐ Immersive audio: Sound effects for moves, captures, cards, and victory, with mute.
- ๐ง Built-in card guide: A modal explains every card and its effects.
- ๐ฏ Free and ad-free: No monetization, no tracking. Just the game.
- Choose mode: AI ๐ค, local multiplayer ๐ฅ, or online ๐.
- Pick your side: White โ or Black โ.
- Set time control: From lightning-fast to classical.
- Play! Each turn:
- ๐ค Draw a card from the deck.
- ๐ The card is revealed and its effect activates.
- โ๏ธ Move your pieces according to the card, or perform the special action.
- ๐ The turn passes (or reverses).
- Win by checkmate or by capturing the enemy king. ๐
๐ก Pro tip: A 0 card may lose you a turn, but sometimes it is the strategic pause you need.
| Card | Color | Main Effect | Emoji |
|---|---|---|---|
| 0 | Any | Lose turn, recover a captured piece. | ๐ซ |
| 1โ9 | Any | Move that many times (1โ9 moves). | ๐ข |
| +2 | Any | Draw 2 cards or recover a piece; extra move possible. | โ |
| Skip | Any | Cancel opponentโs turn. | ๐ |
| Reverse | Any | Flip the board 180ยฐ and change turn; can save from check. | ๐ |
| Wild | Special | Choose a color and teleport a piece. | ๐ |
| Wild +4 | Special | Choose a color and attack an enemy piece. | ๐ฅ |
๐ Inside the game, a detailed Card Guide explains every card with examples.
10 difficulty levels. The AI uses cards strategically, picks Wild colors, and decides when to teleport or attack. Each level adjusts aggression, search depth, and card management.
- Tabletop: Both players see the board.
- Pass & Play: Screen hidden between turns.
Play against other players online or invite a friend with a shareable link. No signup required to join a match via link โ just click and play. ๐
| Level | Name | Approx. Elo | Behavior |
|---|---|---|---|
| 1โ3 | Basic ๐ฑ | 400โ800 | Simple play, makes mistakes. |
| 4โ6 | Normal ๐ฟ | 1000โ1400 | Balanced strategy. |
| 7โ8 | Tactical ๐ณ | 1600โ1800 | Punishes mistakes, manages resources. |
| 9โ10 | Master ๐ | 2000โ2200 | Near-perfect, uses combos and teleports. |
๐งช Elo is approximate. The AI also considers board state and available cards.
| Category | Presets | Description |
|---|---|---|
| โ Unlimited | โ | No clock. Perfect for learning. |
| Bullet โก | 1+0, 1+1, 2+1 | Ultra-fast. |
| Blitz ๐จ | 3+0, 3+2, 5+0, 5+3 | Speed + strategy. |
| Rapid โณ | 10+0, 10+5, 15+10 | More time to plan. |
| Classical ๐ฐ๏ธ | 30+0, 30+20 | Slow, deep games. |
โฒ๏ธ Increment = extra seconds per turn.
- Create an account to save your game history, stats, and online profile.
- Sign in with Lichess: Use your existing Lichess credentials via OAuth to log in instantly. No new password to remember. ๐
- Your Lichess username and rating can be displayed on your profile, bridging the two communities.
๐ Note: This feature set is described based on the author's information. Verify implementation details in the source code or the live app.
- Play with other players online in real-time matches.
- Invite friends with a link: Generate a shareable URL and send it to a friend. They click, join, and play โ no signup required to accept the invite. ๐
- Private rooms: Create a match and control who joins.
- Matchmaking: Find opponents of similar skill level (planned as the player base grows).
๐ This is a core feature of UnoChess. The invite-link system is designed to make sharing and playing with friends frictionless.
25 languages, including: ๐ช๐ธ Spanish ยท ๐ฌ๐ง English ยท ๐ซ๐ท French ยท ๐ฉ๐ช German ยท ๐ฎ๐น Italian ยท ๐ต๐น Portuguese ยท ๐ท๐บ Russian ยท ๐ฏ๐ต Japanese ยท ๐จ๐ณ Chinese ยท ๐ฐ๐ท Korean ยท ๐ธ๐ฆ Arabic ยท ๐ฎ๐ณ Hindi ยท ๐น๐ท Turkish ยท ๐ณ๐ฑ Dutch ยท ๐ต๐ฑ Polish ยท ๐ธ๐ช Swedish ยท ๐ณ๐ด Norwegian ยท ๐ฉ๐ฐ Danish ยท ๐ซ๐ฎ Finnish ยท ๐จ๐ฟ Czech ยท ๐ฌ๐ท Greek ยท ๐ฎ๐ฑ Hebrew ยท ๐น๐ญ Thai ยท ๐ป๐ณ Vietnamese ยท ๐ฎ๐ฉ Indonesian
๐ Auto-detected; change anytime from the start screen.
| Technology | Role |
|---|---|
| โ๏ธ React 19 | UI library. |
| ๐ TypeScript 7 | Static typing. |
| โก Vite 8 | Bundler & dev server. |
| ๐จ Tailwind CSS 4 | Utility-first styling. |
| ๐ i18next | 25-language i18n. |
| ๐๏ธ Motion | Animations. |
| ๐ผ๏ธ Lucide React | Icons. |
| ๐ง @google/genai | Optional Gemini API (future). |
| ๐ OAuth / Lichess API | Login with Lichess. |
| ๐ Realtime backend | Online multiplayer (implementation details in code). |
| โ๏ธ Cloudflare Pages | Deployment. |
| ๐ ๏ธ Wrangler | CLI for Cloudflare. |
๐งฉ Modular architecture: engine (pure logic), components (UI), types, i18n, utils.
UnoChess/
โโโ .github/workflows/deploy.yml
โโโ public/assets/
โโโ src/
โ โโโ components/ # StartScreen, ChessBoard, modalsโฆ
โ โโโ engine/
โ โ โโโ chess.ts # Chess rules, AI, legal moves
โ โ โโโ deck.ts # Deck creation & shuffling
โ โโโ i18n/
โ โ โโโ index.ts
โ โ โโโ languages.ts
โ โ โโโ translations.ts
โ โโโ types/game.ts
โ โโโ utils/audio.ts
โ โโโ App.tsx
โ โโโ main.tsx
โ โโโ index.css
โโโ index.html
โโโ package.json
โโโ tsconfig.json
โโโ vite.config.ts
โโโ .env.example
-
Clone:
git clone https://github.com/MeowDev1011/UnoChess.git cd UnoChess -
Install (
npmorbun):npm install # or bun install -
Optional env (only if using Gemini API or OAuth):
cp .env.example .env # Add GEMINI_API_KEY and any OAuth/Lichess credentials if needed -
Dev server:
npm run dev
โ
http://localhost:3000 -
Production build:
npm run build
-
Preview:
npm run preview
๐งน
npm run cleanremovesdistandserver.js.
Automated via GitHub Actions + Cloudflare Pages. On push to main, the workflow:
- Installs dependencies.
- Runs
npm run build. - Deploys
dist/to Cloudflare Pages via Wrangler.
Requirements for your own deploy:
- Set
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDsecrets. - Have a Cloudflare Pages project named
unochess(or change the name in the workflow).
๐ Live demo: https://unochess.pages.dev/
- ๐ Ranked matches & leaderboards: Climb the ranks.
- ๐ More cards & house rules: New actions, custom decks.
- ๐ฑ Native mobile apps: iOS & Android.
- ๐ค Tournaments and community events.
๐ None of this is possible without you. Share the game, star the repo, and help make UnoChess famous!
- 100% free and ad-free. No monetization, no tracking.
- Open source. Learn, modify, improve.
- Accessible to everyone. Multi-language, touch controls, responsive.
- Strategic depth. Cards add randomness, but tactics still matter.
โค๏ธ Made with care by MeowDev1011 and the community.
- Open an issue with your idea.
- Fork the repo.
- Create a branch (
git checkout -b feature/new-card). - Submit a pull request.
Please follow the existing code style and ensure npm run lint passes.
๐งช Tip: Test locally before submitting a PR.
MIT License. See the LICENSE file for details.
- ๐ฎ Play now: https://unochess.pages.dev/
- ๐ GitHub repo: https://github.com/MeowDev1011/UnoChess
- ๐ Report a bug: GitHub Issues
- ๐ก Suggest an idea: GitHub Discussions
- โ๏ธ Cloudflare Pages: Official docs
If you like the project, give it a star โญ on GitHub and share it with your friends. Let the game begin! ๐
โ๏ธ + ๐ = โค๏ธ