V4.0

@config/shared-theme-zh.ts

@@ -1,6 +1,7 @@
 import { defineConfig, type DefaultTheme } from 'vitepress'
 import { github, branch } from './config'
 
+
 export default function(version: string) {
   return defineConfig({
     lang: 'zh-Hans',

README.md

@@ -11,24 +11,24 @@ npm install
 
 ## Generate Sidebar
 
-node ./scripts/create-sidebar.js versions/3.8/zh/SUMMARY.md
+node ./scripts/create-sidebar.js versions/4.0/zh/SUMMARY.md
 
-node ./scripts/create-sidebar.js versions/3.8/en/SUMMARY.md
+node ./scripts/create-sidebar.js versions/4.0/en/SUMMARY.md
 
 ## Run In Dev Mode
 
-npx vitepress dev versions/3.8
+npx vitepress dev versions/4.0
 
 ## Build
 
-node ./scripts/publish.js --version=versions/3.8
+node ./scripts/publish.js --version=versions/4.0
 
 ## Build All
 
 node ./scripts/publish.js --version=versions/all
 
 ## Preview
 
-npx vitepress preview versions/3.8
+npx vitepress preview versions/4.0
 
-> Change the '3.8' above to operate another version.
+> Change the '4.0' above to operate another version.

package.json

@@ -4,9 +4,9 @@
   "description": "cocos-creator-docs",
   "type": "module",
   "scripts": {
-    "docs:dev": "cross-env __APIDOC__=https://docs.cocos.com/creator/3.8/api vitepress dev versions/3.8 --port=5001 --host",
-    "docs:build": "cross-env __APIDOC__=https://docs.cocos.com/creator/3.8/api vitepress build versions/3.8",
-    "docs:preview": "vitepress preview versions/3.8"
+    "docs:dev": "cross-env __APIDOC__=https://docs.cocos.com/creator/4.0/api vitepress dev versions/4.0 --port=5001 --host",
+    "docs:build": "cross-env __APIDOC__=https://docs.cocos.com/creator/4.0/api vitepress build versions/4.0",
+    "docs:preview": "vitepress preview versions/4.0"
   },
   "keywords": [],
   "author": "cocos",

versions.json

@@ -1,4 +1,7 @@
 [
+    {
+        "version": "4.0"
+    },
     {
         "version": "3.8"
     },

versions/4.0/.vitepress/config/index.ts

@@ -0,0 +1,58 @@
+import { defineConfig } from 'vitepress'
+import { shared } from '../../../../@config/shared'
+
+// 每个语言的配置
+import configZhFn from '../../../../@config/shared-theme-zh'
+import configEnFn from '../../../../@config/shared-theme-en'
+import { nav } from '../../../../@config/shared';
+
+// 侧边栏数据
+import menusEN from '../../en/summary.json' with {type: 'json'};
+import menusZH from '../../zh/summary.json' with {type: 'json'};
+
+import { version } from './version.ts';
+
+// 英文配置
+const configEn = configEnFn(version);
+const en = defineConfig({
+  lang: configEn.lang,
+  description: configEn.description,
+
+  themeConfig: {
+    ...configEn.themeConfig,
+
+    nav: nav(version, 'en'),
+
+    sidebar: {
+      '/en/': { base: '/en/', items: menusEN },
+    }
+  }
+})
+
+// 中文配置
+const configZh = configZhFn(version);
+const zh = defineConfig({
+  lang: configZh.lang,
+  description: configZh.description,
+
+  themeConfig: {
+    ...configZh.themeConfig,
+
+    nav: nav(version, 'zh'),
+
+    sidebar: {
+      '/zh/': { base: '/zh/', items: menusZH },
+    }
+  }
+})
+
+export default defineConfig({
+  ...shared,
+  base: `/creator/${version}/manual/` , // `/${version}/`
+  locales: {
+    // 我们的文档都在 /en/ /zh/ 等文件夹里面，没有在根目录的文档 所以不用配 root
+    // root: { label: 'English', ...en },
+    en: { label: 'English', ...en },
+    zh: { label: '简体中文', ...zh }
+  }
+})

versions/4.0/.vitepress/config/version.ts

@@ -0,0 +1 @@
+export const version = '4.0';

versions/4.0/.vitepress/theme/index.ts

@@ -0,0 +1,6 @@
+
+import theme from '../../../../@config/theme/index.ts'
+import { version } from '../config/version.ts'
+
+export default theme(version)
+

versions/4.0/en/2d-object/2d-render/index.md

@@ -0,0 +1,45 @@
+# 2D Render Description
+
+All rendering objects in the engine that do not own a model are 2D rendering objects. Unlike 3D objects, 2D objects do not have model information, and their vertex information is held by the Rect information of the UITransform component and created by the engine, and they have no thickness themselves. Due to the design requirements of the engine, the 2D render object needs to be a child of the RenderRoot node (the node with the RenderRoot2D component) in order to complete the data collection operation.
+
+The rendering requirements for the 2D render object are twofold:
+1. It needs to have a UITransform component
+2. It needs to be a child of a RenderRoot node
+
+## 2D Rendering Object Visibility Description
+
+Since there is no difference between 2D rendering objects and 3D renderable nodes in terms of camera visibility, users need to control the layer property of the node and set the Visibility of the camera to match the group rendering. If there are multiple cameras in the scene, wrong layer settings may cause the node to be rendered repeatedly or not at all.
+
+## 2D Renderable Components
+
+Components that have rendering capabilities in their own right are called 2D Renderable components, including:
+
+- [Sprite Component Reference](../../ui-system/components/editor/sprite.md)
+- [Label Component Reference](../../ui-system/components/editor/label.md)
+- [Mask Component Reference](../../ui-system/components/editor/mask.md)
+- [Graphics Component Reference](../../ui-system/components/editor/graphics.md)
+- [RichText Component Reference](../../ui-system/components/editor/richtext.md)
+- [UIStaticBatch Component Reference](../../ui-system/components/editor/ui-static.md)
+- [TiledMap Component Reference](../../editor/components/tiledmap.md)
+- [TiledTile Component Reference](../../editor/components/tiledtile.md)
+- [Spine Skeletal Component Reference](../../editor/components/spine.md)
+- [DragonBones ArmatureDisplay Component Reference](../../editor/components/dragonbones.md)
+- [MotionStreak Component Reference](../../editor/components/motion-streak.md)
+
+## How to add 2D Renderable Components
+
+Some 2D renderable components are built into the editor. After creating a RenderRoot node, create a node with 2D renderable components under this node:
+
+![create-2d](./create-2d.png)
+
+2D renderable components can also be added by adding components to the node, the nodes under the 2D menu in the components menu are all 2D renderable components:
+
+![add-render-component](./add-render-component.png)
+
+> **Note**: only one renderable component can be added to each node, and repeated additions will result in error reporting.
+
+## 2D Renderable Component Rules Introduction
+
+- [Rendering Order Rules](../../ui-system/components/engine/priority.md)
+- [2D Renderable Component Batching Rules](../../ui-system/components/engine/ui-batch.md)
+- [Custom Materials for 2D Rendering Objects](../../ui-system/components/engine/ui-material.md)

versions/4.0/en/2d-object/index.md

@@ -0,0 +1,20 @@
+# 2D Objects Overview
+
+Unlike 3D model objects, 2D rendering objects are referred to as the rendering of images that do not involve models. 2D rendering objects are handled differently from 3D models in terms of the underlying data submission, and follow their own rules with some specific adjustments for better efficiency and experience.
+
+## 2D Object Rendering Structure Description
+
+The RenderRoot node (the node with the RenderRoot2D component) is the entry point for 2D object data collection, and all 2D rendering objects must be rendered under the RenderRoot node. Since the Canvas component inherits from the RenderRoot2D component, the Canvas component can also be the entry point for data collection. 2D rendering nodes must have a UITransform component as a requirement for rendering vertex data, click or alignment policies, etc.
+
+2D rendering can also support rendering of models, the only condition is that nodes with model components (e.g. `MeshRenderer`/`SkinnedMeshRenderer`) must have **UI/UIMeshRenderer** components added to them in order to render on the same pipeline as the UI.
+
+The 2D rendering flow is as follows:
+
+![render](render.png)
+
+## 2D object classification
+
+2D objects can be broadly classified into two categories, **2D rendering objects** and **User-interface (UI)**. The difference is that 2D rendering objects are generally only responsible for rendering 2D objects, while UI is more about user interaction. For more details on the differences, users can refer to the specific descriptions:
+
+- [2D Renderable Component Description](2d-render/index.md)
+- [UI System](ui-system/index.md)

versions/4.0/en/2d-object/ui-system/index.md

@@ -0,0 +1,49 @@
+# UI System
+
+This section introduces the powerful and flexible UI (User Interface) system in Cocos Creator. By assembling different UI components to produce UI interfaces that can be adapted to multiple screen resolutions, dynamically generate and update display content from data, and support multiple layout styles.
+
+## Getting Started with UI
+
+The difference between defining UI and 2D rendering objects in the engine mainly lies in adaptation and interaction. All UI needs to be under a Canvas node to make adaptation behavior, and the Canvas component itself inherits from `RenderRoot2D` component, it can also be used as an entry point for data collection.
+
+The UI is a necessary interactive part of game development. Generally, buttons, text, backgrounds, etc. on the game are made through the UI. When starting to create a UI, first it is necessary to determine the size of the display area (design resolution) of the current design content, which can be set in the **Project -> Project Settings -> Project Data** panel in the menu bar.
+
+![resolution-config](resolution_config.png)
+
+Once the design resolution is set, start creating UI elements, all of which are contained under the Canvas node. The Canvas node can be created by clicking the **+** button in the **Hierarchy** panel on the top left and selecting **UI Component -> Canvas**. The Canvas node has a [Canvas](../../ui-system/components/editor/canvas.md) component, which can be associated with a camera.
+
+> **Notes**:
+>
+> 1. Multiple Canvas nodes can exist in a scene, but a Canvas node should not be nested under another Canvas node or its children.
+> 2. Canvas components are not one-to-one with camera, their previous rendering depends on the layer of the node and the Visibility of the camera, so you should pay extra attention to layer management to get the desired rendering effect when you have multiple Canvas.
+
+Next, create UI nodes under the Canvas node. The editor comes with the following UI nodes:
+
+![create-ui](./create-ui.png)
+
+UI components can be viewed by selecting the node and clicking **Add Component** in the **Inspector** panel.
+
+![add-ui-component](./add-ui-component.png)
+
+The order in which UI components are rendered is a depth ordering scheme, which means that the ordering of the child nodes under the Canvas node already determines the entire [rendering order](../../ui-system/components/engine/priority.md).
+
+In general game development, the necessary UI elements are not only basic 2D renderable components such as Sprite, Label (text), Mask, but also Layout, Widget (alignment), etc., which are used to quickly build the interface. Sprite and Label are used to render images and text, Mask is mainly used to limit the display content, more commonly used in chat boxes and backpacks, etc. Layout is generally used for single arrangement of buttons, neat arrangement of props in backpacks, etc. <br>
+The last important feature is the Widget, which is mainly used for display alignment. When finishing designing the UI and publish it to different platforms, the actual device resolution of the platform is bound to be different from our design resolution, therefore some trade-offs need to be made in order to adapt it. It is necessary to add a widget component to it, and always ensure that it is aligned to the top left of our design resolution. Please review the [Alignment Strategy](../../ui-system/components/engine/widget-align.md) and [Alignment](../../ui-system/components/editor/widget.md) documentation.
+
+Once the interface is created, some people may notice that the iPhone 7 displays differently than the iPhone X. This is actually the same problem with the device resolution we mentioned above. When you design in design resolution and finally publish in device resolution, there is a pixel deviation because the resolution of different models of mobile devices may not be the same, so there is another conversion process that needs to be done that is screen adaptation. <br>
+Notice in the **Projects -> Project Settings -> Project Data** page in the menu bar, there are two more options **Fit Width / Fit Height**, which can be easily adapted to different devices by following the screen adaptation rules and combining with the Widget component. The specific adaptation rules can be found in the [Multi-Resolution Adaptation Scheme](../../ui-system/components/engine/multi-resolution.md) documentation.
+
+## UI components
+
+UI components mostly do not have rendering capabilities themselves, but hold 2D renderable components for rendering, which themselves have more ability to quickly form user-interactive interfaces, and take on functions such as event response, typography adaptation, etc.
+
+For specific descriptions of each UI component, please refer to the [UI Components](../../ui-system/components/editor/base-component.md) documentation.
+
+## UI Practice Guide
+
+- [Multi-Resolution Adaptation Scheme](../../ui-system/components/engine/multi-resolution.md)
+- [Alignment Strategy](../../ui-system/components/engine/widget-align.md)
+- [Label Layout](../../ui-system/components/engine/label-layout.md)
+- [Auto Layout Container](../../ui-system/components/engine/auto-layout.md)
+- [Create a List of Dynamically Generated Content](../../ui-system/components/engine/list-with-data.md)
+- [Use a Sliced Sprite to make a UI image](../../ui-system/components/engine/sliced-sprite.md)