Code_of_Conquest/godot_client/docs/GETTING_STARTED.md

Getting Started with Godot Client

Phase 1 Complete! ✓

The foundation for the Godot client is now in place. Here's what's been created:

What's Built

✅ Project Structure: Complete directory organization ✅ Core Services: HTTPClient and StateManager singletons ✅ Theme System: Color palette and styling utilities ✅ UI Components: CustomButton, Card, FormField ✅ Documentation: Architecture, themes, components, export

Project Structure

godot_client/
├── project.godot              # Main project file
├── README.md                  # Project overview
├── ARCHITECTURE.md            # Architecture documentation
├── THEME_SETUP.md             # Theme and font setup guide
├── EXPORT.md                  # Export configuration guide
├── GETTING_STARTED.md         # This file
│
├── scenes/
│   ├── auth/                  # Authentication screens (TODO)
│   ├── character/             # Character management (TODO)
│   ├── combat/                # Combat UI (TODO)
│   ├── world/                 # World exploration (TODO)
│   └── components/            # Reusable UI components
│       └── README.md          # Component documentation
│
├── scripts/
│   ├── services/
│   │   ├── http_client.gd    # ✓ API communication service
│   │   └── state_manager.gd  # ✓ Global state management
│   ├── models/                # Data models (TODO)
│   ├── utils/
│   │   └── theme_colors.gd   # ✓ Color palette
│   └── components/
│       ├── custom_button.gd  # ✓ Custom button component
│       ├── card.gd           # ✓ Card container component
│       └── form_field.gd     # ✓ Form input component
│
└── assets/
    ├── fonts/                 # Fonts (TODO: download)
    │   └── README.md          # Font installation guide
    ├── themes/                # Theme resources (TODO: create in editor)
    └── ui/                    # UI assets (icons, etc.)

Next Steps

1. Open Project in Godot

1. Download Godot 4.5 from godotengine.org

2. Launch Godot and import project:

   • Click "Import"
   • Navigate to godot_client/project.godot
   • Click "Import & Edit"

3. Install export templates (for exporting to platforms):

   • Editor → Manage Export Templates
   • Download and Install

2. Set Up Fonts

1. Download fonts:

   • Cinzel - for headings
   • Lato - for body text

2. Copy to project:

   • Extract .ttf files
   • Copy to godot_client/assets/fonts/
   • Files needed:
     • Cinzel-Regular.ttf, Cinzel-Medium.ttf, Cinzel-SemiBold.ttf, Cinzel-Bold.ttf
     • Lato-Regular.ttf, Lato-Bold.ttf, Lato-Italic.ttf

3. Reimport in Godot (automatic, or click "Reimport" in FileSystem panel)

See THEME_SETUP.md for details.

3. Create Main Theme

1. Create theme resource:

   • Right-click assets/themes/ in Godot FileSystem
   • New Resource → Theme
   • Save as main_theme.tres

2. Configure theme (see THEME_SETUP.md):

   • Set default font to Lato-Regular.ttf
   • Configure button colors and styleboxes
   • Configure panel styleboxes
   • Configure input field styles

3. Set project theme:

   • Project → Project Settings → GUI → Theme
   • Set Custom Theme to res://assets/themes/main_theme.tres

4. Configure Backend URL

Edit scripts/services/http_client.gd:

# Line 16
const API_BASE_URL := "http://localhost:5000"  # Change if needed

For production, you might use:

• https://api.codeofconquest.com
• Or make it configurable via settings

5. Create Main Scene

Create scenes/main.tscn:

1. Scene → New Scene
2. Root node: Control
3. Add script: scripts/main.gd

main.gd:

extends Control

func _ready() -> void:
    print("Code of Conquest starting...")

    # Check if authenticated
    if StateManager.is_authenticated():
        print("User authenticated, loading character list...")
        # TODO: Navigate to character list
    else:
        print("Not authenticated, showing login...")
        # TODO: Navigate to login

4. Set as main scene:
   • Project → Project Settings → Application → Run
   • Set Main Scene to res://scenes/main.tscn

6. Test Services

Create a test scene to verify services work:

scenes/test_services.tscn:

• Root: Control
• Add: Button ("Test API")

test_services.gd:

extends Control

@onready var test_button = $TestButton

func _ready():
    test_button.pressed.connect(_on_test_clicked)

func _on_test_clicked():
    print("Testing HTTPClient...")

    # Test API call (replace with real endpoint)
    # Note: Can use HTTPClient directly in _ready() or later
    HTTPClient.http_get("/api/v1/health", _on_api_success, _on_api_error)

    # Alternative (always works):
    # get_node("/root/HTTPClient").http_get("/api/v1/health", _on_api_success, _on_api_error)

func _on_api_success(response):
    print("API Success!")
    print("Status: ", response.status)
    print("Result: ", response.result)

func _on_api_error(response):
    print("API Error!")
    print("Error: ", response.get_error_message())

Note: If you get "Static function not found" errors, use get_node("/root/HTTPClient") instead of direct HTTPClient access.

Run this scene (F6) and click the button to test API connectivity.

Phase 2: Authentication Screens

Once the foundation is set up, proceed with Phase 2 (Week 2):

Auth Screens to Build

1. Login Screen (scenes/auth/login.tscn)

   • Email and password fields (using FormField)
   • Login button (using CustomButton)
   • Links to register and forgot password

2. Register Screen (scenes/auth/register.tscn)

   • Email, password, confirm password
   • Validation
   • Register button

3. Forgot Password (scenes/auth/forgot_password.tscn)

   • Email field
   • Send reset link button

4. Reset Password (scenes/auth/reset_password.tscn)

   • New password and confirm
   • Reset button

5. Email Verification (scenes/auth/verify_email.tscn)

   • Verification status display

Example: Login Screen

1. Create scene: scenes/auth/login.tscn

2. Root: Control node

3. Add:

   • Card container (center of screen)
   • FormField for email
   • FormField for password
   • CustomButton for login
   • Label for errors

4. Attach script: scenes/auth/login.gd

See ARCHITECTURE.md for complete login implementation example.

Helpful Resources

Documentation Created

• README.md - Project overview, setup, and development guide
• ARCHITECTURE.md - Complete architecture documentation with examples
• THEME_SETUP.md - Theme creation and font setup
• EXPORT.md - Platform export configuration
• scenes/components/README.md - UI component guide

External Resources

• Godot Documentation
• GDScript Reference
• Godot UI Tutorials

Common Issues

"Autoload not found" error

Problem: HTTPClient or StateManager not found Solution: Check project.godot has these lines in [autoload] section:

HTTPClient="*res://scripts/services/http_client.gd"
StateManager="*res://scripts/services/state_manager.gd"

"Class ThemeColors not found"

Problem: ThemeColors class not recognized Solution:

1. Check file exists at scripts/utils/theme_colors.gd
2. Restart Godot (to refresh script cache)
3. Ensure class_name ThemeColors is at top of file

API calls failing

Problem: HTTPClient can't connect to Flask backend Solution:

1. Ensure Flask backend is running on localhost:5000
2. Check API_BASE_URL in http_client.gd
3. Check Flask CORS settings if running on different port/domain

Fonts not showing

Problem: Custom fonts not displaying Solution:

1. Ensure .ttf files are in assets/fonts/
2. Check font imports (click font in FileSystem)
3. Verify theme is set in Project Settings

Development Workflow

Typical Development Session

1. Start Flask backend:

   cd /home/ptarrant/repos/coc
   source venv/bin/activate
   python -m flask run
   

2. Open Godot project:

   • Launch Godot
   • Open godot_client

3. Work on scene:

   • Edit scene in Godot editor
   • Attach/edit scripts
   • Test with F6 (run scene) or F5 (run project)

4. Debug:

   • Check Output panel for print statements
   • Check Debugger panel for errors
   • Use Godot debugger (breakpoints, step through)

5. Test on device:

   • Export to platform (see EXPORT.md)
   • Test on real device

Git Workflow

# Create feature branch
git checkout -b feature/login-screen

# Work on feature
# (edit files in Godot)

# Commit changes
git add godot_client/
git commit -m "feat: implement login screen UI"

# Merge to dev
git checkout dev
git merge feature/login-screen

# When ready for production
git checkout master
git merge dev

Testing

Manual Testing Checklist

Before each release:

• Login/logout works
• Character creation works
• Character list displays correctly
• API errors are handled gracefully
• Network errors show user-friendly messages
• State persists after app restart
• Works on Windows
• Works on macOS
• Works on Linux
• Works on Android
• Works on iOS
• Works in web browser

Performance Checklist

• App starts in < 3 seconds
• API calls complete in < 5 seconds
• UI is responsive (no lag)
• Memory usage is reasonable
• Battery usage is acceptable (mobile)

Estimated Timeline

• Phase 1: Foundation - ✅ Complete
• Phase 2: Authentication (Week 2) - Ready to start
• Phase 3: Character Management (Weeks 3-4) - Documented
• Phase 4: Platform Optimization (Week 5) - Planned
• Phase 5: Future Features (Week 6+) - Ongoing

With full-time focus, you should have a working app with auth and character management in 4-5 weeks.

Questions?

• Check documentation in this directory
• Read Godot documentation
• Check Flask backend API documentation in /docs

Ready to Start?

1. ✅ Open project in Godot
2. ✅ Download and install fonts
3. ✅ Create main theme
4. ✅ Configure backend URL
5. ✅ Create main scene
6. ✅ Test services
7. 🚀 Start building auth screens!

Good luck with the migration! The foundation is solid, and you're ready to build out the UI.