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