> ## 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 & Visualization

> Data visualization, 3D scenes, game development, and AI 3D generation — three orthogonal plugins

# 3D & Visualization

Profy's 3D and visualization capabilities are provided by three orthogonal plugins:

| Plugin                            | Responsibility                          | Typical Use Cases                                   |
| --------------------------------- | --------------------------------------- | --------------------------------------------------- |
| **profy-visualize**               | Data visualization + Three.js 3D scenes | Charts, maps, 3D product showcases, scientific viz  |
| **profy-game-studio**             | Game development                        | 3D/2D games, physics simulations, sprite animations |
| **profy-creative** (3D extension) | AI 3D model generation                  | Text/image to 3D, post-processing, world generation |

## profy-visualize

Unified visualization plugin covering data charts and Three.js 3D scenes.

### Tools

#### `visualize` — Inline Visualization

Generates HTML/CSS/JS visualization fragments rendered directly in the chat area via Inline Visualization.

```python theme={null}
visualize(
    title="Quarterly Sales Trend",
    html="<div id='chart'></div>",
    css="body{margin:0}",
    js="// D3/Three.js code..."
)
```

**Output**: `result.inline_vis` → InlineVisualizationCard in chat (sandboxed iframe)

#### `inspect_3d` — Scene Diagnostics

Injects JavaScript into the target page, traverses the Three.js scene graph, and returns structured diagnostic data.

```python theme={null}
inspect_3d(url="http://localhost:5173")
```

**Returns**:

* `scene_tree` — Scene node tree (type, name, visibility, geometry info)
* `materials` — Material list (type, transparency, texture count)
* `animations` — Animation list (name, duration, track count)
* `performance` — Performance data (draw calls, triangles, texture/geometry memory)
* `warnings` — Performance warnings (over-budget alerts)
* `webgl_status` — WebGL context health

### Technology Stack

**CDN-available libraries**:

* Three.js — 3D scenes
* D3.js — Data-driven documents
* Vega-Lite / Vega-Embed — Declarative charts
* Observable Plot — Quick statistical charts
* @visx — React data visualization

### Dual-Mode Architecture

#### Standalone Mode (Quick Demos)

Single-file HTML with Three.js/D3 via CDN importmap:

* Rendered instantly as Inline Visualization via the `visualize` tool
* Or written to sandbox files for Widget display
* Downloadable and works in any browser

#### Integration Mode (R3F)

React Three Fiber within Sites projects:

* `@react-three/fiber` + `@react-three/drei` + `@react-three/postprocessing`
* Deep integration with TanStack Start
* All dependencies pre-baked in sandbox

### Skills (18)

Covering D3, geospatial, statistical charts, Canvas 2D, Three.js data viz, React component charts, Vega-Lite declarative, accessibility visualization, strategy selection, UML architecture, scrollytelling, Gantt charts, real-time dashboards, node-link diagrams, report export, and more.

***

## profy-game-studio

Standalone game development plugin supporting 3D and 2D games.

### Supported Engines/Frameworks

| Type      | Framework                  | Use Case                        |
| --------- | -------------------------- | ------------------------------- |
| 3D Native | Three.js + Rapier          | High-performance 3D games       |
| 3D React  | React Three Fiber + Rapier | Declarative 3D games            |
| 2D        | Phaser 3                   | 2D platformers/shooters/puzzles |

### Skills (9)

Game Studio router, Three.js WebGL games, React Three Fiber games, Phaser 2D games, 3D asset pipeline, game foundations, game UI, playtest QA, sprite pipeline.

### Pre-baked Sandbox Dependencies

* `phaser` — 2D game engine
* `@dimforge/rapier3d-compat` — Physics engine (WASM)
* Three.js ecosystem (shared with visualize)

***

## AI 3D Generation (profy-creative extension)

AI-driven 3D content creation via Tencent Hunyuan 3D API.

### `generate_3d` — 3D Model Generation

Generate 3D models from text descriptions, reference images, or sketches.

```python theme={null}
generate_3d(
    prompt="A cute cartoon Shiba Inu",
    mode="pro",           # rapid (fast) or pro (high quality)
    format="glb",         # glb/obj/fbx/stl
    pbr_materials=True    # PBR physical materials
)
```

**Supported inputs**:

* Text description (`prompt`)
* Reference image (`image_url`)
* Line sketch (`sketch_url`)

### `postprocess_3d` — 3D Post-processing

Post-process existing 3D models.

```python theme={null}
postprocess_3d(
    model_url="https://..../model.glb",
    action="retopology",    # retopology/texture/rig/animate/uv_unwrap/convert
    target_faces=5000
)
```

**Supported actions**:

* `retopology` — Retopologize (reduce faces)
* `texture` — Re-texture
* `rig` — Auto rigging
* `animate` — Auto animation
* `uv_unwrap` — UV unwrapping
* `convert` — Format conversion

### `generate_world` — World Generation (HY-World 2.0)

Generate navigable 3D worlds (3D Gaussian Splatting).

```python theme={null}
generate_world(
    prompt="A Japanese garden shrouded in mist",
    image_url="reference.png"   # optional reference
)
```

**Output**: 3DGS file + mesh file, automatically opens 3DGS viewer in Widget.

***

## Visual Verification Protocol (Vision in the Loop)

All visualization/3D/game development follows an auto-iteration verification protocol:

1. Generate/modify code
2. Capture screenshot: `browser(action="screenshot", html=<HTML>)` or `browser(action="screenshot", url="localhost:5173")`
3. Self-analyze the screenshot (blank? missing elements? wrong layout?)
4. If ANY issue found → fix → go to step 2
5. Loop until visually correct, then present to user

***

## Performance Budget

| Metric             | Mobile  | Desktop  |
| ------------------ | ------- | -------- |
| Triangles          | \< 500K | \< 2M    |
| Draw calls         | \< 50   | \< 200   |
| Total texture size | \< 50MB | \< 200MB |
| Target FPS         | 30 FPS  | 60 FPS   |

## Standalone Template

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>body{margin:0;overflow:hidden}canvas{display:block}</style>
</head>
<body>
<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"
  }
}
</script>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const scene = new THREE.Scene();
window.__THREE_SCENE__ = scene;

const camera = new THREE.PerspectiveCamera(75, innerWidth/innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true });
window.renderer = renderer;
renderer.setSize(innerWidth, innerHeight);
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

const controls = new OrbitControls(camera, renderer.domElement);
camera.position.set(0, 2, 5);

// Your 3D content...

function animate() {
  requestAnimationFrame(animate);
  controls.update();
  renderer.render(scene, camera);
}
animate();

addEventListener('resize', () => {
  camera.aspect = innerWidth / innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(innerWidth, innerHeight);
});
</script>
</body>
</html>
```

## Key Constraints

1. **Must expose scene**: `window.__THREE_SCENE__ = scene` and `window.renderer = renderer`, otherwise `inspect_3d` won't work
2. **Must handle resize**: All standalone demos must respond to window size changes
3. **Must have interaction controls**: OrbitControls or PresentationControls
4. **Limit pixel ratio**: `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`
5. **Canvas needs height**: R3F's `<Canvas>` parent must have explicit height

## MCP Bridge Plugins (Desktop Only)

For professional 3D modeling, Desktop users can connect local apps via MCP Bridge plugins:

| Bridge Plugin        | Application  | Capabilities                                     |
| -------------------- | ------------ | ------------------------------------------------ |
| **blender-bridge**   | Blender      | Modeling, rendering, animation, Python scripting |
| **photoshop-bridge** | Photoshop    | Image editing, layer ops, batch processing       |
| **godot-bridge**     | Godot Engine | Game engine, GDScript, scene management          |

These plugins are declarative (no runtime code), connecting to local MCP servers via `mcpServers` config (e.g., `uvx blender-mcp`).