# 🕯️ Hearthside Secrets

**Version**: 0.1.0  
**Status**: Phase 1 - Foundation Complete

A social deduction mystery game for The Gathering Stone addon.

---

## Overview

Hearthside Secrets is a modular, replayable mystery game where players take on roles, uncover secrets, share clues, and work to solve (or hide) the truth.

---

## File Structure

```
hearthside_secrets/
├── Init.lua                    # Namespace initialization
├── game.lua                    # Game registration
│
├── core/                       # Core game logic
│   ├── GameController.lua      # Main game controller
│   ├── ScenarioManager.lua     # Scenario loading/validation
│   ├── RoleManager.lua         # Role assignment
│   ├── LocationManager.lua     # Location system
│   ├── ClueManager.lua         # Clue distribution
│   └── AccusationManager.lua   # Accusation handling
│
├── ui/                         # User interface
│   ├── HostUI.lua              # Host controls
│   └── PlayerUI.lua            # Player interface
│
├── net/                        # Network communication
│   └── NetworkManager.lua      # Message handling
│
└── data/                       # Game data
    └── scenarios/
        └── missing_brew.lua    # First scenario
```

---

## Current Status

### ✓ Completed (Phase 1)

- [x] Directory structure
- [x] Core modules (GameController, ScenarioManager, etc.)
- [x] Basic UI (Host and Player)
- [x] Network system
- [x] First scenario: "The Missing Brew"
- [x] Game registration with The Gathering Stone
- [x] TOC file integration

### 🔄 In Progress

- [ ] Location UI (map/navigation)
- [ ] Clue journal UI
- [ ] Accusation panel UI
- [ ] Phase transition animations

### 📋 Planned (Phase 2+)

- [ ] Additional scenarios
- [ ] Special roles
- [ ] Flavor text system
- [ ] Sound effects
- [ ] Statistics tracking

---

## How to Test

1. `/reload` - Reload UI
2. `/gs` - Open The Gathering Stone
3. `/gs host hearthside_secrets` - Host game
4. Select scenario and start
5. Players join and receive roles

---

## Game Flow

1. **Lobby** - Host selects scenario
2. **Gathering** - 5-10 players (including host) receive roles/secrets (1 min)
3. **Investigation** - Explore locations, share clues (5 min)
4. **Accusation** - Submit accusations (2 min)
5. **Reveal** - Solution revealed, winners determined

---

## Scenarios

### The Missing Brew

- **Theme**: Light/Fun
- **Players**: 5-10
- **Difficulty**: Easy
- **Story**: A rare keg has gone missing before the festival!

---

## Development Notes

### Architecture

- **Modular design** - Each system is independent
- **Event-driven** - Uses EventBus for communication
- **Network-ready** - All actions sync across players
- **Extensible** - Easy to add new scenarios/roles

### Key Systems

**GameController**: Manages game state and phases  
**ScenarioManager**: Loads and validates scenarios  
**RoleManager**: Assigns roles to players  
**LocationManager**: Handles location system  
**ClueManager**: Distributes and tracks clues  
**AccusationManager**: Processes accusations  
**NetworkManager**: Syncs game state

---

## Next Steps

1. Build location map UI
2. Create clue journal
3. Add accusation panel
4. Test multiplayer flow
5. Add 2-3 more scenarios

---

## Contributing

When adding new scenarios, use this structure:

```lua
{
  id = "scenario_id",
  name = "Scenario Name",
  theme = "Theme",
  playerCount = { min = 4, max = 8 },

  locations = { ... },
  roles = { ... },
  solution = { ... }
}
```

See `data/scenarios/missing_brew.lua` for complete example.

---

## Credits

**Design**: Based on SYSTEM_DESIGN.md  
**Implementation**: The Gathering Stone Team  
**Inspired by**: Social deduction games like Werewolf, Clue, and Among Us
