Node Chess AI

A real-time multiplayer chess game where AI plays against the community. Built with Node.js, Socket.IO, and Three.js.

Overview

Node Chess AI is an innovative chess platform where:

• White (AI): Powered by various AI models (Claude Sonnet, Grok, Gemini, GPT-3.5)
• Black (Community): Played collectively by users through voting

Users can suggest moves via the website or through PumpFun live chat integration. The most voted move is played when the timer ends.

Features

AI vs Community

• Multiple AI models rotate as White player
• Community votes on moves for Black
• Real-time voting system with configurable duration
• Tie-breaker: Random selection among top-voted moves

Natural Language Input

• Write moves in plain English: "move the rightmost pawn forward"
• AI translates natural language to chess notation
• Supports both standard notation (e5, Nf3) and descriptive input

PumpFun Chat Integration

• Connect to PumpFun live chat for move suggestions
• Wallet addresses are automatically masked (abc1...xyz9)
• Distinguishes between chat messages and move requests

3D Chess Board

• Beautiful Three.js rendered chess board
• Smooth piece animations
• Camera fixed on Black's perspective

Real-time Updates

• Live vote counting and display
• Countdown timer on board and side panel
• Move announcements with animations
• AI thinking log

Tech Stack

• Backend: Node.js, Express.js
• Real-time: Socket.IO
• Chess Logic: chess.js
• AI: OpenRouter API (supports multiple models)
• 3D Graphics: Three.js
• External Chat: PumpFun WebSocket integration

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• OpenRouter API key

Setup

1. Clone the repository:

git clone https://github.com/devaiacc/npm-run-chess.git
cd npm-run-chess

2. Install dependencies:

npm install

3. Create .env file:

OPENROUTER_API_KEY=your_openrouter_api_key
AI_LOG=true
CONTRACT=your_contract_address
DEV=https://x.com/your_handle
LIVE_CHAT=true
HYBRID_CHAT=true
VOTE_DURATION=60

4. Start the server:

npm start

5. Open browser at http://localhost:3000

Environment Variables

Variable	Description	Default
OPENROUTER_API_KEY	API key for OpenRouter	Required
AI_LOG	Enable AI debug logging	false
CONTRACT	Token contract address (displayed in UI)	-
DEV	Developer Twitter/X link	-
LIVE_CHAT	Enable PumpFun chat integration	false
HYBRID_CHAT	Allow both website and PumpFun input	false
VOTE_DURATION	Voting duration in seconds	30

How It Works

Game Flow

1. AI (White) makes the first move
2. Community voting begins for Black's response
3. Users suggest moves via:
   • Direct chess notation (e.g., e5, Nxd4)
   • Natural language (e.g., "move knight to f6")
4. Timer counts down (configurable duration)
5. Most voted legal move is played
6. If no votes received, timer restarts
7. Repeat until game ends

Voting Rules

• Each message counts as one vote
• Users can submit multiple suggestions
• Invalid moves are rejected and highlighted in red
• Ties resolved by random selection

AI Models (White)

The AI randomly selects from:

• Claude Sonnet 4.5
• Grok 4.1 Fast
• Gemini 3 Flash
• GPT-3.5 Turbo

Move translation uses GPT-4o-mini for accuracy.

Project Structure

node-chess-ai/
├── server.js              # Main server & game logic
├── package.json
├── Procfile               # Heroku deployment
├── public/
│   ├── index.html         # Main HTML
│   ├── main.js            # Frontend logic
│   ├── style.css          # Styles
│   └── chess3d.js         # Three.js chess board
└── services/
    └── pumpFunChatClient.js  # PumpFun chat integration

API Events (Socket.IO)

Client → Server

Event	Description
suggestMove	Submit a move suggestion

Server → Client

Event	Description
gameState	Current game state (FEN, players, etc.)
moveMade	A move was played
voteUpdate	Vote counts updated
voteTimerStart	Voting period started
voteTimerEnd	Voting period ended
communityMove	Community's move was played
moveRejected	Invalid move rejected
pumpfunStatus	PumpFun connection status

Deployment

Heroku

heroku create your-app-name
heroku config:set OPENROUTER_API_KEY=your_key
heroku config:set LIVE_CHAT=true
heroku config:set VOTE_DURATION=60
git push heroku main

License

ISC License

Author

Built with by @llmxbt