# @flare-engine/physics 中文文档

规范地址：https://npmcn.com/package/%40flare-engine/physics/

版本：0\.4\.12
npm 元数据更新时间：2026-11-12T19:47:17.413Z
中文译文更新时间：2026-11-14T21:32:59.180Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40flare-engine/physics
原文对照：https://npmcn.com/package/%40flare-engine/physics/?lang=original
项目主页：https://github.com/grzott/flare-engine#readme
源码仓库：https://github.com/grzott/flare-engine

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

- 包体积（解压后）：221 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-06-09T16:19:43.794Z
- 最新版本发布：2026-11-12T19:47:17.027Z
- 近 30 天下载量：2677（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

AABB 碰撞、空间指数、射线

## 安装

```sh
npm install @flare-engine/physics
```

也可以使用：`pnpm add @flare-engine/physics`、`yarn add @flare-engine/physics`、`bun add @flare-engine/physics`

## README

# @flare-engine/物理学

已建 AABB / Circle相撞探测器 - `CollisionWorld` 带有出入信号, `SpatialIndex` 统一相位相, `CollisionWorld.raycast` 用于宽相支持的射线查询加独立 `raycast` 明确的目标清单,以及 `overlapInto` 用于最小翻译分辨率。 触发 / 层/ 口罩过滤 。 固态网格运动 : `buildSolidGrid` 编号 : `isBlockedAABB` 编号 : `moveAndSlideInto` (结构 `SolidTile` 输入,无平面分解,半开AABB-vs-tile,轴相分离的幻灯片,零分量,带有 `isSolidAt` 编号 : `setSolidAt` 在运行时读取或翻出一个单元格。 不存在第三方物理依赖性:刚体反应生活在第一方 [`@flare-engine/dynamics`](https://github.com/grzott/flare-engine/tree/main/packages/dynamics),在设计文件中评价的planck.js选项从未被采纳. 按对撞机计数计算的成本,包括捕获日期和运行到运行的分布,公布于 [基准](https://github.com/grzott/flare-engine/blob/main/docs/references/benchmarks.md)这些行的时间是整个物理框架(移动每个相撞器,然后 `step()`(没有) `step()` 被隔离。 相撞器在硬地边界上包裹,因此整个样本窗口的密度是恒定的,如果有人逃脱,探测器会失败捕获;将行读作放大向导,这就是 `<1000` 以上图出自.

`@flare-engine/physics` 答题 _这些重叠是否_· ; `@flare-engine/dynamics` 答题 _他们最终会在哪里_。两个软件包都取决于另一个软件包的覆盖范围 [`@flare-engine/dynamics`](https://github.com/grzott/flare-engine/tree/main/packages/dynamics) 当身体需要相互推动时, 不只是报告接触.

## 安装

```sh
bun add @flare-engine/physics
```

## 使用量

```ts
import { CollisionWorld, AABB, createCollider } from '@flare-engine/physics';

declare const entityA: number;
declare const x: number, y: number;

const world = new CollisionWorld();
world.onCollisionStart.add((pair) => console.log(pair.entityA, pair.entityB));

const colliderA = createCollider(AABB(32, 32), { layer: 1, mask: 2 });
world.addCollider(entityA, colliderA, x, y);
world.step();
```

## 解决碰撞

`shapeOverlap` 答题 _是否为_ 两个形状相撞 让你知道有问题 而不是如何修复它. `overlapInto` 给出最小的翻译矢量——最短的推力 将它们分开:

```ts
import { AABB, CircleShape, createOverlap, overlapInto } from '@flare-engine/physics';

const mtv = createOverlap(); // reuse across pairs — no per-pair allocation
if (overlapInto(AABB(32, 32), 0, 0, CircleShape(8), 18, 4, mtv) !== null) {
  // mtv.x / mtv.y is a unit axis pointing from a toward b; mtv.depth is how far
  // b must move along it to just stop touching.
}
```

回返 `null` 当形状分开时,你的缓冲器没有动静。 同心圆没有 有意义的轴线,所以 `(1, 0)` 而不是返回 `NaN` 从零向量的正常化.

**触取不是相相相会.** 每个形状对都是严格的: 边缘完全相遇的两个形状 重叠,单位 `shapeOverlap` 财务报告和审定财务报表 `overlapInto` 一样,所以两者总是同意。 零辐射圆 只有在严格在盒子内时,才像零大小的盒子那样相撞.

## 横扫世界

```ts
import { CollisionWorld } from '@flare-engine/physics';

declare const world: CollisionWorld;

// Nearest hit along +x, limited to colliders on layers 1 and 2.
const hit = world.raycast(0, 0, 1, 0, 500, 0b011);
if (hit !== null) {
  // hit.entity / hit.distance / hit.point / hit.normal
}
```

`CollisionWorld.raycast` 只走射线所接触的宽相间细胞和过滤器 编辑 `layer` 位相撞者已经携带( t)`mask` 默认为每层)。 独立 `raycast(ox, oy, dx, dy, maxDist, targets)` 出口仍用于违反明确清单 不是一个世界.

**回击记录在通话之间重复使用** ——在铸造前读取,或者复制需要的 再来一次 这就是保持每帧射线分配自由的原因;相对的独立的帮助者返回 (加上两个巢穴) `Vec2`(s) 呼叫者可能保持的每次通话.

见 [API 规格](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md#flare-enginephysics--4kb-aabb)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @flare-engine/physics 是什么？

AABB 碰撞、空间指数、射线

### 如何安装 @flare-engine/physics？

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

### @flare-engine/physics 支持 TypeScript 吗？

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

### @flare-engine/physics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flare-engine/physics 需要什么版本的 Node\.js？

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

### @flare-engine/physics 可以商用吗？

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

### @flare-engine/physics 的下载量有多少？

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

### @flare-engine/physics 还在维护吗？

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