paprika3d (the three.js toolset for coding agents)

paprika3D：让你的编码 Agent 成为更出色的 three.js 开发者的工具集

paprika3D 是一个 Claude Code 插件和 MCP 服务，可让编码 Agent 在宣布完成之前，打开、查看、操作、测量并修复它编写的 three.js、React Three Fiber 和 WebGL 页面：它能将场景作为数据来观察，按精确时钟运行页面，检查任意网格或数值，使用真实几何体构建形状，并提升帧率。

安装

需要 Google Chrome 和 Node 20.11 或更高版本。

claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d

Chrome 会在 macOS 的默认路径中查找；在其他系统上，将 PAPRIKA3D_CHROME 设置为 Chrome 可执行文件的路径。其他 Agent 请参阅其他 Agent。

文档：https://paprika3d.com/docs。window.__game 约定：https://paprika3d.com/docs/convention。供大模型使用：https://paprika3d.com/docs/llms.txt。

它适用于任何 three.js、React Three Fiber 或 WebGL 页面：游戏、产品查看器或配置器、模拟程序、着色器或后期处理演示。无需更改页面，即可打开、查看、操控和检查。

Agent 能获得什么

three.js 页面只有一个 <canvas>：从外部看，它只是一张图片。paprika3D 深入其中，直接与 3D 场景本身交互。

Agent 提出的问题	paprika3D 给出的答案
屏幕上有什么？	每个命名对象、它在图像中的占比及其边界框；还会列出每个从未出现的对象、它的大小，以及它位于摄像机后方、视野外还是小到无法绘制
我的模型加载了吗？	页面打开时报告已获取的模型、纹理和音频文件，以及所有加载失败的资源
按下空格键会发生什么？	输入会在暂停的固定时钟上，按精确帧写入（每帧 1/60 秒），因此相同输入每次运行都会产生相同帧和状态
游戏当前是什么状态？	每次输入前后的 JSON 状态
这个网格有多大？它是封闭的吗？	无需修改页面即可获取：每个网格的三角形、边界、封闭或开放边、体积和亏格，以及针对 scene、camera 和 renderer 运行的任何 JavaScript
速度够快吗？	根据桌面端、移动端或 Quest 的预算，报告帧耗时、绘制调用、三角形和资源大小
怎样才能让它更快？	game_optimize 会尝试分辨率缩放、实例化、LOD 和资源释放，只保留有效且不会改变画面的优化
命中反馈够明显吗？	事件发生后检查摄像机震动、缩放弹跳、缓动移动而非瞬移、闪光、生成的对象和音效
它能构建我需要的形状吗？	项目中的 geo.js：布尔运算、凸包、拉伸、旋转体和带随机种子的散布，并内置 Manifold

它绝不会截取你的屏幕：所有图像都来自它自己的无头页面。

它能发现什么

下面是 game_look 对一个 Agent 根据要求“将汽车缩放至 0.8”编写的迷你高尔夫页面所做的检查：

On screen (14):
Mesh 17.4% [399, 240, 880, 771]
…
Never visible: ToyCar (0.0338 units, in view), Glass (0.0168 units, in view)

汽车确实存在、位于视野内，但在一条 8 米长的球道上只有 3 厘米长。在下面的运行中，两个 Agent 都打开了类似的页面、查看了截图，却仍然没有发现汽车；这一行能指出它。

在全新安装中使用 Sonnet 5.5 测得，测试采用了详细、精确的 three.js 规格，每项规格都附带一个 glTF 模型：

	仅使用 Agent	使用 paprika3D
导入的模型比例错误或未加载	11 次运行中有 10 次	11 次运行中有 2 次
从未加载的 Draco 压缩模型（“No DRACOLoader instance provided”）	3 次运行中有 3 次	3 次运行中有 0 次

安装工具但不提供提醒时，Agent 在 6 次运行中有 0 次打开页面；使用插件现在每个会话提供一次的提醒后，11 次运行中有 10 次打开了页面。在这些任务的所有测试组中，游戏逻辑都正确，因此提升体现在只有通过查看才能发现的问题上：导入资源、缩放、构图和加载失败。每次运行的费用约为原来的 1.5 到 2 倍，实际耗时约为原来的 2 到 7 倍。这些样本数量较少（每项任务运行 3 到 5 次，使用一个模型）。

面向 Agent：循环流程

若要在提示词中提出此要求，请说 使用 paprika3d 进行试玩。

编写或修改任何 three.js、React Three Fiber 或 WebGL 页面后，在宣布完成之前使用这些工具。

1. 打开页面： 使用 game_open，并设置 url: "index.html"（该文件夹会被提供服务）或 command: "bunx vite"。读取 Loaded: 和 Failed to load: 行。
2. 查看页面： 使用 game_look。读取 Never visible:。在宽 8 个单位的场景中，一个大小为 0.07 个单位的物体比例不对；behind the camera 或 outside the view 表示取景有问题。打开它保存的图片。
3. 操作页面： 对请求中提到的每项交互，调用 game_act 并读取它返回的状态。使用 game_clock 推进时间。
4. 询问场景： game_eval 可回答有关尺寸、材质和位置的问题，并可在你将更改写入源代码前，尝试在页面中应用更改。
5. 修复后重新查看。 性能很重要时，调用 game_perf。

对于规则精确的游戏（计分、碰撞、回合顺序、明确给出的数字），使用 game_contract 锁定 游戏契约，并在每次更改后调用 game_check。钩子也会在后台于每次编辑后进行检查。threejs-game 技能包含适用于纯 three.js、React Three Fiber 和 Rapier 的完整方法与模板。

工具

工具	功能
game_open	在暂停且时间种子固定的 Chrome 无头模式中打开页面（文件或文件夹、http URL 或开发服务器命令），并列出页面获取的模型、纹理和声音文件，以及所有获取失败的文件
game_look	提供页面截图、ID 图像（每个物体一种颜色）和屏幕上已命名物体的列表；还会列出尚未被查看到的已命名物体及其大小和位置（在摄像机后方、视野之外，或在视野内但未绘制任何像素）；使用 target 时，会在一张图片中从正面、右侧、顶部和四分之三角度单独展示一个已命名物体
game_act	逐帧发送按键、鼠标、触控或 __game.act 操作，并提供操作前后的状态
game_observe	页面状态（其 __game.observe() 或已命名的 three.js 物体）、渲染器计数、新出现的控制台错误，以及自上次 observe 以来发生的变化
game_eval	在作用域中包含 scene、camera、renderer、find(name) 和 stats(target) 的页面中运行 JavaScript，并返回运行结果；stats 会提供每个网格的顶点、三角形、边界、属性、材质、闭合或开放边、体积和亏格。回复上限为 2,048 个字符，完整文本会保存在运行文件夹中
game_clock	推进帧、暂停或恢复实时播放、设置时间比例
game_feel	发送触发事件的操作步骤，然后观察后续帧中的摄像机震动、缩放跳变、缓动移动与瞬移、颜色闪烁、生成的物体、HUD 文本变化和声音
game_perf	根据预算（桌面、移动设备、Quest 或契约预算）检查帧时间、绘制调用、三角形数量和资源大小
game_optimize	仅在检查结果显示帧预算超标，或用户询问性能时使用：进行测量，尝试运行时开关，保留有帮助且不会导致关键点检查失败或改变画面的开关，写入 game-runtime.json，最后进行最终检查
game_contract	将用户的提示词转换为 game-contract.json；由一个从未接触过游戏代码的新子 Agent 编写；其哈希保存在项目之外，因此会拒绝手动编辑的契约
game_check	在每个关键点都使用全新加载的页面运行契约；最后一行是关键点推进时的帧时间，并与预算进行对照

让游戏可检查

任何页面都可以打开、查看和操作。若要检查游戏规则，游戏还应在页面加载后公开 window.__game：

window.__game = {
  describe(),        // a short description: name, controls, units
  observe(),         // the state, exactly the keys of game-contract.json's schema, as plain JSON
  act(input),        // performs one input object: { key, down? } or { action, ...args }
  setState(partial), // sets any of the schema's keys at once; keys left out keep their values
};
// Starts playing on load: no title screen, no click to start.
// Time comes only from requestAnimationFrame / performance.now (faked, 1/60 s per frame, never more than 0.1 s a frame).
// Randomness comes only from Math.random (seeded). Keys listen on window and match event.key.

完整规则请见 skills/threejs-game/SKILL.md 和 https://paprika3d.com/docs/convention。

运行时导入

只有当检查提示帧耗时超出预算时，游戏才需要导入运行时。对于尚未包含运行时的游戏，game_optimize 会将构建好的运行时放入项目，命名为 three-runtime.js，并提示添加导入语句；只需在入口文件顶部、创建渲染器之前添加一次，然后重新打开游戏：

import { install } from "./three-runtime.js";
install();

在 game_optimize 写入 game-runtime.json 之前，它不会执行任何操作（如果项目有 public/ 目录，也会将文件写入其中，因为 vite 只会复制该目录）；之后，它会运行其中保存的开关：resolution、defaults、instancing、lod 和 dispose。

程序化几何体

game_open 会将 geo.js 放入项目：这是一个内置 Manifold 的文件，可用于布尔运算、凸包、拉伸和旋转生成几何体，还包含带种子的 scatter。使用 import { geo, scatter } from "./geo.js"; 导入（vite 项目中，从 src/ 目录导入时使用 "../geo.js"）。示例见 skills/threejs-game/references/geometry.md。

其他 Agent

MCP 服务需要 Node 20.11 或更高版本及 Google Chrome，无需安装。克隆此仓库，并将 MCP 客户端指向 src/cli.js serve：

git clone https://github.com/paprika3d/paprika3d.git

{
  "mcpServers": {
    "paprika3d": {
      "command": "node",
      "args": ["/path/to/paprika3d/src/cli.js", "serve"]
    }
  }
}

每个工具都将项目文件夹作为 cwd。编辑后钩子和 threejs-game 技能是 Claude Code 的功能；其他 Agent 可以阅读 AGENTS.md 和 skills/threejs-game/SKILL.md，了解相同的方法。

运行结果存放位置

• <project>/paprika3d/runs/<time>/：每次运行的图片和 run.json。<project>/paprika3d/state.json 保存迭代次数、最近 200 次运行记录，以及钩子连接运行中服务的方式。将 paprika3d/ 添加到项目的 .gitignore。
• ~/.paprika3d/issued.json（或 $PAPRIKA3D_HOME）：每个已签发合约的哈希值。
• Paprika 应用：安装后，每次检查、性能测试和优化运行都会作为操作行写入 ~/.paprika/spool/（或 $PAPRIKA_HOME），其中包含结果、墙钟时间、迭代次数以及触发运行的编辑内容。

许可证

Apache License 2.0（LICENSE）。每个构建包所包含的依赖包均保留各自的许可证，详见 THIRD_PARTY_NOTICES.md。 “paprika3D”和“paprika3d”是 Keeno Corp 的商标（NOTICE）；欢迎遵循许可证创建使用其他名称的分支。欢迎提交问题；代码贡献请参阅 CONTRIBUTING.md。