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](https://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](https://fonts.google.com/specimen/Cinzel) - for headings
   - [Lato](https://fonts.google.com/specimen/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`:

```gdscript
# 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**:
```gdscript
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**:
```gdscript
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](https://docs.godotengine.org/en/stable/)
- [GDScript Reference](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
- [Godot UI Tutorials](https://docs.godotengine.org/en/stable/tutorials/ui/index.html)

## 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**:
   ```bash
   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

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