# @basementuniverse/sprite 中文文档

规范地址：https://npmcn.com/package/%40basementuniverse/sprite/

版本：1\.5\.0
npm 元数据更新时间：2026-10-31T15:21:39.801Z
中文译文更新时间：2026-10-31T15:40:23.646Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：36.7 kB，5 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-07-15T11:23:26.673Z
- 最新版本发布：2026-10-31T15:21:39.647Z
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

用于在2d游戏中渲染带有动画的分层精灵的组件

## 安装

```sh
npm install @basementuniverse/sprite
```

也可以使用：`pnpm add @basementuniverse/sprite`、`yarn add @basementuniverse/sprite`、`bun add @basementuniverse/sprite`

## README

# 游戏组件：精灵

用于2d游戏的基本精灵组件，带有动画和方向。

## 安装

```bash
npm install @basementuniverse/sprite
```

对于直接的浏览器使用，包括UMD构建与脚本标签：

```html
<script src="build/index.js"></script>
```

控件公开其导出 `BasementUniverseSprite` 浏览器 名称空间。它不会将每个导出直接添加到 `window`.

## 如何使用

创建精灵：

```ts
import { Sprite } from '@basementuniverse/sprite';

const sprite = new Sprite({
  // options here...
});
```

当直接从浏览器脚本中使用库时，使用 `BasementUniverseSprite`：

```html
<script src="build/index.js"></script>
<script>
  const sprite = new BasementUniverseSprite.Sprite({
    // options here...
  });
</script>
```

每帧更新精灵：

```ts
sprite.update(dt);
```

随时设置精灵的属性：

```ts
sprite.position = vec(100, 100);
sprite.scale = 1;
sprite.rotation = 0; // radians
```

_(见 [在这里](https://www.npmjs.com/package/@basementuniverse/vec) 用于 `vec` 库)_

获取或设置精灵的方向和动画：

```ts
sprite.animation = 'walk';
sprite.direction = 'right';
```

启动/暂停/重置当前动画：

```ts
sprite.playAnimation();
sprite.pauseAnimation();
sprite.resetAnimation();
```

每帧渲染精灵：

```ts
sprite.draw(context);
```

获取当前帧的图像：

```ts
sprite.image; // the image that draw() will use, updated by sprite.update()
```

在不改变精灵方向的情况下，在另一个方向获得相同的帧：

```ts
sprite.getImage('left');
```

从动画的一个图层中获取图像：

```ts
sprite.getImage(sprite.direction, 'normal');
```

## 选项

```ts
export type SpriteOptions = {
  /**
   * The position of the sprite
   *
   * Defaults to (0, 0)
   */
  position?: vec;

  /**
   * The base size of the sprite
   *
   * If omitted, use the base image size, or fall back to the size of the
   * first image found in available directions for the default animation
   *
   * If a size still can't be found, default to (0, 0)
   */
  size?: vec;

  /**
   * Origin offset from top-left corner, used for rotation and scaling
   *
   * If omitted, this will be placed in the center of the sprite (based on
   * size, noting that size will be calculated first)
   *
   * @see SpriteOptions.size
   */
  origin?: vec;

  /**
   * The scale factor of the sprite
   *
   * Default is 1
   */
  scale?: number;

  /**
   * The sprite rotation, measured in radians
   *
   * Default is 0
   */
  rotation?: number;

  /**
   * An array of valid direction names
   *
   * By default a sprite will have one available direction: 'default'
   */
  directions: string[];

  /**
   * The initial direction of the sprite
   *
   * Default is 'default'
   */
  defaultDirection: string;

  /**
   * An optional base image
   *
   * If an animation frame doesn't exist (for example an animation has been
   * configured with 5 frames but only 3 images exist in the animation's
   * images array), we fall back to this image
   *
   * If an animation frame image can't be found and this base image doesn't
   * exist, we can still render the sprite - it will just have an empty image
   *
   * (this can be useful for sprites that act purely as hosts for attachment
   * points, for example)
   */
  image?: HTMLImageElement | HTMLCanvasElement;

  /**
   * A dictionary of animations
   *
   * Each animation can have multiple variants for different directions
   *
   * Use '*' as a direction name to indicate that a variant is available for
   * all directions and can be used as a fallback if the current direction
   * can't be found
   */
  animations: {
    [name: string]: {
      [direction: string]: SpriteAnimationOptions;
    };
  };

  /**
   * The initial animation for the sprite
   */
  defaultAnimation: string;

  /**
   * A list of attachment points
   */
  attachmentPoints?: SpriteAttachmentPointOptions[];

  /**
   * Optional hook called before rendering the sprite image
   */
  preRender?: (
    context: CanvasRenderingContext2D,
    sprite: Sprite
  ) => void;

  /**
   * Optional hook called after rendering the sprite image
   */
  postRender?: (
    context: CanvasRenderingContext2D,
    sprite: Sprite
  ) => void;

  /**
   * Optional debug options
   *
   * Can be a boolean value (in which case all sub-options will be set to the
   * same value), or an object allowing specific debug options to be enabled
   * individually
   */
  debug?: Partial<SpriteDebugOptions> | boolean;
};

export type SpriteAnimationOptions = {
  /**
   * The name of this animation
   */
  name: string;

  /**
   * The number of frames in this animation
   */
  frameCount: number;

  /**
   * The number of frames per second when playing this animation
   */
  frameRate: number;

  /**
   * The repeat mode for this animation
   */
  mode: SpriteAnimationRepeatMode;

  /**
   * A list of images to use for each frame
   *
   * If this list is longer than frameCount, some images won't be used
   *
   * If this list if shorter than frameCount, we fall back to the base image
   * or don't show an image for some frames
   */
  images?: (HTMLImageElement | HTMLCanvasElement)[];

  /**
   * Named lists of extra images to go with each frame, for example normal maps
   *
   * These aren't drawn by the sprite, use `getImage()` to read them. Unlike
   * `images` there's no fallback to the base image, if a layer doesn't have an
   * image for a frame then `getImage()` will return null
   */
  layers?: {
    [layerName: string]: (HTMLImageElement | HTMLCanvasElement)[];
  };

  /**
   * Keyframes for attachment points
   */
  attachmentPointKeyframes?: {
    [attachmentPointName: string]: SpriteAttachmentPointKeyframe[];
  };
};
```

_(见 `build/index.d.ts` 欲知详情)_

## 附件分

精灵可以有多个命名的附着点。这些附点可以被赋予一个默认位置，并且位置可以通过每个动画中的关键帧来修改。

按名称获取附着点：

```ts
sprite.getAttachmentPoint('weapon-left-hand');
// returns a vec: { x: number; y: number } or null
```

这对于将多个精灵连接在一起非常有用。

## 内容处理器

提供了一个内容处理器函数，以便与 [内容管理器](https://www.npmjs.com/package/@basementuniverse/content-manager).

```ts
import { spriteOptionsContentProcessor } from '@basementuniverse/sprite';
```

这个函数将接受一个JSON对象 `SpriteOptions` 类型（见下面对差异的解释）并返回a `SpriteOptions` 对象，该对象可以传递到 `Sprite` 构造函数。

-   JSON对象可能有 `imageName: string` 字段而不是 `image`． 图像名称将用于从内容管理器中获取图像，而 `imageName` 字段将被替换为 `image` 字段，包含已获取的图像。
    
-   类似地，JSON对象可能有 `imageNames: string[]` 字段而不是 `images` 在每个动画中。这些图像将从内容管理器和 `imageNames` 字段将被替换为 `images` 字段，包含获取的图像。
    
-   每个动画也可以有 `layerImageNames: { [layerName: string]: string[] }` 字段而不是 `layers`，其转换方式相同。

## 常见问题

### @basementuniverse/sprite 是什么？

用于在2d游戏中渲染带有动画的分层精灵的组件

### 如何安装 @basementuniverse/sprite？

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

### @basementuniverse/sprite 支持 TypeScript 吗？

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

### @basementuniverse/sprite 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @basementuniverse/sprite 可以商用吗？

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

### @basementuniverse/sprite 还在维护吗？

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