first
This commit is contained in:
292
DEVELOPMENT_GUIDE.md
Normal file
292
DEVELOPMENT_GUIDE.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# Guide de Développement - Mario Runner
|
||||
|
||||
## 🎮 État du Projet
|
||||
|
||||
### ✅ Fonctionnalités Implémentées
|
||||
|
||||
#### Infrastructure
|
||||
- ✅ Configuration TypeScript + Vite
|
||||
- ✅ Structure de projet organisée
|
||||
- ✅ Phaser 3 intégré
|
||||
- ✅ PWA configuré (manifest.json)
|
||||
- ✅ Build et compilation fonctionnels
|
||||
|
||||
#### Contrôles
|
||||
- ✅ **PC** : Contrôle clavier (Flèches gauche/droite + Espace/Haut pour sauter)
|
||||
- ✅ **Mobile** : Gyroscope pour mouvement + Bouton tactile pour sauter
|
||||
- ✅ Détection automatique PC vs Mobile
|
||||
- ✅ Permission gyroscope iOS (requestPermission)
|
||||
- ✅ Zone morte gyroscope (deadzone) pour stabilité
|
||||
|
||||
#### Jeu
|
||||
- ✅ Classe Player avec physique Arcade
|
||||
- ✅ Mouvement fluide avec accélération/décélération
|
||||
- ✅ Saut avec gravité
|
||||
- ✅ Background qui défile avec effet parallaxe
|
||||
- ✅ Plateformes statiques (sol + plateformes en l'air)
|
||||
- ✅ Obstacles (collision → perte de points)
|
||||
- ✅ Cadeaux (collecte → gain de points)
|
||||
- ✅ Système de score
|
||||
- ✅ Timer de 3 minutes
|
||||
- ✅ Caméra qui suit le joueur
|
||||
- ✅ Niveau étendu (3x la largeur de l'écran)
|
||||
|
||||
#### Scènes
|
||||
- ✅ BootScene : Chargement des assets
|
||||
- ✅ MenuScene : Menu avec demande permission gyroscope
|
||||
- ✅ GameScene : Jeu principal
|
||||
|
||||
#### UI
|
||||
- ✅ Affichage score et timer
|
||||
- ✅ Info contrôles selon plateforme
|
||||
- ✅ Bouton retour menu
|
||||
- ✅ Écran de fin de jeu
|
||||
|
||||
### 🚧 À Faire
|
||||
|
||||
#### Assets Graphiques
|
||||
- [ ] Créer spritesheet du personnage (neveu)
|
||||
- [ ] Animation idle
|
||||
- [ ] Animation walk
|
||||
- [ ] Animation jump
|
||||
- [ ] Background réel (remplacer le ciel généré)
|
||||
- [ ] Sprites plateformes
|
||||
- [ ] Sprites obstacles variés
|
||||
- [ ] Sprites cadeaux variés
|
||||
- [ ] Icônes PWA (192x192, 512x512)
|
||||
|
||||
#### Gameplay
|
||||
- [ ] Plateformes mobiles
|
||||
- [ ] Ennemis animés
|
||||
- [ ] Power-ups spéciaux
|
||||
- [ ] Checkpoints
|
||||
- [ ] Système de vies
|
||||
- [ ] Game Over / Victory screens
|
||||
- [ ] High scores / LocalStorage
|
||||
|
||||
#### Audio
|
||||
- [ ] Musique de fond
|
||||
- [ ] Son de saut
|
||||
- [ ] Son de collecte
|
||||
- [ ] Son de collision
|
||||
- [ ] Gestion volume
|
||||
|
||||
#### Niveau Design
|
||||
- [ ] Créer niveaux avec Tiled
|
||||
- [ ] Importer tilemaps JSON
|
||||
- [ ] Plusieurs niveaux
|
||||
- [ ] Progression de difficulté
|
||||
|
||||
#### Optimisation
|
||||
- [ ] Pooling d'objets
|
||||
- [ ] Optimisation sprites
|
||||
- [ ] Compression assets
|
||||
- [ ] Service Worker pour PWA
|
||||
|
||||
## 🎯 Commandes Disponibles
|
||||
|
||||
```bash
|
||||
# Développement (hot reload)
|
||||
npm run dev
|
||||
|
||||
# Build de production
|
||||
npm run build
|
||||
|
||||
# Prévisualiser le build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 🧪 Test sur Mobile
|
||||
|
||||
### Via réseau local (WiFi)
|
||||
|
||||
1. Assurez-vous que mobile et PC sont sur le même WiFi
|
||||
2. Lancez `npm run dev`
|
||||
3. Notez l'adresse réseau affichée (ex: `http://192.168.1.10:3000`)
|
||||
4. Ouvrez cette adresse sur votre mobile
|
||||
|
||||
### Via tunnel (pour HTTPS requis par iOS)
|
||||
|
||||
**Option 1 : ngrok**
|
||||
```bash
|
||||
npm install -g ngrok
|
||||
npm run dev
|
||||
# Dans un autre terminal :
|
||||
ngrok http 3000
|
||||
```
|
||||
|
||||
**Option 2 : localtunel**
|
||||
```bash
|
||||
npm install -g localtunnel
|
||||
npm run dev
|
||||
# Dans un autre terminal :
|
||||
lt --port 3000
|
||||
```
|
||||
|
||||
## 📱 Contrôles
|
||||
|
||||
### PC (Développement)
|
||||
- **Flèches Gauche/Droite** : Déplacement
|
||||
- **Espace** ou **Flèche Haut** : Saut
|
||||
|
||||
### Mobile (Production)
|
||||
- **Gyroscope** : Inclinez le téléphone pour déplacer le personnage
|
||||
- **Bouton tactile** (bas droite) : Saut
|
||||
|
||||
## 🏗 Architecture du Code
|
||||
|
||||
### Structure des Fichiers
|
||||
|
||||
```
|
||||
src/
|
||||
├── main.ts # Point d'entrée
|
||||
├── game.ts # Config Phaser
|
||||
├── scenes/
|
||||
│ ├── BootScene.ts # Chargement assets
|
||||
│ ├── MenuScene.ts # Menu principal
|
||||
│ └── GameScene.ts # Jeu principal
|
||||
├── controls/
|
||||
│ ├── GyroControl.ts # Gestion gyroscope
|
||||
│ └── JumpButton.ts # Bouton saut tactile
|
||||
├── entities/
|
||||
│ ├── Player.ts # Joueur
|
||||
│ ├── Obstacle.ts # Obstacles
|
||||
│ └── Gift.ts # Cadeaux
|
||||
└── utils/
|
||||
└── constants.ts # Constantes du jeu
|
||||
```
|
||||
|
||||
### Flux du Jeu
|
||||
|
||||
```
|
||||
index.html → main.ts → game.ts
|
||||
↓
|
||||
BootScene (chargement)
|
||||
↓
|
||||
MenuScene (permission gyro)
|
||||
↓
|
||||
GameScene (jeu)
|
||||
```
|
||||
|
||||
### Gestion des Contrôles
|
||||
|
||||
```typescript
|
||||
// GameScene détecte automatiquement la plateforme
|
||||
if (isMobile) {
|
||||
// Gyroscope + Bouton tactile
|
||||
gyroControl.getTiltValue() → direction
|
||||
jumpButton.on('press') → player.jump()
|
||||
} else {
|
||||
// Clavier
|
||||
cursors.left/right → direction
|
||||
cursors.space → player.jump()
|
||||
}
|
||||
|
||||
// Mouvement unifié
|
||||
player.move(direction)
|
||||
```
|
||||
|
||||
## 🎨 Workflow Sprites
|
||||
|
||||
Consultez [public/assets/sprites/SPRITE_WORKFLOW.md](public/assets/sprites/SPRITE_WORKFLOW.md) pour le guide complet de création des sprites du personnage.
|
||||
|
||||
### Résumé rapide :
|
||||
1. Détourez la photo (GIMP, remove.bg)
|
||||
2. Créez les animations (Piskel, Aseprite)
|
||||
3. Exportez en spritesheet PNG
|
||||
4. Placez dans `public/assets/sprites/`
|
||||
5. Chargez dans `BootScene.preload()`
|
||||
6. Créez animations dans `Player.ts`
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Ajuster la Difficulté
|
||||
|
||||
Éditez [src/utils/constants.ts](src/utils/constants.ts) :
|
||||
|
||||
```typescript
|
||||
// Physique joueur
|
||||
export const PLAYER_GRAVITY = 800; // Gravité
|
||||
export const PLAYER_JUMP_VELOCITY = -400; // Force de saut
|
||||
export const PLAYER_MAX_SPEED = 300; // Vitesse max
|
||||
export const PLAYER_ACCELERATION = 50; // Accélération
|
||||
|
||||
// Gyroscope
|
||||
export const GYRO_DEADZONE = 5; // Zone morte (degrés)
|
||||
export const GYRO_MAX_TILT = 30; // Inclinaison max
|
||||
export const GYRO_SENSITIVITY = 10; // Sensibilité
|
||||
|
||||
// Niveau
|
||||
export const LEVEL_DURATION = 180; // Durée (secondes)
|
||||
```
|
||||
|
||||
### Activer le Mode Debug
|
||||
|
||||
Dans [src/game.ts](src/game.ts) :
|
||||
|
||||
```typescript
|
||||
physics: {
|
||||
arcade: {
|
||||
debug: true, // Affiche les hitboxes
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
## 🐛 Problèmes Courants
|
||||
|
||||
### Le gyroscope ne fonctionne pas sur iOS
|
||||
|
||||
- ✅ Vérifiez que vous utilisez **HTTPS** (requis par iOS 13+)
|
||||
- ✅ Vérifiez que la permission a été accordée dans MenuScene
|
||||
- ✅ Testez sur un vrai appareil iOS (pas de gyro sur simulateur)
|
||||
|
||||
### Le jeu est trop rapide/lent
|
||||
|
||||
- Ajustez `PLAYER_MAX_SPEED` et `PLAYER_ACCELERATION`
|
||||
- Ajustez `GYRO_SENSITIVITY` pour mobile
|
||||
|
||||
### Les collisions ne fonctionnent pas
|
||||
|
||||
- Vérifiez que les objets ont un body physique : `this.physics.add.existing()`
|
||||
- Vérifiez les colliders/overlaps dans GameScene
|
||||
|
||||
### Le build échoue
|
||||
|
||||
```bash
|
||||
# Nettoyer et réinstaller
|
||||
rm -rf node_modules dist
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 📚 Ressources
|
||||
|
||||
### Documentation
|
||||
- [Phaser 3](https://photonstorm.github.io/phaser3-docs/)
|
||||
- [DeviceOrientation API](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent)
|
||||
- [PWA Guide](https://web.dev/progressive-web-apps/)
|
||||
|
||||
### Assets Gratuits
|
||||
- [OpenGameArt.org](https://opengameart.org/)
|
||||
- [Kenney.nl](https://kenney.nl/assets)
|
||||
- [Itch.io Assets](https://itch.io/game-assets/free)
|
||||
|
||||
### Outils
|
||||
- [Piskel](https://www.piskelapp.com/) - Sprites
|
||||
- [Tiled](https://www.mapeditor.org/) - Niveaux
|
||||
- [GIMP](https://www.gimp.org/) - Édition images
|
||||
|
||||
## 🚀 Prochaines Étapes Recommandées
|
||||
|
||||
1. **Créer les sprites du personnage** (voir SPRITE_WORKFLOW.md)
|
||||
2. **Ajouter du son** (musique + effets)
|
||||
3. **Créer plus de niveaux** avec Tiled
|
||||
4. **Tester sur mobile réel** via tunnel HTTPS
|
||||
5. **Déployer** (Netlify, Vercel, GitHub Pages)
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- Le jeu détecte automatiquement PC vs Mobile
|
||||
- Les deux modes de contrôle peuvent coexister
|
||||
- Le code est prêt pour l'ajout de vrais sprites
|
||||
- La structure est extensible pour ajouter plus de features
|
||||
Reference in New Issue
Block a user