HonestLiar## 📁 Project Structure

honestliar-game/eb Game

A realtime multiplayer web version of the social deduction party game **HonestLiar**, where players compete to deceive the judge or be the honest player.

## 🎮 Game Overview

**HonestLiar** is a social deduction game for 3-15 players:
- Each round has 1 **Judge**, 1 secret **Honest** player, and remaining **Liars**
- The Honest player sees the real explanation of a term, while Liars must improvise
- All players explain the term, and the Judge must identify the Honest player
- Scoring rewards good deception and correct judgments

## 🏗️ Project Structure

honestliar-game/ ├── backend/ # Node.js + TypeScript + Socket.IO server │ ├── src/ │ │ ├── index.ts # Main server entry point │ │ ├── types.ts # TypeScript interfaces │ │ ├── constants.ts # Game constants and scoring │ │ ├── RoomManager.ts # Game state management │ │ ├── CardDeck.ts # Topic card handling │ │ └── cards.json # Topic cards dataset (20 cards) │ ├── package.json │ └── tsconfig.json │ └── frontend/ # React + TypeScript + Vite ├── src/ │ ├── main.tsx # React entry point │ ├── App.tsx # Main app component │ ├── App.css # Styling │ ├── types.ts # TypeScript interfaces │ ├── socketService.ts # Socket.IO client wrapper │ └── components/ # React components │ ├── Landing.tsx │ ├── Lobby.tsx │ ├── RoleReveal.tsx │ ├── DarkPhase.tsx │ ├── Discussion.tsx │ ├── Judging.tsx │ ├── RoundResultScreen.tsx │ └── GameOver.tsx ├── package.json ├── vite.config.ts └── index.html

## 🚀 Getting Started

### Prerequisites

- Node.js 18+ and npm installed
- Modern web browser

### Installation & Running

#### 1. Install Backend Dependencies

```bash
cd backend
npm install

2. Install Frontend Dependencies

cd ../frontend
npm install

3. Run Backend Server

cd backend
npm run dev

The server will start on http://localhost:3001

4. Run Frontend (in a new terminal)

cd frontend
npm run dev

The app will be available at http://localhost:3000

🎯 How to Play

1. Create/Join Room: One player creates a room and shares the room code with others
2. Lobby: Wait for at least 3 players to join, then the host starts the game
3. Role Assignment: Each player receives their role (Judge/Honest/Liar)
4. Dark Phase: The Honest player reads the real explanation (15 seconds)
5. Discussion: Each non-judge player explains the term in turn (45 seconds each)
6. Judging: The Judge selects who they think is the Honest player
7. Scoring: Points are awarded based on correct/incorrect judgments
8. Next Round: Continue for the configured number of rounds
9. Game Over: Winner(s) with highest score are announced

🎲 Game Features

• ✅ Realtime multiplayer with WebSocket (Socket.IO)
• ✅ Server-authoritative game logic (no cheating!)
• ✅ Role-based information hiding
• ✅ Automatic phase transitions with timers
• ✅ Scoring system with condemn rule option
• ✅ 20 topic cards in Traditional Chinese
• ✅ Reconnection support
• ✅ Mobile-responsive design
• ✅ Beautiful gradient UI with animations

⚙️ Game Settings

Default settings (configurable in lobby):

• Max Rounds: 5
• Speaking Time: 45 seconds per player
• Dark Phase: 15 seconds for Honest to read
• Condemn Rule: Enabled (Judge can condemn suspected Liars)
• Language: Traditional Chinese (zh-Hant)

📊 Scoring System

• Judge correct: +2 points
• Honest picked: +2 points
• Liar fools Judge: +3 points
• Judge wrong: -1 point
• Judge condemns Liar correctly: +1 point (Judge), -1 point (Liar)
• Judge condemns Honest: -3 points (Judge)

🛠️ Technology Stack

Backend

• Node.js + TypeScript
• Express.js
• Socket.IO (WebSocket)
• In-memory room management

Frontend

• React 18
• TypeScript
• Vite (build tool)
• Socket.IO Client
• CSS3 with animations

📝 API / Events

Client → Server

• create_room - Create a new game room
• join_room - Join existing room
• start_game - Start the game (host only)
• judge_decision - Submit judge's decision
• update_settings - Update game settings
• request_next_round - Start next game

Server → Client

• room_created - Room creation confirmation
• room_joined - Join confirmation
• room_state - Current room state
• game_started - Game has started
• round_started - New round info
• your_role - Player's role (private)
• topic_public - Topic title (public)
• phase_changed - Game phase transition
• speaker_changed - Current speaker
• judge_prompt - Judge decision time
• round_result - Round scoring results
• game_over - Game ended
• error - Error message

🎨 Customization

Adding More Topic Cards

Edit backend/src/cards.json:

{
  "id": "card-021",
  "title": "新詞彙",
  "explanation": "這個詞彙的真正解釋..."
}

Adjusting Game Settings

Edit backend/src/constants.ts for default values:

export const DEFAULT_SETTINGS = {
  maxRounds: 5,
  enableCondemnRule: true,
  language: "zh-Hant" as const,
  speakingTimeSec: 45,
  darkPhaseSec: 15,
};

Styling

Edit frontend/src/App.css to customize colors, animations, and layout.

🐛 Troubleshooting

Port already in use?

• Backend: Change PORT in backend/src/index.ts
• Frontend: Change port in frontend/vite.config.ts

Connection refused?

• Make sure backend is running on port 3001
• Check frontend/src/socketService.ts connects to correct URL

TypeScript errors?

• Run npm install in both backend and frontend directories

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code of conduct
• Development setup
• Coding standards
• Pull request process
• Adding new topic cards

� Deployment

Local Development

See QUICKSTART.md for local development setup.

Docker & Cloud Deployment

Deploy to production with Docker containers:

• Docker Compose: Local or EC2 deployment
• AWS ECS: Serverless containers on Fargate
• AWS EKS: Kubernetes on AWS
• EC2: Direct Docker deployment

📖 Full Guide: DOCKER_DEPLOYMENT.md

Quick Start with Docker:

# Copy environment configuration
cp .env.docker .env

# Start all services
docker-compose up -d

# Access: http://localhost:3000

Storage Options

• In-Memory (default): Fast, no persistence
• MongoDB: Persistent storage, survives restarts

See Storage Guide for MongoDB setup.

�📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

What This Means

✅ You can:

• Use this software for personal or commercial purposes
• Modify and create derivative works
• Distribute copies
• Use privately

❌ You must:

• Include the original license and copyright notice
• State changes made to the code

⚠️ No warranty:

• Software is provided "as is" without warranty
• Authors are not liable for damages

⚠️ Disclaimer

Please read our full DISCLAIMER before using this software. Key points:

• Educational Purpose: For entertainment and learning only
• Content: Topic cards are for reference; verify information from authoritative sources
• Privacy: No personal data collected by default; server operators are responsible for data protection
• Age Rating: Recommended for ages 13+
• User Responsibility: Follow online safety guidelines; don't share personal information
• Server Security: If self-hosting, you're responsible for security and compliance

📚 Documentation

• Quick Start Guide - Get up and running in 5 minutes
• Storage Configuration - In-Memory vs MongoDB setup
• Contributing Guide - How to contribute
• Disclaimer - Important legal information

🎉 Credits

Game Inspiration: Inspired by social deduction party games involving bluffing and truth-telling mechanics.

Contributors: Thanks to all who have contributed to this project!

Open Source Libraries:

• Node.js - JavaScript runtime
• React - UI framework
• Socket.IO - Real-time communication
• TypeScript - Type safety
• Vite - Build tool
• Express - Web framework

🌟 Support

If you find this project useful:

• ⭐ Star this repository
• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features via GitHub Discussions
• 🤝 Contribute code or documentation
• 📢 Share with friends!

📞 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Enjoy playing HonestLiar! Have fun deceiving your friends! 🎭

Made with ❤️ by the open-source community