旋转与拖动组件

最新引擎依赖版本:2.19.5+

已知问题:

  • pad下,禁用交互ui仍然会显示,【2.19.0】修复
  • vr下,直线拖动存在问题,【2.18.0】修复
  • ChangeTrackInfo接口失效,【2.19.5】修复

新功能:

  • 多轴拖动,预计【2.18.0】
  • 组合器材拖动,预计【2.19.0】
  • UI 2.0,预计【2.28.0】

拖动旋转组件(AgentComponent_VLabSlideRotateCtrl)

Example

-- 配置track信息(详见【0、一些参数】)
local trackInfo = {
    TrackType = "CircleTrack",
    TrackInfo = {
        --(以下5个字段可以删除,表示使用默认值)
        Range = Vector2(-0.52, 0.52),   -- 旋转范围,弧度制
        -- tip: 绕y轴旋转,可设置:Axis=Vector3.up, InitDirection = Vector3.forward
        -- tip: 绕z轴旋转,可设置:Axis=Vector3.forward, InitDirection = Vector3.right
        -- tip: 绕x轴旋转,可设置:Axis=Vector3.right, InitDirection = Vector3.up
        Axis = Vector3.up,              -- 旋转轴(相对参考系的本地坐标)
        InitDirection = Vector3.left,   -- 起始方向,起始方向处的旋转角度为0,旋转角度的正负判定,使用左手法则
        Radius = 0.2,                   -- 轨道半径,与旋转中心到旋转节点的距离一致(与UI大小相关,保证与实际大小一致)
        Thickness = 0.005               -- 轨道的厚度,与旋转轴方向上的宽度对应
    },
    OperationMode = "Drag",             -- 操作方式:Drag、Rotation、Rotation_Pointer、Rotation_Entirety
    AuxiliaryUi = {},                   -- 辅助UI(可选字段)
    DebugMode = "vr"                    -- 【正式环境记住去除该字段】调试模式(可显示不同版本的UI). 可传入参数:vr、pad、windows
}

-- 初始化(详见【1、初始化】)
local id = self.VLabSlideRotateCtrl:Init(SwitchSPSTAgent.childrenModelPath["zadao"], trackInfo)

-- 添加旋转节点(详见【7、添加需要旋转或者拖动的节点】)ps:这两行代码不是必须的,可以根据查询的数据,自己实现旋转与拖动
local excutor = self.VLabInteractiveNodeCtrl:InitRotationNode(SwitchSPSTAgent.childrenModelPath["zadao"])
self.VLabSlideRotateCtrl:AddNode(id, excutor)

-- 添加回调函数(详见【4、注册回调】)
self.VLabSlideRotateCtrl:RegisterValueChangeCallBack(id, self.ValueChange)
self.VLabSlideRotateCtrl:RegisterBeginSlideCallBack(id, self.BeginSlide)
self.VLabSlideRotateCtrl:RegisterSlidingCallBack(id, self.Sliding)
self.VLabSlideRotateCtrl:RegisterEndSlideCallBack(id, self.EndSlide)

-- 改变track信息(详见【2、参数设置】)
trackInfo["TrackInfo"]["InitDirection"] = Vector3.right;
self.VLabSlideRotateCtrl:ChangeTrackInfo(id, trackInfo)

-- 代码控制拖动(详见【3、代码控制拖动】)
self.VLabSlideRotateCtrl:Slide(id, -0.1)
self.VLabSlideRotateCtrl:SlideTo(id, -0.1)

-- 查询拖动的相关信息(详见【5、数据查询】)
pt("progress", self.VLabSlideRotateCtrl:QueryData(id, "progress"))
pt("ProgressNormalize", self.VLabSlideRotateCtrl:QueryData(id, "ProgressNormalize"))

-- 禁用【6、禁用与启用】
self.VLabSlideRotateCtrl:SetActive(id, false)

-- UI【8、UI相关】
self.VLabSlideRotateCtrl:ChangeLabelContent(id, true, "151")

-- 调试相关(详见【00、调试相关】)

0、一些参数

TrackInfo

轨道信息(LuaTable)

TrackType

  • CircleTrack
  • StraightTrack
  • MultiaxisTrack

TrackInfo

  • CircleTrack
属性 类型 说明
Axis Vector3 旋转轴(相对参考坐标系的值)
InitDirection Vector3 用于计算旋转角度(不与旋转轴同向)
Radius float 轨道半径
Range Vector2 范围(弧度制、Vector2.x < Vector2.y、默认上限为浮点型最大、最小值)
Thickness float 旋转面厚度
  • StraightTrack
属性 类型 说明
Track Vector3 轨道方向
Range Vector2 范围(Vector2.x < Vector2.y)
  • MultiaxisTrack
属性 类型 说明
AxisList Vector3[] 每个轴方向
RangeList Vector2[] 每个轴范围(Vector2.x < Vector2.y)

OperationMode

AuxiliaryUi

辅助UI

属性 类型 说明
LabelOffset Vector3 标签偏移(拖动适用)
IsShowLabel bool 是否显示标签
Trajectory Vector3 轨迹方向(弧形拖动适用)
IsLabelReverseProgress bool 标签百分比数值是否显示为反向(100% - n%)数值,默认false(直线拖动标签适用)
HighlightInteractiveArea string[] 【pad】配置交互高亮区域路径。如果这个参数不设置,使用默认规则。若配置了路径则高亮该路径下的mesh,并且点击高亮区域会出现预交互的黄色圆点(节点下必须有trigger)。

Example

-- StraightTrack
local trackInfo = {
    TrackType = "StraightTrack",
    TrackInfo = {
        Range = Vector2(-0.52, 0.52),
        Track = Vector3.right,
    },
    OperationMode = "Drag"
}

-- CircleTrack(拖动)
local trackInfo = {
    TrackType = "CircleTrack",
    TrackInfo = {
        Range = Vector2(-0.52, 0.52),
        Axis = Vector3.up,
        InitDirection = Vector3.left,
        Radius = 0.2,
        Thickness = 0.005
    },
    OperationMode = "Drag"
}

-- CircleTrack(旋转)
local trackInfo = {
    TrackType = "CircleTrack",
    TrackInfo = {
        Range = Vector2(-0.52, 0.52),
        Axis = Vector3.up,
        InitDirection = Vector3.left,
        Radius = 0.2,
        Thickness = 0.005
    },
    OperationMode = "Rotation"
}

--- MultiaxisTrack(多轴拖动)
local trackInfo = {
    TrackType = "MultiaxisTrack",
    TrackInfo = {
        AxisList = {
            Vector3.up,
            Vector3.forward,
            Vector3.back,
            Vector3.down
        },
        RangeList = {
            Vector2(0, 0.1),
            Vector2(0, 0.1),
            Vector2(0, 0.1),
            Vector2(0, 0.1)
        }
    },
    OperationMode = "Drag"
}

00、调试相关

旋转轴信息(CircleTrack)

  • 黄色圆圈表示旋转的环形轨道,黄色竖线为轨道厚度,黑色的线表示旋转范围,蓝色的线表示开始旋转方向,绿色的线表示旋转轴
  • 旋转的方向使用左手定则判断。也可根据下图中的红线和蓝线判断,从蓝线旋转到红线为正方向

俯视图

左视图

1、初始化

选择以下其中一个初始化即可。注意:参考系应当保持相对静止,即不应该对参考系及其父节点进行旋转等操作【LocalRotation的值不变】。如有特殊需求,可以考虑使用以下第三个初始化接口。

int Init(string trigger, LuaTable trackInfo)

简要说明

拖动组件初始化(自动生成一个与trigger节点具有相同位置信息的节点,作为参考坐标系)

参数

参数名 类型 说明
trigger string 触发拖动节点路径及需拖动的节点路径
trackInfo LuaTable 轨道信息

返回值

类型 说明
int 组件ID

int Init(string trigger, string referenceCoordinateSystem, LuaTable trackInfo)

简要说明

拖动组件初始化(需指定参考坐标系节点)

参数

参数名 类型 说明
trigger string 触发拖动节点路径
referenceCoordinateSystem string 参考坐标系节点路径(nil表示元器件根节点)
trackInfo LuaTable 轨道信息

返回值

类型 说明
int 组件ID

int Init(string trigger, string referencePosition, string referenceRotation, string referenceScale, LuaTable trackInfo)

简要说明

拖动组件初始化(可单独设置参考坐标系的位置、旋转、缩放),大部分情况用以上2个接口即可,当对元器件根节点进行旋转操作时,使用该接口

参数

参数名 类型 说明
trigger string 触发拖动节点路径及需拖动的节点路径
referencePosition string 位置参考节点(””(没空格)表示根节点,nil表示参考世界坐标)
referenceRotation string 旋转参考节点(””(没空格)表示根节点,nil表示参考世界坐标)
referenceScale string 缩放参考节点(””(没空格)表示根节点,nil表示参考世界坐标)
trackInfo LuaTable 轨道信息

返回值

类型 说明
int 组件ID

int Init(string trigger, int entityId, string referenceCoordinateSystem, LuaTable trackInfo)

简要说明

组件初始化,用于组合器材

参数

参数名 类型 说明
trigger string 触发拖动节点路径及需拖动的节点路径
entityId int 器材id
referenceCoordinateSystem string 参考系相对路径
trackInfo LuaTable 轨道信息

返回值

类型 说明
int 组件ID

2、参数设置

void ChangeTrackInfo(int id, LuaTable trackInfo)

简要说明

设置轨道信息

参数

参数名 类型 说明
id int 组件ID
trackInfo LuaTable 轨道信息

3、代码控制拖动

void Slide(int id, float increment)

简要说明

增量拖动,原先基础上拖动

参数

参数名 类型 说明
id int 组件ID
increment float 增量

void SlideTo(int id, float target)

简要说明

拖动到某个位置

参数

参数名 类型 说明
id int 组件ID
target float 目标位置

4、注册回调

void RegisterValueChangeCallBack(int id, LuaFunction callback)

简要说明

值改变回调(在旋转、拖动过程中,或者调用Slide、SlideTo函数会触发回调)
tip:在该回调中需谨慎使用Slide、SlideTo函数,注意判断中断条件,避免死循环

参数

参数名 类型 说明
id int 组件ID
callback LuaFunction 回调

void RegisterSlidingCallBack(int id, LuaFunction callback)

简要说明

旋转、拖动中回调(仅在旋转、拖动过程中触发回调,调用Slide、SlideTo函数不会触发回调)

参数

参数名 类型 说明
id int 组件ID
callback LuaFunction 回调

void RegisterEndSlideCallBack(int id, LuaFunction callback)

简要说明

旋转、拖动结束

参数

参数名 类型 说明
id int 组件ID
callback LuaFunction 回调

void RegisterBeginSlideCallBack(int id, LuaFunction callback)

简要说明

旋转、拖动开始

参数

参数名 类型 说明
id int 组件ID
callback LuaFunction 回调

5、数据查询

object QueryData(int id, string key)

简要说明

查询旋转、拖动相关数据

参数

参数名 类型 说明
id int 组件ID
key string 数据名

返回值

类型 说明
object 数据

key

increment           // 拖动增量(float)
progress            // 拖动的进度(float)
progressnormalize   // 拖动的进度(归一化)(float)
position            // 被拖动物体的虚拟位置(世界坐标)(Vector3)
axisindex           // 当前所在轴(多轴拖动使用)

6、禁用与启用

void SetActive(int id, bool b)

简要说明

查询拖动相关数据

参数

参数名 类型 说明
id int 组件ID
b bool 是否启用

7、为某个节点添加旋转或者拖动的操作

void AddNode(int id, IInteractiveExecutor executor)

简要说明

添加需要执行交互结果的节点

参数

参数名 类型 说明
id int 组件ID
executor IInteractiveExecutor 交互执行节点

IInteractiveExecutor

8、UI相关

void ChangeLabelContent(int id, bool b, string s)

简要说明

修改标签内容

参数

参数名 类型 说明
id int 组件ID
b bool 是否变更默认标签内容
s string 内容

9、组件销毁

void DestroyComponent(int id)

简要说明

销毁某个交互