Skip to content

Commit

Permalink
Doc: translate newest animation doc to en (#2553)
Browse files Browse the repository at this point in the history 
* feat: translate newest animation doc to en
  • Loading branch information
@luzhuang
luzhuang authored Feb 19, 2025
1 parent efbc8fd commit 9a28f37
Show file tree
Hide file tree
Showing 21 changed files with 1,088 additions and 279 deletions.
5 changes: 5 additions & 0 deletions docs/en/animation/_meta.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"examples": {
"title": "Guides and Examples"
}
}
149 changes: 75 additions & 74 deletions docs/en/animation/animator.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,155 +1,156 @@
---
order: 3
title: Animation Control Component
title: Animator Component
type: Animation
label: Animation
---

## Introduction
The Animation Control Component ([Animator](/apis/core/#Animator)) is responsible for reading data from the [Animation Controller](/en/docs/animation/animatorController/) ([AnimatorController](/apis/core/#AnimatorController)) and playing its content.
The `Animator` Component ([API](/apis/core/#Animator)) is responsible for reading the data from the `AnimatorController` ([detailed introduction](/docs/animation/animatorController/)) and playing its content.

### Parameter Description

| Attribute | Function Description |
| Property | Description |
| :----------------- | :----------------------------- |
| animatorController | Bind `AnimatorController` asset |
| animatorController | Bind the `AnimatorController` asset |

## Editor Usage

When you drag a model into the scene, the model is displayed in its initial pose and does not play any animation. At this point, you need to find the Animation Control Component ([Animator](/apis/core/#Animator)) on the model entity and bind an [Animation Controller](/en/docs/animation/animatorController/) asset to it.
When you drag a model into the scene, the model is displayed in its initial pose and does not play any animation. At this time, you need to find the `Animator` Component on the model entity and bind an `AnimatorController` asset to it.

1. Find or create an Animation Control Component ([Animator](/apis/core/#Animator))
1. Find or create an `Animator` Component

<Callout type="info">
The Animation Control Component ([Animator](/apis/core/#Animator)) of the model is on the root entity of the glTF instance, which is the first child entity under the model entity in the editor.
The `Animator` Component of the model is on the root entity of the glTF instance, which is the first child `entity` under the model entity in the editor.

If the model contains animations, a read-only [Animation Controller](/en/docs/animation/animatorController/) will be automatically bound for you.
If the model has animations, a read-only `AnimatorController` will be automatically bound for you.
</Callout>

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WkafRagPFo8AAAAAAAAAAAAADsJ_AQ/original" />

If there is no Animation Control Component ([Animator](/apis/core/#Animator)), you can create one as shown below
If there is no `Animator` Component, you can create it as shown below

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*uOuPT5cFwx4AAAAAAAAAAAAADsJ_AQ/original" />
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WFRXQIjZa0MAAAAAAAAAAAAADsJ_AQ/original" />

2. Create an [Animation Controller](/en/docs/animation/animatorController/) asset and bind it to the model
2. Create an `AnimatorController` asset and bind it to the model. There are two ways to create an `AnimatorController`:
1. Right-click on the blank space in the **[Asset Panel](/docs/assets/interface)** and select `Create` -> `Animation Controller`

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*PxHwTrU58yAAAAAAAAAAAAAADsJ_AQ/original" />
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Ds5TTosYiDYAAAAAAAAAAAAADsJ_AQ/original" />
<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*61Q7S62IZxQAAAAAAAAAAAAADsJ_AQ/original" />

3. After editing the Animation Controller ([see details](/en/docs/animation/animatorController/)), you can play the animations according to the logic of the [Animation Controller](/en/docs/animation/animatorController/)
2. Click the add asset button `+` and select `Animation Controller`

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*QqpxS6I9D90AAAAAAAAAAAAADsJ_AQ/original" />

3. Replace the `AnimatorController` property of the `Animator` Component with the `AnimatorController` just created

<Image src="https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Y0pBQae4UWQAAAAAAAAAAAAADsJ_AQ/original" />

4. After editing the `AnimatorController` (you can refer to the [AnimatorController](/docs/animation/animatorController) document), you can play the animations in it

## Script Usage
<Callout type="positive">
Before using scripts, it is best to read the [Animation System Composition](/en/docs/animation/system) document to help you better understand the operating logic of the animation system.
</Callout>

### Play Animation
Before using scripts, it is recommended to read the following documents:

- [Script](/docs/script/script)
- [Animation System Composition](/docs/animation/system)

After loading the GLTF model, the engine will automatically add an Animator component to the model and include the animation clips from the model. You can directly get the Animator component on the root entity of the model and play the specified animation.
### Play Specified Animation State

You can use the [animator.play](/apis/core/#Animator-play) method to play the specified `AnimatorState` . For parameter descriptions, see the [API documentation](/apis/core/#Animator-play).

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

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

If you need to start playing at a certain point in the animation, you can do so as follows

```typescript
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");
});
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; // Normalized time
animator.play("State Name", layerIndex, normalizedTimeOffset);
}
}
```

#### Control Playback Speed
### Control Playback Speed

You can control the animation playback speed through the [speed](/apis/core/#Animator-speed) property. The default value of `speed` is `1.0`. The larger the value, the faster the playback; the smaller the value, the slower the playback. When the value is negative, it plays in reverse.
You can control the playback speed of the animation through the [speed](/apis/core/#Animator-speed) property. The default value of `speed` is `1.0`, the larger the value, the faster the playback, the smaller the value, the slower the playback. When the value is negative, it plays in reverse.

```typescript
animator.speed = 2.0;
```

#### Stop/Replay
### Stop/Resume Playback

You can stop and replay the animation by setting the [enabled](/apis/core/#Animator-enabled) property of the Animator.
You can stop and resume the animation by setting [animator.enabled](/apis/core/#Animator-enabled).

```typescript
// 停止
// Stop
animator.enabled = false;
// 重新播放
// Resume
animator.enabled = true;
```

#### Pause/Resume Playback
You can pause and resume playback by setting the [speed](/apis/core/#Animator-speed) property of the Animator.
### Pause/Resume Playback
You can pause and resume playback by setting [animator.speed](/apis/core/#Animator-speed).

```typescript
// 暂停
// Pause
animator.speed = 0;
// 恢复
// Resume
animator.speed = 1;
```

If you only want to pause a specific animation state, you can do so by setting its speed to 0.
If you only want to pause a specific `AnimatorState` , you can do so by setting its speed to 0.

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

#### Play a Specific Animation State

You can use the [animator.play](/apis/core/#Animator-play) method to play a specific `AnimatorState`. For parameter details, see the [API documentation](/apis/core/#Animator-play).

```typescript
animator.play("run");
```

If you need to start playing at a specific moment in the animation, you can do so as follows:

```typescript
const layerIndex = 0;
const normalizedTimeOffset = 0.5; // Normalized time
animator.play("run", layerIndex, normalizedTimeOffset);
```

<Playground href="/embed/skeleton-animation-play" />

#### Transition to a Specific Animation State
### Transition to Specified Animation State

You can use the [animator.crossfade](/apis/core/#Animator-crossfade) method to transition the animation to a specified `AnimatorState`. For parameter details, see the [API documentation](/apis/core/#Animator-crossFade).
You can use the [animator.crossfade](/apis/core/#Animator-crossfade) method to transition to the specified `AnimatorState` . For parameter descriptions, see the [API documentation](/apis/core/#Animator-crossFade).

```typescript
animator.crossFade("run", 0.3);
animator.crossFade("OtherStateName", 0.3);
```

<Playground href="/embed/skeleton-animation-crossfade" />
### Get Current Playing Animation State

### Get the Currently Playing Animation State

You can use the [getCurrentAnimatorState](/apis/core/#Animator-getCurrentAnimatorState) method to get the currently playing AnimatorState. The parameter is the index of the layer where the animation state is located, `layerIndex`. For details, see the [API documentation](/apis/core/#Animator-getCurrentAnimatorState). After obtaining it, you can set the properties of the animation state, such as changing the default loop playback to play once.
You can use the [getCurrentAnimatorState](/apis/core/#Animator-getCurrentAnimatorState) method to get the currently playing `AnimatorState` . The parameter is the index `layerIndex` of the `AnimatorControllerLayer` where the `AnimatorState` is located. For details, see the [API documentation](/apis/core/#Animator-getCurrentAnimatorState). After obtaining it, you can set the properties of the `AnimatorState` , such as changing the default loop playback to play once.

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

### Get an Animation State
### Get Animation State

You can use the [findAnimatorState](/apis/core/#Animator-findAnimatorState) method to get an AnimatorState by its specified name. For details, see the [API documentation](/apis/core/#Animator-getCurrentAnimatorState). After obtaining it, you can set the properties of the animation state, such as changing the default loop playback to play once.
You can use the [findAnimatorState](/apis/core/#Animator-findAnimatorState) method to get the specified `AnimatorState` . After obtaining it, you can set the properties of the `AnimatorState` , such as changing the default loop playback to play once.

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

### Animation Culling

You can set the [cullingMode](/apis/core/#Animator-cullingMode) of the [Animator](/apis/core/#Animator) to determine whether the animation should be calculated when the entity bound to the Animator is not visible. When the animation is culled, it will not be calculated or applied to the entity, but the animation state will still update over time, ensuring it behaves correctly when it becomes visible again.
```
You can set whether the animation is calculated when the `entity` is not visible by setting the [cullingMode](/apis/core/#Animator-cullingMode) of the `Animator` Component. When the animation is culled, the animation will not be calculated and applied to the `entity`, but the state of the animation will still be updated over time, so that it is correctly displayed when it becomes visible again.
Loading

0 comments on commit 9a28f37

Please # to comment.