293 lines
7.4 KiB
Markdown
293 lines
7.4 KiB
Markdown
# 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
|