# Code of Conquest - Godot Client

Native desktop, mobile, and web client for Code of Conquest, built with Godot 4.

## Overview

This is the frontend client that connects to the Flask backend API (`/app`) to provide a native game experience across all platforms.

## Project Structure

```
godot_client/
├── project.godot           # Main project configuration
├── scenes/                 # Scene files (.tscn)
│   ├── auth/              # Authentication screens
│   ├── character/         # Character management screens
│   ├── combat/            # Combat interface
│   └── world/             # World exploration
├── scripts/               # GDScript files
│   ├── services/          # Singleton services (HTTP, State)
│   ├── models/            # Data models matching backend
│   └── utils/             # Helper functions
└── assets/                # Resources
    ├── fonts/             # Custom fonts (Cinzel, Lato)
    ├── themes/            # UI themes
    └── ui/                # UI assets (icons, images)
```

## Prerequisites

- **Godot Engine 4.5**: Download from [godotengine.org](https://godotengine.org/)
- **Flask Backend**: Must be running (see `/app` directory)

## Setup

1. **Install Godot 4.5**
   ```bash
   # Download from official site or use package manager
   # For Ubuntu/Debian:
   sudo snap install godot-4
   ```

2. **Open Project**
   - Launch Godot
   - Click "Import"
   - Navigate to `godot_client/project.godot`
   - Click "Import & Edit"

3. **Configure Backend URL**
   - Edit `scripts/services/http_client.gd`
   - Set `API_BASE_URL` to your Flask backend (default: `http://localhost:5000`)

4. **Install Fonts** (if needed)
   - Download Cinzel and Lato fonts
   - Place in `assets/fonts/`
   - Reimport in Godot

## Running the Game

### From Godot Editor
1. Open project in Godot
2. Press F5 (or click Play button)
3. Game launches in development mode

### Exported Builds
See "Export" section below

## Development

### Backend Connection

The game communicates with the Flask backend via REST API:
- Base URL configured in `HTTPClient` singleton
- All API calls go through `HTTPClient.request()` method
- Authentication token stored in `StateManager`

### State Management

- `StateManager` singleton handles global app state
- User session, character data, wizard state
- Persists to local storage between sessions

### Scene Flow

```
Main Scene (initial load)
  ↓
Login/Register (if not authenticated)
  ↓
Character List (main menu)
  ↓
Character Creation Wizard (if creating new)
  ↓
Game World / Combat
```

## Export

### Desktop (Windows, Mac, Linux)

1. In Godot: Project → Export
2. Select platform template
3. Export project
4. Distribute executable + pck file

### Mobile (iOS, Android)

**Android:**
1. Install Android SDK
2. Configure export template
3. Set keystore for signing
4. Export APK/AAB

**iOS:**
1. Requires macOS + Xcode
2. Configure provisioning profile
3. Export Xcode project
4. Build in Xcode

### Web (HTML5/WebAssembly)

1. Export to HTML5
2. Serve via HTTP server (HTTPS recommended)
3. Can deploy to static hosting (Netlify, Vercel, etc.)

**Note:** Web builds have limitations (no threading, some GDNative features disabled)

## Testing

### Local Development
- Run Flask backend on `localhost:5000`
- Run Godot client (F5 in editor)
- Test API integration

### Platform-Specific Testing
- **Desktop**: Test on Windows, Mac, Linux builds
- **Mobile**: Test on real devices (Android/iOS)
- **Web**: Test in multiple browsers (Chrome, Firefox, Safari)

## API Integration

### Authentication Flow

1. User enters credentials in login screen
2. Client calls `POST /api/v1/auth/login`
3. Backend returns JWT token
4. Token stored in `StateManager`
5. Token sent in `Authorization` header for protected endpoints

### Character Management

- Create character: `POST /api/v1/characters`
- List characters: `GET /api/v1/characters`
- Get character: `GET /api/v1/characters/<id>`
- Delete character: `DELETE /api/v1/characters/<id>`

All endpoints expect/return JSON matching backend data models.

## Architecture

### Services (Singletons)

**HTTPClient** (`scripts/services/http_client.gd`):
- Wraps Godot's HTTPRequest node
- Handles JSON serialization/deserialization
- Manages auth tokens
- Error handling and retries

**StateManager** (`scripts/services/state_manager.gd`):
- Global application state
- User session management
- Character creation wizard state
- Navigation/routing state
- Persistence to local storage

### Data Models

GDScript classes in `scripts/models/` mirror Python dataclasses:
- `Character.gd`
- `CharacterClass.gd`
- `Origin.gd`
- `Skill.gd`
- etc.

### UI Components

Reusable scenes in `scenes/components/`:
- `Button.tscn` - Styled button
- `Card.tscn` - Card container
- `FormField.tscn` - Input field with label
- `ProgressIndicator.tscn` - Wizard progress

## Troubleshooting

### "Failed to connect to backend"
- Ensure Flask backend is running
- Check `API_BASE_URL` in `http_client.gd`
- Verify CORS headers if running on web

### "Authentication failed"
- Check Flask backend logs
- Verify token storage in StateManager
- Clear local storage and re-login

### Export issues
- Ensure export templates are installed
- Check platform-specific requirements
- Review Godot export documentation

## Contributing

Follow the same standards as the main project (see `/CLAUDE.md`):
- Type hints on all functions
- Docstrings for public methods
- Clear variable names
- Comments explaining complex logic

## License

Same as main project.