加载网页
LoadWeb| 载体 | 主页对象 |
|---|---|
| 参数 |
|
| 功能 | 运行时加载指定网页。全局有且仅能有一个。 |
| URL 类型 |
|
3DsWorks 是一款面向非程序人员的交互式 3D 内容制作工具:商务人员可以用它制作 3D 版演示文稿,市场人员可以快速生成营销互动内容,工程师可以把 3D CAD 文件直接变成可交互的数字孪生场景。
3DsWorks 由来自全球 8 个国家及地区的 30 多名开发者历经 6 年打造,目标是创造一个极其简单的 3D 互动内容创作工具,让创作者可以快速开发出满足场景需要的 3D 交互内容,例如元宇宙、数字孪生、大屏展示,甚至是 FakeUI。
3DsWorks 在好莱坞电影特效(FakeUI)、航空航天、轨道交通、数字城市、数字星球以及自动化领域都有丰富的应用案例。
3DsWorks 现阶段为 CS 架构 解决方案,暂不支持 BS 架构。BS 版本的支持计划将在后续版本中提供。
3DsWorks 是一个去中心化的研发团队,项目采用了多个国家的技术,其中既涉及中国技术,也包含美国技术。3DsWorks 团队是虚拟团队,不存在于任何物理世界中的任何国家。
我们在全球各地设有当地经销商,由经销商按照当地法律开展市场活动并开具当地发票,因此 3DsWorks 不受各国高科技出口管制影响。
版权所有 © 2013–2026 3DsWorks。
本手册按使用者的工作流程组织,建议按下列顺序阅读:
左侧目录可折叠;顶栏搜索框支持按组件名、函数名、配置项快速定位(快捷键 /)。文中截图可点击放大,按 Esc 关闭。
通过 菜单 › 文件 › 导入 将本地模型文件导入当前工程。
支持的文件类型:Obj、3ds、fbx、stl、gltf、glb、ply、3mf、zip。
通过 菜单 › 资源 导入软件内置的资源文件。
导入模型后,需要先制作模型引用库,才能对模型进行材质编辑;否则只能预览模型效果,无法编辑材质。引用库中可以新建文件夹进行归类。
支持导入火焰、雾气、天气、特效、电、水等资源。
双击对象可获取材质名称,然后用鼠标选择材质颜色进行编辑,也可以编辑材质的其他参数。
| 格式 | 说明 |
|---|---|
FBX | 接受 7.0 以上版本。强烈推荐 FBX,支持得最完善。 |
OBJ | 通用静态模型格式。 |
GLTF 2 | 接受使用实验性功能的 Draco 解压。 |
STL | 常用于 3D 打印与 CAD 导出。 |
PLY | 多边形网格格式。 |
3MF | 3D 制造格式。 |
ZIP | 打包的模型资源。 |
BMPGIFJPGPNGPSDTGAHDR(仅用于加载天空盒,不建议作为普通纹理使用)导入前建议先在建模软件中检查法线朝向与单位比例,可减少 FBX 导入后的镶嵌与材质异常。
低代码组件用于在不编写脚本的情况下完成最常见的交互:切换相机、切换网页、切换场景、对象激活与禁用、关闭软件。下列各节按组件逐一说明操作步骤。
低代码交互示例:通过按钮或事件在多个相机视角之间切换。
3DsWorks 的组件以“检视器(Inspector)”中的属性面板形式提供。每个组件都说明了它的载体(可挂载的对象类型)、参数(可在面板中设置的项目)与功能,并给出模糊搜索时使用的关键字。
在检视器中点击“添加组件”,输入组件的中文名或英文类名即可模糊搜索到该组件。同一对象上,对象预警(网页)、对象预警仿真、对象高亮、对象鼠标事件管理 四个组件只能同时存在一个。
| 组件 | 载体 | 一句话说明 |
|---|---|---|
| 场景必需组件 | ||
| 加载网页 | 主页对象 | 运行时加载指定网页,全局唯一。 |
| 相机控制器 | 主相机 | 运行时位移、旋转、缩放相机。 |
| 基础功能组件 | ||
| 广告牌 | 任意 3D 对象 | 使对象始终朝向主相机。 |
| 加载图片 | 图片组件 | 按 URL 显示图片。 |
| 对象高亮 | 带碰撞器的 3D 对象 | 高亮对象外轮廓或整体。 |
| 2D 画布 | 画布 | 将 3D 界面转换为 2D 界面。 |
| 切换相机位(3D) | 带碰撞器的 3D 对象 | 点击 3D 对象切换相机视角。 |
| 切换相机位(2D) | 按钮 | 点击按钮切换相机视角。 |
| 切换网页(2D 界面) | 按钮 | 点击按钮切换网页 URL。 |
| 切换网页(3D) | 带碰撞器的 3D 对象 | 点击 3D 对象切换网页 URL。 |
| 视频播放器(2D) | UI 元素 | 在 2D / 3D 画布下播放视频。 |
| 视频播放器(3D) | 任意 3D 对象 | 在 3D 对象表面播放视频。 |
| 视频播放器(融合) | 任意 3D 对象 | 支持自定义拉伸网格形状的视频播放。 |
| 加载场景(3D) | 带碰撞器的 3D 对象 | 点击 3D 对象加载场景。 |
| 加载场景(2D 界面) | 按钮 | 点击按钮加载场景。 |
| 对象预警仿真 | 3D 对象 | 运行时闪烁预警。 |
| 对象组激活禁用 | 任意对象 | 激活 / 禁用指定对象组。 |
| 相机漫游 | 任意对象(作用于主相机) | 沿路径漫游并注视目标。 |
| 第一人称角色控制器 | 预制件 | WASD 第一人称行走。 |
| 对象鼠标事件管理 | 带碰撞器与网格渲染器的 3D 对象 | 鼠标进入 / 离开 / 单击 / 双击响应。 |
| 前端 & 3D 交互组件 | ||
| 对象颜色设置(网页) | 带网格渲染器的 3D 对象 | 前端调用 changeColor 改色。 |
| 对象坐标动画设置(网页) | 3D 对象 | 前端调用 tweenObj 控制补间动画。 |
| 传递数据到网页(网页) | 带碰撞器的 3D 对象 | 点击对象把数据发给网页。 |
| 传递对象屏幕坐标到网页(网页) | 带碰撞器的 3D 对象 | 鼠标停留时发送屏幕坐标。 |
| 对象预警(网页) | 3D 对象 | 前端调用 objAlarm 开关预警。 |
| 电梯管理(网页) | UI 元素 | 按楼层实例化电梯并控制去向。 |
| 中控组件 | ||
| 一键顺控连接器 | 场景(唯一) | 连接中控服务器。 |
| 一键顺控(3D) | 带碰撞器的 3D 对象 | 点击对象批量执行指令。 |
| 一键顺控(2D) | 按钮 | 点击按钮批量执行指令。 |
以下两个组件在每个场景中有且仅有一个,已存在于现有场景中,通常无需手动添加。
| 载体 | 主页对象 |
|---|---|
| 参数 |
|
| 功能 | 运行时加载指定网页。全局有且仅能有一个。 |
| URL 类型 |
|
| 载体 | 主相机 |
|---|---|
| 参数 | 位移速度、滚轮缩放速度、缩放最大距离、缩放最小距离、旋转灵敏度(见下图)。 |
| 功能 | 运行时操作相机位移、旋转、缩放等基础功能。全局有且仅能有一个。 |
| 前端控制 | 可通过 enableCameraController() 激活或禁用相机控制器。 |
| 载体 | 任意 3D 对象 |
|---|---|
| 参数 | 是否翻转 180 度。 |
| 功能 | 运行时使对象始终朝向主相机。 |
| 检索关键字 | Billboard 或 广告牌 |

| 载体 | 图片组件 |
|---|---|
| 参数 | 图片 URL 地址。 |
| 功能 | 运行时根据对应的 URL 显示图片,也可以通过网页交互进行设置。 |
| 检索关键字 | LoadImage 或 加载图片 |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 参数 |
|
| 功能 | 高亮 3D 对象及其所有子对象,可通过鼠标或代码控制。 |
| 相关 API | highlightObjOutlineColor()、highlightObjOverlayColor()、clearObjHighlight()。 |
| 检索关键字 | HighLightObj 或 对象高亮 |

highlightObjOutlineColor 的 highQuality 选项:硬件配置较高时开启后高亮效果更好,并可设置透明度,但同时会增加性能开销。硬件配置较低时建议不要开启,否则可能出现高亮显示错乱。
同一个对象上,对象预警(网页)、对象预警仿真、对象高亮、对象鼠标事件管理组件只能同时存在一个。
| 载体 | 画布 |
|---|---|
| 参数 | 画布层级,默认 3。存在多个 2D 画布时,层级越高渲染越优先。 |
| 功能 | 2D 界面必需组件,可使默认的 3D 界面在运行时转化为 2D 界面。 |
| 快捷生成 | 工具栏 › 对象 › UI › 2D 画布 |
| 检索关键字 | Canvas2D 或 2D画布 |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 参数 | 相机组名称、相机视角编号。 |
| 功能 | 运行时点击 3D 对象,主相机切换到指定视角。 |
| 检索关键字 | CameraMove3DClick 或 切换相机位(3D) |

| 载体 | 按钮 |
|---|---|
| 参数 | 相机组名称、相机视角编号。 |
| 功能 | 运行时点击按钮,主相机切换到指定视角。 |
| 快捷生成 | 工具栏 › 对象 › UI › 按钮(切换相机) |
| 检索关键字 | CameraMove2DClick 或 切换相机位(2D) |

| 载体 | 按钮 |
|---|---|
| 参数 | 网页 URL 地址。 |
| 功能 | (2D 界面)运行时点击按钮切换网页 URL。 |
| 快捷生成 | 工具栏 › 对象 › UI › 按钮(切换网页) |
| 检索关键字 | SwitchBrowser 或 切换网页(2D) |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 参数 | 网页 URL 地址。 |
| 功能 | 运行时点击 3D 对象切换网页 URL。 |
| 检索关键字 | SwitchBrowser3DClick 或 切换网页(3D) |

| 说明 | UI 元素,需放置在 2D / 3D 画布下。 |
|---|---|
| 参数 | 是否运行时自动播放;视频地址(支持 http、rtsp 格式)。 |
| 功能 | 播放视频(运行时自动播放,或注册到按钮事件手动播放 / 停止)。 |
| 快捷生成 | 工具栏 › 对象 › UI › 视频播放器(2D) |
| 检索关键字 | VideoPlayer2D 或 视频播放器(2D) |

| 载体 | 任意 3D 对象 |
|---|---|
| 参数 |
|
| 功能 | 3D 对象视频播放。 |
| 按钮函数 | Play() 播放;Pause() 暂停;Stop() 中止。 |
| 快捷生成 | 工具栏 › 对象 › 3D 对象 › 视频播放器(3D) |
| 检索关键字 | VideoPlayer3D 或 视频播放器(3D) |

| 载体 | 任意 3D 对象 |
|---|---|
| 参数 |
与“视频播放器(3D)”相同,另有:
|
| 功能 | 派生自视频播放器(3D),在 3D 对象上播放视频,同时支持自定义拉伸网格形状,需配合自定义建模工具使用。 |
| 按钮函数 | Play() 播放;Pause() 暂停;Stop() 中止。 |
| 快捷生成 | 工具栏 › 对象 › 3D 对象 › 视频播放器(融合) |
| 检索关键字 | VideoPlayerFusion 或 视频播放器(融合) |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 参数 | 场景路径。 |
| 功能 | 运行时点击 3D 对象加载指定场景。 |
| 路径说明 | 需提供工程目录中的完整路径,以 Asset 文件夹为根目录;也可在磁盘目录中查找(推荐),详见 关于场景路径。 |
| 检索关键字 | LoadScene3DClick 或 加载场景(3D) |

| 载体 | 按钮 |
|---|---|
| 参数 | 场景路径。 |
| 功能 | (2D 界面)运行时点击按钮加载指定场景。 |
| 快捷生成 | 工具栏 › 对象 › UI › 按钮(加载场景) |
| 检索关键字 | LoadScene 或 加载场景(2D) |

| 载体 | 3D 对象 |
|---|---|
| 参数 |
|
| 功能 | 运行时对对象进行仿真预警。 |
| 检索关键字 | ObjAlarmSimulation 或 对象预警仿真 |

同一个对象上,对象预警(网页)、对象预警仿真、对象高亮、对象鼠标事件管理组件只能同时存在一个。
| 载体 | 任意对象 |
|---|---|
| 参数 |
|
| 功能 | 运行时激活 / 禁用指定的对象组。 |
| 快捷生成 | 工具栏 › 对象 › UI › 按钮(对象组激活禁用) |
| 检索关键字 | ObjsAbleCtrl 或 对象组激活禁用 |

| 载体 | 可挂载于任意对象,但实际指向的是主相机对象。 |
|---|---|
| 参数 |
|
| 按钮函数 | Play() 播放;Pause() 暂停;Stop() 中止并回到第一个路径点;Restart() 重新播放。 |
| 检索关键字 | CameraAutoRoaming 或 相机漫游 |

漫游过程中如进行相机控制器的移动、旋转、拖动、拉近缩远、放大缩小视角等操作,会立即中止漫游并回到第一个路径点。
| 载体 | 预制件 |
|---|---|
| 参数 |
|
| 生成方式 | 工具栏 › 对象 › 3D 对象 › 第一人称控制器预制件。单独添加此组件会报错、不起作用。 |
| 功能 | 第一人称角色控制器。 |

运行时使用第一人称控制器时,以下受主相机影响的功能将失效:相机控制器、切换相机位(3D)、切换相机位(2D)、相机漫游,以及 3DsWorks.js 中的 enableCameraController() 与 cameraMove()。删除或禁用第一人称控制器后恢复。
| 载体 | 任意带碰撞器、网格渲染器的 3D 对象 |
|---|---|
| 参数 |
|
| 检索关键字 | ObjMouseEventMgr 或 对象鼠标事件管理 |

同一个对象上,对象预警(网页)、对象预警仿真、对象高亮、对象鼠标事件管理组件只能同时存在一个。消息内容推荐使用 JSON 字符串,便于网页端解析。
这一组组件不直接响应鼠标,而是为网页(H5)提供操作 3D 场景的接口。配合 JavaScript API 使用。
| 载体 | 任意带网格渲染器的 3D 对象 |
|---|---|
| 功能 | 前端通过 changeColor 方法改变 3D 场景中的对象颜色。 |
| 检索关键字 | ObjChangeColorLabel 或 对象颜色设置(网页) |

| 载体 | 3D 对象 |
|---|---|
| 功能 | 前端通过 tweenObj 方法控制 3D 对象的位移、旋转、缩放动画。 |
| 检索关键字 | TransformTweenLabel 或 对象坐标动画设置(网页) |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 功能 | 运行时点击 3D 对象,把此对象的数据(名称、世界坐标、视口坐标)发送给网页;网页通过 sendObjInfo 类型接收。具体说明参考 3DsWorks.js。 |
| 检索关键字 | SendInfoToH5 或 传递数据到网页(网页) |

| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 功能 | 运行时鼠标停留在 3D 对象上,把此对象的屏幕坐标数据发送给网页;网页通过 sendObjScreenCoord_MouseStay 类型接收。 |
| 检索关键字 | MouseStaySendObjScreenCoord 或 传递对象屏幕坐标到网页(网页) |

| 载体 | 3D 对象 |
|---|---|
| 参数 | 预警时对象显示的颜色;闪烁速度(值越大闪烁频率越快)。 |
| 功能 | 前端通过 objAlarm 方法控制指定对象的高亮预警开启 / 关闭效果。 |
| 检索关键字 | AlarmObj 或 对象预警(网页) |

同一个对象上,对象预警(网页)、对象预警仿真、对象高亮、对象鼠标事件管理组件只能同时存在一个。
| 说明 | UI 元素,需放置在 2D / 3D 画布下。 |
|---|---|
| 参数 | 电梯最低楼层、最高楼层。 |
| 功能 | 运行时根据参数实例化成相应楼层的电梯实例;网页通过 goToFloor() 控制前往电梯的楼层数。 |
| 快捷生成 | 工具栏 › 对象 › UI › 电梯 |

中控组件用于与中控服务器通信,按指令集批量控制设备。
| 参数 | IP、端口。 |
|---|---|
| 功能 |
|
| 生成方式 | 工具栏 › 工具 › 物联 › 创建一键顺控连接器。不建议通过添加组件的方式创建。 |

每次加载场景时,一键顺控连接器会自动初始化为断开状态。
| 载体 | 任意带碰撞器的 3D 对象 |
|---|---|
| 参数 | 指令集。 |
| 功能 | 运行时点击 3D 对象,批量执行指令集中的指令(需一键顺控连接器已连接)。 |
| 检索关键字 | DeviceReverseCtrl3D 或 一键顺控(3D) |

| 载体 | 按钮 |
|---|---|
| 参数 | 指令集。 |
| 功能 | 按钮需注册组件中的 Execute 方法,在运行时点击按钮批量执行指令集中的指令。 |
| 快捷生成 | 工具栏 › 对象 › UI › 按钮(一键顺控) |
| 检索关键字 | DeviceReverseCtrl2D 或 一键顺控(2D) |

场景路径需提供在工程目录中的完整路径,以 Asset 文件夹为根目录;也可以在磁盘目录中查找(推荐),以
\3DsWorks_Data\StreamingAssets\DefaultProject\Assets 为根目录。场景文件为 .rtscene 后缀,取场景名称即可。

场景路径则为:test1

场景路径则为:Scenes/test2

场景路径则为:Scenes/Main/test3
下表演示了在网页(H5)中通过按钮调用 3DsWorks API 的写法,以及对应的工具侧组件配置。所有函数都需要在 3DsWorks 内嵌浏览器中运行。
| API 功能 | 调用代码 | 工具配置 |
|---|---|---|
| 相机切换 | <button onclick="cameraMove('相机组1',1)">相机组1-视角1</button> |
![]() |
| 修改物体颜色 | <button onclick="changeColor('方块1',0,255,0,255)">方块1绿色化</button>
<button onclick="changeColor('方块1',255,255,0,125)">方块1黄色透明化</button> |
![]() |
| 3D 标签 | <button onclick="handle3DLabel('3D标签1','value1','http:\\browser9.qhimg.com/bdm/640_395_0/t01164a798a68fbf958.jpg')">3D标签设置</button>
<button onclick="handle3DTextLabel('3D文本标签1','value2')">3D文本标签设置</button>
<button onclick="handle3DImageLabel('3D图片标签1','http:\\browser9.qhimg.com/bdm/640_395_0/t019fd908f724f51900.jpg')">3D图片标签设置</button> |
— |
| 加载场景 | <button onclick="loadScene('Scenes/test1')">加载test1场景</button> |
— |
| 物体动画 | <button onclick="tweenObj('Meta','位置',0,0,-5,2)">Meta在2秒内移动到(0,0,-5)处</button>
<button onclick="tweenObj('Meta','旋转',0,180,0,1)">Meta在1秒内旋转180度</button>
<button onclick="tweenObj('Meta','比例',2,2,2,3)">Meta在3秒内比例变为2</button> |
— |
| 物体预警 | <button onclick="objAlarm('Meta',true)">Meta开启对象高亮预警</button>
<button onclick="objAlarm('Meta',false)">Meta关闭对象高亮预警</button> |
![]() |
| 对象显示隐藏 | <button onclick="objActiveCtrl('Fire01',true)">激活火焰Fire01</button>
<button onclick="objActiveCtrl('Fire01',false)">关闭火焰Fire01</button>
<button onclick="objActiveCtrl('Meta',true)">激活Meta</button>
<button onclick="objActiveCtrl('Meta',false)">关闭Meta</button> |
— |
| 电梯 | <button onclick="goToFloor('电梯1',2)">去往电梯1的2楼</button>
<button onclick="goToFloor('电梯1',5)">去往电梯1的5楼</button> |
— |
示例中的对象名称(如 Meta、方块1、电梯1)需与场景层次结构中的名称一致。
3DsWorks.js 提供了前端页面(H5)与孪生端之间双向通信的能力,分为两个方向:
H5ToTwin 对象调用,向后端发送指令;TwinToH5 注册消息监听器,接收孪生端推送的数据。H5 页面需运行在 3DsWorks 内嵌的浏览器组件中。页面加载完成后请先调用 TwinToH5.addMessageListener() 注册监听,再调用 H5ToTwin 的相关方法。
方法一览:
| 函数 | 参数 | 说明 |
|---|---|---|
enableCameraController(enable) | Boolean enable:是否激活 | 是否激活相机控制器(第一人称控制器启用时无效)。 |
block3DRayCaster(block) | Boolean block:是否阻塞 | 是否阻塞 3D 对象射线。默认 false,射线会穿透 2D 和 3D,两者都可交互;设置为 true 将屏蔽 3D 对象交互、保留 2D 交互。此函数仅控制 2D 与 3D 的射线是否穿透,相机控制器不受影响;如需屏蔽相机交互,请调用 enableCameraController。 |
openURL(url) | String url:目标网址 | 调用浏览器打开目标网址(适用于打开外部链接、下载文件)。 |
cameraMove(name, num, duration) | String name:相机组名称;Number num:视角编号;Number duration:可选,动画时间,默认 0.5s | 切换相机组视角(第一人称控制器启用时无效)。推荐使用默认动画时间。 |
changeColor(name, r, g, b, a) | String name:对象名称;Number r/g/b/a:0–255 | 设置 3D 对象材质颜色(目前只支持标准材质)。 |
highlightObjOutlineColor(name, r, g, b, width) | String name:对象名称;Number r/g/b:0–255;Number width:外轮廓宽度,默认 0.5 | 高亮目标 3D 对象并设置其外轮廓(边框)颜色。注:1、需挂载“对象高亮”组件,确保激活“设置外轮廓”字段、禁用“鼠标事件”字段;2、仅高亮设备外边框,如需高亮对象整体,请使用 highlightObjOverlayColor()。 |
highlightObjOverlayColor(name, r, g, b, isFlashing) | String name:对象名称;Number r/g/b:0–255;Boolean isFlashing:是否闪烁,默认 true | 高亮目标 3D 对象并设置其整体颜色。注:需挂载“对象高亮”组件,确保激活“设置整体”字段、禁用“鼠标事件”字段;仅高亮设备整体,如需高亮外轮廓(边框),请使用 highlightObjOutlineColor()。 |
clearObjHighlight(name) | String name:对象名称 | 清除目标 3D 对象高亮状态。需挂载“对象高亮”组件,确保禁用“鼠标事件”字段。 |
handle3DLabel(name, title, url) | String name:标签名称;String title:标题;String url:图片地址 | 操作 3D 标签。 |
handle3DTextLabel(name, title) | String name:3D 文本标签名称;String title:标题 | 操作 3D 文本标签。 |
handle3DImageLabel(name, url) | String name:3D 图片标签名称;String url:图片地址 | 操作 3D 图片标签。 |
tweenObj(name, animationType, x, y, z, duration) | String name:对象名称;String animationType:位置、旋转、比例;Number x/y/z:目标值;Number duration:持续时长 | 控制 3D 对象坐标动画,支持位置、旋转、比例三种补间动画,x/y/z 对应所选类型的对象位置/旋转/比例目标值。 |
loadScene(path) | String path:场景路径 | 加载 3D 场景。场景路径写法参考“加载场景(3D)”组件说明。 |
objAlarm(name, isAlarm) | String name:对象名称;Boolean isAlarm:是否预警 | 对象预警(高亮闪烁),控制 3D 对象开启/关闭预警。 |
objActiveCtrl(name, isOpen) | String name:对象名称;Boolean isOpen:true 开启,false 关闭 | 对象显示/隐藏控制(适用于 3D 对象、粒子、水等)。 |
goToFloor(name, targetFloor) | String name:电梯对象名称;Number targetFloor:目标楼层 | 控制电梯楼层。注意不能小于最低楼层、不能大于最高楼层。 |
getPostProcessProfiles() | 无 | 获取后期预设列表。通过 sendPostProcessProfiles 监听结果。 |
getSkyBoxs() | 无 | 获取天空盒列表。通过 sendSkyBoxs 监听结果。 |
setPostProcessProfile(name) | String name:后期预设名称 | 设置指定后期预设。名称可通过“顶部工具栏 › 编辑 › 设置”或 getPostProcessProfiles() 获取。 |
setSkyBox(name) | String name:天空盒名称 | 设置指定天空盒。名称可通过“顶部工具栏 › 编辑 › 设置”或 getSkyBoxs() 获取。 |
resetFirstCharacterTransform() | 无 | 重置第一人称角色控制器到初始位置。注:1、如未找到第一人称角色控制器则无效果;2、初始位置为编辑器中指定的最后位置。 |
孪生端主动推送给网页的消息通过 type 字段区分,网页在 handleMessage 中按 type 处理。目前已支持的消息类型如下:
| type 类型 | 说明 |
|---|---|
sendObjInfo | 点击对象后返回该对象的数据(名称、世界坐标、视口坐标),由“传递数据到网页(网页)”组件触发。 |
sendPostProcessProfiles | 返回后期预设列表,由 getPostProcessProfiles() 触发。 |
sendSkyBoxs | 返回天空盒列表,由 getSkyBoxs() 触发。 |
sendObjScreenCoord_MouseStay | 返回鼠标停留对象的屏幕坐标数据,由“传递对象屏幕坐标到网页(网页)”组件触发。 |
监听器的注册与移除:TwinToH5.addMessageListener() / TwinToH5.removeMessageListener()。收到的事件数据为字符串,需先用 JSON.parse 解析。
将下列两段源码保存为 3DsWorks.js 并在页面中引入,即可使用 H5ToTwin 与 TwinToH5。
<!-- H5 -> 孪生端 -->
var H5ToTwin = (function () {
/**
* 是否激活相机控制器
*(第一人称控制器启用时无效)
* @param {Boolean} enable 是否激活
* @return {void}
*/
function enableCameraController(enable) {
window.vuplex.postMessage({type: 'enableCameraController', enable: enable});
}
/**
* 是否阻塞 3D 对象射线。
* 注:
* 1、默认 false,射线会穿透 2D 和 3D,两者都可交互。如设置为 true,将屏蔽 3D 对象交互,保留 2D 交互;
* 2、此函数仅控制 2D 和 3D 的射线是否穿透,相机控制器不受影响。如需屏蔽相机交互,调用 enableCameraController
* @param {Boolean} block 是否阻塞
* @return {void}
*/
function block3DRayCaster(block) {
window.vuplex.postMessage({type: 'block3DRayCaster', block: block});
}
/**
* 调用浏览器打开目标网址(适用于打开外部链接,下载文件)
* @param {String} url 目标网址
* @return {void}
*/
function openURL(url) {
window.vuplex.postMessage({type: 'openURL', url: url});
}
/**
* 切换相机组视角
*(第一人称控制器启用时无效)
* @param {String} name 相机组名称
* @param {Number} num 相机视角编号
* @param {Number} duration 可选。动画时间,默认0.5s。推荐使用默认时间。
* @return {void}
*/
function cameraMove(name, num, duration) {
if (!duration) {
duration = 0.5;
}
window.vuplex.postMessage({type: 'cameraMove', name: name, num: num, duration: duration});
}
/**
* 设置 3D 对象材质颜色(目前只支持标准材质)
* @param {String} name 对象名称
* @param {Number} r Red 0-255
* @param {Number} g Green 0-255
* @param {Number} b Blue 0-255
* @param {Number} a Alpha 0-255
* @return {void}
*/
function changeColor(name, r, g, b, a) {
window.vuplex.postMessage({type: 'changeColor', name: name, r: r, g: g, b: b, a: a});
}
/**
* 高亮目标 3D 对象并设置其外轮廓(边框)颜色。
* 注:
* 1、需挂载“对象高亮”组件,确保激活“设置外轮廓”字段,禁用“鼠标事件”字段
* 2、仅高亮设备外边框,如需高亮对象整体,使用 highlightObjOverlayColor()
* @param {String} name 对象名称
* @param {Number} r Red 0-255
* @param {Number} g Green 0-255
* @param {Number} b Blue 0-255
* @param {Number} width 外轮廓宽度,默认 0.5
* @return {void}
*/
function highlightObjOutlineColor(name, r, g, b, width) {
if (!width) {
width = 0.5;
}
window.vuplex.postMessage({ type: 'highlightObjOutlineColor', name: name, r:r ,g:g, b:b, width:width});
}
/**
* 高亮目标3D对象并设置其整体颜色。
* 注:
* 1、需挂载“对象高亮”组件,确保激活“设置整体”字段,禁用“鼠标事件”字段
* 2、仅高亮设备整体,如需高亮设备外轮廓(边框),使用 highlightObjOutlineColor()。
* @param {String} name 对象名称
* @param {Number} r Red 0-255
* @param {Number} g Green 0-255
* @param {Number} b Blue 0-255
* @param {Boolean} isFlashing 是否闪烁,默认是
* @return {void}
*/
function highlightObjOverlayColor(name, r, g, b, isFlashing = true) {
window.vuplex.postMessage({ type: 'highlightObjOverlayColor', name: name, r:r ,g:g, b:b, isFlashing:isFlashing});
}
/**
* 清除目标 3D 对象高亮状态。
* 注:
* 1、需挂载“对象高亮”组件,确保禁用“鼠标事件”字段
* @param {String} name 对象名称
* @return {void}
*/
function clearObjHighlight(name) {
window.vuplex.postMessage({ type: 'clearObjHighlight', name: name});
}
/**
* 操作 3D 标签
* @param {String} name 3D标签名称
* @param {String} title 标题
* @param {String} url 图片 url 地址
* @return {void}
*/
function handle3DLabel(name, title, url) {
window.vuplex.postMessage({type: 'handle3DLabel', name: name, title: title, url: url});
}
/**
* 操作 3D 文本标签
* @param {String} name 3D 文本标签名称
* @param {String} title 标题
* @return {void}
*/
function handle3DTextLabel(name, title) {
window.vuplex.postMessage({type: 'handle3DTextLabel', name: name, title: title});
}
/**
* 操作 3D 图片标签
* @param {String} name 3D 图片标签名称
* @param {String} url 图片 url 地址
* @return {void}
*/
function handle3DImageLabel(name, url) {
window.vuplex.postMessage({type: 'handle3DImageLabel', name: name, url: url});
}
/**
* 控制 3D 对象坐标动画
* 支持三种补间动画:位置,旋转,比例
* @param {String} name 3D 对象名称
* @param {String} animationType 动画类型:位置,旋转,比例
* @param {Number} x
* @param {Number} y
* @param {Number} z 根据设置不同的动画类型对应3D对象位置/旋转/比例的x,y,z目标值
* @param {Number} duration 动画持续时长
* @return {void}
*/
function tweenObj(name, animationType, x, y, z, duration) {
window.vuplex.postMessage({
type: 'tweenObj',
name: name,
animationType: animationType,
x: x,
y: y,
z: z,
duration: duration
});
}
/**
* 加载 3D 场景
* @param {String} path 场景路径
* @return {void}
*/
function loadScene(path) {
window.vuplex.postMessage({type: 'loadScene', path: path});
}
/**
* 对象预警(高亮闪烁),控制 3D 对象开启/关闭预警
* @param {String} name 3D 对象名称
* @param {Boolean} isAlarm 是否对象预警
* @return {void}
*/
function objAlarm(name, isAlarm) {
window.vuplex.postMessage({type: 'objAlarm', name: name, isAlarm: isAlarm});
}
/**
* 对象显示/隐藏控制(适用于 3D 对象,粒子,水等等)
* @param {String} name 对象名称
* @param {Boolean} isOpen true:开启,false:关闭
* @return {void}
*/
function objActiveCtrl(name, isOpen) {
window.vuplex.postMessage({type: 'objActiveCtrl', name: name, isOpen: isOpen});
}
/**
* 控制电梯楼层
* @param {String} name 电梯对象名称
* @param {Number} targetFloor 要去的目标楼层,注意不能小于最低楼层,不能大于最高楼层
* @return {void}
*/
function goToFloor(name, targetFloor) {
window.vuplex.postMessage({type: 'goToFloor', name: name, targetFloor: targetFloor});
}
/**
* 获取后期预设列表。通过 sendPostProcessProfiles 监听。
* @return {void}
*/
function getPostProcessProfiles() {
window.vuplex.postMessage({type: 'getPostProcessProfiles'});
}
/**
* 获取天空盒列表。通过 sendSkyBoxs 监听。
* @return {void}
*/
function getSkyBoxs() {
window.vuplex.postMessage({type: 'getSkyBoxs'});
}
/**
* 设置指定后期预设
* @param {String} name 后期预设名称,可通过顶部工具栏 -> 编辑 -> 设置,或者 getPostProcessProfiles() 获取。
* @return {void}
*/
function setPostProcessProfile(name) {
window.vuplex.postMessage({type: 'setPostProcessProfile', name: name});
}
/**
* 设置指定天空盒
* @param {String} name 天空盒名称,可通过顶部工具栏 -> 编辑 -> 设置,或者 getSkyBoxs() 获取。
* @return {void}
*/
function setSkyBox(name) {
window.vuplex.postMessage({type: 'setSkyBox', name: name});
}
/**
* 重置第一人称角色控制器到初始位置
* 注:
* 1、如未找到第一人称角色控制器,则无效果。
* 2、初始位置:在编辑器中指定的最后位置。
* @return {void}
*/
function resetFirstCharacterTransform(){
window.vuplex.postMessage({type: 'resetFirstCharacterTransform'});
}
return {
enableCameraController: enableCameraController,
block3DRayCaster:block3DRayCaster,
openURL: openURL,
cameraMove: cameraMove,
changeColor: changeColor,
highlightObjOutlineColor: highlightObjOutlineColor,
highlightObjOverlayColor: highlightObjOverlayColor,
clearObjHighlight: clearObjHighlight,
handle3DLabel: handle3DLabel,
handle3DTextLabel: handle3DTextLabel,
handle3DImageLabel: handle3DImageLabel,
tweenObj: tweenObj,
loadScene: loadScene,
objAlarm: objAlarm,
objActiveCtrl: objActiveCtrl,
goToFloor: goToFloor,
getPostProcessProfiles: getPostProcessProfiles,
getSkyBoxs: getSkyBoxs,
setPostProcessProfile: setPostProcessProfile,
setSkyBox: setSkyBox,
resetFirstCharacterTransform: resetFirstCharacterTransform
};
})();
var TwinToH5 = (function () {
// 添加监听器
function addMessageListener() {
if (window.vuplex) {
addBaseMessageListener();
} else {
window.addEventListener('vuplexready', addBaseMessageListener);
}
}
// 移除监听器
function removeMessageListener() {
window.vuplex.removeEventListener('message', handleMessage);
//TODO Test
document.getElementById("label").innerHTML = '';
}
function addBaseMessageListener() {
window.vuplex.addEventListener('message', handleMessage);
}
function handleMessage(event) {
//TODO,处理 3D 发送过来的数据
// 注意:此数据是 string 类型,需先转化成 json
let json;
try {
json = JSON.parse(event.data);
} catch (error) {
console.error('Failed to parse JSON:', error);
return;
}
switch (json.type) {
case 'sendObjInfo':
document.getElementById("label").innerHTML = '当前对象的数据 : ' + event.data;
//...
break;
case 'sendPostProcessProfiles':
document.getElementById("label").innerHTML = '后期预设列表: ' + event.data;
//...
break;
case 'sendSkyBoxs':
document.getElementById("label").innerHTML = '天空盒列表: ' + event.data;
//...
break;
case 'sendObjScreenCoord_MouseStay':
document.getElementById("label").innerHTML = '对象屏幕坐标: ' + event.data;
//...
break;
}
}
return {
addMessageListener: addMessageListener,
removeMessageListener: removeMessageListener
};
})();
<button onclick="H5ToTwin.cameraMove('相机组1', 1)">相机组1-视角1</button>
<button onclick="H5ToTwin.changeColor('方块1', 0, 255, 0, 255)">方块1绿色化</button>
<button onclick="H5ToTwin.objActiveCtrl('Fire01', true)">激活火焰Fire01</button>
<button onclick="H5ToTwin.goToFloor('电梯1', 2)">去往电梯1的2楼</button>
3DsWorks 9.0 提供 Web 云推流解决方案,可以让用户在浏览器中使用 3DsWorks。按下列步骤启动云渲染服务:



在浏览器中输入 127.0.0.1:8586(也可以输入本机实际的 IP 地址),点击 Web 页面播放器上的播放按钮。


云渲染属于授权模块:学习版、教育版可试用,商业版 Plus 可永久使用。具体使用方法参考安装目录下的 WebServer 目录。
配置文件 config.xml 用于对软件的一些全局项进行配置,路径位于 \3DsWorks_Data\StreamingAssets\config.xml。
每次设置完成后必须重启软件才会生效。
目前有以下三种配置项:
作用:发布模式下进入编辑器环境的管理员密码,默认 000000。
<!--发布模式下进入编辑器环境的管理员密码(可通过编辑器中不同的播放模式设置是否需要密码)--> <password>000000</password>
可通过在编辑器中点击不同的播放模式,设置每次进入编辑器是否需要密码:

如设置了 releaseScenePath,并且 showEditorBtn 为 1,则进入编辑器时默认需要密码。
作用:第一次打开软件时默认加载的场景路径,例如 Scenes/test1。如为空则加载默认示例场景,默认为空。
<!--第一次打开软件时默认加载的场景路径,例如Scenes/test1。如为空则加载默认示例场景--> <releaseScenePath></releaseScenePath>
目前场景路径仅支持单工程。
工程存档保存在软件的相对路径中,比较方便的方法是在磁盘上查找:以 \3DsWorks_Data\StreamingAssets\DefaultProject\Assets 为根目录,场景文件为 .rtscene 后缀,取场景名称即可。

场景路径则为:Scenes/test1

场景路径则为:Scenes/test/hehe
作用:设置发布时右上角编辑器按钮是否显示。
1:显示编辑器按钮,可进入编辑器环境(默认)。0:隐藏编辑器按钮,无法进入编辑器环境。<!--设置发布时右上角编辑器按钮是否显示 “1”:显示编辑器按钮,可进入编辑器环境(默认)。 “0”:隐藏编辑器按钮,无法进入编辑器环境。 --> <showEditorBtn>1</showEditorBtn>
以下按版本倒序列出各版本的新增、修改与修复内容。
新增
新增
修复
新增
新增
新增
新增
enableCameraController 函数,可通过前端手动激活或禁用相机控制器。具体说明参考 \3DsWorks_Data\StreamingAssets\LocalPages\demo.html。修改
修复
新增
\3DsWorks_Data\StreamingAssets\Logo;修复
新增
新增
openURL 函数,用来处理网页中无法下载文件的问题。具体说明参考 \3DsWorks_Data\StreamingAssets\LocalPages\demo.html。修改
新增
修改
新增
新增
修改
新增
修改
新增
修改
修改
新增
\3DsWorks_Data\StreamingAssets\config.xml。修改
新增
修改
新增
修复
修改
修复
新增
修改
修改
修复
新增
修复
修改
修改
修改
新增
修复
新增
修改
新增
修复
新增
修改
新增
修改
修复
新增
修复
新增
修改
新增
修改
修复
新增
修改
修复
修改
新增
修改
新增
修改
新增
初版
3DsWorks 版权所有。本手册中的文字、界面截图与示例代码仅用于说明 3DsWorks 软件的使用方法,未经许可不得用于其他用途。
Copyright © 2013–2026 3DsWorks. All rights reserved.
| 官方网站 | http://www.3DsWorks.com |
|---|---|
| 适用版本 | 3DsWorks 9.0(CS 架构) |
| 文档版本 | 2026/11/16 |