Bellum Punicum · Battleship

A Punic Wars-themed Battleship game built with Next.js and TypeScript. You command the Roman fleet against an AI-controlled Carthaginian navy, in a single-page browser game.

Features

• Home screen: a themed main menu with Start Battle, a difficulty picker, a Leaderboard and How to Play.
• Three difficulty levels: Recruit (easy), Strategist (medium) and General (hard). See AI behavior.
• Leaderboard: finished games are saved in the browser (localStorage). It ranks your best victories by fewest shots, can filter by difficulty, and shows your win/loss record.
• Ship placement: place five ships horizontally or vertically (button or R key), with a live preview that shows valid and invalid squares. Overlapping and off-board placements are blocked.
• Hidden enemy fleet: Carthage's ships are placed randomly using the same rules, and stay hidden until sunk.
• Turn-based combat: turns strictly alternate between Rome and Carthage. The game tracks hits and misses, announces sunk ships, shows a Victory or Defeat screen with stats, and offers Play again.
• Cinematic layer: animated ocean, synthesized sound effects (cannon fire, splashes, impacts, crowd reactions, fanfare), and victory confetti or defeat ash. There's a saved mute toggle, and the app respects the system's reduced-motion setting.
• Visual polish: a short "The Battle Begins" intro with Roman and Carthaginian standards, galley-shaped ships drawn in SVG, spray for misses, fire and smoke for hits, a flare when a ship sinks, Scipio and Hannibal coin medallions beside battle remarks, a faint portolan-chart backdrop, and a battle report with laurels and standards at the end. Everything is CSS and inline SVG with no image files, and the extra motion is turned off under reduced motion.
• Designed for phones: below 640px wide, one board shows at a time with a "Roman Fleet" / "Carthaginian Fleet" toggle that follows the action. A sticky status bar shows the turn, the latest shot and the score, and the placement controls sit at the bottom of the screen within thumb reach. The desktop layout keeps both boards side by side.
• Accessible: works on screens down to 320px wide, and the boards can be played with the keyboard and have screen-reader labels.

Running locally

Requires Node.js 20.9 or later.

git clone https://github.com/ianmotz21/ianmotz-battleship.git
cd ianmotz-battleship
npm install
npm run dev

Then open http://localhost:3000.

Command	Purpose
npm run dev	Development server with hot reload
npm run build then npm run start	Production build and server
npm test	Core game logic tests
npm run lint	ESLint
npx tsc --noEmit	Type check

Tech stack

• Next.js 16 (App Router) with React 19
• TypeScript (strict mode)
• CSS Modules for styling, with no UI framework
• Web Audio API for all sound, generated in code with no audio files
• ESLint (eslint-config-next)

Project structure

src/
  app/
    page.tsx           Page layout: title, sound toggle, game
    globals.css        Theme colours and fonts
  components/
    Game.tsx           Home/battle screens, game state and turn flow (single source of truth)
    HomeScreen.tsx     Main menu: difficulty, Start Battle, Leaderboard, How to Play
    Board.tsx          Presentational 10x10 board used for both fleets
    PlayerFleet.tsx    Ship selection and placement controls
    Celebration.tsx    Victory confetti and defeat ash overlay
    BattleIntro.tsx    "The Battle Begins" title card shown as a battle opens
    Insignia.tsx       SVG standards, laurels and commander medallions
    SoundToggle.tsx    Mute button, saved in localStorage
  lib/
    fleet.ts           Fleet definitions and placement/hit/sunk rules (pure functions)
    ai.ts              Carthage's targeting for each difficulty level
    leaderboard.ts     Saved game results and leaderboard ranking (localStorage)
    sound.ts           Synthesized sound effects
    battleMessages.ts  Themed hit and miss commentary
    gameLogic.test.ts  Tests for shots, sinking, winning, placement and the AI

Game logic

• Fleet: each side has five ships with the standard sizes 5, 4, 3, 3 and 2. fleet.ts holds the rules as pure functions that don't touch React: checkPlacement, randomPlacements, shipAt, sunkShipIds, and fireShot, which resolves a single shot. Both the player's placement and the AI's placement use the same rules.
• Screens: Game.tsx shows the home screen first. Start Battle opens a fresh battle against the chosen difficulty. Main menu returns home, and asks for confirmation if a battle is under way. Every finished game is saved to the leaderboard; abandoned games are not.
• State: Game.tsx owns all game state: both fleets, both sets of shots (Map<coord, "hit" | "miss">), whose turn it is, and the winner. The boards only display what they're given.
• Turn flow: firing unlocks once all five Roman ships are placed, and the Roman fleet locks after the first shot. Rome fires, then Carthage replies after about 1.5 seconds. An already-attacked square can't be fired at again: its button is disabled, and fireShot also rejects a repeat shot.
• Sinking and winning: a ship is sunk when every one of its squares has been hit. When all five ships on one side are sunk, the winner is recorded, both boards lock and the full Carthaginian fleet is revealed.
• Hidden fleet: Carthage's layout is generated in the browser after the page loads. This is because Next.js pre-renders the page ahead of time with cacheComponents, and doesn't allow random values during that step. The layout is kept in a React ref, so it doesn't appear in the page until a ship is sunk.

This is the beginning of the README. Read the rest at the original. Read the full README ↗