🎮 NPC Arena v2

A browser-based AI arena game where LLM-powered NPCs compete in team-based challenges. Watch AI agents explore, strategize, and solve puzzles in real-time!

✨ Features

• 4 AI NPCs in 2 competing teams (Red vs Blue)
• Real-time LLM decisions using Groq/Gemini APIs
• Team-based challenges requiring coordination
• Zone exploration with locked gates and puzzles
• Live commentary generated by AI
• WebSocket real-time updates

🚀 Quick Start

# Clone the repo
git clone https://github.com/07AMIT10/npc.git
cd npc

# Set up API keys
export GROQ_API_KEY=your_groq_key      # Fast action decisions
export GEMINI_API_KEY=your_gemini_key  # Strategic brain

# Run the server
go run ./cmd/server/main.go

# Open http://localhost:8080

🏗️ Architecture

┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│  Browser UI  │ ←→  │  Go Server  │ ←→  │  LLM APIs    │
│  (Canvas)    │ WS  │  (Fiber)    │     │ (Groq/Gemini)│
└──────────────┘     └─────────────┘     └──────────────┘

Project Structure

npc/
├── cmd/server/main.go       # Entry point
├── internal/
│   ├── api/                 # LLM integration & orchestration
│   ├── llm/                 # Provider adapters & load balancing
│   ├── game/                # World, teams, zones
│   ├── challenge/           # Puzzle system
│   └── observability/       # Tracing & audit logs
├── web/
│   ├── index.html           # Game page
│   ├── game.js              # Canvas rendering
│   └── style.css            # Dark theme UI
└── config.yaml              # Configuration

---

📋 Implementation Roadmap

Current Focus Areas

1. Cost Optimization - Reduce LLM API costs
2. Visual Polish - Modern UI with animations
3. Scalability - Prepare for deployment

---

🔴 Phase 1: Cost Optimization

Problem

Currently: 4 NPCs × 15 decisions/min = 60 API calls/minute

Solution: Multi-NPC Single Prompt

Instead of 4 separate API calls, combine all NPCs into ONE prompt:

// Before: 4 calls
for _, npc := range npcs {
    decision := callLLM(npc.observation)
}

// After: 1 call
combinedPrompt := `
NPCs:
1. Explorer (red) at [100,100], sees gate at dist 350
2. Scout (red) at [200,150], sees Wanderer at dist 400
3. Wanderer (blue) at [800,600], sees gate at dist 250
4. Seeker (blue) at [750,550], idle

Respond with decisions for ALL NPCs as JSON array.
`
decisions := callLLM(combinedPrompt) // 1 call instead of 4!

Expected savings: ~75%

Additional Optimizations

Optimization	Savings
Multi-NPC prompts	75% fewer calls
Decision caching	30% cache hits
Token compression	73% smaller prompts
Total	~85% reduction

---

🎨 Phase 2: Visual Polish (React Migration)

Current State

• Vanilla JS (1274 lines in single file)
• Basic canvas rendering
• No animations or effects

Target Architecture

src/
├── components/
│   ├── GameCanvas/          # Canvas + particle system
│   ├── Sidebar/             # React components
│   ├── Header/              # Animated scoreboard
│   └── Overlay/             # Tooltips, modals
├── store/
│   └── gameStore.ts         # Zustand state
└── hooks/
    └── useWebSocket.ts      # WS connection

Planned Visual Features

Feature	Description
Particle System	Movement trails, gate unlock effects
Animated Scores	Count-up animation with glow
Tooltips	Hover over NPCs/gates for info
Minimap	Overview in corner
Smooth Transitions	Framer Motion animations

Particle Effects

class ParticleSystem {
  // NPC movement - subtle dust trail
  emitMovementTrail(x, y, color) {...}
  
  // Gate unlock - celebration burst
  emitGateUnlock(x, y) {...}
  
  // Challenge - thinking sparkles
  emitThinkingSparkles(npc) {...}
}

---

🚀 Phase 3: Deployment

Hosting Comparison

Platform	Cost	Cold Start	Best For
Render	Free	30s after 15min	Getting started
Fly.io	~$0-5/mo	<1s	Production
Railway	Free tier	Similar to Render	Quick deploys

Quick Deploy to Render

1. Fork this repo on GitHub
2. Create new Web Service on Render
3. Connect your GitHub repo
4. Set environment variables:
   • GROQ_API_KEY - Your Groq API key
   • GEMINI_API_KEY - Your Gemini API key
5. Deploy!

Keep-Alive with UptimeRobot

1. Sign up at UptimeRobot (free)
2. Create HTTP(s) monitor
3. URL: https://your-app.onrender.com/health
4. Interval: 14 minutes
5. Server stays awake during monitored hours!

Local Docker Build

docker build -t npc-arena .
docker run -p 8080:8080 \
  -e GROQ_API_KEY=your_key \
  -e GEMINI_API_KEY=your_key \
  npc-arena

---

🔧 Go-Specific Improvements

1. Context Cancellation

Enable cancelling in-flight LLM calls when users reset:

ctx, cancel := context.WithCancel(context.Background())
// User clicks Reset → cancel() → saves API tokens

2. Connection Pooling

transport := &http.Transport{
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 10,
}

3. Rate Limiting with stdlib

import "golang.org/x/time/rate"
limiter := rate.NewLimiter(rate.Limit(5), 5)
limiter.Wait(ctx) // Context-aware!

---

🔑 API Configuration

Environment Variables

# Fast SLM (pick one)
GROQ_API_KEY=xxx            # Recommended
SAMBANOVA_API_KEY=xxx
HF_API_KEY=xxx

# Brain LLM
GEMINI_API_KEY=xxx          # Recommended

# Optional: Per-NPC overrides
NPC_EXPLORER_PROVIDER=groq
NPC_EXPLORER_MODEL=llama-3.1-70b

Config File (config.yaml)

game:
  tick_rate: 60
  decision_rate: 2
  
model_roles:
  movement:
    provider: groq
    model: llama-3.1-8b-instant
  challenge:
    provider: gemini
    model: gemini-2.0-flash

---

🎯 Controls

Button	Action
▶ Start	Begin simulation
⏸ Pause	Freeze NPCs
🔄 Reset	Restart world

---

📊 Endpoints

Endpoint	Description
GET /	Game UI
GET /health	Server status
GET /stats	LLM statistics
GET /test	Test all providers
WS /ws	Real-time game updates

---

🛠️ Development

# Run with hot reload
go run ./cmd/server/main.go

# Run tests
go test ./...

# Build binary
go build -o npc-server ./cmd/server

---

📝 License

MIT

---

🙏 Acknowledgments

• Groq - Ultra-fast LLM inference
• Google Gemini - Strategic AI
• Fiber - Go web framework