Skip to content

安装

通过 NPM 安装

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

  1. 安装依赖

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

bash
npm install @orillusion/core --save
  1. 引入模块

引入指定模块:

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

或引入全局模块:

ts
import * as Orillusion from '@orillusion/core'

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

通过 CDN 链接引入

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

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

1. 全局构建版本

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

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

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

2. ESModule 构建版本

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

html
<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.7.x/dist/orillusion.es.js" 
</script>

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

3. 使用 importmap

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

html
<!-- 可以定义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>