chore: add engine version documentation

docs/en/animation/animator.mdx

@@ -0,0 +1,155 @@
+---
+order: 3
+title: Animation Control Component
+type: Animation
+label: Animation
+---
+
+## Introduction
+The Animation Control Component ([Animator](/en/apis/core/#Animator)) is responsible for reading data from the [Animation Controller](/en/docs/animation/animatorController/) ([AnimatorController](/en/apis/core/#AnimatorController)) and playing its content.
+
+### Parameter Description
+
+| Attribute          | Function Description            |
+| :----------------- | :----------------------------- |
+| animatorController | Bind `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](/en/apis/core/#Animator)) on the model entity and bind an [Animation Controller](/en/docs/animation/animatorController/) asset to it.
+
+1. Find or create an Animation Control Component ([Animator](/en/apis/core/#Animator))
+
+<Callout type="info">
+The Animation Control Component ([Animator](/en/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.
+
+If the model contains animations, a read-only [Animation Controller](/en/docs/animation/animatorController/) will be automatically bound for you.
+</Callout>
+
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*WkafRagPFo8AAAAAAAAAAAAADsJ_AQ/original)
+
+If there is no Animation Control Component ([Animator](/en/apis/core/#Animator)), you can create one as shown below
+
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*uOuPT5cFwx4AAAAAAAAAAAAADsJ_AQ/original)
+
+2. Create an [Animation Controller](/en/docs/animation/animatorController/) asset and bind it to the model
+
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*PxHwTrU58yAAAAAAAAAAAAAADsJ_AQ/original)
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Ds5TTosYiDYAAAAAAAAAAAAADsJ_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/)
+
+## 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
+
+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.
+
+```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");
+  });
+```
+
+#### Control Playback Speed
+
+You can control the animation playback speed through the [speed](/en/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
+
+You can stop and replay the animation by setting the [enabled](/en/apis/core/#Animator-enabled) property of the Animator.
+
+```typescript
+// 停止
+animator.enabled = false;
+// 重新播放
+animator.enabled = true;
+```
+
+#### Pause/Resume Playback
+You can pause and resume playback by setting the [speed](/en/apis/core/#Animator-speed) property of the Animator.
+
+```typescript
+// 暂停
+animator.speed = 0;
+// 恢复
+animator.speed = 1;
+```
+
+If you only want to pause a specific animation state, 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](/en/apis/core/#Animator-play) method to play a specific `AnimatorState`. For parameter details, see the [API documentation](/en/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
+
+You can use the [animator.crossfade](/en/apis/core/#Animator-crossfade) method to transition the animation to a specified `AnimatorState`. For parameter details, see the [API documentation](/en/apis/core/#Animator-crossFade).
+
+```typescript
+animator.crossFade("run", 0.3);
+```
+
+<Playground href="/embed/skeleton-animation-crossfade" />
+
+### Get the Currently Playing Animation State
+
+You can use the [getCurrentAnimatorState](/en/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](/en/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.
+
+```typescript
+const currentState = animator.getCurrentAnimatorState(0);
+// 播放一次
+currentState.wrapMode = WrapMode.Once;
+// 循环播放
+currentState.wrapMode = WrapMode.Loop;
+```
+
+### Get an Animation State
+
+You can use the [findAnimatorState](/en/apis/core/#Animator-findAnimatorState) method to get an AnimatorState by its specified name. For details, see the [API documentation](/en/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.
+
+```typescript
+const state = animator.findAnimatorState("xxx");
+// 播放一次
+state.wrapMode = WrapMode.Once;
+// 循环播放
+state.wrapMode = WrapMode.Loop;
+```
+
+### Animation Culling
+
+You can set the [cullingMode](/en/apis/core/#Animator-cullingMode) of the [Animator](/en/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.
+```

docs/en/animation/animatorController.mdx

@@ -0,0 +1,62 @@
+---
+order: 2
+title: Animation Controller
+type: Animation
+label: Animation
+---
+
+The Animation Controller ([AnimatorController](/en/apis/core/#AnimatorController)) helps you organize a set of animations for characters or other animated objects. It visualizes the animation playback logic of animated objects like a flowchart through the [Animation State Machine](/en/docs/animation/state-machine/) ([AnimatorStateMachine](/en/apis/core/#AnimatorStateMachine)) and automatically switches animation states ([AnimatorState](/en/apis/core/#AnimatorState)) and plays the referenced [Animation Clips](/en/docs/animation/clip) ([AnimationClip](/en/apis/core/#AnimationClip)) when conditions are met.
+
+## Editor Usage
+
+Through the Animation Controller editor, users can organize the playback logic of [Animation Clips](/en/docs/animation/clip).
+
+1. Prepare the Animation Clips ([Create Animation Clips](/en/docs/animation/clip)).
+
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Wl35T7U_zg8AAAAAAAAAAAAADsJ_AQ/original)
+
+2. To organize the playback of these Animation Clips, we need to create an Animation Controller ([AnimatorController](/en/apis/core/#AnimatorController)) asset.
+
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*PxHwTrU58yAAAAAAAAAAAAAADsJ_AQ/original)
+
+3. The newly created Animation Controller has no data. We need to edit it, double-click the asset, and add an Animation State ([AnimatorState](/en/apis/core/#AnimatorState)) to it.
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*V0n1TJMquGYAAAAAAAAAAAAADsJ_AQ/original)
+
+4. Click AnimatorState to bind an [Animation Clip](/en/docs/animation/clip) ([AnimationClip](/en/apis/core/#AnimationClip)) to it.
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*xfPTRJg-hOMAAAAAAAAAAAAADsJ_AQ/original)
+
+5. Bind the Animation Controller ([AnimatorController](/en/apis/core/#AnimatorController)) asset to the [Animation Control Component](/en/docs/animation/animator).
+![alt text](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*Ds5TTosYiDYAAAAAAAAAAAAADsJ_AQ/original)
+
+6. At this point, you can play the `Idle` animation in the exported project through `animator.play("New State")`.
+
+<Callout type="info">
+For further usage of the Animation Controller editor, please refer to the [Animation State Machine](/en/docs/animation/state-machine/) documentation.
+</Callout>
+
+## Script Usage
+
+<Callout type="positive">
+  Before using scripts, it is best to read the [Animation System Composition](/en/docs/animation/system) documentation to help you better understand the operation logic of the animation system.
+</Callout>
+
+### Binding the Animation Controller
+
+You can bind the Animation Controller to the [Animator](/en/apis/core/#Animator) through the [animator.animatorController](/en/apis/core/#Animator-animatorController) property. If the loaded glTF model has animation data, it will automatically bind a default AnimatorController to each glTF instance.
+
+```typescript
+animator.animatorController = new AnimatorController(engine);
+animator.play("New State");
+```
+
+#### Reusing Animation Data
+
+The [animatorController](/en/apis/core/#AnimatorController) of the Animator is a data storage class and does not contain runtime data. Based on this design, as long as the hierarchical structure and naming of the skeletal nodes of the model bound to the Animator component are the same, we can reuse the animation data of this model.
+
+```typescript
+const animator = model1.getComponent(Animator);
+// 获取动画模型的动画控制器
+animator.animatorController = animationGLTF.getComponent(Animator).animatorController;
+// 播放 animationGLTF 的动画
+animator.play("anim from animationGLTF");
+```