Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add mini game doc #2503

Open
wants to merge 10 commits into
base: dev/1.4
Choose a base branch
from
6 changes: 6 additions & 0 deletions docs/en/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,12 @@
"collapse": true
}
},
"platform": {
"title": "Platform",
"theme": {
"collapse": true
}
},
"device": {
"title": "Device",
"theme": {
Expand Down
64 changes: 64 additions & 0 deletions docs/en/platform/h5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
order: 1
title: Export To H5
type: Platform
label: Platform
---

## 平台配置说明

导出到 H5 平台,除了通用导出配置外,并没有额外的平台相关导出配置,故无需配置

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Content should be in English for consistency.

This section and the following content are in Chinese while the document is in the English documentation folder (docs/en). Please translate to English for consistency.

-## 平台配置说明
-
-导出到 H5 平台,除了通用导出配置外,并没有额外的平台相关导出配置,故无需配置
+## Platform Configuration
+
+When exporting to the H5 platform, no additional platform-specific configurations are required beyond the general export settings.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 平台配置说明
导出到 H5 平台,除了通用导出配置外,并没有额外的平台相关导出配置,故无需配置
## Platform Configuration
When exporting to the H5 platform, no additional platform-specific configurations are required beyond the general export settings.

## 导出

选择好 H5 平台后,点击导出面板最下方的下载按钮,即可导出所需工程:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*jINgTIhAuDgAAAAAAAAAAAAADjCHAQ/fmt.webp" />

导出到本地后,目录结构如下:

```shell
├── public # 📁 公共资源目录
│ ├── scene.json # 场景文件
│ └── ... # 其他
├── src # 📁 源代码目录
│ └── ... # 其他
├── index.html # ⚙️ 示例项目入口文件
├── main.js # ⚙️ 组件代码入口
├── package.json # ⚙️ 项目配置文件
├── project.json # ⚙️ 编辑器导出工程配置
├── tsconfig.json # ⚙️ TypeScript 配置文件
├── vite.config.ts # ⚙️ vite 配置文件
└── ... # 其他
```

**备注:** 因为 React/Vue/Vanilla JS 均属于 H5 平台,且大同小异,文档统一以 React 进行说明
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Translate note to English.

The note about React/Vue/Vanilla JS should be in English for consistency.

-**备注:** 因为 React/Vue/Vanilla JS 均属于 H5 平台,且大同小异,文档统一以 React 进行说明
+**Note:** Since React/Vue/Vanilla JS are all part of the H5 platform and share similar characteristics, this documentation uses React for illustration purposes.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**备注:** 因为 React/Vue/Vanilla JS 均属于 H5 平台,且大同小异,文档统一以 React 进行说明
**Note:** Since React/Vue/Vanilla JS are all part of the H5 platform and share similar characteristics, this documentation uses React for illustration purposes.


## 调试

1、进入导出工程的根目录,执行安装命令如下:
```bash
npm i 或者 pnpm i
```

2、执行 dev 命令将项目本地跑起来,如下:
```bash
npm run dev
```
执行完上述命令后,如果成功,将出现如下内容:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*FJI5Q7qhFu4AAAAAAAAAAAAADjCHAQ/fmt.webp" />

3、在浏览器中,输入上述 Local 或者 Network 的 URL 即可预览实际运行效果,如下:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*Q9qwQqivKp8AAAAAAAAAAAAADjCHAQ/fmt.webp" />

## 构建

本地完成开发调试后,执行 build 命令进行构建,如下:
```bash
npm run build
```
如果命令执行成功,会在根目录下生成一个 **dist** 文件夹,里面存放了构建产物。可以将产物上传 CDN,当作动态加载的内容,如果项目是当作一个 React 组件,也可以发布至 NPM。

> 导出到 H5 平台的 React/Vue/Vanilla JS 各类项目,根据各自框架说明自行部署即可
52 changes: 52 additions & 0 deletions docs/en/platform/platform.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
order: 0
title: Platform Export Overview
type: Platform
label: Platform
---

为了满足广大开发者对各个平台上线的诉求,真正做到一处开发,处处运行,Galacean 1.4 版本开始支持多平台导出。开发者通过编辑器制作的项目,可以快速的导出到不同的平台所需的工程。
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Content should be in English for consistency.

The entire content appears to be in Chinese while this is in the English documentation folder (docs/en). Please translate to English for consistency.

For the first paragraph:

-为了满足广大开发者对各个平台上线的诉求,真正做到一处开发,处处运行,Galacean 1.4 版本开始支持多平台导出。开发者通过编辑器制作的项目,可以快速的导出到不同的平台所需的工程。
+To meet developers' needs for multi-platform deployment and achieve true "write once, run anywhere" functionality, Galacean 1.4 introduces multi-platform export capabilities. Projects created in the editor can be quickly exported to different platform-specific projects.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
为了满足广大开发者对各个平台上线的诉求,真正做到一处开发,处处运行,Galacean 1.4 版本开始支持多平台导出。开发者通过编辑器制作的项目,可以快速的导出到不同的平台所需的工程。
To meet developers' needs for multi-platform deployment and achieve true "write once, run anywhere" functionality, Galacean 1.4 introduces multi-platform export capabilities. Projects created in the editor can be quickly exported to different platform-specific projects.
🧰 Tools
🪛 LanguageTool

[uncategorized] ~8-~8: 动词的修饰一般为‘形容词(副词)+地+动词’。您的意思是否是:快速"地"导出
Context: ...acean 1.4 版本开始支持多平台导出。开发者通过编辑器制作的项目,可以快速的导出到不同的平台所需的工程。 ## 前置准备 项目在编辑器中开发完成后,就可以...

(wb4)


## 前置准备
项目在编辑器中开发完成后,就可以导出各个平台的工程并进行发布了。在导出之前,我们先来了解一下导出面板和导出设置。

### 导出面板
当我们完成项目开发,需要导出到某个平台(以导出至微信小游戏平台为例)的时候,可以按如下步骤操作:

1、点击编辑器左侧的导出按钮:

<img src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*U2RuQLwwNXIAAAAAAAAAAAAADjCHAQ/fmt.webp" />

2、在唤出的导出面板的左侧,选择导出平台:

<img src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*50WSQoBlxpcAAAAAAAAAAAAADjCHAQ/fmt.webp" />

3、导出面板的右侧为项目相关的一些导出配置,主要分为 2 块:**通用配置**(红色框内)和**平台相关配置**(黄色框内):

<img src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*aCiZTLygoQwAAAAAAAAAAAAADjCHAQ/fmt.webp"/>

### 导出配置说明

平台相关的导出配置将在平台导出的文档里单独说明,这里重点介绍下和平台无关的**通用配置**。

| 配置 | 描述 |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Project Name | 项目名称,导出到本地的根目录名就是项目名称 |
| Main Scene | 项目主场景 |
| Engine version | 项目使用的引擎版本号 |
| Upload to CDN | 是否将资产上传至 CDN |
| Texture Type | 纹理类型,支持 KTX2 和 Original:<br> **Original**:不对纹理做任何处理 <br> **KTX2**:开启纹理压缩 <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*yHPrSrhyo0sAAAAAAAAAAAAADjCHAQ/fmt.webp" /> 选择 KTX2 可以选择不同的压缩格式:<br> **ETC1S:** 尺寸小,内存极小,但是质量较低,适合 albedo, specular 等贴图 <br> **UASTC:** 尺寸大,质量高,适合 normal 这类贴图 <br> <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*_Ga2SKIDvv0AAAAAAAAAAAAADjCHAQ/fmt.webp" /> 如果选择了 ETC1S 压缩格式,可以通过 Quality 来设置压缩质量(值越大,渲染质量越好):<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*ZhviTYuo7A4AAAAAAAAAAAAADjCHAQ/fmt.webp" />|
| Tree shaking | 是否对导出的资产进行裁剪: <br> **None:** 不进行裁剪,导出所有资产 <br> **Current Scene:** 只导出当前场景用到的资产 <br> **All Scene:** 对所有场景 treeshaking,导出全量场景用到的资产 <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*BJbwQrdlghwAAAAAAAAAAAAADjCHAQ/fmt.webp" />|
| WebGL Mode | 选择使用 WebGL 的版本:<br> **Auto:** 优先使用 WebGL2.0, 如果运行环境不支持自动切到 WebGL1.0 <br> **WebGL1.0:** 使用 WebGL1.0 <br> **WebGL2.0:** 使用 WebGL2.0 <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*HszfTJChrdEAAAAAAAAAAAAADjCHAQ/fmt.webp" />|
| Anti-Alias | 是否开启抗锯齿 |
| Alpha | 画布是否支持透明背景,如果希望画布下方的内容可以透出可以开启 |
| Preserve Drawing Buffer | 用于控制在调用 gl.clear() 方法后,绘图缓冲区是否保留其内容 |
| DPR Mode | [设备的像素比](/en/docs/core/canvas),通过调用 engine.canvas.resizeByClientSize 来控制画布的尺寸 <br> **Auto:** 自动适配,即参数为 window.devicePixelRatio <br> **Fixed:** 开发者自行设置参数 <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*EQOxSI8I8awAAAAAAAAAAAAADjCHAQ/fmt.webp" /> 选择 Fixed 后,开发者可以自行输入需要设置的参数 <image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*-7YfTLegt_AAAAAAAAAAAAAADjCHAQ/fmt.webp" />|

## 支持的导出平台
目前 Galacean 支持导出的平台如下:

[导出至 H5 平台](/en/docs/platform/h5/)

[导出至微信小游戏平台](/en/docs/platform/wechatMiniGame/)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Links need to be updated to match the repository structure

The current links include an incorrect path segment. They should be:

  • /en/platform/h5/ (remove "docs")
  • /en/platform/wechatMiniGame/ (remove "docs")
🔗 Analysis chain

Verify documentation links.

The links to platform-specific documentation need verification to ensure they are correct and accessible.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Check if the linked documentation files exist
echo "Checking H5 documentation link..."
[ -f "docs/en/platform/h5.md" ] && echo "✓ H5 doc exists" || echo "✗ H5 doc missing"

echo "Checking WeChat Mini Game documentation link..."
[ -f "docs/en/platform/wechatMiniGame.md" ] && echo "✓ WeChat doc exists" || echo "✗ WeChat doc missing"

Length of output: 355


Script:

#!/bin/bash
# List all platform documentation files
echo "=== All platform documentation files ==="
fd . "docs/en/platform" -t f

echo -e "\n=== Content preview of h5.md ==="
head -n 5 docs/en/platform/h5.md

echo -e "\n=== Content preview of wechatMiniGame.md ==="
head -n 5 docs/en/platform/wechatMiniGame.md

# Check if there's a docs/en/docs directory (as used in links)
echo -e "\n=== Checking alternate docs path ==="
[ -d "docs/en/docs" ] && echo "docs/en/docs exists" || echo "docs/en/docs does not exist"

Length of output: 794


74 changes: 74 additions & 0 deletions docs/en/platform/wechatMiniGame.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
order: 2
title: Export To WechatMiniGame
type: Platform
label: Platform
---

## 平台配置说明

在导出到微信小游戏平台的时候,有以下这些配置项:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Content should be in English for consistency.

This section title and the following paragraph are in Chinese while the document is in the English documentation folder (docs/en). Please translate to English for consistency.

-## 平台配置说明
-
-在导出到微信小游戏平台的时候,有以下这些配置项:
+## Platform Configuration
+
+When exporting to the WeChat Mini Game platform, the following configuration options are available:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 平台配置说明
在导出到微信小游戏平台的时候,有以下这些配置项:
## Platform Configuration
When exporting to the WeChat Mini Game platform, the following configuration options are available:


<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*natiS7i3cvUAAAAAAAAAAAAADjCHAQ/fmt.webp" />
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add alt text to images for accessibility.

Images should include descriptive alt text for accessibility. Add alt attributes to all images in the document.

Example for the first image:

-<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*natiS7i3cvUAAAAAAAAAAAAADjCHAQ/fmt.webp" />
+<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*natiS7i3cvUAAAAAAAAAAAAADjCHAQ/fmt.webp" alt="WeChat Mini Game export configuration panel" />

Also applies to: 16-21, 29-29, 41-41, 49-49, 54-54, 61-61


| 配置 | 描述 | 对应到微信小游戏的配置文件 | 对应到微信小游戏中的字段
| ------------- | ------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| AppId | 微信小游戏的 AppId,必填,截图中的 wxdf8199565c509fb9 为测试账号 | project.config.json | appid |
| Orientation | 设置游戏屏幕方向: Landscape(横屏)、Portrait(竖屏)| game.json | deviceOrientation |
| Request | wx.request 的超时时间,单位:毫秒 | game.json | networkTimeout.request |
| Connect Socket | wx.connectSocket 的超时时间,单位:毫秒 | game.json | networkTimeout.connectSocket |
| Upload File | wx.uploadFile 的超时时间,单位:毫秒 | game.json | networkTimeout.uploadFile |
| Download File | wx.downloadFile 的超时时间,单位:毫秒 | game.json | networkTimeout.downloadFile |

更多配置详见:[project.config.json](https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html)、[game.json](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)

## 导出

选择好微信小游戏平台后,点击导出面板最下方的下载按钮,即可导出所需工程:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*a1-PQIsWlgIAAAAAAAAAAAAADjCHAQ/fmt.webp" />

## 调试

1、工程导出到本地后,先进入到根目录执行以下命令进行依赖包的安装:

```bash
npm i
```

2、打开**微信开发者工具** ,选择小游戏,并导入刚才的工程,如下:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*gCnXSqRgLnMAAAAAAAAAAAAADjCHAQ/fmt.webp" />

3、在微信开发者工具中,点击**工具->构建 npm**,如下:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*G5aBQKNFdV8AAAAAAAAAAAAADjCHAQ/fmt.webp" />

4、完成上述 3 后,即可在微信开发者工具中预览最终的结果,如下:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*JyoIS54k3uYAAAAAAAAAAAAADjCHAQ/fmt.webp" />

5、在微信开发者工具中的调试,详见:[微信小游戏调试](https://developers.weixin.qq.com/minigame/dev/guide/runtime/debug/)

## 发布

本地完成调试后,即可进行发布,具体发布流程详见:[微信小游戏发布](https://developers.weixin.qq.com/minigame/introduction/guide/)

## 导出工程目录说明

导出到本地的工程目录如下:

<image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*3jBDQYE5T9AAAAAAAAAAAAAADjCHAQ/fmt.webp" />

**工程目录说明**
|目录或文件|说明|
|-------------|-------------|
|adapters|项目用到的引擎相关的包,按需导出|
|public|资产目录,编辑器所有资产导出到这个目录下,资产的 path 为 /public/xxx|
|scripts|开发者在编辑器中添加的脚本组件,导出到本地后,开发者可以在里面的脚本组件中进行二次开发|
|game.json|对应微信小游戏工程所需要的 [game.json](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)|
|game.ts|入口文件,初始化的逻辑都放在这里|
|package.json|主要存放项目依赖包|
|polyfill.js|平台 DOM 适配代码和全局变量适配代码,开发者无需关心|
|project.config.json|对应微信小游戏工程所需要的 [project.config.json](https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html)|
|project.ts|Galacean 的工程文件,在初始化的时候会解析|
6 changes: 6 additions & 0 deletions docs/zh/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,12 @@
"collapse": true
}
},
"platform": {
"title": "多平台发布",
"theme": {
"collapse": true
}
},
"device": {
"title": "设备",
"theme": {
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/art/digital-human.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ title: 数字人项目

### 2. 编辑器项目

你可以按照 [导入教程](/docs/graphics/model/importGlTF/) 等一步步实现编辑器的预览,最后进行[项目导出](/docs/assets/build/)到需要的平台。
你可以按照 [导入教程](/docs/graphics/model/importGlTF/) 等一步步实现编辑器的预览,最后进行[项目导出](/docs/platform/platform/)到需要的平台。

### 3. 高级动画定制

Expand Down
92 changes: 0 additions & 92 deletions docs/zh/assets/build.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/zh/assets/overall.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,6 @@ flowchart LR

- 如何[自定义资产加载器](/docs/assets/custom)
- 编辑状态下[资产的增删改查](/docs/assets/interface)
- 构建项目后[资产如何导出并部署](/docs/assets/build)
- 构建项目后[资产如何导出并部署](/docs/platform/platform)
- 运行时如何[加载资产](/docs/assets/load)
- 运行时如何[垃圾回收](/docs/assets/gc)
2 changes: 1 addition & 1 deletion docs/zh/core/canvas.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ flowchart TD
C[HtmlCanvas.clientHeight] -->|pixelRatio| D[WebCanvas.height]
```

若通过编辑器导出 **NPM package** 进行开发,只需在[项目导出](/docs/assets/build)渲染导出配置处控制**设备像素比**即可。
若通过编辑器导出 **NPM package** 进行开发,只需在[项目导出](/docs/platform/platform)渲染导出配置处控制**设备像素比**即可。

<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*afw5QrbrxkQAAAAAAAAAAAAADhuCAQ/original" alt="image.png" style="zoom:50%;" />

Expand Down
2 changes: 1 addition & 1 deletion docs/zh/core/engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ classDiagram
}
```

编辑器导出的项目通常自动设置了编辑器配置的相关选项,比如开发者可以在 [导出界面](/docs/assets/build) 设置上下文的渲染配置:
编辑器导出的项目通常自动设置了编辑器配置的相关选项,比如开发者可以在 [导出界面](/docs/platform/platform) 设置上下文的渲染配置:

<img src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*WZHzRYIpUzQAAAAAAAAAAAAADhuCAQ/original" style="zoom:50%;" />

Expand Down
2 changes: 1 addition & 1 deletion docs/zh/graphics/2D/spine/editor.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ SpineAnimationRenderer 组件的配置如下:
- Priority:渲染优先级

## 4. 项目导出
最终,完成场景编辑器后,可以参考[项目导出](/docs/assets/build/)流程,导出编辑器项目。
最终,完成场景编辑器后,可以参考[项目导出](/docs/platform/platform/)流程,导出编辑器项目。

</br></br></br></br>
下一章节:[在代码中使用 Galacean Spine 运行时](/docs/graphics/2D/spine/runtime)
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/graphics/2D/spine/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Galacean spine 加载器既能加载编辑器上传的资产,也能过加载
## 加载资产并添加至场景

### 加载 Galacean 编辑器中的上传的资产
[导出编辑器项目后](/docs/assets/build/)`已添加至场景中的 Spine 动画,会在加载场景文件时,自动完成加载`
[导出编辑器项目后](/docs/platform/platform/)`已添加至场景中的 Spine 动画,会在加载场景文件时,自动完成加载`

```typescript
// 加载场景文件时,已添加至场景中的 Spine 动画会自行完成加载
Expand Down
Loading
Loading