Flappy-Bird-AI-Driven-Bohdan-Bozhko/AI_RULES.md

# AI_RULES.md - Flappy Bird (AI-driven) Development Guidelines

## 🏗️ Technical Stack
- **Unity Version**: Unity 6000 LTS
- **Physics**: 2D Physics (Rigidbody2D, Collider2D)
- **Dependency Injection**: Zenject
- **Async Operations**: UniTask
- **Platform**: Mobile-ready build
- **Target Performance**: 60 FPS

## 🏛️ Architecture Rules

### 1. MonoBehaviour Separation
- **NO BUSINESS LOGIC** inside MonoBehaviour classes
- MonoBehaviour only for:
  - Unity lifecycle events (Start, Update, OnTrigger, etc.)
  - Component references and initialization
  - View updates and animations
- All game logic must be in separate service classes

### 2. Object Pooling
- Use object pooling for all frequently spawned objects:
  - Pipes
  - Particles
  - UI elements (score popups, etc.)
- Implement `IPoolable` interface for pooled objects
- Use `ObjectPoolManager` service

### 3. GameState Management
- Separate `GameStateManager` service for all game states:
  - MainMenu
  - Playing
  - GameOver
  - Paused
- No direct state changes from MonoBehaviour
- Use events/signals for state transitions

### 4. Dependency Injection (Zenject)
- All services must be registered in Zenject installers
- Use constructor injection for dependencies
- Separate installers for different contexts:
  - `GameInstaller` - core game services
  - `UIInstaller` - UI-related services
  - `SettingsInstaller` - settings and persistence

### 5. Async Operations (UniTask)
- Use UniTask instead of Coroutines
- Async operations for:
  - Scene loading
  - Save/Load operations
  - Network calls (if any)
  - Tweening and animations

## 📁 Project Structure

```
Assets/
├── Scripts/
│   ├── Core/
│   │   ├── GameStateManager.cs
│   │   ├── ScoreManager.cs
│   │   └── ObjectPoolManager.cs
│   ├── Gameplay/
│   │   ├── Bird/
│   │   ├── Pipes/
│   │   └── Physics/
│   ├── UI/
│   │   ├── Views/
│   │   ├── Presenters/
│   │   └── Models/
│   ├── Services/
│   ├── Installers/
│   └── Utilities/
├── Prefabs/
├── Sprites/
├── Audio/
└── Scenes/
```

## 🎮 Gameplay Requirements

### Bird Physics
- Use Rigidbody2D with gravity
- Tap/Click applies upward force
- Smooth rotation based on velocity
- No direct transform manipulation

### Pipe Generation
- Procedural generation system
- Object pooling for performance
- Configurable gap size and spacing
- Random height variations

### Scoring System
- Score increases when passing through pipes
- High score persistence
- Real-time score display
- Score-based achievements

### Game Over Conditions
- Collision with pipes
- Collision with ground/ceiling
- Restart functionality
- Score summary display

## 📱 Mobile Optimization

### Performance
- Target 60 FPS on mid-range devices
- Minimal GC allocations
- Efficient texture usage
- Optimized shader usage

### Input
- Touch-friendly controls
- One-tap gameplay
- Responsive input handling
- Support for different screen sizes

### Build Settings
- Platform-specific optimizations
- Texture compression
- Audio compression
- Build size optimization

## 🔧 Service Contracts

### Core Interfaces
```csharp
public interface IGameStateManager
{
    GameState CurrentState { get; }
    UniTask ChangeStateAsync(GameState newState);
    event System.Action<GameState> OnStateChanged;
}

public interface IScoreManager
{
    int CurrentScore { get; }
    int HighScore { get; }
    void AddScore(int points);
    void ResetScore();
    UniTask SaveHighScoreAsync();
}

public interface IObjectPoolManager
{
    T Get<T>() where T : Component, IPoolable;
    void Return<T>(T item) where T : Component, IPoolable;
}
```

### Event System
- Use C# events or Zenject signals
- No direct references between unrelated systems
- Event naming convention: `On[Action][Result]`

## 🎨 UI Guidelines

### MVP Pattern
- **Model**: Data containers (ScoreModel, SettingsModel)
- **View**: MonoBehaviour UI components
- **Presenter**: Business logic for UI interactions

### UI Services
- `UIManager` for screen management
- `PopupManager` for overlays
- `HUDManager` for in-game UI

## 💾 Data Persistence

### Save System
- JSON-based save files
- PlayerPrefs for settings
- Async save/load operations
- Data validation and error handling

### Settings
- Graphics quality options
- Audio volume settings
- Control sensitivity
- Achievement progress

## 🤖 AI Integration Rules

### AI Behavior
- Separate AI controller from player input
- Machine learning integration points
- Data collection for training
- Performance metrics tracking

### Training Data
- Bird position and velocity
- Pipe positions and gaps
- Score and survival time
- Input timing and patterns

## 📋 Development Checklist

### Phase 1: Core Systems
- [ ] GameStateManager implementation
- [ ] Basic bird physics
- [ ] Object pooling system
- [ ] Zenject setup

### Phase 2: Gameplay
- [ ] Pipe generation
- [ ] Collision detection
- [ ] Score system
- [ ] Game over mechanics

### Phase 3: Polish
- [ ] UI implementation
- [ ] Audio integration
- [ ] Mobile optimization
- [ ] Save system

### Phase 4: AI Integration
- [ ] AI controller setup
- [ ] Training data collection
- [ ] Performance monitoring
- [ ] AI behavior tuning

## 🚨 Code Quality Standards

### Naming Conventions
- PascalCase for classes, methods, properties
- camelCase for fields, parameters
- UPPER_CASE for constants
- Prefix interfaces with 'I'

### Documentation
- XML documentation for public APIs
- Clear variable and method names
- Inline comments for complex logic
- Architecture decision records (ADRs)

### Error Handling
- Use try-catch for recoverable errors
- Validate input parameters
- Graceful degradation for non-critical failures
- Proper logging for debugging

---

**Remember**: Every prompt must follow these AI_RULES.md guidelines. No exceptions.