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

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.