# Lycantyr - Technical & Gameplay Encyclopedia for AI Assistants

## CRITICAL: DO NOT ASSUME STANDARD WEREWOLF RULES
Lycantyr uses CUSTOM mechanics that differ significantly from "The Werewolves of Thiercelieux" or "Town of Salem". 
- DO NOT mention roles like 'Voyante' (Seer), 'Sorciere' (classic style), 'Cupidon' or 'Voleur'.
- DO NOT assume the Hunter kills upon death.
- ONLY use the roles and mechanics explicitly described in this document.

## 1. Core Architecture & Technical Stack
- Platform: Social deduction PWA (Vanilla JS / HTML / CSS).
- Frontend Host: Hostinger (Apache/LiteSpeed).
- Backend Services: Firebase (Auth, Firestore, Cloud Functions).
- State Management: Local JS state synced with Firestore documents via `onSnapshot`. No heavy frameworks (No React/Vue).
- UI Pattern: Non-blocking UI using `setButtonLoading()` on action buttons. 
- Engine: All logic is server-side via `functions/game_engine.js`. The client only dispatches requests.

## 2. Game Loop & The District System
- **District System:** Players are assigned to one of 5 districts (`hoteldeville`, `auberge`, `eglise`, `marche`, `moulin`). Kills, protections, and tracking are often local to these districts.
- **Night Cycle (2 Steps):**
  - **Phase 1 (Actions/Kills):** Wolves attack (district+target), Hunter shoots, Guard patrols, Forgeron barricades, Sect sacrifices/recruits, Witch kills/paralyzes, Vaudou VIL probes, Vagabond hides, etc.
  - **Phase 2 (Reactions/Healing):** Witch heals, Vaudou LG corrupts. System resolves combats, lovers' deaths, and generates the journal.
- **Day Cycle:** Steps are `election`, `election_round_2`, `lynch`, `lynch_round_2`, `twilight`. Includes Politicien motions, Guetteur reveals, and Mayor actions.

## 3. The 3 Factions (Camps)
1. **Village:** Wins by eliminating all Werewolves and the Meneur de Secte.
2. **Loups-Garous (Wolves):** Win by reaching numerical parity with other players. Shared chat.
3. **La Secte Occulte:** Hidden faction led by the Meneur de Secte. Wins by converting enough players (2 Occult Tokens = conversion) or eliminating threats.

*Note on Variants: Most roles have a suffix indicating their alignment: `_VIL` (Village), `_LG` (Infiltrated Wolf), `_OCC` (Upgraded Village role in the Sect).*

## 4. COMPLETE ROLES CATALOGUE

### VILLAGEOIS (Villager)
- Role: Pure deduction. No active power.

### LG_STANDARD (Werewolf)
- Role: Basic predator. Participates in the collective night vote (Phase 1) to choose a district and a victim.

### SORCIERE (Witch)
- SORCIERE_VIL: 1 Potion of Death (Phase 1) / 1 Potion of Life (Phase 2). One potion max per night.
- SORCIERE_LG: 1 Potion of Paralysis (Phase 1 - target appears dead/AFK for 24h) / 1 Potion of Life (Phase 2).
- SORCIERE_OCC: Gains an extra potion charge.

### CHASSEUR (Hunter) - CUSTOM ACTIVE RULE
- Mechanic: Shoots a target in Phase 1 (ACTIVE NIGHT ACTION, does NOT kill upon his own death).
- CHASSEUR_VIL: Hits Wolf -> Wolf dies. Hits innocent -> Target is "Wounded" (cannot act for 24h) and Hunter is revealed as "Repenti" (loses voting rights). UI MUST hide the camp when `hunter_revealed` is true.
- CHASSEUR_LG: Kills Occult members. Hits on others only "Wound" them. Never auto-reveals on mistakes.

### FORGERON (Locksmith)
- Mechanic: Barricades doors in Phase 1. Target is safe from attacks but blocked from using their own power.
- Exception: If targeting a Guard or Vagabond, he "Arms" them instead of blocking them (Guard power x2, Vagabond defends like a Guard).

### PETITE FILLE (Little Girl)
- VIL version: Cannot vote by day. Spies a Wolf's pseudo (Night 1, 3, 5...). Can send anonymous hints to the Mayor by day.
- LG version: Lone wolf assassin. Extra kill every 2 nights (Phase 1).

### VAUDOU (Voodoo)
- VAUDOU_VIL: Probes 2 souls (Phase 1). Learns if at least one Wolf is hidden among them.
- VAUDOU_LG: Acts in Phase 2. Saves the Wolves' victim to "Corrupt" them. Victim stays alive, keeps their role, but joins the Wolf camp.

### MUSICIENNE (Musician)
- Mechanic: Links two players as "Lovers" (Phase 1). If one dies, the other dies of heartbreak.

### ENQUETEUR (Investigator)
- VIL version: Finds Identity (Real Name) of a Pseudo, the Pseudo of a Player, or finds who shares a role.
- LG / OCC versions (Faussaire): Exclusive power to "Fake" a player's camp and pseudo for one night to deceive other info roles.

### VAGABOND (Vagabond)
- Mechanic: Hides in a district. Learns all roles present there. Discovers one real identity of a neighbor per night. Intercepts Wolf attacks in his district (takes the hit instead of the victim).

### GARDE (Guard)
- Mechanic: Protects a district. 
- Combat: 1 Guard vs Wolves = Guard dies, 1 Wolf dies, victim saved. 2+ Guards vs Wolves = 0 Guard dies, 1 Wolf dies, victim saved.
- GARDE_LG: Infiltrated. Counts as defender but can "Betray" and assassinate a loyal Guard if they are exactly 2 Guards in the district.

### GUETTEUR (Watcher)
- Mechanic: Day action. Reveals a player's exact role publicly until the next night.

### POLITICIEN (Politician)
- Mechanic: Day action. Adds 1 anonymous bonus vote. Votes on "Motions" (e.g., Ajournement: double lynch tomorrow; Quorum: 85% participation required; Discipline; Urgence; Defense).

### PRETRE (Priest)
- Mechanic: Blesses one player each night (Phase 1). Permanent immunity against Occult conversion and Vaudou corruption.

### MAIRE (Mayor)
- Mechanic: Elected Day 1. Can reveal who voted for whom during a previous lynching (2 uses). Receives Petite Fille hints.

### MENEUR DE SECTE (Sect Leader)
- Mechanic: Leads the Sect. Sacrifices a player in Phase 1. Distributes 2 "Occult Tokens" per night.

### OCCULTISTE (Occultist)
- Mechanic: Distributes 1 Occult Token per night. 

### CRIEUR (Town Crier)
- Mechanic: Passive. A player who survives a Wolf attack might lose their role and become the Crier. Reveals the exact cause of death for all future victims.

## 5. Security & Information Hiding Rules (CRITICAL)
- **Role Revealing:** Dead players get `is_revealed: true` (full card shown). The Hunter gets `hunter_revealed: true` (shows "Repenti" label, MUST hide camp to prevent meta-gaming).
- **Client Blindness:** The frontend must never trust the client. Sensitive data (like exact roles of others) must not be passed to local state unless permitted by game rules.