Spades Arena: Offline Multiplayer

Play. Win. Rule. — made by Hadzz.

A responsive HTML/CSS/JavaScript web application featuring a complete, playable 4-seat offline Spades game with 5 fair AI difficulty levels, Nil and bag scoring, local profile/coin/avatar progression, and complete frontend screens & state contracts ready for Claude to connect online multiplayer and friend services.

---

1. How to Run the App

Option A: Open Directly in Browser (Zero Setup)

Because all scripts use the universal window.SpadesHadzz namespace (avoiding file:// CORS restrictions), you can simply double-click index.html in Finder/Explorer or open it in any desktop or mobile browser.

Option B: Run a Local Static Server

python3 -m http.server 8080

Then open http://localhost:8080 in your browser.

---

2. Project File Structure

• index.html — App shell containing the Loading Screen ("Spades by Hadzz"), persistent top HUD bar, Main Menu, Offline Game Table, Multiplayer Lobby, Friends & Directory screen, Profile & Avatar Shop, Settings, and Rules / Help.
• styles.css — Spade-green casino felt aesthetic, playing card typography, responsive desktop/mobile layout, animations, and .reduced-motion accessibility mode.
• js/avatars.js — 10 Free Avatars and 5 Locked Legendary Avatars (priced at 60, 70, 80, 90, and 100 coins) rendered via self-contained procedural SVG illustrations.
• js/audio.js — Procedural Web Audio API sound effects (card deal, card play, trick win, Spades broken, illegal play buzzer, coin reward chime) and ambient table lounge music toggle.
• js/store.js — Local persistence (localStorage) for username, starting 60-coin balance, avatar ownership, anti-duplicate round/match reward ledger (rewardedIds), and settings.
• js/engine.js — 4-seat Spades rules engine: 52-card deal (13 cards per player), 0–10 bidding, suit-following enforcement, trump Spade breaking rules, trick winner resolution, Nil (+100/-100) scoring, overtrick bags, and 10-bag (-100) penalties.
• js/bot.js — Fair 5-level AI (Beginner, Easy, Medium, Hard, Impossible). Bots receive only their own hand, bids, and public played-card history—never hidden hands or undealt cards.
• js/network-adapter.js — Live WebSocket client: accounts/login sessions, lobbies, server-synced matches, friends, presence, invites & quick chat.
• server/ — Node.js multiplayer server (server.js protocol & directory, match.js authoritative game, ws-lite.js WebSocket layer).
• js/app.js — Main UI controller coordinating screens, offline match loop, preset quick chat & emoji reactions, profile shop, and settings.

---

3. Online Multiplayer Server (Live)

Online play, accounts, friends, presence, invites and quick chat run on a small zero-dependency Node.js server in server/ (Node 18+).

node server/server.js          # → http://localhost:8787  (WebSocket: ws://<host>:8787/ws)

• Open http://localhost:8787 — the server also hosts the app, so the client connects to it automatically.
• Android phones/tablets on the same Wi-Fi: open http://<your-computer-LAN-IP>:8787. If the app is loaded some other way (file://, APK WebView), tap ⚙ Server on the Login/Lobby screen and enter <LAN-IP>:8787 or wss://your-domain/ws.
• Public internet: deploy server/ to any Node host (Render, Fly.io, Railway, a VPS) behind HTTPS so traffic uses wss:// — passwords are sent over the socket, so always use TLS outside your own network.
• Env vars: PORT (8787), HOST (0.0.0.0), DATA_DIR (default server/data/), SPADES_MSG_LIMIT (messages per 5 s per socket, default 120).
• Player accounts persist in server/data/db.json (passwords hashed with scrypt + salt; login sessions stored only as SHA-256 hashes).

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗