From 7814b043c08de46c3730d0c2bdae1e18fd0e4571 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B9=85=E5=8F=94?= <768442443@qq.com> Date: Fri, 24 Jan 2025 17:11:12 +0800 Subject: [PATCH] refactor: doc md to mdx (#2530) * refactor: doc md to mdx --- docs/en/core/{canvas.md => canvas.mdx} | 0 docs/en/core/{clone.md => clone.mdx} | 0 docs/en/core/component.md | 98 ------------- docs/en/core/component.mdx | 98 +++++++++++++ docs/en/core/{engine.md => engine.mdx} | 0 docs/en/core/{math.md => math.mdx} | 5 +- docs/en/core/prefab.md | 102 -------------- docs/en/core/prefab.mdx | 98 +++++++++++++ docs/en/core/scene.mdx | 6 +- docs/en/core/space.md | 64 --------- docs/en/core/space.mdx | 63 +++++++++ docs/en/core/{time.md => time.mdx} | 0 docs/en/core/transform.md | 131 ------------------ docs/en/core/transform.mdx | 130 +++++++++++++++++ docs/en/interface/inspector.md | 70 ---------- docs/en/interface/inspector.mdx | 70 ++++++++++ .../interface/{shortcut.md => shortcut.mdx} | 2 +- .../interface/{template.md => template.mdx} | 3 +- docs/en/interface/viewport.md | 102 -------------- docs/en/interface/viewport.mdx | 100 +++++++++++++ docs/zh/core/{canvas.md => canvas.mdx} | 0 docs/zh/core/{clone.md => clone.mdx} | 0 docs/zh/core/{component.md => component.mdx} | 12 +- docs/zh/core/{engine.md => engine.mdx} | 0 docs/zh/core/{math.md => math.mdx} | 6 +- docs/zh/core/{prefab.md => prefab.mdx} | 26 ++-- docs/zh/core/scene.mdx | 6 +- docs/zh/core/{space.md => space.mdx} | 18 +-- docs/zh/core/{time.md => time.mdx} | 0 docs/zh/core/{transform.md => transform.mdx} | 10 +- .../interface/{inspector.md => inspector.mdx} | 22 +-- .../interface/{shortcut.md => shortcut.mdx} | 2 +- .../interface/{template.md => template.mdx} | 2 +- .../interface/{viewport.md => viewport.mdx} | 38 ++--- 34 files changed, 637 insertions(+), 647 deletions(-) rename docs/en/core/{canvas.md => canvas.mdx} (100%) rename docs/en/core/{clone.md => clone.mdx} (100%) delete mode 100644 docs/en/core/component.md create mode 100644 docs/en/core/component.mdx rename docs/en/core/{engine.md => engine.mdx} (100%) rename docs/en/core/{math.md => math.mdx} (98%) delete mode 100644 docs/en/core/prefab.md create mode 100644 docs/en/core/prefab.mdx delete mode 100644 docs/en/core/space.md create mode 100644 docs/en/core/space.mdx rename docs/en/core/{time.md => time.mdx} (100%) delete mode 100644 docs/en/core/transform.md create mode 100644 docs/en/core/transform.mdx delete mode 100644 docs/en/interface/inspector.md create mode 100644 docs/en/interface/inspector.mdx rename docs/en/interface/{shortcut.md => shortcut.mdx} (66%) rename docs/en/interface/{template.md => template.mdx} (72%) delete mode 100644 docs/en/interface/viewport.md create mode 100644 docs/en/interface/viewport.mdx rename docs/zh/core/{canvas.md => canvas.mdx} (100%) rename docs/zh/core/{clone.md => clone.mdx} (100%) rename docs/zh/core/{component.md => component.mdx} (72%) rename docs/zh/core/{engine.md => engine.mdx} (100%) rename docs/zh/core/{math.md => math.mdx} (98%) rename docs/zh/core/{prefab.md => prefab.mdx} (68%) rename docs/zh/core/{space.md => space.mdx} (68%) rename docs/zh/core/{time.md => time.mdx} (100%) rename docs/zh/core/{transform.md => transform.mdx} (95%) rename docs/zh/interface/{inspector.md => inspector.mdx} (69%) rename docs/zh/interface/{shortcut.md => shortcut.mdx} (64%) rename docs/zh/interface/{template.md => template.mdx} (68%) rename docs/zh/interface/{viewport.md => viewport.mdx} (56%) diff --git a/docs/en/core/canvas.md b/docs/en/core/canvas.mdx similarity index 100% rename from docs/en/core/canvas.md rename to docs/en/core/canvas.mdx diff --git a/docs/en/core/clone.md b/docs/en/core/clone.mdx similarity index 100% rename from docs/en/core/clone.md rename to docs/en/core/clone.mdx diff --git a/docs/en/core/component.md b/docs/en/core/component.md deleted file mode 100644 index 023384bb61..0000000000 --- a/docs/en/core/component.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -order: 4 -title: Components -type: Core -label: Core ---- - -In the Galacean engine, [Entity](/apis/core/#Entity) does not have actual functionalities such as rendering models. These functionalities are implemented by loading [Component](/apis/core/#Component) component classes. For example, if you want to turn an _Entity_ into a camera, you just need to add the camera component [Camera](/apis/core/#Camera) to that _Entity_. This component-based functionality extension method focuses on encapsulating the program independently according to functionality, and combining and adding as needed during use, which is very beneficial for reducing program coupling and improving code reusability. - -Common components: - -| Name | Description | -| :---------------------------------------------------- | :------------- | -| [Camera](/apis/core/#Camera) | Camera | -| [MeshRenderer](/apis/core/#MeshRenderer) | Static Model Renderer | -| [SkinnedMeshRenderer](/apis/core/#SkinnedMeshRenderer) | Skinned Model Renderer | -| [Animator](/apis/core/#Animator) | Animation Control Component | -| [DirectLight](/apis/core/#DirectLight) | Directional Light | -| [PointLight](/apis/core/#PointLight) | Point Light | -| [SpotLight](/apis/core/#SpotLight) | Spotlight | -| [ParticleRenderer](/apis/core/#ParticleRenderer) | Particle System | -| [BoxCollider](/apis/core/#BoxCollider) | Box Collider | -| [SphereCollider](/apis/core/#SphereCollider) | Sphere Collider | -| [PlaneCollider](/apis/core/#PlaneCollider) | Plane Collider | -| [Script](/apis/core/#Script) | Script | - -## Editor Usage - -After selecting an entity from the **[Hierarchy Panel](/en/docs/interface/hierarchy)** or the scene, the inspector will display all the components mounted on the currently selected node, with the component names displayed in the upper left corner - -Name - -You can control whether it is enabled in the inspector - -Enable - -If you don't need it, you can also delete it - -Delete - -Or edit its various properties - -Edit - -If it is an empty node, you can click the `Add Component` button to add new components to the current entity. - -image-20230926112713126 - -## Script Usage - -### Adding Components - -We use [addComponent(Component)](/apis/core/#Entity-addComponent) to add components, for example, adding a "Direct Light" component ([DirectLight](/apis/core/#DirectLight)) to an `Entity`: - -```typescript -const lightEntity = rootEntity.createChild("light"); -const directLight = lightEntity.addComponent(DirectLight); -directLight.color = new Color(0.3, 0.3, 1); -directLight.intensity = 1; -``` - -### Finding Components on an Entity - -When we need to get a component on an entity, the [getComponent](/apis/core/#Entity-getComponent) API will help you find the target component. - -```typescript -const component = newEntity.getComponent(Animator); -``` - -Sometimes there may be multiple components of the same type, and the above method will only return the first found component. If you need to find all components, you can use [getComponents](/apis/core/#Entity-getComponents): - -```typescript -const components = []; -newEntity.getComponents(Animator, components); -``` - -In assets like glTF, we might not know which entity the target component is on. In this case, you can use [getComponentsIncludeChildren](/apis/core/#Entity-getComponentsIncludeChildren) to search. - -```typescript -const components = []; -newEntity.getComponentsIncludeChildren(Animator, components); -``` - -### Getting the Entity of a Component - -Continuing with the example of adding a component at the beginning. You can directly get the entity of the component: - -```typescript -const entity = directLight.entity; -``` - -### State - -When temporarily not using a component, you can actively call the component's [enabled](/apis/core/#Component-enabled) - -```typescript -directLight.enabled = false; -``` diff --git a/docs/en/core/component.mdx b/docs/en/core/component.mdx new file mode 100644 index 0000000000..f82501c514 --- /dev/null +++ b/docs/en/core/component.mdx @@ -0,0 +1,98 @@ +--- +order: 4 +title: Components +type: Core +label: Core +--- + +An [Entity](/apis/core/#Entity) does not have actual functionalities such as rendering models. These functionalities are achieved by loading [Component](/apis/core/#Component) classes. For example, if you want an _Entity_ to become a camera, you simply add a camera component [Camera](/apis/core/#Camera) to the _Entity_. This component-based extension approach focuses on encapsulating functionalities independently and combining them as needed, which is very beneficial for reducing program coupling and enhancing code reusability. + +Common Components: + +| Name | Description | +| :------------------------------------------------- | :--------------- | +| [Camera](/apis/core/#Camera) | Camera | +| [MeshRenderer](/apis/core/#MeshRenderer) | Static model renderer | +| [SkinnedMeshRenderer](/apis/core/#SkinnedMeshRenderer) | Skinned model renderer | +| [Animator](/apis/core/#Animator) | Animation control component | +| [DirectLight](/apis/core/#DirectLight) | Directional light | +| [PointLight](/apis/core/#PointLight) | Point light | +| [SpotLight](/apis/core/#SpotLight) | Spotlight | +| [ParticleRenderer](/apis/core/#ParticleRenderer) | Particle system | +| [BoxCollider](/apis/core/#BoxCollider) | Box collider | +| [SphereCollider](/apis/core/#SphereCollider) | Sphere collider | +| [PlaneCollider](/apis/core/#PlaneCollider) | Plane collider | +| [Script](/apis/core/#Script) | Script | + +## Using the Editor + +After selecting an entity from the **[Hierarchy Panel](/docs/interface/hierarchy)** or the scene, the inspector will display all the components mounted on the currently selected node, with the component name displayed in the top left corner. + +Name + +You can control whether it is enabled in the inspector. + +Enable + +If you don't need it, you can also delete it. + +Delete + +Or edit its various properties. + +Edit + +If it's an empty node, you can click the `Add Component` button to add new components to the current entity. + +image-20230926112713126 + +## Using Scripts + +### Adding a Component + +We use [addComponent(Component)](/apis/core/#Entity-addComponent) to add components. For example, to add a "parallel light" component ([DirectLight](/apis/core/#DirectLight)) to an `Entity`: + +```typescript +const lightEntity = rootEntity.createChild("light"); +const directLight = lightEntity.addComponent(DirectLight); +directLight.color = new Color(0.3, 0.3, 1); +directLight.intensity = 1; +``` + +### Finding Components on an Entity + +When we need to get a component on an entity, the [getComponent](/apis/core/#Entity-getComponent) API will help you find the target component. + +```typescript +const component = newEntity.getComponent(Animator); +``` + +Sometimes there may be multiple components of the same type, and the above method will only return the first found component. If you need to find all components, you can use [getComponents](/apis/core/#Entity-getComponents): + +```typescript +const components = []; +newEntity.getComponents(Animator, components); +``` + +In entities obtained from assets like glTF, we might not know which entity contains the target component. In this case, you can use [getComponentsIncludeChildren](/apis/core/#Entity-getComponentsIncludeChildren) to search. + +```typescript +const components = []; +newEntity.getComponentsIncludeChildren(Animator, components); +``` + +### Obtaining the Entity of a Component + +Continuing from the example of adding a component at the beginning, you can directly obtain the entity of a component: + +```typescript +const entity = directLight.entity; +``` + +### State + +When you temporarily do not need a component, you can actively call the component's [enabled](/apis/core/#Component-enabled). + +```typescript +directLight.enabled = false; +``` diff --git a/docs/en/core/engine.md b/docs/en/core/engine.mdx similarity index 100% rename from docs/en/core/engine.md rename to docs/en/core/engine.mdx diff --git a/docs/en/core/math.md b/docs/en/core/math.mdx similarity index 98% rename from docs/en/core/math.md rename to docs/en/core/math.mdx index 8382e0951d..5bb183269b 100644 --- a/docs/en/core/math.md +++ b/docs/en/core/math.mdx @@ -255,7 +255,7 @@ color2.toLinear(linearColor); ## Plane We can define a plane using a vector (normal) and a distance. The normal represents the direction of the plane based on the coordinate origin, and the plane is perpendicular to the normal. The distance represents the distance of the plane from the coordinate origin along the normal direction. For example, a plane perpendicular to the Y-axis with a distance of 5 is illustrated as follows: -![plane](https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*1HMeRbPQv1kAAAAAAAAAAAAADjCHAQ/original) + The code to create it is as follows: ```typescript @@ -394,7 +394,8 @@ const isIntersect4 = frustum.intersectsSphere(sphere2); ``` ## Ray A ray represents a line that starts from a point (origin) and extends infinitely in a specified direction (direct), as shown below: -![alt text](https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*w2XVQL-K4UEAAAAAAAAAAAAADjCHAQ/original) + + The types of detection supported by rays are as follows: | Type | Description | diff --git a/docs/en/core/prefab.md b/docs/en/core/prefab.md deleted file mode 100644 index 2dfb188484..0000000000 --- a/docs/en/core/prefab.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -order: 10 -title: Prefab -type: Core Concept -label: Core ---- - -## Introduction - -A prefab is an asset that can be seen as a template storing **[entity](/en/docs/core/entity)** data (including its child entities and components). Prefabs allow developers to create and update this template, then instantiate it into the scene as needed. - -If you want to reuse an entity configured in a specific way in multiple locations within a scene or across multiple scenes in a project, such as non-player characters (NPCs), props, or scenery, you should convert this game object into a prefab. This approach is better than simply copying and pasting game objects because prefabs can keep all copies synchronized. - -### Main features of prefabs: - -#### Reusability: -The same prefab can be used in multiple scenes, and any modifications to the prefab can be automatically applied to all instances. - -#### Easy management: -Prefabs can package complex entities (including their child entities and components) into a single asset, making them easier to manage and organize. - -#### Consistency: -By using prefabs, you can ensure that objects used in different scenes or parts remain consistent. - -#### Increased efficiency: -Extensive use of prefabs can reduce repetitive work, making the development process more efficient. - -## Editor Usage - -### Creating a Prefab - -There are two ways to create a prefab - -1. Right-click the entity to create a prefab using this entity as a template -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*1D-6TpXqDWcAAAAAAAAAAAAADsJ_AQ/original) -2. Drag the entity from the **[Hierarchy Panel](/en/docs/interface/hierarchy)** to the **[Assets Panel](/en/docs/assets/interface)** to create a prefab using this entity as a template -![create](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*IXI9Q4ljEu8AAAAAAAAAAAAADsJ_AQ/original) - -### Updating a Prefab - -There are two ways to update a prefab - -#### Global Replacement - -Drag the entity from the **Hierarchy Panel** to the existing prefab asset in the **Assets Panel**, and the prefab asset will be updated with the new content. All instances generated from this prefab will also be updated with the latest content. -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*o0WAR77vPbIAAAAAAAAAAAAADsJ_AQ/original) - -The entity can also be an instance of this prefab -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*A0TpTZs7i3EAAAAAAAAAAAAADsJ_AQ/original) - -#### Apply Instance Modifications - -Instances of a prefab are generated based on the prefab template, and all instances will change with the template. However, each instance may have its own modifications: adding, deleting, or updating child entities and their components. To make the instance's modifications part of the template, you can do the following: - -1. Add child nodes -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mnm8SIA8MXIAAAAAAAAAAAAADsJ_AQ/original) - -2. Delete child nodes -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*AN5YQpYSoNsAAAAAAAAAAAAADsJ_AQ/original) - -3. Modify child nodes -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*CoZKT4O9mzMAAAAAAAAAAAAADsJ_AQ/original) - -4. Add components -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*XFz3TrsJjBoAAAAAAAAAAAAADsJ_AQ/original) - -5. Update components -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mM2dS70ZR7cAAAAAAAAAAAAADsJ_AQ/original) - -6. Delete components -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WC8ZTIv5MK4AAAAAAAAAAAAADsJ_AQ/original) - -### Unpack Prefab Instance - -If you want a prefab instance to disconnect from the prefab so that it does not change with the prefab, you can unpack the prefab instance -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*vtpERpaqb_AAAAAAAAAAAAAADsJ_AQ/original) - -### Delete Prefab - -A prefab is an asset, and the deletion method is the same as other assets. It is worth noting that after deleting the prefab, there are two ways to handle the prefab instances: - -1. All prefab instances are deleted -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*EJEGSZMi7ZAAAAAAAAAAAAAADsJ_AQ/original) -2. All prefab instances are unpacked -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*54i3QYBUsaQAAAAAAAAAAAAADsJ_AQ/original) - - -## Script Usage - -### Load Prefab -The engine object for the prefab asset is [PrefabResource](/apis/loader/#PrefabResource}). -After loading (see [Asset Loading](/en/docs/assets/load)), you can instantiate the prefab using the [instantiate](/apis/loader/#PrefabResource-instantiate}) method. - -```typescript -engine.resourceManager - .load({ url: "Prefab's URL", type: AssetType.Prefab }) - .then((prefab: PrefabResource) => { - const prefabInstanceEntity = prefab.instantiate(); - scene.addRootEntity(prefabInstanceEntity); - }); - -``` diff --git a/docs/en/core/prefab.mdx b/docs/en/core/prefab.mdx new file mode 100644 index 0000000000..d3bb1bec72 --- /dev/null +++ b/docs/en/core/prefab.mdx @@ -0,0 +1,98 @@ +--- +order: 10 +title: Prefab +type: Core Concept +label: Core +--- + +## Introduction + +Prefabs are assets that can be considered as templates storing **[entities](/docs/core/entity)** (including their child entities and components) data. Prefabs allow developers to create and update this template, which can then be instantiated into the scene as needed. + +If you want to reuse entities configured in a specific way across multiple locations in a scene or multiple scenes in a project, such as non-player characters (NPCs), props, or landscapes, you should convert this game object into a prefab. This approach is better than simply copying and pasting game objects because prefabs can keep all copies synchronized. + +### Main Features of Prefabs: + +#### Reusability: +The same prefab can be used in multiple scenes, and any modifications to the prefab can be automatically applied to all instances. + +#### Easy Management: +Prefabs can package complex entities (including their child entities and components) into a single asset, making them easy to manage and organize. + +#### Consistency: +By using prefabs, you can ensure that objects used in different scenes or different parts maintain consistency. + +#### Increased Efficiency: +Extensive use of prefabs can reduce repetitive work, making the development process more efficient. + +## Editor Usage + +### Creating a Prefab + +There are two ways to create a prefab: + +1. Right-click an entity to create a prefab using this entity as a template. + +2. Drag the entity from the **[Hierarchy Panel](/docs/interface/hierarchy)** to the **[Asset Panel](/docs/assets/interface)** to create a prefab using this entity as a template. + + +### Updating a Prefab + +There are two ways to update a prefab: + +#### Global Replacement + +Drag the entity from the **Hierarchy Panel** onto an existing prefab asset in the **Asset Panel**. The prefab asset will be updated with the new content, and all instances created from this prefab will also be updated with the latest content. + + +The entity can also be an instance of this prefab. + + +#### Apply Instance Modifications + +Instances of a prefab are generated based on the prefab template. All instances will change as the template changes, but each instance may have its own modifications: addition, deletion, or updates of child entities and components. To make the modifications of an instance part of the template, you can do the following: + +1. Add child nodes + + +2. Delete child nodes + + +3. Modify child nodes + + +4. Add components + + +5. Update components + + +6. Delete components + + +### Unlink Prefab Instance + +If you want a prefab instance to disconnect from the prefab so that it no longer changes with the prefab, you can unlink the prefab instance. + + +### Deleting a Prefab + +A prefab is an asset, and it can be deleted just like other assets. Note that when a prefab is deleted, there are two ways to handle its instances: + +1. Delete all prefab instances + +2. Unlink all prefab instances + + +## Script Usage + +### Loading a Prefab +The engine object of a prefab asset is [PrefabResource](/apis/loader/#PrefabResource}). After loading a prefab ([Asset Loading](/docs/assets/load)), you can instantiate it using the [instantiate](/apis/loader/#PrefabResource-instantiate}) method. + +```typescript +engine.resourceManager + .load({ url: "Prefab's URL", type: AssetType.Prefab }) + .then((prefab: PrefabResource) => { + const prefabInstanceEntity = prefab.instantiate(); + scene.addRootEntity(prefabInstanceEntity); + }); \ No newline at end of file diff --git a/docs/en/core/scene.mdx b/docs/en/core/scene.mdx index dc0d9221e3..2ccc326c17 100644 --- a/docs/en/core/scene.mdx +++ b/docs/en/core/scene.mdx @@ -5,6 +5,8 @@ type: Core Concept label: Core --- + + Scene, as a scene unit, can facilitate entity tree management, especially for large game scenes. For example: **scene1** and **scene2** as two different scenes can independently manage their own **Entity** trees. Therefore, the lighting components, rendering components, and physical components under the scenes are also isolated from each other and do not affect each other. We can render one or more Scenes simultaneously, or dynamically switch the current Scene according to project logic at specific times. Structurally, each Engine can contain one or more active scenes (currently the editor does not support multiple). Each Scene can have multiple root entities. @@ -17,10 +19,6 @@ Right-click in the **[Assets Panel](/en/docs/assets/interface)** (or the + sign -### Properties Panel - - - ### Ambient Light For details, please refer to the [Ambient Light Tutorial](/en/docs/graphics/light/ambient/) and [Baking Tutorial](/en/docs/graphics/light/bake/). diff --git a/docs/en/core/space.md b/docs/en/core/space.md deleted file mode 100644 index 793f45d665..0000000000 --- a/docs/en/core/space.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -order: 6 -title: Coordinate System -type: Core -label: Core ---- - -The coordinate system plays a very important role in the rendering engine, ensuring the accuracy of rendering results and interactions. By reading this document, you can understand most of the coordinate systems involved in Galacean. It is important to note that the definitions of various spaces differ among different rendering engines. This article only discusses the space standards in Galacean. - -This article will horizontally compare various coordinate spaces according to the `definition of space` and `types of coordinate systems`. The `types of coordinate systems` specifically refer to the `left-handed coordinate system` and the `right-handed coordinate system`, as shown in the figure below: - - - -Defining as a `left-handed coordinate system` or `right-handed coordinate system` will affect the direction of `forward` and the direction of rotation (clockwise or counterclockwise). For the definition of direction, you can imagine aligning your right hand with `+X` and the top of your head with `+Y`. The direction your face is facing is `forward`. You can simply compare the differences between Galacean and Unity: - -- Unity's local coordinates and world coordinate system are both `left-handed coordinate systems`. The pose transformation rotates in a clockwise direction, and the corresponding `forward` direction is `+Z`. Therefore, the camera's direction (viewing direction) is `+Z`. - -- Galacean's local coordinates and world coordinate system are both `right-handed coordinate systems`. The pose transformation rotates in a counterclockwise direction, and the corresponding `forward` direction is `-Z`. Therefore, the camera's direction (viewing direction) is `-Z`. - -## Local Space - -Local space is relative, using the object's own position as the reference coordinate system. Therefore, it is usually described as: "a point in the local space of node A". The local space is a `right-handed coordinate system`. The `Transform` component will automatically calculate the position of each point in the world space according to the following formula. - - - -## World Space - -World space is absolute. The root node is placed in `world space`, and its child nodes inherit its spatial relationship. Like `local space`, `world space` is also a `right-handed coordinate system`. When two nodes are not in the same `local space`, they can be converted to world space to compare their relative positions. - -## Editor Usage - -merge - -Determine the posture of the gizmo in the scene - -| Icon | Option | Content | -| :-------------------------------------------------------------------------------------------------------------------------------- | :----------- | :--------------------------------------------------- | -| | `Local Space` | Keep the Gizmo's rotation relative to the selected entity | -| | `Global Space` | Fix the Gizmo to the world space direction, consistent with the grid direction in the scene | - -## View Space - -`View space` is the local space of the camera. Taking a perspective camera as an example: - - - -## Screen Space - -The definition of screen space is consistent with front-end specifications. It is a two-dimensional coordinate system with the origin at the top-left corner of the canvas. The value range within this space is consistent with the dimensions of the canvas. It is often used in interactions and screen space transformations. - - - -## Viewport Space - -The definition of viewport space is consistent with front-end specifications. By setting the camera's viewport, you can control the target area for rendering. - - - -## 2D Sprites - -When rendering sprites or other 2D elements such as masks, the default is to place the plane on the XoY plane in the local coordinate system: - - - diff --git a/docs/en/core/space.mdx b/docs/en/core/space.mdx new file mode 100644 index 0000000000..38295c9786 --- /dev/null +++ b/docs/en/core/space.mdx @@ -0,0 +1,63 @@ +--- +order: 6 +title: Coordinate System +type: Core +label: Core +--- + +The coordinate system plays a crucial role in a rendering engine, ensuring the accuracy of rendering results and interactions. By reading this document, you can understand most of the coordinate systems involved in Galacean. It is important to note that the definitions of various spaces differ between rendering engines; this document discusses only the spatial standards within Galacean. + +This document will compare various coordinate spaces in terms of `definition of space` and `coordinate system type`. The `coordinate system type` specifically refers to the `left-handed coordinate system` and `right-handed coordinate system`, as shown in the image below: + + + +Defining a system as `left-handed` or `right-handed` affects the direction of `forward` and the direction of rotation (clockwise or counterclockwise). For the definition of direction, you can imagine overlapping your right hand with `+X`, and the top of your head with `+Y`. The direction your face points is `forward`. You can compare the differences between Galacean and Unity: + +- Unity's local and world coordinate systems are `left-handed`. Rotation during transformations is done clockwise, and the `forward` direction corresponds to `+Z`. Therefore, the camera's direction (viewing direction) is `+Z`. + +- Galacean's local and world coordinate systems are `right-handed`. Rotation during transformations is done counterclockwise, and the `forward` direction corresponds to `-Z`. Therefore, the camera's direction (viewing direction) is `-Z`. + +## Local Space + +Local space is relative, using the object's own position as the reference coordinate system. It is usually described as "a point in the local space of node A". Local space uses a `right-handed coordinate system`. The `Transform` component automatically calculates the position of each point in world space using the following formula. + + + +## World Space + +World space is absolute. The root node is placed in `world space`, and its child nodes inherit its spatial relationships. Like `local space`, `world space` also uses a `right-handed coordinate system`. When two nodes are not in the same `local space`, they can be converted to world space for comparison of relative positional relationships. + +## Editor Usage + +merge + +Determine the gizmo's orientation in the scene: + +| Icon | Option | Description | +| :-------------------------------------------------------------------------------------------------------------------------------- | :---------- | :-------------------------------------------------------- | +| | `Local Coordinates` | Keep the Gizmo's rotation relative to the selected entity | +| | `Global Coordinates` | Fix the Gizmo's orientation to align with the world space direction, consistent with the grid direction in the scene | + +## View Space + +`View space` is the local space of the camera. Taking a perspective camera as an example: + + + +## Screen Space + +The definition of screen space is consistent with front-end specifications; it is a 2D coordinate system with the top-left corner of the canvas as the origin. The value range within the space is consistent with the dimensions of the canvas and is frequently used in interaction and screen space conversion. + + + +## Viewport Space + +The definition of viewport space is consistent with front-end specifications. By setting the camera's viewport, you can control the target area of rendering. + + + +## 2D Sprites + +When rendering sprites or masks and other 2D elements, they are by default placed on the XoY plane in the local coordinate system: + + \ No newline at end of file diff --git a/docs/en/core/time.md b/docs/en/core/time.mdx similarity index 100% rename from docs/en/core/time.md rename to docs/en/core/time.mdx diff --git a/docs/en/core/transform.md b/docs/en/core/transform.md deleted file mode 100644 index 7a25aab0c2..0000000000 --- a/docs/en/core/transform.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -order: 7 -title: Transform -type: Core -label: Core ---- - -## Basic Concepts - -`Transform` is a fundamental component that comes with `Entity`. Developers can use it to manage the position, rotation, and scale of `Entity` in both **local space** and **world space**. - -> Combining with Galacean's **[coordinate system](/en/docs/core/space)** will provide a deeper understanding. - - - -## Editor Usage - -merge - -Change the visual transform component of the selected entity by directly using the mouse to manipulate the auxiliary icon axis. - -

Move

- -| Icon | Operation | Shortcut | -| :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :------- | -| | `Switch to Gizmo Move Mode` | W | - -Click the auxiliary axis to drag the selected entity in a single direction. Click the auxiliary plane to drag the selected entity in a single plane. - -

Rotate

- -| Icon | Operation | Shortcut | -| :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :------- | -| | `Switch to Gizmo Rotate Mode` | E | - -Click and drag to change the rotation of the selected entity. -Red represents rotation around the X axis, green represents rotation around the Y axis, and blue represents rotation around the Z axis. - -

Scale

- -| Icon | Operation | Shortcut | -| :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :------- | -| | `Switch to Gizmo Scale Mode` | R | - -点击中心立方体，在所有轴上均匀的缩放选中实体。点击辅助轴，在单个方向缩放选中实体。 - -通过 **[检查器面板](/en/docs/interface/inspector)** 可以为节点设置更精确的位置、旋转和缩放信息。 - -image.png - -## 脚本使用 - -```typescript -// 创建节点 -const scene = engine.sceneManager.activeScene; -const root = scene.createRootEntity("root"); -const cubeEntity = root.createChild("cube"); - -// entity 在创建后会默认自带变换组件 -// 通过变换组件能够对实体进行几何变换 - -// 修改节点位移，旋转，缩放 -transform.position = new Vector3(); -// 也可以 transform.setPosition(0, 0, 0); - -transform.rotation = new Vector3(90, 0, 0); -// 也可以 transform.setRotation(90, 0, 0); - -// 也可以通过实体的属性获取到 transform 组件 -cubeEntity.transform.scale = new Vector3(2, 1, 1); -// 也可以 cubeEntity.transform.setScale(2, 1, 1); - -// 局部位移 cube 实体 -cubeEntity.transform.translate(new Vector3(10, 0, 0), true); - -// 局部旋转 cube 实体 -cubeEntity.transform.rotate(new Vector3(45, 0, 0), true); -``` - -## 组件属性 - -| 属性名称 | 属性释义 | -| :---------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | -| [position](/apis/core/#Transform-position) | 局部位移 | -| [rotation](/apis/core/#Transform-rotation) | 局部旋转 - 欧拉角 | -| [rotationQuaternion](/apis/core/#Transform-rotationquaternion) | 局部旋转 - 四元数 | -| [scale](/apis/core/#Transform-scale) | 局部缩放 | -| [worldPosition](/apis/core/#Transform-worldPosition) | 世界位移 | -| [worldRotation](/apis/core/#Transform-worldRotation) | 世界旋转 - 欧拉角 | -| [worldRotationQuaternion](/apis/core/#Transform-worldRotationQuaternion) | 世界旋转 - 四元数 | -| [lossyWorldScale](/apis/core/#Transform-lossyWorldScale) | 世界有损缩放 - 当父节点有缩放，子节点有旋转时，缩放会倾斜，无法使用 Vector3 正确表示,必须使用 Matrix3x3 矩阵才能正确表示 | -| [localMatrix](/apis/core/#Transform-localMatrix) | 局部矩阵 | -| [worldMatrix](/apis/core/#Transform-worldMatrix) | 世界矩阵 | -| [worldForward](/apis/core/#Transform-worldMatrix) | forward 向量（世界空间中的单位矩阵） | -| [worldRight](/apis/core/#Transform-worldMatrix) | right 向量（世界空间中的单位矩阵） | -| [worldUp](/apis/core/#Transform-worldMatrix) | up 向量（世界空间中的单位矩阵） | - -## Component Methods - -| Method Name | Method Description | -| ----------------------------------------------------------------------- | -------------------------------------- | -| [getWorldUp](/apis/core/#Transform-getWorldUp) | Get the world matrix up vector | -| [getWorldRight](/apis/core/#Transform-getWorldRight) | Get the world matrix right vector | -| [getWorldForward](/apis/core/#Transform-getWorldForward) | Get the world matrix forward vector | -| [lookAt](/apis/core/#Transform-lookAt) | Rotate and ensure the world forward vector points to the target world position | -| [registerWorldChangeFlag](/apis/core/#Transform-registerWorldChangeFlag) | Register world transformation change flag | -| [rotate](/apis/core/#Transform-rotate) | Rotate according to the specified Euler angles | -| [rotateByAxis](/apis/core/#Transform-rotateByAxis) | Rotate around the specified axis by the specified angle | -| [translate](/apis/core/#Transform-translate) | Translate according to the specified direction and distance | - -### The Role of `registerWorldChangeFlag` - -The `transform` component internally uses dirty flags for a lot of computational optimizations. Since the `worldMatrix` property of `transform` is also optimized using dirty flags, if external components need to monitor whether the current `transform`'s `worldMatrix` has changed, they need to get the status of its dirty flag. The `transform` component provides the `registerWorldChangeFlag` method: this method returns an update flag that triggers a change when the current `transform`'s `worldMatrix` is modified. For specific usage, refer to the camera component: - -```typescript -class Camera { - onAwake() { - this._transform = this.entity.transform; - // 注册更新标记 - this._isViewMatrixDirty = this._transform.registerWorldChangeFlag(); - } - get viewMatrix() { - // 当标记更新时，根据 worldMatrix 得到viewMatrix～ - if (this._isViewMatrixDirty.flag) { - this._isViewMatrixDirty.flag = false; - Matrix.invert(this._transform.worldMatrix, this._viewMatrix); - } - return this._viewMatrix; - } -} -``` diff --git a/docs/en/core/transform.mdx b/docs/en/core/transform.mdx new file mode 100644 index 0000000000..c27dc8d900 --- /dev/null +++ b/docs/en/core/transform.mdx @@ -0,0 +1,130 @@ +--- +order: 7 +title: Transform +type: Core +label: Core +--- + +## Basic Concepts + +`Transform` is a basic component that comes with an `Entity`. Developers can use it to manage the position, rotation, and scale of an `Entity` in **local space** and **world space**. + +> For a deeper understanding, refer to Galacean's **[Coordinate System](/docs/core/space)**. + + + +## Editor Usage + +merge + +Change the visualization transform component of the selected entity by directly using the mouse to manipulate the helper gizmo axes. + +

Move

+ +| Icon | Action | Shortcut | +| :-------------------------------------------------------------------------------------------------------------------------------- | :------------------- | :------- | +| | `Switch to Move Mode` | W | + +Click the helper axis to drag the selected entity in a single direction. Click the helper plane to drag the selected entity in a single plane. + +

Rotate

+ +| Icon | Action | Shortcut | +| :-------------------------------------------------------------------------------------------------------------------------------- | :-------------------- | :------- | +| | `Switch to Rotate Mode` | E | + +Click and drag to change the rotation of the selected entity. Red represents rotation around the X-axis, green represents rotation around the Y-axis, and blue represents rotation around the Z-axis. + +

Scale

+ +| Icon | Action | Shortcut | +| :-------------------------------------------------------------------------------------------------------------------------------- | :------------------- | :------- | +| | `Switch to Scale Mode` | R | + +Click the center cube to uniformly scale the selected entity on all axes. Click the helper axis to scale the selected entity in a single direction. + +Through the **[Inspector Panel](/docs/interface/inspector)**, you can set more precise position, rotation, and scale information for nodes. + +image.png + +## Script Usage + +```typescript +// Create a node +const scene = engine.sceneManager.activeScene; +const root = scene.createRootEntity("root"); +const cubeEntity = root.createChild("cube"); + +// An entity comes with a transform component by default upon creation +// The transform component allows for geometric transformations on the entity + +// Modify node translation, rotation, and scale +transform.position = new Vector3(); +// Alternatively, use transform.setPosition(0, 0, 0); + +transform.rotation = new Vector3(90, 0, 0); +// Alternatively, use transform.setRotation(90, 0, 0); + +// You can also access the transform component via the entity's properties +cubeEntity.transform.scale = new Vector3(2, 1, 1); +// Alternatively, use cubeEntity.transform.setScale(2, 1, 1); + +// Translate the cube entity locally +cubeEntity.transform.translate(new Vector3(10, 0, 0), true); + +// Rotate the cube entity locally +cubeEntity.transform.rotate(new Vector3(45, 0, 0), true); +``` + +## Component Properties + +| Property Name | Description | +| :------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | +| [position](/apis/core/#Transform-position) | Local translation | +| [rotation](/apis/core/#Transform-rotation) | Local rotation - Euler angles | +| [rotationQuaternion](/apis/core/#Transform-rotationquaternion) | Local rotation - Quaternion | +| [scale](/apis/core/#Transform-scale) | Local scale | +| [worldPosition](/apis/core/#Transform-worldPosition) | World translation | +| [worldRotation](/apis/core/#Transform-worldRotation) | World rotation - Euler angles | +| [worldRotationQuaternion](/apis/core/#Transform-worldRotationQuaternion) | World rotation - Quaternion | +| [lossyWorldScale](/apis/core/#Transform-lossyWorldScale) | World lossy scale - When the parent node scales and the child node rotates, the scale becomes skewed and cannot be accurately represented by Vector3, requiring a Matrix3x3 for correct representation | +| [localMatrix](/apis/core/#Transform-localMatrix) | Local matrix | +| [worldMatrix](/apis/core/#Transform-worldMatrix) | World matrix | +| [worldForward](/apis/core/#Transform-worldMatrix) | Forward vector (unit vector in world space) | +| [worldRight](/apis/core/#Transform-worldMatrix) | Right vector (unit vector in world space) | +| [worldUp](/apis/core/#Transform-worldMatrix) | Up vector (unit vector in world space) | + +## Component Methods + +| Method Name | Description | +| --------------------------------------------------------------------- | --------------------------------------- | +| [getWorldUp](/apis/core/#Transform-getWorldUp) | Get the up vector from the world matrix | +| [getWorldRight](/apis/core/#Transform-getWorldRight) | Get the right vector from the world matrix | +| [getWorldForward](/apis/core/#Transform-getWorldForward) | Get the forward vector from the world matrix | +| [lookAt](/apis/core/#Transform-lookAt) | Rotate and ensure the world forward vector points to the target world position | +| [registerWorldChangeFlag](/apis/core/#Transform-registerWorldChangeFlag) | Register a flag for world transformation changes | +| [rotate](/apis/core/#Transform-rotate) | Rotate by a specified Euler angle | +| [rotateByAxis](/apis/core/#Transform-rotateByAxis) | Rotate by a specified angle around a specified axis | +| [translate](/apis/core/#Transform-translate) | Translate by a specified direction and distance | + +### Purpose of `registerWorldChangeFlag` + +The `transform` component internally uses a dirty flag for a lot of computational optimization. Since the `worldMatrix` property of `transform` is also optimized with a dirty flag, if external components need to track whether the current `transform`'s `worldMatrix` has changed, the state of its dirty flag needs to be obtained. The `transform` component provides the `registerWorldChangeFlag` method: this method returns an update flag, which will be triggered when the `worldMatrix` of the current `transform` is modified. For specific usage, refer to the camera component: + +```typescript +class Camera { + onAwake() { + this._transform = this.entity.transform; + // Register the update flag + this._isViewMatrixDirty = this._transform.registerWorldChangeFlag(); + } + get viewMatrix() { + // When the flag is updated, derive the viewMatrix from the worldMatrix + if (this._isViewMatrixDirty.flag) { + this._isViewMatrixDirty.flag = false; + Matrix.invert(this._transform.worldMatrix, this._viewMatrix); + } + return this._viewMatrix; + } +} +``` \ No newline at end of file diff --git a/docs/en/interface/inspector.md b/docs/en/interface/inspector.md deleted file mode 100644 index 4baf36fcac..0000000000 --- a/docs/en/interface/inspector.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -order: 4 -title: Inspector Panel -type: Basics -group: Interface -label: Basics/Interface ---- - -The Inspector panel is located on the right side of the editor and will be the most frequently used panel during your use of the editor. Based on what you currently have selected, the Inspector panel will display the corresponding properties. You can use the Inspector panel to edit almost everything in the scene, such as scenes, entities, assets, etc. - - - -## Types of Inspectors - -### Scene Inspector - - - -The scene is at the top of the hierarchy tree. By clicking on the scene, you can see that the Inspector provides adjustments for scene-related effects such as ambient light, background, shadows, fog, etc. For detailed parameters on how to edit these elements, see [Scene](/en/docs/core/scene). - - - -### Entity Inspector - -The Entity Inspector is the most commonly used inspector. Its properties include the current entity's component list. You can easily modify the properties of a component or conveniently add any built-in engine components and custom script components through the **Add Component** button. The Entity Inspector also includes basic information about the current entity, such as `Transform`, `Layer`, etc. For more details, see [Entity](/en/docs/core/entity). - - - -### Asset Inspector - -After selecting an asset in the asset panel, the Inspector will display the various properties of the current asset and provide a previewer to show the editing results in real-time. The following image is a screenshot of the Inspector for a material asset. - - - -## Using Inspector Controls - -Inspector controls can be divided into two main categories: - -- **Basic Value Types**: Number adjustment, color selection, property toggling, etc. -- **Reference Types**: Usually resources, such as material selection, texture selection, etc. - -### Number Adjustment Controls - -The Inspector provides many entry points for number adjustments. Depending on the property, the range of adjustable numbers and the size of each adjustment will vary. The most typical example is adjusting the position, rotation, and scale values of the `Transform` component. - -You can quickly adjust the number size by dragging the slider on the right side of the input box. While dragging, holding down ⌘ (on Windows, Ctrl) allows for more precise number adjustments (precision is 1/10 of the original step). - - - -Some adjustable properties appear in the form of sliders. You can drag the slider to quickly adjust the number size, such as the `Intensity` of a light. Similarly, while dragging the slider, holding down `⌘` (on Windows, `ctrl`) allows for more precise number adjustments. - - - -Some number adjustment properties appear in the form of input boxes and buttons, such as the `Near Plane` of shadows. These properties often have more precise step sizes (e.g., 0.1, 1, 10). Clicking the buttons can directly increase or decrease the value by the step length. - - - -### Color Picker - -Some properties require color adjustments, such as lighting, scene background color, or the emissive color of a material. To adjust the color, you need to click the color button on the left to bring up the color picker. In the color picker, you can use HUE to select the color and adjust the color's transparency; you can also adjust the specific RGBA values in the input box. Click the button to switch between HSLA, RGBA, and HEXA modes. - - - -### Asset Picker - -Some properties require referencing the necessary assets. In this case, you can click the input box of the asset picker to bring up the asset picker. Different properties require different types of assets, but the asset picker is already configured with the appropriate filters, so you can select directly. - -The asset picker also provides a search box, which you can use to find the corresponding assets more precisely. - - diff --git a/docs/en/interface/inspector.mdx b/docs/en/interface/inspector.mdx new file mode 100644 index 0000000000..fb856a82e4 --- /dev/null +++ b/docs/en/interface/inspector.mdx @@ -0,0 +1,70 @@ +--- +order: 4 +title: Inspector Panel +type: Basics +group: Interface +label: Basics/Interface +--- + +The Inspector panel is located on the right side of the editor, and it is likely to be the panel you use most frequently when working with the editor. Depending on what you currently have selected, the Inspector panel will display the corresponding properties. You can use the Inspector panel to edit almost everything in the scene, such as scenes, entities, assets, etc. + + + +## Inspector Types + +### Scene Inspector + + + +The scene is located at the top of the hierarchy tree. By clicking and selecting the scene, you can see that the Inspector provides adjustments for scene-related effects such as ambient light, background, shadows, fog, etc. For detailed parameters on how to edit these elements, please refer to [Scenes](/docs/core/scene). + + + +### Entity Inspector + +The Entity Inspector is the most commonly used inspector. Its properties include the component list of the current entity. You can easily modify the properties of a component or add any built-in engine component and custom script component via the **Add Component** button. The Entity Inspector also includes the basic information of the current entity, such as `Transform`, `Layer`, etc. See [Entities](/docs/core/entity) for more details. + + + +### Asset Inspector + +After selecting an asset in the asset panel, the Inspector will display various properties of the current asset and provide a previewer to display the editing results in real time. Below is a screenshot of a material asset's inspector. + + + +## Using Inspector Controls + +Inspector controls can be divided into two main categories: + +- **Basic Value Types**: Number adjustment, color selection, attribute switching, etc. +- **Reference Types**: Usually resources, such as material selection, texture selection, etc. + +### Number Adjustment Controls + +The Inspector provides many entry points for number adjustment. Depending on different attributes, the adjustable range of numbers and the size of each adjustment can vary. The most typical example is adjusting the position, rotation, and scale property values of the `Transform` component. + +You can quickly adjust the size of a number by dragging the slider on the right side of the input box. While dragging, holding down ⌘ (or Ctrl on Windows) allows for more precise adjustments (precision is 1/10 of the original step). + + + +Some adjustable properties appear as sliders. You can drag the slider to quickly adjust the size of a number, such as the `Intensity` of a light. Similarly, holding `⌘` (or `Ctrl` on Windows) while dragging the slider allows for more precise adjustments. + + + +Other number adjustment properties appear as input boxes and buttons, such as the `Near Plane` of shadows. These properties often have more precise step sizes (e.g., 0.1, 1, 10). Clicking the button can increase or decrease the value directly by the step length. + + + +### Color Selection Controls + +Some properties require color adjustments, such as lighting, scene background color, or material emissive color. To adjust the color, you need to click the color button on the left to bring up the color picker. In the color picker, you can use HUE to select a color and adjust the transparency; you can also adjust the specific RGBA values of the color in the input box. Clicking the button allows you to switch between HSLA, RGBA, and HEXA modes. + + + +### Asset Selection Controls + +Some properties need to reference required assets. In such cases, you can click the input box of the asset selector to bring up the asset selector. Different attributes require different types of assets, but the asset selector is already pre-configured with appropriate filters, so you can select directly. + +The asset selector also provides a search box, which you can use to find the corresponding asset more precisely. + + \ No newline at end of file diff --git a/docs/en/interface/shortcut.md b/docs/en/interface/shortcut.mdx similarity index 66% rename from docs/en/interface/shortcut.md rename to docs/en/interface/shortcut.mdx index fb7f5ea53a..cf91db0bab 100644 --- a/docs/en/interface/shortcut.md +++ b/docs/en/interface/shortcut.mdx @@ -8,5 +8,5 @@ label: Basics/Interface Shortcuts help improve the efficiency of editing scenes. Users can find the viewport control methods for the mouse (or touchpad) and keyboard, as well as global and panel-specific shortcuts, in the main menu under `Shortcuts`. -image-20230925164702582 +image-20230925164702582 diff --git a/docs/en/interface/template.md b/docs/en/interface/template.mdx similarity index 72% rename from docs/en/interface/template.md rename to docs/en/interface/template.mdx index 3388f33af9..9d04c73b13 100644 --- a/docs/en/interface/template.md +++ b/docs/en/interface/template.mdx @@ -8,5 +8,6 @@ label: Basics/Interface Business templates are currently divided into categories such as animation, special effects, 2D, 3D, XR, and digital humans. By clicking on a template, you can view project details, preview the project, and replicate the project locally. - + + diff --git a/docs/en/interface/viewport.md b/docs/en/interface/viewport.md deleted file mode 100644 index 15253091e5..0000000000 --- a/docs/en/interface/viewport.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -order: 6 -title: Viewport -type: Basics -group: Interface -label: Basics/Interface ---- - -## Introduction - -The viewport window is an interactive interface used to select, position, and change various types of entities and components in the current scene. - -drag5 - -## Browsing the Scene - -There are two ways to browse the scene: standard mode and flight mode. Standard mode rotates around the center viewpoint, while flight mode is suitable for browsing large scenes, where the scene camera moves forward, backward, left, right, up, and down in three-dimensional space. - -| Mode | Operation | Shortcut Key | -| :------------ | :-------------- | ---------------------------------------------------------------------- | -| **Standard Mode** | Orbit | `alt` + left mouse button | -| | Pan | `alt` + `command` + left mouse button, or press the mouse wheel | -| | Zoom | `alt` + `control` + left mouse button, or scroll the mouse wheel, or swipe with two fingers on the touchpad | -| **Flight Mode** | Look around | `alt` + right mouse button | -| | Move forward | Up arrow key, or right mouse button + `W` | -| | Move backward | Down arrow key, or right mouse button + `S` | -| | Move left | Left arrow key, or right mouse button + `A` | -| | Move right | Right arrow key, or right mouse button + `D` | -| | Move up | Right mouse button + `E` | -| | Move down | Right mouse button + `Q` | -| | Change flight speed | Right mouse button + mouse wheel | - -## Toolbar - -The toolbar is located at the top of the viewport window. Hovering the mouse over each item will display its shortcut key or description. - -image-20240131181207870 - -| Icon | Name | Description | Shortcut Key | -| --- | --- | --- | --- | -| image-20240131175906508 | Drag | Drag the view | | -| image-20240131180117064
image-20240131180217044
image-20240131180256738 | Move
Rotate
Scale | Transform the selected entity | `W`
`E`
`R` | -| image-20240131180403373
image-20240131180513384 | Center Pivot/Hub Pivot | Switch the pivot of the selected entity | | -| image-20240131180709163
image-20240131180731465 | Local Coordinates/World Coordinates | Switch the coordinates of the selected entity | | -| image-20240131181105676 | Focus | Focus the scene camera on the selected entity | `F` | -| image-20240131181429677 | Scene Camera | The scene camera menu contains options for configuring the scene camera, mainly used to solve the problem of objects not being visible when the clipping plane is too far or too close while building the scene. These adjustments will not affect the settings of entities with camera components in the scene. | | -| image-20240131181144755 | Settings | The settings menu contains options for adjusting auxiliary displays in the view, including grids, auxiliary icons (graphics associated with specific components in the scene, including cameras, directional lights, point lights, spotlights), and auxiliary wireframes | | -| image-20240131181242445
image-20240131181524219 | Scene Camera Type | Switch between perspective/orthographic camera | | -| image-20240131181459432
image-20240131181607999 | Mode | Convenient for switching between 2D/3D scene modes with a click. In 2D mode, navigation components, orthographic/perspective switching are disabled, and orbiting in navigation is no longer effective. | | -| image-20240131182235406 | Fullscreen/Restore | Maximize the viewport window, minimize the hierarchy, assets, and inspector | | -| | Play | Play all particles and animations in the scene | -| image-20240131182303867 | Screenshot | Take a snapshot of the current scene. Only user-created entities in the scene are displayed; a series of auxiliary display tools such as icons, grids, and gizmos will not be included. After taking a screenshot, the snapshot will be used as the project thumbnail on the homepage. | - -### Auxiliary Elements Settings Interface - - - -| Attribute | Content | -| --- | --- | -| Grid | Whether the grid in the view is displayed | -| 3D Icons | Whether auxiliary icons scale based on the distance between the component and the camera | -| Navigation Gimzo | Used to display the current direction of the scene camera and can quickly modify the view and projection mode (orthographic/perspective) through mouse operations. When enabled, it will be displayed in the lower right corner of the screen.
image-20240131184405058 | -| Outline | Whether to display the outline when an entity is selected. The outline color of the selected entity is orange, and the outline of child nodes is blue | -| Camera | Display the selected camera component as a cone | -| Light | Display light source components | -| Static Collider | Display the shape of static colliders | -| Dynamic Collider | Display the shape of dynamic colliders | -| Emission Shape | Display the shape of particle emitters | - -### Scene Camera Settings Interface - -image-20240131185805023 - -| Attribute | Content | Default Value | -| :---------------------------- | :-------------------------------------------------------------- | :-------------------- | -| Fov | The field of view of the scene camera | 60 | -| Dynamic Clipping | Automatically calculate the near and far clipping planes of the scene camera relative to the selected entity and the scene camera position | Off | -| Near Plane | Manually adjust the nearest point relative to the scene camera | Enabled when dynamic clipping is unchecked | -| Far Plane | Manually adjust the farthest point relative to the scene camera | Enabled when dynamic clipping is unchecked | -| Speed | The movement speed of the camera in flight mode | 10 | -| Opaque Texture | Enable opaque texture for the scene camera | Off | -| HDR | Enable HDR for the scene camera | Off | -| Post Process | Enable post-processing for the scene camera | On | - -## Preview - -When an entity with a camera component is selected, a real-time preview of the camera will be displayed in the lower left corner of the view window. This helps users to adjust the camera and scene position in real-time. The preview window can be dragged, locked, and switched to different device aspect ratios. - -image-20240131190013320 - - -| Attribute | Content | -| :-------- | :------------------------------ | -| Drag | Freely drag the preview window | -| Position | Position the camera in the scene | -| Switch Ratio | Switch windows of different devices and ratios | -| Lock | Lock the camera preview window | - -In the hierarchy tree, objects containing camera components can directly synchronize the relevant properties of the scene camera in the view, making it convenient to adjust the position and perspective. - - - diff --git a/docs/en/interface/viewport.mdx b/docs/en/interface/viewport.mdx new file mode 100644 index 0000000000..3927d8b974 --- /dev/null +++ b/docs/en/interface/viewport.mdx @@ -0,0 +1,100 @@ +--- +order: 6 +title: Viewport +type: Basics +group: Interface +label: Basics/Interface +--- + +## Introduction + +The view window is an interactive interface used for selecting, positioning, and changing various types of entities and components in the current scene. + + + +## Browsing the Scene + +There are two ways to browse the scene: standard mode and flying mode. Standard mode revolves around the central viewpoint, while flying mode is suitable for browsing large scenes, allowing the scene camera to move forward, backward, left, right, up, and down in 3D space. + +| Mode | Action | Shortcut Keys | +| :------------ | :-------------------- | ------------------------------------------------------------------ | +| **Standard** | Orbit rotation | `alt` + Left Mouse Button | +| | Panning | `alt` + `command` + Left Mouse Button, or press the mouse wheel | +| | Zooming | `alt` + `control` + Left Mouse Button, or scroll mouse wheel, or swipe with two fingers on a trackpad | +| **Flying** | Look around camera | `alt` + Right Mouse Button | +| | Move forward | Up Arrow or Right Mouse Button + `W` | +| | Move backward | Down Arrow or Right Mouse Button + `S` | +| | Strafe left | Left Arrow or Right Mouse Button + `A` | +| | Strafe right | Right Arrow or Right Mouse Button + `D` | +| | Move up | Right Mouse Button + `E` | +| | Move down | Right Mouse Button + `Q` | +| | Change flying speed | Right Mouse Button + Mouse Wheel | + +## Toolbar + +The toolbar is located at the top of the view window. Hovering the mouse over each item will show the shortcut keys or description. + +image-20240131181207870 + +| Icon | Name | Description | Shortcut | +| --- | --- | --- | --- | +| | Drag | Drag the screen | | +|

| Move
Rotate
Scale | Transform the selected entity | `W`
`E`
`R` | +|
| Center Anchor/Hub Anchor | Switch the anchor point of the selected entity | | +|
| Local/World Coordinates | Switch the coordinates of the selected entity | | +| | Focus | Focus the scene camera on the selected entity | `F` | +| | Scene Camera | The scene camera menu contains options for configuring the scene camera, mainly to solve issues where objects are not visible because the clipping plane is too far or too near. These adjustments do not affect settings of entities with camera components in the scene. | | +| | Settings | The settings menu contains options to adjust view auxiliary displays, including grids, auxiliary icons (graphics associated with specific components in the scene, including camera, direct light, point light, spotlight), and auxiliary wireframes. | | +|
| Scene Camera Type | Switch between perspective/orthographic camera | | +|
| Mode | Conveniently switch between 2D/3D scene modes. In 2D mode, navigation components, and perspective/orthographic toggle are disabled, and orbit rotation in navigation is no longer effective. | | +| | Fullscreen/Restore | Maximize the view window, minimize hierarchy, assets, inspector | | +| | Play | Play all particles and animations in the scene | +| | Screenshot | Take a snapshot of the current scene. Only user-created entities in the scene are shown, and a series of auxiliary tools like icons, grids, gizmo won't be included. After taking a screenshot, the snapshot will be used as the project thumbnail on the homepage. | + +### Auxiliary Element Settings Interface + + + +| Property | Description | +| --- | --- | +| Grid | Whether the grid is displayed in the view | +| 3D Icons | Whether auxiliary icons scale based on their distance from the camera | +| Navigation Gizmo | Used to display the current direction of the scene camera and can be quickly modified by mouse operation to adjust the view and projection mode (orthographic/perspective). It will appear at the bottom right corner of the screen when open.
image-20240131184405058 | +| Outline | Whether outlines are displayed when an entity is selected. The outline of the selected entity is orange, and child nodes are blue. | +| Camera | Display the selected camera component as a cone | +| Light | Display light source components | +| Static Collider | Show static collider shapes | +| Dynamic Collider | Show dynamic collider shapes | +| Emission Shape | Show particle emitter shapes | + +### Scene Camera Settings Interface + + + +| Property | Description | Default Value | +| :----------------------------- | :----------------------------------------------------- | :------------------- | +| Fov | Field of view of the scene camera | 60 | +| Dynamic Clipping | Automatically calculates near and far clipping planes relative to the selected entity and scene camera position | Off | +| Near Plane | Manually adjust the nearest point relative to the scene camera | Enabled when dynamic clipping is unchecked | +| Far Plane | Manually adjust the farthest point relative to the scene camera | Enabled when dynamic clipping is unchecked | +| Speed | Movement speed of the camera in flying mode | 10 | +| Opaque Texture | Enable opaque texture for the scene camera | Off | +| HDR | Enable HDR for the scene camera | Off | +| Post Process | Enable post-processing for the scene camera | On | + +## Preview + +When an entity with a camera component is selected, the real-time preview of that camera will be displayed at the bottom left of the view window. This helps users adjust the camera and scene position in real-time. The preview window can be dragged, locked, and switched between different device proportions. + +image-20240131190013320 + +| Property | Description | +| :----------- | :-------------------------------- | +| Drag | Freely drag the preview window | +| Position | Locate this camera in the scene | +| Switch Ratio | Switch between different device and ratio windows | +| Lock | Lock the camera preview window | + +Objects containing camera components in the hierarchy tree can directly sync the scene camera's attributes, making position and view adjustments convenient. + + \ No newline at end of file diff --git a/docs/zh/core/canvas.md b/docs/zh/core/canvas.mdx similarity index 100% rename from docs/zh/core/canvas.md rename to docs/zh/core/canvas.mdx diff --git a/docs/zh/core/clone.md b/docs/zh/core/clone.mdx similarity index 100% rename from docs/zh/core/clone.md rename to docs/zh/core/clone.mdx diff --git a/docs/zh/core/component.md b/docs/zh/core/component.mdx similarity index 72% rename from docs/zh/core/component.md rename to docs/zh/core/component.mdx index 730e91dfd9..705564bebc 100644 --- a/docs/zh/core/component.md +++ b/docs/zh/core/component.mdx @@ -5,7 +5,7 @@ type: 核心 label: Core --- -在 Galacean 引擎中，[Entity](/apis/core/#Entity) 不具备渲染模型等实际的功能，这些功能是通过加载 [Component](/apis/core/#Component) 组件类来实现的。例如，如果想让一个 _Entity_ 变成一个相机，只需要在该 _Entity_ 上添加相机组件 [Camera](/apis/core/#Camera)。这种基于组件的功能扩展方式注重将程序按照功能独立封装，在使用的时候按照需要组合添加，非常有利于降低程序耦合度并提升代码复用率。 +[Entity](/apis/core/#Entity) 不具备渲染模型等实际的功能，这些功能是通过加载 [Component](/apis/core/#Component) 组件类来实现的。例如，如果想让一个 _Entity_ 变成一个相机，只需要在该 _Entity_ 上添加相机组件 [Camera](/apis/core/#Camera)。这种基于组件的功能扩展方式注重将程序按照功能独立封装，在使用的时候按照需要组合添加，非常有利于降低程序耦合度并提升代码复用率。 常用组件： @@ -28,23 +28,23 @@ label: Core 从 **[层级面板](/docs/interface/hierarchy)** 或场景中选择一个实体后，检查器将显示出当前选中节点挂载的所有组件，组件名显示在左上角 -Name +Name 你可以在检查器中控制它是否 enabled -Enable +Enable 如果不需要它也可以将它删除 -Delete +Delete 或者编辑它的各种属性 -Edit +Edit 如果是个空节点，你可以点击 `Add Component` 按钮来为当前实体添加新的组件。 -image-20230926112713126 +image-20230926112713126 ## 脚本使用 diff --git a/docs/zh/core/engine.md b/docs/zh/core/engine.mdx similarity index 100% rename from docs/zh/core/engine.md rename to docs/zh/core/engine.mdx diff --git a/docs/zh/core/math.md b/docs/zh/core/math.mdx similarity index 98% rename from docs/zh/core/math.md rename to docs/zh/core/math.mdx index 855418c8a4..1e588dc39d 100644 --- a/docs/zh/core/math.md +++ b/docs/zh/core/math.mdx @@ -256,8 +256,7 @@ color2.toLinear(linearColor); ## 平面 我们可以通过一个向量(normal)和距离(distance)来确定一个平面，normal 表示平面基于坐标原点的方向，平面和 normal 垂直，distance 表示平面沿着 normal 方向距离坐标原点的距离。我们以垂直 Y 轴的平面，并且距离为 5 为例，图示如下： -![plane](https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*1HMeRbPQv1kAAAAAAAAAAAAADjCHAQ/original) - + 代码创建方式如下： ```typescript @@ -396,7 +395,8 @@ const isIntersect4 = frustum.intersectsSphere(sphere2); ``` ## 射线 射线表示从一个点（origin）出发，往指定方向（direct）发射的一个可以无限延伸的线，如下： -![alt text](https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*w2XVQL-K4UEAAAAAAAAAAAAADjCHAQ/original) + + 射线支持的检测类型如下： | 类型 | 解释 | diff --git a/docs/zh/core/prefab.md b/docs/zh/core/prefab.mdx similarity index 68% rename from docs/zh/core/prefab.md rename to docs/zh/core/prefab.mdx index 7a72397e43..0a4e436932 100644 --- a/docs/zh/core/prefab.md +++ b/docs/zh/core/prefab.mdx @@ -32,9 +32,9 @@ label: Core 有两种方式可以创建预制体 1. 右键实体即可创建以此实体作为模版的预制体 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*1D-6TpXqDWcAAAAAAAAAAAAADsJ_AQ/original) + 2. 将实体从 **[层级面板](/docs/interface/hierarchy)** 拖到 **[资产面板](/docs/assets/interface)** 中即可创建以此实体作为模版的预制体 -![create](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*IXI9Q4ljEu8AAAAAAAAAAAAADsJ_AQ/original) + ### 更新预制体 @@ -43,46 +43,46 @@ label: Core #### 全局替换 将实体从 **层级面板** 拖到 **资产面板** 中已有的预制体资产上，预制体资产将会更新为新内容，同时所有由此预制体产生的实例也会更新为最新内容。 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*o0WAR77vPbIAAAAAAAAAAAAADsJ_AQ/original) + 实体也可以是此预制体的实例 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*A0TpTZs7i3EAAAAAAAAAAAAADsJ_AQ/original) + #### 应用实例的修改 预制体的实例是基于预制体模版生成的，所有的实例都会随着模版的更改而更改，但是每个实例可能会有自身的修改：子实体及其组件的添加，删除，更新。想要将实例自身的修改内容变为模版内容可以通过如下方式: 1. 添加子节点 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mnm8SIA8MXIAAAAAAAAAAAAADsJ_AQ/original) + 2. 删除子节点 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*AN5YQpYSoNsAAAAAAAAAAAAADsJ_AQ/original) + 3. 修改子节点 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*CoZKT4O9mzMAAAAAAAAAAAAADsJ_AQ/original) + 4. 添加组件 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*XFz3TrsJjBoAAAAAAAAAAAAADsJ_AQ/original) + 5. 更新组件 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*mM2dS70ZR7cAAAAAAAAAAAAADsJ_AQ/original) + 6. 删除组件 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WC8ZTIv5MK4AAAAAAAAAAAAADsJ_AQ/original) + ### 解开预制体实例 如果想让一个预制体实例与预制体断开联系，使其不随着预制体更改而更改，可以将预制体实例解开 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*vtpERpaqb_AAAAAAAAAAAAAADsJ_AQ/original) + ### 删除预制体 预制体是一个资产，删除的方式同其他资产一样。值得注意的是，删除预制体后预制体实例的处理方式有两种 1. 预制体实例全部删除 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*EJEGSZMi7ZAAAAAAAAAAAAAADsJ_AQ/original) + 2. 预制体实例全部解开 -![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*54i3QYBUsaQAAAAAAAAAAAAADsJ_AQ/original) + ## 脚本使用 diff --git a/docs/zh/core/scene.mdx b/docs/zh/core/scene.mdx index 701259554d..6e901f9599 100644 --- a/docs/zh/core/scene.mdx +++ b/docs/zh/core/scene.mdx @@ -5,6 +5,8 @@ type: 核心概念 label: Core --- + + Scene 作为场景单元，可以方便的进行实体树管理，尤其是大型游戏场景。如: **scene1** 和 **scene2** 作为两个不同的场景，可以各自独立管理其拥有的 **Entity** 树，因此场景下的光照组件、渲染组件和物理组件之间也互相隔离，互不影响。我们可以同时渲染一个或多个 Scene，也可以在特定时机下根据项目逻辑动态切换当前 Scene。 从结构上每个 Engine 下可以包含一个和多个激活的场景（目前编辑器还不支持多个）。每个 Scene 可以有多个根实体。 @@ -17,10 +19,6 @@ Scene 作为场景单元，可以方便的进行实体树管理，尤其是大 -### 属性面板 - - - ### 环境光 详情请参照[环境光教程](/docs/graphics/light/ambient/) 和 [烘焙教程](/docs/graphics/light/bake/)。 diff --git a/docs/zh/core/space.md b/docs/zh/core/space.mdx similarity index 68% rename from docs/zh/core/space.md rename to docs/zh/core/space.mdx index 70d0cb5437..025dfc0f9f 100644 --- a/docs/zh/core/space.md +++ b/docs/zh/core/space.mdx @@ -9,7 +9,7 @@ label: Core 本文会按照`空间的定义`，`坐标系类型`等方面来横向比较各个坐标空间，其中`坐标系类型`具体指`左手坐标系`与`右手坐标系`，如下图所示： - + 定义为`左手坐标系`或`右手坐标系`会影响 `forward` 的朝向与旋转的方向（逆时针或顺时针），对于朝向的定义可以想象着将右手与 `+X` 重合，头顶方向与 `+Y` 重合，此时面部朝向的方向就是 `forward` ，可以简单对比 Galacean 与 Unity 的差异： @@ -21,7 +21,7 @@ label: Core 局部空间是相对的，它以物体的自身位置为参考坐标系的，因此描述的时候通常表示为：“ A 节点局部空间中的某个点”，局部空间是`右手坐标系`， `Transform` 组件会按照以下公式自动计算各个点在世界空间中的位置。 - + ## 世界空间 @@ -29,36 +29,36 @@ label: Core ## 编辑器使用 -merge +merge 确定 gizmo 在场景中姿态 | 图标 | 选项 | 内容 | | :-------------------------------------------------------------------------------------------------------------------------------- | :--------- | :------------------------------------------------ | -| | `本地坐标` | 保持 Gizmo 相对于选中实体的旋转 | -| | `全局坐标` | 固定 Gizmo 与世界空间方向。即与场景中网格方向一致 | +| | `本地坐标` | 保持 Gizmo 相对于选中实体的旋转 | +| | `全局坐标` | 固定 Gizmo 与世界空间方向。即与场景中网格方向一致 | ## 观察空间 `观察空间`就是相机的局部空间，以透视相机为例： - + ## 屏幕空间 屏幕空间的定义与前端规范保持一致，是以画布的左上角为坐标原点的二维空间坐标系，空间内的取值范围与画布的尺寸保持一致，在交互，屏幕空间转换时经常使用。 - + ## 视口空间 视口空间的定义与前端规范保持一致，通过设置相机的 viewport 可以控制渲染的目标区域， - + ## 2D 精灵 渲染精灵或遮罩等 2D 元素时，默认在局部坐标系中的 XoY 平面上放置这个面片： - + diff --git a/docs/zh/core/time.md b/docs/zh/core/time.mdx similarity index 100% rename from docs/zh/core/time.md rename to docs/zh/core/time.mdx diff --git a/docs/zh/core/transform.md b/docs/zh/core/transform.mdx similarity index 95% rename from docs/zh/core/transform.md rename to docs/zh/core/transform.mdx index ac7c4e9186..0b0f605096 100644 --- a/docs/zh/core/transform.md +++ b/docs/zh/core/transform.mdx @@ -15,7 +15,7 @@ label: Core ## 编辑器使用 -merge +merge 更改选中实体的可视化变换组件，直接使用鼠标操纵辅助图标轴。 @@ -23,7 +23,7 @@ label: Core | 图标 | 操作 | 快捷键 | | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :----- | -| | `切换到 Gizmo 移动模式` | W | +| | `切换到 Gizmo 移动模式` | W | 点击辅助轴，可在单个方向内拖动选中实体。点击辅助平面，可在单个平面内拖动选中实体。 @@ -31,7 +31,7 @@ label: Core | 图标 | 操作 | 快捷键 | | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :----- | -| | `切换到 Gizmo 选择模式` | E | +| | `切换到 Gizmo 选择模式` | E | 点击并拖动以更改选中实体的旋转。 红色代表绕 X 轴进行旋转，绿色代表绕 y 轴进行旋转，蓝色代表绕 z 轴进行旋转。 @@ -40,13 +40,13 @@ label: Core | 图标 | 操作 | 快捷键 | | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :----- | -| | `切换到 Gizmo 缩放模式` | R | +| | `切换到 Gizmo 缩放模式` | R | 点击中心立方体，在所有轴上均匀的缩放选中实体。点击辅助轴，在单个方向缩放选中实体。 通过 **[检查器面板](/docs/interface/inspector)** 可以为节点设置更精确的位置、旋转和缩放信息。 -image.png +image.png ## 脚本使用 diff --git a/docs/zh/interface/inspector.md b/docs/zh/interface/inspector.mdx similarity index 69% rename from docs/zh/interface/inspector.md rename to docs/zh/interface/inspector.mdx index 7201f584fd..f1085e59e2 100644 --- a/docs/zh/interface/inspector.md +++ b/docs/zh/interface/inspector.mdx @@ -8,29 +8,29 @@ label: Basics/Interface 检查器面板位于编辑器右侧，它会是你在使用编辑器的过程中最常用的面板。基于你当前选择所选择的东西，检查器面板会显示出相对应的属性。你可以使用检查器面板来编辑场景中几乎所有的事物，如场景、实体、资产等。 - + ## 检查器类型 ### 场景检查器 - + 场景位于层级树的最顶层，点击选中场景，可以看到检查器中提供了包含环境光、背景、阴影、雾等场景相关的效果调整。这些元素的详细参数如何编辑请看[场景](/docs/core/scene)。 - + ### 实体检查器 实体检查器是最常用的检查器，它的属性包含了当前实体的组件列表。你可以很方便地修改某个组件的属性，也可以通过 **Add Component** 按钮方便地添加任何引擎内置的组件和自定义的脚本组件。实体检查器也包含当前实体的基本信息，比如 `Transform`、`Layer` 等。详见[实体](/docs/core/entity)。 - + ### 资产检查器 在资产面板中选中某个资产后，检查器就会显示当前资产的各个属性，并且提供了一个预览器实时展示编辑的结果。下图是一个材质资产的检查器截图。 - + ## 检查器控件的使用 @@ -45,21 +45,21 @@ label: Basics/Interface 你可以通过拖拽输入框右侧的滑块来快速调整数字的大小。在拖拽时，按住 ⌘（window 上为 Ctrl）可以更精确地调整数字的大小（精度为原 step 的 1/10）。 - + 一些可以调节的属性是以滑动条的形式出现的。你可以拖动滑块来快速调整数字的大小，如灯光的 `Intensity`。同样的，在拖动滑块时，按住 `⌘`（window 上为 `ctrl`）可以更精确的调整数字的大小。 - + 还有一些数字调节的属性是以输入框和按钮的形式出现的，如阴影的 `Near Plane`。这些属性往往拥有更精确的步进大小（如 0.1, 1, 10）。点击按钮可以直接以步进长度来增加或减小数值。 - + ### 颜色选择控件 -一些属性需要调整颜色，如光照、场景的背景色，亦或者材质的自发光颜色等。想要调整颜色，你需要点击左侧的颜色按钮来唤起颜色选择器。在颜色选择器中，你可以使用 HUE 来选择颜色，调整颜色的透明度；也可以在输入框来调整颜色具体的 RGBA 数值。点击 按钮可以在 HSLA，RGBA 和 HEXA 三种模式下进行切换。 +一些属性需要调整颜色，如光照、场景的背景色，亦或者材质的自发光颜色等。想要调整颜色，你需要点击左侧的颜色按钮来唤起颜色选择器。在颜色选择器中，你可以使用 HUE 来选择颜色，调整颜色的透明度；也可以在输入框来调整颜色具体的 RGBA 数值。点击 按钮可以在 HSLA，RGBA 和 HEXA 三种模式下进行切换。 - + ### 资产选择控件 @@ -67,4 +67,4 @@ label: Basics/Interface 资产选择器中还提供了一个搜索框，你可以使用它来更精确的找到对应的资产。 - + diff --git a/docs/zh/interface/shortcut.md b/docs/zh/interface/shortcut.mdx similarity index 64% rename from docs/zh/interface/shortcut.md rename to docs/zh/interface/shortcut.mdx index c8b217b4fb..666be045c6 100644 --- a/docs/zh/interface/shortcut.md +++ b/docs/zh/interface/shortcut.mdx @@ -8,4 +8,4 @@ label: Basics/Interface 快捷键有助于提升编辑场景的效率，用户可以在主菜单里 `Shortcuts` 中找到鼠标（或触控板）、键盘的视口控制方式，以及全局和各个面板的快捷键。 -image-20230925164702582 +image-20230925164702582 diff --git a/docs/zh/interface/template.md b/docs/zh/interface/template.mdx similarity index 68% rename from docs/zh/interface/template.md rename to docs/zh/interface/template.mdx index 5393402445..e6c1a5951e 100644 --- a/docs/zh/interface/template.md +++ b/docs/zh/interface/template.mdx @@ -8,4 +8,4 @@ label: Basics/Interface 业务模版按照类型当前分为动画、特效、2D、3D、XR、数字人等大类。点击模版，可以进行项目详情查看、项目预览、复刻项目到本地。 - + diff --git a/docs/zh/interface/viewport.md b/docs/zh/interface/viewport.mdx similarity index 56% rename from docs/zh/interface/viewport.md rename to docs/zh/interface/viewport.mdx index 15845aea39..3e2a21a2ad 100644 --- a/docs/zh/interface/viewport.md +++ b/docs/zh/interface/viewport.mdx @@ -10,7 +10,7 @@ label: Basics/Interface 视图窗口是用于选择、定位、更改当前场景中各种类型实体及组件的交互式界面。 -drag5 + ## 浏览场景 @@ -34,32 +34,32 @@ label: Basics/Interface 工具栏位于视图窗口中上，鼠标停留会出现每一项的快捷键，或者内容说明。 -image-20240131181207870 +image-20240131181207870 | 图标 | 名称 | 解释 | 快捷键 | | --- | --- | --- | --- | -| image-20240131175906508 | 拖动 | 拖动画面 | | -| image-20240131180117064
image-20240131180217044
image-20240131180256738 | 移动
旋转
缩放 | 对选中实体进行变换操作 | `W`
`E`
`R` | -| image-20240131180403373
image-20240131180513384 | 中心锚点/枢纽锚点 | 切换选中实体的锚点 | | -| image-20240131180709163
image-20240131180731465 | 本地坐标/世界坐标 | 切换选中实体的坐标 | | -| image-20240131181105676 | 聚焦 | 场景相机聚焦到的选中实体 | `F` | -| image-20240131181429677 | 场景相机 | 场景相机菜单包含用于配置场景相机的选项，主要用来解决搭建场景时，裁剪面太远或者太近导致看不到物体的问题。这些调整不会影响场景中带有相机组件的实体的设置。 | | -| image-20240131181144755 | 设置 | 设置菜单包含用于调整视图辅助显示的选项，包括网格、辅助图标（与场景中特定组件相关联的图形，包括相机、直射光、点光源、聚光灯）、 辅助线框 | | -| image-20240131181242445
image-20240131181524219 | 场景相机类型 | 切换透视/正交相机 | | -| image-20240131181459432
image-20240131181607999 | 模式 | 方便在 2D/3D 场景模式间进行点击切换。2D 模式下，导航部件、正交/透视切换关闭，导航中的环绕轨道不再生效。 | | -| image-20240131182235406 | 全屏/复原 | 最大化视图窗口，最小化层级、资产、检查器 | | -| | 播放 | 播放场景中所有粒子、动画 | -| image-20240131182303867 | 截屏 | 对当前场景进行快照。仅显示场景内用户创建实体，辅助显示的一系列工具，如图标、网格、gizmo 不会被计入其中。进行截屏后，该快照会在首页作为该项目缩略图。 | +| | 拖动 | 拖动画面 | | +|

| 移动
旋转
缩放 | 对选中实体进行变换操作 | `W`
`E`
`R` | +|
| 中心锚点/枢纽锚点 | 切换选中实体的锚点 | | +|
| 本地坐标/世界坐标 | 切换选中实体的坐标 | | +| | 聚焦 | 场景相机聚焦到的选中实体 | `F` | +| | 场景相机 | 场景相机菜单包含用于配置场景相机的选项，主要用来解决搭建场景时，裁剪面太远或者太近导致看不到物体的问题。这些调整不会影响场景中带有相机组件的实体的设置。 | | +| | 设置 | 设置菜单包含用于调整视图辅助显示的选项，包括网格、辅助图标（与场景中特定组件相关联的图形，包括相机、直射光、点光源、聚光灯）、 辅助线框 | | +|
| 场景相机类型 | 切换透视/正交相机 | | +|
| 模式 | 方便在 2D/3D 场景模式间进行点击切换。2D 模式下，导航部件、正交/透视切换关闭，导航中的环绕轨道不再生效。 | | +| | 全屏/复原 | 最大化视图窗口，最小化层级、资产、检查器 | | +| | 播放 | 播放场景中所有粒子、动画 | +| | 截屏 | 对当前场景进行快照。仅显示场景内用户创建实体，辅助显示的一系列工具，如图标、网格、gizmo 不会被计入其中。进行截屏后，该快照会在首页作为该项目缩略图。 | ### 辅助元素设置界面 - + | 属性 | 内容 | | --- | --- | | 网格（Grid） | 视图中的网格是否显示 | | 3D 图标（3D Icons） | 辅助图标是否根据组件与摄像机的距离进行缩放 | -| 导航 Gimzo | 用于显示场景相机的当前方向，并且可以通过鼠标操作快速修改视角和投影模式（正交/透视）。打开后会在画面右下角显示。
image-20240131184405058 | +| 导航 Gimzo | 用于显示场景相机的当前方向，并且可以通过鼠标操作快速修改视角和投影模式（正交/透视）。打开后会在画面右下角显示。
image-20240131184405058 | | 轮廓显示（Outline） | 选中某个实体时是否显示轮廓，选中的实体轮廓颜色为橙色，子节点轮廓为蓝色 | | 相机（Camera） | 以锥体显示选中相机组件 | | 光源（Light） | 显示光源组件 | @@ -69,7 +69,7 @@ label: Basics/Interface ### 场景相机设置界面 -image-20240131185805023 + | 属性 | 内容 | 默认值 | | :--------------------------- | :----------------------------------------------------------- | :------------------- | @@ -86,7 +86,7 @@ label: Basics/Interface 选中带有相机组件的实体时，会在视图窗口左下角显示该相机的实时预览。帮助用户实时调整相机、场景位置。预览窗口可以拖动、锁定，并且切换不同设备比例的窗口。 -image-20240131190013320 +image-20240131190013320 | 属性 | 内容 | | :------- | :--------------------------- | @@ -97,4 +97,4 @@ label: Basics/Interface 在层级树中包含相机组件的物体，可以直接同步视图的场景相机的相关属性，方便进行位置和视角的调整。 - +