🎯 Battleship API

CPSC 3750 Final Project - Phase 1

Distributed Multiplayer Battleship System

API v1.0

✨ Core Features

UUID Players
Universally unique player identification
1-N Multiplayer
Support for any number of players
Turn Rotation
Automatic turn management
Statistics
Wins, losses, accuracy tracking
Transactions
ACID-compliant persistence
Test Mode
Deterministic testing for grading

📋 API Endpoints

System Control

POST /api/reset

Reset entire system (truncate all tables)

Player Management

POST /api/players

Create new player with UUID

{ "username": "alice" }
GET /api/players/{id}/stats

Get player statistics (games, wins, losses, accuracy)

Game Lifecycle

POST /api/games

Create new game (creator auto-joins with turn_order=0)

{ "creator_id": "uuid", "grid_size": 8, "max_players": 3 }
POST /api/games/{id}/join

Join existing game

{ "player_id": "uuid" }
GET /api/games/{id}

Get game state

Gameplay

POST /api/games/{id}/place

Place 3 ships (exactly 3 single-cell ships required)

{ "player_id": "uuid", "ships": [{"row": 0, "col": 0}, ...] }
POST /api/games/{id}/fire

Fire at coordinate (validates turn, checks hit/miss, updates stats)

{ "player_id": "uuid", "row": 3, "col": 4 }
GET /api/games/{id}/moves

Get chronological move history

Test Mode (Requires X-Test-Password: clemson-test-2026)

POST /api/test/games/{id}/restart

Restart game (clear ships/moves, preserve stats)

POST /api/test/games/{id}/ships

Deterministic ship placement for testing

GET /api/test/games/{id}/board/{player_id}

Reveal board state (for autograder verification)

🗄️ Database Schema

Table Purpose Key Fields
Players Player accounts with UUID player_id (UUID), username, stats
Games Game instances game_id, grid_size, status, current_turn_index
GamePlayers Many-to-many join table game_id, player_id, turn_order, ships_placed
Ships Ship positions game_id, player_id, row, col, is_sunk
Moves Move history log game_id, player_id, target_player_id, result