如何配置项目定制的一键安装步骤

功能概述

注意：此步骤中的配置一般由项目接口人完成，其他普通用户可忽略这一步。

PCG流程中需要各种软件、配置设置对于第一次接触Pangu的用户来说比较复杂，所以Pangu设计了一个一键安装配置，通过简单的设置来帮助用户配置PCG开发环境。

这一步的目的是基于项目具体使用的场景、环境对项目的一键安装步骤进行定制化，因为每个项目的存储库不同、资源放置路径等都不一样，这一步配置后，其他用户直接直接执行一键安装即可快速完成Pangu相关环境的配置。

如果您想直接使用Kaitian资源，那么也请直接跳过这一步。直接启动Pangu工程，进入Pangu界面，进行一键安装即可。

配置文件介绍

一键安装的配置涉及三个文档：
xxxSetupConfig.json：用于配置一键安装需要执行的指令，xxx一般为项目代码或名称。

SetupConfig.json文件分为5个部分：
- 变量（下图红色部分）：变量的值可以通过ui界面中的选择来修改
- AdminCmds（下图黄色部分）：一般在这里配置一键安装中需要管理员权限的指令
- UserCmds（下图绿色部分）：一般在这里配置一键安装中不需要管理员权限的指令
- CustomCmds（下图紫色部分）：一般在这里配置不在一键安装入口执行的指令，比如Pangu窗口右上角的ArtUpdate按钮被点击后执行的指令
- UserOverridableList（下图白色部分）：当变量的名字出现在此部分时，用户在界面上的选择会被保存下来，在您下一次打开一键安装界面时将会保留上一次一键安装的选择

（一键安装的配置文件）

xxxSetupUI.json：用于配置一键安装界面的UI控件，xxx一般为项目代码或名称，一般与xxxSetupConfig.json中的xxx保持一致。如果项目无修改UI控件的需求，可不配置该文件，此时会使用默认的SetupUI。

我们在二进制包体中提供了KaiTianSetupConfig.json和KaiTianSetupUI.json文件，这两份配置文件中几乎包含了最全的一键安装配置，您可以将这两份文件复制为副本，作为项目的一键安装配置文件的参考，然后按需修改内容即可。

ini配置文件：如果项目需要自己组装文件夹结构，比如从A地址拉取文件然后链接到B地址，那么可以在项目文件夹下新增ini配置文件实现。我们在KaiTian项目的文件夹下准备好了KaiTian需要的各种组装文件夹组装的ini配置文件，您可以将该文件复制为一份副本，作为项目组装的ini配置文件的参考，然后按需修改其中的模块。一般项目需要组装的文件夹复杂度远远小于KaiTian，只需要删除大部分其中的条目，以及替换仓库地址即可。

由于一键安装步骤繁多，且项目定制化程度较高，不同项目需要的一键安装步骤大不相同，所以以下以一些比较经典、常见的步骤作为示例

操作步骤

新建SetupConfig.json文件

如果需要定制项目的一键安装配置，则此步骤为必需。
所在目录：Plugins\Pangu\Content\Python\Plugins\PanguSetup\ClientConfig\ActionConfig\

命名：项目名称+SetupConfig.json

有了这个文件后，Pangu的一键安装界面上的Project则会多一个对应的下拉选项，比如新增一个TestPanguSetupConfig.json文件，则Pangu的一键安装界面上的Project下拉选项会多一个TestPangu。 avatar

请记住这里的项目名称，在后续的设置中，都将用这个项目名称字符串来进行对应。在一键安装的流程中使用Project来代指这个字符串。

修改变量值

在配置一键安装的配置中，您可以根据项目需要修改变量值。如果项目不需要某些变量也无需删除，可以随便赋予一个默认值，也可以直接填空字符串""，比如



{
	"UserName": "",
}

一键安装中有部分变量在代码中有其他用途，或者会被系统运行自动写入，请不要用他们来存项目自定义的值。这部分变量的说明请参考一键安装指令大全的特殊变量说明部分

新增变量

变量一般在下文的指令中被引用，如果在指令中需要引用其他变量，请自行定义。
比如，在指令中需要引用TestCustomParam这个变量，则在SetupConfig.json文件中新增一个变量TestCustomParam，并设置其值。



{
	"UserName": "",
	"Branch": "main_dever",
	"Job": "",
	"Project": "KaiTian",
    "TestCustomParam": "test"
}

在指令模块中引用该变量，引用变量的语法为：{变量名}



{
    "AdminCmds":
	[
		"ensure_dir --condition \"{SourceControlSoftware}==\"SVN\"\" \"{KaitianRootPath}/{TestCustomParam}\" OccupiedBackupPaths",
    ]
}

修改指令

可以根据项目的需求，删除掉一些不必要的指令，以及添加一些新的指令。需要注意这个配置文件中的所有指令必须为Pangu一键安装提供的指令。一键安装支持的指令可参考Pangu一键安装指令大全的当前版本支持的指令大全。

指令由指令名、执行条件、执行参数三个部分组成，条件和参数都可以使用变量进行值的替换，如下：



"AdminCmds":
	[
		"change_ue_settings {PanguProjectSettingsName} PerforcePort --condition {SourceControlSoftware}==\"Perforce\" {PerforcePort}",
	]

change_ue_settings为指令名
--condition {SourceControlSoftware}==“Perforce” {PerforcePort}为执行条件
{PanguProjectSettingsName} PerforcePort为执行参数

其他可选步骤

组装项目的文件夹结构

这个功能是提供给项目去自由组装项目需要的资源进Pangu的工程，所有需要从远端拉取文件的操作都需要在这里配置
这里需要注意的是，目前使用Pangu需要依赖部分Kaitian的资源，所以在这一步，可以用Kaitian项目下的某个ini作为模板，然后在此模板上添加项目所需的拉取文件的步骤。

1.从Kaitian复制一份ini到项目目录下

Kaitian项目的ini文件目录：Plugins\Pangu\Content\Python\Plugins\CodeUnifier\config\Kaitian，该目录下有多个ini，是基于不同使用场景来组织的，可以选择最符合项目的使用情况的ini作为模板。
项目目录：Plugins\Pangu\Content\Python\Plugins\CodeUnifier\config\项目名称，如果没有对应目录可以自己创建，这里的项目名称需要和新建SetupConfig.json文件中一致

有了这个文件后，Pangu的一键安装界面上的job选到这个项目名称的时候就会使用这个ini配置文件中的配置来拉取组装用户本地文件。

2.ini文件展示

以下图的ini文件举例，以下两个部分合并后为一份完整的ini文件
以下为变量区域，目前展示的变量基本不用修改，支持新增变量，变量可以在Part区域引用，语法为：{变量名}



[Env]
git_cmd=git
svn_cmd=svn
rsync_cmd=rsync
p4_cmd=p4
; 环境设定
; python运行路径为 UnrealEngine/Engine/Win64 文件夹下，这个路径应该用不到
root = ..
; 测试用的Key
; 运行脚本时实际的panguforunreal项目路径 由一键配置读取写入
pangu_root = H:/PanguForUnreal
; P4仓库地址 项目统一填写配置
p4_server = ssl:dep229-gz-commit02.perforce.netease.com:1666
; P4使用者 一键配置时选择填入
p4_user = huangchenfei
; P4使用的工作区名 一键安装时选择填入
p4_workspace = huangchenfei_GIH-D-30771_5276
; P4工作区的根目录，由上面p4_workspace可以读取到，一键配置时会写入，写出为了展示目录组成环境
p4_workspace_root = e:\huangchenfei_GIH-D-30771_5276
; 用来给一键配置显示这套配置叫什么的
setup_config_name=hou_dever_p4
; 用来给一键配置显示解释的字段
setup_description=P4本地测试:Ue5引擎,hou_dever,本地ArtData和Pcgmaps
; 用来给一键配置ui过滤的字段 支持简单数据类型
setup_show_filter=Branch:hou_dever,SourceControlSoftware:Perforce

Part区域定义了需要拉取的所有任务，举例：
kaitian_artdata为任务名
等号后面的p4指的是拉取指定Perforce版本库的资产
//depot/KaiTian/hou_dever/ArtData/...为trunk仓库地址
//depot/KaiTian/hou_dever/ArtData/...为其他分支仓库地址
depot/KaiTian/hou_dever/ArtData为p4版本库在用户本地的WorkSpace目录
switch_local_root:p4_workspace_root是指令：切换到p4本地WorkSpace的目录
link_to_sub_local:PcgContent:{pangu_root}/Content/PcgContent是指令：通过p4拉取的资产需要链接的目标目录



[Part]
; 例子名，及其使用的部件版本管理类型
;ExampleSvn   =svn_raw
;             svn://svn-dh3d.gz.netease.com/svn/trunk/Projects/game/data/           ; trunk会在之代码当成分支名拼
;             svn://svn-dh3d.gz.netease.com/svn/trunk/Projects/game/data/branches
;             Projects/Game/Scripts/data
;             switch_local_root:abc
;ExampleGit   =git
;             ssh://git@git-internal.nie.netease.com:32200/dh3d/program/infos.git
;             ssh://git@git-internal.nie.netease.com:32200/dh3d/program/infos.git   ; git的两个url设置成一样的
;             Projects/Game/Scripts/infos
;             set_default_branch: main                                              ; 修改自己的default branch，用于某些git默认是main
;ExampleRsyc  =rsync
;             10.212.18.196::dh3d_cicd_read/package_server
;             10.212.18.196::dh3d_cicd_read/package_server                          ; rsync的两个url设置成一样的
;             Projects/Game/Scripts/infos
;             set_default_branch: main                                              ; 修改自己的default branch，用于某些git默认是main
kaitian_artdata     =p4
             //depot/KaiTian/hou_dever/ArtData/...
             //depot/KaiTian/hou_dever/ArtData/...
             depot/KaiTian/hou_dever/ArtData
             switch_local_root:p4_workspace_root
             link_to_sub_local:PcgContent:{pangu_root}/Content/PcgContent
kaitian_houtools     =p4
             //depot/KaiTian/hou_dever/HouTools...
             //depot/KaiTian/hou_dever/HouTools...
             depot/KaiTian/hou_dever/HouTools
             switch_local_root:p4_workspace_root
kaitian_pcgmaps     =p4
             //depot/KaiTian/hou_dever/PcgMaps...
             //depot/KaiTian/hou_dever/PcgMaps...
             depot/KaiTian/hou_dever/PcgMaps
             switch_local_root:p4_workspace_root


[PartSymbol]
all=kaitian_artdata,kaitian_houtools,kaitian_pcgmaps
art_force_update=kaitian_artdata,kaitian_houtools

[Command]

3.新增变量

项目根据仓库需求自行在[Env]区域新增 字符串 变量。这些变量都可以在Part区域中使用。比如新增一个名为svn_username的变量


[env]
...
svn_username = xiaoming

4.修改变量

以下列举必须进行修改才能使用的变量。

setup_config_name：用来给一键安装显示这套配置叫什么的，全局唯一，不能和其他配置重复


setup_config_name=hou_dever_w_local

setup_description：用来给一键安装显示解释的字段


setup_description=开发者推荐使用:Ue5引擎,hou_dever,使用svn仓库,使用W盘,本地Pcgmaps

setup_show_filter：项目目录下有多个ini文件时，使用这里的Filter筛选出符合条件的ini文件
字段名为SetupConfig.json中定义的变量，如CurUnrealEngineMajorVersion需要是SetupConfig.json文件中已经定义的变量
- 多个字段用英文逗号分隔
- 字段名和字段值用英文冒号分隔
- 多个字段名之间的过滤关系为And


setup_show_filter=CurUnrealEngineMajorVersion:5,Branch:hou_dever,UseCloudCook:False,UseCloudTools:True,SourceControlSoftware:SVN

5.使用变量

在Part区域中的其他分支仓库地址区域可以使用branch变量，branch变量无需在ini文件中定义，其取值为用户从一键安装界面选择的分支名。



https://svn-pangu.gz.netease.com/svn/KaiTian/KaiTianFrame/tags/{branch}/KaiTianShare/trunk/Projects/KaiTian/ArtData/ArtHDAs

在Part区域中的版本库本地目录区域和指令区域可以引用[Env]区域中定义的变量，引用变量的语法为：{变量名}



link_to_local:{kaitian_user_real_root}/hou_dever/ArtData/ArtHDAs/DM145

6.配置PartSymbol部分

all：必须配置，且需要包含在Part部分定义的所有任务

art_force_update：如果SetupConfig.json的CustomCmds中存在ArtDataHouToolsUpdate模块，那么该模块中的指令"force_update_kaitian_files {PanguVersion} art_force_update",会用到art_force_update的值。