Merge branch 'main' into fix/findPath

galacean · Feb 6, 2025 · c5ca418 · c5ca418
2 parents 4532dbf + ed9c82f
commit c5ca418
Show file tree

Hide file tree

Showing 40 changed files with 1,560 additions and 300 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -105,19 +105,19 @@ jobs:
           browser: chrome
       - name: Upload Diff
         if: failure()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: cypress-diff
           path: e2e/diff/
       - name: Upload Origin
         if: failure()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: cypress-origin
           path: e2e/fixtures/originImage
       - name: Upload Screenshots
         if: failure()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: cypress-screenshots
           path: e2e/downloads/
diff --git a/docs/en/UI/_meta.json b/docs/en/UI/_meta.json
@@ -0,0 +1,11 @@
+{
+  "overall": {
+    "title": "Overview"
+  },
+  "quickStart": {
+    "title": "QuickStart"
+  },
+  "system": {
+    "title": "Architecture"
+  }
+}
diff --git a/docs/en/UI/overall.md b/docs/en/UI/overall.md
@@ -0,0 +1,26 @@
+---
+order: 0
+title: Overview
+type: UI
+label: UI
+---
+
+UI is a system used to build user interfaces. It provides a range of tools and components to help developers create interactive interface elements. Here are its key features:
+
+- **Visual Editing**: With the basic nodes and component creation capabilities in the [editor](https://galacean.antgroup.com/editor/projects), combined with the RectTool (shortcut key T), developing interactive interfaces becomes more intuitive and efficient.
+- **Rendering and Interactive Components**: Supports rendering components like Image, Text, etc., as well as basic interactive components such as Button.
+- **Transferable Opacity and Interactivity Attributes**: Through the UIGroup component, properties such as **opacity** and **interactivity** can be inherited or ignored.
+- **Events**: In addition to supporting original Pointer events, UI components also support **event bubbling** for interactions triggered by the UI.
+
+In this section, you will:
+
+- Learn how to quickly develop a UI interface:
+  - Create a [Root Canvas](/en/docs/UI/quickStart/canvas)
+  - Familiarize yourself with [UITransform](/en/docs/UI/quickStart/transform)
+  - Create [Image](/en/docs/UI/quickStart/image)
+  - Create [Text](/en/docs/UI/quickStart/text)
+  - Create [Button](/en/docs/UI/quickStart/button)
+  - Create [UIGroup](/en/docs/UI/quickStart/group)
+- Understand the [Overall Architecture and Module Management](/en/docs/UI/system) of UI
+- Learn about [UI Rendering Order](/en/docs/UI/quickStart/order)
+- Understand the [UI Event Mechanism](/en/docs/UI/quickStart/event)
diff --git a/docs/en/UI/quickStart/button.md b/docs/en/UI/quickStart/button.md
@@ -0,0 +1,44 @@
+---
+order: 4
+title: Button
+type: UI
+label: UI
+---
+
+`Button` can be used to create interactive buttons within a UICanvas.
+
+## Editor Usage
+
+### Add Button Node
+
+Add a `Button` node in the **[Hierarchy Panel](/docs/interface/hierarchy/)**.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*Zjn4QbY0B-IAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+> If the parent or ancestor node does not have a Canvas component, a root Canvas node will be automatically added.
+
+### Set Transition
+
+In the editor, you can easily set the button's transition effects for different states.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*IFiaSLZqIWYAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+## Properties
+
+| Property Name   | Description                       |
+| :-------------- | :-------------------------------- |
+| `transitions`   | All the transition effects of the button |
+| `interactive`   | Whether the button is interactive   |
+
+## Methods
+
+| Method Name         | Description                           |
+| :------------------ | :------------------------------------ |
+| `addTransition`     | Add a transition effect to the button |
+| `removeTransition`  | Remove a transition effect from the button |
+| `addClicked`        | Add a click callback function         |
+| `removeClicked`     | Remove a click callback function      |
+
+## Script Development
+
+<playground src="ui-Button.ts"></playground>
diff --git a/docs/en/UI/quickStart/canvas.md b/docs/en/UI/quickStart/canvas.md
@@ -0,0 +1,62 @@
+---
+order: 0
+title: Canvas
+type: UI
+label: UI
+---
+
+The root canvas is the foundation of the UI, but not all `UICanvas` nodes are root canvases. Here’s how to create a root canvas in your scene.
+
+## Editor Usage
+
+### Add UICanvas Node
+
+Add a Canvas node in the **[Hierarchy Panel](/docs/interface/hierarchy/)**.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*ZFO6Q7P7NwQAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+### Set Properties
+
+Select the node that has the `Canvas` component and you can set its properties in the **[Inspector Panel](/docs/interface/inspector)**.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*4nbARKclT8sAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+### Root Canvas
+
+If the parent or ancestor node of the newly added canvas node already contains an active `UICanvas` component, this canvas will not have rendering or interaction functionality.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*9CxZQ5t6GVEAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+## Properties
+
+| Property Name                  | Description                                                   |
+| :------------------------------ | :------------------------------------------------------------ |
+| `renderMode`                    | The rendering mode of the canvas                               |
+| `renderCamera`                  | The camera used for rendering when the canvas is in `ScreenSpaceCamera` mode |
+| `distance`                      | The distance of the canvas relative to the camera when in `ScreenSpaceCamera` mode |
+| `resolutionAdaptationMode`      | The adaptation mode of the canvas, such as width adaptation or height adaptation |
+| `referenceResolution`           | The reference resolution for size adaptation of the canvas    |
+| `referenceResolutionPerUnit`    | The ratio of canvas units to world space units                 |
+| `sortOrder`                     | The rendering priority of the canvas                           |
+
+## Script Development
+
+```typescript
+// Add camera
+const cameraEntity = root.createChild("Camera");
+const camera = cameraEntity.addComponent(Camera);
+
+// Add UICanvas
+const canvasEntity = root.createChild("canvas");
+const canvas = canvasEntity.addComponent(UICanvas);
+
+// Set renderMode to `ScreenSpaceOverlay`
+canvas.renderMode = CanvasRenderMode.ScreenSpaceOverlay;
+// Set renderMode to `ScreenSpaceCamera`
+canvas.renderMode = CanvasRenderMode.ScreenSpaceCamera;
+canvas.renderCamera = camera;
+// Set Reference Resolution
+canvas.referenceResolution.set(750, 1624);
+// Set Adaptation Mode
+canvas.resolutionAdaptationMode = ResolutionAdaptationMode.WidthAdaptation;
+```
diff --git a/docs/en/UI/quickStart/event.md b/docs/en/UI/quickStart/event.md
@@ -0,0 +1,40 @@
+---
+order: 3
+title: Event
+type: UI
+label: UI
+---
+
+UI events follow the engine's event system, with the additional support for event bubbling in UI components.
+
+## Bubbling
+
+The current version only supports the following bubbling flow:
+
+| Interface                                                     | Bubbles    |
+| :----------------------------------------------------------- | :--------- |
+| [onPointerEnter](/apis/core/#Script-onPointerEnter)          | Does not bubble |
+| [onPointerExit](/apis/core/#Script-onPointerExit)            | Does not bubble |
+| [onPointerDown](/apis/core/#Script-onPointerDown)            | Bubbles    |
+| [onPointerUp](/apis/core/#Script-onPointerUp)                | Bubbles    |
+| [onPointerClick](/apis/core/#Script-onPointerClick)          | Bubbles    |
+| [onPointerBeginDrag](/apis/core/#Script-onPointerBeginDrag)  | Bubbles    |
+| [onPointerDrag](/apis/core/#Script-onPointerDrag)            | Bubbles    |
+| [onPointerEndDrag](/apis/core/#Script-onPointerEndDrag)      | Bubbles    |
+| [onPointerDrop](/apis/core/#Script-onPointerDrop)            | Bubbles    |
+
+As shown in the diagram below, if node C triggers the `pointerup` event, the event will bubble along the path C --> B --> A --> RootCanvas.
+
+```mermaid
+stateDiagram
+    RootCanvas --> A
+    RootCanvas --> F
+    A --> B
+    A --> E
+    B --> C
+    B --> D
+```
+
+## Script Development
+
+<playground src="ui-Event.ts"></playground>
diff --git a/docs/en/UI/quickStart/group.md b/docs/en/UI/quickStart/group.md
@@ -0,0 +1,28 @@
+---
+order: 5
+title: UIGroup
+type: UI
+label: UI
+---
+
+The `UIGroup` component allows you to inherit or ignore properties such as **opacity** and **interactivity**.
+
+## Editor Usage
+
+Select the node, then in the **[Inspector Panel](/docs/interface/inspector)**, click **Add Component** and choose **UIGroup**. You can control the opacity of multiple UI elements by modifying the settings.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*PWGYRb7MJs4AAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+## Properties
+
+| Property Name       | Description                        |
+| :------------------ | :--------------------------------- |
+| `alpha`             | Opacity                            |
+| `interactive`       | Whether the element is interactive |
+| `ignoreParentGroup` | Whether to ignore the settings of the parent group |
+
+> UIGroup resolves the issue where UI element properties cannot be passed from parent to child.
+
+## Script Development
+
+<playground src="xr-ar-simple.ts"></playground>
diff --git a/docs/en/UI/quickStart/image.md b/docs/en/UI/quickStart/image.md
@@ -0,0 +1,48 @@
+---
+order: 2
+title: Image
+type: UI
+label: UI
+---
+
+The `Image` component is used to display images within a `UICanvas`.
+
+## Editor Usage
+
+### Add Image Node
+
+Add an `Image` node in the **[Hierarchy Panel](/docs/interface/hierarchy/)**.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*9SCNTZNglo0AAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+> If the parent or ancestor node does not have a Canvas component, a root canvas node will be automatically added.
+
+### Set Sprite
+
+The content displayed by the `Image` depends on the selected [Sprite asset](). Select the node with the `Image` component, and in the **[Inspector Panel](/docs/interface/inspector)**, choose the corresponding sprite asset in the Sprite property to change the displayed content.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*aztPTKxnkHEAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+### Modify Draw Mode
+
+The `Image` component currently provides three draw modes: Normal, Nine-Patch, and Tiled (the default is Normal). You can visually feel the rendering differences between modes by modifying the width and height in each mode.
+
+<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*z6iPRb0U9FUAAAAAAAAAAAAAehuCAQ/original" style="zoom:50%;" />
+
+### Adjust Size
+
+For adjusting the size of UI elements, refer to [Quickly Adjust UI Element Size](/docs/UI/quickStart/transform).
+
+## Properties
+
+| Property Name      | Description                                         |
+| :----------------- | :-------------------------------------------------- |
+| `sprite`           | The sprite to render                                |
+| `color`            | The color of the sprite                             |
+| `drawMode`         | The draw mode, supports Normal, Nine-Patch, and Tiled modes |
+| `raycastEnabled`   | Whether the image can be detected by raycasting    |
+| `raycastPadding`   | Custom padding for raycasting, representing the distance from the edges of the collision area. This is a normalized value, where X, Y, Z, and W represent the distances from the left, bottom, right, and top edges respectively. |
+
+## Script Development
+
+<playground src="ui-Image.ts"></playground>
diff --git a/docs/en/UI/quickStart/order.md b/docs/en/UI/quickStart/order.md
@@ -0,0 +1,61 @@
+---
+order: 6
+title: Rendering Order
+type: UI
+label: UI
+---
+
+The rendering order of UI components follows two rules:
+
+- Different `UICanvas` instances follow a specific rendering order based on their `RendererMode` type.
+- `UIRenderer` components under a `UICanvas` are rendered according to a **depth-first** order, from parent to child, and from left to right.
+
+## UICanvas
+
+Assume the current runtime:
+- There is a scene `Scene`
+- The scene `Scene` contains two cameras, `Camera1` and `Camera2`
+- The scene `Scene` contains three canvases:
+  - `Canvas1` with `WorldSpace` render mode
+  - `Canvas2` with `ScreenSpace-Overlay` render mode
+  - `Canvas3` with `ScreenSpace-Camera` render mode, using `Camera1` as the render camera
+
+```mermaid
+journey
+    title Scene Rendering Cycle
+    section Camera1.render
+      Canvas1.render: 5
+      Canvas3.render: 5
+    section Camera2.render
+      Canvas1.render: 5
+    section Ending
+      Canvas2.render: 5
+```
+
+It's important to note:
+- Canvases with `ScreenSpace-Camera` render mode will only render with their corresponding camera, and they follow the general camera clipping rules, just like canvases with `ScreenSpace-Overlay` render mode.
+- Canvases with `ScreenSpace-Overlay` render mode can still be rendered without a camera.
+- Within the same camera, the rendering order of `UICanvas` follows these rules: canvases in the overlay mode have their rendering order determined only by `sortOrder`.
+
+```mermaid
+flowchart TD
+    A[Sort rendering data] --> B{canvas.sortOrder}
+    B -->|Not equal| C[Return comparison result]
+    B -->|Equal| D{Canvas and camera distance}
+    D -->|Not equal| E[Return comparison result]
+    D -->|Equal| F[Return comparison result]
+```
+
+## UIRenderer Rendering Order
+
+```mermaid
+stateDiagram
+    RootCanvas --> A
+    RootCanvas --> F
+    A --> B
+    A --> E
+    B --> C
+    B --> D
+```
+
+As shown in the diagram above, the rendering order under the root canvas follows A -> B -> C -> D -> E -> F. It is important to note that setting `UIRenderer.priority` does not change its rendering order.