# @driftengine/core 中文文档

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

版本：4\.14\.3
npm 元数据更新时间：2026-11-03T16:30:08.076Z
中文译文更新时间：2026-11-12T23:13:16.342Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：24.5 MB，1755 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：3 个
- 首次发布：2026-09-13T02:15:04.145Z
- 最新版本发布：2026-11-03T16:30:07.812Z
- 近 30 天下载量：3316（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

DriftEngine的运行时间,一个WebGPU的游戏引擎,带有WebGL2回落:渲染器,循环,输入,相机,场景图和物理

## 安装

```sh
npm install @driftengine/core
```

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

## README

# @ driftengine/ core (英语)

运行时间 [漂流引擎](https://github.com/drftrun/driftengine),用于网络的 三维游戏引擎 和已安装的应用程序。 它通过 WebGPU 绘制浏览器有设备的地方和通过 WebGL2 其他任何地方,一个API后面, 并携带固定步骤环路, 渲染器,相机, 输入、场景图、几何、文字和全部 `@driftengine/physics`,它再出口. 其它的都是一个单独的包 当游戏到达它.

**费用:966.4 KB gzipped, 进口 `createRenderer`。 。 。 .** 以 `scripts/size-gate.test.mjs`, (中文(简体) ), 如果数字漂移超过3%,则会失败.

手册在 **[dev/docs (英语)](https://driftengine.dev/docs)**,并运行示例 除了每一章, 每一个导出都在 [参考文献](https://driftengine.dev/docs/api)。 。 。 .

## 安装

```sh
npm install @driftengine/core
```

它决心编译JavaScript,所以任何ES模块捆绑器都把它当作它;Vite就是什么 实例使用。 一个浏览器至少需要WebGL2,这是每个当前都有的. [安装](https://driftengine.dev/docs/start/installation) 覆盖页面、 类型脚本和 后门.

## 快速启动

一个点亮的立方体在固定的台阶上打开,在页面上 `<canvas id="stage">`数字 :

```ts
import {
  Camera,
  MeshBuilder,
  SceneNode,
  createEnvironment,
  createRenderer,
  srgbColor,
  startLoop,
} from '@driftengine/core';
import { bindModule } from '@driftengine/script';
import { loadModule, patchModule } from 'driftscript';
import * as spinScript from './spin.drs';

const canvas = document.querySelector<HTMLCanvasElement>('#stage');
if (canvas === null) throw new Error('the page must carry <canvas id="stage">');

/*
 * Asynchronous because it has to be: asking for a WebGPU adapter returns a promise, and there
 * is no synchronous way to learn whether a usable device exists. The fall back to WebGL2 is
 * automatic and silent, so `reason` is the only thing that says why. Print it: the first
 * question asked about any picture is what drew it.
 */
const { renderer, backend, reason } = await createRenderer(canvas, {
  maxDevicePixelRatio: 1.75,
});

const readout = document.querySelector('#backend');
if (readout !== null) readout.textContent = `${backend}: ${reason}`;

renderer.resize();
addEventListener('resize', () => renderer.resize());

/**
 * Light, air and ground bounce. Chosen once, because these are allocation-sized decisions.
 *
 * Every colour here and below was picked by eye, so it goes through `srgbColor`: the renderer
 * lights in linear values and encodes them for the screen at the end, and a colour typed as it
 * looks would come out too light. The clear colour in the loop is one of them.
 */
const CLEAR = srgbColor(0.05, 0.06, 0.09);

const ENV = createEnvironment({
  directionalDir: [0.4, 0.7, 0.35],
  directionalColor: srgbColor(1, 0.96, 0.88),
  ambient: srgbColor(0.2, 0.22, 0.28),
  ambientGround: srgbColor(0.08, 0.08, 0.1),
  emissiveGain: 0,
  nightFactor: 0,
  fogColor: srgbColor(0.16, 0.18, 0.24),
  fogDensity: 0.004,
  fogHeightFalloff: 0.03,
  fogBaseY: 0,
});

/*
 * Colour is vertex data here, which is what lets a whole world be flat-shaded draw calls.
 * `addBox` takes a centre and *half* extents, so this ground is 24 units across and the cube
 * is two units on a side.
 */
const shapes = new MeshBuilder();
shapes.addBox([0, 1, 0], [1, 1, 1], srgbColor(0.85, 0.45, 0.25));
const cube = renderer.createMesh(shapes.build());

const slab = new MeshBuilder();
slab.addBox([0, -0.25, 0], [12, 0.25, 12], srgbColor(0.3, 0.32, 0.36));
const ground = renderer.createMesh(slab.build());

const spinner = new SceneNode();
spinner.setPosition(0, 1, 0);
const stillness = new SceneNode();
stillness.updateWorld();

const camera = new Camera();
camera.position[0] = 6;
camera.position[1] = 4.5;
camera.position[2] = 8;
camera.lookAt(0, 1, 0);

/*
 * How fast the cube turns is a rule, and rules live in DriftScript: `spin.drs`. The bundler compiles
 * the file, `loadModule` makes a module of it, and `bindModule` gives it the engine capabilities it
 * imports. Saving the file while the page is open replaces its function in place.
 */
const spinModule = loadModule(spinScript as Record<string, unknown>);
const bound = bindModule(spinModule, {});
if (!bound.bound) throw new Error(bound.reason);
const rules = spinModule.exports as unknown as { spinRate(time: number): number };

if (import.meta.hot) {
  import.meta.hot.accept('./spin.drs', (next) => {
    if (next !== undefined) patchModule(spinModule, next as Record<string, unknown>);
  });
}

/*
 * Two angles, because that is what `alpha` is for. The simulation advances in fixed steps and
 * the display does not, so a frame almost never lands on a step boundary: drawing `spin`
 * directly judders at any refresh rate that is not a multiple of the step. Interpolating
 * between the last two states is the whole reason the loop hands `alpha` over.
 */
let spin = 0;
let previousSpin = 0;
let time = 0;

startLoop({
  simulate(dt) {
    previousSpin = spin;
    time += dt;
    spin += dt * rules.spinRate(time);
  },
  render(alpha) {
    spinner.setRotationAxisAngle(0, 1, 0, previousSpin + (spin - previousSpin) * alpha);
    spinner.updateWorld();

    camera.updateMatrices(canvas.height > 0 ? canvas.width / canvas.height : 1);

    renderer.beginFrame(CLEAR);
    renderer.bindMeshPass(camera, ENV);
    renderer.drawMesh(ground, stillness.worldMatrix);
    renderer.drawMesh(cube, spinner.worldMatrix);
    renderer.endFrame();
  },
});
```

立方体转速多快是一条规则,所以它生活在"漂流脚本"(DriftScript, in)中 `spin.drs` 页面旁:

```drs
// How the cube turns. The page owns the cube; this file only says how fast it goes.
//
// Save it while the page is open and the cube takes the new rate without the page reloading. Try a
// steady 2, a cube that stops every few seconds, or one that turns the other way.

import { sin } from "std/math"

// Radians a second: a steady turn that quickens and eases every few seconds.
fn spinRate(time: f32) -> f32 {
    return 0.8 + 0.4 * math.sin(time * 0.5)
}
```

捆绑器用 DriftScript 的 Vite 插件编译, 设置为启动器 `vite.config.ts`· ; [安装](https://driftengine.dev/docs/start/installation#driftscript) 有两个包 这个配置.

这是引擎的 `examples/starter`,并且一个测试 保持两者不变. [哈罗世界](https://driftengine.dev/docs/start/hello-world) 穿过它 [你的第一个游戏](https://driftengine.dev/docs/start/first-game) 建立一个完整的.

## 里面有什么东西

|  |  |
| --- | --- |
| 框架 | 固定步骤 [循环](https://driftengine.dev/docs/start/the-loop) 与内插, [两个后端](https://driftengine.dev/docs/concepts/backends) 一个API后面,建设时间 [质量简介](https://driftengine.dev/docs/concepts/quality),则a [边框](https://driftengine.dev/docs/concepts/the-frame) 你们能读到谁的命令. |
| 绘图 | [梅谢斯](https://driftengine.dev/docs/rendering/meshes), (中文(简体) ), [材料](https://driftengine.dev/docs/rendering/materials), (中文(简体) ), [激励](https://driftengine.dev/docs/rendering/instancing), (中文(简体) ), [灯光](https://driftengine.dev/docs/rendering/lights) 财务报告和审定财务报表 [阴影](https://driftengine.dev/docs/rendering/shadows), (中文(简体) ), [天空](https://driftengine.dev/docs/rendering/sky-and-atmosphere), (中文(简体) ), [雾和天气](https://driftengine.dev/docs/rendering/fog-and-weather), (中文(简体) ), [水费](https://driftengine.dev/docs/rendering/water), (中文(简体) ), [反思](https://driftengine.dev/docs/rendering/reflections), (中文(简体) ), [后处理](https://driftengine.dev/docs/rendering/post-processing), (中文(简体) ), [粒子](https://driftengine.dev/docs/rendering/particles), (中文(简体) ), [文本](https://driftengine.dev/docs/rendering/text-and-overlays) 财务报告和审定财务报表 [自己的通行证](https://driftengine.dev/docs/rendering/custom-passes)。 。 。 . |
| 小规模光度 | [漂流灯](https://driftengine.dev/docs/rendering/driftlight) 为上千个固定的灯光, [漂流雷线](https://driftengine.dev/docs/rendering/driftray) 因为反射出光线 追踪每个相框, [漂流TR( 漂流TR)](https://driftengine.dev/docs/rendering/drifttr) 时间重建,以及 [GPU驱动管道](https://driftengine.dev/docs/rendering/gpu-driven)。 。 。 . |
| 很多东西 | 出现分批积聚,由顶点阶段的骨质纹理所出动画(`createBoneAnimation`),静态绘图记录一次并重放每个帧(`createStaticDraws`) (中文(简体) ). |
| 纹理 | 图像和压缩块通过一个呼叫: BC用于桌面, ETC2, EAC和ASTC用于手机, 每一个上传到它的位置 `compressedFormats` 说设备样本. `updateSurfaceTexture` 可以用手柄后面的块来替换一个图像. |
| 世界 | [世界比浮点大](https://driftengine.dev/docs/worlds/large-worlds)在单元格中流出 [等级细节](https://driftengine.dev/docs/worlds/hierarchical-detail) 财务报告和审定财务报表 [用一个工具箱构建的世界](https://driftengine.dev/docs/worlds/worlds-from-a-kit)。 。 。 . |
| 物理学 | 决定性 [刚体](https://driftengine.dev/docs/simulation/rigid-bodies), (中文(简体) ), [关节](https://driftengine.dev/docs/simulation/joints), (中文(简体) ), [查询](https://driftengine.dev/docs/simulation/queries), (中文(简体) ), [字符](https://driftengine.dev/docs/simulation/characters), (中文(简体) ), [车辆](https://driftengine.dev/docs/simulation/vehicles),以及 [乌鸦和布](https://driftengine.dev/docs/simulation/ragdolls-and-cloth)。 。 。 . |
| 播放 | [投入](https://driftengine.dev/docs/interface/input) 从每个设备 通过一个动作地图, [相机剪断](https://driftengine.dev/docs/interface/cameras), (中文(简体) ), [选择](https://driftengine.dev/docs/rendering/picking) 编辑 [场景图](https://driftengine.dev/docs/concepts/scene-graph)。 。 。 . |
| 围绕游戏 | 通过商店保存游戏用品,主机连接窗口,显示和文件,以及可视门脚本来保存和偏好—— `@driftengine/core/scripts/browser.mjs` 这张照片是GPU硬件上的一页. |

## 其他软件包

当游戏到达时,每个游戏都会被添加,而一个从未导入过游戏的游戏则没有携带任何一款.

| 软件包 | 上面写的 |
| --- | --- |
| `@driftengine/animation` | 滑石 夹子 混合树和IK. [指南](https://driftengine.dev/docs/simulation/animation) |
| `@driftengine/nav` | 导航网和航道. [指南](https://driftengine.dev/docs/simulation/navigation) |
| `@driftengine/entities` | 实体、部件、系统和预发装置,带有倒带. [指南](https://driftengine.dev/docs/simulation/entities) |
| `@driftengine/chemistry` | 发热,燃烧,相位变化和烟雾. [指南](https://driftengine.dev/docs/simulation/chemistry) |
| `@driftengine/ai` | 行为树和特工. [指南](https://driftengine.dev/docs/simulation/agents) |
| `@driftengine/audio` | 搭配了巴士,放置了声音,房间和节奏. [指南](https://driftengine.dev/docs/content/audio) |
| `@driftengine/assets` 财务报告和审定财务报表 `@driftengine/drft` | KTX2型模具进口商和流线 `.drft` 集装箱. [指南](https://driftengine.dev/docs/content/importing-models) |
| `@driftengine/terrain` | 地平线画成剪图. [指南](https://driftengine.dev/docs/worlds/terrain) |
| `@driftengine/splats` | 高斯克特捕捉在梅什人中. [指南](https://driftengine.dev/docs/worlds/splats) |
| `@driftengine/texture` | 作为程序的材料在设备上解码. [指南](https://driftengine.dev/docs/worlds/drifttexture) |
| `@driftengine/capture` | 一个视频片段变成了一出表面,一出对撞机和实体. [指南](https://driftengine.dev/docs/worlds/driftcapture) |
| `@driftengine/ui2d` | 螺旋花,平板花和接口. [指南](https://driftengine.dev/docs/interface/sprites) |
| `@driftengine/script` | DriftScript,引擎的脚本语言,有热重装. [参考文献](https://driftengine.dev/docs/api/script) |
| `@driftengine/network` | 锁定并回滚网码. [参考文献](https://driftengine.dev/docs/api/network) |
| `@driftengine/xr` | WebXR会话. [参考文献](https://driftengine.dev/docs/api/xr) |
| `@driftengine/media` | 录音和导出剪辑. [参考文献](https://driftengine.dev/docs/api/media) |
| `@driftengine/editor` 财务报告和审定财务报表 `@driftengine/tools` | 编辑器和游戏中的工具. [参考文献](https://driftengine.dev/docs/api/editor) |
| `@driftengine/package` 财务报告和审定财务报表 `@driftengine/native-host` | 由同一游戏构建的可安装应用程序 . [参考文献](https://driftengine.dev/docs/api/package) |

## 许可证

阿帕奇2.0 (英语). 发售意味着复制 `NOTICE`,每捆已经 携带。 部分 [漂流引擎](https://github.com/drftrun/driftengine); 见 [`docs/ARCHITECTURE.md`](https://github.com/drftrun/driftengine/blob/main/docs/ARCHITECTURE.md) 页:1 软件包如何分割.

## 常见问题

### @driftengine/core 是什么？

DriftEngine的运行时间,一个WebGPU的游戏引擎,带有WebGL2回落:渲染器,循环,输入,相机,场景图和物理

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

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

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

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

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

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

### @driftengine/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

@driftengine/core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @driftengine/core 的下载量有多少？

根据 npm 官方下载统计，@driftengine/core 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,316 次，日均约 111 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

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

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