first commit
This commit is contained in:
220
godot_client/README.md
Normal file
220
godot_client/README.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user