engine Documentation

1. Project Overview & Quickstart (galacean/engine) Copy Chapter

File: README.md Copy Chapter

Galacean Engine

Galacean Engine is a high-performance, real-time interactive engine designed primarily for web and mobile platforms. It employs a component system architecture and emphasizes ease of use and lightweight design. Developers can create projects using either editor or pure code.

Features Copy Chapter

• 🖥  Platform - Support HTML5 and wechat minigame
• 🔮  Graphics - Advanced 2D + 3D graphics engine
• 🏃  Animation - Powerful animation system
• 🧱  Physics - Powerful and easy-to-use physical features
• 🎨  GUI - Flexible UI system with drag-and-drop and dynamic interactions
• 👆  Input - Easy-to-use interactive capabilities
• 📑  Scripts - Use TypeScript to write logic efficiently

Usage Copy Chapter

Using Editor Copy Section

We recommend using Editor for a streamlined workflow that enables seamless integration between artists and developers. Its intuitive visual tools allow artists to quickly create scenes and enable developers to write custom logic, with convenient platform export. You can even create projects based on pre-built case templates.

Using Pure Code Copy Section

If you want to build your project using pure code via runtime, install the engine from npm:

npm install @galacean/engine

Create a simple scene:

import { BlinnPhongMaterial, Camera, DirectLight, MeshRenderer, WebGLEngine, PrimitiveMesh } from "@galacean/engine";

// Create engine by passing in the HTMLCanvasElement id and adjust canvas size
const engine = await WebGLEngine.create({ canvas: "canvas-id" });
engine.canvas.resizeByClientSize();

// Get scene and create root entity
const scene = engine.sceneManager.activeScene;
const rootEntity = scene.createRootEntity("Root");

// Create light
const lightEntity = rootEntity.createChild("Light");
const directLight = lightEntity.addComponent(DirectLight);
lightEntity.transform.setRotation(-45, -45, 0);
directLight.intensity = 0.4;

// Create camera
const cameraEntity = rootEntity.createChild("Camera");
cameraEntity.addComponent(Camera);
cameraEntity.transform.setPosition(0, 0, 12);

// Create sphere
const meshEntity = rootEntity.createChild("Sphere");
const meshRenderer = meshEntity.addComponent(MeshRenderer);
const material = new BlinnPhongMaterial(engine);
meshRenderer.setMaterial(material);
meshRenderer.mesh = PrimitiveMesh.createSphere(engine, 1);

// Run engine
engine.run();

Contributing Copy Chapter

This repository contains the runtime's source code and documentation. Everyone is welcome to contribute—whether you find a bug, have a feature request, or want to tackle a task from our roadmap, please get in touch.

Make sure to read the Contributing Guide / 贡献指南 before submitting changes.

Clone Copy Chapter

Prerequisites:

• git-lfs (Install by official website)

Clone this repository:

git clone [email protected]:galacean/engine.git

Build Copy Chapter

Prerequisites:

• Node.js v15.0.0+ and NPM (Install by official website)
• PNPM (Install globally by npm install pnpm)

In the folder where you have cloned the repository, install the build dependencies using pnpm:

pnpm install

Then, to build the source, using npm:

npm run b:all

Links Copy Chapter

• Official Site
• Editor
• Documentation

License Copy Chapter

The engine is released under the MIT license. See LICENSE file.

File: docs/zh/animation/examples/blending.mdx Copy Chapter

order: 3 title: 动画混合 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中实现动画的多层混合。通过简单的步骤，你将学习如何让一个模型混合播放多个动画。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

3.动画过渡

0. 准备工作 Copy Chapter

1. 在开始之前，我们需要有一个有动画的模型并且它需要包含一个适合混合的动画。如果你没有模型，可以在点此下载 模型。
   然后我们将其拖入到场景中。

2. 我们要有一个已编辑好的 动画控制器 。请参考：编辑动画控制器。

1. 添加一个动画层 Copy Chapter

想要对动画进行混合播放，需要在动画控制器中添加一个 动画层 。当 动画控制组件 运行时，所有的 动画层 都会一起运行，多个 动画层 通过不同的权重来实现动画的混合。
关于 动画层 的详细介绍请参考 动画层 文档。

在 Layers 面板点击 + 添加一个 动画层

2. 编辑动画层 Copy Chapter

添加一个 动画状态（如果你不知道如何添加，请参考：播放模型中的动画），绑定模型中的 "shakeHead" 动画片段，并从 entry 连接到这个 动画状态，可以根据需要调整 entry 到这个 动画状态的过渡时间。

编辑之后为模型绑定此 动画控制器 。

3. 调整动画层权重 Copy Chapter

新添加的 动画层 的默认混合模式是 Override，我们先预览下效果。

可以看到我们之前在 Base 动画层添加的 动画状态 都失效了，因为混合模式是 Override，它会覆盖掉它下面的所有 动画层 ，我们可以调整 Layer1 的权重看看权重对其的影响。

可以看到随着权重减少 Layer1 对动画的影响越小，而 Base 对动画的影响越大。

4. 调整混合模式 Copy Chapter

在本示例中，我们不希望 Layer1 的权重影响到 Base 动画层，因此我们将 Layer1 的混合模式修改为 Additive。

这样 Layer1 的动画会叠加到 Base 动画层上，它的权重修改只影响自身，而不会影响 Base 层的动画。
为了更好的观察 Additve 的效果，我们删掉 Base 层 run 到 exit 的过渡。

File: docs/zh/animation/examples/controlAnimationByInput.mdx Copy Chapter

order: 4 title: 用户输入控制动画 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中让用户的输入控制动画。通过简单的步骤，你将学习如何结合用户输入来控制动画的切换，让角色根据用户的交互进行相应的动作过渡。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

3.动画过渡

0. 准备工作 Copy Chapter

1. 在开始之前，我们需要有一个包含多个动画的模型， 并将其拖入到场景中。如果你没有模型，可以在点此下载 模型。

2. 我们要有一个已编辑好动画过渡的 动画控制器 。请参考：编辑动画控制器。

1. 添加动画控制参数 Copy Chapter

为了能够根据用户输入控制动画，首先需要给 动画控制器 加一些参数，根据这些参数来切换 动画状态 。

1. 切换到 Parameters 面板

2. 点击 + 添加一个浮点参数 speed，并将默认值设置为 0。

2. 添加过渡条件 Copy Chapter

之前为大家介绍了如何在 动画状态机 中添加 动画过渡（详细介绍），在之前的示例中，时间超过了 ExitTime 就会触发过渡。这里我们需要根据用户输入来触发过渡，所以我们需要添加一个 过渡条件 。

1. 在 动画状态机 中，选中从 idle 到 walk 的过渡，点击 Add Condition 添加一个 Condition。

Condition 的默认值刚好符合我们的需求，当 speed 大于 0 时，就会从 idle 过渡到 walk。

2. 同样的，选中从 walk 到 run 的过渡，添加一个 Condition，使其 speed 大于 5 时，从 walk 过渡到 run。

3. 选中 run 到 exit 的过渡，添加一个 Condition ，使其 speed 为 0 时，从 run 退出动画，重新回到 idle。

3. 添加脚本 Copy Section

我们需要一个脚本来接收用户输入，并根据用户输入来修改 speed 参数的值，以触发动画状态的切换。
添加脚本有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> New Empty Script

2. 点击添加资产按钮 +，选择 New Empty Script

4. 编辑并绑定脚本 Copy Section

1. 双击脚本，打开脚本编辑器，输入以下代码：

import { Script, Animator, Keys } from '@galacean/engine';

export default class extends Script {
  animator: Animator;
  onStart() {
    this.animator = this.entity.getComponent(Animator);
  }

  onUpdate(deltaTime: number) {
    const inputManager = this.engine.inputManager;
    if (inputManager.isKeyHeldDown(Keys.KeyW)) {
        // 如果用户按下 W + Shift 键，则设置 speed 参数值为 6
      if (inputManager.isKeyHeldDown(Keys.ShiftLeft)) {
        this.animator.setParameterValue('speed', 6);
      } else {
        // 如果用户仅按住 W 键，则设置 speed 参数值为 1
        this.animator.setParameterValue('speed', 1);
      }
    }

    // 如果用户松开 W 键，则设置 speed 参数值为 0
    if (inputManager.isKeyUp(Keys.KeyW)) {
      this.animator.setParameterValue('speed', 0);
    }
  }
}

关于脚本的详细说明请参考：脚本

关于用户输入的详细说明请参考：交互总览

2. 找到 Animator 组件所在的实体，为其添加刚刚创建的脚本。

5. 预览动画 Copy Section

与之前的教程不同，因为本次我们为实体添加了脚本，仅点击预览动画按钮，脚本代码是不会生效的，我们需要点击项目预览（项目预览才会编译脚本文件）按钮来预览动画。

当角色处于 idle 状态时，按下 W 键，角色会从 idle 过渡到 walk，按住 Shift 键，角色会从 walk 过渡到 run，松开 W 键，角色会从 run 退出动画，重新回到 idle。

6. 优化动画 Copy Section

我们预览时会发现，如果我们在 walk 状态时松开 W 键，角色并不会切换到 idle 状态，而是继续播放 walk 动画。这是因为我们并没有从 walk 到 idle 的过渡。
而且从 run 到 idle 也没有过渡效果。因为我们是通过重新进入 entry 切换到 idle 的，而 entry 到 idle 的过渡的 Duration 是 0。想要从 run 过渡到 idle ，我们可以将 run 连接到 idle。
同理想要从 run 过渡到 walk 也需要添加过渡。

再次预览，我们发现 walk 到 idle 和 run 到 walk 的过渡效果已经生效了。

但是从 run 到 idle 的过渡效果并没有生效，而是先到 walk 再由 walk 到 idle，这是因为当 speed 参数为 0 时，run 到 walk 和 run 到 idle 的 Condition 都满足。
为了避免这种情况，我们可以给 run 到 walk 再添加一个 Condition 并将其设置为 speed 大于 0。

这样当我们同时松开 W 键和 Shift 键时，角色就会从 run 直接过渡到 idle 了。

File: docs/zh/animation/examples/crossFade.mdx Copy Chapter

order: 2 title: 动画过渡 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中实现动画过渡。通过简单的步骤，你将学习如何让一个动画过渡到另一个动画。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

0. 准备工作 Copy Chapter

在开始之前，我们需要有一个包含多个动画的模型。如果你没有模型，可以在点此下载 模型。

导入模型 Copy Section

如果你不清楚如何导入模型，请参考：导入模型

1. 查看模型 Copy Chapter

点击模型资产上的展开按钮

可以看到模型中包含了三个 动画片段 资产, 以及一个 动画控制器 资产

2. 创建动画控制资产 Copy Chapter

想要控制模型的动画播放，需要编辑 动画控制器 的内容，而模型中的 动画控制器 是只读的，所以需要我们自己创建一个 动画控制器 。
如果你不知道如何创建 动画控制器 ，请参考：创建动画控制器

3. 编辑动画控制器 Copy Chapter

1. 打开动画控制器编辑器，添加三个 动画状态 ，分别绑定模型中的三个 动画片段

如果你不知道如何创建 动画状态 并绑定 动画片段 ，请参考：编辑动画控制器

2. 创建 动画过渡（关于动画过渡的详细介绍请参考 动画状态机 文档的动画过渡部分）：将 idle 动画连接到 entry，并点击连线将 Duration 改为 0，这样在这个动画控制器被应用时，角色就会播放 idle 动画。

3. 以同样的方式将 idle 连接到 walk，将 walk 连接到 run， 将 run 连接到 exit, 这样角色就会在播完 idle 动画后，自动过渡到 walk 动画，再过渡到 run 动画，最后到 exit 退出，重新进入 entry，来循环播放这段动画。

4. 使用动画控制器并预览 Copy Chapter

绑定 动画控制器（如果你不知道如何绑定 动画控制器 ，请参考：使用动画控制器文档）之后点击播放按钮，可以看到模型从 idle 过渡到 walk，再过渡到 run，最后退出，重新回到 idle 状态。

用户输入控制动画 Copy Chapter

上述方式主要是为了调试动画的过渡效果，你可以修改过渡的 Duration , ExitTime , Offset 等参数（详细介绍请参考 动画状态机 文档），来调整到合适的过渡效果。

实际项目中，动画一般不会像本示例一样自动切换，大多数情况需要结合用户输入来控制动画的切换，具体可以参考：用户输入控制动画 文档

File: docs/zh/animation/examples/material-animation.mdx Copy Chapter

order: 7 title: 材质动画 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中实现材质的动画。通过简单的步骤，你将学习如何制作一个材质动画的动画片段。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

0. 准备工作 Copy Chapter

在开始之前，我们需要在 实体 上添加一个 网格渲染器 组件，刚创建的项目中默认会有一个立方体，它已经包含了 网格渲染器 组件。

除此以外，因为默认的 材质 是只读的，所以需要我们还需要创建一个 材质。

创建 材质 有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Material

2. 点击添加资产按钮 +，选择 Material

将 网格渲染器 的 材质 属性替换为刚刚创建的 材质。

1. 创建动画片段 Copy Chapter

添加好组件后， 我们需要创建一个 动画片段（关于动画片段的介绍，请参考 动画片段 文档）创建 动画片段 有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Animation Clip

2. 点击添加资产按钮 +，选择 Animation Clip

2. 打开动画片段编辑器 Copy Chapter

1. 双击刚刚创建的 动画片段 资产

2. 选择 实体，根据提示，我们需要在 层级面板 选择一个 实体 作为编辑动画的目标。

选择编辑器默认创建的 实体（你也可以点击层级面板的 + 按钮创建一个新的）

3. 点击动画片段编辑器的 Create 按钮，编辑器会为你做好一些准备工作，本示例你可以先忽略对这些概念的理解。

创建完成之后，你会打开动画片段编辑器，如图所示：

3. 编辑动画片段 Copy Chapter

1. 开启 动画片段 编辑器的录制模式

2. 将时间线调到 0:00， 然后将 网格渲染器 组件的 材质 的颜色属性设置为红色，在录制模式下，编辑器会自动添加对应的属性及关键帧。

3. 分别在 0:20，0:40 处，将 网格渲染器 组件的 材质 的颜色属性设置为绿色， 蓝色。在 1:00 处，再设置回红色。
   首尾的关键帧相同，动画就可以自然的循环播放了，点击播放按钮，可以预览这个 动画片段。

这样我们的材质颜色变化 动画片段 就制作完成了。关于动画编辑器的更多操作，请参考 动画片段 文档。

关于如何使用这个 动画片段 到你的项目中，可以参考文章顶部列出的两篇文档。

File: docs/zh/animation/examples/playAnimation.mdx Copy Chapter

order: 0 title: 播放模型中的动画 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中播放模型自带的动画。通过简单的步骤，你将学习如何加载一个带有动画的 3D 模型，并控制其动画的播放。这个指南适合初学者了解 Galacean 编辑器的动画系统，也为更复杂的动画应用奠定基础。

0. 准备工作 Copy Chapter

在开始之前，我们需要有一个带动画的模型。如果你没有模型，可以在 mixamo 上下载一个。

下载模型 Copy Section

1. 在 mixamo 中选择一个模型

2. 在 动画Tab 中选择一个动画

3. 下载模型

导入模型 Copy Section

有三种方式导入模型：

1. 将模型文件拖入编辑器的 资产面板 中

2. 右键点击 资产面板 中的空白处，选择 Upload -> Model

3. 点击上传按钮，选择 Model

1. 查看模型 Copy Chapter

点击模型资产上的展开按钮

可以看到模型中包含了一个 动画片段（详细介绍）资产(如果模型中包含多个动画，这里会有多个 动画片段 资产)

以及一个 动画控制器（详细介绍）资产

2. 创建动画控制资产 Copy Chapter

想要控制动画的播放，需要编辑 动画控制器 的内容，而模型中的 动画控制器 是只读的，所以需要我们自己创建一个 动画控制器 。

创建 动画控制器 有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Animation Controller

2. 点击添加资产按钮 +，选择 Animation Controller

3. 编辑动画控制器 Copy Chapter

1. 双击 动画控制器 资产，进入动画控制器编辑器（编辑器的各个功能介绍请参考 动画控制器编辑器 文档）

2. 点击添加动画状态按钮，添加一个动画状态

3. 点击动画状态（动画状态的属性介绍请参考 动画状态机 文档的动画状态部分），绑定动画片段。

4. 从 entry 连接到此 动画状态 并点击连线，并将 Duration 改为0（动画过渡的详细介绍请参考 动画状态机 文档），这样在这个动画控制器被应用时，就会立即自动播放此动画状态。

4. 使用动画控制器并预览 Copy Chapter

1. 将模型拖入到场景中

2. 找到动画控制组件 （详细介绍 , 组件一般在模型实例的根 实体 上，也就是编辑器的模型 实体 下的第一个子 实体 上。

3. 在动画控制器属性上替换为刚才创建的动画控制器

4. 点击播放按钮，就可以看到模型开始播放动画了

File: docs/zh/animation/examples/reuseAnimation.mdx Copy Chapter

order: 1 title: 动画复用 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中播放其他模型的动画。通过简单的步骤，你将学习如何让一个模型复用另一个模型的动画。这个指南适合初学者了解 Galacean 编辑器的动画系统，也为更复杂的动画应用奠定基础。
如果你是第一次使用动画编辑器，建议先阅读这篇文档：

播放模型中的动画

0. 准备工作 Copy Chapter

在开始之前，我们需要有一个没有动画的模型，和一个只有动画的模型（角色模型必须包含与动画模型同名的实体）。如果你没有模型，可以在 mixamo 上下载一个。

下载模型 Copy Section

1. 在 mixamo 中选择一个模型

直接点击下载

2. 在 动画Tab 中选择一个动画

选择 Without Skin 选项，然后点击下载

导入模型 Copy Section

如果你不知道如何导入模型，请参考：导入模型

将角色模型和动画模型导入到编辑器中。

1. 创建动画控制资产 Copy Chapter

想要播放其他模型的动画，需要编辑 动画控制器 的内容，而模型中的 动画控制器 是只读的，所以需要我们自己创建一个 动画控制器 。
如果你不知道如何创建 动画控制器 ，请参考：创建动画控制器

2. 编辑动画控制器 Copy Chapter

1. 双击 动画控制器 资产，进入动画控制器编辑器（编辑器的各个功能介绍请参考 动画控制器编辑器 文档）

2. 点击 添加动画状态 按钮，添加一个 动画状态

3. 点击 动画状态（动画状态的属性介绍请参考 动画状态 文档），绑定动画模型中的 动画片段 。

4. 从 entry 连接到此 动画状态 并点击连线将 Duration 改为 0（动画状态及动画过渡的详细介绍请参考 动画状态机 文档），这样在这个动画控制器被应用时，就会立即自动播放此 动画状态 。

3. 使用动画控制器并预览 Copy Chapter

1. 将模型拖入到场景中

2. 与直接播放模型中的动画不同，我们需要找到动画模型的 动画控制组件（详细介绍）位置, 组件一般在模型实例的根实体上，也就是编辑器的模型实体下的第一个子实体上，因此我们需要将包含动画的模型也拖到节点树中

我们发现 动画控制组件 在动画模型的 mixamorig:Hips 实体上，因此我们需要在角色模型的mixamorig:Hips实体上添加 动画控制组件

3. 在动画控制器属性上替换为刚才创建的动画控制器

4. 点击播放按钮，就可以看到模型开始播放动画了

File: docs/zh/animation/examples/sprite-sheet.mdx Copy Chapter

order: 6 title: 2D 帧动画 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中实现 2D 帧动画。通过简单的步骤，你将学习如何制作一个帧动画动画片段。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

0. 准备工作 Copy Chapter

在开始之前，我们需要有制作帧动画所需的序列帧图片，雪碧图和单帧图片都可以。本示例使用雪碧图，如果你没有，可以在这里下载 雪碧图。

1. 导入纹理 Copy Chapter

有三种方式导入 纹理 ：

1. 将图片拖入编辑器的 资产面板 中

2. 右键点击 资产面板 中的空白处，选择 Upload -> Texture2D

3. 点击上传按钮，选择 Texture2D

2. 创建精灵 Copy Chapter

关于 精灵 的详细介绍请参考 精灵 文档

创建 精灵 有三种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Sprite

2. 点击添加资产按钮 +，选择 Sprite

3. 如果你是单帧图片，可以右键点击 资产面板 中的空白处，选择 Upload -> Sprite，然后选择你的单帧图片。
   这种方式，在导入 纹理 的同时会自动创建一个 精灵 资产并绑定此图片作为其 纹理 。

创建三个 精灵 资产，分别对应雪碧图中的三帧。

3. 为精灵绑定纹理 Copy Chapter

如果你使用雪碧图的话，需要根据帧数，配置合适的 Region。如果你使用单帧图片的话，直接按第一步绑定即可。

1. 点击 精灵 资产，点击 纹理 属性，选择对应的纹理。

2. 根据帧数，配置合适的 Region，本示例共有三帧，并且只有一排， 所以每帧的 Region 的 W 为 1/3 (对应的纹理 width 也改为原来的1/3) H 为 1。

3. 修改另外两个 精灵 的 Region，与第一个 精灵 的 Region 不同的是，它们的 Region 的 X 值不同，分别为 0, 1/3, 2/3。

Sprite1 :

Sprite2 :

全部绑定好纹理后，精灵 资产会展示对应的图片，如图所示：

4. 创建动画片段 Copy Chapter

准备好 精灵 后， 我们需要创建一个 动画片段（关于动画片段的介绍，请参考 动画片段 文档）创建 动画片段 有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Animation Clip

2. 点击添加资产按钮 +，选择 Animation Clip

5. 打开动画片段编辑器 Copy Chapter

1. 双击刚刚创建的 动画片段 资产

2. 选择 实体，根据提示，我们需要在 层级面板 选择一个 实体 作为编辑动画的目标。

选择编辑器默认创建的 实体（你也可以点击层级面板的 + 按钮创建一个新的）

3. 点击动画片段编辑器的 Create 按钮，编辑器会为你做好一些准备工作，本示例你可以先忽略对这些概念的理解。

创建完成之后，你会打开动画片段编辑器，如图所示：

6. 设置实体并切换到2D视图 Copy Chapter

1. 删掉默认的 网格渲染器 组件（如果你是自己创建的, 忽略）。为选择的 实体 添加一个 精灵渲染器 组件，

2. 为 精灵渲染器 组件的 精灵 属性绑定一个我们刚刚创建的 精灵 资产， 作为默认的 精灵。

3. 将 实体 默认的旋转重制，并切换到 2D 视图

7. 编辑动画片段 Copy Chapter

1. 开启 动画片段 编辑器的录制模式

2. 将时间线调到 0:00， 然后将 精灵渲染器 组件的 精灵 属性切换到第一帧的 精灵 资产。因为我们的第一帧与 精灵渲染器 组件的默认 精灵 相同，所以仍然选择此 精灵。
   在录制模式下，编辑器会自动添加对应的属性及关键帧。

3. 分别在 0:20, 0:40 处，将 精灵渲染器 组件的 精灵 属性切换到第二帧，第三帧的 精灵 资产。在 1:00 处，再切换回第一帧的 精灵 资产。
   首尾的关键帧相同，在循环播放时动画就不会出现抖动了，点击播放按钮，可以预览这个 动画片段。

这样我们的帧动画 动画片段 就制作完成了。关于动画编辑器的更多操作，请参考 动画片段 文档。

关于如何应用这个 动画片段 到你的项目中，可以参考文章顶部列出的两篇文档。

File: docs/zh/animation/examples/text-animation.mdx Copy Chapter

order: 5 title: 文字动画 type: 动画 group: 指南和示例 label: Animation/Examples Copy Chapter

本示例展示了如何在 Galacean 编辑器中实现文字的动画。通过简单的步骤，你将学习如何制作一个文字动画的动画片段。
如果你是第一次使用动画编辑器，建议先阅读前面几篇文档：

1.播放模型中的动画

2.动画复用

0. 准备工作 Copy Chapter

在开始之前，我们需要在 实体 上添加一个 文本渲染器 组件。

1. 创建动画片段 Copy Chapter

添加好组件后， 我们需要创建一个 动画片段（关于动画片段的介绍，请参考 动画片段 文档）创建 动画片段 有两种方式：

1. 右键点击 资产面板 中的空白处，选择 Create -> Animation Clip

2. 点击添加资产按钮 +，选择 Animation Clip

2. 打开动画片段编辑器 Copy Chapter

1. 双击刚刚创建的 动画片段 资产

2. 选择 实体，根据提示，我们需要在 层级面板 选择一个 实体 作为编辑动画的目标。

选择编辑器默认创建的 实体（你也可以点击层级面板的 + 按钮创建一个新的）

3. 点击动画片段编辑器的 Create 按钮，编辑器会为你做好一些准备工作，本示例你可以先忽略对这些概念的理解。

创建完成之后，你会打开动画片段编辑器，如图所示：

3. 设置测试文字并切换到2D视图 Copy Chapter

1. 在 实体 上的 文本渲染器 组件的 文本 属性中输入 Hello World，并设置 字体大小 为 200。你也可以按需设置其他属性，关于文字的更多信息，请参考 文本渲染器 文档。

2. 切换到 2D 视图

4. 编辑动画片段 Copy Chapter

1. 开启 动画片段 编辑器的录制模式

2. 将时间线调到 0:00， 然后将 文本渲染器 组件的 字体大小 属性设置为0，在录制模式下，编辑器会自动添加对应的属性及关键帧。

3. 分别在 0:30，1:00 处，将 文本渲染器 组件的 字体大小 属性设置为100， 200。点击播放按钮，可以预览这个 动画片段。

这样我们的文字放大 动画片段 就制作完成了，你也可以尝试其他 文本渲染器 的属性，比如 颜色，字体 等。关于动画编辑器的更多操作，请参考 动画片段 文档。

关于如何使用这个 动画片段 到你的项目中，可以参考文章顶部列出的两篇文档。

File: docs/zh/animation/animator.mdx Copy Chapter

order: 3 title: 动画控制组件 type: 动画 label: Animation Copy Chapter

简介 Copy Chapter

动画控制组件（API）的作用是读取 动画控制器（详细介绍）的数据，并播放其内容。

参数说明 Copy Section

编辑器使用 Copy Chapter

当把模型拖入到场景中，模型以初始姿态展示，并不会播放任何动画，这时需要在模型实体上找到 动画控制组件 并为它绑定一个 动画控制器 资产。

1. 找到或者创建 动画控制组件

import { Script, Animator, Keys } from '@galacean/engine';

export default class extends Script {
  onStart() {
    const animator = this.entity.getComponent(Animator);
    animator.play("State Name");
  }
}

import { Script, Animator, Keys } from '@galacean/engine';

export default class extends Script {
  onStart() {
    const animator = this.entity.getComponent(Animator);
    const layerIndex = 0;
    const normalizedTimeOffset = 0.5; // 归一化的时间
    animator.play("State Name", layerIndex, normalizedTimeOffset);
  }
}

animator.speed = 2.0；

// 停止
animator.enabled = false;
// 重新播放
animator.enabled = true;

// 暂停
animator.speed = 0;
// 恢复
animator.speed = 1;

const state = animator.findAnimatorState("xxx");
state.speed = 0;

animator.crossFade("OtherStateName", 0.3);

const currentState = animator.getCurrentAnimatorState(0);
// 播放一次
currentState.wrapMode = WrapMode.Once;
// 循环播放
currentState.wrapMode = WrapMode.Loop;

const state = animator.findAnimatorState("xxx");
// 播放一次
state.wrapMode = WrapMode.Once;
// 循环播放
state.wrapMode = WrapMode.Loop;

$ yarn
$ yarn dev

open http://local.alipay.net

$ yarn playground

$ yarn build

// leave a blank line here

$ yarn link ../engine/packages/*

$ yarn link ..\engine\packages\galacean

engine.resourceManager
  .load<GLTFResource>(
    "https://gw.alipayobjects.com/os/bmw-prod/5e3c1e4e-496e-45f8-8e05-f89f2bd5e4a4.glb"
  )
  .then((asset) => {
    const { defaultSceneRoot } = asset;
    rootEntity.addChild(defaultSceneRoot);
    const animator = defaultSceneRoot.getComponent(Animator);
    animator.play("run");
  });

animator.speed = 2.0；

// 暂停
animator.enabled = false;
// 恢复
animator.enabled = true;

const state = animator.findAnimatorState("xxx");
state.speed = 0;

animator.play("run");

const layerIndex = 0;
const normalizedTimeOffset = 0.5; // 归一化的时间
animator.play("run", layerIndex, normalizedTimeOffset);

const currentState = animator.getCurrentAnimatorState(0);
// 播放一次
currentState.wrapMode = WrapMode.Once;
// 循环播放
currentState.wrapMode = WrapMode.Loop;

const state = animator.findAnimatorState("xxx");
// 播放一次
state.wrapMode = WrapMode.Once;
// 循环播放
state.wrapMode = WrapMode.Loop;

const layers = animator.animatorController.layers;
layers[0].stateMachine.defaultState = animator.findAnimatorState("walk");
layers[1].stateMachine.defaultState = animator.findAnimatorState("sad_pose");
layers[1].blendingMode = AnimatorLayerBlendingMode.Additive;

const walkThenRunState = animatorStateMachine.addState("walkThenRun");
walkThenRunState.clip = walkClip;
const runState = animatorStateMachine.addState("run");
runState.clip = runClip;
const transition = new AnimatorStateTransition();
transition.duration = 1;
transition.offset = 0;
transition.exitTime = 0.5;
transition.destinationState = runState;
walkThenRunState.addTransition(transition);
animator.play("walkThenRun");

animator.animatorController = new AnimatorController()；

const animator = model1.getComponent(Animator);
animator.animatorController = model2.getComponent(Animator).animatorController;

class theScript extends StateMachineScript {
  // onStateEnter is called when a transition starts and the state machine starts to evaluate this state
  onStateEnter(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log("onStateEnter", animator, stateInfo, layerIndex);
  }

  // onStateUpdate is called on each Update frame between onStateEnter and onStateExit callbacks
  onStateUpdate(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log("onStateUpdate", animator, stateInfo, layerIndex);
  }

  // onStateExit is called when a transition ends and the state machine finishes evaluating this state
  onStateExit(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log("onStateExit", animator, stateInfo, layerIndex);
  }
}

animatorState.addStateMachineScript(theScript);

state.addStateMachineScript(
  class extends StateMachineScript {
    onStateEnter(
      animator: Animator,
      animatorState: AnimatorState,
      layerIndex: number
    ): void {
      console.log("onStateEnter: ", animatorState);
    }
  }
);

//custom rotate clip
const rotateClip = new AnimationClip("rotate");
const rotateState =
  animator.animatorController.layers[0].stateMachine.addState("rotate");
rotateState.clip = rotateClip;

const rotateCurve = new AnimationVector3Curve();
const key1 = new Keyframe<Vector3>();
key1.time = 0;
key1.value = new Vector3(0, 0, 0);
const key2 = new Keyframe<Vector3>();
key2.time = 10;
key2.value = new Vector3(0, 360, 0);
rotateCurve.addKey(key1);
rotateCurve.addKey(key2);
rotateClip.addCurveBinding("", Transform, "rotation", rotateCurve);

//custom color clip
const colorClip = new AnimationClip("color");
const colorState =
  animator.animatorController.layers[0].stateMachine.addState("color");
colorState.clip = colorClip;

const colorCurve = new AnimationFloatCurve();
const key1 = new Keyframe<number>();
key1.time = 0;
key1.value = 0;
const key2 = new Keyframe<number>();
key2.time = 10;
key2.value = 1;
colorCurve.addKey(key1);
colorCurve.addKey(key2);
colorClip.addCurveBinding("/light", DirectLight, "color.r", colorCurve);

const event = new AnimationEvent();
event.functionName = "test";
event.time = 0.5;
clip.addEvent(event);

flowchart LR
 添加动画片段 --> 创建动画控制器并导入动画片段 --> 添加动画控制组件播放动画

const walkState = animatorStateMachine.addState('walk');
walkState.clip = walkClip;
const runState = animatorStateMachine.addState('run');
runState.clip = runClip;
const transition = new AnimatorStateTransition();
transition.duration = 1;
transition.offset = 0;
transition.exitTime = 0.5;
transition.destinationState = runState;
walkState.addTransition(transition);
animator.play("walk");

const layers = animator.animatorController.layers;
layers[0].stateMachine.defaultState = animator.findAnimatorState('walk');
layers[1].stateMachine.defaultState = animator.findAnimatorState('sad_pose');
layers[1].blendingMode = AnimatorLayerBlendingMode.Additive;

const currentState = animator.getCurrentAnimatorState(0);
// 播放一次
currentState.wrapMode = WrapMode.Once;
// 循环播放
currentState.wrapMode = WrapMode.Loop;

const state = animator.findAnimatorState('xxx');
// 播放一次
state.wrapMode = WrapMode.Once;
// 循环播放
state.wrapMode = WrapMode.Loop;

class theScript extends StateMachineScript {
  // onStateEnter is called when a transition starts and the state machine starts to evaluate this state
  onStateEnter(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log('onStateEnter', animator, stateInfo, layerIndex);
  }

  // onStateUpdate is called on each Update frame between onStateEnter and onStateExit callbacks
  onStateUpdate(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log('onStateUpdate', animator, stateInfo, layerIndex);
  }

  // onStateExit is called when a transition ends and the state machine finishes evaluating this state
  onStateExit(animator: Animator, stateInfo: any, layerIndex: number) {
    console.log('onStateExit', animator, stateInfo, layerIndex);
  }
}

animatorState.addStateMachineScript(theScript)

state.addStateMachineScript(
  class extends StateMachineScript {
    onStateEnter(
      animator: Animator,
      animatorState: AnimatorState,
      layerIndex: number
    ): void {
      console.log("onStateEnter: ", animatorState);
    }
  }
);

flowchart TD
	%% Colors %%
		linkStyle default stroke-width:1px,stroke-dasharray:3
		classDef white fill:white,stroke:#000,stroke-width:1px,color:#000
		classDef yellow fill:#fffd75,stroke:#000,stroke-width:1px,color:#000
		classDef green fill:#93ff75,stroke:#000,stroke-width:1px,color:#000

    Animator:::green --> AnimatorController:::yellow
    Animator --> AnimatorControllerParameter:::white
    AnimatorController --> AnimatorControllerLayer
    AnimatorControllerLayer --> AnimatorStateMachine
    AnimatorControllerLayer --> BlendingMode:::white
    AnimatorStateMachine --> AnimatorState
    AnimatorStateMachine --> AnimatorTransition:::white
    AnimatorState --> AnimationClip
    AnimationClip:::yellow --> AnimationCurve
    AnimationClip --> AnimationEvent:::white
    AnimationCurve --> Keyframe
    AnimationCurve --> Interpolation:::white