云渲染安装使用

前置准备

1. 下载 PiStudio 客户端

📺 视频教程：CIMPro孪大师-pistudio云渲染使用

2. 下载前端示例代码包

解压后得到以下文件：

文件	说明
`pixel.html`	示例页面
`index.umd.js`	PiClient SDK（调用客户端接口）
`lib-pixelstreamingfrontend.js`	云渲染前端依赖库
`cloudrender.md`	云渲染初始化参数文档

快速接入（4步）

Step 1：引入 SDK

在 HTML 中引入两个必需的脚本文件：

html

<!-- 云渲染前端依赖 -->
<script src="./lib-pixelstreamingfrontend.js"></script>
<!-- PiClient SDK -->
<script src="./index.umd.js"></script>

Step 2：初始化 PiClient

javascript

// 检查 SDK 是否加载
if (!window.PiClientJS?.PiClient) {
  console.error('PiClientJS 库未加载');
}

// 创建实例
const piclient = new PiClientJS.PiClient({ debug: true });

Step 3：配置云渲染参数并连接

javascript

const initConfig = {
  $el: document.getElementById('renderContainer'),  // 渲染容器 DOM
  address: 'ws://127.0.0.1:8888',                   // 服务器地址
  appKey: '',                                       // AppKey（可选）
  mode: 'pixelstreaming',                           // 模式：pixelstreaming / embed
  editorMode: false,
  projectId: '',
  showUI: false,
  StreamerId: 'client_' + Date.now(),              // 唯一标识
  initialSettings: {
    MatchViewportRes: false,
    MinQP: 25,
    MaxQP: 35,
    WebRTCMinBitrate: 5000,
    WebRTCMaxBitrate: 100000,
    MaxReconnectAttempts: 0,      // 禁用自动重连
    TimeoutIfIdle: false,         // 禁用空闲超时
    AFKTimeout: 0                 // 禁用 AFK 超时
  },
  onProgress: (percent) => {
    console.log('加载进度:', percent + '%');
  },
  onDisconnect: (msg) => {
    console.log('连接断开:', msg);
  }
};

// 发起连接
piclient.cloudrender.init(initConfig).then((baseDb) => {
  console.log('连接成功', baseDb);
  // 进入播放模式
  piclient.emit('mode.enterPlayMode');
}).catch((err) => {
  console.error('连接失败:', err);
});

Step 4：发送第一个 API 调用

连接成功后，即可调用客户端 API：

javascript

// 设置天气为晴天
piclient.emit('environment.setWeather', { weather: 1 });

// 相机飞行到指定对象
piclient.emit('camera.fly', {
  target: 'ObjectId',
  time: '3.0'
});

事件监听

javascript

// 监听云渲染初始化完成
piclient.on('cloud.init', '', (res) => {
  console.log('云渲染初始化:', res);
});

// 监听对象点击事件
piclient.on('object.onClick', '', (res) => {
  console.log('对象被点击:', res);
});

// 全局监听所有事件
piclient.on('global', '', (res) => {
  console.log('全局事件:', res);
});

资源释放

页面卸载或需要断开连接时，务必调用销毁方法释放资源：

javascript

function forceDestroy() {
  if (!piclient) return;
  try {
    const cloudRenderIns = piclient._cloudrenderIns;
    if (cloudRenderIns?.webRtcPlayerController) {
      const c = cloudRenderIns.webRtcPlayerController;
      if (c.peerConnection) {
        c.peerConnection.close();
        c.peerConnection = null;
      }
      if (c.videoPlayer?.videoElement) {
        c.videoPlayer.videoElement.srcObject = null;
      }
      if (c.signallingProtocol?.webSocket?.readyState === WebSocket.OPEN) {
        c.signallingProtocol.webSocket.close(1000, 'Client disconnect');
      }
    }
    document.getElementById('renderContainer').innerHTML = '';
  } catch (e) {
    console.error(e);
  }
}

// 页面卸载时自动清理
window.addEventListener('beforeunload', forceDestroy);

常见问题

Q：连接失败怎么办？

检查服务器地址是否正确（格式 ws://ip:port）
确认 PiStudio 客户端已启动并处于等待连接状态
检查浏览器控制台是否有 CORS 或 WebSocket 错误

Q：如何禁用自动重连？

在 initialSettings 中设置 MaxReconnectAttempts: 0。

Q：连接成功后画面黑屏？

确认已进入播放模式：piclient.emit('mode.enterPlayMode')
检查 showUI 是否为 false，避免编辑器 UI 遮挡