refactor: doc md to mdx #2530
refactor: doc md to mdx #2530
Conversation
WalkthroughThis pull request involves a comprehensive documentation update for the Galacean engine, focusing on core components and interface documentation. The changes primarily include replacing markdown documentation files with MDX files, updating image rendering methods, and enhancing content clarity across English and Chinese documentation. Key areas of focus include canvas, components, engine, math, prefab, scene, space, transform, and interface documentation. Changes
Sequence DiagramsequenceDiagram
participant Dev as Developer
participant Engine as Galacean Engine
participant Canvas as WebCanvas
participant Scene as Scene Manager
Dev->>Engine: Create WebGLEngine
Engine->>Canvas: Initialize Canvas
Canvas-->>Engine: Canvas Ready
Dev->>Scene: Load/Create Scene
Scene-->>Dev: Scene Prepared
Dev->>Canvas: Configure Canvas Settings
Canvas->>Engine: Apply Rendering Configuration
Possibly related PRs
Suggested Reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (2)
docs/en/core/scene.mdx (2)
Line range hint
123-126: Add error handling for scene loading.The code example for loading a scene should include error handling.
Apply this diff:
const sceneUrl = "..."; -engine.resourceManager.load({ type: AssetType.Scene, url: "..." }).then((scene) => { +engine.resourceManager.load({ type: AssetType.Scene, url: sceneUrl }) +.then((scene) => { engine.sceneManager.addScene(scene); +}) +.catch((error) => { + console.error("Failed to load scene:", error); + // Handle the error appropriately });
Line range hint
132-137: Chinese comments should be in English.The code example contains comments in Chinese which should be in English for consistency.
Apply this diff:
-// 获取当前所有激活的场景 +// Get all currently active scenes const scenes = engine.sceneManager.scenes; -// 获取节点属于的场景 +// Get the scene that the entity belongs to const scene = entity.scene;
🧹 Nitpick comments (16)
docs/zh/core/engine.mdx (1)
20-26: Add example values for configuration options.The initialization example would be more helpful with concrete values for each configuration option.
Consider updating the example like this:
const engine = await WebGLEngine.create({ canvas: "canvas-id", - colorSpace: {...}, - graphicDeviceOptions: {...}， - gltf: {...}, - ktx2Loader: {...} + colorSpace: ColorSpace.Linear, + graphicDeviceOptions: { + webGLMode: WebGLMode.WebGL2 + }, + gltf: { + meshOpt: { workerCount: 2 } + }, + ktx2Loader: { + workerCount: 2, + priorityFormats: [KTX2TargetFormat.RGBA] + } });docs/en/core/component.mdx (2)
29-29: Add hyphen to "top-left corner".For consistency with standard technical writing, "top left corner" should be hyphenated.
-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. +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.🧰 Tools
🪛 LanguageTool
[uncategorized] ~29-~29: Consider adding a hyphen.
Context: ...ith the component name displayed in the top left corner. <Image src="https://mdn.alipay...(TOP_LEFT_CORNER)
55-60: Add error handling to the component example.The code example should demonstrate proper error handling when adding components.
const lightEntity = rootEntity.createChild("light"); -const directLight = lightEntity.addComponent(DirectLight); +const directLight = lightEntity.addComponent(DirectLight); +if (!directLight) { + console.error("Failed to add DirectLight component"); + return; +} directLight.color = new Color(0.3, 0.3, 1); directLight.intensity = 1;docs/en/core/prefab.mdx (1)
92-98: Enhance type safety and error handling in the prefab loading example.The code example should demonstrate proper error handling and type safety.
engine.resourceManager .load({ url: "Prefab's URL", type: AssetType.Prefab }) - .then((prefab: PrefabResource) => { + .then((prefab) => { + if (!(prefab instanceof PrefabResource)) { + throw new Error("Failed to load prefab resource"); + } const prefabInstanceEntity = prefab.instantiate(); + if (!prefabInstanceEntity) { + throw new Error("Failed to instantiate prefab"); + } scene.addRootEntity(prefabInstanceEntity); - }); + }) + .catch((error) => { + console.error("Error loading or instantiating prefab:", error); + });docs/en/core/canvas.mdx (1)
16-18: Add accessibility attributes to canvas element.The HTML canvas example should include ARIA attributes for better accessibility.
-<canvas id="canvas" style="width: 500px; height: 500px" /> +<canvas + id="canvas" + style="width: 500px; height: 500px" + aria-label="3D rendering canvas" + role="img" +/>docs/en/interface/inspector.mdx (3)
11-11: Image source should use a more reliable CDN.The image is currently hosted on
mdn.alipayobjects.com. Consider moving it to a more reliable CDN to ensure long-term availability.
25-25: Improve clarity of Entity Inspector description.The sentence structure could be improved for better readability.
Apply this diff:
-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. +The Entity Inspector is the most commonly used inspector. It displays the component list and basic information (such as `Transform` and `Layer`) of the current entity. You can easily modify component properties or add built-in engine components and custom script components via the **Add Component** button. See [Entities](/docs/core/entity) for more details.🧰 Tools
🪛 LanguageTool
[grammar] ~25-~25: The correct preposition here is “on” or “about”.
Context: ...tor also includes the basic information of the current entity, such asTransform...(INFORMATION_OF)
60-60: Improve color picker description clarity.The description of the color picker functionality could be more concise and clearer.
Apply this diff:
-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 <img src="https://gw.alipayobjects.com/zos/OasisHub/dc030a4b-8813-4ea2-acb0-549c04363b1d/image-20230926110451443.png" /> button allows you to switch between HSLA, RGBA, and HEXA modes. +For color properties (like lighting, scene background, or material emissive color), click the color button to open the color picker. You can select colors using the HUE slider, adjust transparency, or input specific RGBA values. Click the <img src="https://gw.alipayobjects.com/zos/OasisHub/dc030a4b-8813-4ea2-acb0-549c04363b1d/image-20230926110451443.png" /> button to switch between HSLA, RGBA, and HEXA modes.docs/en/core/scene.mdx (1)
8-8: Image source should use a more reliable CDN.The image is currently hosted on
gw.alipayobjects.com. Consider moving it to a more reliable CDN to ensure long-term availability.docs/en/core/engine.mdx (2)
19-27: Add example configuration values.The configuration example should include actual values to better illustrate usage.
Apply this diff:
const engine = await WebGLEngine.create({ canvas: "canvas-id", - colorSpace: {...}, - graphicDeviceOptions: {...}, - gltf: {...}, - ktx2Loader: {...} + colorSpace: ColorSpace.Linear, + graphicDeviceOptions: { + webGLMode: WebGLMode.WebGL2, + alpha: true, + antialias: true + }, + gltf: { + meshOpt: { workerCount: 2 } + }, + ktx2Loader: { + priorityFormats: [KTX2TargetFormat.RGBA], + transcoder: KTX2Transcoder.ZSTD, + workerCount: 2 + } });
67-67: Add explanation for the warning.The warning about non-vertical sync should include an explanation of why it's not recommended.
Apply this diff:
-> ⚠️ Non-vertical sync is not recommended. +> ⚠️ Non-vertical sync is not recommended as it can lead to screen tearing and inconsistent frame rates. It may also cause unnecessary GPU load and power consumption.docs/en/core/transform.mdx (1)
112-130: Add type annotations to the Camera class example.The code example should include TypeScript type annotations for better clarity.
Apply this diff:
class Camera { + private _transform: Transform; + private _isViewMatrixDirty: { flag: boolean }; + private _viewMatrix: Matrix; 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; } }docs/en/interface/viewport.mdx (2)
62-62: Fix preposition in navigation gizmo description.The description uses incorrect preposition "at" instead of "in".
Apply this diff:
-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. +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 in the bottom right corner of the screen when open.🧰 Tools
🪛 LanguageTool
[grammar] ~62-~62: The usual preposition to use with “corner” is “in”, not “on”. Did you mean “in the bottom right corner”?
Context: ...thographic/perspective). It will appear at the bottom right corner of the screen when open.
<img src=...(ON_IN_THE_CORNER)
78-79: Improve clarity of clipping plane descriptions.The descriptions for Near Plane and Far Plane could be clearer.
Apply this diff:
-| 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 | +| Near Plane | Distance to the nearest visible objects from the scene camera (manual adjustment) | Enabled when dynamic clipping is unchecked | +| Far Plane | Distance to the farthest visible objects from the scene camera (manual adjustment) | Enabled when dynamic clipping is unchecked |docs/zh/core/math.mdx (1)
398-399: Consider adding alt text to the Ray illustration.For better accessibility, consider adding descriptive alt text to the Ray illustration.
-<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*w2XVQL-K4UEAAAAAAAAAAAAADjCHAQ/original" style={{zoom: "50%"}} /> +<Image + src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*w2XVQL-K4UEAAAAAAAAAAAAADjCHAQ/original" + style={{zoom: "50%"}} + alt="Illustration of a ray starting from origin point and extending in a direction" +/>docs/zh/interface/inspector.mdx (1)
54-54: Improve Chinese grammar in documentation.Consider these grammatical improvements:
- Line 54: "步进" should be "步骤"
- Line 68: "精确的" should be "精确地"
-这些属性往往拥有更精确的步进大小 +这些属性往往拥有更精确的步骤大小 -你可以使用它来更精确的找到对应的资产 +你可以使用它来更精确地找到对应的资产Also applies to: 68-68
🧰 Tools
🪛 LanguageTool
[uncategorized] ~54-~54: 您的意思是“"不"进”？
Context: ...和按钮的形式出现的，如阴影的Near Plane。这些属性往往拥有更精确的步进大小（如 0.1, 1, 10）。点击按钮可以直接以步进长度来增加或减小数值。...(BU)
[uncategorized] ~54-~54: 您的意思是“"不"进”？
Context: ...这些属性往往拥有更精确的步进大小（如 0.1, 1, 10）。点击按钮可以直接以步进长度来增加或减小数值。 <Image src="https://gw.ali...(BU)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (32)
docs/en/core/canvas.md(0 hunks)docs/en/core/canvas.mdx(1 hunks)docs/en/core/component.md(0 hunks)docs/en/core/component.mdx(1 hunks)docs/en/core/engine.md(0 hunks)docs/en/core/engine.mdx(1 hunks)docs/en/core/math.mdx(2 hunks)docs/en/core/prefab.md(0 hunks)docs/en/core/prefab.mdx(1 hunks)docs/en/core/scene.mdx(1 hunks)docs/en/core/space.md(0 hunks)docs/en/core/space.mdx(1 hunks)docs/en/core/transform.md(0 hunks)docs/en/core/transform.mdx(1 hunks)docs/en/interface/inspector.md(0 hunks)docs/en/interface/inspector.mdx(1 hunks)docs/en/interface/shortcut.mdx(1 hunks)docs/en/interface/template.mdx(1 hunks)docs/en/interface/viewport.md(0 hunks)docs/en/interface/viewport.mdx(1 hunks)docs/zh/core/canvas.mdx(3 hunks)docs/zh/core/component.mdx(2 hunks)docs/zh/core/engine.mdx(1 hunks)docs/zh/core/math.mdx(2 hunks)docs/zh/core/prefab.mdx(2 hunks)docs/zh/core/scene.mdx(1 hunks)docs/zh/core/space.mdx(2 hunks)docs/zh/core/transform.mdx(2 hunks)docs/zh/interface/inspector.mdx(2 hunks)docs/zh/interface/shortcut.mdx(1 hunks)docs/zh/interface/template.mdx(1 hunks)docs/zh/interface/viewport.mdx(5 hunks)
💤 Files with no reviewable changes (8)
- docs/en/interface/viewport.md
- docs/en/core/transform.md
- docs/en/core/prefab.md
- docs/en/interface/inspector.md
- docs/en/core/canvas.md
- docs/en/core/engine.md
- docs/en/core/space.md
- docs/en/core/component.md
✅ Files skipped from review due to trivial changes (10)
- docs/en/interface/shortcut.mdx
- docs/zh/interface/shortcut.mdx
- docs/zh/core/canvas.mdx
- docs/zh/core/transform.mdx
- docs/zh/core/scene.mdx
- docs/zh/core/prefab.mdx
- docs/zh/core/space.mdx
- docs/zh/interface/template.mdx
- docs/en/interface/template.mdx
- docs/zh/interface/viewport.mdx
🧰 Additional context used
🪛 LanguageTool
docs/en/core/engine.mdx
[style] ~37-~37: This phrasing could be wordy, so try replacing it with something more concise.
Context: ... workerCount: number }`. If workerCount is greater than 0, worker threads will be created; if i...
(MORE_THAN_EXCEEDS)
docs/en/core/transform.mdx
[style] ~12-~12: Consider an alternative adjective to strengthen your wording.
Context: ...l space** and world space. > For a deeper understanding, refer to Galacean's **[C...
(DEEP_PROFOUND)
docs/en/interface/viewport.mdx
[grammar] ~62-~62: The usual preposition to use with “corner” is “in”, not “on”. Did you mean “in the bottom right corner”?
Context: ...thographic/perspective). It will appear at the bottom right corner of the screen when open.
<img src=...
(ON_IN_THE_CORNER)
docs/en/core/component.mdx
[uncategorized] ~29-~29: Consider adding a hyphen.
Context: ...ith the component name displayed in the top left corner. <Image src="https://mdn.alipay...
(TOP_LEFT_CORNER)
docs/en/interface/inspector.mdx
[grammar] ~25-~25: The correct preposition here is “on” or “about”.
Context: ...tor also includes the basic information of the current entity, such as Transform...
(INFORMATION_OF)
docs/zh/core/component.mdx
[typographical] ~8-~8: Niet-gecombineerd symbool: “[” lijkt te ontbreken
Context: ...le: 组件 type: 核心 label: Core --- Entity 不具备渲染模型等实际的功能，这些功能是...
(UNPAIRED_BRACKETS)
docs/zh/interface/inspector.mdx
[uncategorized] ~54-~54: 您的意思是“"不"进”？
Context: ...和按钮的形式出现的，如阴影的 Near Plane。这些属性往往拥有更精确的步进大小（如 0.1, 1, 10）。点击按钮可以直接以步进长度来增加或减小数值。...
(BU)
[uncategorized] ~54-~54: 您的意思是“"不"进”？
Context: ...这些属性往往拥有更精确的步进大小（如 0.1, 1, 10）。点击按钮可以直接以步进长度来增加或减小数值。 <Image src="https://gw.ali...
(BU)
[uncategorized] ~68-~68: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：精确"地"找到
Context: ...的过滤器，直接选择即可。 资产选择器中还提供了一个搜索框，你可以使用它来更精确的找到对应的资产。 <Image src="https://gw.alipayo...
(wb4)
🔇 Additional comments (6)
docs/en/core/space.mdx (1)
16-18: LGTM! Clear comparison between Unity and Galacean coordinate systems.The explanation of coordinate system differences between Unity and Galacean is accurate and well-presented.
docs/en/core/canvas.mdx (1)
69-81: LGTM! Well-documented energy-saving mode implementation.The energy-saving mode implementation is clear and includes helpful comments explaining the scaling calculations.
docs/zh/core/math.mdx (2)
259-259: Image components follow React best practices.The conversion from HTML img tags to React Image components is implemented correctly with proper style props.
Also applies to: 399-399
398-399: Verify image URLs are accessible.Let's verify that the image URLs are accessible and loading correctly.
Also applies to: 258-259
✅ Verification successful
Image URLs are accessible and working correctly
Both image URLs return HTTP 200 status codes, confirming they are properly accessible.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Check if the image URLs are accessible # Test: Verify HTTP status codes for the image URLs urls=( "https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*w2XVQL-K4UEAAAAAAAAAAAAADjCHAQ/original" "https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*1HMeRbPQv1kAAAAAAAAAAAAADjCHAQ/original" ) for url in "${urls[@]}"; do status=$(curl -s -o /dev/null -w "%{http_code}" "$url") echo "URL: $url" echo "Status: $status" if [ "$status" != "200" ]; then echo "Warning: Image not accessible" fi doneLength of output: 1088
docs/en/core/math.mdx (1)
258-258: Documentation maintains consistency across languages.The English version correctly mirrors the Chinese version in both content and styling.
Also applies to: 397-397
docs/zh/core/component.mdx (1)
31-31: Well-structured image components with proper accessibility.The image components are correctly implemented with:
- Consistent zoom styling
- Meaningful alt text
- Proper React component syntax
Also applies to: 35-35, 39-39, 43-43, 47-47
| // Modify node translation, rotation, and scale | ||
| transform.position = new Vector3(); |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add missing variable declaration in code example.
The code example uses transform without declaring it first.
Apply this diff:
// Create a node
const scene = engine.sceneManager.activeScene;
const root = scene.createRootEntity("root");
const cubeEntity = root.createChild("cube");
+// Get the transform component
+const transform = cubeEntity.transform;
// Modify node translation, rotation, and scale
transform.position = new Vector3();Also applies to: 73-76
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2530 +/- ##
==========================================
- Coverage 69.05% 68.60% -0.45%
==========================================
Files 957 957
Lines 100125 100125
Branches 8569 8572 +3
==========================================
- Hits 69138 68695 -443
- Misses 30731 31174 +443
Partials 256 256
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Please check if the PR fulfills these requirements
What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
What is the current behavior? (You can also link to an open issue here)
What is the new behavior (if this is a feature change)?
Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)
Other information:
Summary by CodeRabbit
Based on the comprehensive documentation changes, here are the release notes:
Documentation Updates
.md) to MDX (.mdx) format<Image>componentsNew Features
Randclass for pseudo-random number generationImprovements
Changes