> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 3D 与可视化开发
> 数据可视化、3D 场景、游戏开发与 AI 3D 生成 — 三个正交插件的完整能力
# 3D 与可视化开发
Profy 的 3D 与可视化能力由三个正交插件提供：
| 插件 | 职责 | 典型场景 |
| --------------------------- | ---------------------- | ----------------------- |
| **profy-visualize** | 数据可视化 + Three.js 3D 场景 | 图表、地图、3D 产品展示、科学可视化 |
| **profy-game-studio** | 游戏开发 | 3D/2D 游戏、物理模拟、Sprite 动画 |
| **profy-creative**（3D 生成扩展） | AI 3D 模型生成 | 文本/图片生成 3D、后处理、世界生成 |
## profy-visualize
统一的可视化插件，涵盖数据图表和 Three.js 3D 场景。
### 工具
#### `visualize` — 内联可视化
生成 HTML/CSS/JS 可视化片段，通过 Inline Visualization 渲染面直接嵌入聊天区。
```python theme={null}
visualize(
title="季度销售趋势",
html="",
css="body{margin:0}",
js="// D3/Three.js 代码..."
)
```
**返回方式**：`result.inline_vis` → 聊天区 InlineVisualizationCard（沙箱 iframe）
#### `inspect_3d` — 场景诊断
注入 JavaScript 到目标页面，遍历 Three.js 场景图，返回结构化诊断数据。
```python theme={null}
inspect_3d(url="http://localhost:5173")
```
**返回数据**：
* `scene_tree` — 场景节点树（类型、名称、可见性、几何体信息）
* `materials` — 材质清单（类型、透明度、贴图数量）
* `animations` — 动画列表（名称、时长、轨道数）
* `performance` — 性能数据（draw calls、三角面数、纹理/几何体内存）
* `warnings` — 性能警告（超预算提醒）
* `webgl_status` — WebGL 上下文健康状态
### 技术栈
**CDN 可用库**：
* Three.js — 3D 场景
* D3.js — 数据驱动文档
* Vega-Lite / Vega-Embed — 声明式图表
* Observable Plot — 快速统计图表
* @visx — React 数据可视化
### 双模式架构
#### Standalone 模式（快速 demo）
单文件 HTML，Three.js/D3 通过 CDN importmap 加载：
* 通过 `visualize` 工具即时渲染为 Inline Visualization
* 或写入沙箱文件通过 Widget 展示
* 下载后在任何浏览器中直接打开
#### Integration 模式（R3F 集成）
在 Sites 项目中使用 React Three Fiber：
* `@react-three/fiber` + `@react-three/drei` + `@react-three/postprocessing`
* 与 TanStack Start 框架深度集成
* 沙箱中已预烘焙所有依赖
### Skills（18 个）
涵盖 D3、地理空间、统计图、Canvas 2D、Three.js 数据可视化、React 组件化图表、Vega-Lite 声明式、无障碍可视化、策略选型、UML 架构图、滚动叙事、甘特图、实时仪表盘、节点链接图、报告导出等。
***
## profy-game-studio
独立的游戏开发插件，支持 3D 和 2D 游戏。
### 支持的引擎/框架
| 类型 | 框架 | 适用场景 |
| -------- | -------------------------- | ----------- |
| 3D 原生 | Three.js + Rapier | 高性能 3D 游戏 |
| 3D React | React Three Fiber + Rapier | 声明式 3D 游戏 |
| 2D | Phaser 3 | 2D 平台/射击/益智 |
### Skills（9 个）
游戏工作室路由、Three.js WebGL 游戏、React Three Fiber 游戏、Phaser 2D 游戏、3D 资产管线、游戏基础设施、游戏 UI、Playtest QA、Sprite 管线。
### 沙箱预烘焙依赖
* `phaser` — 2D 游戏引擎
* `@dimforge/rapier3d-compat` — 物理引擎（WASM）
* Three.js 生态（与 visualize 共享）
***
## AI 3D 生成（profy-creative 扩展）
通过腾讯混元 3D API 实现 AI 驱动的 3D 内容创作。
### `generate_3d` — 3D 模型生成
从文本描述、参考图片或草图生成 3D 模型。
```python theme={null}
generate_3d(
prompt="一只可爱的卡通柴犬",
mode="pro", # rapid（快速）或 pro（高质量）
format="glb", # glb/obj/fbx/stl
pbr_materials=True # PBR 物理材质
)
```
**支持输入**：
* 文本描述（`prompt`）
* 参考图片（`image_url`）
* 线稿草图（`sketch_url`）
### `postprocess_3d` — 3D 后处理
对已有 3D 模型进行后处理操作。
```python theme={null}
postprocess_3d(
model_url="https://..../model.glb",
action="retopology", # retopology/texture/rig/animate/uv_unwrap/convert
target_faces=5000
)
```
**支持操作**：
* `retopology` — 重新拓扑（减面）
* `texture` — 重新贴图
* `rig` — 自动骨骼绑定
* `animate` — 自动动画
* `uv_unwrap` — UV 展开
* `convert` — 格式转换
### `generate_world` — 世界生成（HY-World 2.0）
生成可导航的 3D 世界（3D Gaussian Splatting）。
```python theme={null}
generate_world(
prompt="一座被薄雾笼罩的日式庭院",
image_url="reference.png" # 可选参考图
)
```
**输出**：3DGS 文件 + 网格文件，自动在 Widget 中打开 3DGS 查看器。
***
## 视觉验证协议（Vision in the Loop）
所有可视化/3D/游戏开发都遵循自动迭代验证协议：
1. 生成/修改代码
2. 截图验证：`browser(action="screenshot", html=)` 或 `browser(action="screenshot", url="localhost:5173")`
3. 自我分析截图（空白？缺元素？布局错？）
4. 有问题 → 修复 → 回到步骤 2
5. 循环直到视觉正确，才呈现给用户
***
## 性能预算
| 指标 | 移动端 | 桌面端 |
| ---------- | ------- | -------- |
| 三角面数 | \< 500K | \< 2M |
| Draw calls | \< 50 | \< 200 |
| 纹理总大小 | \< 50MB | \< 200MB |
| 目标帧率 | 30 FPS | 60 FPS |
## Standalone 模板
```html theme={null}
```
## 关键约束
1. **必须暴露场景**：`window.__THREE_SCENE__ = scene` 和 `window.renderer = renderer`，否则 `inspect_3d` 无法工作
2. **必须处理 resize**：所有 Standalone demo 必须响应窗口大小变化
3. **必须有交互控制**：OrbitControls 或 PresentationControls
4. **限制像素比**：`renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`
5. **Canvas 需要高度**：R3F 的 `