通用交互表现开发应知应会

0.业务范围说明

业务代码

1.实验通用表现组件
2 实验通用交互组件

资源类

1 通用资源
2 化学现象资源
3 化学药品资源

依赖关系说明


1.组件仓库说明

http://git.sdp.nd/component-dll/vlab-generalability.git

如果没有权限的话可以找黄金民(171517)申请开下权限

2.wiki地址

新能力开发完成后请在下面的wiki地址中新增接口使用说明
wiki地址

3.前置知识

3.1 代码工程结构

工程名 说明
ASEVLabCommonAbility 包含所有通用能力组件开放给LUA的接口函数,称为AC(AgentComponent)接口工程
VLabGeneralAbility 实验通用表现组件的实现代码
VLabInteractiveAbility 实验交互组件的核心实现代码
Fenmo 粉末插件
VLiquidVolume 液体插件

3.2 ActionSystem介绍

1)ActionSystem主要由能力平台提供的C#语言和LUA语言互操作的组件,具体见ActionSystem程序集和能力平台的说明;
2)它在C#层和LUA层分别定义了一套规范,只要遵守它的规范就能很容易实现互相调用,比如暴露给LUA的类必现继承自AgentComponentBase, 暴露的函数必须加上AgentAttriInFunction标签,具体要按照流程跑一遍才能理解。
3)C#层与LUA互相调用的性能不好,特别是传复杂对象的时候,所以一般接口上都尽量使用基本类型
4)应用层的框架已经处理了ActionSystem的初始化,播放器在加载元器件的时候,会在模型资源的根节点上添加ActionSystem相关的组件,LUA代码一般会传相对路径给组件,方便组件在对应的节点上添加Unity相关的组件。

4.如何新增一个通用能力

4.1 表现组件

非化学交互结构

通能能力组件从结构上可以分为三层,如上图所示
1.AC接口层(命名以AgentComponent_开头),LUA可调用的接口函数
2.适配层(以C命名开头),连接接口层和封装核心代码,负责核心脚本实例的创建以及多例的实现。
3.底层,组件核心逻辑代码的实现

AC接口层
  在AgentComponent目录下新建一个接口文件,命名格式为AgentComponent_VLabXXXX(XXXX为组件的名称)
  例如 :AgentComponent_VLabCircleTrackCtrl.cs文件包含了外部所有可调用的函数接口。
  AC接口层主要实现两个功能
  1.通过依赖注入获得指定的对象。通过继承AgentComponentBase来实现。然后调用方法 this.GetAction<ICircleTrackCtrlAction>();
  2.通过反射实现LUA对C#的调用。在方法头部加上[AgentAttriInFunction(LuaAccess = LUAACCESSTYPE.LuaCanAccess, FuncNetPro = FUNCNETPRO.Normal)]

适配层
  接口头文件的创建,在Interface目录下的新增接口头文件。命名格式为I+组件的名称+Action
  中间层主体文件的创建,在Implement目录下添加中间层文件,命名格式一般为C+组件的名称+Action
  适配层继承自CommonAbilityBase类,CommonAbilityBase类主要提供了两个接口,
  Bind(ulong entityID) 根据LUA传递过来的entityID数字绑定元器件
  GameObject GO { get; set; }  返回绑定元器件的根节点对象

底层
  VLabGeneralAbility工程
  通用能力组件的核心代码放在Scripts目录下。

4.2 交互组件

基于化学交互框架添加新能力需要依赖LUA中的InteractAbilityConfig.json
help01

实验交互框架可以分为23大部分

1.移动过程中的事件
2.移动结束后的事件
3.实时监测

PreDetectedState.cs中负责处理移动中需要进行的表现,例如移动中对齐物体或者高亮。
假设我们要在移动过程中添加一个虚影显示的功能。

在PreDetectedState.cs 的void OnAdd(Context context, out object data)函数中添加如下代码:
help02

然后在InteractAbilityConfig.json中”onPreDetect”字段添加ghost动作。

TryInteractActionTask.cs负责处理移动结束后需要进行的表现,例如结束移动时触发拼接或者倾倒。
假设要在移动结束时添加一个物体拼接的动作。

在TryInteractActionTask.cs的void DoTask(IActor actor, Context context)添加拼接初始化代码:

然后在InteractAbilityConfig.json中”onDetect”字段添加joint动作。

5.开发注意事项

5.1 如何加载资源

开发一些组件的时候如果有需要依赖图片或者粒子特效等unity资源,可以调用一套已经封装好的资源加载接口。可以自动适配本地和AB包两种加载。

可以通过ResourceHelper.Load<T>("CameraEffect/BrokenBumpMap")加载AB包中的资源
T可以为任何UnityEngine.Object对象
"CameraEffect/BrokenBumpMap" 自己定义的字符串
例如我要加载AB包中的一个图片资源就可以使用如下代码ResourceHelper.Load<Material>("Material/TrackMat/TrackFullLine0")

如何将资源放入AB包?
1.进入工程vlab-editor\ElementResource\GenernalResource\BuildConfig目录下
Config.csv中配置 字符串和资源路径的映射,如下所示
CameraEffect/BrokenBumpMap,Assets/Resources/ElementResource/GenernalResource/Texture/bumpMap.png
CameraEffect/BrokenBumpMap为程序代码中配置的识别字段
Assets/Resources/ElementResource/GenernalResource/Texture/bumpMap.png 为资源的存放路径

2.在ResourcesConfig.json中配置资源路径
"Assets/Resources/ElementResource/GenernalResource/Texture/bumpMap.png"
然后将对应的资源放入上面路径中。

如果需要在发包下测试的话,将GenernalResource打包上传至平台即可。

5.2 如何验证开发的组件

要验证所开发的组件功能和表现,通常有以下两种方法,一般5.2.1方法用于快速调试和验证组件底层MonoBehaviour脚本的功能和表现,在完成组件核心脚本即可进行,5.2.2方法用于完整的从调用方调用组件接口进行验证组件功能,在把组件底层脚本封装到最后的AC接口后可以进行。

5.2.1 直接在场景中元器件对象上AddComponent挂载组件核心脚本验证功能和表现

运行编辑器,在拖出的元器件对象上直接添加组件底层MonoBehaviour脚本,相比5.2.2介绍的方法,该方法能较为快速直接的验证脚本功能和表现,但是不能验证外部调用组件接口是否正确,且由于是在元器件对象上直接挂载脚本,需要初始化的部分参数或许需要暴露在Unity Inspector面板上

5.2.2 LUA脚本中配置组件信息,调用组件接口验证功能和表现

下面将以AgentComponent_VLabDrawingBoard画线组件为例,介绍如何在LUA中配置组件、对组件初始化和调用组件实例的接口

1.在AgentClassConfig.xml中按照格式配置对应组件
  PS:AgentClassConfig.xml位于ElementResource/LabElementLua/XXXX_PC/resource目录下,其中XXXX为某一元器件名,白纸元器件名为BaiZhiElement
  白纸元器件的组件配置表如下图

2.在元器件LUA代码中初始化组件
  在Lua中初始化组件,第一步要调用组件的Bind(ulong entityId)接口,告诉组件所绑定的元器件实体ID,如果组件需要额外的参数(例如资源路径、Unity对象路径等等)进行初始化,则需要提供一个接口用于初始化,例如画线组件中的接口Init(string path)
  白纸元器件LUA脚本初始化画线组件和画线组件初始化的接口如下图所示

3.调用组件接口
  上述步骤完成了对画线组件的初始化,接下来代码中添加调用画线组件的画线接口,然后运行实验编辑器,拖出白纸和铅笔元器件,拖动铅笔在白纸上移动,即可验证画线组件的画线功能

5.3 Textmeshpro字体包生成

1.选择字体的字库。
  如果字库中没有所需要的字符,则需要重新编辑生成字库。
  在线字库编辑器 http://fontstore.baidu.com/static/editor/index.html
  另一个字库 https://www.jianshu.com/p/6fb74839a2c1

[
点击打开按钮加载字库,点击新字形创建一个空的框框,在打开个一个字库将所需的字符复制过来。然后点击上面的ttf保存按钮即可。

2.字库编辑好后,选择textmeshpro的字体文件。textmeshpro会根据这个字体文件去查找字库去生成字体包。
  虚拟实验室中使用的字体文件一般为LabText.txt,路径是在vlab-editor-4test\U3DProject\Assets\Resources\Font

[

 http://cheonhyeong.com/Simplified/download.html 这里可以下载到unicode全部的字符。选择天珩全字库(TH-Tshyn),解压后如下所示

[

点击window => TextMeshPro => Font Asset Creator进入Textmeshpro的字库生成界面
3.textmeshpro参数设置
 (1)选择字库源,这里选择微软雅黑
 (2)选择字体大小,一般设定为23
 (3)选择字体包大小。这里设置为4096x4096
 (4)选择字库需要包含的字体文本

[

 生成完毕后点击save textmeshpro font asset保存文件,如果有缺失的字符会显示出来。

[
路径保存在
vlab-editor-4test\U3DProject\Assets\TextMesh Pro\Resources\Fonts & Materials
覆盖LiberationSans SDF.asset

5.4 如何处理第三方插件

在开发通用表现组件时,有时会遇到依赖第三方dll的情况,此时应该按照以下流程处理。

0.名词解释
  编辑器工程:开发联调阶段使用的工程,dll更新依赖于本地上传,不用来发包,只用来产出稳定的dll,最终会发布到管理平台,
  仓库地址:http://git.sdp.nd/vlab-projects/vlab-editor-4test
  管理平台:发布稳定组件的平台,地址:
  https://vlab-developer.sdp.101.com/main.html#/component-list
  PC播放器工程:发布稳定客户端使用的工程,dll更新依赖于从管理平台下载,
  仓库地址:http://git.sdp.nd/app-u3d/3d_labplayer
  VR播放器工程**:测试VR平台下表现的工程,,dll更新依赖于本地上传
  仓库地址:http://git.sdp.nd/app-u3d/vr-lab-player,
  VR环境搭建文档:https://www.showdoc.com.cn/VLab?page_id=4664464604883283
1.Demo阶段
  在Demo阶段,若引用了第三方dll,应该先验证Demo工程能否打包,将编辑器专属的dll单独放在Editor文件夹。
2.组件化阶段
  组件化编写代码时,只把打包时需要用到的dll放到下图所示Libs目录,并在VLabGeneralAbility工程下添加上述dll的引用,编译成功后,将Libs目录提交推送。


3. 联调测试阶段
  代码组件化完成后,在和LUA同学联调之前,要把Libs目录中的dll文件复制到图中所示plugins目录,若无报错,则将plugins目录上传推送到develop分支。接下来LUA端就可以正常动用接口,Libs目录中的dll文件有变动,则此处要同步变动。
  WithoutMultiLanguage分支也做同样处理。

4. 合并发布阶段
  代码合并进release分支并通过测试后,需要将稳定的dll包放到管理平台,此时要联系洪彬(140913)同学,指明自己新增的Libs目录中的dll文件,提醒其打包时不要遗漏。洪彬(140913)同学会进行PC播放器工程和VR播放器工程的dll更新。

6.如何发包

6.1 通用能力代码发包

1.编译dll
  通用能力组件编译后dll位于 \GeneralAbility\Output路径下。结构如下图所示:

2.dll数字签名
  (1)登录签名服务器192.168.251.40
     账号 administrator
     密码 Icricr1
  (2)进入服务器发包路径D:\signSolf\FaBao
  (3)清空目录下的旧dll,将编译过后的通用能力dll拷贝进去
  (4)在上一层目录中找到 签名发包.bat并运行。然后将签名过后的dll拷贝到本地。

签名后的dll如下所示:

3.进入管理平台
  https://vlab-developer.sdp.101.com/main.html#/component-list
  点击分组,选择通用表现组件

  选择最新的版本,下载组件包。下载后的组件包一般是类似VModuleCode_2.1.4_191204002.cmp这样的。

  用winRAR等工具解压下载文件。下载文件的目录结构如下所示:

  (1)修改Meta.json中的"Version"字段到最新版本(在上个版本末位+1)
  (2)将签名后的dll覆盖到Logic目录下
  (3)修改组件包的名称,确认后缀名为.cmp
  (4)在管理平台新增版本,并将组件包上传。至此通用能力的发包完成。
  PS:上传至管理平台的状态一般切为提测

6.2 GenernalResource资源发包