# @aura3d/engine 中文文档

规范地址：https://npmcn.com/package/%40aura3d/engine/

版本：4\.7\.0
npm 元数据更新时间：2026-10-31T13:49:55.836Z
中文译文更新时间：2026-10-31T15:13:50.460Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aura3d/engine
原文对照：https://npmcn.com/package/%40aura3d/engine/?lang=original
项目主页：https://aura3d.auraone.ai/
源码仓库：https://github.com/auraoneai/aura3d

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：48.5 MB，8037 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：recast-navigation 0\.43\.1，@dimforge/rapier3d-compat 0\.20\.0
- 首次发布：2026-06-03T06:53:12.179Z
- 最新版本发布：2026-10-31T13:49:19.415Z
- 已发布版本数：57（近 12 个月 57 个）

## 中文简介

使用TypeScript、键入GLB/glTF资产、Vite模板、场景工具包、诊断、截图和部署检查构建ai授权的浏览器3D应用程序。

## 安装

```sh
npm install @aura3d/engine
```

也可以使用：`pnpm add @aura3d/engine`、`yarn add @aura3d/engine`、`bun add @aura3d/engine`

## README

# Aura3D

[![npm version](https://img.shields.io/npm/v/@aura3d/engine.svg)](https://www.npmjs.com/package/@aura3d/engine) [![npm downloads](https://img.shields.io/npm/dm/@aura3d/engine.svg)](https://www.npmjs.com/package/@aura3d/engine) [![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-browser%203D-3178c6.svg)](https://www.typescriptlang.org/)

**TypeScript 3D引擎提供了整个堆栈。** Aura3D是一个带有自己渲染器的浏览器3D引擎，加上围绕它的工具链：类型和授权资产，照明外观，游戏套件和部署检查。它是为代理编写的浏览器3D构建的，手工编写它的人使用相同的API。当前版本已导入 [`CHANGELOG.md`](https://npmcn.com/package/%40aura3d/engine/CHANGELOG.md).

一个带有轨道控制的发光、阴影、框架产品，共10行：

```ts
import { camera, createAuraApp, interactions, looks, model, scene } from "@aura3d/engine";
import { assets } from "./aura-assets";

createAuraApp("#app", {
  scene: scene()
    .add(looks.preset("product-studio"))
    .add(model(assets.product, { name: "product", targetHeight: 1.6, castShadow: true }))
    .add(interactions.orbit({ target: "product" }))
    .camera(camera.frameAsset(assets.product, { targetHeight: 1.6 })),
  ...looks.appOptions("product-studio")
});
```

一、 `looks.preset` 提供基于图像的光，阴影投射键，雾，背景和post grade作为一个单元。 `model(assets.product)` 是由CLI生成的类型化资产，而不是原始URL。js中的相同场景在轨道控制([口号检查](https://npmcn.com/package/%40aura3d/engine/evidence/vs-threejs/tagline-check/);行计数包括导入和跳过（空白行和注释行）。

## 以五个命令开始

```bash
npx create-aura3d@latest my-scene --template mini-game       # also writes llms.txt and the Aura3D agent skills
cd my-scene && npm install
npm run dev                                                  # Vite on 127.0.0.1
npx @aura3d/cli@latest assets resolve "robot" --name robot   # assets add also works for local GLBs; then model(assets.robot)
npm run build && npx @aura3d/cli@latest check-deploy --dist dist
```

模板: `product-viewer` (默认), `cinematic-scene`， `mini-game`， `racing-starter`， `falling-blocks-starter`， `fighting-game`， `character-controller`， `arena-shooter` 还有更多(`npx create-aura3d@latest --help`）。

## 如果你是一个人工智能代理

读 [`llms.txt`](https://npmcn.com/package/%40aura3d/engine/llms.txt) （一个屏幕，快速路径），然后 [`docs/agents/agent-quickstart.md`](https://npmcn.com/package/%40aura3d/engine/docs/agents/agent-quickstart.md) 和 [`docs/agents/claims-and-boundaries.md`](https://npmcn.com/package/%40aura3d/engine/docs/agents/claims-and-boundaries.md)． 每个代理文档的索引为 [`docs/agents/README.md`](https://npmcn.com/package/%40aura3d/engine/docs/agents/README.md);技能生活 [`packages/aura3d-cli/skills/`](https://npmcn.com/package/%40aura3d/engine/packages/aura3d-cli/skills/). `npx create-aura3d@latest` 和 `npx @aura3d/cli@latest init --agent all` 将指令文件写入项目中。

## 你得到了什么

-   **类型化场景API。** `scene`， `model`， `looks`， `lights`， `camera`， `effects`， `interactions`， `primitives`， `instances` 和 `game.*` 通过一个入口， `@aura3d/engine`.
-   **输入的、经过出处检查的资产。** `assets search`， `assets resolve`， `assets add`， `assets import-meshy`， `assets optimize`， `assets validate`． 在生产环境中，模型需要同源URL、sha256和来源，否则它将不绘制任何内容。网格生成通过带有准入记录的CLI。
-   **游戏装备。** `@aura3d/engine/game` （`createGame`（生命周期，暂停，结果，DOM HUD，触摸，果汁，声音）， `createFixedStepLoop`， `installQaHooks` 和种子重赛， `createCueBank` 音频合成器, `defineModelAssets`，球拍运动和其他类型的工具包。
-   **安全网。** `installSafetyNet` 从 `@aura3d/debug`： `?diag=1` 面板，优质开关和黑框自愈。自定义着色器失败报告，而不是沉默。
-   **检查。** `aura3d doctor`， `aura3d check-deploy` (添加 `--browser` 加载headless Chromium中的每个路由，并在失败的请求和控制台错误时失败)，路由健康和屏幕截图证据，look-dev循环(`aura3d look capture`， `aura3d look lint`）。
-   **迁移。** `aura3d migrate three` 是记录每个近似的代码模块。这不是一个临时索赔。

组件的文档: [`docs/api/game-kit.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/game-kit.md)， [`qa-kit.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/qa-kit.md)， [`safety-net.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/safety-net.md)， [`audio-synth.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/audio-synth.md)， [`model-loader.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/model-loader.md)， [`glsl-chunks.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/glsl-chunks.md)， [`scatter-merge.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/scatter-merge.md)， [`cli-asset-tools.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/cli-asset-tools.md)， [`toon.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/toon.md).

## 用它来建造

这个 [展示指数](https://aura3d.auraone.ai/apps/showcase-index/) 有25款可玩游戏，包括赛车，运动，动作，平台和街机，包括Aura Slam 3D（网球，带有确定性重播门），Apex Overdrive（赛车），Glint Courier（迷宫追逐）和Craterline GP（自行车赛车）。每页都说明了它的限制；游戏是独立作品，不隶属于任何其他游戏或工作室。游戏在WebGL2软件上进行远程检查；real-GPU确认是部分的，并在 [`evidence/`](https://npmcn.com/package/%40aura3d/engine/evidence/).

## 为什么是Aura3D而不是three.js

js给你一个渲染器。Aura3D是一个完整的TypeScript 3D引擎和工具链，它有自己的渲染器，所以3 .js留给你的部分是内置的：

-   **一个有灯光、阴影、框架的10行产品。** js中的相同场景在轨道控制([口号检查](https://npmcn.com/package/%40aura3d/engine/evidence/vs-threejs/tagline-check/)）. 在我们的5个场景基准测试中，带有HDR照明、阴影、绽放和轨道控制的PBR查看器是24行而不是49行，1个导入而不是8行([结果](https://npmcn.com/package/%40aura3d/engine/evidence/vs-threejs/RESULTS.md)）。
-   **你可以信任的资产。** 每个模型都经过输入、散列和许可；在生产中，未经验证的模型无法绘制。
-   **包括游戏堆栈。** HUD，触摸控制，音频提示，固定步长循环，种子回放，安全网和120和144hz显示器的平滑运动。
-   **为AI编码代理构建。** `llms.txt`每个新项目都会附带14项技能和汇编的食谱。
-   **在已发布的4.5.0包上进行测量。** 一个立方体场景在420毫秒内到达第一帧，并在一次调用中绘制；一个带有阴影和花朵的PBR查看器场景绘制在25。五个基准测试场景没有记录控制台警告或错误，并且16个选项覆盖测试通过，因此一个选项要么生效，要么引发 `OPTION_IGNORED`． 软件WebGL2远程运行，一次运行，第一帧中位数为3个冷负载；非GPU编号([结果](https://npmcn.com/package/%40aura3d/engine/evidence/vs-threejs/RESULTS-4.5.0.md)）。

移植一个已有的three.js项目： [`docs/migration/from-threejs.md`](https://npmcn.com/package/%40aura3d/engine/docs/migration/from-threejs.md).

## 包

公共包(都在同一个版本； `@aura3d/engine` 是这个存储库的根目录)：

| 包 | 目的 |
| --- | --- |
| `@aura3d/engine` | 公共运行时: `createAuraApp`，场景节点，外观，效果，游戏套件，子路径等 `/game` 和 `/audio` |
| `@aura3d/cli` | 类型资产工作流，跨开放公共资源的资产搜索，mesh准入，look-dev， `check-deploy`， `init`， `migrate three` |
| `create-aura3d` | Vite项目脚手架与代理技能和 `llms.txt` |
| `@aura3d/core`， `@aura3d/math`， `@aura3d/scene` | 生命周期和确定性步进，数学，场景图 |
| `@aura3d/rendering` | 渲染设备，WebGL2后端，材料，通道 |
| `@aura3d/assets`， `@aura3d/asset-index` | 资产加载和缓存；跨公共资源的资产搜索 |
| `@aura3d/animation`， `@aura3d/audio`， `@aura3d/input`， `@aura3d/controls` | 剪辑和状态机，音频总线，输入，摄像机控制 |
| `@aura3d/physics`， `@aura3d/physics-rapier`， `@aura3d/navigation-recast` | 物理，可选的剑和导航适配器 |
| `@aura3d/ecs`， `@aura3d/scripting` | ECS和行为图 |
| `@aura3d/debug` | 诊断和运行时安全网 |
| `@aura3d/product-studio`， `@aura3d/apps`， `@aura3d/workflows`， `@aura3d/react`， `@aura3d/editor-runtime` | 产品查看器、应用预设、工作流、React主机、编辑器运行时 |

`@aura3d/engine/production-runtime`， `/advanced-runtime`， `/rendering` 和 `/contracts` 是弃用的子路径；新代码使用根目录。

## 索赔和核实

每一项公开声明 [`docs/agents/claims-and-boundaries.md`](https://npmcn.com/package/%40aura3d/engine/docs/agents/claims-and-boundaries.md)：标明能力，并只要求经过判断的捕获或保留的证据显示的能力。发布的门包括路由运行状况、类型来源、公共api表面检查、包大小检查和 `check-deploy`． 发行说明见 [`CHANGELOG.md`](https://npmcn.com/package/%40aura3d/engine/CHANGELOG.md).

## 文档

-   [`docs/index.md`](https://npmcn.com/package/%40aura3d/engine/docs/index.md)：人类和代理的中心
-   [`docs/agents/README.md`](https://npmcn.com/package/%40aura3d/engine/docs/agents/README.md)：代理文档索引
-   [`docs/api/public-api.md`](https://npmcn.com/package/%40aura3d/engine/docs/api/public-api.md)：公共API
-   [`docs/aura3d-vs-threejs.md`](https://npmcn.com/package/%40aura3d/engine/docs/aura3d-vs-threejs.md) 和 [`docs/migration/from-threejs.md`](https://npmcn.com/package/%40aura3d/engine/docs/migration/from-threejs.md)为什么Aura3D超过three.js，以及如何移植
-   [`docs/workflows/game-conversion-playbook.md`](https://npmcn.com/package/%40aura3d/engine/docs/workflows/game-conversion-playbook.md)：将浏览器游戏转变为Aura3D游戏
-   网站: [https://aura3d.auraone.ai](https://aura3d.auraone.ai/)

## 贡献

使用提示、包版本、资源源和屏幕截图或路由运行状况输出打开问题。在这个单线程中，浏览器、剧作家套件和重型构建在远程运行器上运行。`tools/remote-acr/run.sh`)，而不是在笔记本电脑上。麻省理工学院授权。

## 常见问题

### @aura3d/engine 是什么？

使用TypeScript、键入GLB/glTF资产、Vite模板、场景工具包、诊断、截图和部署检查构建ai授权的浏览器3D应用程序。

### 如何安装 @aura3d/engine？

在项目目录运行 npm install @aura3d/engine，或使用 pnpm add / yarn add / bun add。

### @aura3d/engine 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aura3d/engine 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aura3d/engine 可以商用吗？

@aura3d/engine 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aura3d/engine 还在维护吗？

最新版本 4\.7\.0 发布于 2026/10/31（2 天前）；至今共发布 57 个版本，其中过去 12 个月发布了 57 个；首次发布于 2026/06/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。