Vibe Eyes Client

Vibe Eyes 客户端

一个轻量级客户端库，可将浏览器游戏与 Vibe Eyes MCP 调试服务集成，实现实时调试、可视化和分析。

这样，AI 就能实时看到它正在开发的游戏！

功能

• 自动捕获并传输画布截图
• 收集控制台日志和错误，并记录时间戳
• 处理全局错误和未处理的 Promise 拒绝
• 在专用调试窗口中显示 SVG 可视化内容
• 提供完整的调试统计数据，包括 SVG 尺寸测量值
• 对游戏性能的影响极小
• 具备稳健的错误处理能力，可在连接中断后平稳恢复
• 支持多种构建格式（UMD、ESM、IIFE）

1.1.0 新增内容

• 断开连接时显示 SVG：即使未连接到服务，调试窗口也能正常工作
• 连接状态可视化：通过视觉反馈实时显示连接状态
• 智能窗口定位：可将调试窗口定位在游戏窗口的右侧、左侧、顶部或底部
• 自适应默认值：调试窗口的默认尺寸为游戏窗口尺寸的 75%
• 改进错误处理：更好地处理窗口关闭和重新连接场景

安装

npm install vibe-eyes-client

或者直接在 HTML 中引入：

<script src="https://unpkg.com/vibe-eyes-client/dist/vibe-eyes.min.js"></script>

用法

基本集成

// Initialize with default settings (auto-connects to http://localhost:8869)
// Available globally when using the script tag
// The client will automatically start capturing once connected
initializeVibeEyes();

// Or use the existing client instance directly
window.VibeEyesClient.initialize();

自定义配置

// Initialize with custom settings (when included via script tag)
initializeVibeEyes({
  serverUrl: 'http://your-debug-server:8869',
  captureDelay: 2000,   // Screenshot every 2 seconds
  maxLogs: 50,          // Store more logs
  canvasId: 'my-canvas' // Specific canvas to capture
});

// Or when using as a module
import { initializeVibeEyes } from 'vibe-eyes-client';

initializeVibeEyes({
  serverUrl: 'http://your-debug-server:8869',
  captureDelay: 2000,
  canvasId: 'game-canvas'
});

手动控制

// Get the client instance
const client = window.VibeEyesClient;

// Explicitly stop/restart capturing if needed
client.stopCaptureLoop();
client.startCaptureLoop();

显示 SVG 可视化内容

Vibe Eyes MCP 服务会返回 SVG 可视化内容，你可以在专用调试窗口中显示：

// Get the client from initialization
const client = initializeVibeEyes();

// Enable SVG display - opens a new debug window with SVG and stats
client.enableSvgDisplay();

// You can optionally provide a custom container
client.enableSvgDisplay({
  container: '#my-custom-container' // Optional existing container element
});

// Configure the debug window position and size (all options are optional)
const client = initializeVibeEyes({
  serverUrl: 'http://localhost:8869',
  debugWindow: {
    // All debugWindow properties are optional with sensible defaults
    width: 500,                // Optional: Width in pixels (default: 75% of game window width)
    height: 600,               // Optional: Height in pixels (default: 75% of game window height)
    position: 'right'          // Optional: Position relative to game window (default: 'right')
    // Possible positions: 'right', 'left', 'top', 'bottom', 'detached'
  }
});

// Toggle the display on/off
client.toggleSvgDisplay();

// Disable the display (closes the debug window)
client.disableSvgDisplay();

调试窗口会显示：

• 顶部的 SVG 可视化内容
• 底部的完整响应统计数据，包括 SVG 尺寸
• 服务收到新数据时实时更新

配置选项

所有配置选项均为可选项，并提供合理的默认值。

客户端初始化选项

选项	默认值	描述
serverUrl	'http://localhost:8869'	Vibe Eyes MCP 服务的 URL
captureDelay	1000	截图间隔（毫秒）
maxLogs	10	最多保存的控制台日志数
maxErrors	10	最多保存的错误日志数
autoConnect	true	初始化时连接
canvasId	null	要捕获的特定画布 ID（null = 自动检测）
debugWindow	Object	调试窗口的配置（见下文）

SVG 显示选项

选项	默认值	描述
container	null	SVG 容器的元素或选择器（为 null 时会创建弹出窗口）

调试窗口选项

选项	默认值	描述
width	null	调试窗口的宽度，单位为像素（null = 游戏窗口宽度的 75%）
height	null	调试窗口的高度，单位为像素（null = 游戏窗口高度的 75%）
position	'right'	相对于游戏窗口的位置：'right'、'left'、'top'、'bottom' 或 'detached'

构建格式

以下构建格式位于 dist/ 目录中：

• vibe-eyes.min.js - 适用于大多数场景的压缩版 UMD 构建
• vibe-eyes.js - 用于调试的未压缩版 UMD 构建
• vibe-eyes.iife.js - 带全局变量的 IIFE 构建，可直接用于浏览器
• vibe-eyes.esm.js - 适用于现代打包工具和环境的 ES Module

相关项目

• Vibe Eyes MCP 服务 - 用于处理调试数据并生成可视化内容的配套服务

许可证

ISC