# @aura3d/core 中文文档

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

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

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

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

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

- 包体积（解压后）：105 kB，62 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-06T02:14:40.107Z
- 最新版本发布：2026-10-31T13:38:52.359Z
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

Aura3D的引擎生命周期、调度、确定性时间步进、诊断、事件、日志、任务队列和一次性资源范围。

## 安装

```sh
npm install @aura3d/core
```

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

## README

# @aura3d /核心

`@aura3d/core` 拥有引擎生命周期、调度脊柱、确定性时间步进、诊断、事件、日志、任务队列和一次性资源范围。它是根运行时包，不依赖于场景、渲染、物理、动画、资源、输入、音频、脚本、编辑器或仅用于浏览器的api。

## 公共API

-   `Engine`：插件初始化、调度程序执行、手动步进、启动/停止控制、事件、诊断、任务队列和资源处置的生命周期所有者。
-   `EngineConfig`， `resolveEngineConfig`， `ResolvedEngineConfig`：针对固定步长计时、最大帧增量、时间尺度和可选的自动启动行为的有效运行时配置。
-   `EngineLoop`， `FrameContext`使用的确定性框架循环 `Engine` 手动和requestanimationframe支持的执行。
-   `FixedStepAccumulator`：固定步长蓄能器，具有最大步长箝位，用于确定性仿真相位。
-   `Scheduler`， `SystemPhase`：显式有序的阶段调度程序，具有依赖性验证、重复拒绝、周期检测和跨阶段依赖性拒绝。
-   `TaskQueue`：在引擎任务阶段刷新异步安全队列。
-   `EventBus`：引擎生命周期、框架和错误信号使用的类型化事件发射器。
-   `Diagnostics`：结构化度量/计数器快照支持。
-   `Logger`：有作用域的运行时日志抽象。
-   `DisposableStack`， `ResourceScope`确定性后进先出清理原语。
-   `VersionedSchema`， `MigrationRegistry`， `SaveSlot`：独立于浏览器的模式验证，保存数据迁移，保存槽元数据/数据快照。
-   `ValidationError`， `LifecycleError`为无效的配置、图形和生命周期操作键入错误类。

## 生命周期的合同

一个 `Engine` 开始于 `created`． 插件只能在这种状态下注册。调用 `init()` 转换通过 `initializing` 成 `initialized`、调用插件 `init` 按注册顺序排列的处理程序。如果任何插件初始化失败，已经初始化的插件处理器将以相反的顺序运行，引擎将转换为 `failed`.

调用 `start()` 仅从 `initialized` 或者 `stopped`;它启动配置好的循环，并转换到 `running`． 调用 `stop()` 从 `running` 停止循环并过渡到 `stopped`． 调用 `step(delta)` 从 `created` 初始化引擎，然后执行一个确定性框架 `initialized`， `running`，或者 `stopped`.

每一帧执行阶段的顺序如下：

1.  `Platform`
2.  `Tasks`
3.  排队 `TaskQueue` 工作
4.  `Fixed`，每累积固定步一次
5.  `Update`
6.  `Scene`
7.  `Render`
8.  `Present`
9.  `Cleanup`

调用 `dispose()` 是等幂的。如果引擎正在运行，它首先停止，然后处置插件资源和引擎拥有的 `ResourceScope` 条目、清除事件和转换到 `disposed`． 处理错误报告为 `AggregateError`.

## 验证

生命周期，调度器，固定步骤，插件回滚，确定性手动步进和帧诊断包括：

-   `tests/unit/core/scheduler-engine.test.ts`
-   `tests/unit/core/config-time.test.ts`
-   `tests/unit/core/events-disposal-diagnostics.test.ts`
-   `tests/unit/core/versioned-serialization.test.ts`
-   `tests/integration/engine-loop.test.ts`
-   `tests/browser/core-raf-loop.spec.ts`

包含公共导出和导入边界 `pnpm verify:exports`， `pnpm verify:imports`, `pnpm verify:boundaries`.

## 常见问题

### @aura3d/core 是什么？

Aura3D的引擎生命周期、调度、确定性时间步进、诊断、事件、日志、任务队列和一次性资源范围。

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

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

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

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

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

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

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

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

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

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