DTS二次开发文档

Class: CustomObject

CustomObject

CustomObject类，提供用户自定义对象相关的操作
一般通过api.customObject调用其方法

<protected> new CustomObject()

See:

Extends

Methods

add(data, fn)

添加一个或多个CustomObject对象

路径参数assetPath获取方法如下动图：

Parameters:
Name Type Description
data object | array

数据结构，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) CustomObject对象的ID

  • groupId (string) 可选，Group分组

  • userData (string) 可选，用户自定义数据

  • pakFilePath (string) pak文件路径，资源引入说明

  • assetPath (string) 蓝图Actor在UE工程的资源引用目录（相对路径），注意：模型必须是蓝图Actor类，即在使用UE打包pak文件时此自定义对象在UE工程内的相对路径

  • range (array) 可视范围: [近裁距离, 远裁距离]，默认值: [0, 10000]

  • location (array) 模型位置坐标：[X,Y,Z]，取值示例，数组元素类型：(number)，取值范围：[任意数值]

  • coordinateType (number) 坐标系类型，取值范围：0为Projection类型，1为WGS84类型，2为火星坐标系(GCJ02)，3为百度坐标系(BD09)，默认值：0

  • rotation (array) 世界坐标系旋转：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：[任意数值]

  • localRotation (array) 模型自身旋转：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：[任意数值]

  • isEffectRotation (boolean) 模型是否开启旋转效果，注意：支持startMove()和moveTo()方法调用时生效

  • scale (array) 模型缩放：[X,Y,Z]，数组元素类型：(number)，取值范围：[任意正整数]

  • smoothMotion (number) 模型移动动画效果，1: 平滑移动，0: 跳跃移动

  • supportAttach (boolean) 是否支持贴画贴合，默认值：true

  • visible (boolean) 可选，设置自定义对象加载后是否显示，默认：true
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

addByTileLayer(data, fn)

把TileLayer图层中包含的一个或多个(Actor)模型复制为一个CustomObject对象

Parameters:
Name Type Description
data object | array

数据结构，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) CustomObject对象的ID

  • tileLayerId (string) TileLayer图层的ID

  • objectId (string | array) TileLayer图层中包含的待复制的模型(Actor)的ObjectId，同时也支持数组类型参数即把多个actor复制为一个customObject

  • location (array) 位置坐标：[X,Y,Z]，取值示例，数组元素类型：(number)，取值范围：[任意数值]

  • coordinateType (number) 坐标系类型，取值：0为Projection类型，1为WGS84类型，默认值：0

  • rotation (array) 旋转：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：[任意数值]

  • scale (array) 缩放：[X,Y,Z]，数组元素类型：(number)，取值范围：[任意正整数]

  • smoothMotion (number) 1: 平滑插值，0: 跳跃
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

callBPFunction(id, functionName, paramType, paramValue, parameters, fn)

已过时方法 推荐使用同名的批量调用方法

Parameters:
Name Type Description
id sting

CustomObject对象的ID
functionName string

函数名
paramType BPFuncParamType

传入单个参数，参数类型
paramValue any

传入单个参数，参数值
parameters array

传入多个参数，可选参数，数组类型，注意：传入多参数的顺序与类型务必与蓝图函数的参数顺序及其参数类型一致以保证执行结果符合预期。多个参数结构示例：[{"paramType":BPFuncParamType.String,"paramValue":"示例值"},{"paramType":BPFuncParamType.Bool,"paramValue":false},{"paramType":BPFuncParamType.Float,"paramValue":100.8}]
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Deprecated:
  • 已过时方法 推荐使用同名的批量调用方法

callBPFunction(data, fn)

批量方法，调用多个CustomObject对象的多个蓝图函数

Parameters:
Name Type Description
data object | array

数据结构，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) CustomObject对象的ID

  • functionName (string) 蓝图函数名

  • parameters (array) 蓝图函数包含的多个参数，可选参数，数组类型，注意：传入多参数的顺序与类型务必与蓝图函数的参数顺序及其参数类型一致以保证执行结果符合预期。多个参数结构示例：[{"paramType":BPFuncParamType.String,"paramValue":"示例值"},{"paramType":BPFuncParamType.Bool,"paramValue":false},{"paramType":BPFuncParamType.Float,"paramValue":100.8}]
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

clear(fn)

删除场景中所有的CustomObject

Parameters:
Name Type Description
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

delete(ids, fn)

删除一个或多个CustomObject对象

Parameters:
Name Type Description
ids string | array

要删除的CustomObject对象的ID或者ID数组（可以删除一个或者多个）
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

focus(ids, distance, flyTime, rotation, actionMode, fn)

自动定位到合适的观察距离

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者ID数组
distance number

可选参数，观察点距离目标点（被拍摄物体）的距离， 该值有以下3种情况：
1. 如果distance小于0，则是相机跟随移动模式
2. 如果distance等于0，则自动计算飞到合适的距离
3. 如果distance大于0，则是飞到指定距离的位置
flyTime number

可选参数，相机飞行的时间，取值范围：[0~任意正数]，单位：秒，默认值2秒
rotation array

可选参数，相机旋转的欧拉角：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：Pitch[-90~90] Yaw[-180~180] Roll[0]
actionMode ActionMode

可选参数，相机视角跟随模式枚举，注意：如果指定了rotation参数同时又指定了跟随枚举，则枚举值包含的相机欧拉角会覆盖rotation参数
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

get(ids, fn)

根据ID获取CustomObject的详细信息

Parameters:
Name Type Description
ids string | array

要获取的CustomObject对象ID或者ID数组（可以获取一个或者多个）
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Example
CustomObject的详细信息
[{
            "id":	"o1",
            "groupId":	"",
            "userdata":	"",
            "coordinatetype":	144,
            "tileLayerId":	"C:\\Users\\Administrator\\AppData\\Roaming\\Cloud\\SDK/media/pak/custom.pak",
            "objectId":	"/Game/Common/Asset_Bank/Mesh/Car/BP_Car_JiuHuChe",
            "location":	[495490.906250, 2490908.000000, 0.250098],
            "rotation":	[0.000000, 0.000000, 0.000000],
            "scale":	[1.000000, 1.000000, 1.000000]
        }]

getBPFunction(ids, fn)

根据自定义模型id查询自定义模型包含的蓝图函数信息

Parameters:
Name Type Description
ids string | array

customObject对象的id或id数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Example
返回结果示例：

[{
			"idOrPath":	"co1",
			"objectType":	"Actor",
			"params":	[{
					"functionName":	"特效",
					"functionParams":	[{
							"name":	"点特效样式",
							"type":	16,
							"defaultValue":	""
						}, {
							"name":	"线特效样式",
							"type":	16,
							"defaultValue":	""
						}]
				}, {
					"functionName":	"图标",
					"functionParams":	[{
							"name":	"图标样式",
							"type":	16,
							"defaultValue":	""
						}, {
							"name":	"图标背景",
							"type":	16,
							"defaultValue":	""
						}]
				}, {
					"functionName":	"动画",
					"functionParams":	[{
							"name":	"启用动画",
							"type":	0,
							"defaultValue":	0
						}, {
							"name":	"反向动画",
							"type":	0,
							"defaultValue":	0
						}]
				}, {
					"functionName":	"文字",
					"functionParams":	[{
							"name":	"文字内容",
							"type":	5,
							"defaultValue":	""
						}, {
							"name":	"文字大小",
							"type":	2,
							"defaultValue":	0
						}, {
							"name":	"背景颜色",
							"type":	6,
							"defaultValue":	[1.000000, 1.000000, 1.000000, 1.000000]
						}, {
							"name":	"背景倒角",
							"type":	3,
							"defaultValue":	0.000000
						}]
				}]
		}]

glow(data, fn)

闪烁

Parameters:
Name Type Description
data object | array

数据结构，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) CustomObject对象的ID

  • color (Color) 闪烁的颜色，支持四种格式，取值示例

  • duration (number) 闪烁持续时间，单位：秒，取值范围：[0.01~任意正数]

  • interval (number) 闪烁间隔时间，单位：秒，取值范围：[0.01~任意正数]，注意：间隔时间要小于持续闪烁时间
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

hide(ids, fn)

隐藏CustomObject

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者ID数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

hideByGroupId(groupId, fn)

根据分组ID隐藏自定义对象自定义对象

Parameters:
Name Type Description
groupId string

自定义对象创建时指定的分组ID
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

highlight(ids, fn)

高亮

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

moveTo(data, fn)

设置CustomObject对象运动（根据实时获取的GPS数据运动）

Parameters:
Name Type Description
data object | array

数据结构，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) CustomObject对象的ID

  • location (array) 位置坐标：[X,Y,Z]，取值示例，数组元素类型：(number)，取值范围：[任意数值]

  • rotation (array) 模型旋转：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：[任意数值]

  • smoothTime {number} 可选，平滑移动的插值时间，仅在smoothMotion=1即平滑移动下生效，注意：传值若为0则根据调用setLocation()接口的时间自动计算平滑移动的插值时间，默认值：1，单位：秒
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Example
请求参数结构示例

[{
     "id":"co1",
     "location":[2768.1734375,-2264.37375,6.5],
     "rotation":[0,90,0],
     "smoothTime":5
}]

overrideMaterial(data, fn)

替换CustomObject对象材质

Parameters:
Name Type Description
data object | array

替换CustomObject对象材质的详细信息，支持对象或数组，对于每一个对象支持以下属性：

  • id (string) 必选参数，CustomObject对象的ID

  • material (string) 可选参数，替换材质的文件路径，UE工程里材质文件对应资源的相对路径

  • scalarParameters (array) 可选参数，替换材质数值类型参数数组，包含name/value键值对的数组，其中value为数值

  • vectorParameters (array) 可选参数，替换材质矢量类型参数数组，包含name/value键值对的数组，其中value为数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Example
请求参数调用说明

构造请求参数须知：
1、如果不传入material参数，注意：不传入material参数的前提是已经用对应材质执行过当前overrideMaterial()方法，
   则需要传入材质对应的scalarParameters或vectorParameters参数，才会执行对应的材质参数进行替换；
2、如果只传入material参数，不传入对应的scalarParameters或vectorParameters参数，则会使用替换材质包含的默认材质参数；
3、如果同时传入material、scalarParameters、vectorParameters参数，则使用指定的材质和指定的材质参数进行材质替换

请求参数示例：
[{
     "id":"o1",
     "material":"/Game/Temp/MaterialA",
     "scalarParameters":[{"name":"scalar1","value":1.0},{"name":"scalar2","value":2.0}],
     "vectorParameters":[{"name":"vector1","value":[1,1,1,1]},{"name":"vector2","value":[2,2,2,2]}]
 },
{
     "id":"o2",
     "material":"/Game/Temp/MaterialB",
     "scalarParameters":[{"name":"Param1","value":3.0},{"name":"Param2","value":4.0}],
     "vectorParameters":[{"name":"Param3","value":[3,3,1,3]},{"name":"Param4","value":[4,2,2,2]}]
}]

restoreMaterial(ids, fn)

恢复指定自定义对象的材质

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setLocalRotation(id, newVal, fn)

设置模型自身的旋转

Parameters:
Name Type Description
id string

CustomObject对象的ID
newVal array

新值
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setLocation(id, newVal, smoothTime, fn)

设置位置

Parameters:
Name Type Description
id string

CustomObject对象的ID
newVal array

新的位置坐标：[X,Y,Z]，取值示例，数组元素类型：(number)，取值范围：[任意数值]
smoothTime number

可选，平滑移动的插值时间，仅在smoothMotion=1即平滑移动下生效，注意：传值若为0则根据调用setLocation()接口的时间自动计算平滑移动的插值时间，默认值：1，单位：秒
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setRotation(id, newVal, fn)

设置世界坐标系旋转

Parameters:
Name Type Description
id string

CustomObject对象的ID
newVal array

新值
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setScale(id, newVal, fn)

设置缩放

Parameters:
Name Type Description
id string

CustomObject对象的ID
newVal array

新值
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setSmoothMotion(id, newVal, fn)

设置是平滑插值还是跳跃， 0：跳跃， 1：平滑差值

Parameters:
Name Type Description
id string

CustomObject对象的ID
newVal number

新值
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setSmoothTime(id, smoothTime, fn)

设置平滑移动的插值时间

Parameters:
Name Type Description
id string

CustomObject对象的ID
smoothTime number

可选，平滑移动的插值时间，仅在smoothMotion=1即平滑移动下生效，注意：传值若为0则根据调用setLocation()接口的时间自动计算平滑移动的插值时间，默认值：1，单位：秒
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setTintColor(ids, newColor, fn)

设置模型叠加颜色

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者数组
newColor Color

新颜色值
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

setViewportVisible(id, vp, fn)

多视口状态下，设置CustomObject对象在各视口的可见性

Parameters:
Name Type Description
id string

CustomObject对象的ID
vp Viewport

视口掩码（Viewport位运算）
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

show(ids, fn)

显示CustomObject

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者ID数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

showByGroupId(groupId, fn)

根据分组ID显示自定义对象

Parameters:
Name Type Description
groupId string

自定义对象创建时指定的分组ID
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

startMove(id, coordinateType, pathPointArr, fn)

自定义对象按轨迹点移动

Parameters:
Name Type Description
id string

CustomObject对象的ID
coordinateType number

移动轨迹点的坐标系类型，取值范围：0为Projection类型，1为WGS84类型，2为火星坐标系(GCJ02)，3为百度坐标系(BD09)，默认值：0
pathPointArr array

移动轨迹点的坐标数组，其中每个数组元素支持以下属性：

  • time (number) 运动到达时间，单位：秒，注意：运动时间起点默认值必须为0

  • coordinate (array) 运动轨迹点坐标：[X,Y,Z]，取值示例，数组元素类型：(number)，取值范围：[任意数值]

  • rotation (array) 可选参数，每个时刻模型的运动姿态（欧拉角），不传则系统自动计算。格式：[Pitch,Yaw,Roll]，数组元素类型：(number)，取值范围：[任意数值]
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Example
请求参数pathDataArr示例说明

其中：time表示到达时间，即从当前轨迹点移动到下一个轨迹点花费时间为（time2-time1）。
[
            {"time":0,"coordinate":[ -15726.0537109375, 7340.0205078125, 0 ],"rotation": [0,90,0]},//注意：时间起点默认值必须为0
            {"time":0.5,"coordinate":[ -15700.7431640625, 7308.4287109375, 0 ],"rotation": [0,90,0]},
            {"time":1,"coordinate":[ -15682.779296875, 7345.14697265625, 0 ],"rotation": [0,90,0]},
            {"time":1.5,"coordinate":[ -15662.0478515625, 7312.79931640625, 0 ],"rotation": [0,90,0]}
        ]

stopGlow(ids, fn)

停止闪烁

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者数组
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

unhighlight(ids, fn)

取消高亮

Parameters:
Name Type Description
ids string | array

CustomObject对象的ID或者数组
该参数是可选的：
- 如果没有指定该参数，则会把场景中所有高亮的CustomObject对消高亮显示
- 如果指定了该参数，则只取消高亮指定的CustomObject对象。
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

update(data, fn)

修改一个或多个CustomObject对象

Parameters:
Name Type Description
data object | array

数据结构，请参考add方法
fn function

可选的回调函数，请参考二次开发：异步接口调用方式

updateBegin()

用于批量多次修改对象的属性

在开始修改之前调用updateBegin，然后可以多次调用setXXX方法，最后调用updateEnd提交修改更新数据
注意：
updateBegin不是异步调用，不需要await，也没有回调函数参数

Inherited From:
Overrides:
Example
fdapi.xxx.updateBegin();
for (let i = 0; i < 1000; i++) {
     fdapi.xxx.setColor(i, Color.Yellow);
} 
fdapi.xxx.updateEnd(function () {
     log('update finished!');
});

updateEnd(fn)

用于批量多次修改对象的属性，与updateBegin配套使用
注意：
updateEnd是异步调用，可以用回调函数也可以await

Parameters:
Name Type Description
fn function

可选的回调函数，请参考二次开发：异步接口调用方式
Inherited From:
Overrides: