Fish Table Arcade Game Bot v1.0

A comprehensive, AI-driven autonomous bot for fish table arcade games with adaptive learning, advanced targeting, and self-evolution capabilities.

🎮 Features

Core Functionality

• Autonomous Operation: Fully autonomous shooting with human-controlled safety hotkeys
• Multi-Player Support: Detects and tracks 1-6 player games
• Adaptive Difficulty: Learns from own shots and observes other players
• Dynamic Shot Cost Management: Automatically adjusts shot cost based on bankroll and ROI
• Bankroll Protection: Prevents bankroll from dropping below safe threshold

Vision & Detection

• YOLO v8 OCR: Real-time score and shot cost detection
• Motion Tracking: ByteTrack + optical flow for fish tracking between OCR updates
• Window Adaptation: Works with any Chrome window size and monitor configuration
• Player Seat Detection: Automatic identification of 1-6 player configurations

Fish Classification & Targeting

• AI-Powered Classification: Learns fish types and multipliers from observations
• Cluster Detection: Identifies and prioritizes groups of fish for multi-kills
• Linear Formation Recognition: Detects linear fish arrangements for burst fire
• Kill Stealing: Intelligently steals kills on low-HP fish
• Multiplier Learning: Updates expected values based on observed player kills

Strategy & Learning

• Q-Learning System: Learns optimal state-action pairs
• Pattern Recognition: Analyzes other players' strategies
• Table Phase Detection: Identifies GIVING vs TAKING modes
• Performance Metrics: Tracks ROI, win rate, and strategy effectiveness
• Aggressiveness Scaling: Continuously adjusts risk level (-100 to +100)

Self-Evolution

• GitHub Integration: Automatically checks for and tests strategy updates
• Code Self-Healing: Attempts to fix common errors autonomously
• Safe Integration: Validates and tests new strategies before deployment
• Performance Comparison: Reverts strategies if they degrade performance

Advanced Features

• Trajectory Prediction: Predicts fish movement and future positions
• Convergence Detection: Identifies when fish will intersect
• ROI Optimization: Adjusts shot costs for optimal return on investment
• Session Persistence: Saves learning state between runs
• Performance History: Tracks all shots and outcomes for analysis

📋 System Architecture

├── main.py                  # Main orchestrator and game loop
├── config.py                # Global configuration and constants
├── window_detector.py       # Chrome window detection and adaptation
├── player_detector.py       # Player seat detection (1-6 players)
├── yolo_ocr.py             # YOLO v8 OCR for scores/shot costs
├── motion_tracker.py       # ByteTrack + optical flow tracking
├── fish_classifier.py      # Fish classification and multiplier learning
├── game_state.py           # Game state and entity management
├── targeting_engine.py     # Advanced targeting algorithms
├── shot_manager.py         # Shot execution and bankroll management
├── learning_system.py      # AI learning from observations
├── strategy.py             # Strategy selection and adaptation
├── hotkey_manager.py       # Hotkey input handling
├── self_evolution.py       # GitHub integration and self-healing
└── strategies/             # Directory for learned strategies

⌨️ Hotkeys

Key	Action
a	Toggle autofire ON/OFF
[	Lower shot cost (-5)
]	Raise shot cost (+5)
p	Pause/Resume bot
-	More conservative (aggressiveness -10)
+	More aggressive (aggressiveness +10)
Hold q	Exit program (hold for 2 seconds)

🚀 Installation

Prerequisites

• Python 3.10+
• Windows OS (tested on Windows 10/11)
• Chrome/Chromium browser
• Tesseract OCR installed (for pytesseract)

Step 1: Install Tesseract OCR

1. Download Tesseract installer: https://github.com/UB-Mannheim/tesseract/wiki
2. Install to default location (usually C:\Program Files\Tesseract-OCR)
3. Update config.py if installed to different location

Step 2: Clone/Setup Project

git clone <repo-url>
cd f3
python -m venv venv
venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

# Download YOLO model (will happen automatically on first run)
# But you can pre-download:
python -c "from ultralytics import YOLO; YOLO('yolov8n.pt')"

Step 4: Configure (Optional)

Edit config.py to customize:

• OCR_CONFIDENCE_THRESHOLD - YOLO OCR sensitivity
• BANKROLL_MIN_THRESHOLD - Minimum bankroll to maintain
• AGGRESSIVENESS_SCALE - Default risk level (-100 to +100)
• GITHUB_TOKEN - For strategy auto-updates (optional)

▶️ Running the Bot

python main.py

First Run

1. Launch the fish table game in Chrome
2. Run the bot - it will:
   • Find Chrome window
   • Detect player count and seats
   • Identify your seat (bottom player)
   • Initialize all systems
3. Enable autofire with a key
4. Press a again to enable shooting

📊 Output & Monitoring

The bot displays real-time status:

[STATUS] Time: 45s | Autofire: ON | Bankroll: 5200 | Shot Cost: 15 | Fish: 8 | Phase: GIVING | Aggr: 20

Log Files

• logs/ - Session logs and errors
• strategies/ - Learned strategies and databases
• models/ - Downloaded YOLO models

🧠 Learning System

How It Works

1. Observation: Records every shot and its outcome
2. Classification: Learns fish types from visual features
3. Multiplier Learning: Updates expected values from kills
4. Pattern Recognition: Analyzes other players' strategies
5. Adaptation: Adjusts own strategy based on performance

Learning Metrics

[+] Learning Metrics:
  - Total observations: 487
  - Recent avg ROI: 2.45
  - Win rate: 68%
  - Fish classes learned: 4
  - Players analyzed: 2

🔧 Configuration

Key Settings

Performance

OCR_UPDATE_FREQUENCY = 0.5  # Update OCR every 0.5 seconds
MOTION_UPDATE_FREQUENCY = 0.016  # Motion tracking at ~60 FPS
ENABLE_MOTION_TRACKING = True  # Use motion between OCR updates

Bankroll Management

BANKROLL_MIN_THRESHOLD = 50  # Never drop below 50 points
BANKROLL_BUFFER_PERCENT = 0.10  # Keep 10% buffer
MIN_SHOT_COST = 1
MAX_SHOT_COST = 100

Targeting

CLUSTER_RADIUS = 50  # Pixel radius for clustering
LINEAR_FORMATION_THRESHOLD = 0.95  # Correlation for linear detection
LOW_HP_THRESHOLD = 0.25  # Fish HP for kill stealing

AI Learning

LEARNING_RATE = 0.01
DISCOUNT_FACTOR = 0.99
EXPLORATION_RATE = 0.1

📈 Performance Tips

1. Initial Calibration

   • Run bot in practice/demo mode first
   • Let it observe 10-20 kills to calibrate multipliers
   • Watch aggressiveness adjustment

2. Bankroll Growth

   • Start conservative (-50 aggressiveness)
   • Increase aggressiveness as winrate improves
   • Target 2.0+ average ROI before increasing shot cost

3. Table Selection

   • Works best on GIVING tables
   • Automatically becomes conservative on TAKING tables
   • Avoid tables with erratic multipliers (game bugs)

4. Monitor Health

   • Check logs/ for errors
   • If OCR fails, verify Tesseract installation
   • If motion tracking lags, check CPU usage

🐛 Troubleshooting

"Could not find Chrome window"

• Ensure game is running in Chrome browser
• Run bot as Administrator
• Check that Chrome window is visible

"Low match confidence" (OCR issues)

• Increase OCR_CONFIDENCE_THRESHOLD in config.py (but may miss detections)
• Ensure score boxes are clearly visible
• Try different monitor resolutions

"Bankroll depleted"

• Increase BANKROLL_MIN_THRESHOLD
• Set more conservative aggressiveness (-)
• Check that initial bankroll detection is correct

Motion tracking laggy

• Disable with ENABLE_MOTION_TRACKING = False in config.py
• Reduce FRAME_RATE or skip more frames
• Close other heavy applications

📚 Strategy & Algorithms

Cluster Targeting

Detects groups of fish and shoots through center for multi-kills.

Linear Formation Burst

Identifies linear arrangement of fish and fires burst through all targets.

Kill Stealing

Monitors all fish HP and prioritizes low-HP fish for quick kills.

ROI Optimization

Calculates expected return vs shot cost:

• Conservative: ROI > 2.5
• Balanced: ROI > 2.0
• Aggressive: ROI > 1.5

Table Phase Detection

• GIVING: 60%+ players gaining points → increase aggressiveness
• TAKING: All players losing → become conservative
• NEUTRAL: Mixed results → balanced approach

🔄 Self-Evolution

Bot automatically:

1. Checks GitHub for new strategies (daily)
2. Tests strategy safety
3. Validates performance improvements
4. Integrates if ROI improves >10%
5. Reverts if performance degrades

📊 Data Persistence

Bot saves between sessions:

• learning_state.json - Learned Q-values and shot history
• fish_database.json - Classified fish and multipliers
• evolution_state.json - Integrated strategies
• Session logs for analysis

⚠️ Disclaimer

This bot is for:

• Practice/learning games only
• Personal use
• Authorized arcade games only

Not for:

• Real money gambling
• Unauthorized game hacking
• Commercial distribution

Use at your own risk. Always verify legality before use.

📝 License

MIT License - See LICENSE file

🤝 Contributing

Improvements welcome! Areas for contribution:

• Better fish detection algorithms
• Multiplayer coordination strategies
• Performance optimizations
• Additional game variants

📞 Support

For issues:

1. Check troubleshooting section
2. Review logs in logs/ directory
3. Ensure all dependencies installed correctly
4. Run in administrator mode

---

Fish Table Game Bot v1.0 - Master the arcade with AI assistance! 🎯🐟