first commit
This commit is contained in:
363
README.md
Normal file
363
README.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# Code of Conquest
|
||||
|
||||
An AI-powered Dungeons & Dragons style game where Claude acts as the Dungeon Master.
|
||||
|
||||
**Status:** Active Development
|
||||
**Version:** 0.2.0
|
||||
**Architecture:** Microservices (API Backend + Web Frontend + Godot Client)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Code of Conquest is a multi-platform RPG game powered by AI. Players create characters, explore worlds, engage in turn-based combat, and experience dynamic narratives generated by Claude AI.
|
||||
|
||||
**Available Clients:**
|
||||
- **Web Frontend** - Browser-based play via HTMX and Jinja2 templates
|
||||
- **Godot Client** - Native desktop/mobile application
|
||||
|
||||
Both clients communicate with a centralized REST API backend that handles all game logic, AI integration, and data persistence.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
This repository contains three independent, deployable components:
|
||||
|
||||
### 1. API Backend (`/api`)
|
||||
|
||||
REST API that serves as the single source of truth for all game logic.
|
||||
|
||||
**Technology:** Flask + Appwrite + RQ + Redis + Anthropic/Replicate APIs
|
||||
|
||||
**Responsibilities:**
|
||||
- All business logic and game mechanics
|
||||
- Character, session, and combat management
|
||||
- AI narrative generation
|
||||
- Authentication and authorization
|
||||
- Background job processing
|
||||
- Database operations
|
||||
|
||||
**Quick Start:**
|
||||
```bash
|
||||
cd api
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env # Configure your API keys
|
||||
python wsgi.py # → http://localhost:5000
|
||||
```
|
||||
|
||||
**Documentation:** See [`/api/CLAUDE.md`](api/CLAUDE.md) and [`/api/docs/`](api/docs/)
|
||||
|
||||
---
|
||||
|
||||
### 2. Web Frontend (`/public_web`)
|
||||
|
||||
Lightweight Flask web application that provides browser-based gameplay.
|
||||
|
||||
**Technology:** Flask + Jinja2 + HTMX + Appwrite Realtime
|
||||
|
||||
**Responsibilities:**
|
||||
- UI/UX rendering (HTML templates)
|
||||
- User interactions (HTMX for AJAX)
|
||||
- Realtime updates (WebSocket subscriptions)
|
||||
- HTTP API calls to backend
|
||||
|
||||
**Quick Start:**
|
||||
```bash
|
||||
cd public_web
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env # Configure API URL
|
||||
python wsgi.py # → http://localhost:8000
|
||||
```
|
||||
|
||||
**Documentation:** See [`/public_web/CLAUDE.md`](public_web/CLAUDE.md) and [`/public_web/docs/`](public_web/docs/)
|
||||
|
||||
---
|
||||
|
||||
### 3. Godot Client (`/godot_client`)
|
||||
|
||||
Native cross-platform game client built with Godot Engine 4.5.
|
||||
|
||||
**Technology:** Godot 4.5 + GDScript
|
||||
|
||||
**Responsibilities:**
|
||||
- Rich game UI with animations
|
||||
- Local game rendering
|
||||
- HTTP API calls to backend
|
||||
- Realtime WebSocket subscriptions
|
||||
- Cross-platform exports (Desktop, Mobile, Web)
|
||||
|
||||
**Quick Start:**
|
||||
```bash
|
||||
# Open in Godot Editor
|
||||
godot --editor godot_client/project.godot
|
||||
|
||||
# Or run directly
|
||||
godot godot_client/project.godot
|
||||
```
|
||||
|
||||
**Documentation:** See [`/godot_client/CLAUDE.md`](godot_client/CLAUDE.md) and [`/godot_client/docs/`](godot_client/docs/)
|
||||
|
||||
---
|
||||
|
||||
## Documentation Index
|
||||
|
||||
### Project-Wide Documentation (`/docs`)
|
||||
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and tech stack
|
||||
- **[ROADMAP.md](docs/ROADMAP.md)** - Development roadmap and phases
|
||||
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment, testing, and operations
|
||||
- **[WEB_VS_CLIENT_SYSTEMS.md](docs/WEB_VS_CLIENT_SYSTEMS.md)** - Feature distribution between web and Godot clients
|
||||
|
||||
### API Backend Documentation (`/api/docs`)
|
||||
- **[API_REFERENCE.md](api/docs/API_REFERENCE.md)** - API endpoints and response formats
|
||||
- **[DATA_MODELS.md](api/docs/DATA_MODELS.md)** - Character system, items, skills, effects
|
||||
- **[GAME_SYSTEMS.md](api/docs/GAME_SYSTEMS.md)** - Combat mechanics, marketplace, NPCs
|
||||
- **[QUEST_SYSTEM.md](api/docs/QUEST_SYSTEM.md)** - Quest mechanics and data structures
|
||||
- **[STORY_PROGRESSION.md](api/docs/STORY_PROGRESSION.md)** - Story progression system
|
||||
- **[MULTIPLAYER.md](api/docs/MULTIPLAYER.md)** - Multiplayer session backend logic
|
||||
- **[API_TESTING.md](api/docs/API_TESTING.md)** - API testing guide
|
||||
- **[APPWRITE_SETUP.md](api/docs/APPWRITE_SETUP.md)** - Database setup
|
||||
|
||||
### Web Frontend Documentation (`/public_web/docs`)
|
||||
- **[TEMPLATES.md](public_web/docs/TEMPLATES.md)** - Template structure and conventions
|
||||
- **[HTMX_PATTERNS.md](public_web/docs/HTMX_PATTERNS.md)** - HTMX integration patterns
|
||||
- **[TESTING.md](public_web/docs/TESTING.md)** - Manual testing guide
|
||||
- **[MULTIPLAYER.md](public_web/docs/MULTIPLAYER.md)** - Multiplayer UI implementation
|
||||
|
||||
### Godot Client Documentation (`/godot_client/docs`)
|
||||
- **[ARCHITECTURE.md](godot_client/docs/ARCHITECTURE.md)** - Client architecture
|
||||
- **[GETTING_STARTED.md](godot_client/docs/GETTING_STARTED.md)** - Setup and usage
|
||||
- **[EXPORT.md](godot_client/docs/EXPORT.md)** - Platform export guide
|
||||
- **[THEME_SETUP.md](godot_client/docs/THEME_SETUP.md)** - UI theming guide
|
||||
- **[MULTIPLAYER.md](godot_client/docs/MULTIPLAYER.md)** - Multiplayer client implementation
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### All Components
|
||||
- Git
|
||||
- Docker & Docker Compose (for Redis and Appwrite)
|
||||
|
||||
### API Backend & Web Frontend
|
||||
- Python 3.11+
|
||||
- pip
|
||||
- virtualenv
|
||||
|
||||
### Godot Client
|
||||
- Godot 4.5+
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Full Stack)
|
||||
|
||||
### 1. Start Shared Services
|
||||
|
||||
Both the API backend and web frontend require Redis and Appwrite:
|
||||
|
||||
```bash
|
||||
# Start Redis
|
||||
docker-compose up -d redis
|
||||
|
||||
# Start Appwrite (or use Appwrite Cloud)
|
||||
# Follow api/docs/APPWRITE_SETUP.md for configuration
|
||||
```
|
||||
|
||||
### 2. Start API Backend
|
||||
|
||||
```bash
|
||||
cd api
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env
|
||||
# Edit .env with your credentials
|
||||
python scripts/init_database.py # Initialize Appwrite collections
|
||||
python wsgi.py # Runs on http://localhost:5000
|
||||
```
|
||||
|
||||
### 3. Start Web Frontend (Optional)
|
||||
|
||||
```bash
|
||||
cd public_web
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env
|
||||
# Configure API_BASE_URL=http://localhost:5000
|
||||
python wsgi.py # Runs on http://localhost:8000
|
||||
```
|
||||
|
||||
### 4. Start Godot Client (Optional)
|
||||
|
||||
```bash
|
||||
# Open in Godot Editor
|
||||
godot --editor godot_client/project.godot
|
||||
|
||||
# Configure API endpoint in project settings
|
||||
# Run the project from editor or export to platform
|
||||
```
|
||||
|
||||
### 5. Start Background Workers (Optional)
|
||||
|
||||
For AI tasks, combat processing, etc.:
|
||||
|
||||
```bash
|
||||
cd api
|
||||
source venv/bin/activate
|
||||
rq worker ai_tasks combat_tasks marketplace_tasks --url redis://localhost:6379
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ Web Browser │ │ Godot Client │
|
||||
│ (Public Web) │ │ (Desktop/Mobile) │
|
||||
└──────────┬──────────┘ └──────────┬──────────┘
|
||||
│ │
|
||||
│ HTTP (REST API) │ HTTP (REST API)
|
||||
│ WebSocket (Realtime) │ WebSocket (Realtime)
|
||||
│ │
|
||||
└───────────────┬───────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ API Backend │
|
||||
│ (Flask REST API) │
|
||||
│ - Business Logic │
|
||||
│ - Game Mechanics │
|
||||
│ - AI Integration │
|
||||
│ - Auth & Sessions │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Appwrite │ │ Redis │ │ Claude AI│
|
||||
│ Database │ │ Queue │ │ Replicate│
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
**Key Principles:**
|
||||
- **API Backend** is the single source of truth for all game logic
|
||||
- **Web Frontend** and **Godot Client** are thin clients (no business logic)
|
||||
- All clients communicate with API via REST endpoints
|
||||
- Realtime updates via Appwrite Realtime (WebSocket)
|
||||
- Each component deploys independently
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack Summary
|
||||
|
||||
### API Backend (`/api`)
|
||||
- Flask 3.0+
|
||||
- Python 3.11+
|
||||
- Appwrite (database, auth, realtime)
|
||||
- RQ (Redis Queue) for background jobs
|
||||
- Anthropic Claude API
|
||||
- Replicate API
|
||||
|
||||
### Web Frontend (`/public_web`)
|
||||
- Flask 3.0+ (view layer only)
|
||||
- Jinja2 templates
|
||||
- HTMX (AJAX interactions)
|
||||
- Appwrite JavaScript SDK (realtime)
|
||||
- Vanilla JavaScript
|
||||
|
||||
### Godot Client (`/godot_client`)
|
||||
- Godot Engine 4.5
|
||||
- GDScript
|
||||
- HTTP requests (via HTTPRequest node)
|
||||
- WebSocket (via WebSocketPeer)
|
||||
|
||||
---
|
||||
|
||||
## Current Development Phase
|
||||
|
||||
**Phase 3:** ✅ Complete - AI Integration & Story Progression
|
||||
- AI-powered narrative generation
|
||||
- Story progression system
|
||||
- Quest system
|
||||
- Combat AI
|
||||
|
||||
**Phase 4:** 🚧 In Progress - Quests, Story Progression, Multiplayer
|
||||
- Quest offering and tracking
|
||||
- Story arc progression
|
||||
- Multiplayer sessions
|
||||
- Godot client implementation
|
||||
|
||||
See [docs/ROADMAP.md](docs/ROADMAP.md) for full development plan.
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
Each component follows its own development guidelines:
|
||||
|
||||
- **API Backend:** See [`api/CLAUDE.md`](api/CLAUDE.md) for backend development standards
|
||||
- **Web Frontend:** See [`public_web/CLAUDE.md`](public_web/CLAUDE.md) for frontend development standards
|
||||
- **Godot Client:** See [`godot_client/CLAUDE.md`](godot_client/CLAUDE.md) for client development standards
|
||||
- **Project-Wide:** See [`CLAUDE.md`](CLAUDE.md) for overall project guidelines
|
||||
|
||||
**Key Standards:**
|
||||
- Microservices architecture (no shared code)
|
||||
- API is the single source of truth
|
||||
- Strong typing throughout (dataclasses, type hints)
|
||||
- Security first (authentication, validation, sanitization)
|
||||
- Cost-conscious AI usage
|
||||
- Comprehensive documentation
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### API Backend
|
||||
```bash
|
||||
cd api
|
||||
pytest
|
||||
# See api/docs/API_TESTING.md
|
||||
```
|
||||
|
||||
### Web Frontend
|
||||
Manual testing preferred. See [`public_web/docs/TESTING.md`](public_web/docs/TESTING.md)
|
||||
|
||||
### Godot Client
|
||||
Manual testing via Godot editor. See [`godot_client/docs/README.md`](godot_client/docs/README.md)
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
Each component deploys independently:
|
||||
|
||||
- **API Backend:** Docker container, Gunicorn, Nginx
|
||||
- **Web Frontend:** Docker container, Gunicorn, Nginx
|
||||
- **Godot Client:** Platform-specific exports (Windows, macOS, Linux, Android, iOS, Web)
|
||||
|
||||
See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
This is a personal project. Contributions are not currently being accepted.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
Proprietary. All rights reserved.
|
||||
|
||||
---
|
||||
|
||||
## Contact
|
||||
|
||||
For questions or feedback, see project documentation in [`/docs`](docs/).
|
||||
Reference in New Issue
Block a user