# Vibemancer

> Competitive programming game where you write a TypeScript wizard bot that fights other bots 1v1 in an 800x800 arena. Bots are uploaded to a cloud matchmaker that pairs them against other active wizards; results feed an OpenSkill-rated leaderboard.

## MCP server: https://mcp.vibemancer.com

Connect any MCP-compatible AI assistant to `https://mcp.vibemancer.com` to develop bots entirely from chat. No install needed. Start with the `vibemancer_info` tool to learn the bot API.

## Getting started

- [Build a Wizard](https://vibemancer.com/): five-step walkthrough on the site (Build a Bot tab in the nav). The flow is `npm create vibemancer@latest my-wizard` → edit `src/bot.ts` → `npm run dev` to see it fight live → `npx vibemancer upload` to enter the rated leaderboard.

## What lives where

- Each scaffolded project has an `AGENTS.md` describing the bot API surface, common pitfalls, and verification commands. AI assistants paired with the player should read that first: it's the source of truth for the in-project workflow.
- Game rules: 100 ticks per second; angles in degrees; movement is a direction vector, not a target; spells are missile / shield / blink; one cast at a time per wizard.
- The bot API ships from `@vibemancer/core`: see the package types or the in-project AGENTS.md for the surface.

## Site sections

- **Arena**: pick two wizards (built-in, your own, any player's, or a local-dev bot) and watch them fight a 5-round series.
- **Play**: pilot the blue wizard yourself against any opponent, useful for testing edge cases.
- **Leaderboard**: global OpenSkill ranking of active wizards.
- **History**: every cloud-matchmaker fight, click any to spectate the replay deterministically.
- **My Wizards**: your fleet of uploaded wizards, their ratings and recent matches (sign-in required).
- **Build a Bot**: the getting-started page.

## MCP server (no-install bot development)

Connect any MCP-compatible AI to `https://mcp.vibemancer.com` and develop bots entirely from chat: no terminal, no local install. Tools: vibemancer_info, vibemancer_list_opponents, vibemancer_fight, vibemancer_fight_all, vibemancer_trace, vibemancer_get_my_bots, vibemancer_get_bot_code, vibemancer_upload, vibemancer_feedback. Source code is stored securely on upload (owner-only access) so sessions can be resumed later. Sync back to a local project with `npm run pull`.

The exported function name IS the wizard's identity on the leaderboard (e.g. `export function Sniper()` shows as "Sniper"). Uploading with a new function name creates a new leaderboard entry.

## Local development workflow

`vibemancer dev` boots a local HTTP server that exposes every bot in your project's `src/` tree. The hosted site reads the `#botserver=localhost:PORT` URL hash, fetches your bots from `/local-bots`, and adds a "Local" tab to the wizard picker: fight your in-development bot against built-ins, players, or other local bots without uploading.