Game of the Generals 3D

A 3D online multiplayer implementation of the classic Filipino strategy board game, Game of the Generals (Salpakan), invented by Sofronio H. Pasola Jr. in 1970. Command an army of ranked officers, outmaneuver your opponent, and capture their flag to win.

• Online Multiplayer — Create or join rooms with a 6-character code. Real-time sync via Socket.io with reconnection support.
• Local Hot-Seat — Two players on the same device, with a pass-device screen between turns.
• vs. AI — Three difficulty levels: Easy (random), Medium (heuristic), Hard (minimax-like strategy).
• Tutorial Mode — Learn the rules and piece rankings.
• 3D Board — Three.js + React Three Fiber rendering with orbit camera (rotate, pan, zoom).
• Combat System — Rank-based combat with spy mechanics, combat outcome modals, and move history log.
• Audio — Sound effects via Howler.js.
• Military UI — Share Tech Mono font, command center aesthetic, piece info panels and rank tooltips.

Install dependencies:

npm install

Run the Next.js dev server (UI only, no WebSocket):

npm run dev

Run the WebSocket server (required for online multiplayer):

npm run dev:server

Open http://localhost:3000 in your browser.

For online multiplayer in development, run both commands in separate terminals.

npm run build
npm run start:server

npm test

Objective: Capture the opponent's flag, or move your own flag to the opponent's base row.

Setup: Each player arranges 21 pieces in their 3 base rows before the game begins.

Movement: Pieces move one square orthogonally (no diagonals). Moving onto an opponent's piece initiates combat.

Combat: The higher-ranked piece wins. Special rules:

• The Spy defeats all officers but loses to Privates.
• The Flag loses to all pieces.
• Equal ranks result in both pieces being eliminated.

Piece ranks (strongest to weakest): 5-Star General, 4-Star General, 3-Star General, 2-Star General, 1-Star General, Colonel, Lt. Colonel, Major, Captain, 1st Lieutenant, 2nd Lieutenant, Sergeant, Private, Spy, Flag.

app/            # Next.js pages (menu, local, online, AI, tutorial)
components/
  game/         # 3D board, pieces, camera, combat effects
  ui/           # Setup phase, lobby, chat, modals, HUD panels
lib/
  engine/       # Core game logic (state, board, pieces, combat, moves, win conditions)
  ai/           # AI players (random, medium, hard)
  socket/       # Socket.io events, room manager, client
  audio/        # Sound manager and React hook
shared/         # Shared constants (board size, ranks, setup rows)
store/          # Zustand stores (local, online, AI, UI)
server.ts       # Node.js + Socket.io server for online multiplayer

The app is configured for both Fly.io (fly.toml) and Vercel (vercel.json).

Fly.io (recommended for WebSocket support):

fly deploy

Runs the full server.ts WebSocket server on port 3000 with HTTPS enforced.

Vercel supports the Next.js frontend but requires a separate WebSocket server for online multiplayer.