Skip to main content
Glama
deenesjakoruzh
elemarin

Renderoni

by elemarin
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

🍝 Renderoni

3D 网页游戏，端上桌时恰至熟度（Al dente）。 一个开箱即用、面向智能体的 3D 引擎，基于 Three.js 和 Rapier。 确定性 WebAssembly 物理引擎、声明式预设、以及用于 AI 结对编程的内置模型上下文协议 (MCP)。

CI Deploy Pages License: MIT TypeScript MCP

⚡ 问题与解决方案

使用 Three.js 和 Rapier WebAssembly 构建 3D 游戏通常需要编写数千行样板代码：固定时间步长循环、变换插值、角色控制器、空间音频、粒子系统和 UI 投影。

与此同时，AI 编码智能体（Claude、Gemini、Cursor）在处理 3D 引擎时遇到困难，因为游戏循环是非确定性的黑盒，需要昂贵的视觉截图。

Renderoni 为您提供两者：

  • 面向人类： 一个声明式、开箱即用的 3D 引擎。单次 createRenderoni() 调用即可启动物理引擎、渲染、摄像机控制、空间音频、动画状态机和粒子系统，并带有类型化预设。

  • 面向 AI 智能体与无头 CI： 一个确定性模拟内核，带有内置的模型上下文协议 (MCP) 服务器。智能体通过轻量级语义 Markdown（<500 字节 / ~120 个 token）检查场景，分派类型化动作，并在 Node.js 中无头验证游戏状态，耗时不到 10 毫秒。

Related MCP server: maige-3d-mcp

🎮 在线演示

在浏览器中在线体验交互式游乐场：elemarin.github.io/renderoni（或本地运行 npm run dev）。

演示

功能说明

操作方式

🪙 快速入门演示

README 快速入门的实时交互式浏览器实现：英雄角色、旋转金币传感器、音频提示音和粒子爆发特效。

WASD / 方向键（移动英雄）、Space（跳跃）、🪙 重生金币 按钮

✈️ 飞行模拟器

具有升力、阻力、跑道起降、可收放起落架和环形赛道的空气动力学飞行物理引擎。

W/S（俯仰）、A/D（偏航）、Q/E（滚转）、Shift/Ctrl（油门）、Z/X（最大/切断）、G（起落架）、C（座舱/追尾视角）、R（重置）

🧱 广阔体素沙盒

多生物群系程序化世界（约 2,000+ 方块），包含海洋水体、沙滩、连绵丘陵、雪峰和树木。

WASD（行走与自动跨越）、Shift（冲刺）、Space（跳跃）、1-6（快捷栏）、左键/右键（破坏/放置）

🔦 PSX 风格第三人称恐怖

复古 PSX 生存恐怖风格，第三人称追尾摄像机、哥特式庄园走廊、手电筒、钥匙谜题和动画铁门。

WASD（移动侦探）、鼠标（环绕摄像机）、E（拾取钥匙并解锁大门）

📦 安装

npm install renderoni three @dimforge/rapier3d-compat

可摇树优化的子路径导出：

import { createRenderoni } from 'renderoni';
import { body, kccPlayer, sensor, light } from 'renderoni/presets';
import { audio } from 'renderoni/audio';
import { animation } from 'renderoni/animation';
import { vfx } from 'renderoni/vfx';
import { ui } from 'renderoni/ui';
import { createMCPServer } from 'renderoni/mcp';
import 'renderoni/testing/matchers';

🚀 快速入门

import { createRenderoni } from 'renderoni';
import { body, kccPlayer, sensor, light } from 'renderoni/presets';
import { audio } from 'renderoni/audio';
import { vfx } from 'renderoni/vfx';

// 1. Initialize engine (runs headlessly in CI or interactively in browser)
const game = await createRenderoni({
  mode: 'interactive', // or 'headless'
  seed: 42,
  subsystems: [
    audio({ volume: 0.8 }),
    vfx({ particles: true }),
  ],
});

// 2. Add Environment & Lighting
game.add(light({ type: 'directional', position: [20, 40, 20] }));
game.add(body({ shape: 'box', type: 'fixed', size: [100, 1, 100], position: [0, 0, 0] }));

// 3. Add Collectible Item
const coin = game.add(sensor({
  id: 'golden_coin',
  shape: 'sphere',
  radius: 0.6,
  position: [4, 1.2, 0],
}));

// 4. Add Player Character
const player = game.add(kccPlayer({
  id: 'hero',
  position: [0, 1.5, 0],
  moveSpeed: 6.5,
}));

// 5. Handle Gameplay Events
game.events.on('sensor.enter', ({ sensor, target }) => {
  if (sensor.id === 'golden_coin' && target.id === 'hero') {
    game.audio.play('coin_pickup');
    game.vfx.spawnParticles({ count: 16, position: [4, 1.2, 0] });
    coin.destroy();
  }
});

// 6. Run headlessly (CI/Tests) or start interactive render loop (Browser)
game.step(60);   // Step 60 fixed ticks in ~1ms (Headless CI)
// game.start(); // Start 60fps presentation loop (Browser)

🤖 AI 智能体集成 (MCP 服务器)

将 Claude Desktop、Antigravity、Cursor 或任何 MCP 客户端直接连接到您的模拟：

{
  "mcpServers": {
    "renderoni": {
      "command": "npx",
      "args": ["renderoni", "mcp"]
    }
  }
}

内置 MCP 工具：

  • describe：返回活动实体、碰撞体、标签和引擎模式。

  • observe：返回超密集的第 0 层 Markdown 摘要（<500B / ~120 个 token），包含位置、速度和游戏状态。

  • act：注入确定性语义游戏动作（game.act({ name, payload })）。

  • step：将模拟推进 $N$ 个固定时间步长并返回状态哈希。

  • check：评估机器 AST 断言。

🧪 使用 Vitest 进行无头测试

在 Node.js 中无头运行完整的游戏集成测试，耗时不到 10 毫秒，并带有自定义 Vitest 匹配器：

import { expect, test } from 'vitest';
import { createRenderoni } from 'renderoni';
import { kccPlayer, sensor } from 'renderoni/presets';
import 'renderoni/testing/matchers';

test('player collects coin and verifies state hash', async () => {
  const game = await createRenderoni({ mode: 'headless', seed: 42 });
  const hero = game.add(kccPlayer({ id: 'hero', position: [0, 1, 0] }));
  const coin = game.add(sensor({ id: 'coin', position: [3, 1, 0] }));

  hero.actions.move({ x: 1, z: 0 });
  game.step(60);

  expect(game).toHaveTick(60);
  expect(hero.position[0]).toBeGreaterThan(1.5);
  expect(game).toHavePassedDiagnostics();
});

🏛️ 架构

┌────────────────────────────────────────────────────────────────────────┐
│                              L3 APPLICATION                            │
│           Game Rules, Custom Assets, Levels, Shaders, UI Layouts       │
├────────────────────────────────────────────────────────────────────────┤
│                           L2 TOOLING & AGENTS                          │
│     Built-in MCP Server (stdio/SSE), Vitest Matchers, Live Inspector   │
├────────────────────────────────────────────────────────────────────────┤
│                         L1 BATTERIES & SUBSYSTEMS                      │
│   Spatial Audio • Skeletal Animation • UI Projections • VFX Emitters   │
│   Declarative Presets: body, sensor, light, kccPlayer, dynamicPlayer   │
├────────────────────────────────────────────────────────────────────────┤
│                          L0 DETERMINISTIC KERNEL                       │
│   Integer Tick Clock • Seeded PRNG • Dual-Buffer Transform Pipeline    │
│   Quantized State Hashing (XXH3) • Resource Ownership Tracking         │
├────────────────────────────────────────────────────────────────────────┤
│                             NATIVE ENGINES                             │
│       Three.js (WebGL / WebGPU)   │   @dimforge/rapier3d-compat (WASM) │
└────────────────────────────────────────────────────────────────────────┘

📜 许可证

MIT © Esteban Leandro Marín

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers