# @galacean/effects-core 中文文档

规范地址：https://npmcn.com/package/%40galacean/effects-core/

版本：2\.10\.6
npm 元数据更新时间：2026-11-09T11:02:28.541Z
中文译文更新时间：2026-11-15T21:30:13.361Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40galacean/effects-core
原文对照：https://npmcn.com/package/%40galacean/effects-core/?lang=original

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

- 包体积（解压后）：10.6 MB，260 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2023-11-13T01:55:56.471Z
- 最新版本发布：2026-11-09T11:02:28.300Z
- 近 30 天下载量：3975（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：273（近 12 个月 49 个）

## 中文简介

Galacean 效果运行时间核心

## 安装

```sh
npm install @galacean/effects-core
```

也可以使用：`pnpm add @galacean/effects-core`、`yarn add @galacean/effects-core`、`bun add @galacean/effects-core`

## README

# 加来森效应核心

Galacean Effects的核心运行时间库,负责资产加载,场景管理和渲染.

## 基本概念

这个 **组成** 是Galacean Effects中动画回放的基本单位. 这个 `Composition` 类管理从数据解析(JSON - > VFX 项目 - > 渲染器组件)到渲染框架的创建、更新和销毁的整个生命周期(`RenderFrame`颁发通行证`RenderPass`) (中文(简体) ).

### 核心结构

```
Engine
  ├── Composition
  │     ├── VFXItem (Element)
  │     │     ├── Component
  │     │     │     └── RendererComponent
  │     │     └── Transform
  │     ├── RenderFrame
  │     │     └── RenderPass
  │     └── Camera
  └── Resource Management
        ├── Texture
        ├── Material
        └── Geometry
```

每种构成包含不同类型的要素(`VFXItem`及其组成部分`Component`),包括:

-   相机组件
-   Sprite( 层) 组件
-   颗粒系统
-   文本组件
-   互动部分

当一个组成被创建时,它会完成:

1.  装入数据资产
2.  要素的产生(`VFXItem`及其组成部分
3.  装入并创建纹理( E)`Texture`(中文(简体) )
4.  初始化 `RenderFrame` 财务报告和审定财务报表 `RenderPass`

## 核心单元

### 1\. 发动机 [发动机](https://npmcn.com/package/%40galacean/effects-core/src/engine.ts)

`Engine` 是核心切入点,负责管理所有GPU资源和组成物的生命周期.

```typescript
import { Engine } from '@galacean/effects-core';

// Create engine
const engine = Engine.create(canvas, {
  fps: 60,
  pixelRatio: window.devicePixelRatio,
});
```

主要特点:

-   管理渲染器(`Renderer`(中文(简体) )
-   管理 GPU 资源( 文字、 材料、 几何等)
-   管理成分的创建和销毁
-   提供计数器( E)`Ticker`驱动渲染回路
-   处理交互式活动

### 2\. 资产管理 [资产管理人](https://npmcn.com/package/%40galacean/effects-core/src/asset-manager.ts)

负责装入效果所需的所有资源:

```typescript
import { AssetManager } from '@galacean/effects-core';

const assetManager = new AssetManager(options);
```

支持的特性 :

1.  正在装入 JSON 和 二进制资源
2.  正在装入图像和视频资源
3.  根据渲染级别选择资源下载
4.  图像/文本模板替换
5.  字体装入( 通过) `AssetManager.loadFontFamily`(中文(简体) )

### 3\. 组成 [组成](https://npmcn.com/package/%40galacean/effects-core/src/composition.ts)

管理用于动画回放的数据处理和渲染:

```typescript
const composition = new Composition(props, scene);

// Playback control
composition.play();
composition.pause();
composition.resume();

// Update
composition.update(deltaTime);

// Dispose
composition.dispose();
```

主要属性 :

-   `renderFrame`: 当前框架的渲染数据对象
-   `rootItem`: 构成的根要素
-   `camera`: 相机组件
-   `speed`: 回放速度

### 4\. VFX 元素 [VFX 项目](https://npmcn.com/package/%40galacean/effects-core/src/vfx-item.ts)

所有效果元素的基础类,支持基于组件的架构:

```typescript
// Get component
const component = item.getComponent(SpriteComponent);

// Iterate children
item.children.forEach(child => {
  // ...
});

// Transform operations
item.transform.setPosition(x, y, z);
```

主要属性 :

-   `transform`: 位置、旋转、比例转换
-   `components`: 构成部分清单
-   `children`: 儿童要素清单

### 5\. 组件系统 [构成部分](https://npmcn.com/package/%40galacean/effects-core/src/components/component.ts)

项目:

```typescript
abstract class Component extends EffectsObject {
  item: VFXItem;           // Owner element
  enabled: boolean;        // Whether enabled
  
  onAwake() {}             // Initialization
  onEnable() {}            // On enable
  onDisable() {}           // On disable
  onStart() {}             // Before first update
  onUpdate(dt: number) {}  // Per-frame update
  onLateUpdate(dt: number) {} // Late update
  onDestroy() {}           // On destroy
}
```

### 6\. 渲染器组件 [渲染器组件](https://npmcn.com/package/%40galacean/effects-core/src/components/renderer-component.ts)

所有渲染元件的基等,负责添加可渲染出物来渲染出传:

```typescript
class RendererComponent extends Component {
  material: Material;      // Material
  materials: Material[];   // Material list
  priority: number;        // Render priority
  
  render(renderer: Renderer): void {}  // Render method
}
```

当一个组件被启用时,它会自动被添加到默认渲染通过 `RenderFrame`。 。 。 .

### 7\. 渲染框架 [发光灯](https://npmcn.com/package/%40galacean/effects-core/src/render/render-frame.ts)

每个帧的渲染数据对象,管理渲染口和全局制服:

```typescript
interface RenderFrameOptions {
  camera: Camera,
  renderer: Renderer,
  globalVolume?: PostProcessVolume,
  postProcessingEnabled?: boolean,
}
```

主要特点:

-   管理 `RenderPass` 列表
-   存储相机属性
-   管理全局统一变量( E)`GlobalUniforms`(中文(简体) )
-   支持后处理( Bloom, ToneMapping)

主要方法:

-   `addMeshToDefaultRenderPass(mesh: RendererComponent)`: 将渲染器组件添加到默认渲染通过中
-   `removeMeshFromDefaultRenderPass(mesh: RendererComponent)`: 从默认渲染器组件中去除渲染器组件

### 8\. 通行证 [渲染纸](https://npmcn.com/package/%40galacean/effects-core/src/render/render-pass.ts)

管理一组要渲染的对象 :

```typescript
interface RenderPassClearAction {
  clearColor?: vec4,
  colorAction?: TextureLoadAction,
  clearDepth?: number,
  depthAction?: TextureLoadAction,
}
```

特征 :

-   管理渲染对象列表
-   配置颜色、 深度、 质地附件
-   设定清晰的行为

### 9\. 几何学 [几何](https://npmcn.com/package/%40galacean/effects-core/src/render/geometry.ts)

用于管理顶点和索引数据的摘要类:

```typescript
const geometry = Geometry.create(engine, {
  attributes: {
    aPosition: { size: 3, data: positions },
    aTexCoord: { size: 2, data: texCoords },
  },
  indices: { data: indices },
  mode: WebGLRenderingContext.TRIANGLES,
});

// Update data
geometry.setAttributeData('aPosition', newPositions);
geometry.setAttributeSubData('aPosition', offset, partialData);
geometry.setIndexData(newIndices);
geometry.setDrawCount(count);
```

### 10\. 材料 [材料](https://npmcn.com/package/%40galacean/effects-core/src/material/material.ts)

用于管理阴影和渲染的文摘类:

```typescript
const material = Material.create(engine, {
  shader: shaderSource,
  uniformValues: {
    uColor: [1, 0, 0, 1],
  },
});

// Set render states
material.blending = true;
material.depthTest = true;
material.depthMask = true;
```

渲染状态属性 :

-   `blending`: 颜色混合开关
-   `blendFunction`: 混合函数
-   `depthTest`: 深度测试开关
-   `depthMask`: 深度写入开关
-   `stencilTest`: Stencil 测试开关
-   `culling`: 后相摇动开关

### 11\. 纹理 [纹理](https://npmcn.com/package/%40galacean/effects-core/src/texture/texture.ts)

管理 GPU 纹理资源的摘要类 :

```typescript
// From image
const texture = await Texture.fromImage(url, engine);

// From video
const texture = await Texture.fromVideo(url, engine);

// From data
const texture = Texture.create(engine, {
  sourceType: TextureSourceType.data,
  data: {
    width: 256,
    height: 256,
    data: pixelData,
  },
});
```

## 插件系统

支持通过插件扩展功能 :

```typescript
import { registerPlugin } from '@galacean/effects-core';

registerPlugin('custom', CustomLoader);
```

内建插件 :

-   `sprite`: 图层渲染
-   `particle`: 粒子系统
-   `text`: 文本渲染
-   `interact`: 交互处理
-   `camera`: 相机控制器

## 安装

```bash
npm install @galacean/effects-core
```

## 依赖关系

-   `@galacean/effects-specification`: 数据规格定义
-   `@galacean/effects-math`: 数学库

## [API 文档](https://www.galacean.com/effects/api/effects-core)

## 常见问题

### @galacean/effects-core 是什么？

Galacean 效果运行时间核心

### 如何安装 @galacean/effects-core？

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

### @galacean/effects-core 支持 TypeScript 吗？

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

### @galacean/effects-core 支持 ESM 还是 CommonJS？

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

### @galacean/effects-core 可以商用吗？

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

### @galacean/effects-core 的下载量有多少？

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

### @galacean/effects-core 还在维护吗？

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