🌊 Battleship P2P 🚀

Drop in. Aim true. Sink everything. 🔥

Battleship, the classic naval combat game — reborn for the modern web. No downloads. No accounts. Just open a link, share a code, and wage full-on fleet war against a friend. 🛠️

⚡ Built with Astro, WebRTC, and pure vanilla JS — all game data flows peer-to-peer between browsers. Zero server-side game logic. Maximum privacy. Minimum latency.

---

🔥 Why You'll Love It

Feature	The Deal
🧡 True P2P	Your shots never touch a game server — browsers connect directly via WebRTC
🌐 Zero Sign-Up	Open the URL. Pick a mode. Share a 6-character code. That's it.
🔥 Three Game Modes	Round-Based for fast-fire thrills, Queue-Based for chill tactical play, Hybrid for the best of both
🚙 Special Ships	Sneaky submarines that hide until first hit. Shifting torpedo boats that dodge after a miss.
🎨 Canvas Graphics	Smooth HTML5 Canvas rendering with fire & splash animations
📍 LAN-Ready	Works on your home network, at a hackathon, or across the globe

---

🛠️ How to Play in 30 Seconds

1. Open the game URL in any modern browser 🖤️
2. Create a game (or join with a code)
3. Pick your mode:
   • ⏱️ Round-Based — 3-second timer per round. Fast decisions. Who blinks first?
   • 🦄 Queue-Based — Fire whenever you're ready. No pressure. Maximum strategy.
   • 🔄 Hybrid — Timer + grace period. Structure and flexibility.
4. Share the 6-char code with your opponent via chat, DM, or carrier pigeon 🕊
5. Click to fire. Sink all 6 ships to win. ⚔️

The Fleet

Ship	Size	🎯 Special Ability
🛝 Carrier	5 cells	Classic heavy hitter
🚢 Battleship	4 cells	Second only to the carrier in power
🛣️ Heavy Cruiser	3 cells	Solid workhorse of the fleet
🛣️ Light Cruiser	3 cells	Agile and versatile
🐲 Submarine	2 cells	Hidden until first hit — invisible threat!
🚥 Torpedo Boat	2 cells	Shifts position after a miss — never still for long!

---

🚀 Quick Start

# Install dependencies
pnpm install

# Start the Astro dev server
pnpm dev            # 🎲️  http://localhost:4321

For local multiplayer testing, also start the single-origin production-style server after building:

pnpm build
pnpm server         # 🔍  http://localhost:4321 with /signaling WebSocket

Open two browser tabs, create a game in one, join with the code in the other. Done. 🎉

Host friends over a tunnel

Want a friend on another computer to join? Run the guided setup — it picks a tunnel, signs you in, and opens one public link to share:

pnpm tunnel:setup        # interactive: pick zrok/ngrok, install, sign in, host
pnpm tunnel:doctor       # friendly "is everything ready?" health check

Prefer to do it by hand?

pnpm tunnel:install:zrok        # project-local, checksum-verified
.tools/bin/zrok2 enable <token> # one-time sign-in (see the Hosting guide)
pnpm tunnel:zrok                # build, serve, and open a zrok tunnel

pnpm tunnel:install:ngrok       # system-wide via your OS package manager
ngrok config add-authtoken <token>
pnpm tunnel:ngrok

zrok installs project-local into .tools/ (checksum-verified); ngrok installs system-wide via your OS package manager. The Hosting guide explains why, where to get a free token, and how to troubleshoot.

Windows users run the PowerShell helper directly:

.\scripts\tunnel-setup.pwsh setup

---

💾 Under the Hood

Browser (Player 1)  <──────── WebRTC P2P ────────►  Browser (Player 2)
        ▲                                                 ▲
        │  Signaling handshake only (SDP + ICE)           │
        └────────── Node.js / WebSocket ─────────────────┘

• Game state lives entirely in each player's browser 🧰
• Signaling server handles only the initial WebRTC handshake on /signaling — it never sees a single move
• Rendering via vanilla HTML5 Canvas with requestAnimationFrame loop
• Zero dependencies on UI frameworks — just pure, performant JS

---

📚 Documentation

Want a feel for the game first? Take the 📸 Screenshots tour — a few annotated shots from start screen to firing the first salvo.

Start at the Guide index — it routes you by what you want to do:

• 🎮 Playing — a friend sent you a link or a code. Zero setup, just a browser.
• 🎉 Hosting — invite friends to play online. Run pnpm tunnel:setup and it walks you through everything.
• 🚀 Deploying — put the game on a real web address (static dist/ + signaling).
• 🌱 Seed — run the game natively on a Cognitum One Seed device as a self-contained Rust cog.
• 🔧 Maintainer Docs — project setup, architecture overview, testing, and release process.

---

🧪 Tech Stack

Layer	Tech
🎨 Pages	Astro (static output)
🕹️ Rendering	HTML5 Canvas (vanilla JS)
🔗 Networking	WebRTC DataChannel (P2P)
🔍 Signaling	Node.js ws WebSocket
🎯 Styling	Pure CSS
🧪 Testing	Vitest

---

⚙️ Scripts

# 🏗️  Build & run
pnpm dev          # 🎲️  Astro dev server
pnpm build        # 📦  production bundle
pnpm preview      # 👀  local preview of build
pnpm server       # 🔍  static site + /signaling WebSocket

# 🧭  Host friends over a tunnel (see docs/HOSTING.md for the walkthrough)
pnpm tunnel:setup             # 🧭  guided: pick a tunnel, sign in, host
pnpm tunnel:doctor            # 🩺  health check: is everything ready to host?
pnpm tunnel:install:zrok      # project-local, checksum-verified
pnpm tunnel:uninstall:zrok
pnpm tunnel:install:ngrok     # system-wide (user scope, via package manager)
pnpm tunnel:uninstall:ngrok
pnpm tunnel:zrok              # build, serve, open a zrok tunnel
pnpm tunnel:ngrok             # build, serve, open an ngrok tunnel

# ✅  Quality gates (see docs/MAINTAINERS.md → Developer workflow)
pnpm test         # 🧪  run all tests once
pnpm test:watch   # 👁️   re-run tests on change
pnpm typecheck    # 🔎  astro check (TS + template types)
pnpm lint         # 🧡  ESLint
pnpm lint:fix     # 🔧  ESLint with autofix
pnpm format       # 💾  Prettier across everything
pnpm format:check # 📏  Prettier in check-only mode
pnpm lint:md      # 📖  Markdown lint (markdownlint-cli2)
pnpm lint:md:fix  # 📝  Markdown lint with autofix
pnpm check        # ✅  typecheck + lint + format:check + test
pnpm fix          # 🧹  lint:fix + format (auto-clean everything)

# 📦  Dependency hygiene
pnpm audit            # 🛡️   report known vulnerabilities (also runs weekly in CI)
pnpm audit:fix        # 🔧  apply available audit fixes
pnpm deps:outdated    # 📅  list outdated dependencies
pnpm deps:update      # ⬆️   update within semver ranges
pnpm deps:update:latest  # 🚀  update to latest (may break)

---

🎯 Ship It

Deploy the static dist/ folder to any static hosting provider and run server/index.mjs anywhere that can serve WebSockets:

• 🐶 GitHub Pages — use the included CI workflow
• ⚙️ Netlify / Vercel — connect repo, build cmd: pnpm build
• ☁️ Cloudflare Pages — same build command
• ❄️ S3 + CloudFront — upload dist/ as a static website
• 🌱 Cognitum One Seed — build the Rust cog (cross build --release) and register it on the device; no Node.js required

For LAN parties and demos, pnpm server serves both the static build and signaling on one port.

---

🔝 License

MIT — go forth and wage naval warfare. 🚀🌊