Code_of_Conquest/godot_client/README.md

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
• Flask Backend: Must be running (see /app directory)

Setup

1. Install Godot 4.5

   # 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.