Scriptable Build Pipeline - 2018.2 入门指南

                   相关文章暂时还是太少了~  

        转载自：https://docs.google.com/document/d/1uuiEDV7WqpHEylzE4GQwOztCttrwPu6ak0kfELz6ilc/edit#

https://docs.unity3d.com/2018.2/Documentation/ScriptReference/Build.Player.PlayerBuildInterface.html   

https://docs.unity3d.com/Packages/[email protected]/api/UnityEditor.Build.Pipeline.html   

Addressable资源系统的文档可以点击下面来查看：
 https://docs.unity3d.com/Packages/[email protected]/manual/index.html

==================================================  先个示例代码 =====================

Scriptable Build Pipeline 大多数都是使用 BuildTaskRunner，IBuildTask并IContextObject 类实现功能。

• IContextObject： 存储数据的接口。
• IBuildTask： 负责处理构建的接口。BuildTaskRunner按照他们在任务列表Run()中注册的顺序。要使用的数据会[InjectContext]自动注入现场。
• BuildTaskRunner：执行构建的类

下面的代码只是一个简单的代码，可以注册字母，获取注册的字母并显示它们。

先安装插件：

                    （看到很多文章 说路径在  项目的 Library/ PackageCache  路径下，  但是并没有这个路径呀~~）

或者这样单独添加也行 ： 

还要做一件事情：   做一下拷贝 （为什么要做这个拷贝？“我之前的文章   Unity3d 周分享 第x期 ，提到过，方便查看源码，  为了设断点调试   虽然一些反编译工具也可以做到， 但是 设断点查看它的内部执行过程这样做很方便~”  ）

  

在 Legacy Build Pipeline 中， 能看到   应该是Unity 5系列的 AB 构建流程 。 

还有  类 DefaultBuildTasks.cs  中

   Demo

using System.Collections.Generic;
using UnityEditor;
using UnityEngine;
using UnityEditor.Build.Pipeline.Interfaces;
using UnityEditor.Build.Pipeline;
using UnityEditor.Build.Pipeline.Injector;
using UnityEngine.Assertions;

public static class BuildTest
{
    // 菜单栏
    [MenuItem("Build/test build")]
    static void Build()
    {
        //注册上下文
        //此处注册的上下文用于Task
        BuildContext buildContext = new BuildContext();
        buildContext.SetContextObject(new MyContextData { message = "hoge" });

        //创建任务
        //任务使用的参数是从上下文中获取的。
        //任务注册顺序=任务执行顺序
        IList taskList = new List();
        taskList.Add(new DisplayNameTask());

        //实际执行该过程
        var result = BuildTasksRunner.Run(taskList, buildContext);
        Assert.AreEqual(ReturnCode.Success, result);
    }
}

//使用BuildTasksRunner注册的任务
class DisplayNameTask : IBuildTask
{
    //注入匹配接口的上下文
    // ContextUsage.In：使用从BuildContext注册的那个
    // ContextUsage.Out：注册在Run中创建的上下文
    [InjectContext(ContextUsage.In)]
    IMyContextData data = null;

    public int Version { get { return 1; } }

    public ReturnCode Run()
    {
        //仅显示字符的任务
        //实际上收集对象并更新/生成上下文
        Debug.Log(data.Name);
        return ReturnCode.Success;
    }
}

//这次使用的字符数据接口
//在DisplayNameTask上使用InjectContext
public interface IMyContextData : IContextObject
{
    string Name { get; }
}

//上下文数据的实体
public class MyContextData : IMyContextData
{
    public string message = null;
    public string Name => message;
}

 

 

======================================================

Note to readers: this content is for the Scriptable Build Pipeline package and will reside in the package documentation at https://docs.unity3d.com/Manual/PackagesList.html Documentation source will reside at https://gitlab.internal.unity3d.com/build-pipeline/AddressablesDemo/tree/master/AddressablesDemo/Packages/com.unity.scriptablebuildpipeline/Documentation Table of Contents (tableofcontents.md) Unity Scriptable Build Pipeline (index.md) Getting started with Scriptable Build Pipeline (gettingstarted.md) Terminology (terminology.md) Usage Examples (usageexamples.md) Upgrade Guide (upgradeguide.md)

Unity Scriptable Build Pipeline

The Scriptable Build Pipeline (SBP) package allows you to control how Unity builds content. The package moves the previously C++-only build pipeline code to a public C# package with a pre-defined build flow for building AssetBundles. The pre-defined AssetBundle build flow reduces build time, improves incremental build processing, and provides greater flexibility than before.

 

If you are moving from using BuildPipeline methods to the SBP, see the Usage Examples and Upgrade Guide.

 

Getting started with Scriptable Build Pipeline

Installing the Scriptable Build Pipeline (SBP) package

Requires Unity 2018.2 or later.

To install this package, follow the instructions in the Package Manager documentation.

To build AssetBundles, use the ContentPipeline.BuildAssetBundles() method. In its simplest form, you supply the following parameters:

 

• Build Parameters - An object that implements the IBuildParameters interface. The object specifies the BuildTarget, the BuildTargetGroup, the output path, and additional optional properties.

• The content to build - An object that implements the IBundleBuildContent interface. The object specifies the content to build (the assets) and its layout (what assets in which bundles.)

• A results object - An object that implements the IBundleBuildResults interface. The object receives the details of the built AssetBundles.

 

Note: The UnityEditor.Build.Pipeline namespace contains default implementations for all of the SBP required interfaces.  Implementation names mirror the interfaces, with the leading ‘I’ removed. For example, the IBuildParameters interface is implemented as BuildParameters.

 

To quickly switch to building AssetBundles with SBP, use the CompatibilityBuildPipeline.BuildAssetBundles() method as a drop in replacement for existing code. This method has the nearly identical parameters as the BuildPipeline.BuildAssetBundles() method. For additional information, see the Usage Examples and Upgrade Guide.

 

Terminology

Asset - A source file on disk, typically located in the Project’s Assets folder. This file is imported to a game-ready representation of your Asset internally which can contain multiple Objects (SubAssets.)

 

Object (SubAsset) - A single Unity serializable unit. Also known as a SubAsset. An imported Asset is made up of one or more Objects.

 

Includes - The unique set of Objects from which an Asset is constructed.

 

References - The unique set of Objects that are needed (referenced) by the Includes of an Asset, but not included in the Asset.

 

Usage Examples

Basic Example

This example assumes that your are already familiar with the basic usage of the two BuildPipeline.BuildAssetBundles methods and want to switch to using Scriptable Build Pipeline with as little effort  as possible.

 

The following code example shows how AssetBundles are currently built:

 

using System.IO;

using UnityEditor;

 

public static class BuildAssetBundlesExample

{

   public static bool BuildAssetBundles(string outputPath, bool forceRebuild, bool useChunkBasedCompression, BuildTarget buildTarget)

   {

       var options = BuildAssetBundleOptions.None;

       if (useChunkBasedCompression)

           options |= BuildAssetBundleOptions.ChunkBasedCompression;

 

       if (forceRebuild)

           options |= BuildAssetBundleOptions.ForceRebuildAssetBundle;

 

       Directory.CreateDirectory(outputPath);

       var manifest = BuildPipeline.BuildAssetBundles(outputPath, options, buildTarget);

       return manifest != null;

   }

}

 

To update the previous code example to use SBP instead, replace the call to BuildPipeline.BuildAssetBundles with CompatibilityBuildPipeline.BuildAssetBundles as shown below:

 

using System.IO;

using UnityEditor;

using UnityEditor.Build.Pipeline;

 

public static class BuildAssetBundlesExample

{

   public static bool BuildAssetBundles(string outputPath, bool forceRebuild, bool useChunkBasedCompression, BuildTarget buildTarget)

   {

       var options = BuildAssetBundleOptions.None;

       if (useChunkBasedCompression)

           options |= BuildAssetBundleOptions.ChunkBasedCompression;

 

       if (forceRebuild)

           options |= BuildAssetBundleOptions.ForceRebuildAssetBundle;

 

       Directory.CreateDirectory(outputPath);

       var manifest = CompatibilityBuildPipeline.BuildAssetBundles(outputPath, options, buildTarget);

       return manifest != null;

   }

}

 

Notes: Some changes in the SBP building and loading process do not match the BuildPipeline behavior. For more information on these changes, see the Upgrade Guide.

 

Cache Server Integration Example

This following example shows how to share build artifacts between team members or multiple machines to achieve faster build times.

 

Requirements:

1. A separate Cache Server instance dedicated to build artifacts. It cannot be shared as an Asset Cache Server as data collisions will occur.

2. The build code must use the ContentPipeline.BuildAssetBundles method.

3. BundleBuildParameters.UseCache is set to true.

4. BundleBuildParameters.CacheServerHost and BundleBuildParameters.CacheServerPort are set to the cache server instance host or IP address and port respectively.

 

Example code:

 

using UnityEditor;

using UnityEditor.Build.Content;

using UnityEditor.Build.Pipeline;

using UnityEditor.Build.Pipeline.Interfaces;

 

public static class BuildAssetBundlesExample

{

   public static bool BuildAssetBundles(string outputPath, bool useChunkBasedCompression, BuildTarget buildTarget, BuildTargetGroup buildGroup)

   {

       var buildContent = new BundleBuildContent(ContentBuildInterface.GenerateAssetBundleBuilds());

       var buildParams = new BundleBuildParameters(buildTarget, buildGroup, outputPath);

       buildParams.UseCache = true;

       buildParams.CacheServerHost = "buildcache.unitygames.com";

       buildParams.CacheServerPort = 8126;

 

       if (useChunkBasedCompression)

           buildParams.BundleCompression = BuildCompression.DefaultLZ4;

 

       IBundleBuildResults results;

       ReturnCode exitCode = ContentPipeline.BuildAssetBundles(buildParams, buildContent, out results);

       return exitCode == ReturnCode.Success;

   }

}

 

Per-Bundle Compression Example

The following example shows how to build your AssetBundles using different compression levels for each AssetBundle.This is useful if you are planning on shipping part of your bundles as Lz4 or Uncompressed with Player and want to download the remainder as Lzma later.

 

The simplest implementation is to create a custom build parameters class that inherits from BundleBuildParameters and override the GetCompressionForIdentifier method. Then construct and pass this into the ContentPipeline.BuildAssetBundles method.

 

using UnityEditor;

using UnityEditor.Build.Content;

using UnityEditor.Build.Pipeline;

using UnityEditor.Build.Pipeline.Interfaces;

 

public static class BuildAssetBundlesExample

{

   class CustomBuildParameters : BundleBuildParameters

   {

       public Dictionary PerBundleCompression { get; set; }

 

       public CustomBuildParameters(BuildTarget target, BuildTargetGroup group, string outputFolder) : base(target, group, outputFolder)

       {

           PerBundleCompression = new Dictionary();

       }

 

       public new BuildCompression GetCompressionForIdentifier(string identifier)

       {

           BuildCompression value;

           if (PerBundleCompression.TryGetValue(identifier, out value))

               return value;

           return BundleCompression;

       }

   }

 

   public static bool BuildAssetBundles(string outputPath, bool useChunkBasedCompression, BuildTarget buildTarget, BuildTargetGroup buildGroup)

   {

       var buildContent = new BundleBuildContent(ContentBuildInterface.GenerateAssetBundleBuilds());

       var buildParams = new CustomBuildParameters(buildTarget, buildGroup, outputPath);

       buildParams.PerBundleCompression.Add("Bundle1", BuildCompression.DefaultUncompressed);

       buildParams.PerBundleCompression.Add("Bundle2", BuildCompression.DefaultLZMA);

 

       if (m_Settings.compressionType == CompressionType.None)

           buildParams.BundleCompression = BuildCompression.DefaultUncompressed;

       else if (m_Settings.compressionType == CompressionType.Lzma)

           buildParams.BundleCompression = BuildCompression.DefaultLZMA;

       else if (m_Settings.compressionType == CompressionType.Lz4 || m_Settings.compressionType == CompressionType.Lz4HC)

           buildParams.BundleCompression = BuildCompression.DefaultLZ4;

 

       IBundleBuildResults results;

       ReturnCode exitCode = ContentPipeline.BuildAssetBundles(buildParams, buildContent, out results);

       return exitCode == ReturnCode.Success;

   }

}

Load By Filename Example

The following example shows how to use the CompatibilityBuildPipeline methods to load by a filename instead of the full path.

 

The example uses the ContentBuildInterface.GenerateAssetBundleBuilds() method to get the set of bundles and assets to build, then modifies addressableNames field to set the loading path of the filename instead of the full path.

 

using System.IO;

using System.Linq;

using UnityEditor;

using UnityEditor.Build.Content;

using UnityEditor.Build.Pipeline;

 

public static class BuildAssetBundlesExample

{

   public static bool BuildAssetBundles(string outputPath, bool forceRebuild, bool useChunkBasedCompression, BuildTarget buildTarget)

   {

       var options = BuildAssetBundleOptions.None;

       if (useChunkBasedCompression)

           options |= BuildAssetBundleOptions.ChunkBasedCompression;

 

       if (forceRebuild)

           options |= BuildAssetBundleOptions.ForceRebuildAssetBundle;

 

       var bundles = ContentBuildInterface.GenerateAssetBundleBuilds();

       for (var i = 0; i < bundles.Length; i++)

           bundles[i].addressableNames = bundles[i].assetNames.Select(Path.GetFileNameWithoutExtension).ToArray();

 

       var manifest = CompatibilityBuildPipeline.BuildAssetBundles(m_Settings.outputPath, bundles, options, m_Settings.buildTarget);

       return manifest != null;

   }

}

 

Custom Build Task Example

 

// TODO: make code example

 

Assign Built-In Objects to Bundles Example

 

// TODO: Maybe this should just be built-in shader extraction?

 

Upgrade Guide

To build your AssetBundles with the SBP package, use the CompatibilityBuildPipeline.BuildAssetBundles method wherever you used the BuildPipeline.BuildAssetBundle method.

 

Note: Not all of the features that were supported previously are supported in SBP.

 

The following tables list the features of the CompatibilityBuildPipeline.BuildAssetBundles method in comparison to the BuildPipeline.BuildAssetBundle method.

 

Feature	Support	Notes
AssetBundles	Supported	SBP builds AssetBundles that are built nearly identically to the previous build pipeline. You load them in a similar manner to how you currently load AssetBundles.
Incremental Building	Supported	SBP implements this feature using the BuildCache.
Asset loading path	Behavior changed	AssetBundles built with BuildPipeline today support loading an Asset by full path (“Assets/ExampleFolder/Asset.prefab”) file name (“Asset”) or file name with extension (“Asset.prefab”). However AssetBundles built with SBP by default only support loading an Asset by full path (“Assets/ExampleFolder/Asset.prefab”). This is to avoid loading collision that can occur if two Assets in the same AssetBundle have the different full paths, but the same file name. To change this behavior, the loading path can be set using IBundleBuildContent.Addresses with the ContentPipeline API or AssetBundleBuild.addressableNames field. See Code Examples.
AssetBundle Manifest	Behavior changed	SBP implements replacement functionality using the new class name CompatibilityAssetBundleManifest. This has an identical API to the existing AssetBundleManifest class, and has an additional method to get the CRC value for a bundle which did not exist before.
AssetBundle Variants	Not supported	There is currently no replacement functionality for AssetBundle Variants.

 

BuildAssetBundleOptions Enum:

 

Value	Support	Notes
UncompressedAssetBundle	Supported	Identical to using BuildCompression.DefaultUncompressed with the new API.
ChunkBasedCompression	Supported	Identical to using BuildCompression.DefaultLZ4 with the new API. Note: This has always been LZ4HC in the Editor, and LZ4 if it was recompressed at Runtime.
DisableWriteTypeTree	Supported	Identical to using ContentBuildFlags.DisableWriteTypeTree with the new API.
DeterministicAssetBundle	Supported	This is enabled by default, and it can’t be disabled. SBP builds deterministically.
ForceRebuildAssetBundle	Supported	Identical to using IBuildParameters.UseCache = false; with the new API.
AppendHashToAssetBundleName	Supported	Identical to using IBundleBuildParameters.AppendHash = true; with the new API.
DisableLoadAssetByFileName	Always enabled	This is enabled by default, and can’t be disabled. SBP is strict about the rule: “what you pass in is exactly what you get out”. If you pass in “My/Example1/Example2/Asset.asset” as the file name to use to load the Asset, you must use that identifier exactly, including the correct upper and lower case, and all punctuation.
DisableLoadAssetByFileNameWithExtension	Always enabled	See above details on DisableLoadAssetByFileName.
IgnoreTypeTreeChanges	Not supported	The incremental build system used this value to prevent rebuilding AssetBundles when an Asset's serialization layout changed, but the data for the Asset itself did not change. SBP currently rebuilds if there are any changes.
StrictMode	Not supported	The SBP is stricter about properly building AssetBundles and knowing when builds fail.
DryRunBuild	Not supported	SBP works fundamentally differently. It is faster to do a full build to determine if anything has changed.