Skip to content

Commit

Permalink
Merge pull request cocos#2822 from yanOO1497/382_builder
Browse files Browse the repository at this point in the history
update build docs for 3.8.2
  • Loading branch information
MrKylinGithub authored Nov 30, 2023
2 parents 1bbe6ed + cf97a8a commit b01b4f2
Show file tree
Hide file tree
Showing 10 changed files with 379 additions and 7 deletions.
7 changes: 5 additions & 2 deletions en/asset/bundle.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
Starting with v2.4, Creator officially supports **Asset Bundle**. The Asset Bundle is a modular resource tool that allows developers to divide the resources such as textures, scripts, scenes, etc. into different Asset Bundles according to the project requirements. Then, as the game runs, load different Asset Bundles as needed to minimize the number of resources to be loaded at startup. thus reducing the time required for the first download and loading of the game.

The Asset Bundle can be placed in different places as needed, such as on a remote server, locally, or in a subpackage of a mini game platform.
The Asset Bundle can be placed in different places as needed, such as on a remote server, locally, or in a subpackage of a mini game platform.

## The built-in Asset Bundle

Expand Down Expand Up @@ -408,6 +408,9 @@ After clicking the **Build** button, it can be canceled by clicking on the **Can

This feature is designed for big projects or some time-consuming bundles. Developers can build these bundles separately to reduce the build time.

### Bundle Build via Command Line

Please refer to [Executing Independent Release Bundle in Command Line](./../editor/publish/publish-in-command-line.md) for details.

## FAQ

Expand All @@ -429,7 +432,7 @@ This feature is designed for big projects or some time-consuming bundles. Develo
**A**: Absolutely. In fact, as of v2.4, the packaged project is entirely based on the Asset Bundle, and the `settings.json` no longer stores any configuration information related to the resource, all configuration information are stored in the `config.json` of each Asset Bundle. Each `config.json` stores only the resource information in the respective Asset Bundle, which reduces the size of the first package. This can simply be understood as all the `config.json` combined equal to the previous `settings.json`.

- **Q**: Does the Asset Bundle support cross project reuse?<br>
**A**: The current version supports it, but we **do not recommend reusing **across projects. As the engine is updated and iterated, this can create all kinds of compatibility issues. cross-project reuse requires the following conditions to be met for now:
**A**: The current version supports it, but we **do not recommend reusing**across projects. As the engine is updated and iterated, this can create all kinds of compatibility issues. cross-project reuse requires the following conditions to be met for now:
1. The engine version is the same
2. All scripts referenced in the Asset bundle are placed under the Asset bundle.
3. The Asset Bundle has no other external dependency bundle, and if it does, it must be loaded.
Expand Down
Binary file added en/asset/bundle/export-config.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion en/asset/compress-texture.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Except for the `JPG` and `PNG` supported by all platforms, the details of other

| Platform | TextureCompressTypes |
| ----------------- | -------------------- |
| Web Desktop | ASTC / ETC2 / ETC1 / PVR / WEBP |
| Web Desktop | - |
| Web Mobile | ASTC / ETC2 / ETC1 / PVR / WEBP |
| WeChat Mini Game | ASTC / ETC1 / PVR |
| AliPay Mini Game | ETC1 / PVR |
Expand Down
181 changes: 180 additions & 1 deletion en/editor/publish/custom-build-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,14 +110,193 @@ Please pay extra attention to the following points when writing start scripts:

1. The environment variables in different processes will be different. The start script will be loaded by the rendering process and the main process at the same time, do not use the editor interface that only exists in a single process in the start script.

2. There are two ways to configure the key of `config`:
2. There are two ways to configure the key of `config`:

- One is for a single platform configuration, and the key is filled in as **platform plugin name** (available in the editor menu bar **Extensions -> Extension Manager -> Internal** to view the platform plug-in name).

- One is the configuration for all platforms, the key is filled in as `*`. These two configuration methods are mutually exclusive, please do not use them in the same build extension package.

> **Note**: these two configuration methods are mutually exclusive, please do not use both in the same build extension package. Otherwise the configuration for a single platform (key value `platform build plugin name`) will overwrite the configuration for all platforms (key value `*`).
## Customizing Build Panel Options

There are currently two ways to add build options to the interface: **options automatic rendering configuration method** and **panel custom panel configuration method** (>=3.8.2). The former automatically renders the content of the options configuration in the build panel and performs data update operations after some operations, while the latter adds a panel configuration to place the content of a custom panel, and the build will use this configuration to render with `ui-panel`.
To facilitate testing, this article will use `web-mobile` as an example to demonstrate how to add new options to the build panel and display them.

### Options Automatic Rendering Configuration Method

Create a new `src/builder.ts` script file and write the following code in `builder.ts`:

```ts
import { BuildPlugin, IBuildTaskOption } from "../@types/packages/builder/@types";

export const load: BuildPlugin.load = function() {
console.debug('custom-build-example load');
};

export const unload: BuildPlugin.load = function() {
console.debug('custom-build-example unload');
};

export const configs:BuildPlugin.Configs = {
'web-mobile': {
options: {
testInput: {
label: 'testVar',
description: 'this is a test input.',
default: '',
render: {
ui: 'ui-input',
attributes: {
placeholder: 'Enter numbers',
},
},
verifyRules: ['required','ruleTest']
},
testCheckbox: {
label: 'testCheckbox',
description: 'this is a test checkbox.',
default: false,
render: {
ui: 'ui-checkbox',
},
},
},
verifyRuleMap: {
ruleTest: {
message: 'length of content should be less than 6.',
func(val: any, option: IBuildTaskOption) {
if (val.length < 6) {
return true;
}
return false;
}
}
}
},
};
```

In the above `configs`, we define two parameters:

- `testInput`: string - String variable, modified by input box
- `testCheckbox`: boolean - Boolean variable, modified by checkbox

The meanings of each field in the configuration of build options are as follows:

- `label`: string - Required, the name of this parameter displayed on the interface, supports `i18n:key` configuration
- `description`: string - Optional, brief description information, used for displaying hints when the mouse hovers over the label, supports `i18n:key` configuration
- `default`: any - Optional, the default value of the parameter
- `render`: {} - Required, configure information about the rendered component
- `ui`: string - Required, UI component name, please refer to the documentation [UI components](../extension/ui.md)
- `attributes`: {} - Optional, properties required by the UI component, please refer to the documentation [UI components](../extension/ui.md)

- `verifyRules`: [] - Optional, parameter verification rules
- `verifyRuleMap`: [] - Optional, custom parameter verification rule functions. Refer to the section below on [parameter validation rules](#%E5%8F%82%E6%95%B0%E6%A0%A1%E9%AA%8C%E8%A7%84%E5%88%99)

After executing `npm run build` to compile this extension and refresh it, open the build panel and you can see two additional build parameters at the end of the web-mobile build task, as shown in the following figure:

![custom-build-example-options](./custom-build-plugin/custom-build-example-options.png)

### Panel customization method (>=3.8.2)

Create a new `src/builder.ts` script file and write the following code in `builder.ts`:

```ts
import { BuildPlugin, IBuildTaskOption } from "../@types/packages/builder/@types";

export const configs:BuildPlugin.Configs = {
'web-mobile': {
panel: './panel',
}
};
```

Create a new `src/panel.ts` script file and write the following code in `panel.ts`:

```ts
import { ICustomPanelThis, ITaskOptions } from '../@types';
import { PACKAGE_NAME } from './global';
let panel: ICustomPanelThis;

export const style = ``;

export const template = `
<div class="build-plugin">
<ui-prop>
<ui-label slot="label" value="Hide Link"></ui-label>
<ui-checkbox slot="content"></ui-checkbox>
</ui-prop>
</div>
`;

export const $ = {
root: '.build-plugin',
hideLink: 'ui-checkbox',
link: '#link',
};

/**
* all change of options dispatched will enter here
* @param options
* @param key
* @returns
*/
export async function update(options: ITaskOptions, key: string) {
if (key) {
return;
}
// when import build options, key will bey ''
init();
}

export function ready(options: ITaskOptions) {
// @ts-ignore
panel = this as ICustomPanelThis;
panel.options = options;
init();
}

export function close() {
panel.$.hideLink.removeEventListener('change', onHideLinkChange);
}

function init() {
panel.$.hideLink.value = panel.options.hideLink;
updateLink();
panel.$.hideLink.addEventListener('change', onHideLinkChange);
}

function onHideLinkChange(event: any) {
panel.options.hideLink = event.target.value;
// Note: dispatch the change to build panel
panel.dispatch('update', `packages.${PACKAGE_NAME}.hideLink`, panel.options.hideLink);
updateLink();
}

function updateLink() {
if (panel.options.hideLink) {
panel.$.link.style.display = 'none';
} else {
panel.$.link.style.display = 'block';
}
}
```

#### Rules for customizing build panels

The above code comes from a simple example code in the template of a custom build plugin. You can choose other front-end frameworks to develop the interface more conveniently according to your preferences. Just pay attention to the following rules:

1. The file content rules of the panel are rendered by ui-panel, and need to follow the relevant component rules, which basically refer to the variables or lifecycle hooks exposed in the above example code.
2. The `ready` function of the panel will be called after the panel has been loaded. According to needs, you can do some dom element initialization, event binding, or some front-end framework initialization binding in this function.
3. The `close` function of the panel will be called when the panel is closed. According to needs, you can do some event unregistration, object destruction, etc. in this function.

4. The `update` function of the panel will be called whenever any build option changes (including those sent by itself). If necessary, you can add this hook here. At the same time, when the build panel has an action of importing configuration, you can also do some updating of the customization panel in this function. At this time, `key` is an empty string.

5. If the interaction in the customized panel involves updating the build option, including the data update that may be done during the initialization process, you must use `panel.dispatch('update', key, value, error)` to perform the update, where `key` needs to follow the format of `packages.${PACKAGE_NAME}.key`. Only after calling it will the data be synchronized to the final build option when building. Sending an error mainly affects the disablement status of the build button, and error is an optional parameter.

6. If the interaction in the customized panel involves reading the build option, you need to use `panel.options.key`

### Start script interface definition

The detailed interface definition is described as follows:
Expand Down
41 changes: 41 additions & 0 deletions en/editor/publish/publish-in-command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,47 @@ Each platform's build will be embedded in the **Build** panel as a separate plug

After the build plugin system is opened to the public, the configuration parameters of other plugins are embedded in the **Build** panel in the same way. **Please refer to the documentation of each platform for the specific parameter fields of each platform**, it is better to use the **Export** function of the **Build** panel to get the configuration parameters. Currently it is still compatible with the old version of the parameters to build, but the compatibility process will be gradually removed later, so please upgrade the configuration parameters as soon as possible.

## Bundle Build via Command Line

1. Open the Bundle Build panel and configure the options. After configuring, export the configuration (since 3.8.2).
![export-config](./../../asset/bundle/export-config.png)
The exported configuration is as follows:

```json
{
"buildTaskIds": [
"1699344873959"
],
"dest": "project://build/build-bundle",
"id": "buildBundle",
"bundleConfigs": [
{
"root": "db://assets/resources",
"output": true
}
],
"taskName": "build bundle db://assets/resources"
}

```

2. Execute the following command in the command line:

- Mac

```bash
/Applications/CocosCreator/Creator/3.0.0/CocosCreator.app/Contents/MacOS/CocosCreator --project projectPath
--build "stage=bundle;configPath=./bundle-build-config.json;"
```

- Windows

```bash
...\CocosCreator.exe --project projectPath --build "stage=bundle;configPath=./bundle-build-config.json;"
```

The command line publish of the Bundle is similar to the ordinary command line build, but the `stage` parameter needs to be specified as `bundle`, and the configuration exported on the Bundle Build Panel should be specified as the `configPath` parameter.

## Publish using Jenkins

**Cocos Creator** still needs the GUI environment when running from the command line. If the Jenkins server can not run **Cocos Creator** from the command line, a solution is running Jenkins in agent mode, so it can interact with the operating systems window server. For more details please review this [Stack Overflow post](https://stackoverflow.com/questions/13966595/build-unity-project-with-jenkins-failed).
Expand Down
6 changes: 5 additions & 1 deletion zh/asset/bundle.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,7 @@ assetManager.removeBundle(bundle);

点击预览可以查看当前选中的 Bundle 内最终有哪些资源会打包进入 Bundle

## 构建 Bundle
## 独立构建 Bundle

如果只是想更新某些 Bundle 而不是对整个游戏进行打包,引擎自 v3.8 开始提供了更方便的构建 Bundle 功能。

Expand Down Expand Up @@ -406,6 +406,10 @@ assetManager.removeBundle(bundle);

该面板的设计目的是针对较大的项目,或者某些耗时的 Bundle,开发者可以单独对其进行打包。例如要热更新某个包。可以有效的降低打包耗时。

### 命令行执行独立发布 Bundle

详情请参考 [命令行执行独立发布 Bundle](./../editor/publish/publish-in-command-line.md#命令行执行独立发布-Bundle)

## FAQ

- **Q**Asset Bundlev2.4 之前的资源分包有什么区别?
Expand Down
Binary file added zh/asset/bundle/export-config.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion zh/asset/compress-texture.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Cocos Creator 3.0 在构建图片的时候,会查找当前图片是否进行

| 平台名称 | 支持的压缩格式 |
| :---------------- | :------------------- |
| Web Desktop | ASTC / ETC2 / ETC1 / PVR / WEBP |
| Web Desktop | - |
| Web Mobile | ASTC / ETC2 / ETC1 / PVR / WEBP |
| WeChat Mini Game | ASTC / ETC1 / PVR |
| AliPay Mini Game | ETC1 / PVR |
Expand Down
Loading

0 comments on commit b01b4f2

Please sign in to comment.