安装

TIP

WebGPU 属于低级访问权限 API，为了防止中间人攻击，大部分浏览器限制仅能在 Secure contexts 中访问使用。当发布基于 WebGPU 构建的 Web 应用时，需要用户自行部署基于 https 的安全域名，或基于 localhost 的域名进行访问，包括 http://127.0.0.1，http://localhost 或 http://*.localhost 等自定义域名。

通过 NPM 安装

我们推荐使用基于 Node.js 的前端构建工具来开发 Web3D 应用，比如配合 Vite 或 Webpack 等前端生态框架来构建复杂的前端项目，当然也可以更方便的使用 TypeScript 进行开发。

1. 安装依赖

使用 npm 命令在提示行中安装引擎依赖：

npm install @orillusion/core --save

2. 引入模块

引入指定模块：

import { Engine3D, Camera3D } from '@orillusion/core'

或引入全局模块：

import * as Orillusion from '@orillusion/core'

TIP

Orillusion 引擎需要支持最新的 WebGPU 标准的浏览器运行，例如 Chrome >= 114, 因此无需兼容旧版 JavaScript 语法，默认基于 ESNext 进行构建发布。如果您使用 Vite 或 Webpack 等构建工具来部署项目，推荐将构建目标设定为 ES2021 及以上版本来确保所有 API 以最佳状态运行。

通过 CDN 链接引入

我们也支持借助 <script> 标签直接通过 CDN 链接快捷使用 orillusion 引擎。下面以 @orillusion/core 链接为例，展示三种不同的引入方法。

用户可以使用第三方 NPM 分发服务来加载 orillusion 各个版本文件，如 unpkg 或 jsdelivr 等。如有本地开发需求，用户可以下载对应版本的 js 文件，自主进行部署。

1. 全局构建版本

<!- 通过 unpkg 加载最新发布版本 ->
<script src="https://unpkg.com/@orillusion/core/dist/orillusion.umd.js"></script>
<!- 或加载指定版本 ->
<script src="https://unpkg.com/@orillusion/core@0.8.x/dist/orillusion.umd.js"></script>

页面全局加载 <script>，window 对象中会引入一个全局 Orillusion 变量，直接使用即可：

<script>
  const { Engine3D, Camera3D } = Orillusion
</script>

2. ESModule 构建版本

我们推荐使用 ESModule 语法进行开发。大多数浏览器已经支持原生 ES 模块，用户可以直接引入符合 ESNext 标准的 orillusion.es.js 构建版本进行快速开发:

<script type="module">
  // 或从 unpkg.com 加载最新版本
  import { Engine3D, Camera3D } from "https://unpkg.com/@orillusion/core/dist/orillusion.es.js" 
  // 或加载指定版本 
  import { Engine3D, Camera3D } from "https://unpkg.com/@orillusion/core@0.8.x/dist/orillusion.es.js" 
</script>

注意我们使用了 <script type="module"> 标签，这使得我们可以在浏览器中直接使用 import 和 export 等模块化语法。当然配合 vite 等前端构建工具，我们也可以直接在项目中导入 CDN 链接进行开发。

3. 使用 importmap

为了统一管理依赖的地址和名称，我们推荐使用 导入映射表(Import Maps) 来管理浏览器如何定位依赖包：

<!-- 可以定义ES模块的名称和对应地址 -->
<script type="importmap">
{
  "imports": {
    "@orillusion/core": "https://unpkg.com/@orillusion/core/dist/orillusion.es.js",
    "@orillusion/stats": "https://unpkg.com/@orillusion/stats/dist/stats.es.js"
  }
}
</script>
<!-- 可以使用自定义名称引入 -->
<script type="module">
  import { Engine3D, Camera3D } from "@orillusion/core"
  import { Stats } from "@orillusion/stats"
</script>