create-vibemancer 1.0.12 → 1.0.14

package/dist/index.js

@@ -98,7 +98,7 @@ function vibemancerJson(botName) {
 function botTemplate(botName) {
   return `import {
 	usePosition, useEnemy, useTicksUntilReady, useThreats,
-	missile, shield, move,
+	missile, move,
 	getMissileContext, turnToward, flyStraight,
 	// More actions (all importable from '@vibemancer/core'):
 	//   blink, cancel, idle, turnToAngle,
@@ -204,17 +204,24 @@ export function ${botName}()
 	const dist = Math.sqrt(dx * dx + dy * dy);
 	const angle = Math.atan2(dy, dx) * (180 / Math.PI);
 
-	// While on cooldown, move toward the enemy
-	// move() takes a direction vector, not an absolute position
-	if (ready > 0) return move(dx, dy);
-
-	// Shield if a missile is about to hit (within 30 ticks = 0.3s)
+	// DEFENCE FIRST, and the order matters more than it looks. useTicksUntilReady() is
+	// nonzero for the whole cast AND the GCD after it \u2014 about 99% of a match \u2014 so anything
+	// placed after the \`ready > 0\` return below can essentially never run. This template
+	// used to check for threats down there and raised 0 shields in an entire match.
+	//
+	// Dodging is also what the numbers favour: measured against every ranked built-in,
+	// dodge-only wins 7 matchups, dodge-then-shield 4, shield-first 2. A shield decays while
+	// you hold it and you cannot attack through it, so reach for a sidestep first.
 	const closestThreat = threats[0];
-	if (closestThreat && closestThreat.ticksToImpact < 30)
+	if (closestThreat && closestThreat.willHit && closestThreat.bestDodgeDirection)
 	{
-		return shield();
+		return move(closestThreat.bestDodgeDirection.x, closestThreat.bestDodgeDirection.y);
 	}
 
+	// While on cooldown, move toward the enemy
+	// move() takes a direction vector, not an absolute position
+	if (ready > 0) return move(dx, dy);
+
 	// Fire a homing missile at the enemy
 	// Duration scales with distance so missiles always have enough range
 	// Chain .move() to walk toward enemy at 33% speed while casting

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/scaffolder.ts"],"sourcesContent":["/**\r\n * create-vibemancer\r\n *\r\n * Scaffolds a new Vibemancer wizard bot project.\r\n *\r\n * Usage:\r\n *   npx create-vibemancer my-wizard\r\n *   npx create-vibemancer my-wizard --name MyWizard\r\n */\r\n\r\nimport fs from 'node:fs';\r\nimport path from 'node:path';\r\nimport {\r\n\ttoPascalCase,\r\n\tisValidIdentifier,\r\n\tisValidProjectName,\r\n\tscaffoldProject,\r\n\tRANKED_OPPONENTS,\r\n} from './scaffolder.js';\r\n\r\nconst args = process.argv.slice(2);\r\n\r\nfunction printHelp(): void\r\n{\r\n\tconsole.log(`\r\ncreate-vibemancer - Create a new Vibemancer wizard bot project\r\n\r\nUsage:\r\n  npx create-vibemancer <project-name> [--name <BotName>]\r\n\r\nOptions:\r\n  --name <name>   Bot function name (also the leaderboard name; default: derived from project name)\r\n\r\nExamples:\r\n  npx create-vibemancer my-wizard\r\n  npx create-vibemancer fire-mage --name FireMage\r\n`);\r\n}\r\n\r\nfunction parseArgs(): {projectName: string; botName: string}\r\n{\r\n\tconst projectName = args.find((a) => !a.startsWith('-'));\r\n\tif (!projectName)\r\n\t{\r\n\t\tprintHelp();\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tif (!isValidProjectName(projectName))\r\n\t{\r\n\t\tconsole.error(`Error: \"${projectName}\" is not a valid project name.`);\r\n\t\tconsole.error('Project names must start and end with alphanumeric characters');\r\n\t\tconsole.error('and may contain letters, digits, dots, hyphens, and underscores.');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconst nameIdx = args.indexOf('--name');\r\n\tif (nameIdx !== -1 && !args[nameIdx + 1])\r\n\t{\r\n\t\tconsole.error('Error: --name requires a value.');\r\n\t\tconsole.error('Example: npx create-vibemancer my-bot --name MyBot');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconst botName = nameIdx !== -1 && args[nameIdx + 1]\r\n\t\t? args[nameIdx + 1]\r\n\t\t: toPascalCase(projectName);\r\n\r\n\tif (!isValidIdentifier(botName))\r\n\t{\r\n\t\tconsole.error(`Error: \"${botName}\" is not a valid JavaScript identifier.`);\r\n\t\tconsole.error('Bot names must start with a letter, underscore, or $');\r\n\t\tconsole.error('and contain only letters, digits, underscores, and $.');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\treturn {projectName, botName};\r\n}\r\n\r\nfunction main(): void\r\n{\r\n\tconst {projectName, botName} = parseArgs();\r\n\tconst projectDir = path.resolve(projectName);\r\n\r\n\tif (fs.existsSync(projectDir))\r\n\t{\r\n\t\tconsole.error(`Error: Directory \"${projectName}\" already exists.`);\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconsole.log(`\\nCreating Vibemancer project: ${projectName}`);\r\n\tconsole.log(`Bot name: ${botName}\\n`);\r\n\r\n\ttry\r\n\t{\r\n\t\t// Print what was ACTUALLY written, not a hardcoded list — the old one claimed seven\r\n\t\t// files while eight were created, silently omitting AGENTS.md.\r\n\t\tconst files = scaffoldProject(projectDir, projectName, botName);\r\n\t\tfor (const filePath of files)\r\n\t\t{\r\n\t\t\tconsole.log(`  Created ${filePath}`);\r\n\t\t}\r\n\t}\r\n\tcatch(err)\r\n\t{\r\n\t\tconsole.error(`\\nError creating project: ${err instanceof Error ? err.message : String(err)}`);\r\n\t\ttry\r\n\t\t{\r\n\t\t\tfs.rmSync(projectDir, {recursive: true, force: true});\r\n\t\t}\r\n\t\tcatch\r\n\t\t{\r\n\t\t\t// Best-effort cleanup\r\n\t\t}\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconsole.log(`\r\nDone! To get started:\r\n\r\n  cd ${projectName}\r\n  npm install\r\n  npm test          (verify everything works)\r\n  npm run dev       (start dev server + open browser)\r\n\r\nOther commands:\r\n  npm run fight     Round-robin against all ${RANKED_OPPONENTS} ranked built-ins\r\n  npm run trace     Per-tick debug trace (see exactly what your bot does)\r\n  npm run optimize  Auto-tune bot parameters\r\n\r\nEdit src/bot.ts to change your bot. Refresh the browser to see changes.\r\n`);\r\n}\r\n\r\nmain();\r\n","/**\n * Scaffolder - Core logic for creating a Vibemancer project.\n *\n * Pure functions for validation, naming, and template generation.\n * Separated from index.ts for testability.\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport {fileURLToPath} from 'node:url';\n\n/**\n * How many opponents `npm run fight` actually faces.\n *\n * A LITERAL, deliberately, and guarded by a test rather than derived.\n *\n * I first wrote this as `BOT_GROUPS.flatMap(...).length` imported from @vibemancer/core, and\n * running `npm create vibemancer` proved that wrong immediately: tsup bundles the import, so\n * pulling anything from core's entrypoint drags the whole engine in — including the NATIVE\n * isolated-vm — and the scaffolder crashed on startup before printing a word. A scaffolder\n * that cannot start is worse than a stale number, so the number stays inline and\n * scaffolder.test.ts asserts it against the real roster instead.\n *\n * Hero is excluded on purpose: it is the showcase bot the roster tells players to beat, and\n * it is fought deliberately with `--opponent Hero` rather than swept up in the round-robin.\n */\nexport const RANKED_OPPONENTS = 29;\n\n/**\n * This package's own version, read from its manifest at load time.\n *\n * Read rather than hardcoded so a release bump cannot leave scaffolded projects pinned to\n * an older toolchain — the exact bug this replaced. Falls back to a permissive range if\n * the manifest cannot be found (e.g. an unusual install layout), which is better than\n * emitting a version that does not exist.\n */\nfunction readOwnVersion(): string\n{\n\ttry\n\t{\n\t\tconst here = path.dirname(fileURLToPath(import.meta.url));\n\t\tfor (const rel of ['../package.json', '../../package.json'])\n\t\t{\n\t\t\tconst candidate = path.resolve(here, rel);\n\t\t\tif (!fs.existsSync(candidate)) continue;\n\t\t\tconst parsed: unknown = JSON.parse(fs.readFileSync(candidate, 'utf8'));\n\t\t\tif (typeof parsed !== 'object' || parsed === null) continue;\n\t\t\tif (!('name' in parsed) || !('version' in parsed)) continue;\n\t\t\tconst {name, version} = parsed;\n\t\t\tif (name === 'create-vibemancer' && typeof version === 'string') return version;\n\t\t}\n\t}\n\tcatch\n\t{\n\t\t// fall through\n\t}\n\treturn '';\n}\n\nexport const SCAFFOLDER_VERSION = readOwnVersion();\n\nexport function toPascalCase(str: string): string\n{\n\tlet result = str\n\t\t.replace(/[-_]+/g, ' ')\n\t\t.replace(/\\b\\w/g, (c) => c.toUpperCase())\n\t\t.replace(/\\s+/g, '');\n\n\t// Ensure starts with a letter (prepend underscore if starts with digit)\n\tif (/^\\d/.test(result))\n\t{\n\t\tresult = '_' + result;\n\t}\n\n\treturn result;\n}\n\n/**\n * Validate that a string is a valid JavaScript identifier.\n */\nexport function isValidIdentifier(name: string): boolean\n{\n\treturn /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);\n}\n\n/**\n * Validate that a project name is safe for use as a directory name.\n */\nexport function isValidProjectName(name: string): boolean\n{\n\treturn /^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$/.test(name);\n}\n\n/**\n * The version range new projects pin their Vibemancer toolchain to.\n *\n * Derived from THIS package's own version rather than hardcoded: all five packages are\n * released in lockstep on a single version, so a scaffolder shipped at 0.2.1 must hand out\n * ~0.2.1. It was previously frozen at `~0.1.0` while the published packages had moved to\n * 0.2.1 — and `~0.1.0` means `>=0.1.0 <0.2.0`, so it could never reach them. Every new\n * player was scaffolded onto a stale core and CLI.\n */\nexport function toolchainRange(scaffolderVersion: string = SCAFFOLDER_VERSION): string\n{\n\tif (!scaffolderVersion) return 'latest';\n\treturn `~${scaffolderVersion}`;\n}\n\nexport function packageJson(projectName: string, scaffolderVersion: string = SCAFFOLDER_VERSION): string\n{\n\tconst toolchain = toolchainRange(scaffolderVersion);\n\treturn JSON.stringify({\n\t\tname: projectName,\n\t\tversion: '0.1.0',\n\t\tprivate: true,\n\t\ttype: 'module',\n\t\tscripts: {\n\t\t\tdev: 'vibemancer dev',\n\t\t\ttest: 'vibemancer test',\n\t\t\ttypecheck: 'tsc --noEmit',\n\t\t\tfight: 'vibemancer fight',\n\t\t\ttrace: 'vibemancer trace --opponent TargetDummy',\n\t\t\toptimize: 'vibemancer optimize',\n\t\t\tupload: 'vibemancer upload',\n\t\t\tpull: 'vibemancer pull',\n\t\t\tfeedback: 'vibemancer feedback',\n\t\t\tbuild: 'vibemancer build --opponent Battlemage',\n\t\t},\n\t\tdependencies: {\n\t\t\t'@vibemancer/core': toolchain,\n\t\t},\n\t\tdevDependencies: {\n\t\t\t'vibemancer': toolchain,\n\t\t\t'typescript': '^5.9.0',\n\t\t\t'vitest': '^3.0.0',\n\t\t},\n\t}, null, '\\t') + '\\n';\n}\n\nexport function tsconfigJson(): string\n{\n\treturn JSON.stringify({\n\t\tcompilerOptions: {\n\t\t\ttarget: 'ESNext',\n\t\t\tmodule: 'ESNext',\n\t\t\tlib: ['ESNext'],\n\t\t\tskipLibCheck: true,\n\t\t\tmoduleResolution: 'Bundler',\n\t\t\tstrict: true,\n\t\t\tnoUnusedLocals: true,\n\t\t\tnoUnusedParameters: true,\n\t\t\tisolatedModules: true,\n\t\t\tnoEmit: true,\n\t\t},\n\t\tinclude: ['src', 'tests'],\n\t}, null, '\\t') + '\\n';\n}\n\nexport function vibemancerJson(botName: string): string\n{\n\treturn JSON.stringify({\n\t\tbot: 'src/bot.ts',\n\t\texport: botName,\n\t}, null, '\\t') + '\\n';\n}\n\nexport function botTemplate(botName: string): string\n{\n\treturn `import {\n\tusePosition, useEnemy, useTicksUntilReady, useThreats,\n\tmissile, shield, move,\n\tgetMissileContext, turnToward, flyStraight,\n\t// More actions (all importable from '@vibemancer/core'):\n\t//   blink, cancel, idle, turnToAngle,\n\t// More hooks:\n\t//   useHealth, useBlinkCooldown, useStatus, useVelocity,\n\t//   useCastProgress, useMyProjectiles, useMyThreatsToEnemy,\n\t//   useClosestThreat, useShieldStrength, useCastingSpell,\n\t//   useTick, useArenaSize, useDamageDealt, useDamageTaken,\n\t//   useRandom,\n\t// Utility functions:\n\t//   distanceTo, angleTo, directionTo, directionAway,\n\t//   getLeadPosition, fitMissileToBudget, getMissileCastTime,\n\t//   predictPosition, interceptAngle, clampPositionToArena,\n\t// Persistence hooks (React-style, state preserved across ticks):\n\t//   useState, useRef, useMemo, useEffect\n\t// Parameter tuning (for optimizer):\n\t//   useParam\n} from '@vibemancer/core';\n\n/**\n * ${botName} - Your custom wizard bot!\n *\n * === HOW IT WORKS ===\n * Your function is called EVERY TICK (100x per second). Each call you:\n *   1. Read game state using hooks (usePosition, useEnemy, etc.)\n *   2. Return ONE action (missile, shield, blink, move, cancel, or idle)\n *\n * The function must ALWAYS return an action. During cooldowns (GCD), return\n * move() to keep moving — casting spells during GCD is silently ignored.\n * Check useTicksUntilReady() > 0 to know when you're on cooldown.\n *\n * === GAME RULES ===\n *   Arena:     860x860 total. The PLAYFIELD is [30, 830] — the outer 30 units are LAVA.\n *   LAVA:      Standing in it KILLS YOU. Positions are NOT clamped to the playfield: you\n *              can walk into lava, and knockback can push you in. Many losses are this.\n *   SAFE BOX:  lava is tested against your EDGE, not your centre. usePosition() gives the\n *              centre and your radius is 5, so you die once your centre passes 825 (or\n *              drops below 35). Steer by [35, 825]. Aiming at 828 because the playfield\n *              \"ends at 830\" is fatal.\n *   Health:    60 HP, wizard dies at 0\n *   Timing:    100 ticks = 1 second, match lasts 30,000 ticks (5 min)\n *   Movement:  1.5 units/tick (150 u/s), 33% speed while casting, 0% while shielding\n *   Knockback: missiles above 10 damage shove the target. Yours push them; theirs push you\n *              — possibly into the lava.\n *   GCD:       100 ticks (1s) lockout after any spell completes or is canceled\n *   Thinking:  45 SECONDS of total thinking time per fight (all ten matches share it).\n *              Spend it all and your bot stops being asked for the rest of the fight — it\n *              just stands there. That is NOT a crash: a slow bot loses fights, it does\n *              not get removed from the ladder. There is no per-tick limit, so one slow\n *              tick costs you nothing but the time itself. You will not come close to\n *              this by accident — the worst built-in bot uses about 5.6s of its 45.\n *\n * === SPELLS ===\n *   missile(config, ai, direction)\n *     config: { damage, speed, duration, turnRate }\n *       - damage:   HP removed on hit (1-60). Hitbox radius = (2 + 0.1 x damage) x 3.\n *       - speed:    units/tick (min 1.5, and a wizard moves at 1.5 too — so a minimum-speed\n *                   missile does NOT outrun a fleeing target). Range = speed x duration.\n *       - duration: ticks the missile lives (min 10). Longer = more range but slower cast.\n *       - turnRate: degrees/tick of homing (0 = straight, 3 = moderate, 5+ = strong).\n *     ai: hooks-style function called every tick to steer. Use getMissileContext() to read state, return turnToward(x,y), turnToAngle(deg), or flyStraight().\n *     direction: launch angle in degrees (0=right, 90=down, 180=left, 270=up).\n *     Cast time scales with all stats. Repeated similar missiles cast 20% faster (warmup).\n *     Chain .move(dx, dy) to walk at 33% speed while casting.\n *\n *   shield()\n *     Channeled. Blocks 90% initially, decays 20%/sec, minimum 30%.\n *     0.2s cast time. Immobile while channeling. Cancel with cancel().\n *\n *   blink(x, y)      — Teleport to ABSOLUTE position (not direction). Max 300 units.\n *   move(dx, dy)      — Move in DIRECTION (not position). Speed clamped to [-1, 1].\n *   cancel()          — Cancel current cast/channel. Chain .move() to dodge simultaneously.\n *   idle()            — Do nothing this tick.\n *\n * === KEY TYPES ===\n *   useEnemy() returns:  { position: {x, y}, velocity: {x, y}, health, state, ... }\n *   useThreats() returns array of AnalyzedThreat:\n *     { id, projectile, ticksToImpact, willHit }\n *     - projectile carries the incoming missile's own position/velocity/damage.\n *     - willHit is the one to branch on: a threat that misses needs no reaction.\n *   fitMissileToBudget(budgetTicks, distance, options?) — best missile config for a\n *     cast-time budget. The distance argument is REQUIRED (units to the target).\n *   getLeadPosition(targetPos, targetVel, missileSpeed, myPos) — where to aim at a moving\n *     target. All four are REQUIRED. The third is the MISSILE'S SPEED, not a time.\n *\n *   Both of these previously appeared here with fewer parameters. Calling them that way\n *   does not throw an error you can see — your wizard simply freezes at spawn for the whole\n *   fight and the result still says success. If your bot does nothing, check your arguments\n *   here first.\n *\n * All imports have full JSDoc — hover or jump-to-definition to see docs.\n */\nexport function ${botName}()\n{\n\tconst myPos = usePosition();\n\tconst enemy = useEnemy();\n\tconst ready = useTicksUntilReady();\n\tconst threats = useThreats();\n\n\t// Direction toward enemy (used for movement and aiming)\n\tconst dx = enemy.position.x - myPos.x;\n\tconst dy = enemy.position.y - myPos.y;\n\tconst dist = Math.sqrt(dx * dx + dy * dy);\n\tconst angle = Math.atan2(dy, dx) * (180 / Math.PI);\n\n\t// While on cooldown, move toward the enemy\n\t// move() takes a direction vector, not an absolute position\n\tif (ready > 0) return move(dx, dy);\n\n\t// Shield if a missile is about to hit (within 30 ticks = 0.3s)\n\tconst closestThreat = threats[0];\n\tif (closestThreat && closestThreat.ticksToImpact < 30)\n\t{\n\t\treturn shield();\n\t}\n\n\t// Fire a homing missile at the enemy\n\t// Duration scales with distance so missiles always have enough range\n\t// Chain .move() to walk toward enemy at 33% speed while casting\n\treturn missile(\n\t\t{damage: 25, speed: 6, duration: Math.max(60, Math.ceil(dist / 6) + 20), turnRate: 3},\n\t\t() =>\n\t\t{\n\t\t\t// Missile AI: hooks-style function called every tick to steer the missile\n\t\t\t// Use getMissileContext() to read state, return turnToward/flyStraight\n\t\t\tconst ctx = getMissileContext();\n\t\t\tconst target = ctx.worldState.enemies[0];\n\t\t\tif (!target) return flyStraight();\n\t\t\treturn turnToward(target.position.x, target.position.y);\n\t\t},\n\t\tangle,  // Launch angle in degrees toward enemy\n\t).move(dx, dy);\n}\n`;\n}\n\nexport function readmeMd(botName: string): string\n{\n\treturn `# ${botName} — Vibemancer Bot\n\nThis is a Vibemancer wizard bot project. The bot fights 1v1 against other wizard bots in an 860x860 arena whose outer 30 units are instant-death lava (playfield [30, 830]).\n\n## Quick Start\n\n\\`\\`\\`bash\nnpm test               # Verify everything works\nnpm run dev            # Start dev server + open browser (refresh to see changes)\nnpm run fight          # Round-robin against all ${RANKED_OPPONENTS} ranked built-ins\nnpm run trace          # Per-tick debug trace against TargetDummy\nnpm run typecheck      # Check for type errors (catches bugs esbuild misses)\nnpm run optimize       # Auto-tune useParam() values via optimizer\nnpm run upload         # Upload to vibemancer.com for rated competition\nnpm run pull           # Download latest source from server (after MCP edits)\n\\`\\`\\`\n\nTo trace/fight a specific opponent:\n\\`\\`\\`bash\nnpx vibemancer trace --opponent Battlemage\nnpx vibemancer fight --opponent Nightblade\nnpx vibemancer bots                          # list all bots with descriptions\nnpx vibemancer bots Battlemage               # details about a specific bot\n\\`\\`\\`\n\n## Project Structure\n\n- \\`src/bot.ts\\` — Bot source code (edit this!)\n- \\`tests/bot.test.ts\\` — Automated tests for your bot\n- \\`vibemancer.json\\` — Config: \\`{ \"bot\": \"src/bot.ts\", \"export\": \"${botName}\" }\\`\n\n## Development Workflow\n\n1. Edit \\`src/bot.ts\\`\n2. Run \\`npm run typecheck\\` to catch type errors early\n3. Run \\`npm test\\` to check your bot doesn't crash and beats weak bots\n4. Run \\`npm run fight\\` to rank yourself against all ${RANKED_OPPONENTS} ranked built-ins.\n   Then try the showcase bot the ladder is built around: \\`npx vibemancer fight --opponent Hero\\`\n5. Run \\`npm run trace\\` to see per-tick events when something isn't working\n6. Run \\`npm run optimize\\` to auto-tune useParam() values\n\nFor the browser viewer: run \\`npm run dev\\`, then refresh the browser after editing your bot.\n\n## Difficulty Progression\n\nStart by beating the weakest bots and work your way up:\n\n| Milestone | Bots to Beat | What You Need |\n|-----------|-------------|---------------|\n| Beginner  | TargetDummy, Critter | Basic missile firing |\n| Easy      | Rookie, Hogger, Bonemancer | Homing missiles + movement |\n| Medium    | Turtle, Sentinel, Flamecaller | Shielding + dodge awareness |\n| Hard      | Battlemage (#11), Stormchaser | Cast timing + positioning |\n| Expert    | Archmage, Stormforger | Adaptive missiles + vulnerability punish |\n| Master    | Nightblade (#29) | Everything at once |\n\n## Debugging\n\nWhen your bot isn't working:\n1. \\`npm test\\` — check for runtime errors (captured in test results)\n2. \\`vibemancer trace --opponent TargetDummy\\` — watch exactly what happens tick by tick\n3. Look at the trace stats: hit rate, shield usage, idle time\n4. Look for ERROR and WARNING events in the trace output\n\n## Common Pitfalls\n\n- \\`move(dx, dy)\\` is a **direction vector**, NOT a target position\n- \\`blink(x, y)\\` is an **absolute position**, NOT a direction\n- Calling \\`missile()\\` during GCD is **silently ignored** — check \\`useTicksUntilReady()\\` first\n- Missile range = speed x duration. If range < distance, missiles expire before reaching the enemy\n- All angles are in **degrees** (not radians). Use: \\`Math.atan2(dy, dx) * (180 / Math.PI)\\`\n- All time values are in **ticks** (100 ticks = 1 second)\n- Your bot runs every tick — always return an action, even during cooldowns (\\`move()\\`)\n- \\`fitMissileToBudget()\\` and \\`getLeadPosition()\\` return **null** when no solution exists\n\n## Built-in Bots (29 total, ranked weakest -> strongest)\n\nTargetDummy, Critter, Bonemancer, Hogger, Rookie, Turtle, Sentinel, Flamecaller,\nGolem, Stormchaser, Battlemage, Spellspinner, Doombringer, Lich, Stormcaller,\nSpellbinder, Shadowblade, Pyromancer, Warmage, Spelltracer, Archmage, Spellseeker,\nStormforger, Spellweaver, Spellshot, Voidblade, Infernalist, Archlich, Nightblade\n\nRun \\`vibemancer bots\\` to see descriptions, or \\`vibemancer bots Battlemage\\` for details.\n\n## Strategy Tips\n\n- Shield is strongest at the start (90% block) — cancel early to minimize GCD waste\n- Repeated similar missiles cast 20% faster (warmup). Switching styles costs 20%\n- Higher damage = longer cast time, but DPS always increases with damage\n- Homing missiles (turnRate > 0) are harder to dodge but cost more cast time\n- Straight missiles (turnRate: 0) are fast to cast. Use \\`getLeadPosition()\\` to aim\n- Use \\`useThreats()\\` to decide: dodge (best), shield (good), or eat the hit (risky)\n`;\n}\n\nexport function botTestTemplate(botName: string): string\n{\n\treturn `import {expect, test} from 'vitest';\nimport {testBot} from '@vibemancer/core';\nimport {${botName}} from '../src/bot';\n\n// Run with: npm test\n// These all pass on the starter bot. Keep them green as you change it, and add\n// your own — they are the fastest way to know you have not broken anything.\n\ntest('no runtime errors', () =>\n{\n\tconst result = testBot(${botName}).simulate('TargetDummy');\n\texpect(result.errors).toHaveLength(0);\n});\n\ntest('beats TargetDummy', () =>\n{\n\tconst result = testBot(${botName}).fight('TargetDummy');\n\texpect(result.won).toBe(true);\n});\n\ntest('beats Critter', () =>\n{\n\tconst result = testBot(${botName}).fight('Critter');\n\texpect(result.won).toBe(true);\n});\n\ntest('kills TargetDummy within 15 seconds', () =>\n{\n\tconst result = testBot(${botName}).simulate('TargetDummy', {maxTicks: 1500});\n\texpect(result.won).toBe(true);\n});\n\ntest('lands at least 40% of missiles', () =>\n{\n\tconst result = testBot(${botName}).simulate('Rookie', {maxTicks: 3000});\n\tif (result.stats.missilesLaunched > 0)\n\t{\n\t\texpect(result.stats.hitRate).toBeGreaterThan(0.4);\n\t}\n});\n`;\n}\n\nexport function agentsMd(botName: string): string\n{\n\treturn `# AGENTS.md — context for AI assistants\n\nThis is a [Vibemancer](https://vibemancer.com) wizard-bot project. The goal\nis to write a TypeScript bot that wins 1v1 fights against other wizards in\nan 860x860 arena whose outer 30 units are instant-death lava (playfield [30, 830]).\n\n## Layout\n\n- \\`src/bot.ts\\` — the bot. Edit this. Export must be a single PascalCase\n  function (currently \\`${botName}\\`).\n- \\`tests/bot.test.ts\\` — vitest suite. Add cases as you discover edge\n  cases the bot should handle.\n- \\`vibemancer.json\\` — \\`{ \"bot\": \"src/bot.ts\", \"export\": \"${botName}\" }\\`.\n  Don't move the bot without updating this.\n- \\`README.md\\` — a more thorough developer guide. Skim it once.\n\n## How to verify a change\n\n\\`\\`\\`bash\nnpm test                          # vitest — fast, runs every change\nnpm run typecheck                 # catches typos esbuild would silently bundle\nnpm run fight                     # round-robin against all ${RANKED_OPPONENTS} ranked built-ins\nnpx vibemancer fight --opponent Hero   # the showcase bot — beat this one\nnpx vibemancer trace --opponent <Bot>   # per-tick debug trace\n\\`\\`\\`\n\nTreat \\`npm test\\` as the smallest verifying step. Run it before claiming a\nchange is done.\n\n## The bot API\n\nImported from \\`@vibemancer/core\\`. The bot is called every tick (100 ticks\nper second). It returns an action object — typically built by helpers:\n\n- **Movement:** \\`move(dx, dy)\\` — direction vector (NOT a target). Always\n  return *something* even on cooldown — bare \\`move(0, 0)\\` if you have\n  nothing else to do.\n- **Spells (only one per cast):**\n  - \\`missile({damage, speed, duration, turnRate}, ai, angle)\\` — fire a\n    projectile. Range = speed × duration. Higher damage = longer cast time.\n    The \\`ai\\` is a hooks-style function \\`() => MissileAction\\` — use\n    \\`getMissileContext()\\` to read state, return \\`turnToward(x, y)\\`,\n    \\`turnToAngle(degrees)\\`, or \\`flyStraight()\\`.\n  - \\`shield()\\` — channel a shield. Strongest at start (90% block),\n    decays. Cancel early to free up GCD.\n  - \\`blink(x, y)\\` — teleport to **absolute position** (NOT a direction).\n    Range cap is 300; further targets are clamped along the line.\n- **Hooks** (read state):\n  - \\`usePosition()\\` — your current \\`{x, y}\\`.\n  - \\`useEnemy()\\` — opponent's last-known state.\n  - \\`useThreats()\\` — incoming missiles you might want to dodge/shield.\n  - \\`useTicksUntilReady()\\` — GCD remaining. Cast attempts during GCD are\n    silently ignored — gate on this.\n  - \\`useRandom()\\` — seeded PRNG (\\`() => number\\`). Deterministic. Use\n    instead of \\`Math.random()\\` (blocked in sandbox).\n  - \\`useParam(name, default, {min, max, step})\\` — declare a tunable; the\n    optimizer's coordinate-descent will sweep it.\n\nRead the full surface: \\`packages/core/src/index-browser.ts\\` if you have\nthe monorepo, or jump-to-definition from any \\`@vibemancer/core\\` import.\n\n## Common pitfalls\n\n- All angles are in **degrees**, not radians. Use \\`Math.atan2(dy, dx) * (180 / Math.PI)\\`.\n- All time values are in **ticks**, not seconds. 100 ticks = 1 second.\n- \\`getLeadPosition()\\` and \\`fitMissileToBudget()\\` return **null** when no\n  solution exists — handle that, don't assume non-null.\n- Returning nothing freezes the bot for that tick. Always return at least\n  \\`move(0, 0)\\`.\n- The bot runs in a sandboxed Web Worker / isolated-vm — no \\`fetch\\`,\n  no DOM, no \\`Math.random()\\` (use \\`useRandom()\\` for a seeded,\n  deterministic PRNG).\n\n## Don't\n\n- Don't add new top-level files outside \\`src/\\` and \\`tests/\\` without a\n  reason — the dev server scans \\`src/\\` for bots.\n- Don't add npm dependencies that pull in Node-only modules. Bots are\n  bundled for browser/sandbox execution.\n- Don't mutate globals or the prototype chain — the sandbox freezes them\n  and crashes will be silent.\n\n## Publishing\n\nOnce \\`npm run fight\\` shows acceptable wins:\n\n\\`\\`\\`bash\nnpx vibemancer upload\n\\`\\`\\`\n\nThis signs in (Google), compiles, and ships the bundle to vibemancer.com.\nThe matchmaker auto-pairs your wizard against other active uploads. Watch\nthe leaderboard / your wizard's match history for results, find a\nweakness, edit, re-upload.\n`;\n}\n\nexport function gitignore(): string\n{\n\treturn `node_modules/\ndist/\n.vibemancer/\n*.tgz\n`;\n}\n\n/**\n * Scaffold a new project directory with all template files.\n */\n/**\n * Write the project and RETURN the files written.\n *\n * The caller used to print a hardcoded list of seven while this wrote eight — AGENTS.md,\n * the file the website advertises as the AI-onboarding hook, was created silently and left\n * out of the scaffolder's own output. Returning the list makes that drift impossible.\n */\nexport function scaffoldProject(projectDir: string, projectName: string, botName: string): string[]\n{\n\tconst files: [string, string][] = [\n\t\t['package.json', packageJson(projectName)],\n\t\t['tsconfig.json', tsconfigJson()],\n\t\t['vibemancer.json', vibemancerJson(botName)],\n\t\t['src/bot.ts', botTemplate(botName)],\n\t\t['tests/bot.test.ts', botTestTemplate(botName)],\n\t\t['README.md', readmeMd(botName)],\n\t\t['AGENTS.md', agentsMd(botName)],\n\t\t['.gitignore', gitignore()],\n\t];\n\n\tfs.mkdirSync(path.join(projectDir, 'src'), {recursive: true});\n\tfs.mkdirSync(path.join(projectDir, 'tests'), {recursive: true});\n\n\tfor (const [filePath, content] of files)\n\t{\n\t\tconst fullPath = path.join(projectDir, filePath);\n\t\tfs.writeFileSync(fullPath, content);\n\t}\n\n\treturn files.map(([filePath]) => filePath);\n}\n"],"mappings":"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","names":["fs","path","path","fs"]}
+{"version":3,"sources":["../src/index.ts","../src/scaffolder.ts"],"sourcesContent":["/**\r\n * create-vibemancer\r\n *\r\n * Scaffolds a new Vibemancer wizard bot project.\r\n *\r\n * Usage:\r\n *   npx create-vibemancer my-wizard\r\n *   npx create-vibemancer my-wizard --name MyWizard\r\n */\r\n\r\nimport fs from 'node:fs';\r\nimport path from 'node:path';\r\nimport {\r\n\ttoPascalCase,\r\n\tisValidIdentifier,\r\n\tisValidProjectName,\r\n\tscaffoldProject,\r\n\tRANKED_OPPONENTS,\r\n} from './scaffolder.js';\r\n\r\nconst args = process.argv.slice(2);\r\n\r\nfunction printHelp(): void\r\n{\r\n\tconsole.log(`\r\ncreate-vibemancer - Create a new Vibemancer wizard bot project\r\n\r\nUsage:\r\n  npx create-vibemancer <project-name> [--name <BotName>]\r\n\r\nOptions:\r\n  --name <name>   Bot function name (also the leaderboard name; default: derived from project name)\r\n\r\nExamples:\r\n  npx create-vibemancer my-wizard\r\n  npx create-vibemancer fire-mage --name FireMage\r\n`);\r\n}\r\n\r\nfunction parseArgs(): {projectName: string; botName: string}\r\n{\r\n\tconst projectName = args.find((a) => !a.startsWith('-'));\r\n\tif (!projectName)\r\n\t{\r\n\t\tprintHelp();\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tif (!isValidProjectName(projectName))\r\n\t{\r\n\t\tconsole.error(`Error: \"${projectName}\" is not a valid project name.`);\r\n\t\tconsole.error('Project names must start and end with alphanumeric characters');\r\n\t\tconsole.error('and may contain letters, digits, dots, hyphens, and underscores.');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconst nameIdx = args.indexOf('--name');\r\n\tif (nameIdx !== -1 && !args[nameIdx + 1])\r\n\t{\r\n\t\tconsole.error('Error: --name requires a value.');\r\n\t\tconsole.error('Example: npx create-vibemancer my-bot --name MyBot');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconst botName = nameIdx !== -1 && args[nameIdx + 1]\r\n\t\t? args[nameIdx + 1]\r\n\t\t: toPascalCase(projectName);\r\n\r\n\tif (!isValidIdentifier(botName))\r\n\t{\r\n\t\tconsole.error(`Error: \"${botName}\" is not a valid JavaScript identifier.`);\r\n\t\tconsole.error('Bot names must start with a letter, underscore, or $');\r\n\t\tconsole.error('and contain only letters, digits, underscores, and $.');\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\treturn {projectName, botName};\r\n}\r\n\r\nfunction main(): void\r\n{\r\n\tconst {projectName, botName} = parseArgs();\r\n\tconst projectDir = path.resolve(projectName);\r\n\r\n\tif (fs.existsSync(projectDir))\r\n\t{\r\n\t\tconsole.error(`Error: Directory \"${projectName}\" already exists.`);\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconsole.log(`\\nCreating Vibemancer project: ${projectName}`);\r\n\tconsole.log(`Bot name: ${botName}\\n`);\r\n\r\n\ttry\r\n\t{\r\n\t\t// Print what was ACTUALLY written, not a hardcoded list — the old one claimed seven\r\n\t\t// files while eight were created, silently omitting AGENTS.md.\r\n\t\tconst files = scaffoldProject(projectDir, projectName, botName);\r\n\t\tfor (const filePath of files)\r\n\t\t{\r\n\t\t\tconsole.log(`  Created ${filePath}`);\r\n\t\t}\r\n\t}\r\n\tcatch(err)\r\n\t{\r\n\t\tconsole.error(`\\nError creating project: ${err instanceof Error ? err.message : String(err)}`);\r\n\t\ttry\r\n\t\t{\r\n\t\t\tfs.rmSync(projectDir, {recursive: true, force: true});\r\n\t\t}\r\n\t\tcatch\r\n\t\t{\r\n\t\t\t// Best-effort cleanup\r\n\t\t}\r\n\t\tprocess.exit(1);\r\n\t}\r\n\r\n\tconsole.log(`\r\nDone! To get started:\r\n\r\n  cd ${projectName}\r\n  npm install\r\n  npm test          (verify everything works)\r\n  npm run dev       (start dev server + open browser)\r\n\r\nOther commands:\r\n  npm run fight     Round-robin against all ${RANKED_OPPONENTS} ranked built-ins\r\n  npm run trace     Per-tick debug trace (see exactly what your bot does)\r\n  npm run optimize  Auto-tune bot parameters\r\n\r\nEdit src/bot.ts to change your bot. Refresh the browser to see changes.\r\n`);\r\n}\r\n\r\nmain();\r\n","/**\n * Scaffolder - Core logic for creating a Vibemancer project.\n *\n * Pure functions for validation, naming, and template generation.\n * Separated from index.ts for testability.\n */\n\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport {fileURLToPath} from 'node:url';\n\n/**\n * How many opponents `npm run fight` actually faces.\n *\n * A LITERAL, deliberately, and guarded by a test rather than derived.\n *\n * I first wrote this as `BOT_GROUPS.flatMap(...).length` imported from @vibemancer/core, and\n * running `npm create vibemancer` proved that wrong immediately: tsup bundles the import, so\n * pulling anything from core's entrypoint drags the whole engine in — including the NATIVE\n * isolated-vm — and the scaffolder crashed on startup before printing a word. A scaffolder\n * that cannot start is worse than a stale number, so the number stays inline and\n * scaffolder.test.ts asserts it against the real roster instead.\n *\n * Hero is excluded on purpose: it is the showcase bot the roster tells players to beat, and\n * it is fought deliberately with `--opponent Hero` rather than swept up in the round-robin.\n */\nexport const RANKED_OPPONENTS = 29;\n\n/**\n * This package's own version, read from its manifest at load time.\n *\n * Read rather than hardcoded so a release bump cannot leave scaffolded projects pinned to\n * an older toolchain — the exact bug this replaced. Falls back to a permissive range if\n * the manifest cannot be found (e.g. an unusual install layout), which is better than\n * emitting a version that does not exist.\n */\nfunction readOwnVersion(): string\n{\n\ttry\n\t{\n\t\tconst here = path.dirname(fileURLToPath(import.meta.url));\n\t\tfor (const rel of ['../package.json', '../../package.json'])\n\t\t{\n\t\t\tconst candidate = path.resolve(here, rel);\n\t\t\tif (!fs.existsSync(candidate)) continue;\n\t\t\tconst parsed: unknown = JSON.parse(fs.readFileSync(candidate, 'utf8'));\n\t\t\tif (typeof parsed !== 'object' || parsed === null) continue;\n\t\t\tif (!('name' in parsed) || !('version' in parsed)) continue;\n\t\t\tconst {name, version} = parsed;\n\t\t\tif (name === 'create-vibemancer' && typeof version === 'string') return version;\n\t\t}\n\t}\n\tcatch\n\t{\n\t\t// fall through\n\t}\n\treturn '';\n}\n\nexport const SCAFFOLDER_VERSION = readOwnVersion();\n\nexport function toPascalCase(str: string): string\n{\n\tlet result = str\n\t\t.replace(/[-_]+/g, ' ')\n\t\t.replace(/\\b\\w/g, (c) => c.toUpperCase())\n\t\t.replace(/\\s+/g, '');\n\n\t// Ensure starts with a letter (prepend underscore if starts with digit)\n\tif (/^\\d/.test(result))\n\t{\n\t\tresult = '_' + result;\n\t}\n\n\treturn result;\n}\n\n/**\n * Validate that a string is a valid JavaScript identifier.\n */\nexport function isValidIdentifier(name: string): boolean\n{\n\treturn /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);\n}\n\n/**\n * Validate that a project name is safe for use as a directory name.\n */\nexport function isValidProjectName(name: string): boolean\n{\n\treturn /^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$/.test(name);\n}\n\n/**\n * The version range new projects pin their Vibemancer toolchain to.\n *\n * Derived from THIS package's own version rather than hardcoded: all five packages are\n * released in lockstep on a single version, so a scaffolder shipped at 0.2.1 must hand out\n * ~0.2.1. It was previously frozen at `~0.1.0` while the published packages had moved to\n * 0.2.1 — and `~0.1.0` means `>=0.1.0 <0.2.0`, so it could never reach them. Every new\n * player was scaffolded onto a stale core and CLI.\n */\nexport function toolchainRange(scaffolderVersion: string = SCAFFOLDER_VERSION): string\n{\n\tif (!scaffolderVersion) return 'latest';\n\treturn `~${scaffolderVersion}`;\n}\n\nexport function packageJson(projectName: string, scaffolderVersion: string = SCAFFOLDER_VERSION): string\n{\n\tconst toolchain = toolchainRange(scaffolderVersion);\n\treturn JSON.stringify({\n\t\tname: projectName,\n\t\tversion: '0.1.0',\n\t\tprivate: true,\n\t\ttype: 'module',\n\t\tscripts: {\n\t\t\tdev: 'vibemancer dev',\n\t\t\ttest: 'vibemancer test',\n\t\t\ttypecheck: 'tsc --noEmit',\n\t\t\tfight: 'vibemancer fight',\n\t\t\ttrace: 'vibemancer trace --opponent TargetDummy',\n\t\t\toptimize: 'vibemancer optimize',\n\t\t\tupload: 'vibemancer upload',\n\t\t\tpull: 'vibemancer pull',\n\t\t\tfeedback: 'vibemancer feedback',\n\t\t\tbuild: 'vibemancer build --opponent Battlemage',\n\t\t},\n\t\tdependencies: {\n\t\t\t'@vibemancer/core': toolchain,\n\t\t},\n\t\tdevDependencies: {\n\t\t\t'vibemancer': toolchain,\n\t\t\t'typescript': '^5.9.0',\n\t\t\t'vitest': '^3.0.0',\n\t\t},\n\t}, null, '\\t') + '\\n';\n}\n\nexport function tsconfigJson(): string\n{\n\treturn JSON.stringify({\n\t\tcompilerOptions: {\n\t\t\ttarget: 'ESNext',\n\t\t\tmodule: 'ESNext',\n\t\t\tlib: ['ESNext'],\n\t\t\tskipLibCheck: true,\n\t\t\tmoduleResolution: 'Bundler',\n\t\t\tstrict: true,\n\t\t\tnoUnusedLocals: true,\n\t\t\tnoUnusedParameters: true,\n\t\t\tisolatedModules: true,\n\t\t\tnoEmit: true,\n\t\t},\n\t\tinclude: ['src', 'tests'],\n\t}, null, '\\t') + '\\n';\n}\n\nexport function vibemancerJson(botName: string): string\n{\n\treturn JSON.stringify({\n\t\tbot: 'src/bot.ts',\n\t\texport: botName,\n\t}, null, '\\t') + '\\n';\n}\n\nexport function botTemplate(botName: string): string\n{\n\treturn `import {\n\tusePosition, useEnemy, useTicksUntilReady, useThreats,\n\tmissile, move,\n\tgetMissileContext, turnToward, flyStraight,\n\t// More actions (all importable from '@vibemancer/core'):\n\t//   blink, cancel, idle, turnToAngle,\n\t// More hooks:\n\t//   useHealth, useBlinkCooldown, useStatus, useVelocity,\n\t//   useCastProgress, useMyProjectiles, useMyThreatsToEnemy,\n\t//   useClosestThreat, useShieldStrength, useCastingSpell,\n\t//   useTick, useArenaSize, useDamageDealt, useDamageTaken,\n\t//   useRandom,\n\t// Utility functions:\n\t//   distanceTo, angleTo, directionTo, directionAway,\n\t//   getLeadPosition, fitMissileToBudget, getMissileCastTime,\n\t//   predictPosition, interceptAngle, clampPositionToArena,\n\t// Persistence hooks (React-style, state preserved across ticks):\n\t//   useState, useRef, useMemo, useEffect\n\t// Parameter tuning (for optimizer):\n\t//   useParam\n} from '@vibemancer/core';\n\n/**\n * ${botName} - Your custom wizard bot!\n *\n * === HOW IT WORKS ===\n * Your function is called EVERY TICK (100x per second). Each call you:\n *   1. Read game state using hooks (usePosition, useEnemy, etc.)\n *   2. Return ONE action (missile, shield, blink, move, cancel, or idle)\n *\n * The function must ALWAYS return an action. During cooldowns (GCD), return\n * move() to keep moving — casting spells during GCD is silently ignored.\n * Check useTicksUntilReady() > 0 to know when you're on cooldown.\n *\n * === GAME RULES ===\n *   Arena:     860x860 total. The PLAYFIELD is [30, 830] — the outer 30 units are LAVA.\n *   LAVA:      Standing in it KILLS YOU. Positions are NOT clamped to the playfield: you\n *              can walk into lava, and knockback can push you in. Many losses are this.\n *   SAFE BOX:  lava is tested against your EDGE, not your centre. usePosition() gives the\n *              centre and your radius is 5, so you die once your centre passes 825 (or\n *              drops below 35). Steer by [35, 825]. Aiming at 828 because the playfield\n *              \"ends at 830\" is fatal.\n *   Health:    60 HP, wizard dies at 0\n *   Timing:    100 ticks = 1 second, match lasts 30,000 ticks (5 min)\n *   Movement:  1.5 units/tick (150 u/s), 33% speed while casting, 0% while shielding\n *   Knockback: missiles above 10 damage shove the target. Yours push them; theirs push you\n *              — possibly into the lava.\n *   GCD:       100 ticks (1s) lockout after any spell completes or is canceled\n *   Thinking:  45 SECONDS of total thinking time per fight (all ten matches share it).\n *              Spend it all and your bot stops being asked for the rest of the fight — it\n *              just stands there. That is NOT a crash: a slow bot loses fights, it does\n *              not get removed from the ladder. There is no per-tick limit, so one slow\n *              tick costs you nothing but the time itself. You will not come close to\n *              this by accident — the worst built-in bot uses about 5.6s of its 45.\n *\n * === SPELLS ===\n *   missile(config, ai, direction)\n *     config: { damage, speed, duration, turnRate }\n *       - damage:   HP removed on hit (1-60). Hitbox radius = (2 + 0.1 x damage) x 3.\n *       - speed:    units/tick (min 1.5, and a wizard moves at 1.5 too — so a minimum-speed\n *                   missile does NOT outrun a fleeing target). Range = speed x duration.\n *       - duration: ticks the missile lives (min 10). Longer = more range but slower cast.\n *       - turnRate: degrees/tick of homing (0 = straight, 3 = moderate, 5+ = strong).\n *     ai: hooks-style function called every tick to steer. Use getMissileContext() to read state, return turnToward(x,y), turnToAngle(deg), or flyStraight().\n *     direction: launch angle in degrees (0=right, 90=down, 180=left, 270=up).\n *     Cast time scales with all stats. Repeated similar missiles cast 20% faster (warmup).\n *     Chain .move(dx, dy) to walk at 33% speed while casting.\n *\n *   shield()\n *     Channeled. Blocks 90% initially, decays 20%/sec, minimum 30%.\n *     0.2s cast time. Immobile while channeling. Cancel with cancel().\n *\n *   blink(x, y)      — Teleport to ABSOLUTE position (not direction). Max 300 units.\n *   move(dx, dy)      — Move in DIRECTION (not position). Speed clamped to [-1, 1].\n *   cancel()          — Cancel current cast/channel. Chain .move() to dodge simultaneously.\n *   idle()            — Do nothing this tick.\n *\n * === KEY TYPES ===\n *   useEnemy() returns:  { position: {x, y}, velocity: {x, y}, health, state, ... }\n *   useThreats() returns array of AnalyzedThreat:\n *     { id, projectile, ticksToImpact, willHit }\n *     - projectile carries the incoming missile's own position/velocity/damage.\n *     - willHit is the one to branch on: a threat that misses needs no reaction.\n *   fitMissileToBudget(budgetTicks, distance, options?) — best missile config for a\n *     cast-time budget. The distance argument is REQUIRED (units to the target).\n *   getLeadPosition(targetPos, targetVel, missileSpeed, myPos) — where to aim at a moving\n *     target. All four are REQUIRED. The third is the MISSILE'S SPEED, not a time.\n *\n *   Both of these previously appeared here with fewer parameters. Calling them that way\n *   does not throw an error you can see — your wizard simply freezes at spawn for the whole\n *   fight and the result still says success. If your bot does nothing, check your arguments\n *   here first.\n *\n * All imports have full JSDoc — hover or jump-to-definition to see docs.\n */\nexport function ${botName}()\n{\n\tconst myPos = usePosition();\n\tconst enemy = useEnemy();\n\tconst ready = useTicksUntilReady();\n\tconst threats = useThreats();\n\n\t// Direction toward enemy (used for movement and aiming)\n\tconst dx = enemy.position.x - myPos.x;\n\tconst dy = enemy.position.y - myPos.y;\n\tconst dist = Math.sqrt(dx * dx + dy * dy);\n\tconst angle = Math.atan2(dy, dx) * (180 / Math.PI);\n\n\t// DEFENCE FIRST, and the order matters more than it looks. useTicksUntilReady() is\n\t// nonzero for the whole cast AND the GCD after it — about 99% of a match — so anything\n\t// placed after the \\`ready > 0\\` return below can essentially never run. This template\n\t// used to check for threats down there and raised 0 shields in an entire match.\n\t//\n\t// Dodging is also what the numbers favour: measured against every ranked built-in,\n\t// dodge-only wins 7 matchups, dodge-then-shield 4, shield-first 2. A shield decays while\n\t// you hold it and you cannot attack through it, so reach for a sidestep first.\n\tconst closestThreat = threats[0];\n\tif (closestThreat && closestThreat.willHit && closestThreat.bestDodgeDirection)\n\t{\n\t\treturn move(closestThreat.bestDodgeDirection.x, closestThreat.bestDodgeDirection.y);\n\t}\n\n\t// While on cooldown, move toward the enemy\n\t// move() takes a direction vector, not an absolute position\n\tif (ready > 0) return move(dx, dy);\n\n\t// Fire a homing missile at the enemy\n\t// Duration scales with distance so missiles always have enough range\n\t// Chain .move() to walk toward enemy at 33% speed while casting\n\treturn missile(\n\t\t{damage: 25, speed: 6, duration: Math.max(60, Math.ceil(dist / 6) + 20), turnRate: 3},\n\t\t() =>\n\t\t{\n\t\t\t// Missile AI: hooks-style function called every tick to steer the missile\n\t\t\t// Use getMissileContext() to read state, return turnToward/flyStraight\n\t\t\tconst ctx = getMissileContext();\n\t\t\tconst target = ctx.worldState.enemies[0];\n\t\t\tif (!target) return flyStraight();\n\t\t\treturn turnToward(target.position.x, target.position.y);\n\t\t},\n\t\tangle,  // Launch angle in degrees toward enemy\n\t).move(dx, dy);\n}\n`;\n}\n\nexport function readmeMd(botName: string): string\n{\n\treturn `# ${botName} — Vibemancer Bot\n\nThis is a Vibemancer wizard bot project. The bot fights 1v1 against other wizard bots in an 860x860 arena whose outer 30 units are instant-death lava (playfield [30, 830]).\n\n## Quick Start\n\n\\`\\`\\`bash\nnpm test               # Verify everything works\nnpm run dev            # Start dev server + open browser (refresh to see changes)\nnpm run fight          # Round-robin against all ${RANKED_OPPONENTS} ranked built-ins\nnpm run trace          # Per-tick debug trace against TargetDummy\nnpm run typecheck      # Check for type errors (catches bugs esbuild misses)\nnpm run optimize       # Auto-tune useParam() values via optimizer\nnpm run upload         # Upload to vibemancer.com for rated competition\nnpm run pull           # Download latest source from server (after MCP edits)\n\\`\\`\\`\n\nTo trace/fight a specific opponent:\n\\`\\`\\`bash\nnpx vibemancer trace --opponent Battlemage\nnpx vibemancer fight --opponent Nightblade\nnpx vibemancer bots                          # list all bots with descriptions\nnpx vibemancer bots Battlemage               # details about a specific bot\n\\`\\`\\`\n\n## Project Structure\n\n- \\`src/bot.ts\\` — Bot source code (edit this!)\n- \\`tests/bot.test.ts\\` — Automated tests for your bot\n- \\`vibemancer.json\\` — Config: \\`{ \"bot\": \"src/bot.ts\", \"export\": \"${botName}\" }\\`\n\n## Development Workflow\n\n1. Edit \\`src/bot.ts\\`\n2. Run \\`npm run typecheck\\` to catch type errors early\n3. Run \\`npm test\\` to check your bot doesn't crash and beats weak bots\n4. Run \\`npm run fight\\` to rank yourself against all ${RANKED_OPPONENTS} ranked built-ins.\n   Then try the showcase bot the ladder is built around: \\`npx vibemancer fight --opponent Hero\\`\n5. Run \\`npm run trace\\` to see per-tick events when something isn't working\n6. Run \\`npm run optimize\\` to auto-tune useParam() values\n\nFor the browser viewer: run \\`npm run dev\\`, then refresh the browser after editing your bot.\n\n## Difficulty Progression\n\nStart by beating the weakest bots and work your way up:\n\n| Milestone | Bots to Beat | What You Need |\n|-----------|-------------|---------------|\n| Beginner  | TargetDummy, Critter | Basic missile firing |\n| Easy      | Rookie, Hogger, Bonemancer | Homing missiles + movement |\n| Medium    | Turtle, Sentinel, Flamecaller | Shielding + dodge awareness |\n| Hard      | Battlemage (#11), Stormchaser | Cast timing + positioning |\n| Expert    | Archmage, Stormforger | Adaptive missiles + vulnerability punish |\n| Master    | Nightblade (#29) | Everything at once |\n\n## Debugging\n\nWhen your bot isn't working:\n1. \\`npm test\\` — check for runtime errors (captured in test results)\n2. \\`vibemancer trace --opponent TargetDummy\\` — watch exactly what happens tick by tick\n3. Look at the trace stats: hit rate, shield usage, idle time\n4. Look for ERROR and WARNING events in the trace output\n\n## Common Pitfalls\n\n- \\`move(dx, dy)\\` is a **direction vector**, NOT a target position\n- \\`blink(x, y)\\` is an **absolute position**, NOT a direction\n- Calling \\`missile()\\` during GCD is **silently ignored** — check \\`useTicksUntilReady()\\` first\n- Missile range = speed x duration. If range < distance, missiles expire before reaching the enemy\n- All angles are in **degrees** (not radians). Use: \\`Math.atan2(dy, dx) * (180 / Math.PI)\\`\n- All time values are in **ticks** (100 ticks = 1 second)\n- Your bot runs every tick — always return an action, even during cooldowns (\\`move()\\`)\n- \\`fitMissileToBudget()\\` and \\`getLeadPosition()\\` return **null** when no solution exists\n\n## Built-in Bots (29 total, ranked weakest -> strongest)\n\nTargetDummy, Critter, Bonemancer, Hogger, Rookie, Turtle, Sentinel, Flamecaller,\nGolem, Stormchaser, Battlemage, Spellspinner, Doombringer, Lich, Stormcaller,\nSpellbinder, Shadowblade, Pyromancer, Warmage, Spelltracer, Archmage, Spellseeker,\nStormforger, Spellweaver, Spellshot, Voidblade, Infernalist, Archlich, Nightblade\n\nRun \\`vibemancer bots\\` to see descriptions, or \\`vibemancer bots Battlemage\\` for details.\n\n## Strategy Tips\n\n- Shield is strongest at the start (90% block) — cancel early to minimize GCD waste\n- Repeated similar missiles cast 20% faster (warmup). Switching styles costs 20%\n- Higher damage = longer cast time, but DPS always increases with damage\n- Homing missiles (turnRate > 0) are harder to dodge but cost more cast time\n- Straight missiles (turnRate: 0) are fast to cast. Use \\`getLeadPosition()\\` to aim\n- Use \\`useThreats()\\` to decide: dodge (best), shield (good), or eat the hit (risky)\n`;\n}\n\nexport function botTestTemplate(botName: string): string\n{\n\treturn `import {expect, test} from 'vitest';\nimport {testBot} from '@vibemancer/core';\nimport {${botName}} from '../src/bot';\n\n// Run with: npm test\n// These all pass on the starter bot. Keep them green as you change it, and add\n// your own — they are the fastest way to know you have not broken anything.\n\ntest('no runtime errors', () =>\n{\n\tconst result = testBot(${botName}).simulate('TargetDummy');\n\texpect(result.errors).toHaveLength(0);\n});\n\ntest('beats TargetDummy', () =>\n{\n\tconst result = testBot(${botName}).fight('TargetDummy');\n\texpect(result.won).toBe(true);\n});\n\ntest('beats Critter', () =>\n{\n\tconst result = testBot(${botName}).fight('Critter');\n\texpect(result.won).toBe(true);\n});\n\ntest('kills TargetDummy within 15 seconds', () =>\n{\n\tconst result = testBot(${botName}).simulate('TargetDummy', {maxTicks: 1500});\n\texpect(result.won).toBe(true);\n});\n\ntest('lands at least 40% of missiles', () =>\n{\n\tconst result = testBot(${botName}).simulate('Rookie', {maxTicks: 3000});\n\tif (result.stats.missilesLaunched > 0)\n\t{\n\t\texpect(result.stats.hitRate).toBeGreaterThan(0.4);\n\t}\n});\n`;\n}\n\nexport function agentsMd(botName: string): string\n{\n\treturn `# AGENTS.md — context for AI assistants\n\nThis is a [Vibemancer](https://vibemancer.com) wizard-bot project. The goal\nis to write a TypeScript bot that wins 1v1 fights against other wizards in\nan 860x860 arena whose outer 30 units are instant-death lava (playfield [30, 830]).\n\n## Layout\n\n- \\`src/bot.ts\\` — the bot. Edit this. Export must be a single PascalCase\n  function (currently \\`${botName}\\`).\n- \\`tests/bot.test.ts\\` — vitest suite. Add cases as you discover edge\n  cases the bot should handle.\n- \\`vibemancer.json\\` — \\`{ \"bot\": \"src/bot.ts\", \"export\": \"${botName}\" }\\`.\n  Don't move the bot without updating this.\n- \\`README.md\\` — a more thorough developer guide. Skim it once.\n\n## How to verify a change\n\n\\`\\`\\`bash\nnpm test                          # vitest — fast, runs every change\nnpm run typecheck                 # catches typos esbuild would silently bundle\nnpm run fight                     # round-robin against all ${RANKED_OPPONENTS} ranked built-ins\nnpx vibemancer fight --opponent Hero   # the showcase bot — beat this one\nnpx vibemancer trace --opponent <Bot>   # per-tick debug trace\n\\`\\`\\`\n\nTreat \\`npm test\\` as the smallest verifying step. Run it before claiming a\nchange is done.\n\n## The bot API\n\nImported from \\`@vibemancer/core\\`. The bot is called every tick (100 ticks\nper second). It returns an action object — typically built by helpers:\n\n- **Movement:** \\`move(dx, dy)\\` — direction vector (NOT a target). Always\n  return *something* even on cooldown — bare \\`move(0, 0)\\` if you have\n  nothing else to do.\n- **Spells (only one per cast):**\n  - \\`missile({damage, speed, duration, turnRate}, ai, angle)\\` — fire a\n    projectile. Range = speed × duration. Higher damage = longer cast time.\n    The \\`ai\\` is a hooks-style function \\`() => MissileAction\\` — use\n    \\`getMissileContext()\\` to read state, return \\`turnToward(x, y)\\`,\n    \\`turnToAngle(degrees)\\`, or \\`flyStraight()\\`.\n  - \\`shield()\\` — channel a shield. Strongest at start (90% block),\n    decays. Cancel early to free up GCD.\n  - \\`blink(x, y)\\` — teleport to **absolute position** (NOT a direction).\n    Range cap is 300; further targets are clamped along the line.\n- **Hooks** (read state):\n  - \\`usePosition()\\` — your current \\`{x, y}\\`.\n  - \\`useEnemy()\\` — opponent's last-known state.\n  - \\`useThreats()\\` — incoming missiles you might want to dodge/shield.\n  - \\`useTicksUntilReady()\\` — GCD remaining. Cast attempts during GCD are\n    silently ignored — gate on this.\n  - \\`useRandom()\\` — seeded PRNG (\\`() => number\\`). Deterministic. Use\n    instead of \\`Math.random()\\` (blocked in sandbox).\n  - \\`useParam(name, default, {min, max, step})\\` — declare a tunable; the\n    optimizer's coordinate-descent will sweep it.\n\nRead the full surface: \\`packages/core/src/index-browser.ts\\` if you have\nthe monorepo, or jump-to-definition from any \\`@vibemancer/core\\` import.\n\n## Common pitfalls\n\n- All angles are in **degrees**, not radians. Use \\`Math.atan2(dy, dx) * (180 / Math.PI)\\`.\n- All time values are in **ticks**, not seconds. 100 ticks = 1 second.\n- \\`getLeadPosition()\\` and \\`fitMissileToBudget()\\` return **null** when no\n  solution exists — handle that, don't assume non-null.\n- Returning nothing freezes the bot for that tick. Always return at least\n  \\`move(0, 0)\\`.\n- The bot runs in a sandboxed Web Worker / isolated-vm — no \\`fetch\\`,\n  no DOM, no \\`Math.random()\\` (use \\`useRandom()\\` for a seeded,\n  deterministic PRNG).\n\n## Don't\n\n- Don't add new top-level files outside \\`src/\\` and \\`tests/\\` without a\n  reason — the dev server scans \\`src/\\` for bots.\n- Don't add npm dependencies that pull in Node-only modules. Bots are\n  bundled for browser/sandbox execution.\n- Don't mutate globals or the prototype chain — the sandbox freezes them\n  and crashes will be silent.\n\n## Publishing\n\nOnce \\`npm run fight\\` shows acceptable wins:\n\n\\`\\`\\`bash\nnpx vibemancer upload\n\\`\\`\\`\n\nThis signs in (Google), compiles, and ships the bundle to vibemancer.com.\nThe matchmaker auto-pairs your wizard against other active uploads. Watch\nthe leaderboard / your wizard's match history for results, find a\nweakness, edit, re-upload.\n`;\n}\n\nexport function gitignore(): string\n{\n\treturn `node_modules/\ndist/\n.vibemancer/\n*.tgz\n`;\n}\n\n/**\n * Scaffold a new project directory with all template files.\n */\n/**\n * Write the project and RETURN the files written.\n *\n * The caller used to print a hardcoded list of seven while this wrote eight — AGENTS.md,\n * the file the website advertises as the AI-onboarding hook, was created silently and left\n * out of the scaffolder's own output. Returning the list makes that drift impossible.\n */\nexport function scaffoldProject(projectDir: string, projectName: string, botName: string): string[]\n{\n\tconst files: [string, string][] = [\n\t\t['package.json', packageJson(projectName)],\n\t\t['tsconfig.json', tsconfigJson()],\n\t\t['vibemancer.json', vibemancerJson(botName)],\n\t\t['src/bot.ts', botTemplate(botName)],\n\t\t['tests/bot.test.ts', botTestTemplate(botName)],\n\t\t['README.md', readmeMd(botName)],\n\t\t['AGENTS.md', agentsMd(botName)],\n\t\t['.gitignore', gitignore()],\n\t];\n\n\tfs.mkdirSync(path.join(projectDir, 'src'), {recursive: true});\n\tfs.mkdirSync(path.join(projectDir, 'tests'), {recursive: true});\n\n\tfor (const [filePath, content] of files)\n\t{\n\t\tconst fullPath = path.join(projectDir, filePath);\n\t\tfs.writeFileSync(fullPath, content);\n\t}\n\n\treturn files.map(([filePath]) => filePath);\n}\n"],"mappings":"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","names":["fs","path","path","fs"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-vibemancer",
-	"version": "1.0.12",
+	"version": "1.0.14",
 	"description": "Create a new Vibemancer wizard bot project",
 	"type": "module",
 	"author": "Low Entry",