Virtual 3D Studio — 网页版3D虚拟导演台
Overview
Deploy a full-featured browser-based 3D virtual studio — a director's stage where the user is the director, imported 3D characters are actors, and virtual cameras capture scenes. Built with Three.js 0.160 + Vite, pure vanilla JS, no framework dependencies.
When to Use
- User requests a 3D virtual studio, director's stage, or virtual photography platform
- User wants to import 3D characters (GLB/GLTF/FBX) and animate them in-browser
- User needs virtual camera control with shot types, focal lengths, and camera movements
- User wants to record video from virtual camera perspectives
- User mentions "小云雀3D导演台" or similar director-style 3D tools
- User needs pose presets, lighting control, composition guides for 3D scenes
Quick Start
Deploy the Template
- Run the deployment script to copy the template to a target directory:
python scripts/deploy_template.py <target-directory>
This copies all template files from assets/template/ and runs npm install automatically. Use --no-install to skip dependency installation.
- Start the dev server:
cd <target-directory> && npm run dev
- Open
http://localhost:3000in the browser.
Manual Deployment
If the script is unavailable, manually copy all files from assets/template/ to the target directory, then run npm install and npm run dev.
Feature Set
| Category | Features |
|---|---|
| 3D Viewport | WebGL rendering, orbit controls (rotate/zoom/pan), grid floor |
| Model Import | GLB/GLTF/FBX via drag-drop or file picker, auto-skeleton detection |
| Default Actor | Procedural block-character with full skeleton (no external model needed) |
| Animations | 5 procedural: idle/walk/wave/jump/run + imported animation playback |
| Pose Presets | 12 static poses: standing/arms-crossed/thinking/pointing/sitting/crouching/fighting/waving/hands-up/t-pose/hero/bowing |
| Transform | Move/Rotate/Scale gizmo (TransformControls), W/E/R hotkeys |
| Trajectory | Draw path on ground → character walks along Catmull-Rom curve |
| Shot Types | 6 presets: extreme-wide/wide/medium/medium-close/close/extreme-close — auto-adjusts FOV + distance |
| Focal Length | 14mm-200mm slider, 36mm sensor FOV conversion |
| Camera Movements | 10 types: push/pull/pan-left/pan-right/truck-left/truck-right/crane-up/crane-down/orbit/follow, easeInOutCubic |
| Virtual Cameras | Multiple camera positions, frustum visualization, follow target, live thumbnails |
| Video Recording | MediaRecorder API → WebM export from virtual camera POV |
| Lighting | 6 params: key intensity, key color temp (2000K-10000K), fill intensity, ambient intensity, exposure, light angle |
| Background | Import image as scene background |
| Composition | 5 guides: thirds/golden-ratio/safe-frame/crosshair/none (SVG overlay) |
| Environments | 3 presets: studio/outdoor/void |
| Screenshot | Export current frame as PNG |
| Hotkeys | W=Move, E=Rotate, R=Scale, Space=Play/Pause, F=Focus, Del=Delete, Esc=Deselect |
Architecture
For detailed module APIs and technical specifications, see references/architecture.md.
assets/template/
├── package.json # three, fflate, vite
├── vite.config.js # Port 3000, host enabled
├── index.html # Entry point
└── src/
├── main.js # Bootstrap: layout → Studio → AnimationSystem → UI → Recorder
├── Studio.js # 3D engine: scene/renderer/cameras/lights/import/transform/trajectory/cameras/shots/focal/movements/bg/composition/lighting
├── AnimationSystem.js # AnimationMixer + procedural animations + 12 pose presets
├── UI.js # Full director console: topbar/left/right/bottom panels
├── VideoRecorder.js # MediaRecorder canvas → WebM
└── style.css # Dark theme professional styling
Customization Guide
Add New Procedural Animations
In AnimationSystem.js, add a new entry to the procedural update functions in _getProceduralUpdate(). The function receives (bones, t) and manipulates bone rotations. Register the new type in getAnimations().
Add New Pose Presets
In AnimationSystem.js, add a new function to POSE_PRESETS object. Each function receives bones and sets static rotations. Register in getAvailablePoses().
Add New Shot Types
In Studio.js, add entries to SHOT_TYPES with { fov, distance } values. The setShotType() method handles the rest.
Add New Camera Movements
In Studio.js, add movement definitions to CAMERA_MOVEMENTS with position/rotation deltas. startCameraMovement() interpolates start→end over duration.
Add New Environments
In Studio.js, add environment setup to setEnvironment() — configure fog, ground, skybox, and default lighting per environment type.
Technical Notes
- Three.js version: 0.160.x (pinned in package.json). GLTFLoader/FBXLoader/TransformControls from
three/addons/. - No framework: Pure vanilla JS with ES modules. Vite handles dev serving and HMR.
- Browser requirements: WebGL2 support, MediaRecorder API for video recording (Chrome/Firefox/Edge recommended).
- Model formats: GLB recommended (single-file, embedded textures). GLTF requires external assets. FBX supported but heavier.
- Performance: Default character is low-poly boxes. Complex imported models may need LOD optimization for smooth recording.
