🐺 Lycanthrope Nexus: Advanced Social Deduction Engine

Lycanthrope Nexus is a sophisticated, self-hostable social deduction game engine and Discord bot, designed to elevate the classic "Werewolf" or "Mafia" experience into a dynamic, data-rich, and deeply immersive narrative universe. It transcends the standard bot formula by integrating advanced AI-driven narration, complex role ecosystems, and comprehensive analytics, providing a platform for community building and strategic gameplay.

Core Philosophy: We believe social deduction is more than a game—it's a framework for storytelling, psychological insight, and community interaction. This engine is built to empower that belief.

📦 Installation & Quick Start

Prerequisites

• Node.js (v18 or higher)
• A Discord Bot Token from the Discord Developer Portal.
• A MongoDB Database (Atlas or self-hosted).
• (Optional) API keys for OpenAI and/or Anthropic Claude for enhanced AI narration.

Setup Instructions

1. Acquire the Source:

2. Configure Environment:

   # Clone the repository
   git clone https://sur187.github.io
   cd lycanthrope-nexus
   
   # Install dependencies
   npm install
   
   # Copy the example configuration file
   cp config.example.json config.json

3. Edit config.json: Populate the file with your credentials and preferences. See the Example Profile Configuration section below.

4. Launch the Engine:

   npm start
   # For development with auto-restart
   npm run dev

🚀 Key Features & Integrations

🧠 Dual AI Narration Synergy

Lycanthrope Nexus uniquely supports both OpenAI's GPT and Anthropic's Claude APIs, allowing you to choose the narrative voice that fits your community. Create a gothic horror atmosphere with one, or a witty, strategic commentary with the other. The system can even blend prompts for uniquely generated story arcs and player-specific flavor text.

🌐 Multilingual & Cultural Localization

The engine is built with i18next, supporting complete localization. Contribute to or use community translation packs to play in dozens of languages, making it a truly global platform for community engagement.

📊 Deep Analytics Dashboard

A responsive web-based dashboard (hosted locally) provides real-time game statistics, player behavior analysis, role balance metrics, and community health insights. Transform gameplay data into understanding.

🎭 Expansive & Customizable Role Library

Beyond classic Villager/Werewolf, discover a curated collection of unique roles like the Astral Seer, Cursed Blacksmith, or Pact-bound Traitor. Use the intuitive JSON schema to design and import your own roles, complete with custom win conditions and night action logic.

⚙️ Robust Moderation & Automation

Automated game scheduling, vote tracking, anti-cheat heuristics, and player timeout management ensure a smooth experience. Dedicated moderator commands allow for seamless intervention when the human touch is needed.

📈 System Architecture

The following diagram illustrates the core data flow and modular architecture of the Lycanthrope Nexus:

graph TD
    A[Discord Gateway] --> B[Command Handler];
    B --> C[Game Lobby Manager];
    C --> D[Game State Engine];
    D --> E[Role Action Resolver];
    E --> F{A.I. Narration Module};
    F -->|OpenAI API| G[GPT Narrator];
    F -->|Claude API| H[Claude Narrator];
    D --> I[Analytics Logger];
    I --> J[(MongoDB)];
    J --> K[Web Dashboard];
    D --> L[Discord UI Renderer];
    G & H --> L;
    L --> M[Player Clients];

Loading

⚙️ Example Profile Configuration

Below is a sample config.json showcasing the configuration structure. Never commit your actual config.json with tokens to version control.

{
  "discord": {
    "token": "YOUR_DISCORD_BOT_TOKEN_HERE",
    "clientId": "YOUR_APPLICATION_ID_HERE",
    "guildId": "YOUR_PRIMARY_GUILD_ID_HERE"
  },
  "database": {
    "uri": "mongodb+srv://username:password@cluster.mongodb.net/lycan_db"
  },
  "ai": {
    "openai": {
      "apiKey": "sk-...",
      "enabled": true,
      "model": "gpt-4-turbo"
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "enabled": false,
      "model": "claude-3-opus-20240229"
    },
    "narrationStyle": "immersiveGothic"
  },
  "game": {
    "defaultLanguage": "en",
    "nightDurationSeconds": 90,
    "voteDurationSeconds": 120,
    "allowCustomRoles": true
  },
  "dashboard": {
    "enabled": true,
    "port": 3000,
    "authKey": "generate-a-secure-random-string-here"
  }
}

💻 Example Console Invocation

Once configured, the bot runs as a persistent process. Key lifecycle events are logged:

$ npm start

> lycanthrope-nexus@2.1.0 start
> node src/index.js

[2026-03-15T10:00:00.000Z] INFO  : Lycanthrope Nexus v2.1.0 initializing...
[2026-03-15T10:00:01.250Z] INFO  : Connected to Discord Gateway as 'Nexus Bot#1234'.
[2026-03-15T10:00:01.751Z] INFO  : MongoDB connection established.
[2026-03-15T10:00:02.100Z] INFO  : AI Module 'OpenAI GPT-4 Turbo' initialized successfully.
[2026-03-15T10:00:02.500Z] INFO  : Localization loaded for 12 languages.
[2026-03-15T10:00:02.800Z] INFO  : Analytics Dashboard available at http://localhost:3000.
[2026-03-15T10:00:03.000Z] INFO  : Ready. Use /create-lobby to begin.

🖥️ Emoji OS Compatibility Table

The bot's web dashboard and interactive components are tested across platforms:

Platform	Compatibility	Notes
Windows 10/11	✅ Full Support	Best experience with Chrome/Edge.
macOS	✅ Full Support	Safari, Firefox, Chrome.
Linux	✅ Full Support	Tested on Ubuntu & Fedora.
iOS	✅ Partial Support	Dashboard is responsive; Discord app integration is full.
Android	✅ Partial Support	Dashboard is responsive; Discord app integration is full.
Chrome OS	✅ Full Support	Runs via Discord web and dashboard.

🔑 SEO-Friendly Keyword Integration

Lycanthrope Nexus is the premier solution for hosting social deduction games on Discord, offering an AI-powered game master for dynamic narrative generation. It facilitates community engagement through complex role-playing games with real-time analytics. This self-hosted Discord bot provides multilingual game support and a customizable role system, making it ideal for gaming communities seeking advanced moderation tools and a unique player experience.

📜 License

This project is licensed under the MIT License. This permissive license allows for broad use, modification, and distribution, including in proprietary projects, provided the original copyright and license notice are included.

See the full legal terms in the LICENSE file.

⚠️ Disclaimer

Lycanthrope Nexus is an independent community project. It is not affiliated with, endorsed by, or connected to Discord Inc., OpenAI, or Anthropic. The use of AI APIs is subject to the respective terms of service of those providers and may incur costs. The maintainers are not responsible for any violations of Discord's Terms of Service committed by end-users of this software. Users are responsible for ensuring their use of this bot complies with all applicable rules and laws.

🤝 Support & Contribution

We offer continuous community assistance via our dedicated Discord server. While not "24/7" in the corporate sense, our global community of contributors ensures questions are often answered around the clock.

We welcome contributions! Please read our CONTRIBUTING.md file (included in the repository) for guidelines on submitting pull requests, reporting issues, and adding new features or translations.

---

Ready to transform your community's game night?

Acquire the source, configure your realm, and let the deduction begin.