Metadata-Version: 2.4
Name: daemons-engine
Version: 0.1.16
Summary: A modern MUD engine - headless game engine for real-time, text-based multiplayer worlds
Author-email: Adam Huston <adamjhuston@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/adamhuston/1126
Project-URL: Documentation, https://github.com/adamhuston/1126#readme
Project-URL: Repository, https://github.com/adamhuston/1126.git
Project-URL: Issues, https://github.com/adamhuston/1126/issues
Keywords: mud,game-engine,rpg,multiplayer,websocket,fastapi
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)
Classifier: Topic :: Games/Entertainment :: Role-Playing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: alembic>=1.13.1
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: click>=8.3.1
Requires-Dist: colorama>=0.4.6
Requires-Dist: fastapi>=0.122.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: passlib[argon2]>=1.7.4
Requires-Dist: prometheus-client>=0.22.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: python-jose[cryptography]>=3.4.0
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: SQLAlchemy>=2.0.44
Requires-Dist: slowapi>=0.1.9
Requires-Dist: structlog>=25.3.0
Requires-Dist: uvicorn[standard]>=0.38.0
Requires-Dist: websockets>=15.0.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: safety>=2.0.0; extra == "dev"
Provides-Extra: client
Requires-Dist: flet>=0.21.0; extra == "client"
Dynamic: license-file

# Daemons Engine

A Python framework for building text-based multiplayer RPGs with real-time WebSocket communication.

>  **Pre-Release Beta**  API subject to change. Not recommended for production use.
>  **Latest Roadmap Release:**  Phase 16 - Cybersecurity upgrades, including input validation and production mode

---

## Quickstart

### Prerequisites

- Python 3.11 or higher
- pip (Python package manager)

### Step 1: Create Project Directory

```bash
mkdir my-game
cd my-game
```

### Step 2: Create Virtual Environment

```powershell
# Windows
python -m venv .venv
.\.venv\Scripts\Activate
```

```bash
# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
```

### Step 3: Install Daemons Engine

```bash
pip install daemons-engine
```

### Step 4: Initialize Your Game

```bash
daemons init <new_game>
```

This creates:
- `world_data/`  YAML content (rooms, NPCs, items)
- `config.py`  Server configuration
- `main.py`  Application entry point
- `alembic.ini`  Database migration config
- `alembic/`  Migration scripts

### Step 5: Set Up Database

```bash
cd <new_game>
daemons db upgrade
```

### Step 6: Run the Server
From `/<new_game>`...

```bash
# Development (auto-reload on code changes)
daemons run --reload

# Production (requires JWT secret key)
daemons run --production
```

The `--production` flag enables security hardening:
- Requires `JWT_SECRET_KEY` environment variable
- Enforces JWT issuer/audience validation
- Runs without auto-reload

If `JWT_SECRET_KEY` is not set, you'll be prompted to generate one.

You should see:

```
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.
```

### Step 7: Connect a Client

**Option A: Reference Client**

```bash
pip install flet
daemons client
```

**Option B: Build Your Own**

Connect via WebSocket to `ws://127.0.0.1:8000/ws/game/auth`.

**Test Credentials:**
- Username: `testplayer1` / Password: `testpass1`
- Username: `testplayer2` / Password: `testpass2`

---

## Create Game Content

All content is defined in YAML files under `world_data/`.

### Example Room (`world_data/rooms/tavern.yaml`)

```yaml
id: tavern_main
name: "The Rusty Tankard"
description: |
  A cozy tavern with a crackling fireplace.
room_type: indoor
area_id: starter_town
exits:
  north: town_square
```

### Example NPC (`world_data/npcs/barkeeper.yaml`)

```yaml
id: npc_barkeeper
name: "Greta the Barkeeper"
description: "A stout woman with a warm smile."
level: 5
behaviors:
  - merchant
spawn_room: tavern_main
```

---

## Project Structure

```
my-game/
 world_data/              # Your game content
    rooms/               # Room definitions
    items/               # Items and equipment
    npcs/                # NPC templates
    quests/              # Quest definitions
    dialogues/           # NPC dialogue trees
 alembic/                 # Database migrations
 config.py                # Server configuration
 main.py                  # Application entry point
 dungeon.db               # SQLite database
```

---

## Quick Reference

| Task | Command |
|------|---------|
| Initialize project | `daemons init` |
| Run migrations | `daemons db upgrade` |
| Start server (dev) | `daemons run --reload` |
| Start server (prod) | `daemons run --production` |
| Run client | `daemons client` |

| URL | Description |
|-----|-------------|
| http://127.0.0.1:8000/docs | Swagger API docs |
| http://127.0.0.1:8000/redoc | ReDoc API docs |

---

## Documentation

Coming soon

---

## License

MIT License  see [LICENSE](LICENSE) for details.
