# @debuffjp/core 中文文档

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

版本：0\.33\.0
npm 元数据更新时间：2026-11-11T02:35:24.370Z
中文译文更新时间：2026-11-11T18:53:40.652Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：197 kB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-10-16T09:03:35.671Z
- 最新版本发布：2026-11-11T02:35:24.023Z
- 近 30 天下载量：9680（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 56 个）

## 中文简介

游戏回路、固定步时钟、场景、相机、图示和已键入的解禁创意参数

## 安装

```sh
npm install @debuffjp/core
```

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

## README

# @ debuffjp/ 分数

游戏回路,固定步时钟,场景,相机,斯匹克和打入的创意参数. 渲染为 [丝状](https://npmcn.com/package/%40debuffjp/spryte),一个带有自动 Canvas 2D倒置的分批WebGL2 渲染器,在此再导出 `Draw`, (中文(简体) ), `BitmapFont` 和朋友从 `@debuffjp/core` 和以前一样 一个依赖(spryte),没有其他依赖.

```bash
npm install @debuffjp/core
```

```ts
import { Game } from "@debuffjp/core";

const game = new Game({ canvas, width: 320, height: 180, scale: "integer", pixelArt: true });

const tuning = game.params.define("player", {
  speed: { type: "number", default: 140, min: 0, max: 600, units: "px/s" },
});

game
  .add({
    id: "play",
    update(dt) {
      /* simulation at a fixed step */
    },
    render(draw, alpha) {
      /* draw in logical units */
    },
    inspect: () => ({
      /* JSON snapshot for tools and tests */
    }),
  })
  .go("play");
game.start();
```

## API 密码

| 导出 | 目的 |
| --- | --- |
| `Game` | 循环,场景,缩放, `camera`, (中文(简体) ), `random`, (中文(简体) ), `params`, (中文(简体) ), `stats`, (中文(简体) ), `freeze()`, (中文(简体) ), `timeScale`, (中文(简体) ), `step(n)`, (中文(简体) ), `emit(name, detail?)` (标记游戏事件,如硬币或死亡,用于测试和代理) |
| `game.use(plugin)`, (中文(简体) ), `Plugin` | 安装运行时间插件 。 见 [文件/插件.md](https://github.com/debuffjp/debuff/blob/main/docs/plugins.md) |
| `game.hooks` | `beforeUpdate`, (中文(简体) ), `afterUpdate`, (中文(简体) ), `beforeRender`, (中文(简体) ), `afterRender`, (中文(简体) ), `sceneChange`, (中文(简体) ), `splashEnd` (0.31.1) (中文(简体) ). 每个返回一个未订阅的函数 |
| `game.inspect` | `register(name, () => json)` dev工具和设想方案 |
| `Scene` | `{ id, enter?, update?, render?, exit?, inspect? }`。 。 。 . `game.go(id)` 运行旧场景 `exit`,然后新的一个 `enter`,则 `sceneChange`A级 `go()` 当当前开关完成后,从内部调用(从0.31.1;之前,从一次调用),所以 `sceneChange` 出了点问题 `go()` 内 `exit` 可能发生) |
| `Camera` | 平滑的跟随,死区,界限,外伤震动, 发牢骚, `toWorld()` |
| `smoothMotion(game, objects)` | 在固定步骤之间绘制移动对象而不保留 `prevX`编号 :`prevY` 自己;见 [平滑运动](https://npmcn.com/package/%40debuffjp/core/#readme-smooth-motion-between-steps)。添加到0.26中 |
| `Sprite`, (中文(简体) ), `sliceGrid` | 框架、命名动画、出处、翻转、撞击闪光 |
| `draw.text`, (中文(简体) ), `draw.measure` | 已删除的 sans (内置像素字体), a `BitmapFont` 或CSS字体; `measure` 返回框中 `text` 填补 |
| `debuffSans()` | 内置像素字体:可打印的 ASCII, 5x7 首府有递归符, 比例式, 白色 so `color` 轻而易举 |
| `BitmapFont` | 图像表网格中的像素字体 。 从 glyph 像素中测量宽度; 在任意整数尺度下压缩 |
| `ParamRegistry`, (中文(简体) ), `ParamGroup` | 已打入、范围、单位说明值; `describe()` 这是JSON |
| `Random` | 种子 PRNG: 种子 PRNG: `next`, (中文(简体) ), `range`, (中文(简体) ), `int`, (中文(简体) ), `pick` |
| `FixedClock` | 固定步积分器,并作内插. `budgetMs` (在0.28中增加)保持了沉重的模拟,避免帧率崩溃 |
| `Storage` | `localStorage` 永远不扔的包裹 从0.28起, `set` 财务报告和审定财务报表 `reset` 返回是否写入存储 |
| `FrameStats` | 无分配框架间隔/工作时间安排 |
| `clamp`, (中文(简体) ), `lerp`, (中文(简体) ), `damp`, (中文(简体) ), `approach`, (中文(简体) ), `overlaps`, (中文(简体) ), `circlesOverlap` | 数学助手 |
| `SpatialHash` | 一个网格,用于“什么是接近此”查询(`near`, (中文(简体) ), `nearest`,每一步重建;见 [找到接近的东西](https://npmcn.com/package/%40debuffjp/core/#readme-finding-whats-near)。添加到0.26中 |

### 找到接近的东西

检查每一个敌人对每一枪,是好的几十个。 成百上千,把它们放进去 `SpatialHash` 每一步只询问一个点周围的细胞。 增加于0.26:

```ts
import { SpatialHash } from "@debuffjp/core";

const grid = new SpatialHash<Enemy>(24); // cell size: about the radius you query most

// in update, after things moved:
grid.rebuild(enemies);
for (const shot of shots)
  grid.near(shot.x, shot.y, 12, (e) => {
    hit(e, shot);
    return true; // stop at the first
  });
const target = grid.nearest(player.x, player.y, 200, (e) => !e.dead);
```

`near` 访问中心位于半径以内并有平方距离的每个物品; `nearest` 返回最近的一个 `accept` 允许。 物品是点,所以对于有半径的大型查询加上其大小. 结果以固定顺序出现,所以重播时要保持决定性,在第一步之后,它不会分配任何东西. 不允许查询运行时重建; 在另一个查询的回调中进行查询是好的 。 在人群隔离的工作量(每个敌人在自己周围查询16个px)上,它测得的速度大约是每对检查的4到15倍,共500到2000个敌人.

### 步间平滑运动

模拟运行在固定的60赫兹,以及 `render(draw, alpha)` 获得后一步与后一步相距多远(0比1). 在他们的位置上画出,移动的物体跳出显示速度快于60赫兹. 相机已经混合了 `alpha`· ; `smoothMotion` 用于您的对象, 在0. 26 中添加:

```ts
import { smoothMotion } from "@debuffjp/core";

const smooth = smoothMotion(game, () => [player, enemies, shots]); // objects, or arrays of them

// in render:
draw.sprite(heroImg, smooth.x(player), smooth.y(player));
for (const e of enemies) draw.sprite(enemyImg, smooth.x(e), smooth.y(e));

// after moving something instantly (respawn, warp), so it doesn't streak for a step:
smooth.snap(player);
```

它在每一个步骤之前都会保存每个对象的位置,因此新对象不需要注册,去掉的物体不需要清理. 有些东西它还没有保存(只是创建,或者之后) `snap`)被绘制在它的位置. 它只读位置, 所以回放和测试 没有影响,只有 `x` 财务报告和审定财务报表 `y` 混合起来.

虽然游戏被冻结(`game.freeze()`因此从0.26起 `render` 和使钩得到 `alpha` 1和相机画的地方。 在0.26之前,他们得到了剩下的时间, 所以相机和任何东西混合 `alpha` 摇摆在每帧一站.

### 像素字体

`draw.text` 用途 **松饼** 除非你通过一个 `font`,所以文本是简洁的像素艺术出框. 在 0.6 之前,默认是浏览器的 `8px monospace`; 通过 `font: "8px monospace"` 保持这个表情。 其来源和用于其他引擎的PNG工作表都在 [字体/ 调值](https://github.com/debuffjp/debuff/tree/main/fonts/debuff-sans)。使用自己的:

在 Aseprite( 或任何编辑器) 的网格上绘制格, 每个字符一个单元格 `BitmapFont.ASCII` 顺序( 空格到 `~`,将工作表保存为 `assets/font@6x9.png` 用你的细胞大小。 从单元格的左边缘绘制出每个格;从最不透明的柱来测量前进.

```ts
const font = new BitmapFont({ frames: assets.frames("font"), chars: BitmapFont.ASCII });
draw.text("coins 3", 4, 4, { font, color: "#fbbf24" });
```

与 `aseprite()` CLI 插件, 您可以保留源代码为 `assets/font@6x9.aseprite` 并跳过导出; `@debuffjp/cli`是因为 `aseprite/new-font.lua` 创建空白工作表并设置网格。 见 [CLI 读取](https://npmcn.com/package/tooling/cli/README.md#aseprite)。 。 。 .

### 缩放模式

-   `fit` (默认):填入容器,保持宽度比.
-   `integer`: 用于快活像素艺术的完整设备-像素平面.
-   `expand`喜欢 `fit`,但逻辑大小沿备用轴而增长,而不是收发信箱.
-   `pixel`: 每个逻辑单位是 `pixelSize` CSS像素(默认3,被整个设备像素折断),逻辑大小随容器而增长,因此一个更大的窗口或显示器显示更多的游戏而不是更大的像素. `width`编号 :`height` 是最小的:一个较小的容器平面由整个设备像素向下,一个设备像素低于一个单位的分数以适应,比如: `fit`在0.29.3之前,它停留在单位一个装置像素上,帆布溢出容器.
-   `none`: CSS 像素中的逻辑大小.

与 `expand` 财务报告和审定财务报表 `pixel`, (中文(简体) ), `game.width` 财务报告和审定财务报表 `game.height` 调整大小时的变动( e)`game.hooks.resize`故你应当从他们的每个框架出来.

游戏代码总是使用逻辑单元. 后卫店紧随其后 `devicePixelRatio`。 。 。 .

## 启动喷出

生产建设采用"用去巴克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 它持续了1.6秒,任何密钥都会跳过. 点击或踢踏也会跳过它(在0.5之前,点击会打开debuff.jp,卡片会显示它的URL). 它没有链接或URL,因此游戏停留在出入口规则之内(Poki,CrazyGames等禁止链接出游戏). **出版关于波基?** Poki要求游戏完全没有喷出屏幕,所以关闭它与 `splash: false`。它从不显示在 dev, 或时间被驱动 `step()` (情节和代理人). 要删除它:

```ts
new Game({ canvas, width, height, splash: false });
```

您也可以将其长度设定为 `splash: { duration: 1 }`,或从代码中结束 `game.skipSplash()`。 。 。 .

跳过喷出物的密钥或水龙头在游戏中并不同时算作媒体: `@debuffjp/input` 喷出时滴出压力 `game.hooks.splashEnd` 火,所以同样的水龙头不能跳过标题屏幕。 钥匙仍然被扣留 在0.31.1之前,这一水龙头被视为第一步所压.

## 常见问题

### @debuffjp/core 是什么？

游戏回路、固定步时钟、场景、相机、图示和已键入的解禁创意参数

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

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

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

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

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

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

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

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

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

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

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

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