完善部分文档 (cocos#1977)

* 完善部分文档

* 补充微信小游戏开启 WebGL 2.0 说明

* 完善 2D 渲染组件合批

* Fix error

* Apply suggestions from code review

Author: xunyi0

en/editor/project/index.md

@@ -86,11 +86,14 @@ Used to configure various parameters of physics, please refer to the [Physics Co
 
 - **MAX_LABEL_CANVAS_POOL_SIZE**: set the maximum number of Canvas object pools used by the Label, and adjust it according to the number of Labels in the same scene of the project.
 
-- **ENABLE_WEBGL_HIGHP_STRUCT_VALUES**: on the Android platform with WebGL backend, the internal variables of the structures defined in the fragment shader use **mediump** precision, which may lead to incorrect results for some data that requires high precision (such as position information). To avoid this problem, check this option (new in v3.4.1) and enable WebGL to calculate variables with **highp** precision.
+- **ENABLE_WEBGL_HIGHP_STRUCT_VALUES** (new in v3.4.1): on the Android platform with WebGL backend, the internal variables of the structures defined in the fragment shader use **mediump** precision, which may lead to incorrect results for some data that requires high precision (such as position information). To avoid this problem, check this option and enable WebGL to calculate variables with **highp** precision.
 
     - If this option is enabled, use the `HIGHP_VALUE_STRUCT_DEFINE` macro in the fragment shader code to define structural variables, and use `HIGHP_VALUE_TO_STRUCT_DEFINED` and `HIGHP_VALUE_FROM_STRUCT_DEFINED` to assign values between structural and non-structural variables.
+
     - For specific information and code on the above macro calls, please refer to [packing.chunk](https://github.com/cocos-creator/engine/blob/v3.4.1/editor/assets/chunks/packing.chunk#L40) for details.
 
+- **BATCHER2D_MEM_INCREMENT** (new in v3.4.1): this option affects the maximum number of vertices in each MeshBuffer, the default value is 144KB, please refer to the [MeshBuffer Batch Description](../../ui-system/components/engine/ui-batch.md) documentation for the conversion relationship between the number and the value.
+
 - **Custom Macro**: used to customize macro configurations, providing a macro tagging feature for current project scripts for easy visual configuration. Click the **+** button below to add a new macro configuration, hover over the added macro configuration and the **Delete** and **Modify** buttons will be displayed on the left side for deleting/renaming the current macro configuration respectively.
 
   ![macro](./index/custom-macro.png)

en/editor/project/index/macro.png

@@ -42,6 +42,8 @@ In addition, the game submission, review and release process of the **WeChat Min
 
 ### Build Options
 
+![build](./publish-wechatgame/wechat-build.png)
+
 | Options | Optional or not | Default | Explanation |
 | :-- | :-- | :-- | :-- |
 | **appid** | Required | `wx6ac3f5090a6b99c5` | The appid of the WeChat Mini Games, it will be written to `project.config.json` file.|
@@ -51,6 +53,7 @@ In addition, the game submission, review and release process of the **WeChat Min
 | **Orientation** | Required | `landscape` | Device orientation, it will be written to `game.json` file.|
 | **Separate Engine** | Optional | Empty | Whether to use WeChat Mini Games engine plugin, please refer to [WeChat Mini Games Engine Plugin Instructions](./wechatgame-plugin.md) for details. |
 | **Wasm 3D physics system (based on `ammo.js`)** | Optional | Enabled | This option is used to select whether to enable **Wasm**, which takes effect when using **bullet（ammo.js）** physics. Please refer to the **WebAssembly Support** section below for more details. |
+| **Whether to enabled WebGL2** (Experimental feature) | - | Forced Off | In order to allow WebGL 2.0 to be enabled on WeChat Mini Games in the future, we have added this option in **v3.4.1** to support to enable WebGL 2.0 following the configuration in the **Project Settings** panel, and to turn off to reduce the package by default.<br>If this option is set to **Consistent with project settings** and **WebGL 2.0** is checked in **Project Settings -> Feature Cropping**, it will be successfully enabled in the future if the WeChat environment supports WebGL 2.0. |
 
 ## Asset Management for WeChat Mini Game Environment
 

en/editor/publish/publish-wechatgame.md

@@ -1,47 +1,77 @@
 # Input Event System
 
-As mentioned in the previous document, `EventTarget` supports a complete set of event listening and emitting mechanisms. In Cocos Creator v3.4.0, `input` object is supported, which implements the event registering interface of `EventTarget`, and can register global system input events through this object. The original `systemEvent` object has been deprecated since v3.4.0, and the differences between `systemEvent` and `input` are as follows:
+As mentioned in the previous document, `EventTarget` supports a complete set of event listening and emitting mechanisms. In Cocos Creator v3.4.0, `input` object is supported, which implements the event registering interface of `EventTarget`, and can register global system input events through this object. The original `systemEvent` object has been deprecated since v3.4.0 and will be gradually removed in the future, we recommend using the `input` object as a replacement.
 
-- The declaration of touch event callback in `systemEvent` is `(touch: Touch, event: EventTouch) => void`
-- The declaration of touch event callback in `input` is `(event: EventTouch) => void`
+The differences between `systemEvent` and `input` are as follows:
 
-__Note__: in v3 4.0 there are also the following differences between the two objects:
-- The event listener of `systemEvent` will be intercepted by the event listener of the node.
-- `input` objects have higher priority than nodes and will not be intercepted.
-We have lowered the priority of 'input' in v3.4.1. Currently, there is no difference in priority between the two objects.
+- **Differences in type definitions**
 
-> __Note__: the `systemEvent` object is no longer recommended and will be phased out in the future, we recommend using the `input` object as a replacement.
+    - The declaration of touch event callback in `systemEvent` is `(touch: Touch, event: EventTouch) => void`
 
-In this section, the `global input events` of __Cocos Creator__ will be introduced.
+    - The declaration of touch event callback in `input` is `(event: EventTouch) => void`
 
-`Global input events` are irrelevant with the node hierarchy, so they are dispatched globally by `input`, currently supported:
+- **Differences in priority**
+
+    - The event listener of `systemEvent` will be intercepted by the event listener of the node.
+
+    - `input` objects have higher priority than nodes and will not be intercepted.
+
+    > __Note__: we lowered the priority of `input` in **v3.4.1**, so there is no difference in priority between the two objects since v3.4.1.
+
+---
+
+In this section, the handling of global input events in Cocos Creator will be introduced.
+
+**Global input events** are irrelevant with the node hierarchy, so they are dispatched globally by `input`, currently supported:
 
 - Mouse
 - Touch
-- Keyboard 
+- Keyboard
 - DeviceMotion
 
 ## How to define the input events
 
-Use `input.on(type, callback, target)` to register global input event listeners.
+Use `input.on(type, callback, target)` to register global input event listeners. Event types included:
 
-Event types included:
-
-1. `Input.EventType.MOUSE_DOWN`, `Input.EventType.MOUSE_MOVE`, `Input.EventType.MOUSE_UP`, `Input.EventType.MOUSE_WHEEL`
-2. `Input.EventType.TOUCH_START`, `Input.EventType.TOUCH_MOVE`, `Input.EventType.TOUCH_CANCEL`, `Input.EventType.TOUCH_END`
-3. `Input.EventType.KEY_DOWN`, `Input.EventType.KEY_PRESSING`, `Input.EventType.KEY_UP`
-4. `Input.EventType.DEVICEMOTION`
+| Input Event | `type` |
+| :----- | :---------- |
+| Mouse Event | `Input.EventType.MOUSE_DOWN`<br>`Input.EventType.MOUSE_MOVE`<br>`Input.EventType.MOUSE_UP`<br>`Input.EventType.MOUSE_WHEEL` |
+| Touch Event | `Input.EventType.TOUCH_START`<br>`Input.EventType.TOUCH_MOVE`<br>`Input.EventType.TOUCH_END`<br>`Input.EventType.TOUCH_CANCEL` |
+| Keyboard Event | `Input.EventType.KEY_DOWN` (keyboard pressed)<br>`Input.EventType.KEY_PRESSING` (keyboard continuously pressed)<br>`Input.EventType.KEY_UP` (keyboard release) |
+| DeviceMotion Event | `Input.EventType.DEVICEMOTION` |
 
 ### Pointer Events
 
 Pointer events include mouse and touch events.
 
-- Event Listener Types:
-    - `Input.EventType.MOUSE_DOWN`, `Input.EventType.MOUSE_MOVE`, `Input.EventType.MOUSE_UP`, `Input.EventType.MOUSE_WHEEL`
-    - `Input.EventType.TOUCH_START`, `Input.EventType.TOUCH_MOVE`, `Input.EventType.TOUCH_CANCEL`, `Input.EventType.TOUCH_END`
-- Callback Function:
-    - Custom Function: callback(event);
-- Callback Parameter:
+- Event listener types
+
+    - Mouse event listening
+
+        - `Input.EventType.MOUSE_DOWN`
+
+        - `Input.EventType.MOUSE_MOVE`
+
+        - `Input.EventType.MOUSE_UP`
+
+        - `Input.EventType.MOUSE_WHEEL`
+
+    - Touch event listening
+
+        - `Input.EventType.TOUCH_START`
+
+        - `Input.EventType.TOUCH_MOVE`
+
+        - `Input.EventType.TOUCH_CANCEL`
+
+        - `Input.EventType.TOUCH_END`
+
+- Callback function after event triggering
+
+    - Custom callback function: `callback(event);`
+
+- Callback parameter
+
     - [EventMouse](__APIDOC__/en/#/docs/3.4/en/cocos-input-types-event/Class/EventMouse) or [EventTouch](__APIDOC__/en/#/docs/3.4/en/cocos-input-types-event/Class/EventTouch)
 
 Examples of the use of pointer events are as follows:
@@ -69,12 +99,24 @@ export class Example extends Component {
 
 ### Keyboard events
 
-- Event Listener Types: `Input.EventType.KEY_DOWN`，`Input.EventType.KEY_PRESSING` and `Input.EventType.KEY_UP`
-- Callback Function:
-    - Custom Function: callback(event);
-- Callback Parameter:
+- Event listener types
+
+    - `Input.EventType.KEY_DOWN`
+
+    - `Input.EventType.KEY_PRESSING`
+
+    - `Input.EventType.KEY_UP`
+
+- Callback function after event triggering
+
+    - Custom Function: `callback(event);`
+
+- Callback parameter
+
     - [EventKeyboard](__APIDOC__/en/#/docs/3.4/en/event/Class/EventKeyboard)
 
+Examples of the use of keyboard events are as follows:
+
 ```ts
 import { _decorator, Component, input, Input, EventKeyboard, KeyCode } from 'cc';
 const { ccclass } = _decorator;
@@ -111,11 +153,19 @@ export class Example extends Component {
 
 ### Device Motion
 
-- Type: `Input.EventType.DEVICEMOTION`
-- Callback:
-  - Custom Function: `callback(event);`;
-- Callback parameter:
-  - [EventAcceleration](__APIDOC__/en/#/docs/3.4/en/cocos-input-types-event/Class/EventAcceleration)
+- Event listener type
+
+    - `Input.EventType.DEVICEMOTION`
+
+- Callback function after event triggering
+
+    - Custom callback function: `callback(event);`
+
+- Callback parameter
+
+    - [EventAcceleration](__APIDOC__/en/#/docs/3.4/en/cocos-input-types-event/Class/EventAcceleration)
+
+Examples of the use of DeviceMotion events are as follows:
 
 ```ts
 import { _decorator, Component, input, Input, log } from 'cc';
@@ -138,54 +188,55 @@ export class Example extends Component {
 }
 ```
 
-Please review the [test-cases-3d](https://github.com/cocos-creator/test-cases-3d/tree/v3.4/assets/cases/event) (This includes the keyboard, accelerometer, single  touch, multi-touch examples).
+The specific usage can be found in the example [event](https://github.com/cocos-creator/test-cases-3d/tree/v3.4/assets/cases/event), which contains the implementation of keyboard, accelerometer, single-touch, multi-touch and other functions.
 
 ## Touch detection for 3D objects
 
 The touch detection for 3D objects and 2D UI nodes is different:
 
-- 2D UI nodes only need the size information provided by the `UITransform` component and the position information of the node to do the touch detection. For details, please refer to [Node Event System](event-node.ts). 
+- 2D UI nodes only need the size information provided by the `UITransform` component and the position information of the node to do the touch detection. For details, please refer to [Node Event System](event-node.md).
+
 - The touch detection for 3D objects needs to be implemented by ray cast. The specific method is to generate a ray from the rendering camera of the 3D object to the screen coordinates of the touch point to determine whether the ray hits the object that was detected. The specific code implementation is as follows: 
 
-```ts
-import { _decorator, Component, Node, Camera, geometry, input, Input, EventTouch, PhysicsSystem } from 'cc';
-const { ccclass, property } = _decorator;
+    ```ts
+    import { _decorator, Component, Node, Camera, geometry, input, Input, EventTouch, PhysicsSystem } from 'cc';
+    const { ccclass, property } = _decorator;
 
-@ccclass("Example")
-export class Example extends Component {
+    @ccclass("Example")
+    export class Example extends Component {
 
-    // Specify the camera rendering the target node.
-    @property(Camera)
-    readonly cameraCom!: Camera;
+        // Specify the camera rendering the target node.
+        @property(Camera)
+        readonly cameraCom!: Camera;
 
-    @property(Node)
-    public targetNode!: Node
+        @property(Node)
+        public targetNode!: Node
 
-    private _ray: geometry.Ray = new geometry.Ray();
+        private _ray: geometry.Ray = new geometry.Ray();
 
-    onEnable () {
-        input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
-    }
+        onEnable () {
+            input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
+        }
 
-    onDisable () {
-        input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
-    }
+        onDisable () {
+            input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
+        }
 
-    onTouchStart(event: EventTouch) {
-        const touch = event.touch!;
-        this.cameraCom.screenPointToRay(touch.getLocationX(), touch.getLocationY(), this._ray);
-        if (PhysicsSystem.instance.raycast(this._ray)) {
-            const raycastResults = PhysicsSystem.instance.raycastResults;
-            for (let i = 0; i < raycastResults.length; i++) {
-                const item = raycastResults[i];
-                if (item.collider.node == this.targetNode) {
-                    console.log('raycast hit the target node !');
-                    break;
+        onTouchStart(event: EventTouch) {
+            const touch = event.touch!;
+            this.cameraCom.screenPointToRay(touch.getLocationX(), touch.getLocationY(), this._ray);
+            if (PhysicsSystem.instance.raycast(this._ray)) {
+                const raycastResults = PhysicsSystem.instance.raycastResults;
+                for (let i = 0; i < raycastResults.length; i++) {
+                    const item = raycastResults[i];
+                    if (item.collider.node == this.targetNode) {
+                        console.log('raycast hit the target node !');
+                        break;
+                    }
                 }
+            } else {
+                console.log('raycast does not hit the target node !');
             }
-        } else {
-            console.log('raycast does not hit the target node !');
         }
     }
-}
-```
+    ```

en/editor/publish/publish-wechatgame/wechat-build.png

@@ -120,7 +120,7 @@ Touch events support the event bubbling on the node tree, take the pictures belo
 
 In the scene shown in the picture, suppose node A has a child node B which has a child node C. The developer sets the touch event listeners for all these three nodes (each node has a touch event listener in examples below by default).
 
-When the mouse or finger was applied in the node C region, the event will be triggered at node C first and the node C listener will receive the event (this is the target phase). Then the node C will pass this event to its parent node, so the node B listener will receive this event. Similarly the node B will also pass the event to its parent node A. This is a basic event bubbling phase. 
+When the mouse or finger was applied in the node C region, the event will be triggered at node C first and the node C listener will receive the event (this is the target phase). Then the node C will pass this event to its parent node, so the node B listener will receive this event. Similarly the node B will also pass the event to its parent node A. This is a basic event bubbling phase.
 
 > __Note__: it needs to be emphasized that there is no hit test in parent nodes in the bubbling phase, which means that nodes A and B can receive touch events even though the touch location is out of their node area.
 
@@ -132,9 +132,9 @@ Suppose the node B and C in the picture above are brother nodes, while C partly
 
 At the same time, if C has a parent node, it will also pass the touch event to its parent node through the event bubble mechanism.
 
-In v3.4.0, the ability of event penetrating dispatch is supported. In this example, if the event needs to be dispatched to node B, the event can be prevented from being swallowed by node C by calling `event.preventSwallow = true`. 
+In v3.4.0, the ability of event penetrating dispatch is supported. In this example, if the event needs to be dispatched to node B, the event can be prevented from being swallowed by node C by calling `event.preventSwallow = true`.
 
-> __Note__: the event penetrating dispatch reduces the efficiency of event dispatch, please use it with caution. 
+> __Note__: the event penetrating dispatch reduces the efficiency of event dispatch, please use it with caution.
 
 ### Point of Contact Attribution for Different Canvas
 
@@ -158,7 +158,7 @@ Only touch or mouse events can be registered in the capturing phase, while the o
 
 ### Event Interception
 
-Normal events are dispensed as described above. However, if the node has components such as `Button`, `Toggle` or `BlockInputEvents` on it, it will stop event bubbling. 
+Normal events are dispensed as described above. However, if the node has components such as `Button`, `Toggle` or `BlockInputEvents` on it, it will stop event bubbling.
 
 Look at the picture below. There are two buttons, priority 1 for Canvas0 and priority 2 for Canvas1. Click on the intersection of the two buttons, which is the blue area in the picture, it appears that button priority 2 received the contact event successfully, while button priority 1 did not. <br>That's because according to the event reception rules above, button priority 2 receives contact events first and intercepts them (`event.propagationStopped = true`) to prevent event penetration. If the node is a non-button node, events can also be intercepted by adding the `BlockInputEvents` component to prevent penetration.
 
@@ -243,15 +243,3 @@ Resume node system events
 // Example
 this.node.resumeSystemEvents();
 ```
-
-
-
-
-
-
-
-
-
-
-
-