器材开发指南

1. 器材概览


  • 虚拟实验室中的器材,比如灯泡烧杯等都属于一个器材,或者叫做元器件
  • 目前器材分为两大学科:物理化学,还有一类比较特殊的器材是化学药品,未来还会有生物学科。
  • 根据使用场景的不同,器材可能会有不同的表现或者交互方式等。目前主要有PCVR两个场景,未来还会有手机端的应用。
  • 器材的使用方式是:通过编辑器编辑相关器材的颗粒文件,并通过播放器播放相应的文件来使用其中的器材
  • 器材的主要开发环境是编辑器的develop分支,编辑器存在两种加载器材的方式:本地模式和线上模式
    本地模式:该模式下编辑器通过加载预制体的方式加载创建器材,这种方式下加载的器材代码位于VlabEquip/LabElementLua,器材预制体位于ElementResource/LabElementPrefabs
    线上模式:该模式下编辑器通过加载AB包的方式加载创建器材,这种方式下编辑器会使用从实验开发管理工具平台(管理平台)下载的器材AB包,AB包位于vlab-editor\U3DProject\LabObjPackage\NewModule下。
    一般器材的开发过程中是使用本地模式进行开发,调试。直到开发完成时,将器材打包上传到管理平台后,在提测之前,通过线上模式进行自测。
    切换方式:在编辑器的Launch场景中,通过勾选use Local Resource 来开启本地模式

    2. 开发环境搭建


  • 必要软件安装

    1. 安装unity
      目前使用的版本号是[2019.4.16f1][],请使用对应版本的unity进行开发,否则可能导致无法预料的问题,在虚拟实验室的网盘中下载,地址: X:\FTP共享\软件下载\Unity\Unity-2019.4.16f1。
    2. 安装git
      项目工程放在GitLab仓库中,需要使用git拉取,下载一个最新版本安装即可。
    3. 安装一个图形化git工具
      这里推荐两个软件
      TortoiseGit操作更加接近原生git,性能较好。
      SourceTree界面简洁,操作简单,清晰的版本、分支视图。非常适合git新手使用。
      选择其中一个安装即可,也可以两个配合使用。
    4. 安装一个lua代码编辑器
      这里推荐使用vscode作为代码编辑器使用
  • 开发必知网址

    1. 化学元器件策划案总地址 账号密码为自己的99u账号密码
    2. 物理有两个策划案地址
      一个在svn上,账号密码同上
      一个在OA上,账号:guest 密码:123456
        器材管理->器材【所有】->右上角搜索->输入器材名称->查询
      
    3. 项目组件wiki:C#层提供的大部分通用能力组件都会在这个网址里有相应的组件接口说明
    4. 联合交互组件说明文档 由于这个组件涉及能力较多,配置复杂,因此特地列出来,该组件包括了常用的拼接,对齐等交互。
    5. 实验开发管理平台,开发完成的器材都需要上传到该平台,走提测发布流程。相关使用指南请参考实验开发管理工具使用指南—器材相关分页
    6. 禅道,QA测试时提bug的地址,如果器材出现bug请及时解决哦
    7. 实验开发流程管理系统(OA),实验开发流程管理系统,统筹管理项目的开发流程,器材同学主要关心其中的器材提测功能。
    8. 项目工程主要由以下几个git仓库构成
      vlab-editor: 编辑器工程地址,器材主要在该工程下开发
      vlab-equip:器材脚本资源存放仓库,是器材开发的主要仓库,配合下面一个存放模型资源的仓库使用
      vlab-elements:器材模型资源存放仓库。
      vr-lab-player:VR播放器工程仓库,开发vr器材时主要在该工程下,工程搭建请参考VR环境搭建
      vlab-player: PC播放器工程仓库,主要用于排查器材在播放器中使用时出现的问题,不做为主要开发环境。
      还有几个组件引擎的仓库,由于平时使用较少,这里不做说明,有兴趣的同学可以自行查看vlab-editor的子模块

3. 器材制作流程详解


虚拟实验室的器材是由以下几个部分组成:

  1. 一个主要逻辑lua脚本
  2. n个器材相关配置文件
  3. 一个unity器材预制体
  4. 器材图标文件

详细的制作流程将会在器材制作流程分页中做详细的说明。

4. 器材代码详解,lua框架介绍


器材的功能,通用逻辑,交互等有一大部分是在器材的基类中实现的。
器材通过继承相应的基类来拥有相应的功能。
器材的99%的功能都是通过编写代码实现,这里不仅仅包括了lua编写的功能,也包括了使用C#编写的组件所提供的更通用的功能。而lua与C#要能互相沟通调用,就离不开一个沟通的中间介质。在此部分我们会着重介绍器材的核心代码库,lua与C#的沟通桥梁--AgentSystem,以及整个器材运作的流程图。

请看器材代码详解分页

5. 基类代码开发使用须知—-gerrit接入


为了减少基类代码中可能出现的代码错误,故将器材基类单独出一个仓库【VLabLuaCodeBase】放在VLabEquip的子模块中,并接入gerrit代码评审,以下将说明如何进行基类代码开发以及提交
1. 到gerrit中获取工程地址
gerrit网址:http://gerrit.sdp.nd/
gerrit会为每个成员分配一个个人的工程地址,在Projects中可以选择VLabLuaCodeBase,可以查看自己的git地址
可以选择http或者ssh地址

2. 获取秘钥
使用http地址的话只要在My-Groups-HTTP Password中生成,获取对应的秘钥即可

如果是使用ssh地址,同样是在Groups中选择SSH Public Keys ,按照其中的说明文档进行配置即可
3. 切换本地VLabLuaCodeBase仓库的远程地址,并配置Commit-msg
gerrit需要配置commit-msg,这里你可以选择手动将VLabLuaCodeBase的远程地址替换为第一步中得到的地址,然后将VLabLuaCodeBase目录下的commit-msg文件放到.git\hooks文件夹下,注意该文件路径会因为子模块的嵌套而改变,.git文件夹只会在最外层的仓库才有,子模块的配置文件在.git\modules中。
也可以选择运行CodeBase目录下SwitchToGerrit自动完成上述两步操作。
4. 提交代码审核
目前只有提交develop分支需要走gerrit,日常在开发一个完整的功能时,建议自行创建一个新分支,等功能开发完时,再合并develop发起审核。
提交develop分支代码时,需要将提交的远端分支改成refs/for/develop,可以勾选【总是推送这个本地分支到选择的远端分支】,下次推送时不需重复填写。

5. 审核不通过时,修改代码重新提交审核
第一种方案:
提交代码后可以在gerrit上看到对应的提交记录

当代码评审反馈了结果(通常指评审不通过,需要修正),需要使用git fetch获取本次评审的代码(如下),在此基础上重新修改后提交。注意提交(git commit)时,使用amend参数,这样本次提交的内容将被gerrit当做一个新的patch set来处理。

  // fetch and checkout the change
  // (checkout command copied from change screen)
  $ git fetch https://gerrithost/myProject refs/changes/74/67374/2 && git checkout FETCH_HEAD

  // rework the change
  $ git add <path-of-reworked-file>
  ...

  // amend commit
  $ git commit --amend

  // push patch set
  $ git push origin HEAD:refs/for/master
例:在change页面可以通过download获取要修改的地址


在change页面可以在看reviewer已经对代码进行了备注和修改

重新修改文件(此例中为test.txt),并提交

第二种方案
如果基于当前提交的内容,则可以勾选Amend Last Commit

最后通过审核提交到develop分支

**6. 解决冲突:

解决冲突之前通过变基方式拉取到最新代码

获取到最新代码后开始

  • 1 复制Cherry Pick
  • 2 在VLabLuaCodeBase中 右键选择Git Bash Here;右键选择past,将刚刚复制的命令粘贴进去,然后回车。


  • 3.点击git提交解决冲突

  • 4.最后把冲突内容删掉,并提交推送

6. 开发规范


为了让器材更利于维护,减少器材开发产生的bug,因此总结如下开发规范,请同学们开发器材时务必遵守,如果有好的建议,也可以在下面补充:

  • 器材配置规范
    1. 开发时预制体中的各个节点,请按规范进行分类

      器材编码:JiQiPingElement

      模型总节点:GameObjScale(所有的物体都需要放到该节点下,才能被组件组件识别)

      器材实体模型节点:ModelPaths(在场景中看到的物体,可以交互的碰撞体等,均放在该节点下)
      器材虚拟逻辑节点:LogicPoints(该节点用于放置器材的一些接触或者交互需要的触发器)

    2. 一个gameObject上不应该同时有collider和trigger,如非必要请分别放置在两个物体上。
    3. 在创建器材命名器材编码时请遵循以下规则进行命名,以免出现问题:
      1. 编码应有器材的名称的拼音组成,最好能根据编码即可知道是哪个器材
      2. 器材编码的总字符数不得超过32个。
      3. 器材编码应由以字母开头,不使用特殊字符。
    4. 器材预制体的根节点和GameObjScale节点的Transform需要保证Position和Rotation都为(0,0,0),scale为(1,1,1)。如果需要修改模型的大小,只能改变其子节点。
  • 器材资源存放规范

    1. 所有器材相关的资源都要放在ElementResource子仓库下面,不能放到editor工程目录下,以下路径说明使用ElementResource下的相对路径。
    2. 器材的预制体放在“LabElementPrefabs\<对应学科分类>”文件夹下面。
    3. —TODO
  • 编码规范

    1. 变量命名规范

    2. lua表使用规范
      lua的table在使用时应尽量在构造表时即将要存入表中的值一并写入。eg:

    3. 器材提测规范
      器材的每次提测需要满足一下提测标准:
      1.单次提测的内容至少包含一个完整的功能实现
      2.如果是解决bug,需要确保本次提测已包括所有bug(依赖器材解决的bug)的解决
      3.颗粒需求需要尽快解决的bug可单独提测
      4.确保提测内容所依赖的内容(基类,引擎,播放器,其他器材的相关功能)已经同步提测之后才可提测
      QA发现不符合标准时会拒绝测试

7. 辅助参考文档


3D能力平台虚拟实验室元器件制作详解
虚拟实验室器材开发手册(旧版)
待增加。。。。