cve-connector

v0.3.12

Published

7 days ago

UE Web 开发套件

0High
0Medium
0Low

sampung

TypeScript UE Web Pixel Streaming CVE

Connector 是用于 UE5 像素流播放的插件，包含 <cve-player> 组件，15 个 Controller ，点/线/面/体 4 种 Features ，及若干云渲染相关方法。

版本变更

[0.3.12] 2025-12-16

修复

指令：setResolution 只能设置 16 / 9 的BUG

[0.3.11] 2025-10-20

新增

方法: useWebBrowser，基于新版本 CVE 套件，Web 卡片的通讯方案
方法: useWebView2，基于新版本 CVE 套件，使用 UE 内嵌入 Web 开发模式的通讯方案
接口: RenderController，一维水动力可视化相关方法(创建、删除、更新、显示、隐藏)

修复

接口：GisController 相关变量类型校正，引用类型 => 基本类型

[0.3.9] 2025-06-25

新增

特性: Point 新增 WidgetZOrder 属性
特性: Feature 新增 EnableFlyTo 属性

[0.3.8] 2025-06-03

修复

BUG: startMultiView 方法传参修复
缺陷: 屏蔽高频事件控制台日志，包括 MouseClick、timechange、ViewDirectionChanged、Walk、WalkthroughPathPlayTime

[0.3.7] 2025-05-27

新增

接口: AnalysisController 新增同屏对比刷新视口 API

[0.3.6] 2025-05-26

新增

接口: AnalysisController 新增同屏对比相关 API

[0.3.5] 2025-04-24

新增

接口: 为 Point、Polyline、Polygon和 Polymesh 增加 update、addTag、removeTag 和 removeAllTags 方法
接口: ActorController 新增 addDecal、delete 方法
特性: 各类要素数据的公共属性新增 FlyToSpecifiedPosition、SpecifiedPosition
特性: Polygon 的 Solid01 样式新增 OutlineColor、OutlineWidth 属性，设置轮廓宽度及颜色
特性: Point 新增 WidgetPivot 属性
特性: Point 新增 Web01、Web02、Web03 三种样式

[0.3.1] 2025-02-18

新增

接口: 新增 listen/unlisten 方法添加/移除事件监听

[0.3.0] 2025-02-12

破坏性变更

属性: <cve-player> 的 match-maker-url 属性变更为 matchmaker-url
配置: 环境变量 MATCH_MAKER_URL 变更为 MATCHMAKER_URL
接口: 移除 PoinData/PolygonData/PolylineData/PolymeshData 等面向对象的接口
接口: ViewController 中 flyTo 新增 duration 参数，ViewSettings 中移除 Duration 参数

新增

属性: Polyline 增加 ODLine01 样式
接口: 新增 createPoinData/createPolygonData/createPolylineData/createPolymeshData 等数据构造方法

修改

属性: Polyline 的 FlowSpeed 的单位从米/秒改为厘米/秒
接口: 修复基于 WebUI 通讯的接口

使用

安装

npm install cve-connector@latest

yarn

yarn add cve-connector@latest

集成到 Web 页面

在 HTML 模板内使用之前，必须先引入！
<cve-player> 的高度不能为 0！
基于模板渲染设置事件回调函数时(以 Vue2 为例):

<cve-player
  application-name="HdecUnrealHaining"
  matchmaker-url="http://localhost:1234"
  @error="onError"
  @start="onStart"
>
</cve-player>

<script type="module">
import { defineContainer } from 'cve-connector'

defineContainer()

export default {
  methods: {
    onStart(evt) {
      console.warn('start ===> ', evt.detail)
    },
    onError(evt) {
      console.error('error ===> ', evt.message)
    },
  }
}
</script>

不基于前端框架的集成示例

<!-- HTML Template -->
<cve-player
  application-name="HdecUnrealHaining"
  matchmaker-url="http://localhost:1234"
>
</cve-player>

<script type="module">
import { defineContainer } from 'cve-connector'

defineContainer((player) => {
  player.addEventListener('start', (evt) => {
    console.warn('start ===> ', evt.detail)
  })
  player.addEventListener('error', (evt) => {
    console.error('error ===> ', evt.message)
  })
})
</script>

属性

<cve-player
  application-name="HdecUnrealPinglu"
  aspect-ratio="auto"
  matchmaker-url="http://39.170.3.124:80/"
  volume="0.3"
>
</cve-player>

application-name

必要属性
UE 应用名称，联系 UE 研发人员确认
无默认值

aspect-ratio

可选属性
云渲染视口纵横比例
设置 aspect-ratio 非 auto 时，height 和 width 比例应一致或不设置
示例: 'auto', '16 / 9', '4 / 3'
默认值: 'auto'
补充三种使用情况说明
1、不设置height、width、aspect-ratio
2、设置height、width，但不设置 aspect-ratio
3、不设置height、width，设置 aspect-ratio

matchmaker-url

可选属性
云渲染源地址，协议://主机:端口/路径
无默认值

signaling-url

可选属性
信令服务地址，协议://主机:端口/路径
无默认值

volume

可选属性
UE 音量
默认值: 0.3

事件

CvePlayer 扩展了 HTMLELment，有更多的事件回调。

| Event | Description | | ------- | ------------------ | | command | Web 发送指令到 UE | | error | 云渲染异常 | | message | UE 传递消息到 Web | | start | 云渲染开始 | | stop | 云渲染结束 |

全局环境下，有且仅有一个 player 元素，请导入后使用；
player 可能为空(尚未初始化)，请注意校验；

export class CvePlayer extends HTMLELment {
  oncommand?: (evt: CustomEvent<UIDescriptor>) => void
  onerror?: (evt: ErrorEvent) => void
  onmessage?: (evt: CustomEvent<UIDescriptor>) => void
  onstart?: (evt: CustomEvent<number>) => void
  onstop?: (evt: CustomEvent<string>) => void
}
export let player: CvePlayer | undefined

云渲染控制

connect2Matchmaker

import { connect2Matchmaker } from 'cve-connector'
// 运行云渲染程序，使用绑定的源地址和应用名称
connect2Matchmaker()

connect2Signaling

import { connect2Signaling } from 'cve-connector'
// 输入像素流实例地址，重新渲染
connect2Signaling('http://localhost:8081')

defineContainer

import { defineContainer } from 'cve-connector'
// 云渲染插件初始化后，立即执行回调函数
defineContainer(async () => {
  if (!player) {
    return
  }

  player.onstart = () => {
    const reference: CVE.GeoReference = {
      IsOriginLocationInProjectedCRS: true,
      OriginCenter: [116, 39, 100],
    }
    GisController.config(reference)
  }
})

disconnect

import { disconnect } from 'cve-connector'
// 停止渲染
disconnect()

listen

import { listen } from 'cve-connector'
// 监听鼠标点击事件
listen('mouseclick', function(e) {
  console.log(e)
})

requestInstance

import { requestInstance } from 'cve-connector'
// 获取云渲染实例
requestInstance('http://127.0.0.1:8080', 'HdecUnrealDemo')

unlisten

import { unlisten } from 'cve-connector'
// 取消监听鼠标点击事件
unlisten('mouseclick', function(e) {
  console.log(e)
})

useWebBrowser

import { useWebBrowser } from 'cve-connector'
// 基于新版本 CVE 套件，Web 卡片的通讯方案
useWebBrowser()

useWebView2

import { useWebView2 } from 'cve-connector'
// 基于新版本 CVE 套件，使用 UE 内嵌入 Web 开发模式的通讯方案
useWebView2()

补充说明

关于 Controller 和 Feature 的内容，请查看 cve-connector 插件 /docs 目录下相关文档。