优化原生插件文档描述、完善原生插件示例工程

Author: zhefengzhang

versions/3.6/en/advanced-topics/native-plugins/brief.md

@@ -1,101 +1,111 @@
 # Native Plugins
 
-> Notice: Native plugin support for 3.6.2 is broken, please upgrade to 3.6.3 or later.
+> **Note**:
+>
+> * Please use the native plugin feature in CocosCreator 3.6.3 and above.
+> * The native plugin feature is not yet adapted for HarmonyOS related platforms.
 
-Native Plugins are part of the editor plugins. By calling JSB interfaces (e.g. export with `sebind`) through native plugins, developers can extend the ability of JS scripts to call C++ interfaces, which can be very beneficial for solving script performance bottles and reusing existing codebases. As the engine is upgraded in the future, the native plugins will open up more features.
+Native plugins are part of the editor plugin system. Developers can use native plugins to call script binding interfaces (such as sebind) to extend the capability of JS scripts calling C++ interfaces, which is very beneficial for solving script performance bottlenecks and reusing existing codebases.
 
-## Cooperation with existing *Editor Extensions*
+## Relationship with Existing Plugin System
 
-Native plugins can exist independently of editor extensions, and users can use native plug-ins by copying them to the specified directory.
+Native plugins can exist independently of editor plugins. Users can use native plugins by copying them to specified directories.
 
-At the same time, native plugins complement the existing editor extension system, extending the game's runtime capabilities. Developers use the ability of editor extensions to manage native plugins, such as download/switch/version upgrade, etc.
+At the same time, native plugins also serve as a supplement to the existing editor plugin system, extending the capabilities of the game runtime. They leverage the capabilities of editor plugins to manage native plugins, such as: download/on-off switching/version upgrade and other functions.
+
+### Plugin Structure
+
+Each plugin has a plugin description file `cc_plugin.json` in its root directory, which is a standard JSON file.
+
+When building native projects, the build system will recursively search for all `cc_plugin.json` files from the project's `extensions` and `native` directories to locate native plugins. Once `cc_plugins.json` is found in a directory, it will not search subdirectories further.
 
 ## Installing Dependencies
 
-To support plugin configuration parsing, a minimum of [NodeJS](https://nodejs.org/en/download/) version 8.0 is required. You can set the environment variable `PATH` or set `NODE_EXECUTABLE` to the full path to the node. In case CMake fails to locate NodeJS, you can directly set `NODE_EXECUTABLE` in CMakeLists.txt. This can now be done in `native/engine/common/localCfg.cmake`, starting from version 3.6.2, which is recommended.
+In a few environments where the editor is not installed, [NodeJS](https://nodejs.org/en/download/) version 8.0 or above needs to be installed to support plugin configuration parsing. Developers can set the NodeJS environment variable `PATH`, or specify it by setting `NODE_EXECUTABLE` in `CMakeLists.txt`.
 
-## Example of the plugin's directory structure
+You can also set the environment variable `NODE_EXECUTABLE` to the full path of node. Starting from version 3.6.2, if CMake still cannot locate nodejs, you can directly set `NODE_EXECUTABLE` in `native/engine/common/localCfg.cmake`.
+
+## Basic Directory Structure Example
 
 ```
 ├── cc_plugin.json
 ├── android
-│ ├── arm64-v8a
-│ ├── armeabi-v7a
-│ ├── x86
-│ └─ x86_64
-├─ ios
-│ ├── include
-│ └── lib
-├─ mac
-│ ├── include
-│ └── lib
-└─ windows
-    ├─ include
-    └── lib
+│   ├── arm64-v8a
+│   ├── armeabi-v7a
+│   ├── x86
+│   └── x86_64
+│__ google-play
+│   ├── arm64-v8a
+│   ├── armeabi-v7a
+│   ├── x86
+│   └── x86_64
+├── ios
+│   ├── include
+│   └── lib
+├── mac
+│   ├── include
+│   └── lib
+│── windows
+│    ├── include
+│    └── lib
 ```
 
-The file `cc_plugin.json` provides the information necessary to load the plugin, and is the identifier of the native plugin. Each supported native platform corresponds to a directory that contains at least one `<PackageName>-Config.cmake` file. The build system will use CMake's [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html#id7) mechanism to locate or link to the required library files. 
+The file `cc_plugin.json` provides the necessary information for loading plugins and serves as the identifier for native plugins. Each supported native platform corresponds to a directory, which contains at least one `<PackageName>-Config.cmake` file. The build system uses CMake's [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html#id7) mechanism to locate or link to the required library files.
 
-If there are cross-platform source files or CMake configurations in the plugin, these files can be merged into the top-level directory. For example: [example project](https://github.com/PatriceJiang/ccplugin_tutorial/tree/main/NewProject/native/plugins/hello_cocos)
+If there are cross-platform source files or CMake configurations in the plugin, these files can be merged into the top-level directory. For details, please refer to the [example project](https://github.com/PatriceJiang/ccplugin_tutorial/tree/main/NewProject/native/plugins/hello_cocos).
 
-## Description file `cc_plugin.json` format
+## Description File `cc_plugin.json` Format
 
 ```ts
 {
-    "name": string;             // required: plugin name
-    "version": string;          // required: plugin version
-    "engine-version":string;    // mandatory: the range of the corresponding engine version
-    "author": string;           // required: the author of the plugin
-    "description": string;      // required: description of the plugin
-    "platforms":string[];       // optional: list of supported platforms, all native platforms are supported by default if not filled. Including windows, android, mac, ios
-    "disabled":true;            // optional: Disable plugins on all platforms
-    "disable-by-platforms":string[];    // optional: Disable plugins for the specified platform
-    "modules": [{        // mandatory: the libraries included in the plugin, 
-        "target":string;                // mandatory: the name of the corresponding `find_package`, consistent with the first parameter of `CC_PLUGIN_ENTRY`
-        "depends": string|string[];     // optional: depends on other module names 
-        "platforms":string[];           // optional: re-qualify the supported native platforms
+    "name": string;             // Required: Plugin name
+    "version": string;          // Required: Plugin version
+    "engine-version":string;    // Required: Corresponding engine version range
+    "author": string;           // Required: Plugin author
+    "description": string;      // Required: Plugin description
+    "platforms":string[];       // Optional: Supported platform list, defaults to all native platforms if not specified. Includes windows, android, google-play, mac, ios
+    "disabled":true;         // Optional: Disable plugin
+    "disable-by-platforms":string[];    // Optional: Disable plugin on specified platforms
+    "modules": [{                        // Required: Libraries included in the plugin
+        "target":string;                // Required: Corresponding `find_package` name, must be consistent with the first parameter of `CC_PLUGIN_ENTRY`
+        "depends": string|string[];     // Optional: Dependencies on other module names
+        "platforms":string[];           // Optional: Re-specify supported native platforms
     }]
+    
 }
 ```
 
-`engine-version` can specify a version range and exclude specific versions, for example:
-
+`engine-version` can specify version ranges and exclude specific versions. Code example as follows:
+ 
 ```ts
-"engine-version": ">=3.3 <= 3.6.0 !3.5.2 || 4.x"
+"engine-version": ">=3.3 <= 3.6.0 !3.5.2|| 4.x"
 ```
 
-### Example file
-
-Example of description file `cc_plugin.json`
+### File Example
 
 ```json
 {
-    "name": "hello-cocos-demo",
-    "version": "0.1.0",
-    "author": "demo group",
-    "engine-version":">=3.6.0",
-    "description": "demo project",
+    "name":"hello-cocos-demo",
+    "version":"1.0.0",
+    "author":"cocos",
+    "engine-version":">=3.6.3",
+    "disabled":false,
     "modules":[
         {
-            "target": "hello_cocos_glue"
+            "target":"hello_cocos_glue"
         }
     ],
-    "platforms":[ "windows", "android", "mac", "iOS" ]
+    "platforms":["windows", "android", "mac", "ios", "google-play"]
 }
 ```
+## Creating Native Plugins
 
-## Installing Native Plugins
-
-Developers can download and enable editor extensions from the Store that contain native plugins, and complete the installation of the plugins into the `extensions` directory. You can also get the plugin archive from the forums and manually extract it to the `native/` directory or its subdirectories. 
-
-If you want to disable the plugin, or disable it only in a special platform, you can change the relevant fields(`disabled` and `disable-by-platforms`) in `cc_plugin.json`. 
-
-> **Note**: Native plugins require CMake 3.12+, Android projects need to [specify cmake version](https://developer.android.com/studio/projects/install-ndk#vanilla_cmake) to 3.18.1.
+Cocos native projects use CMake for management. Native plugins are managed through the search paths/directories of find_package, so as long as the directory conforms to CMake find_package search rules, the plugin can be loaded correctly. Therefore, the development process of native plugins involves providing CMake configurations and related resources, as well as writing cc_plugin.json. For related examples, please refer to [Native Plugin Creation and Usage Example](./tutorial.md).
 
-## Creating native plugins
+## Installing and Disabling Native Plugins
 
-Cocos native projects are managed using CMake. Simply put, a native plugin is a search directory for `find_package` on specific platform.
+Download the created plugin package from [Native Plugin Creation and Usage Example](https://github.com/zhefengzhang/cocos-native-plugins), and choose to extract it to the `extensions` or `native` directory according to project needs.
 
-As long as the directory matches the cmake find_package search rules, the plugin will load correctly, regardless of whether it is source code or precompiled libraries. Therefore, the development process of a native plugin is the process of providing the cmake configuration and related resources, and writing `cc_plugin.json`.
+If you want to disable the plugin, or disable it only on specific platforms, you can modify the `disabled` and `disable-by-platforms` fields in cc_plugin.json.
 
-See [Cocos Native Plugin Quick Tutorial](./tutorial.md) to learn more about native plugins.
+> **Note**: Native plugins require CMake 3.12+. Android needs to [specify CMake version](https://developer.android.com/studio/projects/install-ndk#vanilla_cmake) as 3.18.1. Other platforms use the built-in CMake in the editor, so the version number does not need to be specified.