221 lines
5.5 KiB
Markdown
221 lines
5.5 KiB
Markdown
# 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.
|