# QuakeJS - Browser FPS Arena

> Play Quake III Arena directly in your browser. No downloads. No plugins. Just frags.

QuakeJS is a browser-based first-person shooter inspired by Quake III Arena, built with Next.js, React Three Fiber, and Rapier physics. It features a full 3D game engine running in WebGL with AI bots, 7 weapons, health/armor pickups, jump pads, teleporters, and multiple game modes.

## Core Features

- **Browser-native FPS**: No downloads or plugins required. Runs in any modern browser with WebGL support.
- **7 Classic Weapons**: Gauntlet, Machine Gun, Shotgun, Rocket Launcher, Railgun, Lightning Gun, Plasma Gun.
- **AI Bots**: 5 AI-controlled opponents with pathfinding and combat behavior.
- **Game Modes**: Free For All (FFA), Team Deathmatch (TDM), Duel, Capture The Flag (CTF).
- **Arena Map**: Q3DM17-inspired floating platform arena with jump pads, teleporters, and kill volumes.
- **HUD**: Health, armor, ammo, crosshair, kill feed, scoreboard, timer.
- **Server Browser**: Browse and filter game servers by mode, region, and player count.
- **Leaderboard**: Player rankings by frags, K/D ratio, wins, and playtime.

## API Endpoints

- `GET /api/health` - Service health check
- `GET /api/docs` - OpenAPI 3.1 specification
- `GET /api/v1/servers` - List game servers (filterable by mode, region)
- `POST /api/v1/servers` - Register a new game server (multiplayer hub registration)
- `GET /api/v1/servers/:id` - Server details with connected players and rules
- `PATCH /api/v1/servers/:id` - Update server status/player count (heartbeat)
- `DELETE /api/v1/servers/:id` - Deregister a server from the hub
- `GET /api/v1/leaderboard` - Player leaderboard (sortable, paginated)
- `GET /api/v1/stats` - Global game statistics (players, matches, weapons)
- `GET /api/v1/matches` - Recent match history (paginated)
- `POST /api/v1/matches` - Record a match result (idempotent)
- `POST /api/webhooks` - Webhook receiver (signed, idempotent, retryable)
- `GET /api/events` - Event outbox (filterable by type, delivery status)

## MCP (Model Context Protocol)

QuakeJS exposes an MCP-compatible tool server for AI agent integration:

- `GET /api/mcp` - MCP server manifest (server info, protocol version, tool list)
- `POST /api/mcp` - JSON-RPC 2.0 endpoint for tool invocation

### Available MCP Tools

- `list_servers` - List active game servers (filter by mode, region)
- `get_server` - Get server details by ID (players, rules, map)
- `get_leaderboard` - Get player rankings (sort by frags, K/D, wins)
- `get_global_stats` - Global statistics (players, matches, weapons, modes)
- `list_matches` - Recent completed match history
- `register_server` - Register a new game server with the hub (multiplayer support)

Protocol: JSON-RPC 2.0, MCP version 2024-11-05.
See also: https://mcp.platphormnews.com/api/mcp

## Technical Stack

- **Frontend**: Next.js 16 App Router, React, TypeScript, Tailwind CSS
- **3D Engine**: React Three Fiber (Three.js), @react-three/drei
- **Physics**: @react-three/rapier (Rapier WASM)
- **State Management**: Zustand
- **Audio**: Web Audio API (procedural synthesis)
- **API**: Edge Runtime, OpenAPI 3.1, MCP 2024-11-05

## Platform Ecosystem (PlatphormNews)

- Platform hub: https://platphormnews.com
- Games directory: https://games.platphormnews.com
- MCP tool server: https://mcp.platphormnews.com/api/mcp
- MCP tool docs: https://mcp.platphormnews.com/api/docs
- Calendar events: https://calendar.platphormnews.com/api/docs
- Jobs board: https://jobs.platphormnews.com/api/docs

## Links

- [Play Now](https://quakejs.com/play)
- [Server Browser](https://quakejs.com)
- [Leaderboard](https://quakejs.com/leaderboard)
- [API Docs](https://quakejs.com/api/docs)
- [MCP Server](https://quakejs.com/api/mcp)
- [RSS Feed](https://quakejs.com/rss.xml)
- [Sitemap](https://quakejs.com/sitemap.xml)

## Optional

- [Full LLM Context](https://quakejs.com/llms-full.txt)
- [LLM Index](https://quakejs.com/llms-index.json)