Spaces:
Sleeping
Sleeping
🔄 Migration Guide: Pygame → Web Application
Vue d'ensemble de la migration
Ce document explique comment le jeu RTS original en Pygame a été transformé en application web moderne.
🎯 Objectifs de la migration
- ✅ Accessibilité : Jouer dans le navigateur sans installation
- ✅ Portabilité : Compatible tous systèmes d'exploitation
- ✅ Hébergement : Déployable sur HuggingFace Spaces
- ✅ UI/UX : Interface moderne et intuitive
- ✅ Architecture : Prêt pour le multijoueur
📊 Comparaison des architectures
Architecture Pygame (Avant)
┌──────────────────────────────────────────┐
│ Application Monolithique │
│ │
│ ┌────────────────────────────────────┐ │
│ │ main.py (2909 lignes) │ │
│ │ - Rendu Pygame │ │
│ │ - Logique de jeu │ │
│ │ - Input handling │ │
│ │ - IA │ │
│ │ - Tout dans un fichier │ │
│ └────────────────────────────────────┘ │
│ │
│ Dépendances: │
│ - pygame (GUI desktop) │
│ - llama-cpp-python (IA) │
└──────────────────────────────────────────┘
Architecture Web (Après)
┌─────────────────────────────────────────────┐
│ Frontend (Client) │
│ ┌───────────────────────────────────────┐ │
│ │ HTML5 Canvas + JavaScript │ │
│ │ - Rendu 2D │ │
│ │ - Input handling │ │
│ │ - UI/UX moderne │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
↕ WebSocket
┌─────────────────────────────────────────────┐
│ Backend (Serveur) │
│ ┌───────────────────────────────────────┐ │
│ │ FastAPI + Python │ │
│ │ - Logique de jeu │ │
│ │ - Game loop │ │
│ │ - IA │ │
│ │ - État du jeu │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
🔄 Mapping des composants
Rendu (Rendering)
| Pygame | Web |
|---|---|
pygame.display.set_mode() |
HTML5 <canvas> |
pygame.Surface |
CanvasRenderingContext2D |
pygame.draw.rect() |
ctx.fillRect() |
pygame.draw.circle() |
ctx.arc() + ctx.fill() |
screen.blit() |
ctx.drawImage() |
pygame.display.flip() |
requestAnimationFrame() |
Input Handling
| Pygame | Web |
|---|---|
pygame.event.get() |
addEventListener('click') |
pygame.mouse.get_pos() |
event.clientX/Y |
pygame.key.get_pressed() |
addEventListener('keydown') |
MOUSEBUTTONDOWN |
mousedown event |
KEYDOWN |
keydown event |
Game Loop
| Pygame | Web |
|---|---|
while running: loop |
requestAnimationFrame() (client) |
clock.tick(60) |
20 ticks/sec (serveur) |
| Direct update | WebSocket communication |
| Synchrone | Asynchrone |
État du jeu
| Pygame | Web |
|---|---|
| Variables globales | GameState class |
| Listes Python | Dictionnaires avec UUID |
| Mémoire locale | Serveur + sync WebSocket |
📝 Étapes de migration
1. Analyse du code original ✅
Fichiers analysés :
main.py(2909 lignes) - Jeu principalentities.py- Classes Unit et Buildingcore/game.py- Logique de jeubalance.py- Équilibragesystems/*- Systèmes (combat, pathfinding, etc.)
Fonctionnalités identifiées :
- 5 types d'unités
- 6 types de bâtiments
- Système de ressources (Ore, Gems, Credits)
- IA ennemie
- Fog of war
- Production queue
- Pathfinding A*
2. Architecture backend ✅
Choix techniques :
- FastAPI : Framework moderne, documentation auto
- WebSocket : Communication temps réel
- Dataclasses : Types structurés
- Async/await : Performance I/O
Implémentation :
# app.py (600+ lignes)
- FastAPI app avec routes
- WebSocket manager
- GameState avec logique
- Classes Unit, Building, Player
- Game loop 20 ticks/sec
- AI simple
3. Frontend moderne ✅
Technologies :
- HTML5 Canvas : Rendu performant
- Vanilla JS : Pas de dépendances lourdes
- CSS3 : Design moderne
- WebSocket API : Communication
Composants créés :
index.html: Structure UI complètestyles.css: Design professionnelgame.js: Client de jeu complet
4. UI/UX Design ✅
Améliorations :
- Top bar avec ressources et stats
- Sidebars gauche/droite
- Minimap interactive
- Contrôles caméra
- Notifications toast
- Loading screen
- Drag-to-select
- Animations fluides
Palette de couleurs :
--primary-color: #4A90E2 (Bleu)
--secondary-color: #E74C3C (Rouge)
--success-color: #2ECC71 (Vert)
--warning-color: #F39C12 (Orange)
--dark-bg: #1a1a2e (Fond sombre)
5. Docker & Déploiement ✅
Dockerfile :
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
HuggingFace Spaces :
- README.md avec métadonnées
- Configuration sdk: docker
- Port 7860 (standard HF)
🎨 Améliorations UI/UX
Interface utilisateur
Avant (Pygame) :
- Interface basique
- Boutons simples
- Pas de minimap
- Contrôles limités
- Pas de feedback visuel
Après (Web) :
- Interface professionnelle
- Design moderne avec gradients
- Minimap interactive
- Contrôles intuitifs
- Animations et transitions
- Notifications en temps réel
- Barres de progression
- Icônes emoji
Expérience utilisateur
| Aspect | Pygame | Web |
|---|---|---|
| Installation | Requise | Aucune |
| Plateforme | Desktop uniquement | Tous navigateurs |
| Partage | Impossible | URL simple |
| Mise à jour | Manuelle | Automatique |
| Feedback | Limité | Riche |
🔧 Défis et solutions
Défi 1 : Rendu temps réel
Problème : Pygame gère le rendu directement, Web nécessite Canvas
Solution :
// Game loop client avec requestAnimationFrame
function render() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
drawTerrain();
drawBuildings();
drawUnits();
requestAnimationFrame(render);
}
Défi 2 : Communication client-serveur
Problème : Pygame est monolithique, Web nécessite sync
Solution :
- WebSocket pour communication bidirectionnelle
- État côté serveur (source de vérité)
- Mises à jour incrémentales
- Optimistic UI updates
Défi 3 : État du jeu
Problème : Variables globales vs état distribué
Solution :
class GameState:
def __init__(self):
self.units: Dict[str, Unit] = {}
self.buildings: Dict[str, Building] = {}
self.players: Dict[int, Player] = {}
# ...
def to_dict(self):
# Sérialisation pour WebSocket
return {...}
Défi 4 : Performance
Problème : Latence réseau vs jeu local
Solution :
- Game loop 20 ticks/sec (suffisant)
- Interpolation côté client
- Prediction local
- Compression données
📈 Métriques de migration
Lignes de code
| Composant | Pygame | Web | Changement |
|---|---|---|---|
| Backend | 2909 | 600 | -79% |
| Frontend | 0 | 1200 | NEW |
| CSS | 0 | 800 | NEW |
| Total | 2909 | 2600 | -11% |
Fonctionnalités
| Catégorie | Pygame | Web | Status |
|---|---|---|---|
| Unités | 5 types | 5 types | ✅ Migré |
| Bâtiments | 6 types | 6 types | ✅ Migré |
| Ressources | 3 types | 3 types | ✅ Migré |
| IA | Complexe | Simple | ⚠️ Simplifié |
| Fog of war | Oui | Oui | ✅ Migré |
| Pathfinding | A* | A suivre | 📝 TODO |
| Combat | Oui | Oui | ✅ Migré |
| UI | Basique | Moderne | ✅ Amélioré |
🚀 Avantages de la migration
1. Accessibilité
- ✅ Aucune installation requise
- ✅ Fonctionne partout
- ✅ Partage facile
2. Développement
- ✅ Séparation concerns
- ✅ Code plus maintenable
- ✅ Tests plus faciles
3. Déploiement
- ✅ Docker containerisé
- ✅ CI/CD simple
- ✅ Scaling horizontal
4. Expérience utilisateur
- ✅ UI moderne
- ✅ Responsive
- ✅ Feedback riche
📚 Leçons apprises
Technique
- WebSocket > HTTP polling : Latence faible, bidirectionnel
- Canvas > DOM : Performance rendu
- Server authoritative : Sécurité, cohérence
- Dataclasses : Type safety Python
Architecture
- Séparer client/serveur : Flexibilité
- État immuable : Debugging facile
- Event-driven : Scalabilité
- Async/await : Performance
UI/UX
- Feedback visuel : Crucial
- Animations : Engagement
- Responsive design : Accessibilité
- Minimap : Navigation
🎯 Prochaines étapes
Court terme
- Implémenter pathfinding A*
- Améliorer IA
- Ajouter sons
- Tests unitaires
Moyen terme
- Multijoueur réel
- Système de compte
- Classements
- Campagne
Long terme
- Mobile app
- Tournois
- Modding support
- Esports ready
📖 Ressources
Documentation
Outils
Migration réussie ! 🎉
De Pygame desktop à Web application moderne en conservant toutes les fonctionnalités essentielles et en améliorant l'expérience utilisateur.