Code_of_Conquest/godot_client/docs/THEME_SETUP.md

# Theme Setup Guide

This guide explains how to set up the Code of Conquest theme in Godot, including fonts, colors, and UI styling.

## Overview

The theme recreates the web UI's RPG/fantasy aesthetic:
- **Color Palette**: Dark slate gray backgrounds with gold accents
- **Fonts**: Cinzel (headings), Lato (body text)
- **Style**: Medieval/fantasy with ornate borders and rich colors

## Color Palette

All colors are defined in `scripts/utils/theme_colors.gd`:

### Backgrounds
- Primary: `#1a1a2e` - Very dark blue-gray
- Secondary: `#16213e` - Slightly lighter
- Card: `#1e1e2f` - Card backgrounds

### Text
- Primary: `#e4e4e7` - Light gray (main text)
- Secondary: `#a1a1aa` - Medium gray (secondary text)
- Disabled: `#71717a` - Dark gray (disabled)

### Accents
- Gold: `#d4af37` - Primary accent color
- Gold Light: `#f4d03f`
- Gold Dark: `#b8930a`

### Status
- Success: `#10b981` - Green
- Error: `#ef4444` - Red
- Warning: `#f59e0b` - Orange
- Info: `#3b82f6` - Blue

## Font Setup

### 1. Download Fonts

**Cinzel** (for headings):
- Download from [Google Fonts](https://fonts.google.com/specimen/Cinzel)
- Download all weights (Regular, Medium, SemiBold, Bold)

**Lato** (for body text):
- Download from [Google Fonts](https://fonts.google.com/specimen/Lato)
- Download Regular, Bold, and Italic

### 2. Install Fonts in Project

1. Extract downloaded font files (.ttf or .otf)
2. Copy to `godot_client/assets/fonts/`:
   ```
   assets/fonts/
   ├── Cinzel-Regular.ttf
   ├── Cinzel-Medium.ttf
   ├── Cinzel-SemiBold.ttf
   ├── Cinzel-Bold.ttf
   ├── Lato-Regular.ttf
   ├── Lato-Bold.ttf
   └── Lato-Italic.ttf
   ```

3. In Godot, the fonts will auto-import
4. Check import settings (select font → Import tab):
   - Antialiasing: Enabled
   - Hinting: Full
   - Subpixel Positioning: Auto

### 3. Create Font Resources

For each font file:

1. Right-click font in FileSystem
2. Select "New Resource"
3. Choose "FontVariation" (or use font directly)
4. Configure size and other properties
5. Save as `.tres` resource

Example font resources to create:
- `Cinzel_Heading_Large.tres` (Cinzel-Bold, 32px)
- `Cinzel_Heading_Medium.tres` (Cinzel-SemiBold, 24px)
- `Cinzel_Heading_Small.tres` (Cinzel-Medium, 18px)
- `Lato_Body.tres` (Lato-Regular, 14px)
- `Lato_Body_Bold.tres` (Lato-Bold, 14px)

## Theme Resource Setup

### 1. Create Main Theme

1. In Godot: Right-click `assets/themes/` → New Resource
2. Select "Theme"
3. Save as `main_theme.tres`

### 2. Configure Default Font

1. Select `main_theme.tres`
2. In Inspector → Theme → Default Font:
   - Set to `Lato-Regular.ttf`
3. Default Font Size: `14`

### 3. Configure Colors

For each Control type (Button, Label, LineEdit, etc.):

1. In Theme editor, expand control type
2. Add color overrides:

**Button**:
- `font_color`: `#e4e4e7` (TEXT_PRIMARY)
- `font_hover_color`: `#f4d03f` (GOLD_LIGHT)
- `font_pressed_color`: `#d4af37` (GOLD_ACCENT)
- `font_disabled_color`: `#71717a` (TEXT_DISABLED)

**Label**:
- `font_color`: `#e4e4e7` (TEXT_PRIMARY)

**LineEdit**:
- `font_color`: `#e4e4e7` (TEXT_PRIMARY)
- `font_placeholder_color`: `#a1a1aa` (TEXT_SECONDARY)
- `caret_color`: `#d4af37` (GOLD_ACCENT)
- `selection_color`: `#d4af37` (GOLD_ACCENT with alpha)

### 4. Configure StyleBoxes

Create StyleBoxFlat resources for backgrounds and borders:

**Button Normal**:
1. Create New StyleBoxFlat
2. Settings:
   - Background Color: `#1e1e2f` (BACKGROUND_CARD)
   - Border Width: `2` (all sides)
   - Border Color: `#3f3f46` (BORDER_DEFAULT)
   - Corner Radius: `4` (all corners)

**Button Hover**:
- Background Color: `#16213e` (BACKGROUND_SECONDARY)
- Border Color: `#d4af37` (GOLD_ACCENT)

**Button Pressed**:
- Background Color: `#0f3460` (BACKGROUND_TERTIARY)
- Border Color: `#d4af37` (GOLD_ACCENT)

**Button Disabled**:
- Background Color: `#1a1a2e` (BACKGROUND_PRIMARY)
- Border Color: `#27272a` (DIVIDER)

**Panel**:
- Background Color: `#1e1e2f` (BACKGROUND_CARD)
- Border Width: `1`
- Border Color: `#3f3f46` (BORDER_DEFAULT)
- Corner Radius: `8`

**LineEdit Normal**:
- Background Color: `#16213e` (BACKGROUND_SECONDARY)
- Border Width: `2`
- Border Color: `#3f3f46` (BORDER_DEFAULT)
- Corner Radius: `4`

**LineEdit Focus**:
- Border Color: `#d4af37` (GOLD_ACCENT)

### 5. Set Theme in Project

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

Or set per-scene by selecting root Control node and setting Theme property.

## Using the Theme

### In Scenes

Most UI elements will automatically use the theme. For custom styling:

```gdscript
# Access theme colors
var label = Label.new()
label.add_theme_color_override("font_color", ThemeColors.GOLD_ACCENT)

# Access theme fonts
var heading = Label.new()
heading.add_theme_font_override("font", preload("res://assets/fonts/Cinzel_Heading_Large.tres"))

# Access theme styleboxes
var panel = Panel.new()
var stylebox = get_theme_stylebox("panel", "Panel").duplicate()
stylebox.bg_color = ThemeColors.BACKGROUND_TERTIARY
panel.add_theme_stylebox_override("panel", stylebox)
```

### Creating Custom Styles

```gdscript
# Create a card-style panel
var stylebox = StyleBoxFlat.new()
stylebox.bg_color = ThemeColors.BACKGROUND_CARD
stylebox.border_width_all = 2
stylebox.border_color = ThemeColors.BORDER_DEFAULT
stylebox.corner_radius_all = 8
stylebox.shadow_color = ThemeColors.SHADOW
stylebox.shadow_size = 4

panel.add_theme_stylebox_override("panel", stylebox)
```

### Reusable Component Scenes

Create reusable UI components in `scenes/components/`:

**Card.tscn**:
- PanelContainer with card styling
- Margins for content padding
- Optional header and footer sections

**CustomButton.tscn**:
- Button with custom styling
- Hover effects
- Icon support

**FormField.tscn**:
- Label + LineEdit combo
- Validation error display
- Help text support

## Theme Variations

### Headings

Create different heading styles:

```gdscript
# H1 - Large heading
var h1 = Label.new()
h1.add_theme_font_override("font", preload("res://assets/fonts/Cinzel_Heading_Large.tres"))
h1.add_theme_color_override("font_color", ThemeColors.GOLD_ACCENT)

# H2 - Medium heading
var h2 = Label.new()
h2.add_theme_font_override("font", preload("res://assets/fonts/Cinzel_Heading_Medium.tres"))
h2.add_theme_color_override("font_color", ThemeColors.TEXT_PRIMARY)

# H3 - Small heading
var h3 = Label.new()
h3.add_theme_font_override("font", preload("res://assets/fonts/Cinzel_Heading_Small.tres"))
h3.add_theme_color_override("font_color", ThemeColors.TEXT_PRIMARY)
```

### Status Messages

```gdscript
# Success message
var success_label = Label.new()
success_label.add_theme_color_override("font_color", ThemeColors.SUCCESS)

# Error message
var error_label = Label.new()
error_label.add_theme_color_override("font_color", ThemeColors.ERROR)
```

### Progress Bars

```gdscript
# HP Bar
var hp_bar = ProgressBar.new()
hp_bar.add_theme_color_override("fill_color", ThemeColors.HP_COLOR)

# Mana Bar
var mana_bar = ProgressBar.new()
mana_bar.add_theme_color_override("fill_color", ThemeColors.MANA_COLOR)
```

## Responsive Scaling

### DPI Scaling

Godot handles DPI scaling automatically. For custom scaling:

```gdscript
# Get DPI scale
var scale = DisplayServer.screen_get_scale()

# Adjust font size
var font_size = 14 * scale
label.add_theme_font_size_override("font_size", int(font_size))
```

### Mobile Adjustments

```gdscript
# Detect platform
var is_mobile = OS.get_name() in ["Android", "iOS"]

if is_mobile:
    # Larger touch targets
    button.custom_minimum_size = Vector2(60, 60)
    # Larger fonts
    label.add_theme_font_size_override("font_size", 16)
else:
    # Smaller desktop sizes
    button.custom_minimum_size = Vector2(40, 40)
    label.add_theme_font_size_override("font_size", 14)
```

## Testing the Theme

### Visual Consistency

Create a theme test scene with all UI elements:
- Buttons (normal, hover, pressed, disabled)
- Labels (headings, body, secondary)
- Input fields (normal, focused, error)
- Panels and cards
- Progress bars
- Lists and grids

### Cross-Platform

Test theme on:
- Desktop (Windows/Mac/Linux) - Check with different DPI settings
- Mobile (Android/iOS) - Check on different screen sizes
- Web - Check in different browsers

## Advanced: Dynamic Theming

For future dark/light mode support:

```gdscript
# Theme manager (future)
class ThemeManager:
    static var current_theme = "dark"

    static func switch_theme(theme_name: String):
        match theme_name:
            "dark":
                # Load dark theme
                get_tree().root.theme = preload("res://assets/themes/dark_theme.tres")
            "light":
                # Load light theme
                get_tree().root.theme = preload("res://assets/themes/light_theme.tres")
```

## Resources

- [Godot Theme Documentation](https://docs.godotengine.org/en/stable/tutorials/ui/gui_using_theme_editor.html)
- [Google Fonts](https://fonts.google.com/)
- [Color Palette Tool](https://coolors.co/)

## Quick Start Checklist

- [ ] Download Cinzel and Lato fonts
- [ ] Copy fonts to `assets/fonts/`
- [ ] Create `main_theme.tres` in `assets/themes/`
- [ ] Set default font to Lato-Regular
- [ ] Configure Button colors and styleboxes
- [ ] Configure Panel styleboxes
- [ ] Configure LineEdit colors and styleboxes
- [ ] Create heading font variations
- [ ] Set project theme in settings
- [ ] Test in a sample scene
- [ ] Create reusable component scenes