Battleship Hackathon

🎯 Overview

Welcome to the Battleship AI Hackathon! This is a competitive coding challenge where developers build bots to play Battleship as efficiently as possible. Your goal is simple: find all ships in the fewest moves across 20 rounds.

The player with the lowest total move count wins. Strategy, optimization, and clever algorithms are key to success!

🇦🇫 Open to All Afghan Developers: This hackathon is for students, professionals, and anyone in Afghanistan who loves coding and wants to compete in a fun, challenging environment.

🏆 Prizes

🥇

1st Place

$200 USD
+ Exclusive Hoodie ⭐
+ Exclusive Drinking Bottle 🏆

🥈

2nd Place

$100 USD
+ Exclusive Hoodie ⭐

🥉

3rd Place

$50 USD

🎖️

4th - 10th Place

Exclusive Hackathon
Sticker Swags 🎨

⚠️ Fair Play Policy: Prizes are awarded to unique individuals. Multiple accounts by the same person will be disqualified. Keep it fair and competitive! Also, inappropriate usernames are not tolerated and may result in removal from the leaderboard.

🚢 What is Battleship?

Battleship is a classic strategy game where players try to locate and "sink" hidden ships on a grid. In this hackathon:

Grid Size: 10x10 board
Ships: 4 ships with lengths [2, 3, 4, 5]
Goal: Find all ship positions by calling coordinates
Hit: When you call a coordinate with a ship, you get the ship's length as the response
Miss: When you call an empty coordinate, you get 0 as the response

🎥 New to Battleship? Watch this tutorial to understand the game:

🚀 Getting Started

Step 1: Create an Account

Navigate to the Sign Up page and create your account. You'll receive a unique secret_key that authenticates your bot.

Step 2: Access Your Credentials

Once logged in, go to the Developer Portal. Here you'll find:

Username: Your account username
Server URL: The WebSocket server endpoint
Secret Key: Your unique authentication key (keep this private!)

Step 3: Try the Sandbox

Head to the Sandbox to play manually and understand the game mechanics. Use your credentials to start a game with 1-2 rounds:

Enter your username and secret_key
Set rounds to 2 for testing
Click "Start Game" and play by clicking cells
Observe how hits (red) and misses (black) work
Watch the ship tracker on the right to see progress

Sandbox environment with game in progress

🤖 Building Your Bot

Step 1: Download Starter Template

From your Developer Portal, download either:

starter_template.py - Python implementation
starter_template.js - Node.js implementation

Developer portal starter templates section

Step 2: Configure Your Bot

Open the template file and replace the placeholder values:

# Python Example
SERVER_URL = "http://your-server-url:5050"
USERNAME = "your-username"
SECRET_KEY = "your-secret-key-here"
ROUNDS = 2  # Start with 2 rounds for testing
GUESTS = []  # We'll explain this later

Step 3: Install Dependencies

For Python:

pip install python-socketio websocket-client requests

For Node.js:

npm install socket.io-client

Step 4: Understand the Game Flow

Your bot communicates via WebSocket events:

1️⃣ Connect & Start Game

# Bot connects and sends credentials
emit("start_game", {
    "username": "your-username",
    "secret_key": "your-secret-key",
    "rounds": 2
})

2️⃣ Receive Game Started

# Server responds with game info
{
    "message": "Game started for username with 2 rounds.",
    "session_id": "abc-123-uuid",
    "board_size": {"x": 10, "y": 10},
    "ships": [2, 3, 4, 5]
}

3️⃣ Receive New Round

# Server signals a new round
{
    "round": 1,
    "session_id": "abc-123-uuid",
    "ships": [2, 3, 4, 5]
}

4️⃣ Play Coordinates

# Bot plays a coordinate
emit("play_coordinate", {
    "session_id": "abc-123-uuid",
    "x": 5,
    "y": 3
})

5️⃣ Receive Round Result

# Server responds with hit/miss info
{
    "value": 3,  # 0 = miss, >0 = ship length hit
    "score": 42,  # Total moves so far
    "round_finished": false,
    "x": 5,
    "y": 3,
    "session_id": "abc-123-uuid"
}

💡 Key Insight: When value > 0, you hit a ship! The number tells you the ship's length (2, 3, 4, or 5). When value = 0, it's a miss.

6️⃣ Round Ends

When you've found all ship positions, round_finished: true is returned. The server automatically starts the next round until all rounds are complete.

7️⃣ Game Finished

# All rounds complete
{
    "total_score": 250,  # Your final score (lower is better!)
    "rounds": 100,
    "session_id": "abc-123-uuid"
}

👀 Testing with Spectator Mode

💡 No Login Required: You don't need to enter your username, secret key, or start a game manually in the Sandbox to use spectator mode. Just open it, copy the Session ID, and run your bot!

You can watch your bot play in real-time using the Sandbox! This is incredibly helpful for debugging and understanding your strategy.

How to Enable Spectator Mode:

Open the Sandbox in your browser
Look at the game log - you'll see your Session ID displayed with a copy button
Click the copy button to copy your Session ID (e.g., i8DuZfq3lOj0sH2PAAAD)
In your bot code, add it to the GUESTS array:

GUESTS = ["i8DuZfq3lOj0sH2PAAAD"] # Your sandbox session ID

Add a delay between moves so you can see what's happening:

# Python
import time
time.sleep(0.2)  # 200ms delay

// JavaScript
await new Promise(resolve => setTimeout(resolve, 200));

Simply run your bot script
The Sandbox will receive live updates as your bot plays! Watch the board light up with hits and misses in real-time 🎉

💡 Pro Tip: Start with small delays (0.2-0.5s) and 1-2 rounds to debug your strategy. Once it works, remove delays and scale up to 20 rounds!

📊 Submitting to Leaderboard

Testing Phase (1-10 rounds)

Test your bot with fewer rounds first. Check the leaderboard for 1, 2, 5, or 10 round brackets to see how you compare!

Final Submission (20 rounds)

When you're confident in your strategy:

Remove the GUESTS array (no spectators needed)
Remove any delays you added for testing
Set ROUNDS = 20
Run your bot!

# Final configuration
USERNAME = "your-username"
SECRET_KEY = "your-secret-key"
ROUNDS = 20  # The competition round!
GUESTS = []   # No spectators

Your submission is automatically saved and appears on the leaderboard. You can submit as many times as you want - only your best (lowest) score is displayed.

🏆 Only the 20-round leaderboard counts for prizes! Use other round counts for testing and practice.

📈 Tracking Your Progress

Visit your Developer Portal to see all your submissions:

Submission date and time
Number of rounds played
Total moves (score)
Average moves per round

Keep an eye on the Leaderboard to see how you rank!

💬 Community & Support

Join our Telegram community to ask questions, share strategies, and connect with other participants!

📱 Join Telegram Community

❓ FAQ

Yes! Submit as many times as you want. Only your best score appears on the leaderboard.

The submission with the lowest total moves across all rounds.

Absolutely! Since bots run on your machine, use any tools you want.

No hard limits, but play fair. Excessive abuse may be flagged.

Report it in the Telegram community or contact the organizers.

Yes, but prizes are per account. Coordinate as you see fit!

Network latency is expected! Each move requires a round-trip to the server (~200-500ms depending on your location). A 20-round game with ~25 moves per round takes 2-5 minutes. This affects everyone equally, so focus on minimizing your move count, not execution speed. Your algorithm efficiency (fewer moves) matters more than network speed!

Note: If the server is particularly slow or unresponsive, it might be handling multiple submissions at once. Try again in a few minutes during off-peak hours for better performance.

Due to network limitations beyond our control (high latency, unstable connections), brief disconnections may occur during long game sessions. Don't worry! The starter templates include automatic reconnection logic that will:

Automatically attempt to reconnect (up to 5 tries)
Continue your game from where it left off
Preserve your game state and session

This is especially useful for longer games. If you see "Disconnected from server (will attempt to reconnect...)" in your bot logs, the reconnection is happening automatically - no action needed!

🎉 Good Luck!

May the most efficient algorithm win. Happy coding! 🚀

Get Started Now View Leaderboard

📘 Battleship AI Hackathon Documentation