unicorn-studio

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unicorn Studio — No-code WebGL Scenes (Embed/SDK) Skill

Unicorn Studio — 无代码WebGL场景（嵌入/SDK）技能

When to use

适用场景

Designers want custom WebGL visuals without hand-coding shaders/three.js
You need “designed” effects layered with text/images/video, with built-in interactivity
Site builders: Framer, Webflow, Wix, Figma Sites, etc.

设计师无需手动编写着色器/three.js即可制作自定义WebGL视觉效果
需要将“设计好的”效果与文本/图片/视频分层，并具备内置交互功能
适用于网站搭建平台：Framer、Webflow、Wix、Figma Sites等

What it is

是什么

A scene editor (layers + effects + events) that exports:
- Embed via Unicorn Studio SDK (small JS library)
- Or JSON/code export for faster/self-hosted loading (plan-dependent)

一款场景编辑器（包含图层+效果+事件），可导出：
- 通过Unicorn Studio SDK（轻量JS库）嵌入
- 或导出JSON/代码以实现更快的加载速度或自托管（取决于套餐）

Key embed patterns

核心嵌入模式

Load SDK (can be in
```
<head>
```
or footer depending on above-the-fold):
- UMD from jsDelivr (versioned)
- Call
```
UnicornStudio.init()
```
  once DOM is ready

Add attributes to a container element:

```
data-us-project="PROJECT_ID"
```

Optional performance/behavior params:

```
data-us-scale
```
(render scale)
```
data-us-dpi
```
(resolution multiplier)
```
data-us-fps
```
(cap FPS)
```
data-us-lazyload="true"
```
```
data-us-production="true"
```

Optional JSON source:

data-us-project-src="https://.../scene.json.txt"

加载SDK（可根据是否在首屏决定放在
```
<head>
```
或页脚）：
- 来自jsDelivr的UMD版本（带版本号）
- DOM加载完成后调用
```
UnicornStudio.init()
```
  一次

为容器元素添加属性：

```
data-us-project="PROJECT_ID"
```
可选的性能/行为参数：
- ```
data-us-scale
```
  （渲染缩放比例）
- ```
data-us-dpi
```
  （分辨率乘数）
- ```
data-us-fps
```
  （帧率上限）
- ```
data-us-lazyload="true"
```
- ```
data-us-production="true"
```

可选的JSON源：

data-us-project-src="https://.../scene.json.txt"

Events (authoring-side)

事件（创作端）

Appear (entrance), Scroll (progress/velocity), Hover, Mousemove
Use events for “feels interactive” without writing JS.

出现（入场）、滚动（进度/速度）、悬停、鼠标移动
无需编写JS即可通过事件实现“交互式体验”

Common pitfalls

常见陷阱

Container has no defined dimensions → scene won’t display
- Ensure the element with
```
data-us-project
```
  has width/height.
Too many scenes on one page → WebGL context limits + memory
- Prefer <10 scenes/page; WebGL context max ~16.
Performance on low-end devices
- Use
```
data-us-scale
```
  /
```
data-us-dpi
```
  /
```
data-us-fps
```
  ; reduce dynamic layers/effects.
Site builder preview limitations
- Many builders won’t render in edit mode; must preview/publish to see it.

容器未定义尺寸→场景无法显示
- 确保带有
```
data-us-project
```
  的元素设置了宽高
单页中场景过多→WebGL上下文限制+内存占用过高
- 建议单页场景数<10；WebGL上下文最大约16个
低端设备上的性能问题
- 使用
```
data-us-scale
```
  /
```
data-us-dpi
```
  /
```
data-us-fps
```
  参数；减少动态图层/效果
网站搭建平台预览限制
- 许多平台在编辑模式下无法渲染，必须预览/发布才能查看

Quick recipes

快速示例

1) Basic embed container

1) 基础嵌入容器

html

<div style="width: 100%; height: 420px" data-us-project="YOUR_PROJECT_ID"></div>

html

<div style="width: 100%; height: 420px" data-us-project="YOUR_PROJECT_ID"></div>

2) Performance-first embed

2) 性能优先的嵌入

html

<div
  style="width: 100%; height: 420px"
  data-us-project="YOUR_PROJECT_ID"
  data-us-lazyload="true"
  data-us-production="true"
  data-us-scale="0.75"
  data-us-dpi="1.25"
  data-us-fps="45"
></div>

html

<div
  style="width: 100%; height: 420px"
  data-us-project="YOUR_PROJECT_ID"
  data-us-lazyload="true"
  data-us-production="true"
  data-us-scale="0.75"
  data-us-dpi="1.25"
  data-us-fps="45"
></div>

What to ask the user

需要询问用户的问题

Target platform: Webflow / Framer / coded site?
Is the scene above-the-fold? (affects script placement and lazyload)
Mobile support requirement + acceptable quality/FPS
Number of scenes on the page and whether JSON export is available

目标平台：Webflow / Framer / 自定义编码网站？
场景是否在首屏？（影响脚本放置和懒加载设置）
移动端支持要求以及可接受的质量/帧率
页面中的场景数量，以及是否可以使用JSON导出